Why SST

SST is for people who want to render files in the browser without building a framework around it.

Drop in one tag, point it at any file, and it renders with smart defaults:

• smart file detection — auto-detects 60+ file types from the URL and applies syntax highlighting
• display modes — render as default, book, A4, or raw (unstyled)
• sanitized by default — DOMPurify keeps output safe
• syntax highlighting — highlight.js for code, config, and data files
• 3 tag names — <simple-spawn>, <sst-spawn>, <md-spawn> all work
• inline fallback — if src fails, inline content is the backup
• lazy loading & shadow DOM — optional, built in

Preview

Quick Start

Option 1: CDN (no install)

<simple-spawn src="./README.md"></simple-spawn>
<script type="module" src="https://unpkg.com/sst-spawn/dist/index.js"></script>

Option 2: npm

npm install sst-spawn

import "sst-spawn";

<simple-spawn src="/docs/guide.md"></simple-spawn>

After the import, all three tag names (<simple-spawn>, <sst-spawn>, <md-spawn>) are registered automatically.

Smart File Detection

SST detects the file type from the src URL and renders accordingly:

| File Type | What SST Does | |-----------|---------------| | .md | Renders as Markdown (GFM) | | .js, .ts, .py, .go, .rs, .java, .rb, .c, .cpp, .swift, .kt, .php, .lua, .r | Syntax-highlighted code block | | .json, .yaml, .toml, .xml, .ini | Syntax-highlighted data | | .sql, .sh, .css, .graphql, .diff | Syntax-highlighted code | | .html | Rendered as HTML (sanitized) | | .svg | Rendered inline (sanitized) | | .csv, .log, .txt, .env | Displayed as text | | Dockerfile, Makefile | Syntax-highlighted |

Override auto-detection with the type attribute:

<!-- Force a .txt file to highlight as JSON -->
<simple-spawn src="./data.txt" type="json"></simple-spawn>

<!-- Force any file to render as markdown -->
<simple-spawn src="./notes.txt" type="markdown"></simple-spawn>

Display Modes

Control how content is presented with the mode attribute:

Default (no attribute)

<simple-spawn src="./guide.md"></simple-spawn>

Clean GitHub-flavored styling. This is what you get out of the box.

Book Mode

<simple-spawn src="./story.md" mode="book"></simple-spawn>

Serif fonts, justified text, reading-optimized spacing, centered layout — like a printed book.

A4 Mode

<simple-spawn src="./report.md" mode="a4"></simple-spawn>

A4 page dimensions (210mm x 297mm), print-ready margins, <hr> elements become page breaks.

Raw Mode

<simple-spawn src="./data.json" mode="raw"></simple-spawn>

Zero styling. No theme CSS injected. Raw rendered output.

All Attributes

| Attribute | Values | Effect | |-----------|--------|--------| | src | URL | File to fetch and render | | type | language name | Override auto-detection (json, python, markdown, html, svg, plaintext) | | mode | book / a4 / raw | Display mode (default: styled) | | loading | lazy | Defer render until element enters viewport | | shadow | (boolean) | Render inside shadow DOM for style isolation | | unsafe | (boolean) | Skip sanitization (use only with trusted content) |

Tag Names

All three work identically — pick whichever fits your project:

<!-- Primary -->
<simple-spawn src="./file.md"></simple-spawn>

<!-- Short alias -->
<sst-spawn src="./file.md"></sst-spawn>

<!-- Backward compatible with md-spawn v1 -->
<md-spawn src="./file.md"></md-spawn>

Usage Patterns

Render a Markdown file

<simple-spawn src="/content/guide.md"></simple-spawn>

Display a JSON API response

<simple-spawn src="/api/config.json"></simple-spawn>

Show source code with highlighting

<simple-spawn src="./src/index.ts"></simple-spawn>

Write Markdown inline

<simple-spawn>
# Hello from SST

This content is **inline Markdown** with zero ceremony.
</simple-spawn>

Combine features

<simple-spawn src="./chapter-1.md" mode="book" loading="lazy" shadow></simple-spawn>

Built For

• changelogs and release notes
• embedded documentation
• code showcases and tutorials
• config file viewers
• markdown-driven landing pages
• browser-side file previews
• lightweight content systems

Migrating from md-spawn v1

SST v2 is fully backward compatible. Existing <md-spawn> tags continue to work:

<!-- This still works exactly as before -->
<md-spawn src="./README.md"></md-spawn>
<script type="module" src="https://unpkg.com/sst-spawn/dist/index.js"></script>

What's new:

• <simple-spawn> and <sst-spawn> as additional tag names
• Smart file detection (code files now get syntax highlighting)
• mode attribute for display modes
• type attribute for manual content type override

Creator

CI / CD

Three GitHub Actions workflows automate the full release cycle:

| Workflow | Trigger | What it does | |----------|---------|--------------| | CI | Push / PR to main | Install, build, and test on Node 18, 20, 22 | | Version Bump & Release | Manual (Actions tab) | Bump package.json version, commit, tag, push, and create a GitHub Release | | Publish to npm | GitHub Release created | Run tests, build, and npm publish with provenance |

Release flow

Actions tab -> "Version Bump & Release" -> pick patch/minor/major
  -> package.json 2.0.0 -> 2.0.1
  -> commit + tag + push to main
  -> GitHub Release v2.0.1 created automatically
  -> Publish workflow fires -> npm gets v2.0.1

Setup (one-time)

1. Generate an Automation token at npmjs.com/settings/tokens.
2. In your repo go to Settings > Secrets and variables > Actions.
3. Add a secret named NPM_TOKEN with the token value.

Local Demo

npm run build
npx serve . -l 4173

Open http://127.0.0.1:4173/test-formats.html to see all 60+ file types, display modes, and tag names in action.

Contributing

Contributions are welcome! Please read the Contributing Guide before opening a PR.

This project follows the Contributor Covenant Code of Conduct.

Security

To report a vulnerability, see SECURITY.md. Please do not open a public issue for security reports.

Changelog

See CHANGELOG.md for a full version history.

License

MIT © KingHippo