Update pandoc README

2026-04-18 12:47:31 +02:00 · 2026-03-26 10:51:36 +01:00 · 2026-03-26 10:51:36 +01:00 · 9df9fb9385
commit 9df9fb9385
parent 37ba3383ba
1 changed files with 535 additions and 0 deletions
--- a/convertion_templates_pandoc/README.md
+++ b/convertion_templates_pandoc/README.md
@ -0,0 +1,535 @@
+# 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.