Cookbook
Task recipes for authoring IDML by hand — build a table, apply a gradient, place an image — each grounded in a validated example and cross-linked to the reference.
The cookbook is where you come knowing what you want to make, not what a part is called.
In short: the rest of this reference explains the IDML format part by part —
what a Story is, how a Gradient is defined, why an Image nests inside a
frame. The cookbook flips that around. Each recipe starts from a task you already
have in mind ("I need a table," "I need a placed image") and walks the few
elements you actually have to write to get it. Every recipe is grounded in a real,
validated example — the same XML our renderer opens in CI —
and links back to the reference chapter when you want the full picture. It is a
lookup, not a learning path.
How the recipes work
Each recipe follows the same shape, so you can scan it fast:
- The goal in one line — what you'll have when you're done.
- The recipe — numbered, imperative steps over the elements you write. We name every element and attribute exactly as it appears in the XML, because those names are the part of IDML you can't paraphrase.
- The worked example — a validated package you can read in full (raw, annotated, and as a tree), embedded right in the page. The recipe describes that example's actual XML, so what you read is what the renderer accepts.
- Things to get right — the boundary cases that bite, and where the reference goes deeper.
The recipes don't repeat the reference. When a detail belongs to a chapter — how a table breaks across frames, the two ways a tint reaches a color — we point you there rather than copy it.
The recipes
- Build a table in a story — nest a
Tableon a paragraph, set its grid, and fill its cells. Pairs with Tables. - Apply a gradient fill — define a
Gradientswatch and point a shape'sFillColorat it. Pairs with Color & swatches. - Place an image in a frame — turn a
Rectangleinto a graphic frame by nesting anImagethat links an external file. Pairs with Images & graphics.
Already covered elsewhere
Two common tasks already have a home in the reference, so they aren't repeated here:
- Pull the plain text out of a document — Extract all text walks every story in reading order.
- Flow one story across several frames — Threading and overset explains how a single story spans multiple frames and what happens to text that doesn't fit.
Frequently asked questions
Do I have to author IDML by hand to use these? No — most IDML is generated by tools. But the recipes are written at the XML level because that's the contract: whether you hand-write a part or emit it from code, these are the elements and attributes the renderer reads. Authoring one by hand once is the fastest way to understand what your generator should produce.
Can I copy a recipe's example as a starting point? Yes. Every embedded example is a complete, validated IDML package released under a permissive license (see the test corpus). Read it in full, adapt the part the recipe edits, and you have a working document.
Why are some recipes marked a higher tier than others? The tier reflects how much surrounding structure the task touches, not how hard the steps are. Placing an image or applying a gradient changes one part; a table pulls in the grid model, cell addressing, and the text that lives inside each cell.
The docs examples loop
Every example in this reference is a hand-authored, unzipped IDML package that CI assembles into a real .idml and runs through the pinned renderer on each build — a structural parse-and-build gate that breaks the docs if the renderer ever stops accepting it.
Build a table in a story
A recipe for authoring an IDML Table — nest it on a paragraph, declare its grid with row, column, and cell counts, then give each Cell its own paragraph.