md2pdf

Overview

Convert Markdown files to professional PDF using Pandoc + XeLaTeX + MiKTeX. Renders Mermaid diagrams as images, uses a ctexbook-based template (inspired by ucasthesis) for high-quality Chinese typesetting, and automatically generates figure captions from context.

Prerequisites

Tool	Install Command	Purpose
Pandoc >= 3.9	winget install JohnMacFarlane.Pandoc	Markdown to LaTeX conversion
MiKTeX	winget install MiKTeX.MiKTeX	LaTeX distribution (xelatex)
Mermaid CLI	npm install -g @anthropic-ai/mermaid-cli	Mermaid diagram rendering
Python >= 3.10	Already installed	Orchestration script

File Structure

~/.claude/skills/md2pdf/
├── SKILL.md           # This file (skill definition)
├── md2pdf.py          # Main conversion script
└── template.tex       # LaTeX template (ctexbook-based)

Mermaid images are cached in <input-dir>/.mermaid-images/ (auto-created).

Usage

python <skill-dir>/md2pdf.py <input.md> <output.pdf>

When the user asks to convert a markdown file to PDF:

1. Run python <skill-dir>/md2pdf.py <input.md> <output.pdf>
2. Check for errors in the output
3. Report the result to the user

Conversion Pipeline

Markdown
  │
  ├─ Remove manual section numbering (中文序号/数字序号)
  ├─ Remove manual table of contents
  ├─ Extract document title for cover page
  │
  ├─ Extract mermaid code blocks
  ├─ Render each as PNG via mmdc (natural size, 2x scale)
  ├─ Auto-generate figure captions from nearest heading
  ├─ Cache images in .mermaid-images/ (content hash keyed)
  │
  ├─ Pandoc: Markdown → LaTeX (using template.tex)
  │
  ├─ XeLaTeX compile (pass 1: collect TOC info)
  ├─ XeLaTeX compile (pass 2: populate TOC + cross-references)
  │
  └─ Clean up temp files (.tex, .aux, .log, .toc)

Key Design Decisions

Mermaid Rendering

• Use -s 2 (2x scale) WITHOUT fixed width (-w), preserving natural diagram size so text sizes are consistent across all diagrams
• Images are cached by content hash; unchanged diagrams are reused across runs
• Figure captions are auto-extracted from the nearest ##/### heading before the diagram

Image Scaling in PDF

• Template uses adjustbox with max width=\textwidth and max height=0.85\textheight
• Small diagrams render at natural size; only oversized ones are scaled down proportionally

Section Numbering

• Markdown manual numbering is stripped (e.g., ## 一、概述 → ## 概述, ### 5.1 标题 → ### 标题)
• LaTeX ctexbook auto-numbers all chapters, sections, subsections
• Manual TOC in Markdown is also removed; LaTeX generates its own

Table of Contents

• XeLaTeX must compile TWICE: first pass collects .toc data, second pass fills in the TOC
• Without two passes the TOC page will be blank

Tables

• Pandoc generates longtable with p{} columns (auto-wrapping, proportionally sized)
• Table text uses \footnotesize (one size smaller than body)
• Three-line table style via booktabs

Chinese Support

• Template uses ctexbook document class (no need for manual xeCJK setup)
• Windows system fonts (SimSun, SimHei, FangSong) are used automatically

Template Features

Feature	Detail
Document class	ctexbook (ucasthesis-inspired)
Page margins	2.5cm all sides
Auto-numbering	Chapters, sections, subsections
Table of contents	Auto-generated with dot leaders (two-pass compilation)
Table style	Three-line table (booktabs), footnotesize, auto-wrapping columns
Image handling	Natural size; only scaled down if exceeding page
Figure captions	Auto-extracted from nearest heading context
Code blocks	Gray background (snugshade) with syntax highlighting
Header/Footer	Page number + chapter/section title
Cover page	Title + date

Troubleshooting

Issue	Solution
pandoc not found	Restart terminal after install, or use full path in md2pdf.py
xelatex not found	Restart terminal after MiKTeX install
mmdc not found	Run npm install -g @mermaid-js/mermaid-cli
Missing LaTeX package	Run miktex packages install <package>
Chinese characters missing	Ensure system fonts (SimSun, SimHei) are available
Mermaid diagrams not rendered	Check mmdc: mmdc -i test.mmd -o test.png
TOC page is blank	Ensure two-pass xelatex compilation (script does this automatically)
Table exceeds page width	Table columns use p{} with auto-wrapping; check cell content length
No counter 'none' defined	Template defines \newcounter{none} to fix Pandoc+ctexbook conflict
\pandocbounded undefined	Template defines \providecommand{\pandocbounded}
Shaded environment undefined	Template defines Shaded environment using framed/snugshade