DocumentationWriting
Blocks
Every kind of thing you can put on a page besides prose: quotes, verse, callouts, tables, images, definition lists and page breaks.
A paragraph is a block. So is a quote, a table, a poem, a picture. Each type carries its own typography, set once in FormattingBlocks and applied to every block of that type in the book.
Inserting a block
Two routes, the same list:
In the toolbar above the manuscript.
The slash menu opens only on an empty line. Typing / mid-paragraph does nothing.

In the flow
| Block | What it is for | Shortcut |
|---|---|---|
| Image | A figure, with a caption and alt text | |
| Quote | A quotation set apart from the prose | |
| Footnote | A note at the foot of the page | ⌘⌥F |
| Epigraph | A quotation at the head of a chapter | |
| Callout | An aside: note, tip, warning or example | |
| Poem / verse | Lines and stanzas, kept as written | |
| Definition list | Term and definition pairs | |
| Table | Rows and columns, with a header row | |
| Scene separator | A break between scenes inside a chapter | *** |
Page layout
| Block | Effect |
|---|---|
| Page break | The next block starts a new page |
| Break to a right-hand page | Starts on a recto, inserting a blank if needed |
| Break to a left-hand page | Starts on a verso |
Paragraph roles
The block type menu in the toolbar carries paragraph roles below the block types. A role changes how a paragraph is set without making it a different kind of block.
| Role | Used for |
|---|---|
| Body text | Ordinary prose |
| Opening paragraph | The first paragraph of a chapter — takes the drop cap and lead-in |
| Editorial voice | An intrusion in the publisher’s voice rather than the author’s |
| Attribution | The source line under a quotation |
Attribution is how a quotation gets its source: type the quote, then a paragraph after it with the role set to Attribution.
Verse
Verse keeps every line and every indent exactly as typed. ⌘⏎ starts a new stanza.
Lines that are too long for the measure are run over with a hanging indent rather than wrapped flush, so a run-over reads as a continuation rather than as a new line of poetry.
Tables
Insert gives you a 3×3 table with a header row. Once the cursor is inside one, the Table menu in the toolbar becomes active:
- Insert row above / below, insert column left / right
- Toggle header row
- Merge or split cells
- Delete row / column / table
A table that is too wide for the text measure is scaled down or rotated in print. Check it in Preview.
Images
Insert an image and it lands inline. Its placement is set in the Properties panel:
| Placement | Result |
|---|---|
| In the text | Sits in the flow at the width you set |
| Full measure | Spans the text column |
| Beside the text, left / right | Text wraps around it |
| A page of its own | Takes a page, no text |
| Off the edge of the page | Bleeds past the trim — needs bleed set in the Page panel |
Width is always a fraction of the text measure, never a pixel count, so an image keeps its proportion when you change trim size or margins.
Alt text describes the picture for a screen reader and is required for an accessible EPUB. The Media panel lists every image in the book and flags the ones with none.
Callouts
Four kinds, plus one you title yourself:
| Kind | For |
|---|---|
| Note | An aside in the book’s own voice |
| Tip | Something the reader can act on |
| Warning | Something that goes wrong if ignored |
| Example | A worked case set apart from the argument |
| Custom | Titled by the book rather than by a kind |
Each kind takes its own colour and treatment in FormattingBlocks.