Markdown → Polished Word/PDF

Convert Markdown to a real, well-formatted .docx (or PDF) using the locally installed pandoc. Pandoc parses the Markdown and emits true document structure — headings become Word heading styles, **bold** becomes bold, lists and tables become real lists and tables. Literal #, *, and | never appear in the output.

Preconditions

• Requires pandoc (already installed: check with pandoc --version). If missing, tell the user to brew install pandoc — do not attempt a silent workaround that reintroduces raw symbols.
• For PDF output, pandoc needs a PDF engine. Prefer --pdf-engine=weasyprint or wkhtmltopdf if present; if none is available, produce .docx and tell the user to export to PDF from Word.

Core conversion (this is the fix for "raw # symbols")

pandoc INPUT.md \
  --from gfm \
  --to docx \
  --toc --toc-depth=3 \
  --number-sections \
  --reference-doc="$HOME/.claude/skills/md-to-docx/reference/template.docx" \
  -o OUTPUT.docx

• --from gfm parses GitHub-Flavored Markdown (tables, task lists, fenced code).
• --toc adds a table of contents; --number-sections numbers headings (drop either if unwanted).
• --reference-doc applies the styled template for fonts/spacing/branding. If the template file does not exist, omit that flag — pandoc then uses its clean default styles (still no raw symbols).

Workflow

1. Confirm the input .md path and desired output (docx or pdf) and filename.
2. Verify pandoc is available.
3. Decide on options with the user only if they care: TOC yes/no, numbered sections yes/no, styled template yes/no. Otherwise use the defaults above.
4. Run the conversion.
5. Verify the output has no literal Markdown. Run a round-trip check and inspect:

   pandoc OUTPUT.docx -t plain | grep -nE '(^#{1,6} )|\*\*|\]\(http|^\s*\|' && echo "WARN: raw markdown detected" || echo "clean"

   If raw markdown is detected, the source likely used a syntax pandoc didn't parse — investigate rather than shipping.
6. Report the output path and that the conversion is clean.

Styled template (visual quality)

To make the document look good (corporate fonts, heading colors, spacing), create a reference template once and pass it with --reference-doc:

# Generate a starter template, then edit its styles in Word and re-save:
pandoc -o "$HOME/.claude/skills/md-to-docx/reference/template.docx" --print-default-data-file reference.docx

Edit the heading/body styles in that file (Home → Styles → modify), save, and every future conversion inherits the look. See reference/styling-notes.md.

Notes

• Pandoc is deterministic and local — no network calls. This skill only orchestrates it.
• This skill is the final step after the customer-facing-spec → leak-check → writing-clearly-and-concisely pipeline: convert only the cleared, edited Markdown.