kaffesky-markdown-templates/README.md

# Markdown, Git, and the Art of Writing That Lasts

> *Plain text is the most durable file format ever invented. This repository is built around that idea.*

---

## Table of Contents

1. [What is Markdown?](#what-is-markdown)
2. [Markdown as a Writing System](#markdown-as-a-writing-system)
3. [Writing with AI — Markdown at the Core](#writing-with-ai--markdown-at-the-core)
4. [Why Markdown and Git Are Exceptionally Powerful Together](#why-markdown-and-git-are-exceptionally-powerful-together)
5. [Conversion Path 1 — iA Writer](#conversion-path-1--ia-writer)
6. [Conversion Path 2 — Pandoc](#conversion-path-2--pandoc)
7. [Choosing Your Path](#choosing-your-path)
8. [This Repository](#this-repository)

---

## What is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004 with a single governing principle: a plain text file should be readable as-is, without needing to be rendered or compiled first. The syntax was designed to look like the conventions people were already using in email and plain text documents.

A heading is written with a `#`. Emphasis is wrapped in `*asterisks*`. A list item starts with a `-`. That is nearly all you need to know to write a properly structured document.

```markdown
# The Title of My Document

This is an introductory paragraph. It is just text.

## A Section Heading

Here is a **bold** word and an *italic* one. Below is a list:

- First item
- Second item
- Third item

And a [link to something](https://example.com).
```

The raw file above is completely legible. It communicates its own structure without a single application being open. This is the defining quality of Markdown, and the reason it has quietly become the dominant format for technical writing, documentation, note-taking, and increasingly, all serious long-form writing.

### The Markdown Family

Several extended variants exist, each adding features for specific use cases:

| Variant | Adds | Common use |
|---|---|---|
| **CommonMark** | Strict, unambiguous specification | Baseline interoperability |
| **GitHub Flavored Markdown (GFM)** | Tables, task lists, strikethrough | GitHub, GitLab, documentation |
| **MultiMarkdown (MMD)** | Footnotes, metadata, citations, math | Academic and long-form writing |
| **Pandoc Markdown** | All of the above + definition lists, raw LaTeX/HTML blocks, advanced tables | Scholarly and professional documents |
| **MDX** | JSX components inside Markdown | Modern web development |

For most writing purposes, CommonMark plus GFM extensions is the right starting point. For academic or book-length work, Pandoc Markdown is the most capable superset.

---

## Markdown as a Writing System

Most document formats mix content and presentation into a single file. A `.docx` file is a zip archive containing dozens of XML files, embedded fonts, relationship graphs, and binary blobs. Opening it requires Microsoft Word or a compatible application. If that application does not exist, the file is opaque. If the format changes, old files break.

Markdown separates these concerns cleanly:

- **Content** lives in the `.md` file — pure text, fully readable by any editor on any system
- **Presentation** is handled by stylesheets, templates, or export tools — applied at the moment you need a rendered output

This separation is not merely a technical nicety. It changes how you write. When your editor shows you nothing but words, you think about words. The temptation to fiddle with spacing, fonts, and bullet styles — which consumes enormous time in word processors — simply does not exist.

### Structure Without Distraction

Markdown provides exactly the structural elements most documents need:

- **Six heading levels** — enough hierarchy for any document
- **Paragraphs, lists, blockquotes** — the basic units of prose
- **Code blocks** — first-class support for technical content
- **Tables** — for data that needs tabular presentation
- **Footnotes and citations** (in extended variants) — for academic rigour
- **Metadata blocks** — title, author, date, and custom fields in YAML front matter

```yaml
---
title: "Annual Strategy Review"
author: "Emma Lindqvist"
date: "March 2026"
abstract: "An assessment of strategic priorities for the coming year."
---

# Executive Summary

...
```

This metadata travels with the document and can be picked up by any conversion tool to populate templates, generate title pages, or fill headers and footers automatically.

### Portability Across Time and Tools

A Markdown file written in 2004 opens perfectly in 2026. It will open in 2050. It requires no licence, no subscription, no application — just any text editor, including the simplest ones. This is not a minor point. Organisations routinely discover that documents written five years ago in a proprietary format are effectively lost because the software that created them no longer runs.

Plain text does not have this problem. It is, by definition, future-proof.

---

## Writing with AI — Markdown at the Core

Large language models are text generators. Their native output is unformatted prose. But they are also excellent at producing structured Markdown, and this has significant implications for any writing workflow that involves AI assistance.

### AI Output is Already Structured

When you ask a well-prompted AI model to produce a document, report, proposal, or article, the natural output format is Markdown. Headings, lists, bold terms, code blocks — all of these map directly to Markdown syntax. The AI does not need to understand InDesign paragraph styles or Word heading levels. It produces logical structure in text, and Markdown captures that structure precisely.

The implication is that AI-assisted writing fits most naturally into a Markdown-first workflow:

```
Prompt AI → Receive Markdown → Edit in plain text editor → Commit to Git → Export on demand
```

At no point in this chain does a proprietary format touch your content. You remain in complete control of the source material at every stage.

### Human Writing and AI Writing Are the Same Format

One of the most practical benefits of a Markdown-centred workflow is that text written by a human author and text generated or revised by an AI model are stored in exactly the same format. You can mix them freely in the same file, the same repository, the same commit history.

This is not true of, say, a Word document passed back and forth with tracked changes. The format itself introduces friction — version conflicts, compatibility problems, lost formatting. A plain text file simply does not have these problems.

### Prompting Strategies for Clean Markdown Output

When working with AI to produce documents, a few practices significantly improve the quality and consistency of the output:

**Specify the format explicitly.** Ask for Markdown, name the heading levels you want, specify whether you want front matter.

```
Write this as a Markdown document with YAML front matter containing title, 
author, and date. Use ## for section headings and ### for subsections. 
Do not use bold for decoration — only for genuinely critical terms.
```

**Work iteratively on the source file.** Draft with AI, then open the `.md` file and edit directly. Do not pass rendered outputs back into the AI — always work from the source.

**Keep one document per file.** Short, focused files version better than long monolithic ones. A report with five sections works well as five `.md` files in a folder, assembled by a conversion tool at export time.

**Use metadata to drive templates.** Put title, author, abstract, and keywords in YAML front matter. A well-configured conversion pipeline will use these fields to populate a title page, running headers, and document metadata automatically — no manual entry required.

---

## Why Markdown and Git Are Exceptionally Powerful Together

Git was designed for source code. But source code is text. And Markdown is text. This means every capability Git provides for software development applies, without modification, to a writing project.

This is more significant than it first appears.

### Line-by-Line Version History

Every change to a Markdown file is tracked at the character level. You can see exactly which sentence was added, which paragraph was rewritten, which word was changed — and by whom, and when, and in the context of every other change made at the same time.

```bash
git log --oneline
```
```
a3f82c1  Revise executive summary for clarity
7e1c904  Add methodology section, first draft
3b209d0  Initial document structure and outline
```

```bash
git diff 3b209d0..a3f82c1 -- strategy-review.md
```

This produces a precise, human-readable diff of every change between those two commits. No word processor offers anything close to this level of auditability.

With a binary format like `.docx`, `git diff` produces meaningless binary output. With Markdown, every diff is immediately readable prose.

### Branching for Structural Exploration

Git branches allow you to explore a structural alternative — a different argument order, an alternative introduction, a rewritten conclusion — without touching the main document. If the experiment works, you merge it. If it does not, you discard the branch with no residue.

```bash
git checkout -b rewrite/introduction
# ... edit freely ...
git checkout main
git merge rewrite/introduction   # if it worked
git branch -d rewrite/introduction   # clean up
```

This workflow is genuinely useful for any document that goes through serious revision. It lets a writer take risks with structure without anxiety about losing good work.

### Collaboration Without Conflicts

When multiple people work on a document stored as plain text in a Git repository, conflicts are rare and, when they occur, resolvable. Each person works in their own branch. Changes are reviewed as pull requests — which show exactly what was added, changed, or removed — before being merged.

Compare this to the alternative: emailing `.docx` files, managing `v1`, `v2`, `v2_FINAL`, `v2_FINAL_revised` naming conventions, and manually reconciling tracked changes from multiple reviewers. The Git model is simply better for collaborative writing, and Markdown is what makes it possible.

### Issues and Pull Requests as an Editorial System

A GitHub repository gives you a complete editorial workflow out of the box:

- **Issues** — track needed revisions, open questions, or structural problems
- **Pull requests** — propose and review specific changes to the text
- **Comments on diffs** — leave inline feedback on specific lines or paragraphs
- **Labels and milestones** — organise work by document section, priority, or deadline

This is a full editorial system built on the same infrastructure used to build the world's most complex software. It scales from a single writer working alone to a large team producing a multi-volume publication.

### Automation and CI/CD for Documents

Because the document lives in a repository, you can attach automation to it. A simple GitHub Actions workflow can:

- Build a PDF automatically every time a change is merged to `main`
- Publish an HTML version to a website on every commit
- Run a spell-checker or style linter as part of a pull request check
- Archive a dated PDF snapshot at each tagged release

```yaml
# .github/workflows/build-pdf.yml
name: Build PDF

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Pandoc and LaTeX
        run: sudo apt-get install -y pandoc texlive-xetex
      - name: Build PDF
        run: pandoc docs/main.md -o dist/document.pdf --pdf-engine=xelatex
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: document-pdf
          path: dist/document.pdf
```

The document becomes a living artefact — always up to date, always reproducible, always auditable.

---

## Conversion Path 1 — iA Writer

iA Writer is a focused writing application that uses Markdown natively. For writers who want a polished, typography-first PDF export without touching the command line, it is the most direct path.

The conversion model is: **Markdown → iA Writer template (HTML/CSS) → PDF or web preview.**

See [`README-iAWriter.md`](./README-iAWriter.md) in this repository for full documentation on iA Writer, template structure, the margin model, and how to install and develop custom templates.

### Markdown to PDF via iA Writer

1. Open your `.md` file in iA Writer
2. Go to **File → Export → PDF**
3. Select your template from the picker
4. Export

The template system gives you full typographic control through HTML and CSS. All document metadata in your YAML front matter (`title`, `author`, `date`) is automatically available in the template via `data-title`, `data-author`, and `data-date` attributes.

This repository includes `ExampleTemplate_CleanDoc` as a starting point — a Roboto-based A4 template with a title page, running header, and page-numbered footer.

### Markdown to Web via iA Writer

iA Writer's Preview pane renders your Markdown through the active template using the same HTML/CSS engine. For web output, the same template that drives your PDF export also drives your web preview — you write once and the styling applies to both contexts.

The template can include responsive CSS, dark mode support, and any web typography. The output is standard HTML rendered in a WebKit view.

---

## Conversion Path 2 — Pandoc

Pandoc is a universal document converter written by John MacFarlane, a philosopher and programmer at UC Berkeley. It is, without exaggeration, one of the most capable document transformation tools ever built. It understands over forty input formats and can produce over sixty output formats from a single source.

For a Markdown-first workflow, Pandoc is the production-grade conversion layer that handles everything iA Writer does not — particularly when the target is a word processor format, a typesetting system, or a highly customised PDF.

Install Pandoc from [pandoc.org/installing.html](https://pandoc.org/installing.html). It is available on macOS (via Homebrew), Linux, and Windows.

```bash
brew install pandoc          # macOS
sudo apt-get install pandoc  # Debian/Ubuntu
```

### Pandoc Markdown

Pandoc uses its own Markdown superset that extends CommonMark with features specifically useful for serious documents:

```markdown
---
title: "Document Title"
author: "Author Name"
date: "2026-03-26"
abstract: |
  A short abstract that will appear on the title page.
bibliography: references.bib
csl: chicago-author-date.csl
---

This is body text with a footnote.[^1]

[^1]: This is the footnote text.

| Column A | Column B | Column C |
|----------|----------|----------|
| Value 1  | Value 2  | Value 3  |

: Table caption goes here {#tbl:example}
```

---

### Markdown to PDF

Pandoc converts Markdown to PDF by first converting it to LaTeX, then compiling the LaTeX to PDF. This gives you access to the full power of the TeX typesetting system — arguably the highest-quality document typesetting available anywhere.

You need a LaTeX distribution installed: [TeX Live](https://tug.org/texlive/) on Linux/Windows or [MacTeX](https://www.tug.org/mactex/) on macOS. Alternatively, use `--pdf-engine=weasyprint` or `--pdf-engine=typst` to avoid LaTeX entirely.

**Basic PDF export:**

```bash
pandoc document.md -o document.pdf
```

**With a custom LaTeX template and metadata:**

```bash
pandoc document.md \
  --pdf-engine=xelatex \
  --template=my-template.tex \
  --variable=mainfont:"Roboto" \
  --variable=fontsize:11pt \
  --variable=geometry:"a4paper, margin=25mm" \
  --table-of-contents \
  -o document.pdf
```

**Multiple input files combined into one PDF:**

```bash
pandoc introduction.md methods.md results.md conclusion.md \
  --pdf-engine=xelatex \
  -o full-report.pdf
```

**With a bibliography:**

```bash
pandoc document.md \
  --bibliography=references.bib \
  --csl=apa.csl \
  --pdf-engine=xelatex \
  -o document.pdf
```

The `--csl` flag accepts any Citation Style Language file — there are thousands available at [zotero.org/styles](https://www.zotero.org/styles), covering every academic citation style.

For templates, the Pandoc community maintains a large collection at [github.com/jgm/pandoc/wiki/User-contributed-templates](https://github.com/jgm/pandoc/wiki/User-contributed-templates). The Eisvogel template is particularly polished for general documents.

---

### Markdown to Web

Pandoc can produce self-contained HTML files, Hugo/Jekyll-compatible pages, or full static sites.

**Standalone HTML page:**

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

**Self-contained HTML (CSS and images embedded inline):**

```bash
pandoc document.md \
  --standalone \
  --embed-resources \
  --css=style.css \
  -o document.html
```

**With a custom HTML template:**

Pandoc's HTML templates use its own template language. Create a `template.html` and reference variables with `$title$`, `$author$`, `$body$`:

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

**For a static site generator (Hugo):**

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

Pandoc can also output EPUB directly, making it straightforward to produce e-books from the same Markdown source.

---

### Markdown to Word Processor Formats

When you need to deliver a document in a format that non-technical collaborators can open and edit, Pandoc produces both `.docx` (Microsoft Word) and `.odt` (LibreOffice / OpenDocument) from the same Markdown source.

#### DOCX (Microsoft Word)

```bash
pandoc document.md -o document.docx
```

**With a reference document (the key to controlling styles):**

The most important feature of Pandoc's DOCX export is the `--reference-doc` flag. Pandoc maps its internal document structure to Word styles. By providing a Word document that contains those styles with your own formatting, you get complete typographic control.

```bash
# First, extract Pandoc's default reference document
pandoc --print-default-data-file reference.docx > my-reference.docx

# Open my-reference.docx in Word, modify the styles (Heading 1, Body Text, etc.)
# Then use it as the reference for all future exports

pandoc document.md \
  --reference-doc=my-reference.docx \
  -o document.docx
```

The heading levels in Markdown (`#`, `##`, `###`) map to Word's `Heading 1`, `Heading 2`, `Heading 3` styles. Body text maps to the `Normal` style. Code blocks map to `Verbatim`. By styling these in your reference document, you control the entire typographic output.

#### ODT (LibreOffice / OpenDocument)

The same principle applies for ODT:

```bash
pandoc document.md -o document.odt
```

```bash
# With a reference ODT
pandoc --print-default-data-file reference.odt > my-reference.odt
# Open in LibreOffice, modify styles, save, then:
pandoc document.md \
  --reference-doc=my-reference.odt \
  -o document.odt
```

ODT is the better choice for workflows where the document will be edited in LibreOffice, as the style mapping is cleaner. Both formats support tables, footnotes, images, and lists.

---

### Markdown to Professional Publishing Systems

For documents that need to go into a professional typesetting environment — whether for commercial print, publication design, or high-quality book production — Pandoc offers export paths to both InDesign and Scribus.

#### Adobe InDesign via ICML

InDesign can import ICML (InCopy Markup Language) files directly as a structured story. This gives a designer a fully tagged, styled text flow that maps directly onto InDesign paragraph and character styles.

```bash
pandoc document.md -o document.icml
```

The resulting `.icml` file can be placed into an InDesign layout via **File → Place** exactly as you would place any other file. InDesign reads the structural tags and applies whatever paragraph styles you have defined in your document.

**Workflow:**

1. Write content in Markdown
2. Export to ICML with Pandoc
3. Open InDesign; define paragraph styles matching Pandoc's tags (`Heading 1`, `Heading 2`, `Para`, `VerbatimChunk`, `BlockQuote`, and so on)
4. Place the `.icml` file into your layout
5. InDesign applies your styles automatically

When the content changes, re-export the ICML and re-place the file — InDesign updates the linked story. This is a fully round-trippable workflow for text-heavy publications.

The Pandoc-generated ICML uses these standard paragraph style names:

| Markdown element | InDesign paragraph style |
|---|---|
| `# Heading 1` | `Heading 1` |
| `## Heading 2` | `Heading 2` |
| Body paragraph | `Para` or `BodyText` |
| Code block | `VerbatimChunk` |
| Blockquote | `BlockQuote` |
| List item | `BulletList` |

#### Scribus via XML

Scribus is a professional open-source page layout application that reads SLA (Scribus document format) and can import XML structured text. The most practical Pandoc path to Scribus is via an intermediate format.

**Path 1 — via ODT:**
Export to ODT and import into Scribus using the **Get Text** function with the OpenDocument importer. Scribus reads ODT paragraph styles and maps them onto its own character and paragraph styles.

```bash
pandoc document.md -o document.odt
# Then in Scribus: File → Import → Get Text → select document.odt
```

**Path 2 — via HTML:**
Export to a clean, semantically structured HTML file and import into a Scribus text frame using its HTML import capability.

```bash
pandoc document.md \
  --standalone \
  --template=scribus-import.html \
  -o document.html
# Then in Scribus: right-click text frame → Get Text → select document.html
```

**Path 3 — via LaTeX:**
For complex scientific or mathematical documents, export to LaTeX first and use a LaTeX-to-Scribus bridge, or use a Pandoc LaTeX template tuned to produce clean output that can be directly typeset.

```bash
pandoc document.md --standalone -o document.tex
```

The ODT path is the most reliable for general prose documents. For highly structured publications or those with complex tables and figures, the HTML path gives you the most control over how Scribus receives the content.

---

## Choosing Your Path

| Need | Best tool |
|---|---|
| Polished PDF with custom typography, quick setup | iA Writer + template |
| PDF with citations, footnotes, and a LaTeX-quality layout | Pandoc → PDF via XeLaTeX |
| Deliver to a Word user | Pandoc → DOCX with reference doc |
| Deliver to a LibreOffice user | Pandoc → ODT with reference doc |
| Web publication | Pandoc → HTML, or iA Writer preview |
| Hand off to an InDesign designer | Pandoc → ICML |
| Hand off to a Scribus layout | Pandoc → ODT, then import |
| EPUB / e-book | Pandoc → EPUB |
| Automated CI/CD document builds | Pandoc in a GitHub Actions workflow |

The two paths are not mutually exclusive. A practical setup uses iA Writer for daily writing and preview, and Pandoc for production exports to specific formats. The Markdown source is always the same file.

---

## This Repository

This repository contains:

- **`ExampleTemplate_CleanDoc.iatemplate`** — an iA Writer template for A4 PDF export with Roboto typography, title page, running header, and page-numbered footer
- **`README-iAWriter.md`** — full documentation on iA Writer's template system: bundle structure, `Info.plist` reference, `data-*` content injection, the margin model, night mode, and the development workflow
- **`README.md`** — this document

Contributions, corrections, and additional templates are welcome via pull request.