Markdown Document Publishing

Markdown Document Publishing

Turn an authored markdown file into a single HTML document you can email, host, or print — semantic structure, an automatic table of contents, figures and tables numbered and referenceable by number, footnotes, and a print stylesheet that survives contact with a PDF exporter. One file out, no runtime dependencies, no external assets.

When to use this skill

• Publishing a report or whitepaper that must arrive as one file, not a folder
• Producing a PDF from markdown without a LaTeX or Pandoc toolchain
• Numbering figures and tables so prose can reference them instead of saying "below"
• Converting untrusted or contributed markdown where injection safety matters
• Standardizing a document series so every issue looks like the same publication
• Catching broken cross-references before a document reaches readers

Inputs the skill expects

• A markdown source file, optionally with YAML frontmatter
• Figure images as relative paths (or data URIs, for true single-file output)
• The intended output: screen, print, or both
• Document length and whether a table of contents is warranted
• Page geometry, if printing: size, margins, single- or double-sided
• A stylesheet, if not using the bundled theme

Clarify First

Before converting, confirm these inputs. If any is unknown or vague, ASK — do not assume:

• Screen, print, or both — why it changes the output: print needs a page profile, forced light colors, and break control; skipping it produces a document that looks right on screen and breaks on paper
• Whether images must be embedded — why it changes the output: relative image paths mean the HTML file is not actually self-contained, which defeats the point if it will be emailed
• Document length and TOC expectation — why it changes the output: a TOC on a two-page memo is noise; depth 3 on a long report produces a TOC longer than some sections
• Whether the markdown is trusted — why it changes the output: it does not change escaping (always on), but it determines whether a review gate should run first

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

Workflows

Workflow 1 — Convert a document to self-contained HTML