# Pandoc Templates and the Separation of Writing from Design > *Write once in plain text. Render everywhere with intention.* --- ## Table of Contents 1. [What Pandoc Is (and Is Not)](#what-pandoc-is-and-is-not) 2. [The Pandoc Project](#the-pandoc-project) 3. [Templates as a Presentation Layer](#templates-as-a-presentation-layer) 4. [Path 1 — PDF via LaTeX Templates](#path-1--pdf-via-latex-templates) 5. [Path 2 — Microsoft Word Templates (DOCX)](#path-2--microsoft-word-templates-docx) 6. [Path 3 — LibreOffice Templates (ODT)](#path-3--libreoffice-templates-odt) 7. [Path 4 — Web and HTML Output](#path-4--web-and-html-output) 8. [Path 5 — EPUB and E-books](#path-5--epub-and-e-books) 9. [Path 6 — Adobe InDesign via ICML](#path-6--adobe-indesign-via-icml) 10. [Path 7 — Scribus via Intermediate Formats](#path-7--scribus-via-intermediate-formats) 11. [Designing Templates Without Writing Code](#designing-templates-without-writing-code) 12. [Choosing the Right Output Format](#choosing-the-right-output-format) 13. [The Workflow in Practice](#the-workflow-in-practice) 14. [Key Resources and Documentation](#key-resources-and-documentation) --- ## What Pandoc Is (and Is Not) [Pandoc](https://pandoc.org) is not a writing tool. It does not replace your editor. It does not manage your documents. It does not impose structure. Pandoc is a **conversion engine**. It takes structured input — in our case, [Markdown](https://en.wikipedia.org/wiki/Markdown) — and transforms it into another format: [PDF](https://en.wikipedia.org/wiki/PDF), [Word](https://en.wikipedia.org/wiki/Microsoft_Word), [LibreOffice](https://en.wikipedia.org/wiki/LibreOffice), [HTML](https://en.wikipedia.org/wiki/HTML), [EPUB](https://en.wikipedia.org/wiki/EPUB), and many more. Pandoc understands over forty input formats and can produce over sixty output formats from a single source. ``` Markdown (source of truth) → Pandoc → Output format ``` This distinction matters. You **write in Markdown**, where content is clean, readable, and versionable. You **design in templates**, where presentation is defined. Pandoc sits between them and connects the two. --- ## The Pandoc Project Pandoc was created by [John MacFarlane](https://johnmacfarlane.net), a philosopher and computer scientist at [UC Berkeley](https://en.wikipedia.org/wiki/University_of_California,_Berkeley). He began the project around 2006 to solve a practical problem: moving documents between formats without losing structure. What started as a personal utility became one of the most widely used document processing tools in academic, technical, and publishing workflows worldwide. The project is written in [Haskell](https://en.wikipedia.org/wiki/Haskell_(programming_language)) and is free, open-source software released under the [GPL-2.0 license](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html). The source code is maintained at [github.com/jgm/pandoc](https://github.com/jgm/pandoc). ### What Makes Pandoc Distinctive Most document converters operate between two specific formats. Pandoc's architecture is different: it converts every supported input format into an internal abstract syntax tree (AST), then renders that AST to any supported output format. This means a new input format needs only one parser, and a new output format needs only one writer — the combination space grows automatically. This design gives Pandoc a capability no other tool matches: **a single source document can be rendered to dozens of formats without modification.** ### Pandoc Markdown Beyond conversion, Pandoc defines its own [Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown) superset that extends [CommonMark](https://commonmark.org) with features specifically designed for serious documents: - **YAML front matter** — title, author, date, abstract, bibliography, and custom variables - **Footnotes and endnotes** - **Citation processing** via [CSL](https://citationstyles.org) (Citation Style Language) and `.bib` bibliography files - **Definition lists, line blocks, and raw LaTeX/HTML blocks** - **Math** via [MathJax](https://www.mathjax.org) or LaTeX - **Advanced table syntax** For academic, book-length, or technically demanding documents, Pandoc Markdown is the most capable plain-text writing format available. ### Installation Pandoc is available on all major platforms. Full installation instructions are at [pandoc.org/installing.html](https://pandoc.org/installing.html). ```bash brew install pandoc # macOS via Homebrew sudo apt-get install pandoc # Debian / Ubuntu winget install JohnMacFarlane.Pandoc # Windows ``` --- ## Templates as a Presentation Layer In this workflow, templates are not optional decoration — they are the entire presentation system. They define: - Typography (fonts, sizes, spacing) - Page layout (margins, columns, headers, footers) - Structural styling (headings, lists, quotes, code blocks) - Title pages and metadata rendering The key idea is simple: > **Your Markdown never contains visual formatting.** A `# Heading` is not "16pt bold text." It is a semantic element that *becomes* 16pt bold text (or something else entirely) depending on the template. Pandoc enforces that separation consistently across every output format it supports. --- ## Path 1 — PDF via LaTeX Templates When Pandoc produces a PDF, it does so through a typesetting system — most commonly [LaTeX](https://en.wikipedia.org/wiki/LaTeX), though [Typst](https://typst.app) and [WeasyPrint](https://weasyprint.org) are also supported as alternative PDF engines. ``` Markdown → LaTeX → PDF ``` [LaTeX](https://www.latex-project.org) is not a word processor. It is a **layout engine** built on [Donald Knuth's](https://en.wikipedia.org/wiki/Donald_Knuth) [TeX](https://en.wikipedia.org/wiki/TeX) system, and an extremely powerful one. The output quality — particularly for mathematics, academic documents, and complex typography — is unmatched by any other tool in this space. To use the LaTeX PDF path, you need a TeX distribution installed on your system: - **[TeX Live](https://tug.org/texlive/)** — the standard distribution for Linux and Windows - **[MacTeX](https://www.tug.org/mactex/)** — the macOS packaging of TeX Live - **[MiKTeX](https://miktex.org)** — an alternative Windows distribution that installs packages on demand The recommended PDF engine for Unicode text and custom fonts is [XeLaTeX](https://en.wikipedia.org/wiki/XeTeX). ### What the Template Controls A LaTeX template defines: - Page size and margins - Font families and typographic hierarchy - Line spacing and paragraph rhythm - Header and footer content - Title page layout - Table of contents styling ### Using a Template ```bash pandoc document.md \ --pdf-engine=xelatex \ --template=template.tex \ -o document.pdf ``` ### Community Templates The Pandoc community maintains a large collection of user-contributed templates at [github.com/jgm/pandoc/wiki/User-contributed-templates](https://github.com/jgm/pandoc/wiki/User-contributed-templates). Notable options include: - **[Eisvogel](https://github.com/Wandmalfarbe/pandoc-latex-template)** — a polished, general-purpose LaTeX template widely used for professional documents - **[pandoc-scholar](https://github.com/pandoc-scholar/pandoc-scholar)** — designed for academic papers - **[Tufte-Pandoc](https://github.com/jez/tufte-pandoc-css)** — inspired by Edward Tufte's book design --- ## Path 2 — Microsoft Word Templates (DOCX) Pandoc maps Markdown structure to **[Word styles](https://support.microsoft.com/en-us/office/customize-or-create-new-styles-d38d6e47-f6fc-48eb-a607-1eb120dec563)**, not to raw formatting. This is the correct mental model for understanding DOCX output. ``` Markdown structure → Word styles → Visual formatting ``` ### How the Mapping Works | Markdown element | Word style | |---|---| | `# Heading 1` | Heading 1 | | `## Heading 2` | Heading 2 | | Body paragraph | Normal | | `` ```code``` `` | Verbatim | | `> Blockquote` | Block Text | By controlling these styles in a reference document, you control the entire typographic output — without touching the Markdown source. ### Create a Reference Document ```bash pandoc --print-default-data-file reference.docx > my-template.docx ``` ### Design in Word Open `my-template.docx` in [Microsoft Word](https://www.microsoft.com/en-us/microsoft-365/word) and modify the named styles: Heading 1, Heading 2, Normal, page layout, margins, fonts. Save the file. ### Use the Template ```bash pandoc document.md \ --reference-doc=my-template.docx \ -o document.docx ``` Every future export from the same Markdown source will inherit the styles you defined. --- ## Path 3 — LibreOffice Templates (ODT) The same principle as Word, applied to the [OpenDocument](https://en.wikipedia.org/wiki/OpenDocument) format. [LibreOffice](https://www.libreoffice.org) and its predecessor [OpenOffice](https://www.openoffice.org) use ODT as their native format, and it is a better choice than DOCX whenever the document will be worked on in LibreOffice — the style mapping is cleaner and more predictable. ``` Markdown → ODT styles → Visual formatting ``` ODT is also a fully open, standardised format specified by [OASIS](https://en.wikipedia.org/wiki/OASIS_(organization)), making it the most future-proof of the word-processor output formats. ### Create Template ```bash pandoc --print-default-data-file reference.odt > my-template.odt ``` ### Design in LibreOffice Open the file in [LibreOffice Writer](https://www.libreoffice.org/discover/writer/) and use the **Styles** panel (F11) to modify Headings, Body Text, Page styles, and Lists. Save the file. ### Use Template ```bash pandoc document.md \ --reference-doc=my-template.odt \ -o document.odt ``` --- ## Path 4 — Web and HTML Output Pandoc produces clean, standards-compliant [HTML](https://en.wikipedia.org/wiki/HTML) and integrates naturally with web publishing workflows. ### Standalone HTML Page ```bash pandoc document.md \ --standalone \ --css=style.css \ -o document.html ``` ### Self-Contained HTML Embeds all CSS and images inline — a single portable file: ```bash pandoc document.md \ --standalone \ --embed-resources \ --css=style.css \ -o document.html ``` ### With a Custom HTML Template Pandoc's template language uses `$variable$` syntax. A minimal template: ```html $title$

$title$

$author$ · $date$

$body$
``` ```bash pandoc document.md \ --standalone \ --template=template.html \ -o document.html ``` ### Static Site Generators Pandoc integrates directly with [Hugo](https://gohugo.io), [Jekyll](https://jekyllrb.com), and similar tools: ```bash pandoc document.md \ --to=markdown \ --standalone \ -o content/posts/document.md ``` --- ## Path 5 — EPUB and E-books Pandoc can produce [EPUB](https://en.wikipedia.org/wiki/EPUB) files directly from Markdown, making it a straightforward tool for e-book production. EPUB is the standard format for most e-reader devices and applications, supported by [Apple Books](https://www.apple.com/apple-books/), [Kobo](https://www.kobo.com), [Adobe Digital Editions](https://www.adobe.com/solutions/ebook/digital-editions.html), and many others. ```bash pandoc document.md -o document.epub ``` With a cover image and stylesheet: ```bash pandoc document.md \ --epub-cover-image=cover.jpg \ --css=epub-style.css \ -o document.epub ``` Multiple input files are assembled in order, making it easy to produce book-length works from chapter files: ```bash pandoc preface.md chapter-01.md chapter-02.md conclusion.md \ --epub-cover-image=cover.jpg \ -o book.epub ``` --- ## Path 6 — Adobe InDesign via ICML For documents destined for professional print or publication design, Pandoc can export directly to [ICML](https://en.wikipedia.org/wiki/InCopy) — the InCopy Markup Language used by [Adobe InDesign](https://en.wikipedia.org/wiki/Adobe_InDesign). This is one of Pandoc's most powerful and least-known output paths. ### What ICML Is [ICML](https://helpx.adobe.com/incopy/using/import-export-incopy.html) is an XML-based format that InDesign uses to represent a structured text story. It carries all paragraph and character style tags from the source document, which InDesign then maps to its own paragraph and character styles. The result is a fully linked, live story that a designer can place directly into a layout. ### Exporting to ICML ```bash pandoc document.md -o document.icml ``` ### Importing into InDesign 1. In [Adobe InDesign](https://www.adobe.com/products/indesign.html), open or create your layout document 2. Define paragraph styles matching Pandoc's tag names (see table below) 3. Go to **File → Place** and select the `.icml` file 4. InDesign places the story as a linked content flow and applies your paragraph styles automatically ### Style Name Mapping | Markdown element | InDesign paragraph style | |---|---| | `# Heading 1` | `Heading 1` | | `## Heading 2` | `Heading 2` | | `### Heading 3` | `Heading 3` | | Body paragraph | `Para` or `BodyText` | | Code block | `VerbatimChunk` | | Blockquote | `BlockQuote` | | List item | `BulletList` | ### Round-Trip Workflow When the content changes: 1. Edit the Markdown source 2. Re-export to ICML: `pandoc document.md -o document.icml` 3. In InDesign, InDesign detects that the linked story has changed and updates it automatically This makes it possible to maintain a **fully round-trippable workflow** between writers (working in plain text) and designers (working in InDesign), with no manual copy-pasting at any point in the process. ### When to Use This Path The ICML path is the right choice when: - The final output is a designed print publication (magazine, book, annual report, brochure) - A professional designer is responsible for layout, and writers need to deliver structured text - Content updates need to flow back into the layout without disrupting the design --- ## Path 7 — Scribus via Intermediate Formats [Scribus](https://www.scribus.net) is a professional open-source page layout application comparable in capability to InDesign. It is developed by a volunteer community and released under the [GPL](https://en.wikipedia.org/wiki/GNU_General_Public_License), making it the primary free alternative for publication design. Pandoc does not produce a native Scribus format, but there are reliable intermediate paths. ### Path 7a — via ODT (Recommended for General Prose) This is the most reliable path for text-heavy documents. Scribus can import ODT files directly, reading the paragraph styles defined in the document. ```bash pandoc document.md -o document.odt ``` In Scribus: 1. Create or open your Scribus layout (`.sla`) 2. Draw a text frame in your layout 3. Right-click the text frame → **Get Text** 4. Select `document.odt` and enable **Import Styles** 5. Scribus imports the text flow and maps LibreOffice paragraph styles to Scribus paragraph styles Define matching style names in Scribus beforehand (Heading 1, Heading 2, Body Text, and so on) for automatic style application on import. ### Path 7b — via HTML For more control over how Scribus receives the content, export to a clean, semantically structured HTML file: ```bash pandoc document.md \ --standalone \ -o document.html ``` In Scribus, right-click a text frame → **Get Text** → select `document.html`. Scribus applies basic structural mapping from HTML heading and paragraph tags. ### Path 7c — via LaTeX (for Scientific and Mathematical Documents) For documents with complex mathematics, export to [LaTeX](https://www.latex-project.org) first. You can then either use a LaTeX-to-Scribus bridge, or more practically, produce a high-quality PDF via LaTeX and use Scribus only for the surrounding layout and cover design. ```bash pandoc document.md --standalone -o document.tex ``` ### When to Use Scribus vs InDesign | Consideration | Scribus | InDesign | |---|---|---| | Cost | Free and open-source | Adobe Creative Cloud subscription | | Platform | Windows, macOS, Linux | Windows, macOS | | ICML import | Not supported | Native | | ODT import | Good | Requires plugin | | Community | Volunteer-maintained | Professional support | | Best for | Independent publishing, open workflows | Commercial publishing, agency work | --- ## Designing Templates Without Writing Code For LaTeX templates, working knowledge of LaTeX syntax is helpful but not required for basic modifications — many templates are designed to be configured via variables rather than edited directly. For DOCX and ODT templates, no code is involved at all. The design work happens inside Word or LibreOffice Writer, using the standard style editor: > **You are styling structure, not text.** Define the appearance of: - **Headings** (Heading 1, Heading 2, Heading 3) — size, weight, spacing, colour - **Body text** (Normal / Body Text) — font, size, line height - **Lists** (List Bullet, List Number) — indent, spacing - **Quotations** (Block Text) — indent, italic, rule - **Code** (Verbatim) — monospace font, background Keep it simple. Consistency matters more than flexibility. A template with five well-considered styles outperforms one with thirty inconsistent ones. --- ## Choosing the Right Output Format | Need | Best path | |---|---| | Print-quality PDF with full typographic control | LaTeX (XeLaTeX) | | PDF without installing LaTeX | Pandoc → Typst or WeasyPrint | | Deliver to a Word user | DOCX with reference document | | Deliver to a LibreOffice user | ODT with reference document | | Academic paper with citations and bibliography | LaTeX + CSL + `.bib` | | Web publication | HTML with CSS template | | Static site (Hugo, Jekyll) | Markdown passthrough | | EPUB / e-book | EPUB export | | Hand off to an InDesign designer | ICML | | Hand off to a Scribus layout | ODT, then import | | Automated CI/CD document builds | Pandoc in a GitHub Actions workflow | --- ## The Workflow in Practice ``` Write → Markdown (.md) Version → Git Render → Pandoc Style → Templates Output → PDF / DOCX / ODT / ICML / EPUB / HTML ``` Because the source is always a plain text file, the same document can be sent simultaneously to a word-processor user as a `.docx`, to a designer as an `.icml`, to a web server as `.html`, and to an archive as `.pdf` — all from a single `pandoc` invocation or a simple shell script. This is what it means to separate writing from design. --- ## Key Resources and Documentation ### Pandoc - **Official site:** [pandoc.org](https://pandoc.org) - **Full user manual:** [pandoc.org/MANUAL.html](https://pandoc.org/MANUAL.html) - **Installation guide:** [pandoc.org/installing.html](https://pandoc.org/installing.html) - **GitHub repository:** [github.com/jgm/pandoc](https://github.com/jgm/pandoc) - **Wikipedia article:** [en.wikipedia.org/wiki/Pandoc](https://en.wikipedia.org/wiki/Pandoc) - **User-contributed templates:** [github.com/jgm/pandoc/wiki/User-contributed-templates](https://github.com/jgm/pandoc/wiki/User-contributed-templates) - **Pandoc Discuss forum:** [github.com/jgm/pandoc/discussions](https://github.com/jgm/pandoc/discussions) ### LaTeX and PDF - **LaTeX Project:** [latex-project.org](https://www.latex-project.org) - **TeX Live:** [tug.org/texlive](https://tug.org/texlive/) - **MacTeX (macOS):** [tug.org/mactex](https://www.tug.org/mactex/) - **MiKTeX (Windows):** [miktex.org](https://miktex.org) - **Eisvogel template:** [github.com/Wandmalfarbe/pandoc-latex-template](https://github.com/Wandmalfarbe/pandoc-latex-template) - **Typst (LaTeX alternative):** [typst.app](https://typst.app) - **Wikipedia — LaTeX:** [en.wikipedia.org/wiki/LaTeX](https://en.wikipedia.org/wiki/LaTeX) ### Word Processing Formats - **Microsoft Word:** [microsoft.com/microsoft-365/word](https://www.microsoft.com/en-us/microsoft-365/word) - **LibreOffice:** [libreoffice.org](https://www.libreoffice.org) - **OpenDocument Format:** [en.wikipedia.org/wiki/OpenDocument](https://en.wikipedia.org/wiki/OpenDocument) ### Professional Publishing - **Adobe InDesign:** [adobe.com/products/indesign.html](https://www.adobe.com/products/indesign.html) - **InCopy / ICML documentation:** [helpx.adobe.com/incopy](https://helpx.adobe.com/incopy/using/import-export-incopy.html) - **Scribus:** [scribus.net](https://www.scribus.net) - **Wikipedia — Adobe InDesign:** [en.wikipedia.org/wiki/Adobe_InDesign](https://en.wikipedia.org/wiki/Adobe_InDesign) - **Wikipedia — Scribus:** [en.wikipedia.org/wiki/Scribus](https://en.wikipedia.org/wiki/Scribus) ### Citations and Bibliography - **Zotero CSL styles repository:** [zotero.org/styles](https://www.zotero.org/styles) - **Citation Style Language:** [citationstyles.org](https://citationstyles.org) - **BibTeX:** [en.wikipedia.org/wiki/BibTeX](https://en.wikipedia.org/wiki/BibTeX) ### Markdown - **CommonMark specification:** [commonmark.org](https://commonmark.org) - **Wikipedia — Markdown:** [en.wikipedia.org/wiki/Markdown](https://en.wikipedia.org/wiki/Markdown) - **GitHub Flavored Markdown:** [github.github.com/gfm](https://github.github.com/gfm/) --- > Write in plain text. Apply design at the edges. Preserve your content forever.