Rendering Spec & Plan Docs

Overview

Render a markdown design/spec/plan/notes document to self-contained, house-style HTML (Times body, Helvetica headings, warm accent palette, CSS inlined). One look across every doc the user reads.

Core rule: author Markdown, render with the script. NEVER hand-roll a pandoc command, and NEVER hand-write HTML or invent CSS. Ad-hoc invocations drift from the house style and can't be re-rendered consistently.

This is the general renderer. For PR review walkthroughs (a specific narrative structure), use pr-walkthrough instead (it has its own page style: contents box, margin footnotes).

How to render

Pick the first that applies:

# 1. Inside the munis_home repo (source of truth for the CSS):
./utilities/bash/render_spec.sh path/to/doc.md

# 2. Any other repo (portable, bundled with this skill — only needs pandoc):
~/.claude/skills/rendering-spec-docs/render-doc.sh path/to/doc.md
#   add --open to open it in the browser after rendering

Both write doc.html next to the source, inline the CSS (--embed-resources), and highlight code with pygments. Only dependency: pandoc (brew install pandoc).

Verify self-contained

rg -c '<style' doc.html   # expect >= 1
rg -c '<link'  doc.html   # expect 0

Then surface the path (and a file:// URL) on its own line so the user can click it.

Common mistakes

Keywords

render spec, render plan, design doc to html, view markdown in browser, house style, review.css, pandoc, self-contained html, superpowers specs, superpowers plans, brainstorm doc, handoff doc.