About this reference

This is an independent, living reference for IDML, the InDesign Markup Language.

In short IDML is the format an InDesign document takes when it travels as text — an open, inspectable package instead of a sealed binary. This reference explains the format for humans, from first principles: from small files we author ourselves, and from what a working renderer does with them. It is not the normative specification — it points to the authoritative spec where a normative answer is needed — and it runs roughly beginner to pro so you can enter wherever your question lives.

The reference implementation behind every example is Paged, an open-source engine that reads, renders and writes IDML. Where it helps, a page notes how Paged handles a construct; the format itself is described independently of any one tool.

How this is organized

The reference runs roughly beginner to pro, ordered by how a reader actually comes to understand the format — not by the order any source document happens to list things in. Three reader tiers run throughout:

• 🟢 Beginner — "What is this thing?"
• 🟡 Intermediate — "How do I work with it?"
• 🔴 Pro — "How does it really work, and where are the edges?"

Every page declares one tier and one job, and carries a difficulty label. Pages still being written are excluded from search until they reach real depth.

Start here

• Foundationswhat IDML is and how to read one by hand.
• Package anatomywhat is actually inside the ZIP.
• Stories & textwhere the words live.

Frequently asked questions

What is this reference? It is an independent, community-minded reference for the IDML file format and the open-source Paged renderer. Every page is written from first principles — from small files we author ourselves and from how our own parser behaves — rather than copied from any specification.

Is this the official IDML specification? No. This is an explanatory reference for humans, not the normative spec. Where a strictly normative answer matters, we say so and point you to the authoritative specification; element and attribute names themselves are simple facts and are used freely throughout.

Where should I start? If you are new to the format, begin with Foundations to learn what IDML is and read one by hand, then move to Package anatomy to see what is inside the ZIP. The reference runs beginner → intermediate → pro, and each page declares its tier so you can enter wherever your question lives.