Write Pandoc Markdown
Apply the Pandoc Markdown conventions from the reference files below when
creating or editing academic papers authored in Pandoc-flavored Markdown.
This skill covers Pandoc extensions and the Markdown-to-LaTeX pipeline. For
GFM formatting and markdownlint rules, see the write-markdown skill instead.
Document titles belong in YAML frontmatter (title:), not as a body #
heading. The frontmatter title is the implicit H1, so the first real body
section starts at ##.
Core Principles
- Plain text sustainability -- Markdown source should remain readable and
editable decades from now, independent of any tool
- Separation of content and formatting -- write content in Markdown; let
the template and build pipeline handle visual presentation
- Pandoc syntax over raw LaTeX when possible -- use
[@key] for
citations, $...$ for math, Markdown headings for sections; fall back to
raw LaTeX only for constructs Pandoc cannot express
- Format-independent content -- raw LaTeX blocks are invisible in HTML and
DOCX output; prefer Pandoc-native syntax for maximum portability
Workflow
- Review against the essential checklist:
./references/essential/checklist.md
- For specific questions, consult the comprehensive references below
Reference Navigation
Quick reviews (default):
references/essential/checklist.md -- condensed, actionable rules
Deep dives by topic:
references/comprehensive/math-and-citations.md -- math delimiter rules,
currency escaping, citation syntax, natbib vs citeprocreferences/comprehensive/cross-references.md -- raw LaTeX spans,
pandoc-crossref, section labels, filter orderingreferences/comprehensive/raw-latex-blocks.md -- when to use raw LaTeX,
fenced block syntax, inline raw spans, theorem environmentsreferences/comprehensive/yaml-frontmatter.md -- academic metadata fields,
template variables, header includes, field escapingreferences/comprehensive/build-pipeline.md -- two-stage build, Pandoc
flags, PDF engines, Lua filters
Sources
- MacFarlane, J. Pandoc User's Guide. pandoc.org.
- Yakimova, N. pandoc-crossref. GitHub.
- Drescher, D. and Gessler, A. Pandoc Scholar.
- Programming Historian. "Sustainable Authorship in Plain Text Using Pandoc
and Markdown."
1---2name: write-pandoc-markdown3description: Pandoc-flavored Markdown conventions for academic papers with LaTeX output. Use when: (1) writing or editing .md files that use Pandoc extensions (math delimiters, citations, raw LaTeX blocks), (2) configuring YAML frontmatter for academic papers, (3) using Pandoc citation syntax, (4) embedding raw LaTeX in Markdown, or (5) working with the Pandoc-to-LaTeX build pipeline. This skill is distinct from write-markdown, which covers GFM and markdownlint rules.4---56# Write Pandoc Markdown78Apply the Pandoc Markdown conventions from the reference files below when9creating or editing academic papers authored in Pandoc-flavored Markdown.1011This skill covers Pandoc extensions and the Markdown-to-LaTeX pipeline. For12GFM formatting and markdownlint rules, see the `write-markdown` skill instead.1314Document titles belong in YAML frontmatter (`title:`), not as a body `#`15heading. The frontmatter title is the implicit H1, so the first real body16section starts at `##`.1718## Core Principles19201. **Plain text sustainability** -- Markdown source should remain readable and21 editable decades from now, independent of any tool221. **Separation of content and formatting** -- write content in Markdown; let23 the template and build pipeline handle visual presentation241. **Pandoc syntax over raw LaTeX when possible** -- use `[@key]` for25 citations, `$...$` for math, Markdown headings for sections; fall back to26 raw LaTeX only for constructs Pandoc cannot express271. **Format-independent content** -- raw LaTeX blocks are invisible in HTML and28 DOCX output; prefer Pandoc-native syntax for maximum portability2930## Workflow31321. Review against the essential checklist:33 `./references/essential/checklist.md`341. For specific questions, consult the comprehensive references below3536## Reference Navigation3738**Quick reviews (default):**3940- `references/essential/checklist.md` -- condensed, actionable rules4142**Deep dives by topic:**4344- `references/comprehensive/math-and-citations.md` -- math delimiter rules,45 currency escaping, citation syntax, natbib vs citeproc46- `references/comprehensive/cross-references.md` -- raw LaTeX spans,47 pandoc-crossref, section labels, filter ordering48- `references/comprehensive/raw-latex-blocks.md` -- when to use raw LaTeX,49 fenced block syntax, inline raw spans, theorem environments50- `references/comprehensive/yaml-frontmatter.md` -- academic metadata fields,51 template variables, header includes, field escaping52- `references/comprehensive/build-pipeline.md` -- two-stage build, Pandoc53 flags, PDF engines, Lua filters5455## Sources5657- MacFarlane, J. _Pandoc User's Guide_. pandoc.org.58- Yakimova, N. _pandoc-crossref_. GitHub.59- Drescher, D. and Gessler, A. _Pandoc Scholar_.60- Programming Historian. "Sustainable Authorship in Plain Text Using Pandoc61 and Markdown."
cboone