| name | markdown-to-pdf |
| description | Convert a Markdown document (an ana_log, report, or note) to a shareable PDF or Word (.docx) via pandoc. Use when the user asks to "convert/render markdown to PDF/Word/docx", "render this ana_log/report to PDF", "export markdown to a document", "make a PDF of this", "turn this .md into a docx". Prose documents, not slide decks (slides go through Marp). Requires pandoc + a LaTeX engine for PDF, and python-docx for round-trip-safe .docx edits. Self-contained repo copy — depends only on tools the environment provides, not on any user-level skill or ~/.claude workflow. |
| modes | {"requires_fates":false,"nutrient_pathway":"any","scope":["reporting"],"summary":"Markdown → PDF/DOCX conversion; applies in every mode."} |
Markdown → PDF / DOCX
Convert a Markdown document into a shareable PDF or Word .docx. For A2MC this is the
"render an ana_log / report to PDF" step. Prose only — slide decks go through Marp
(markdown → PDF/PPTX), not here.
Self-contained by design. This is a repo-vendored copy of a general converter, kept
inside .claude/skills/ so it works wherever this repo runs (local, Perlmutter, a fresh
clone) — it must NOT depend on a user-level skill or on ~/.claude/ assets that won't exist
elsewhere. It relies only on tools the environment provides (pandoc, a LaTeX engine,
python-docx).
Requirements (provided by the environment, locations vary by machine)
| Tool | Role | Find it |
|---|
| pandoc (v3+) | Markdown ↔ PDF / DOCX | command -v pandoc (macOS dev: /opt/homebrew/bin; Perlmutter: module load or conda) |
LaTeX engine (pdflatex/xelatex) | PDF backend pandoc calls | macOS: BasicTeX at /Library/TeX/texbin (export PATH="/Library/TeX/texbin:$PATH"); Perlmutter: module load texlive |
| python-docx | round-trip-safe .docx edits | any Python with it installed (pip install python-docx) |
Step 1 — pick the target
| Want | Step |
|---|
| PDF of a prose note/report/ana_log | pandoc → PDF (Step 2) |
New .docx from markdown | pandoc → DOCX (Step 3) |
Edit an existing .docx preserving tables / tracked changes / citation fields | python-docx, not a round-trip (Step 4) |
Step 2 — Markdown → PDF
pandoc note.md -o note.pdf
pandoc note.md --pdf-engine=xelatex -o note.pdf
PDF requires a LaTeX engine. pandoc renders LaTeX math natively. Missing TeX package on a
machine you control: tlmgr install <package> (BasicTeX) or via the cluster's texlive.
Step 3 — Markdown → DOCX
pandoc -f markdown -t docx note.md -o note.docx
pandoc -f markdown -t docx --reference-doc=template.docx note.md -o note.docx
--reference-doc carries a Word template's styles (headings, fonts, margins) into the output.
Step 4 — editing an EXISTING .docx (round-trip-safe)
A naive pandoc docx→md→docx drops tracked changes, comments, and live citation fields and can
mangle tables. Don't do it for a document that has any of those. Instead edit in place with
python-docx (paragraph-level, preserves styles/tables):
python3 -c "from docx import Document; d=Document('in.docx'); ...; d.save('out.docx')"
(Manuscript-grade section-merge tooling lives in the manuscript workspace, not this repo —
keep this skill's footprint to the generic pandoc + python-docx mechanics.)
Guardrails
- PDF needs a LaTeX engine — if
pandoc -o x.pdf errors "pdflatex not found", put the
engine on PATH (/Library/TeX/texbin on macOS) or module load texlive on a cluster.
- Back up before overwriting a
.docx in a non-git location: copy to
<name>_v<n>_YYYYMMDD.docx first.
- Don't round-trip a
.docx through markdown if it has tracked changes / comments /
citation fields — use python-docx (Step 4).
- Prose only; slide decks go through Marp, not here.
Changelog
- 2026-06-23: Repo-vendored, self-contained copy of the general
markdown-to-pdf converter
(the canonical cross-project version stays at user level). Adapted for this repo: stripped
the ~/.claude/workflows/ Manuscript_DocxMerge_Workflow + user-level skill references and
the hardcoded personal env paths, so it works wherever the repo runs (local / Perlmutter /
fresh clone) — it depends only on environment-provided tools (pandoc, a LaTeX engine,
python-docx). Referenced by the scientific-analysis skill for rendering ana_logs.
