/render-pdf-doc

name: render-pdf-doc
description: Use when rendering a Markdown document (English or Korean) such as a proposal, IRB cover letter, handout or reference table to PDF via pandoc and xelatex, with auto-fitted table widths and CJK fonts. Not for manuscripts with a bibliography (/manage-refs) or Word forms.
metadata:
  triggers: "render PDF, PDF 렌더, korean PDF, 한글 PDF, anchor doc PDF, briefing PDF, proposal PDF, 연구계획서 PDF, 표 정렬 PDF, 표 폭 자동, tbl-colwidths, 학술 PDF"

Render-PDF-Doc Skill

This skill handles layout only (CJK fonts, table column widths) with raw pandoc + xelatex — no Quarto, whose `tbl-colwidths` has reported PDF regressions (issues 6089/9200). Not for: a manuscript with a bibliography (`/manage-refs` `scripts/render_pandoc.sh`), an institutional .docx form (`/fill-protocol`), the ICMJE COI form (`/fill-icmje-coi`), figures or PPTX (`/make-figures`, `/present-paper`).

Dependencies

Python 3 is required by the wrapper. FontTools is optional for the font-file coverage check (`python3 -m pip install fonttools`).

# macOS
brew install pandoc
brew install --cask mactex-no-gui          # xelatex + xeCJK (~5 GB)

# Linux
sudo apt-get install pandoc texlive-xetex texlive-lang-cjk fonts-noto-cjk

# Windows (PowerShell) — run in Git Bash afterwards
winget install --id JohnMacFarlane.Pandoc
winget install --id MiKTeX.MiKTeX          # xelatex; installs missing LaTeX packages on demand
# No CJK font download needed: Malgun Gothic ships with Windows 7+ and is the default here.

Detection:

bash scripts/check_deps.sh

On Windows / Git Bash, MiKTeX's bin directory (`%LOCALAPPDATA%\Programs\MiKTeX\miktex\bin\x64`) is often not on `PATH`; both `check_deps.sh` and `render_pdf.sh` probe it. If `xelatex` still reads `[MISS]`, add that directory to `PATH`.

Workflow

Step 1 — Author markdown with frontmatter

---
title: "Paper 2 Calibration Anchor — Q&A Grid"
author: "<Author Group>"
date: "2026-05-01"
mainfont: "Apple SD Gothic Neo"        # macOS default
CJKmainfont: "Apple SD Gothic Neo"
geometry: "margin=0.85in"
fontsize: 11pt
linestretch: 1.25
colorlinks: true
---

• Set both `mainfont` and `CJKmainfont`: without `CJKmainfont`, Hangul falls back to Times New

Roman (broken glyphs or blanks). Use `Noto Sans CJK KR` on Linux/CI and `Malgun Gothic` on Windows; the render script auto-detects the per-OS default when the fields are absent.

• Read every number in a table from the source CSV or analysis output. Do not retype a number

from prose or carry one forward from an earlier draft — a table correct in v3 is not evidence it is correct in v4.

• A circulation PDF carries no change history, internal version numbers (e.g. v3.2.2) or PI

attribution: put them in a separate circulation file or a supplementary. Keep the received primary source (the `.docx` or `.eml` a co-author sent) unmodified as its own artifact — the PDF is a derivative, and the next round is diffed against the source. If that source was AI-drafted by a collaborator, re-derive every number, denominator and author-year in it from the underlying paper or analysis output before it reaches the PDF.

Step 2 — Infer column widths

Never split pipe-table columns equally: a column holding only short labels then gets the same width as the data columns, which cramps them. Size from content instead:

python3 scripts/infer_colwidths.py input.md > input.colwidths.md

For each pipe table it computes per-column display width = `max(len(header), max(len(cell)))` (CJK = 2 cells, ASCII = 1) and rewrites the separator row with proportional dash counts. To set widths by hand, write the separator dashes yourself and render without `--infer-colwidths`.

Step 3 — Render

bash scripts/render_pdf.sh -i input.colwidths.md -o output.pdf

Or one-shot:

bash scripts/render_pdf.sh -i input.md -o output.pdf --infer-colwidths

Frontmatter wins over wrapper defaults, including `--font` / `--cjk-font`. Missing fields use the wrapper or OS defaults. This also applies to `geometry`, `fontsize`, `linestretch` and `colorlinks` (including `false`). Explicit pandoc `-V` / `-M` arguments after `--` still override frontmatter; for example, `-- -V fontsize=10pt`. The wrapper logs font **fallbacks**, not the final fonts.

The standard `article` class honours only `10pt`, `11pt` and `12pt` and silently ignores any other size. When the effective `fontsize` is anything else and no `documentclass` is set, the wrapper switches to KOMA-Script `scrartcl` (pandoc's documented route), adds `classoption: fontsize=<size>` when you set no `classoption` (KOMA reads a fractional size such as `8.5pt` only that way), and logs the switch. Set `documentclass` yourself to override it.

Step 3.5 — Scientific-symbol + CJK glyph scan (before render)

xelatex can finish successfully with missing glyphs. `render_pdf.sh` counts the `Missing character` warnings pandoc relays: if there are any, it lists each glyph (code point, count, font) and **exits 4** — the PDF is written but incomplete. It reads them from pandoc's JSON `--log` (yours if you pass one after `--`), so a pass-through `--quiet` does not hide them. `--allow-missing-glyphs` prints the same list and exits 0. Academic markdown routinely carries glyphs a default Latin font misses: transition arrows (→ ↑ ↓), math operators (− ≤ ≥ ± √ ∪ × ≈ ≠), stats Greek (κ μ σ β), bullets/marks (• ★ ✓), and CJK. Scan the source first so a silent drop is caught before it ships:

python3 scripts/scan_glyph_coverage.py input.md --strict
# real cmap check when you have the font file + fonttools:
python3 scripts/scan_glyph_coverage.py input.md --font "/path/to/body.otf" --strict
# TTC/OTC collections require the zero-based face index used by the renderer:
python3 scripts/scan_glyph_coverage.py input.md --font "/path/to/body.ttc" --font-index 0 --strict --json glyphs.json

Without `--font` it groups the risky glyphs by class (advisory);