# Write Pandoc Markdown

> 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.

- Skill: `cboone/write-pandoc-markdown` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add cboone/write-pandoc-markdown`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cboone/write-pandoc-markdown/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: cboone (https://skillmd.com/u/cboone)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cboone/write-pandoc-markdown

---


# 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

1. **Plain text sustainability** -- Markdown source should remain readable and
   editable decades from now, independent of any tool
1. **Separation of content and formatting** -- write content in Markdown; let
   the template and build pipeline handle visual presentation
1. **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
1. **Format-independent content** -- raw LaTeX blocks are invisible in HTML and
   DOCX output; prefer Pandoc-native syntax for maximum portability

## Workflow

1. Review against the essential checklist:
   `./references/essential/checklist.md`
1. 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 citeproc
- `references/comprehensive/cross-references.md` -- raw LaTeX spans,
  pandoc-crossref, section labels, filter ordering
- `references/comprehensive/raw-latex-blocks.md` -- when to use raw LaTeX,
  fenced block syntax, inline raw spans, theorem environments
- `references/comprehensive/yaml-frontmatter.md` -- academic metadata fields,
  template variables, header includes, field escaping
- `references/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."