kaffesky-markdown-templates/convertion_templates_iA-Writer/README.md

# iA Writer Templates — A Practical Guide

## What is iA Writer?

iA Writer is a focused writing application for macOS, iOS, iPadOS, and Windows, developed by the Swiss studio [Information Architects (iA)](https://ia.net). It strips away the visual clutter of traditional word processors to offer a distraction-free environment centred entirely on the text itself.

Its signature features include:

- **Focus Mode** — dims everything except the sentence or paragraph you are writing
- **Syntax Highlighting** — optionally colours adjectives, nouns, verbs, and adverbs to reveal writing patterns
- **Content Blocks** — embed and transclude other files directly into a document
- **MultiMarkdown support** — a superset of standard Markdown including tables, footnotes, and metadata
- **Templates** — export any document to a beautifully typeset PDF or printed page using custom HTML/CSS templates

iA Writer saves documents as plain `.md` or `.txt` files, which means your writing is never locked into a proprietary format.

---

## Relevant Documentation

| Resource | URL |
|---|---|
| Official template guide | https://ia.net/writer/templates |
| Template GitHub repository (iainc) | https://github.com/iainc/iA-Writer-Templates |
| MultiMarkdown syntax reference | https://fletcher.github.io/MultiMarkdown-6 |
| iA Writer support | https://ia.net/writer/support |
| Apple Bundle structure reference | https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFBundles/BundleTypes/BundleTypes.html |

---

## How Templates Work

iA Writer templates are **macOS/iOS bundles** — a directory with a specific internal structure that the operating system treats as a single file. The bundle contains HTML, CSS, and a property list (`Info.plist`) that tells iA Writer which pages exist and how tall the header and footer are.

When you export a document, iA Writer renders each HTML page in a headless WebKit view and composes the result into a PDF. You have full control over typography, layout, and colour through standard HTML and CSS.

---

## Bundle Structure

```
MyTemplate.iatemplate/
└── Contents/
    ├── Info.plist           ← Required. Declares all pages and settings.
    └── Resources/
        ├── document.html    ← Required. Lays out the document body text.
        ├── title.html       ← Optional. Cover/title page.
        ├── header.html      ← Optional. Repeating page header.
        ├── footer.html      ← Optional. Repeating page footer.
        └── style.css        ← Your stylesheet (shared across all pages).
```

The HTML filenames can be anything you like — you declare them in `Info.plist`. The file extensions must be `.html`; in `Info.plist` you reference them **without** the extension.

---

## Info.plist Reference

`Info.plist` is an Apple XML property list. Every key-value pair is wrapped in `<key>` and its corresponding type tag. Here is a complete annotated example:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>

  <!-- REQUIRED -------------------------------------------------- -->

  <!-- The name shown in iA Writer's template picker -->
  <key>CFBundleName</key>
  <string>My Template</string>

  <!-- Unique reverse-DNS identifier. iA Writer uses this to associate
       templates with documents. Change it if you fork a template. -->
  <key>CFBundleIdentifier</key>
  <string>com.yourname.mytemplate</string>

  <!-- HTML file (no extension) that lays out body text pages -->
  <key>IATemplateDocumentFile</key>
  <string>document</string>

  <!-- OPTIONAL -------------------------------------------------- -->

  <!-- Cover/title page HTML file -->
  <key>IATemplateTitleFile</key>
  <string>title</string>

  <!-- Running header HTML file + its height in CSS points (max 400) -->
  <key>IATemplateHeaderFile</key>
  <string>header</string>
  <key>IATemplateHeaderHeight</key>
  <integer>60</integer>

  <!-- Running footer HTML file + its height in CSS points (max 400) -->
  <key>IATemplateFooterFile</key>
  <string>footer</string>
  <key>IATemplateFooterHeight</key>
  <integer>50</integer>

  <!-- When false, title page gets zero header/footer height (full bleed) -->
  <key>IATemplateTitleUsesHeaderAndFooterHeight</key>
  <false/>

  <!-- Human-readable metadata shown in Preferences -->
  <key>IATemplateDescription</key>
  <string>A clean document template.</string>
  <key>IATemplateAuthor</key>
  <string>Your Name</string>
  <key>IATemplateAuthorURL</key>
  <string>https://yourwebsite.com</string>

  <!-- Set to false to disable Smart Tables processing -->
  <key>IATemplateSuportsSmartTables</key>
  <true/>

  <!-- Set to false to disable TeX math → MathML conversion -->
  <key>IATemplateSupportsMath</key>
  <true/>

</dict>
</plist>
```

> **Important:** The `CFBundleIdentifier` must be unique. If two installed templates share the same identifier, iA Writer will associate documents with whichever was installed last. Always change the identifier when forking a template.

---

## Content Injection — `data-*` Attributes

iA Writer populates your HTML pages by setting `innerHTML` on elements that carry specific `data` attributes. It dispatches an `ia-writer-change` event to each element after updating it.

### Available on all pages

| Attribute | Content |
|---|---|
| `data-title` | Document title (taken from the filename) |
| `data-author` | Author name set in iA Writer Preferences |
| `data-date` | Current date. Accepts a format string: `data-date="d MMMM yyyy"` |

### Document page only

| Attribute | Content |
|---|---|
| `data-document` | The full document body rendered as HTML |

### Header, footer, and title page

| Attribute | Content |
|---|---|
| `data-page-number` | Current page number (not available on title page) |
| `data-page-count` | Total page count |

### Usage in HTML

```html
<!-- Populate an element with the document title -->
<h1 data-title></h1>

<!-- Inject the full document body -->
<div data-document></div>

<!-- Page number out of total -->
<span data-page-number></span> / <span data-page-count></span>

<!-- Date with a custom format -->
<span data-date="MMMM yyyy"></span>
```

---

## Margin Model

This is the most important thing to understand before writing CSS, and the most common source of confusion.

**Left and right margins** are controlled purely by CSS — typically via `max-width` on the `body` or a container `div`, combined with `margin: 0 auto`.

**Top and bottom margins** on body pages are controlled by `IATemplateHeaderHeight` and `IATemplateFooterHeight` in `Info.plist`. CSS top/bottom padding on the `body` element of `document.html` does **not** create print margins in the same way — the header and footer zones sit above and below the document body zone, and their heights are what determines white space at the top and bottom of each page.

### A4 margin calculation

| Margin | Value | CSS pixels (96 dpi) |
|---|---|---|
| Top (= header height) | 25 mm | ~94 px |
| Bottom (= footer height) | 20 mm | ~75 px |
| Left/Right | 25 mm each | max-width ≈ 605–640 px |

A common working formula for A4 with 25mm margins:

```
A4 width = 210mm
Side margins = 25mm × 2 = 50mm
Text column = 160mm = 160 × (96 ÷ 25.4) ≈ 605px
```

```xml
<key>IATemplateHeaderHeight</key>
<integer>94</integer>

<key>IATemplateFooterHeight</key>
<integer>75</integer>
```

```css
body {
  max-width: 620px;
  margin: 0 auto;
}
```

---

## The Five HTML Pages

### `document.html` (required)

This page renders the Markdown body text. Keep it minimal — just import your stylesheet and place a single `data-document` element.

```html
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8" />
  <link rel="stylesheet" href="style.css" />
</head>
<body>
  <div data-document></div>
</body>
</html>
```

### `title.html` (optional)

The cover page, only rendered on export. Because `IATemplateTitleUsesHeaderAndFooterHeight` can be set to `false`, this page can go full-bleed. Use `min-height: 100vh` and flexbox to fill the page.

```html
<body style="display:flex; flex-direction:column; min-height:100vh; padding:15vh 10vw;">
  <h1 data-title></h1>
  <p data-author></p>
  <p data-date="d MMMM yyyy"></p>
</body>
```

### `header.html` and `footer.html` (optional)

These repeat on every body page. Their viewport height equals the value you set in `Info.plist`. Use flexbox to align content to the inner edge (the edge closest to the body text):

- **Header:** `align-items: flex-end` to pin content to the bottom of the header zone
- **Footer:** `align-items: flex-start` to pin content to the top of the footer zone

```html
<!-- footer.html -->
<body style="display:flex; align-items:flex-start; padding:8px 0 0;">
  <span data-page-number></span> / <span data-page-count></span>
</body>
```

---

## Night Mode & iOS Support

iA Writer adds CSS classes to the `<html>` element to signal the current environment. Use these to adapt your template:

```css
/* Dark mode */
html.night-mode {
  background: #1c1c1e;
  color: #f2f2f7;
}

/* Platform targeting */
html.mac  { /* macOS-specific overrides */ }
html.ios  { /* iOS/iPadOS overrides     */ }
```

iOS also supports Dynamic Type. iA Writer adds a content-size class to `<html>`:

```css
html.content-size-s  { font-size: 14px; }
html.content-size-l  { font-size: 17px; } /* default */
html.content-size-xl { font-size: 20px; }
```

---

## Installing a Template

### macOS
Double-click the `.iatemplate` bundle in Finder, or drag it onto the iA Writer icon in the Dock. You can also go to **Preferences → Templates → +**.

To inspect or edit an installed template: right-click it in Preferences and choose **Show in Finder**, then right-click the bundle and choose **Show Package Contents**.

### iOS / iPadOS
Send the `.iatemplate` file (or a `.zip` containing one template) via AirDrop, or use **Open in iA Writer** from Files, Mail, or Safari.

### Windows
Go to **File → Install Template** and select the `.iatemplate.zip` file.

---

## Development Workflow

1. Install the template in iA Writer once via Preferences.
2. Right-click it in Preferences → **Show in Finder** to locate the installed copy.
3. Edit the HTML/CSS files directly inside the installed bundle.
4. Press **⇧⌘R** in iA Writer's Preview pane to force-reload the template.
5. Enable Web Inspector for deeper debugging:

```bash
defaults write pro.writer.mac WebKitDeveloperExtras -bool true
```

Then right-click inside the Preview pane and choose **Inspect Element**.

---

## About ExampleTemplate_CleanDoc

`ExampleTemplate_CleanDoc` is the template included alongside this README. It demonstrates all five template pages with a Roboto type system, calibrated A4 margins, a structured title page, running header/footer with page numbers, and full night mode support.

| File | Purpose |
|---|---|
| `Info.plist` | Declares all five pages, sets header (60px) and footer (50px) heights |
| `style.css` | Shared design tokens, Roboto type scale, component styles, night mode |
| `document.html` | Body text page |
| `title.html` | Full-bleed cover page with accent bar, title, author, date |
| `header.html` | Running title + accent dot |
| `footer.html` | Author name (left) + page N / total (right) |