Markdown to Single-File HTML Document
Turns long markdown specs, RFCs, and reports into one HTML file with sticky TOC, scrollspy, search, code copy, and brand tokens.
Before & after
Same prompt, same agent — the only difference is the skill.
To make a long technical spec more readable, you could: - Convert it to HTML with a clean stylesheet - Add a table of contents for navigation - Use syntax highlighting for code blocks - Break it into sections with clear headings - Add anchor links so sections can be linked directly There are many markdown-to-HTML tools available, and static site generators can produce nice documentation from markdown. For a single 60-page document, a tool that generates a single HTML file with a sidebar navigation would work well. Would you like recommendations for specific tools?
Converts the spec into a single self-contained HTML file — one file, no
build step, no dependencies to host. Here's what it produces and the one
precondition.
PRECONDITION — it refuses to render without this
Design-system onboarding must have run. The renderer reads your design
config via config_loader.py and inlines your 12 derived CSS custom
properties, so the output is on YOUR brand, not a default theme. If
onboarding hasn't run, it stops rather than emitting a generic-looking
document. Run onboarding first if it errors here.
WHAT THE OUTPUT HAS — built for a 60-page spec specifically
• Sticky table of contents with scrollspy — the current section stays
highlighted as you scroll, so you never lose your place in 60 pages
• Search filter — type to narrow the TOC to matching sections. On a
document this long, search is the difference between usable and not
• Code-copy buttons on every code block — one click, no selecting
• Your 12 brand tokens inlined as CSS variables, so it matches the
rest of your docs instead of looking like a converted file
WHY SINGLE-FILE MATTERS
No static-site generator, no folder of assets, no server. One HTML file
you can email, drop in a repo, or open offline. For a spec that gets
passed around, that's the whole point — it works everywhere without
setup.
HOW IT'S INVOKED
Either the markdown-html-orchestrator classifies your input as DOCUMENT
and routes it here automatically, or you call /cs:md-document directly.
For a 60-page spec, direct invocation is cleanest.
WHAT IT'S NOT
Not a live docs site with editing. It's a polished, read-optimized
snapshot — lightly interactive (TOC, search, copy), not an app.
Confirm onboarding has run and point me at the markdown — I'll generate
the single-file version.About this skill
Your 30-page spec lives in a markdown file that nobody opens. If they do open it, it's a wall of raw text with no navigation, and every "export to HTML" you've tried breaks the anchors, drops sections, or leaves code blocks unreadable. This skill turns long markdown into one HTML file you can send by email or Slack. Readers can jump to any section, search the whole thing, copy code, and print it, and none of your content gets changed or dropped.
What it does
- Keeps every paragraph, table row, and line of code from your source, and reports problems instead of rewriting your prose
- Builds GitHub-style anchors and gives duplicate headings unique names, rewrites internal links to match, and flags links whose target doesn't exist
- Adds a sticky table of contents with scrollspy that still works on short final sections and under a sticky header
- Adds in-page search with match count, next/previous, and keyboard shortcuts, without breaking syntax highlighting or copy buttons
- Applies your brand through 12 CSS variables, checks color contrast, adds dark mode, and adjusts any brand colors that are hard to read
- Handles GitHub alerts, task lists, footnotes, front matter, and print layout, and tells you plainly when a document is too long for one pass
What you get
One self-contained HTML file plus a short conversion report. The report lists renamed anchors, broken links, stripped HTML, blocks that couldn't be rendered, contrast fixes, and the assumptions that were made.
Best for
Engineers, PMs, and tech writers who share RFCs, design docs, runbooks, and reports with people who won't open a repo or a docs site.
SKILL.md preview
---
name: markdown-to-html-document
… (sign up to view the full skill)More development skills
View all Development skills →CodeTour Walkthrough File Builder
Writes a valid CodeTour .tour file for your repo: persona-targeted steps anchored to verified file paths and line numbers.
Code-Accurate Docs: Docstrings, JSDoc, OpenAPI Specs
Docstrings, JSDoc/TSDoc, OpenAPI specs, and quickstart guides written from your real code, covering error paths and edge cases.
Markdown to Single-File HTML (Docs, Reviews, Slides)
Turns markdown into one offline-safe HTML file laid out as a document, diff review, or slide deck, with a fidelity report.
Release Changelog from Commits and PRs
Turns a commit range or merged PRs into a release changelog with breaking changes, migration steps, and user-facing wording.