spm1001/ia-presenter

iA Presenter Markdown

Write and edit markdown files for iA Presenter, which generates beautiful slides from plain text.

What is iA Presenter?

iA Presenter is a macOS/iOS/iPadOS app from Information Architects (iA) — the same company that makes iA Writer. It takes markdown files and renders them as presentation slides with automatic responsive layout. The app emphasizes story-first presentation design: you write your script, and the design adapts to your content rather than forcing content into templates.

Key differentiator: visible/speaker notes separation is controlled by indentation, not by a separate notes panel. This means your markdown file contains both what you show and what you say, distinguished only by whether lines are tab-indented.

The Core Insight: Visible vs Speaker Notes

iA Presenter's key innovation is separating what the audience sees from what you say (speaker notes/teleprompter). This is controlled by indentation:

| Element | Visibility | How to Write | |---------|------------|--------------| | Headings | ALWAYS visible | #, ##, ### at line start | | Tab-indented text | Visible on slide | ⇥Text here (literal tab character) | | Plain paragraphs | Speaker notes only | No indent — audience never sees this | | Images/videos/tables | Visible by default | URL or path on its own line | | Lists | Visible only if tabbed | ⇥1. Item or ⇥- Item |

The tab character is load-bearing. A leading tab makes body text visible to the audience. Without it, the text becomes speaker notes (shown in teleprompter, hidden from audience).

File Format

iA Presenter uses .iapresenter bundles (directories), not plain .md files:

MyPresentation.iapresenter/
├── assets/          # Images, media (optional)
├── info.json        # Metadata
└── text.md          # The markdown content

info.json template:

{
  "creatorIdentifier" : "net.ia.presenter",
  "net.ia.presenter" : {},
  "transient" : false,
  "type" : "net.daringfireball.markdown",
  "version" : 2
}

To create a new presentation programmatically:

1. Create MyPresentation.iapresenter/ directory
2. Create assets/ subdirectory (can be empty)
3. Create info.json with the template above
4. Create text.md with your markdown content

When to Use

• Creating new presentations in iA Presenter format
• Editing existing .presenter or .md files for iA Presenter
• Validating that markdown will render correctly as slides
• Converting standard markdown to iA Presenter format
• Working in the iCloud~net~ia~presenter folder

When NOT to Use

• Standard markdown files (no iA Presenter involvement)
• PowerPoint or Google Slides (use pptx skill instead)
• Reveal.js, Marp, or other slide frameworks (different syntax)
• HTML/CSS slide decks

Slide Structure

Slide Separation

Content for slide 1

---

Content for slide 2

Three dashes (---) on their own line create a new slide.

Heading Hierarchy

# Title Slide Heading (H1 - largest)
## Section Heading (H2 - major sections)
### Content Heading (H3 - within slides)

Headings are ALWAYS visible. Use them for the key message the audience must see.

Basic Slide Pattern

### Visible Heading
	Visible subtitle or key point (TAB-indented)

Speaker notes go here without indentation. The audience never sees this.
You can write as much context as you need for yourself.

---

Text Visibility Examples

Title Slide

	Fast and Focused
# Main Title
	Subtitle line

This introductory paragraph is speaker notes - invisible to audience.

Result: Three visible lines stacked (subtitle, title, subtitle), with speaker notes in teleprompter.

Content Slide

### The Key Point
	The heart of a great presentation is the message. Get the script right before anything else.

Most presentation tools ask you to choose a design first. iA Presenter flips the process. You focus on what matters: your story.

Result: Heading + one visible paragraph. The longer explanation is speaker notes.

Multi-Column Layout

### Column One
	Description for the first column goes here.

### Column Two
	Description for the second column goes here.

Speaker notes for this slide.

Result: Auto-arranges as two columns side-by-side.

Visible Lists

### Table of Contents
	1. Write
	2. Structure
	3. Iterate
	4. Design
	5. Action

The numbered list above is visible because each line is tab-indented.

Images

Basic Image

https://example.com/image.jpg

Or a local path:
/Theme/image.webp

Images are visible by default. Just put the URL or path on its own line.

Image with Metadata

https://example.com/screenshot.png
x: left
y: top
title: "Caption text"

Available metadata:

• x: — horizontal position: left, center, right
• y: — vertical position: top, center, bottom
• size: — sizing: contain, cover
• background: — true to place behind other elements
• filter: — lighten, darken, grayscale, sepia, blur
• opacity: — 0% to 100%
• title: — caption/alt text

Image Captions with H4

#### Caption introducing the image

/assets/photo.jpg

Or image first, caption below:

/assets/photo.jpg

#### Caption below the image

Multiple Images (Grid)

https://example.com/image1.jpg

https://example.com/image2.jpg

https://example.com/image3.jpg

https://example.com/image4.jpg

These images auto-arrange into a grid layout.

Image + Text Layout

### Heading on Left
	Visible description text that appears alongside the image.

https://example.com/image.png
x: right
y: top

Speaker notes explaining what we're showing.

Result: Text on left, image on right.

Inline Formatting

Standard markdown formatting works:

• **bold** — bold
• *italic* — italic
• ~~strikethrough~~ — strikethrough
• ==highlight== — highlighted text
• [link text](url) — hyperlinks
• `code` — inline code
• $x^2$ — inline LaTeX math
• // comment — comment (only you see)

Common Patterns

Kicker (Small Text Above Title)

	Small kicker text
# Main Title
	Subtitle below

Tab-indented text directly above a title creates a "kicker" — small headline often seen above main titles.

Section Divider

## 1. Write
	Start With a Script

Brief visible tagline. Then your speaker notes expand on it below.

---

Quote/Callout Slide

	**Key insight in bold.** Additional visible context that supports the main point.

The rest of your speaking notes. Expand, give examples, tell stories.

Closing Slide

## Now go and move mountains.

Final thoughts in speaker notes. Link to resources: [How-To](https://ia.net/presenter/how-to)

Validation Checklist

When reviewing iA Presenter markdown:

1. Tab characters exist — Visible body text MUST start with a literal tab (not spaces)
2. Slides are separated — --- between each slide
3. One idea per slide — Keep slides focused
4. Headings are concise — They're always visible; make them count
5. Speaker notes are useful — Don't waste the teleprompter space
6. Images have paths — URLs or local paths on their own lines

Common Mistakes

| Mistake | Problem | Fix | |---------|---------|-----| | Spaces instead of tabs | Text won't be visible | Use literal tab character | | Too much visible text | Stuffed slides bore audiences | Move detail to speaker notes | | Missing --- | Slides won't separate | Add --- between slides | | Forgetting speaker notes | Wasting the teleprompter | Add context below visible content |

Generating New Presentations

When creating iA Presenter markdown from scratch:

1. Start with the story — Write the narrative first
2. Identify key points — These become headings
3. Decide what audience sees — Tab-indent only essential text
4. Add speaker notes — Context, examples, transitions
5. Add images last — URLs/paths with positioning metadata
6. Review slide count — --- separators should match intended slides

Example: Complete Slide

### Tell Your Story
	The heart of a great presentation is the message. Get the script right before anything else.

Most presentation tools ask you to choose a design and then adjust your story to fit it. iA Presenter flips the process.

Start with what you want to say. The design comes later, and it adapts to your content — not the other way around.

---

Visible to audience:

• "Tell Your Story" (heading)
• "The heart of a great presentation..." (tab-indented paragraph)

Speaker notes (teleprompter only):

• "Most presentation tools ask you to choose..."
• "Start with what you want to say..."

Layout Algorithm

Presenter auto-selects layouts based on:

• Number of visual blocks (cells) in the slide
• Types of graphics in each block
• First heading level of each block
• Order of blocks

| Content | Result | |---------|--------| | 2-3 elements separated by blank lines | Side-by-side columns | | 4+ elements | Grid layout | | H4 + image | Caption layout | | Image with background: true | Background image behind text |

Cells: Content separated by blank lines goes into different cells. One element per cell usually looks better.

Anti-Patterns

| Pattern | Problem | Fix | |---------|---------|-----| | Spaces for indentation | Content invisible on slides | MUST use literal tab characters | | Missing --- separators | Slides run together | Add --- between each slide | | Empty speaker notes | Wasting teleprompter, no speaking context | Add narrative below visible content | | All-headings slides | Headings are always visible — no notes | Balance headings with tab-indented text | | Skip validation | Broken slides discovered during presentation | Test in iA Presenter app before presenting | | Create .md instead of .iapresenter | Won't open correctly in app | Create bundle with text.md + info.json |

Full Reference

See references/syntax-reference.md for complete documentation including:

• All text formatting (highlight, superscript, subscript)
• Footnotes and citations
• LaTeX math
• Code blocks with syntax highlighting
• Tables
• Custom themes and CSS classes
• Layout CSS classes for theming