# 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
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>$title$</title>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <header>
    <h1>$title$</h1>
    <p>$author$ · $date$</p>
  </header>
  <main>$body$</main>
</body>
</html>
```

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