kaffesky-markdown-templates/convertion_templates_iA-Writer

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

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

<key>IATemplateHeaderHeight</key>
<integer>94</integer>

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

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.

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

<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

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

/* 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>:

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:

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)