What it does

Converts markdown documents into branded HTML or PDF on demand. Markdown stays as the source of truth. Formatted outputs are generated artifacts, never edited directly.

The pattern

Write everything in markdown. It is portable, version-controllable, diffable, and readable by every tool in your stack. When you need a polished output, convert it.

The pipeline:

1. Author in markdown. Standard markdown with frontmatter for metadata (title, date, author, audience).

2. Detect context. The converter infers branding from file location or frontmatter tags. A document in a client directory gets client styling. A document tagged "internal" gets internal branding. No manual template selection.

3. Inject template. HTML templates define the visual wrapper: fonts, colors, headers, footers, margins. The markdown content slots into the template body. Templates are reusable across documents.

4. Render output. For HTML, the pipeline produces a self-contained single-file HTML document (inline CSS, no external dependencies). For PDF, a headless browser (Playwright) renders the HTML and prints to PDF.

5. Deliver. The output file lands next to the source markdown or in a designated output directory.

report.md  -->  [template injection]  -->  report.html
                                      -->  report.pdf

Key decisions

Markdown as source of truth. Never edit the HTML or PDF directly. If the content needs to change, change the markdown and regenerate. This prevents the common problem of having a "nice looking" PDF that diverges from the "actual" content.

Light themes for PDF. Dark backgrounds consume toner and render poorly in print. Even if your brand uses dark mode on the web, use light themes for any document that might be printed or viewed as a PDF.

Self-contained HTML. No external CSS links, no CDN fonts, no JavaScript dependencies. The HTML file should render correctly when opened from a local filesystem, emailed as an attachment, or viewed offline.

Headless browser for PDF, not a markdown-to-PDF library. Libraries like wkhtmltopdf and markdown-pdf have limited CSS support. A headless browser renders exactly what you see in the browser, including complex layouts, CSS grid, and web fonts.

When to use it

When you need to share documents with people who expect polished formatting: clients, executives, external partners. When you want to maintain one source file that produces multiple output formats. When your documentation pipeline needs to be scriptable and reproducible rather than dependent on manual formatting in a word processor.