sigma-html-export

Turn a folder of Markdown files into a linked static HTML dashboard. Zero build step. Works offline. Incremental.

---

What it does

You have a folder full of Markdown files — a spec bundle, a pile of PRDs, a design-doc dump from a planning workflow. You want to show them to someone without making them clone the repo or open GitHub 12 times.

sigma-html-export reads the folder recursively and produces:

1. A sibling .html next to every .md (self-contained, CDN-rendered, themed)
2. A master index.html with a sidebar grouping docs by folder, word counts, and offline-friendly navigation

No dev server. No npm install in your doc folder. No config required. One command.

Install

Zero install — run with npx:

cd path/to/your/markdown/folder
npx sigma-html-export

Or install globally:

npm install -g sigma-html-export
sigma-html-export

Or add as a dev dependency:

npm install --save-dev sigma-html-export

Then in your package.json:

{
  "scripts": {
    "docs": "sigma-html-export --root docs"
  }
}

Usage

From inside a folder containing .md files:

npx sigma-html-export                       # incremental build
npx sigma-html-export --force               # rebuild everything
npx sigma-html-export --root ./docs         # scan a subfolder
npx sigma-html-export --title "Project X"   # custom brand
npx sigma-html-export --theme midnight      # dark mode
npx sigma-html-export --themes              # list themes

Open index.html in your browser. Done.

All flags

Flag	Default	Description
--root <dir>	.	Folder to scan for .md files
--title <string>	folder name	Brand / title shown in header
--subtitle <string>	—	Optional subtitle under the brand
--theme <name>	cream-ember	Built-in theme
--layout <name>	classic	classic or narrative (see below)
--force, -f	false	Rebuild every HTML even if MD is older
--themes	—	List built-in themes
--lang <code>	en	HTML lang attribute
--version, -v	—	Print version
--help, -h	—	Show help

Config file

Drop a sigma-html-export.config.json in your doc root to lock the settings in:

{
  "title": "Project X",
  "subtitle": "Design Docs",
  "theme": "anthropic",
  "lang": "de",
  "meta": {
    "Branch": "main",
    "Updated": "2026-04-21"
  },
  "ignore": ["drafts", "archive"]
}

CLI flags override config values.

Layouts

Two layouts ship in the box — pick via --layout or set "layout" in the config.

classic (default)

Each .md renders as a single clean article page. A master index.html at the root lists every document in a grouped sidebar. Good for reference docs, spec dumps, documentation bundles.

narrative

Each .md renders as a step-by-step learning experience:

• The sidebar becomes a table of contents built from every ## Heading in the document, numbered 01, 02, 03…
• As you scroll, the TOC auto-highlights the current step and marks earlier steps with ✓
• Each step fades in as it enters the viewport (scroll-triggered reveal)
• A progress bar shows how far through the document you are
• Respects prefers-reduced-motion — no animations if the user opted out

Perfect for:

• Product walkthroughs (pricing → architecture → implementation)
• Tutorials with linear flow
• Design decisions explained in sequence
• Pitch / sales bundles you want people to read in order

npx sigma-html-export --layout narrative

Authoring: just write normal Markdown with ## Heading for each step. The tool handles splitting, numbering, and reveal logic at render-time in the browser — no frontmatter required, no framework, still self-contained.

Themes

Name	Look	Fonts
cream-ember	Warm editorial, terracotta accent	Cormorant Garamond + Inter + JetBrains Mono
anthropic	Paper + terracotta, Claude-ish	Source Serif 4 + Space Grotesk + Geist Mono
minimal	White + system fonts, zero web-font load	system
midnight	Dark mode, terminal-inspired	Inter + JetBrains Mono

Custom themes: fork lib/themes.mjs, add your block, done. See demo/architecture/theming.md after running the demo.

How it works

┌──────────────────┐   ┌──────────────────┐   ┌──────────────────┐
│  walk the tree   │ → │  render each MD  │ → │  write index.html│
│  (recursive)     │   │  to sibling .html│   │  (sidebar nav)   │
└──────────────────┘   └──────────────────┘   └──────────────────┘

• Recursive walk, skips node_modules, .git, build, dist, .next, .cache, .planning, dotfolders
• Each .md → .html in the same folder, only if MD is newer (unless --force)
• Every HTML inlines the Markdown source as a <script type="text/plain"> block and renders it with marked.js loaded from jsDelivr — browser-cached after first load → offline-stable
• Master index.html is rewritten each run (cheap), groups docs by top-level folder as sidebar sections

Try the demo

git clone https://github.com/b02thomas/sigma-html-export.git
cd sigma-html-export
npm run demo
open demo/index.html

Wiring into a spec workflow

This tool was extracted from a Sigma Protocol-style product design workflow where every step writes more Markdown. The integration pattern:

# After every step that writes .md files
cd docs/specs/my-project
npx sigma-html-export
git add '*.html' index.html

Since the build is incremental and zero-config, it's cheap to run on every commit or as a pre-push hook.

Plays nicely with:

• PRDs / ADRs / RFCs
• Shape Up pitches
• Design-doc directories
• Handwritten spec bundles

Design rules

1. Zero dependencies in the builder. Pure Node stdlib. marked.js is only ever loaded by the browser, from a CDN.
2. Markdown is the source of truth. HTML is a view. Do not edit .html files directly — they'll be overwritten.
3. Incremental by default. Only re-render MDs whose mtime is newer than their HTML.
4. Offline-stable. After first page load, CDN assets are cached by the browser. The HTMLs have no fetch dependencies on sibling files.
5. Self-contained HTMLs. You can zip the folder, email it, upload it to a static host — every file works on its own.

Contributing

Bug reports and PRs welcome. Please:

1. Keep the zero-dep promise intact — no new runtime dependencies
2. If you're adding a theme, drop it in lib/themes.mjs and add a row to the README table
3. Run npm run demo to smoke-test locally

License

MIT © 2026 Benedikt

Related

• marked.js — the underlying Markdown renderer
• Sigma Protocol — the spec workflow this tool was built for