mirror of
https://github.com/Kaffesky/kaffesky-markdown-templates.git
synced 2026-04-18 12:17:31 +02:00
Update pandoc README
This commit is contained in:
jostein
parent
37ba3383ba
commit
9df9fb9385
1 changed files with 535 additions and 0 deletions
535
convertion_templates_pandoc/README.md
Normal file
535
convertion_templates_pandoc/README.md
Normal file
|
|
@ -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.
|
||||||
Loading…
Add table
Add a link
Reference in a new issue