Kaffesky/kaffesky-markdown-templates
3
0
Fork 0
mirror of https://github.com/Kaffesky/kaffesky-markdown-templates.git synced 2026-04-18 10:37:30 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions
kaffesky-markdown-templates/convertion_templates_pandoc
History
jostein 9cee929317 updates
2026-03-26 22:59:09 +01:00
..
template_OpenDocument Update with examples 2026-03-26 16:11:31 +01:00
template_pdf-via-xelatex updates 2026-03-26 22:59:09 +01:00
lorem_ipsum_via_OpenDocument_first-example.odt Update with examples 2026-03-26 16:11:31 +01:00
lorem_ipsum_via_OpenDocument_first-example.pdf Update with examples 2026-03-26 16:11:31 +01:00
README.md Update pandoc README 2026-03-26 10:51:36 +01:00

README.md

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)
  2. The Pandoc Project
  3. Templates as a Presentation Layer
  4. Path 1 — PDF via LaTeX Templates
  5. Path 2 — Microsoft Word Templates (DOCX)
  6. Path 3 — LibreOffice Templates (ODT)
  7. Path 4 — Web and HTML Output
  8. Path 5 — EPUB and E-books
  9. Path 6 — Adobe InDesign via ICML
  10. Path 7 — Scribus via Intermediate Formats
  11. Designing Templates Without Writing Code
  12. Choosing the Right Output Format
  13. The Workflow in Practice
  14. Key Resources and Documentation

What Pandoc Is (and Is Not)

Pandoc 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 — and transforms it into another format: PDF, Word, LibreOffice, HTML, 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, a philosopher and computer scientist at UC 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 and is free, open-source software released under the GPL-2.0 license. The source code is maintained at 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 superset that extends CommonMark 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 (Citation Style Language) and .bib bibliography files
  • Definition lists, line blocks, and raw LaTeX/HTML blocks
  • Math via MathJax 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.

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, though Typst and WeasyPrint are also supported as alternative PDF engines.

Markdown → LaTeX → PDF

LaTeX is not a word processor. It is a layout engine built on Donald Knuth's 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 — the standard distribution for Linux and Windows
  • MacTeX — the macOS packaging of TeX Live
  • MiKTeX — an alternative Windows distribution that installs packages on demand

The recommended PDF engine for Unicode text and custom fonts is XeLaTeX.

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

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. Notable options include:

  • Eisvogel — a polished, general-purpose LaTeX template widely used for professional documents
  • pandoc-scholar — designed for academic papers
  • Tufte-Pandoc — inspired by Edward Tufte's book design

Path 2 — Microsoft Word Templates (DOCX)

Pandoc maps Markdown structure to Word styles, 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

pandoc --print-default-data-file reference.docx > my-template.docx

Design in Word

Open my-template.docx in Microsoft Word and modify the named styles: Heading 1, Heading 2, Normal, page layout, margins, fonts. Save the file.

Use the Template

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 format. LibreOffice and its predecessor OpenOffice 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, making it the most future-proof of the word-processor output formats.

Create Template

pandoc --print-default-data-file reference.odt > my-template.odt

Design in LibreOffice

Open the file in LibreOffice Writer and use the Styles panel (F11) to modify Headings, Body Text, Page styles, and Lists. Save the file.

Use Template

pandoc document.md \
  --reference-doc=my-template.odt \
  -o document.odt

Path 4 — Web and HTML Output

Pandoc produces clean, standards-compliant HTML and integrates naturally with web publishing workflows.

Standalone HTML Page

pandoc document.md \
  --standalone \
  --css=style.css \
  -o document.html

Self-Contained HTML

Embeds all CSS and images inline — a single portable file:

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:

<!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>

pandoc document.md \
  --standalone \
  --template=template.html \
  -o document.html

Static Site Generators

Pandoc integrates directly with Hugo, Jekyll, and similar tools:

pandoc document.md \
  --to=markdown \
  --standalone \
  -o content/posts/document.md

Path 5 — EPUB and E-books

Pandoc can produce 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, Kobo, Adobe Digital Editions, and many others.

pandoc document.md -o document.epub

With a cover image and stylesheet:

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:

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 — the InCopy Markup Language used by Adobe InDesign.

This is one of Pandoc's most powerful and least-known output paths.

What ICML Is

ICML 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

pandoc document.md -o document.icml

Importing into InDesign

  1. In Adobe InDesign, 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 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, 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.

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:

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

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

LaTeX and PDF

Word Processing Formats

Professional Publishing

Citations and Bibliography

Markdown

Write in plain text. Apply design at the edges. Preserve your content forever.