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.
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---56# pandoc78Convert documents between formats with the universal9[`pandoc`](https://pandoc.org/) CLI. Input/output formats are inferred from file10extensions; override with `-f <from>` / `-t <to>` when needed.1112PDF output requires a LaTeX engine (or `--pdf-engine`). Markdown/HTML/DOCX/EPUB13conversions need only `pandoc` itself.1415## Setup health check (run first, every session)1617Verify with **one solo step**:1819```20[{ "tool": "os.shell.run", "args": { "cmd": "pandoc", "args": ["--version"] } }]21```2223Outcome 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"**.2728## Setup playbook (when prerequisites are missing)2930### pandoc missing3132Reply (solo `reply` step):3334> "`pandoc` is not installed. I can install it: `brew install pandoc`. Install it?"3536On yes:3738```39[{ "tool": "os.shell.run", "args": { "cmd": "brew", "args": ["install", "pandoc"] } }]40```4142On Linux: `apt-get install pandoc`.4344### PDF engine missing4546PDF output needs a TeX engine. Offer the lightweight option:4748> "PDF export needs a TeX engine. I can install: `brew install --cask basictex` (or the lightweight `brew install tectonic`). Which do you prefer?"4950`tectonic` is simplest (`pandoc in.md -o out.pdf --pdf-engine=tectonic`).5152## When to use5354- "Convert this Markdown to DOCX / PDF / HTML", "turn this HTML into Markdown".55- "Make an EPUB from these chapters", "export notes to a Word doc".5657## When NOT to use5859- Reading a document's text — use `os.fs.read_document`.60- Editing PDFs structurally (merge/split) — use the `pdf` skill.61- Spreadsheet conversion — use the `xlsx` skill.6263## Common operations6465All examples invoke `os.shell.run` with `cmd: "pandoc"`. Outputs go to the66session working directory; the approval gate surfaces each write.6768| Goal | args |69|---|---|70| Markdown → DOCX | `["notes.md", "-o", "notes.docx"]` |71| Markdown → PDF | `["notes.md", "-o", "notes.pdf", "--pdf-engine=tectonic"]` |72| Markdown → standalone HTML | `["notes.md", "-s", "-o", "notes.html"]` |73| DOCX → Markdown | `["report.docx", "-o", "report.md"]` |74| HTML → Markdown | `["page.html", "-f", "html", "-t", "gfm", "-o", "page.md"]` |75| Many MD → one EPUB | `["ch1.md", "ch2.md", "-o", "book.epub", "--toc"]` |76| With a table of contents | append `["--toc", "--toc-depth=2"]` |7778## Rules79801. Always specify an explicit `-o <output>` path and report it to the user.812. For PDF, prefer `--pdf-engine=tectonic` if installed (fewer dependencies).823. Verify the output exists (e.g. `os.fs.list`) before claiming success.834. Preserve the source file — pandoc writes a new file, never edit in place.
AtomicBot-ai