Cookbook

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 the text out of this file," "I need a placed image") and walks the few elements you actually have to read or write to get it. Every recipe is built on an example package that you can read on the page and download as an .idml file, 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 complete package you can read in full (raw, annotated, and as a tree), embedded in the page and offered as a download. The recipe describes that example's actual XML.
• 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.

Working with files

• Extract text from an IDML fileunzip, list the stories, walk Content and <Br/>.
• Generate an IDML file from codethe minimum package, entry by entry, and how to zip it.
• Swap text and images in a templatefind frames by name and change only what is inside them.
• Read which InDesign version wrote a fileproduct and DOMVersion in the design map.

Building parts of a layout

• Build a table in a storynest a Table on a paragraph, set its grid, and fill its cells. Pairs with Tables.
• Apply a gradient filldefine a Gradient swatch, point a shape's FillColor at it, and orient it. Pairs with Color & swatches.
• Place an image in a framenest an Image in a Rectangle and link the file. Pairs with Images & graphics.

Already covered elsewhere

• The full text-extraction recipe — Extract all text covers the special characters and markers in detail.
• 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 a reader, InDesign included, sees. 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 IDML package released under the MIT license, and each recipe links its download. Read it in full, adapt the part the recipe edits, and you have a working document. How the examples are checked is described in the docs examples loop.

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. Reading the version touches one attribute; a table pulls in the grid model, cell addressing, and the text that lives inside each cell.