Skill: tridefender/pandoc-convert (version 1.0.0)

--- name: pandoc-convert description: "Convert documents between formats using Pandoc CLI (Markdown, DOCX, PDF, HTML, EPUB, PPTX, ODT, RTF, LaTeX, CSV/TSV, Jupyter, etc.). Use when: (1) converting file formats, (2) generating DOCX/PDF from Markdown, (3) creating slide decks (PPTX/Beamer/Reveal.js), (4) extracting text from DOCX/EPUB/ODT, (5) producing EPUBs, (6) any Pandoc conversion task." --- # Pandoc Document Conversion Pandoc 3.6.3 installed at `~/.local/bin/pandoc`. Features: +server +lua. ## Quick Reference ```bash # Basic conversion pandoc input.md -o output.docx # MD → Word pandoc input.md -o output.pdf # MD → PDF (needs LaTeX) pandoc input.md -o output.html # MD → HTML pandoc input.md -o output.epub # MD → EPUB pandoc input.md -o output.pptx # MD → PowerPoint pandoc input.md -o output.odt # MD → OpenDocument pandoc input.md -o output.rtf # MD → RTF pandoc input.md -o output.tex # MD → LaTeX pandoc input.docx -o output.md # Word → Markdown pandoc input.html -o output.md # HTML → Markdown pandoc input.epub -o output.md # EPUB → Markdown # Standalone document (with headers/footers/styles) pandoc -s input.md -o output.html # With metadata pandoc -s --metadata title="Report" --metadata author="Kairo" input.md -o output.docx # With table of contents pandoc -s --toc input.md -o output.docx # With custom reference doc (Word styles) pandoc --reference-doc=custom-reference.docx input.md -o output.docx # With CSS (HTML/EPUB) pandoc -s --css=style.css input.md -o output.html # Extract media from document pandoc --extract-media=./media input.docx -o output.md # Self-contained HTML (no external dependencies) pandoc -s --embed-resources input.md -o output.html # Number sections pandoc -s --number-sections input.md -o output.docx # Read from URL pandoc -f html -t markdown https://example.com -o page.md # Custom request header for URL fetch pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" https://example.com -o page.md ``` ## Key Options ### General Options | Option | Effect | |---|---| | `-f FORMAT` | Input format (default: auto-detect by extension) | | `-t FORMAT` | Output format (default: auto-detect by extension) | | `-o FILE` | Output file path (`-` for stdout) | | `-s, --standalone` | Produce complete document (header, footer, etc.) | | `--template=FILE\|URL` | Custom template (implies --standalone) | | `-M KEY[=VAL]` | Set metadata field (overrides YAML block) | | `--metadata-file=FILE` | Read metadata from YAML/JSON file | | `-V KEY[=VAL]` | Set template variable | | `--variable-json=KEY=JSON` | Set template variable to JSON value (bool, list, map) | | `-d FILE, --defaults=FILE` | Load options from YAML/JSON defaults file | | `--data-dir=DIRECTORY` | User data directory for templates, reference docs, etc. | | `--sandbox` | Limit IO operations (for untrusted input) | | `--verbose` | Verbose debugging output | | `--quiet` | Suppress warning messages | | `--fail-if-warnings` | Exit with error if any warnings | | `--log=FILE` | Write log messages as JSON to FILE | ### Reader Options | Option | Effect | |---|---| | `--shift-heading-level-by=N` | Shift heading levels (positive or negative) | | `--file-scope` | Parse each file individually (multi-file) | | `-F PROGRAM, --filter=PROGRAM` | JSON filter to transform AST | | `-L SCRIPT, --lua-filter=SCRIPT` | Lua filter to transform AST | | `--extract-media=DIR\|FILE.zip` | Extract embedded media | | `--track-changes=accept\|reject\|all` | Handle Word Track Changes | | `--preserve-tabs` | Keep tabs instead of converting to spaces | | `--tab-stop=NUMBER` | Spaces per tab (default 4) | ### Writer Options | Option | Effect | |---|---| | `--toc` | Include table of contents | | `--toc-depth=N` | TOC depth (default 3) | | `--lof` | List of figures | | `--lot` | List of tables | | `-N, --number-sections` | Number section headings | | `--number-offset=N[,N…]` | Offset section numbers | | `--wrap=auto\|none\|preserve` | Text wrapping (default: auto) | | `--columns=N` | Line width in chars (default 72) | | `--resource-path=DIR:DIR` | Resource search paths (default: working dir) | | `--embed-resources` | Self-contained HTML (no external deps) | | `--reference-doc=FILE\|URL` | Custom styles for DOCX/ODT/PPTX | | `--css=URL` | Link CSS stylesheet (repeatable) | | `--reference-links` | Use reference-style links in MD output | | `--top-level-division=section\|chapter\|part` | Top-level heading division type | | `--ascii` | Use only ASCII in output | | `--dpi=NUMBER` | Default DPI for image conversion (default 96) | | `--eol=crlf\|lf\|native` | Line ending style | | `--pdf-engine=ENGINE` | PDF engine (see below) | | `--pdf-engine-opt=STRING` | Extra args for PDF engine | | `-i, --incremental` | Incremental lists in slide shows | | `--slide-level=N` | Heading level that creates slides | | `--split-level=N` | Heading level for EPUB/chunked HTML splitting | | `--epub-cover-image=FILE` | EPUB cover image | | `--epub-title-page=true\|false` | Include EPUB title page (default true) | | `--epub-embed-font=FILE` | Embed font in EPUB (repeatable) | | `--epub-metadata=FILE` | XML file with Dublin Core metadata | | `--epub-subdirectory=DIR` | EPUB subdirectory in OCF container | | `--highlight-style=STYLE\|FILE` | **(Deprecated)** Use `--syntax-highlighting` | | `--syntax-highlighting=default\|none\|idiomatic\|STYLE\|FILE` | Code highlighting method | | `--no-highlight` | **(Deprecated)** Use `--syntax-highlighting=none` | | `-H FILE` | Include in header (CSS/JS for HTML, raw LaTeX) | | `-B FILE` | Include before body | | `-A FILE` | Include after body | ### Citation Options | Option | Effect | |---|---| | `-C, --citeproc` | Process citations, render bibliography | | `--bibliography=FILE` | Bibliography file (.bib, .bibtex, .json, .yaml, .ris) | | `--csl=FILE` | CSL citation style file | | `--citation-abbreviations=FILE` | Journal abbreviation JSON | | `--natbib` | Use natbib for LaTeX citations (no --citeproc) | | `--biblatex` | Use biblatex for LaTeX citations (no --citeproc) | ### Math Rendering (HTML) | Option | Effect | |---|---| | `--mathjax[=URL]` | Render math with MathJax | | `--mathml` | Render math as MathML | | `--webtex[=URL]` | Convert math to images via external service | | `--katex[=URL]` | Render math with KaTeX | | `--gladtex` | Use GladTeX for math rendering | ## PDF Generation ```bash # Default (LaTeX via pdflatex) pandoc input.md -o output.pdf # Chinese support (XeLaTeX) pandoc --pdf-engine=xelatex -V CJKmainfont="Noto Sans CJK SC" input.md -o output.pdf # LuaLaTeX (alternative CJK) pandoc --pdf-engine=lualatex -V CJKmainfont="Noto Sans CJK SC" input.md -o output.pdf # HTML intermediate (wkhtmltopdf) pandoc --pdf-engine=wkhtmltopdf -s input.md -o output.pdf # WeasyPrint (HTML intermediate) pandoc --pdf-engine=weasyprint -s input.md -o output.pdf # Typst (fast, no LaTeX needed) pandoc --pdf-engine=typst input.md -o output.pdf # ConTeXt pandoc -t context input.md -o output.pdf # roff ms (via pdfroff) pandoc -t ms input.md -o output.pdf # latexmk (auto-run LaTeX as needed) pandoc --pdf-engine=latexmk input.md -o output.pdf # Pass extra options to PDF engine pandoc --pdf-engine=xelatex --pdf-engine-opt=-shell-escape input.md -o output.pdf # Debug: output intermediate LaTeX pandoc -s -o output.tex input.md # Then test: pdflatex output.tex ``` **Supported PDF engines**: pdflatex, xelatex, lualatex, latexmk, tectonic, wkhtmltopdf, weasyprint, pagedjs-cli, prince, context, groff, pdfroff, typst. **Default engines by intermediate format**: - `-t latex` (or none): pdflatex - `-t context`: context - `-t html`: weasyprint - `-t ms`: pdfroff - `-t typst`: typst **Chinese PDF requirements**: XeLaTeX or LuaLaTeX + CJK font. If CJKmainfont is set, xeCJK is needed (xelatex) or luatexja (lualatex). fontspec is required for xelatex/lualatex. **LaTeX packages needed**: amsfonts, amsmath, lm, unicode-math, iftex, fancyvrb, longtable, booktabs, multirow, graphicx, bookmark, xcolor, soul, geometry (with geometry variable), setspace (with linestretch), babel (with lang). ### 默认中英混排 PDF 字体方案（实测可用） Linux 系统字体路径：`/usr/share/fonts/` | 用途 | 字体包 | 字体名（pandoc -V 参数） | |------|--------|------------------------| | 中文正文/标题 | 文泉驿正黑 | `wqy-zenhei` | | 英文正文/标题 | Helvetica Neue | `helvetiker` | | 代码块 | Courier New / Latin Modern Mono | 默认 monospace 即可 | **标准生成命令（中英混排）**： ```bash pandoc input.md \ -o output.pdf \ --pdf-engine=xelatex \ -V CJKmainfont="wqy-zenhei" \ -V mainfont="helvetiker" \ -V monofont="Courier New" \ -V geometry:margin=1in \ -V linestretch=1.1 \ -V fontsize=12pt ``` **注意事项**： - `mainfont`（英文）和 `CJKmainfont`（中文）必须同时设置，否则中英文混排时其中一种会回退到默认 CM 字体 - 不要混用 pdflatex（不支持中文）和 xelatex - 代码块默认用 Latin Modern Mono，若要 Courier 风格可加 `-V monofont="Courier New"` - 字体名大小写敏感，敲错 Pandoc 只给警告但仍出 PDF（回退到默认字体），需注意检查输出 **字体名参考**（xelatex + fontspec）： ``` # 查看已安装的中文字体（Linux） fc-list :lang=zh -f '%{family}\n' | sort -u # 查看已安装的英文无衬线字体 fc-list | grep -i 'helvetica\|arial\|sans' | head -20 # 测试字体是否可用（直接 pandoc -V CJKmainfont="字体名"） ``` ## DOCX Customization Generate a reference doc to customize styles: ```bash pandoc -o custom-reference.docx --print-default-data-file reference.docx ``` Open in Word, modify styles, save. Then use `--reference-doc=custom-reference.docx`. **Paragraph styles**: Normal, Body Text, First Paragraph, Compact, Title, Subtitle, Author, Date, Abstract, AbstractTitle, Bibliography, Heading 1–9, Block Text, Footnote Block Text, Source Code, Footnote Text, Definition Term, Definition, Caption, Table Caption, Image Caption, Figure, Captioned Figure, TOC Heading. **Character styles**: Default Paragraph Font, Verbatim Char, Footnote Reference, Hyperlink, Section Number. **Table style**: Table. **Custom block styles** (via `custom-style` attribute): ```markdown ::: {custom-style="My Special Style"} This paragraph gets the "My Special Style" style. ::: ``` ## ODT Customization ```bash pandoc -o custom-reference.odt --print-default-data-file reference.odt ``` Open in LibreOffice, modify styles, save. Use `--reference-doc=custom-reference.odt`. ## PowerPoint Customization Templates included with MS PowerPoint 2013+ work. Required layout names: - Title Slide, Title and Content, Section Header, Two Content, Comparison, Content with Caption, Blank. ```bash pandoc -o custom-reference.pptx --print-default-data-file reference.pptx ``` **Layout choice** (automatic based on content): - **Title Slide**: Initial slide from metadata (title, author, date) - **Section Header**: Title slides (heading above slide level) - **Two Content**: Two-column slides (div.columns with div.column) - **Comparison**: Two-column with text + non-text (image/table) - **Content with Caption**: Text followed by non-text - **Blank**: Only blank content or speaker notes - **Title and Content**: Default for everything else ## Slide Shows ```bash # PowerPoint pandoc -t pptx slides.md -o presentation.pptx # Beamer (LaTeX PDF) pandoc -t beamer slides.md -o presentation.pdf --pdf-engine=xelatex # Reveal.js pandoc -s -t revealjs slides.md -o presentation.html # S5, Slidy, Slideous, DZSlides pandoc -s -t slidy slides.md -o presentation.html pandoc -s -t s5 slides.md -o presentation.html pandoc -s -t slideous slides.md -o presentation.html pandoc -s -t dzslides slides.md -o presentation.html # Set slide level (which heading level creates slides) pandoc -t pptx --slide-level=2 slides.md -o presentation.pptx # Incremental lists pandoc -t pptx -i slides.md -o presentation.pptx # Beamer theme pandoc -t beamer -V theme:Warsaw -V colortheme:beaver slides.md -o presentation.pdf # Reveal.js theme pandoc -s -t revealjs -V theme=moon slides.md -o presentation.html # Self-contained reveal.js pandoc -s -t revealjs --embed-resources slides.md -o presentation.html # Speaker notes (reveal.js, pptx, beamer) ::: notes This is a speaker note. ::: # PowerPoint title slide speaker notes (via metadata) --- title: My Talk author: Jane Doe notes: | Welcome everyone. Remember to introduce yourself. --- # Pauses within a slide (not for PPTX) content before . . . content after # Columns :::::::::::::: {.columns} ::: {.column width="40%"} Left column ::: ::: {.column width="60%"} Right column ::: :::::::::::::: # Background images (reveal.js, beamer, pptx) ## {background-image="/path/to/image.jpg"} ``` ## Supported Formats **Input**: markdown, gfm, commonmark, commonmark_x, html, latex, docx, odt, epub, pptx, rtf, csv, tsv, org, rst, mediawiki, textile, json, ipynb, jira, djot, typst, vimwiki, xml, native, bibtex, biblatex, csljson, ris, docbook, jats, haddock, man, mdoc, fb2, opml, dokuwiki, muse, t2t, twiki, tikiwiki, creole, endnotexml, asciidoc, xlsx, pod, and more. **Output**: markdown, gfm, commonmark, html, html4, html5, latex, docx, odt, epub, epub2, epub3, pptx, pdf, rtf, plain, beamer, revealjs, slidy, s5, dzslides, slideous, typst, context, man, ms, texinfo, opendocument, icml, ipynb, rst, asciidoc, mediawiki, textile, jats, tei, vimdoc, chunkedhtml, fb2, docbook, docbook4, docbook5, jats_archiving, jats_articleauthoring, jats_publishing, json, native, xml, ansi, bbcode, markua, xwiki, zimwiki, bibtex, biblatex, csljson, and more. List formats: `pandoc --list-input-formats` / `pandoc --list-output-formats` ## Metadata in Markdown ```markdown --- title: "Document Title" author: "Author Name" date: 2026-04-12 lang: zh-CN subtitle: "Optional Subtitle" abstract: "Optional abstract" keywords: [keyword1, keyword2] subject: "Document subject" description: "Document description" category: "Document category" toc: true --- Content here... ``` Multiple authors: ```markdown --- author: - Aristotle - Peter Abelard --- ``` Structured authors: ```markdown --- author: - name: Author One affiliation: University of Somewhere - name: Author Two affiliation: University of Nowhere --- ``` ## Extensions Enable/disable per format: `-f markdown+footnotes-tex_math_dollars` or `-f gfm+raw_html`. Common useful extensions: - `+footnotes` — footnotes - `+inline_notes` — inline footnotes `^[note text]` - `+tex_math_dollars` — `$...$` inline math, `$$...$$` display math - `+raw_html` — raw HTML in Markdown - `+smart` — smart typography (em dashes, quotes, etc.) - `+yaml_metadata_block` — YAML front matter - `+table_captions` — table captions - `+implicit_figures` — standalone images become figures - `+fenced_divs` — `:::` fenced divs - `+bracketed_spans` — `[text]{.class}` spans - `+citations` — citation syntax `@key` - `+definition_lists` — definition lists - `+fancy_lists` — ordered lists with letters/roman numerals - `+task_lists` — `- [ ]` / `- [x]` task lists - `+example_lists` — `@` numbered examples - `+pipe_tables` — pipe tables - `+grid_tables` — grid tables - `+emoji` — `:smile:` emoji parsing - `+alerts` — GitHub-style `> [!TIP]` alerts - `-` prefix disables: `-smart`, `-raw_html` List: `pandoc --list-extensions=markdown` ## Filters & Lua Filters ```bash # JSON filter pandoc --filter ./filter.py input.md -o output.html # Lua filter pandoc --lua-filter=./filter.lua input.md -o output.html # Combine filters (applied in command-line order) pandoc --filter ./first.py --lua-filter=./second.lua -C input.md -o output.html # Lua filter path lookup order: # 1. Specified path (full or relative) # 2. $DATADIR/filters # JSON filter lookup adds: 3. $PATH (executable only) ``` ## Citations ```bash # With citeproc pandoc --citeproc --bibliography=refs.bib --csl=apa.csl input.md -o output.docx # In-text citation syntax @key # Author-in-text [@key] # Parenthetical [@key, p. 33] # With locator [-@key] # Suppress author [@key1; @key2] # Multiple see [@key, pp. 33-35] # With prefix/suffix # Include all references without citing nocite: | @* # Custom bibliography placement ::: {#refs} ::: # Suppress bibliography suppress-bibliography: true ``` **Bibliography formats**: BibLaTeX (.bib), BibTeX (.bibtex), CSL JSON (.json), CSL YAML (.yaml), RIS (.ris). ## Common Patterns ```bash # Concatenate multiple files into book pandoc ch1.md ch2.md ch3.md -o book.docx -s --toc # Convert web page pandoc -f html -t markdown https://example.com -o page.md # Batch convert (shell) for f in *.md; do pandoc "$f" -o "${f%.md}.docx" -s; done # Extract text from Word (for processing) pandoc document.docx -t plain -o text.txt # Markdown to styled HTML with TOC pandoc -s --toc --toc-depth=2 --css=style.css --metadata title="Report" input.md -o output.html # Number sections with offset pandoc -s --number-sections --number-offset=5 input.md -o output.docx # EPUB with metadata pandoc -s --toc --epub-cover-image=cover.jpg --metadata lang=zh-CN \ --css=epub.css input.md -o output.epub # Chunked HTML (split into multiple files) pandoc -s --toc -t chunkedhtml input.md -o output # Jupyter notebook pandoc input.ipynb -o output.md pandoc input.md -o output.ipynb # Convert between bibliography formats pandoc chem.bib -s -f biblatex -t csljson -o chem.json pandoc chem.json -s -f csljson -t biblatex -o chem.bib # Shift heading levels (e.g., HTML docs with H1 title → make H2 the top section) pandoc --shift-heading-level-by=-1 input.md -o output.md ``` ## Troubleshooting - **PDF fails**: Ensure LaTeX is installed (`which pdflatex`). Try `--pdf-engine=xelatex` for CJK. - **Chinese garbled**: Use `--pdf-engine=xelatex -V CJKmainfont="FontName"`. - **Images not found**: Use `--resource-path=.:images` to set search paths. - **Missing styles in DOCX**: Use `--reference-doc=reference.docx`. - **Code blocks not highlighted**: Use `--syntax-highlighting=pygments` (not `--highlight-style`). - **List all extensions**: `pandoc --list-extensions=markdown` - **Debug PDF**: Output intermediate: `-o output.tex` instead of `.pdf`. - **Exit codes**: See `references/advanced.md` for full exit code table. - **Untrusted input**: Use `--sandbox` to limit IO operations. ## Advanced Reference For detailed template variables, custom writers, Lua scripting, citation management, EPUB creation, chunked HTML, and exit codes, see [references/advanced.md](references/advanced.md).

path: references/advanced.md
content: # Pandoc Advanced Reference

## Exit Codes

| Code | Error |
|---|---|
| 0 | Success |
| 1 | PandocIOError |
| 3 | PandocFailOnWarningError |
| 4 | PandocAppError |
| 5 | PandocTemplateError |
| 6 | PandocOptionError |
| 21 | PandocUnknownReaderError |
| 22 | PandocUnknownWriterError |
| 23 | PandocUnsupportedExtensionError |
| 24 | PandocCiteprocError |
| 25 | PandocBibliographyError |
| 31 | PandocEpubSubdirectoryError |
| 43 | PandocPDFError |
| 44 | PandocXMLError |
| 47 | PandocPDFProgramNotFoundError |
| 61 | PandocHttpError |
| 62 | PandocShouldNeverHappenError |
| 63 | PandocSomeError |
| 64 | PandocParseError |
| 66 | PandocMakePDFError |
| 67 | PandocSyntaxMapError |
| 83 | PandocFilterError |
| 84 | PandocLuaError |
| 89 | PandocNoScriptingEngine |
| 91 | PandocMacroLoop |
| 92 | PandocUTF8DecodingError |
| 93 | PandocIpynbDecodingError |
| 94 | PandocUnsupportedCharsetError |
| 95 | PandocInputNotTextError |
| 97 | PandocCouldNotFindDataFileError |
| 98 | PandocCouldNotFindMetadataFileError |
| 99 | PandocResourceNotFound |

## Template Variables

### Metadata Variables
Set via YAML front matter or `-M/--metadata`:

| Variable | Description |
|---|---|
| `title` | Document title |
| `title-meta` | PDF/HTML metadata title (without body title) |
| `author` | Author(s) (string or list) |
| `author-meta` | PDF/HTML metadata author |
| `date` | Date |
| `date-meta` | PDF/HTML metadata date |
| `lang` | Language (e.g., `zh-CN`, `en`), BCP 47 tags |
| `subtitle` | Subtitle (HTML, EPUB, LaTeX, ConTeXt, docx) |
| `abstract` | Abstract text (HTML, LaTeX, ConTeXt, AsciiDoc, docx) |
| `abstract-title` | Title of abstract (HTML, EPUB, docx, Typst) |
| `keywords` | Keywords (HTML, PDF, ODT, pptx, docx, AsciiDoc) |
| `subject` | Subject (ODT, PDF, docx, EPUB, pptx) |
| `description` | Description (ODT, docx, pptx) |
| `category` | Category (docx, pptx) |
| `copyright` | Copyright |
| `pagetitle` | HTML page title (defaults to title) |
| `institute` | Institution (Beamer) |

### CJK / Chinese Variables
| Variable | Description |
|---|---|
| `CJKmainfont` | CJK main font (XeLaTeX/LuaLaTeX) |
| `CJKsansfont` | CJK sans-serif font |
| `CJKmonofont` | CJK monospace font |
| `mainfont` | Latin main font |
| `sansfont` | Latin sans-serif font |
| `monofont` | Latin monospace font |

### LaTeX Variables
| Variable | Description |
|---|---|
| `classoption` | Document class options |
| `documentclass` | LaTeX class (article, report, book) |
| `header-includes` | Raw LaTeX for header |
| `include-before` | Content before body |
| `include-after` | Content after body |
| `toc` | Include TOC |
| `toc-depth` | TOC nesting depth |
| `toc-title` | TOC heading text |
| `lof` | List of figures |
| `lot` | List of tables |
| `bibliography` | Bibliography file |
| `csl` | CSL style file |
| `nocite` | Include uncited items |
| `secnumdepth` | Section numbering depth |
| `geometry` | Page geometry (e.g., `margin=1in`) |
| `linestretch` | Line spacing |
| `fontsize` | Font size (e.g., `12pt`) |
| `papersize` | Paper size (a4, letter) |
| `margin-top`, `margin-bottom`, `margin-left`, `margin-right` | Page margins |
| `colorlinks` | `true` for colored links |
| `linkcolor` | Link color (e.g., `blue`) |
| `urlcolor` | URL color |
| `citecolor` | Citation color |
| `urlcolor` | URL color |
| `toccolor` | TOC link color |
| `links-as-notes` | `true` to show URLs as footnotes |

### HTML Variables
| Variable | Description |
|---|---|
| `css` | CSS stylesheet(s) |
| `header-includes` | Raw HTML for `<head>` |
| `include-before` | Content after `<body>` |
| `include-after` | Content before `</body>` |
| `lang` | Language for HTML lang attribute |
| `dir` | Text direction (ltr or rtl) |

### HTML Math Variables
| Variable | Description |
|---|---|
| `math` | Math rendering method |
| `mathjax` | MathJax URL (for `--mathjax`) |
| `katex` | KaTeX URL (for `--katex`) |
| `webtex` | WebTeX URL (for `--webtex`) |
| `gladtex` | GladTeX boolean |

### HTML Slide Variables
| Variable | Description |
|---|---|
| `theme` | Reveal.js / Slidy / S5 / Slideous theme |
| `colortheme` | Beamer color theme |
| `fonttheme` | Beamer font theme |
| `innertheme` | Beamer inner theme |
| `outertheme` | Beamer outer theme |
| `fontfamily` | Font family |
| `fontsize` | Base font size |
| `s5-url`, `slidy-url`, `slideous-url`, `revealjs-url` | JS/CSS URL paths |
| `title-slide-attributes` | Attributes for reveal.js/pptx title slide |
| `parallaxBackgroundImage` | Reveal.js parallax background |
| `parallaxBackgroundSize` | Reveal.js parallax size |
| `background-image` | Background image for all slides (beamer, reveal.js, pptx) |

### PowerPoint Variables
| Variable | Description |
|---|---|
| `aspectratio` | 43 (default) or 169 |
| `navigation` | symbols, frames, or empty |
| `incremental` | true/false |

### Variables Set Automatically
| Variable | Description |
|---|---|
| `sourcefile` | Source file path |
| `outputfile` | Output file path |
| `date` | Current date if not set in metadata |
| `lang` | Locale language if not set |
| `fontsize` | Default font size for format |
| `papersize` | Default paper size for format |
| `documentclass` | Default document class for format |

## Defaults Files

Place in `~/.local/share/pandoc/defaults/` (YAML or JSON):

```yaml
# ~/.local/share/pandoc/defaults/docx-chinese.yaml
from: markdown
to: docx
standalone: true
metadata:
  lang: zh-CN
variables:
  CJKmainfont: "Noto Sans CJK SC"
toc: true
toc-depth: 3
```

Usage: `pandoc -d docx-chinese input.md -o output.docx`

**Environment variable interpolation** in file path fields:
```yaml
csl: ${HOME}/mycsldir/special.csl   # User home
epub-cover-image: ${.}/cover.jpg     # Dir containing defaults file
resource-path:
  - .
  - ${.}/images
```

**Defaults file key mappings** (selected):
| Command line | Defaults file |
|---|---|
| `--from FORMAT` | `from:` / `reader:` |
| `--to FORMAT` | `to:` / `writer:` |
| `--output FILE` | `output-file:` |
| `--standalone` | `standalone: true` |
| `--metadata key=val` | `metadata: {key: val}` |
| `--variable key=val` | `variables: {key: val}` |
| `--toc` | `toc: true` |
| `--number-sections` | `number-sections: true` |
| `--pdf-engine xelatex` | `pdf-engine: xelatex` |
| `--citeproc` | `citeproc: true` |
| `--bibliography refs.bib` | `bibliography: refs.bib` |
| `--verbose` | `verbosity: INFO` |
| `--quiet` | `verbosity: ERROR` |

Multiple defaults combine; command-line values merge with defaults (don't replace for repeatable options like --metadata, --css, --filter).

## EPUB Creation

```bash
# Basic EPUB
pandoc -s --toc input.md -o output.epub

# With metadata and cover
pandoc -s --toc --metadata title="My Book" --metadata author="Author" \
  --metadata lang=zh-CN --epub-cover-image=cover.jpg --css=epub.css \
  input.md -o output.epub

# From multiple chapters
pandoc -s --toc ch1.md ch2.md ch3.md -o book.epub \
  --metadata title="Book Title"

# Keep footnotes separate per file
pandoc -s --toc --file-scope ch1.md ch2.md ch3.md -o book.epub

# Embed custom fonts
pandoc -s --toc --epub-embed-font=DejaVuSans-Regular.ttf \
  --epub-embed-font=DejaVuSans-Bold.ttf input.md -o output.epub

# EPUB metadata via XML
pandoc -s --toc --epub-metadata=meta.xml input.md -o output.epub

# Custom chapter split level (default 1)
pandoc -s --toc --split-level=2 input.md -o output.epub

# Suppress title page
pandoc -s --toc --epub-title-page=false input.md -o output.epub
```

**EPUB metadata YAML fields**: title (string or list with type), creator (string or list with role), identifier, publisher, rights, date, lang, subject, description, type, format, relation, coverage, belongs-to-collection, group-position, cover-image, css, page-progression-direction (ltr/rtl), accessibility features/summary/hazards/modes.

## Chunked HTML

```bash
# Create chunked HTML (zip archive of linked HTML files)
pandoc -s --toc -t chunkedhtml input.md -o output.zip

# Or output to directory (if no extension)
pandoc -s --toc -t chunkedhtml input.md -o output_dir

# Custom chunk template
pandoc -s --toc -t chunkedhtml --chunk-template="%i.html" input.md -o output

# Custom split level (default: level-1 headings)
pandoc -s --toc -t chunkedhtml --split-level=2 input.md -o output
```

## Template Syntax

Delimiters: `$...$` or `${...}` (can mix). Literal `$` → `$$`.

```text
$if(foo)$content$endif$           # Conditional
$if(foo)$yes$else$no$endif$       # If/else
${if(foo)}yes${endif}

$for(item)$$item$$endfor$         # Loop
$for(item)$$item$$sep$, $endfor$  # Loop with separator
${for(item)}${item}${sep}, ${endfor}

$it.key$                          # Anaphoric keyword in loops
$for(author)$  $it.name$ ($it.affiliation$) $endfor$

$partial_name()                   # Include partial template
${ styles() }                     # Same with braces
${ articles:bibentry() }          # Apply partial to each item

${ foo/uppercase }                # Pipe (transform)
${ foo/alpha }                    # Array index → letter (a, b, c...)
${ foo/roman }                    # Array index → roman numeral
${ foo/left 20 "|" " |" }        # Left-aligned in 20 chars
${ foo/right 10 " |" }           # Right-aligned in 10 chars
```

**Available pipes**: pairs, uppercase, lowercase, length, reverse, first, last, rest, allbutlast, chomp, nowrap, alpha, roman, left, right, center.

## Pandoc Server Mode

```bash
# Start server
pandoc --server localhost:3000

# Convert via HTTP
curl -X POST http://localhost:3000 \
  --data-binary @input.md \
  -H "Content-Type: text/markdown" \
  -H "Accept: application/vnd.openxmlformats-officedocument.wordprocessingml.document" \
  -o output.docx
```

## Pandoc as Lua Interpreter

```bash
pandoc -l script.lua
```

## Custom Readers and Writers

Custom Lua readers/writers can be specified as file paths in `-f` or `-t` options. They must return appropriate functions.

## Reproducible Builds

For LaTeX: the `--lua-filter` option can be used with a filter that normalizes metadata.
For ConTeXt, WeasyPrint, Prince XML, Typst: see the manual's "Reproducible builds" section.

## Accessible PDFs

LaTeX, ConTeXt, WeasyPrint, Prince XML, and Typst all support generating accessible (tagged) PDFs. See the manual's specific instructions for each engine.


path: scripts/pandoc-convert.sh
content: #!/usr/bin/env bash
# pandoc-convert.sh — Quick document conversion wrapper
# Usage: pandoc-convert.sh <input> <output> [options...]
#
# Examples:
#   pandoc-convert.sh report.md report.docx
#   pandoc-convert.sh slides.md slides.pptx --toc
#   pandoc-convert.sh readme.md readme.pdf --pdf-engine xelatex

set -euo pipefail

INPUT="${1:?Usage: pandoc-convert.sh <input> <output> [options...]}"
OUTPUT="${2:?Usage: pandoc-convert.sh <input> <output> [options...]}"
shift 2

# Auto-detect standalone for non-fragment formats
STANDALONE=false
case "$OUTPUT" in
  *.docx|*.odt|*.epub|*.epub3|*.epub2|*.pptx|*.pdf|*.rtf|*.icml)
    STANDALONE=true
    ;;
  *.html|*.htm)
    if [[ " $@ " != *" -s "* ]] && [[ " $@ " != *" --standalone "* ]] && [[ " $@ " != *" --embed-resources "* ]]; then
      STANDALONE=true
    fi
    ;;
esac

PANDOC_OPTS=()
if $STANDALONE; then
  PANDOC_OPTS+=("-s")
fi

# Auto-add PDF engine if none specified
if [[ "$OUTPUT" == *.pdf ]]; then
  if [[ " $@ " != *" --pdf-engine "* ]]; then
    if command -v xelatex &>/dev/null; then
      PANDOC_OPTS+=("--pdf-engine=xelatex")
    elif command -v lualatex &>/dev/null; then
      PANDOC_OPTS+=("--pdf-engine=lualatex")
    fi
  fi
fi

PANDOC_OPTS+=("$@")
pandoc "$INPUT" -o "$OUTPUT" "${PANDOC_OPTS[@]}"
echo "✅ Converted: $INPUT → $OUTPUT"


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)