pandoc
Convert documents between formats with the universal
pandoc CLI. Input/output formats are inferred from file
extensions; override with -f <from> / -t <to> when needed.
PDF output requires a LaTeX engine (or --pdf-engine). Markdown/HTML/DOCX/EPUB
conversions need only pandoc itself.
Setup health check (run first, every session)
Verify with one solo step:
[{ "tool": "os.shell.run", "args": { "cmd": "pandoc", "args": ["--version"] } }]
Outcome map:
exit 0 + version → ready, proceed.command not found: pandoc → enter Setup playbook → "pandoc missing".- PDF target fails with
pdflatex not found → enter Setup playbook → "PDF engine missing".
Setup playbook (when prerequisites are missing)
pandoc missing
Reply (solo reply step):
"pandoc is not installed. I can install it: brew install pandoc. Install it?"
On yes:
[{ "tool": "os.shell.run", "args": { "cmd": "brew", "args": ["install", "pandoc"] } }]
On Linux: apt-get install pandoc.
On Windows, offer this exact winget command after confirmation:
[{ "tool": "os.shell.run", "args": { "cmd": "winget", "args": ["install", "--id", "JohnMacFarlane.Pandoc", "-e"] } }]
PDF engine missing
PDF output needs a TeX engine. Offer the lightweight option:
"PDF export needs a TeX engine. I can install: brew install --cask basictex (or the lightweight brew install tectonic). Which do you prefer?"
tectonic is simplest (pandoc in.md -o out.pdf --pdf-engine=tectonic).
When to use
- "Convert this Markdown to DOCX / PDF / HTML", "turn this HTML into Markdown".
- "Make an EPUB from these chapters", "export notes to a Word doc".
When NOT to use
- Reading a document's text — use
os.fs.read_document.
- Editing PDFs structurally (merge/split) — use the
pdf skill.
- Spreadsheet conversion — use the
xlsx skill.
Common operations
All examples invoke os.shell.run with cmd: "pandoc". Outputs go to the
session working directory; the approval gate surfaces each write.
| Goal |
args |
| Markdown → DOCX |
["notes.md", "-o", "notes.docx"] |
| Markdown → PDF |
["notes.md", "-o", "notes.pdf", "--pdf-engine=tectonic"] |
| Markdown → standalone HTML |
["notes.md", "-s", "-o", "notes.html"] |
| DOCX → Markdown |
["report.docx", "-o", "report.md"] |
| HTML → Markdown |
["page.html", "-f", "html", "-t", "gfm", "-o", "page.md"] |
| Many MD → one EPUB |
["ch1.md", "ch2.md", "-o", "book.epub", "--toc"] |
| With a table of contents |
append ["--toc", "--toc-depth=2"] |
Rules
- Always specify an explicit
-o <output> path and report it to the user.
- For PDF, prefer
--pdf-engine=tectonic if installed (fewer dependencies).
- Verify the output exists (e.g.
os.fs.list) before claiming success.
- Preserve the source file — pandoc writes a new file, never edit in place.
1---2name: pandoc3description: Convert documents between formats (Markdown, DOCX, HTML, PDF, RST, EPUB, LaTeX) via the `pandoc` CLI. Use to transform a document from one format to another.4---5
6# pandoc
7
8Convert documents between formats with the universal
9[`pandoc`](https://pandoc.org/) CLI. Input/output formats are inferred from file
10extensions; override with `-f <from>` / `-t <to>` when needed.
11
12PDF output requires a LaTeX engine (or `--pdf-engine`). Markdown/HTML/DOCX/EPUB
13conversions need only `pandoc` itself.
14
15## Setup health check (run first, every session)
16
17Verify with **one solo step**:
18
19```
20[{ "tool": "os.shell.run", "args": { "cmd": "pandoc", "args": ["--version"] } }]
21```
22
23Outcome map:
24- `exit 0` + version → ready, proceed.
25- `command not found: pandoc` → enter **Setup playbook → "pandoc missing"**.
26- PDF target fails with `pdflatex not found` → enter **Setup playbook → "PDF engine missing"**.
27
28## Setup playbook (when prerequisites are missing)
29
30### pandoc missing
31
32Reply (solo `reply` step):
33
34> "`pandoc` is not installed. I can install it: `brew install pandoc`. Install it?"
35
36On yes:
37
38```
39[{ "tool": "os.shell.run", "args": { "cmd": "brew", "args": ["install", "pandoc"] } }]
40```
41
42On Linux: `apt-get install pandoc`.
43
44On Windows, offer this exact winget command after confirmation:
45
46```
47[{ "tool": "os.shell.run", "args": { "cmd": "winget", "args": ["install", "--id", "JohnMacFarlane.Pandoc", "-e"] } }]
48```
49
50### PDF engine missing
51
52PDF output needs a TeX engine. Offer the lightweight option:
53
54> "PDF export needs a TeX engine. I can install: `brew install --cask basictex` (or the lightweight `brew install tectonic`). Which do you prefer?"
55
56`tectonic` is simplest (`pandoc in.md -o out.pdf --pdf-engine=tectonic`).
57
58## When to use
59
60- "Convert this Markdown to DOCX / PDF / HTML", "turn this HTML into Markdown".
61- "Make an EPUB from these chapters", "export notes to a Word doc".
62
63## When NOT to use
64
65- Reading a document's text — use `os.fs.read_document`.
66- Editing PDFs structurally (merge/split) — use the `pdf` skill.
67- Spreadsheet conversion — use the `xlsx` skill.
68
69## Common operations
70
71All examples invoke `os.shell.run` with `cmd: "pandoc"`. Outputs go to the
72session working directory; the approval gate surfaces each write.
73
74| Goal | args |
75|---|---|
76| Markdown → DOCX | `["notes.md", "-o", "notes.docx"]` |
77| Markdown → PDF | `["notes.md", "-o", "notes.pdf", "--pdf-engine=tectonic"]` |
78| Markdown → standalone HTML | `["notes.md", "-s", "-o", "notes.html"]` |
79| DOCX → Markdown | `["report.docx", "-o", "report.md"]` |
80| HTML → Markdown | `["page.html", "-f", "html", "-t", "gfm", "-o", "page.md"]` |
81| Many MD → one EPUB | `["ch1.md", "ch2.md", "-o", "book.epub", "--toc"]` |
82| With a table of contents | append `["--toc", "--toc-depth=2"]` |
83
84## Rules
85
861. Always specify an explicit `-o <output>` path and report it to the user.
872. For PDF, prefer `--pdf-engine=tectonic` if installed (fewer dependencies).
883. Verify the output exists (e.g. `os.fs.list`) before claiming success.
894. Preserve the source file — pandoc writes a new file, never edit in place.
gabrielmoreira