mirror of
https://github.com/Kaffesky/kaffesky-markdown-templates.git
synced 2026-04-18 12:47:31 +02:00
Updating iA-writer section
This commit is contained in:
jostein
parent
6f50b1f00d
commit
37ba3383ba
7 changed files with 866 additions and 0 deletions
328
convertion_templates_iA-Writer/README.md
Normal file
328
convertion_templates_iA-Writer/README.md
Normal file
|
|
@ -0,0 +1,328 @@
|
|||
# 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) |
|
||||
Loading…
Add table
Add a link
Reference in a new issue