# InDesign: import, export and porting

> The two ways to bring an InDesign book into Postext, the IDML importer that copies what the document holds and the agent skill that works out its layout rules, when to use each, and how the IDML exporter hands a book back to InDesign

- HTML version: https://postext.dev/en/docs/indesign
- Last updated: 2026-11-14
- Reading time: 9 min
- Other languages: [es](https://postext.dev/es/docs/indesign.md), [ca](https://postext.dev/ca/docs/indesign.md), [de](https://postext.dev/de/docs/indesign.md), [fr](https://postext.dev/fr/docs/indesign.md), [it](https://postext.dev/it/docs/indesign.md), [pt](https://postext.dev/pt/docs/indesign.md), [zh](https://postext.dev/zh/docs/indesign.md), [ja](https://postext.dev/ja/docs/indesign.md), [ar](https://postext.dev/ar/docs/indesign.md)

## In short

Postext can bring a book made in InDesign into Postext in two ways. The importer copies what the InDesign file holds: every page, frame and style as it is. It is quick, but the result is a copy of the old pages, hard to change and to translate. The agent skill studies the file, the printed PDF, the fonts and the pictures, works out the rules the designer followed and rebuilds the book from them, with the text free to flow. That gives a better book, so it is what we recommend. This page explains both ways, when each one fits, and how Postext sends a finished book back to InDesign.

**A book made in InDesign can come into Postext by copying its pages or by working out its design. We recommend working out the design.**

Postext reads and writes InDesign Markup packages (`.idml`), the file InDesign saves with **File › Save As › InDesign Markup (IDML)**. Three tools use them:

- the **importer**, which turns an `.idml` into a Postext book;
- the **agent skill** [`postext-port`](https://postext.dev/en/docs/skill.md), which ports a book from all its sources, the `.idml` among them;
- the **exporter**, which writes a Postext book as an `.idml` for a designer to finish in InDesign.

The importer and the skill both bring a book in, and they do not give the same book. This page explains the difference so you can choose.

> [InDesign, in and out: import, port and export InDesign books with Postext](https://youtu.be/Rel3IvPCsg0) · 4:25

## Two ways into Postext

An InDesign document is a set of pages that someone made by hand. The designer followed rules, such as a type size, a grid, the way a chapter opens, where a box goes and how a caption sits under its figure. The `.idml` keeps the result of applying those rules, frame by frame, and does not record the rules themselves.

**The importer copies the result.** It reads the package and writes what it finds: each frame where it stood, each style with its values, each picture and table as a resource. Nothing is guessed, and the same file always gives the same book. Like the HTML of a web page, the copy shows the pages without the reasoning behind them. A frame placed by eye stays at its coordinates, a heading pushed down with an empty paragraph keeps the empty paragraph, and a local override stays an override. The book looks like the source, and it keeps the source's craft.

**The skill works out the rules.** An agent reads the whole source: the `.idml`, the print PDF, the fonts and the artwork. It measures the pages and writes down the rules they follow, such as the trim and margins, the baseline grid, the type roles, the openers, the running heads, the box families and where floats go. It then writes the text as reflowable Markdown that carries no page positions, and sets the design in the configuration from those rules. Postext lays the pages out from the rules, so the book can be edited, translated and set at another size, and it still looks like the original.

|  | Importer | Agent skill |
| --- | --- | --- |
| Reads | The `.idml` and its linked pictures | The `.idml`, the print PDF, the fonts and the linked artwork (`.ai`, `.psd`, `.eps`, `.tif`) |
| Method | Deterministic: copies what the document holds | Inference: measures the pages and works out the rules |
| Text | Bound to the document's frames (`--layout pages`) or flowing under its styles (`--layout flow`) | Reflowable Markdown with directives, free of page positions |
| Design | The values of the document's styles and frames | A configuration of rules: grid, type roles, openers, running heads, boxes, floats, page templates for composed pages |
| Time | Seconds | Hours for a book, with an agent and checks against the PDF |
| Result | A replica, with a report of what was lost | A Postext book that behaves like the original |

**Use the skill by default.** It is the right route for any book you will keep: a book you will revise, translate, set at another trim or publish as EPUB as well as print.

**Use the importer** when a copy is the goal:

- **A book that Postext exported.** An `.idml` written by Postext comes back with the same lines and the same pages, so a designer's InDesign changes return to the book.
- **A quick look.** The import report lists the document's pages, stories, styles, fonts, pictures and tables in seconds, before you decide anything.
- **A fixed page kept as it is.** A poster, a form, a single spread or a short brochure that will not be edited or reflowed.
- **The first step of a port.** The skill itself can run the importer to get an inventory and a first draft, then correct it; see [below](https://postext.dev/en/docs/indesign.md#how-the-skill-uses-the-importer).

## The importer

```bash
postext import-idml book.idml -o book/
postext import-idml book.idml -o book.postext --layout flow --links Links/
postext import-idml book.idml --report --json
postext import-idml package.zip -o book.postext
```

The same import runs in the Sandbox, under **Books › New › New book from an InDesign document (IDML)** (see [Importing an InDesign document](https://postext.dev/en/docs/indesign.md#importing-an-indesign-document)), which also opens a zipped InDesign package under **New book from an InDesign package (.zip)** and takes its fonts and linked pictures from it, and in code with `idmlToPostext` from the `postext-idml` package (see [Programmatic usage › InDesign packages](https://postext.dev/en/docs/configuration-programmatic-usage.md#indesign-packages-postext-idml)). Every option of the command is in [Command line › import-idml](https://postext.dev/en/docs/command-line.md#import-idml).

### Importing an InDesign document

**New book from an InDesign document (IDML)**, in the **New** menu of the Books panel, reads an `.idml` file in the browser and opens a dialog. It shows what the document holds: its pages and their size, its stories, the fonts it names, its pictures, linked and embedded, and its tables. **Layout** chooses between **Composed pages**, where every page keeps its frames where the document has them, and **Flowing book**, where the text runs through pages the book's design makes; **Automatic** leaves the choice to the importer, which gives its reason. An `.idml` does not carry the pictures it links to: choose the files, or the folder that holds them, and each one is matched by its file name. The import report follows every choice: a verdict, the counts, what was lost, approximated or noted, each with a count and an example, the fonts the book needs and the links still missing. **Create the book** adds the result to your books and opens it, and the books you had stay as they are. An `.indd` file is refused with a message that says to save it as IDML from InDesign. The command line does the same import with [`postext import-idml`](https://postext.dev/en/docs/command-line.md#import-idml). The import is a copy of the document's pages; for a book you will keep, the [agent skill](https://postext.dev/en/docs/skill.md) works out its layout rules instead (see [The skill](https://postext.dev/en/docs/indesign.md#the-skill)).

**New book from an InDesign package (.zip)** takes the folder InDesign's **File › Package** makes, zipped, with **Include IDML** ticked. When the package holds more than one IDML document, a dialog asks which one becomes the book. The import dialog then works as above, with what the package adds. Its linked pictures are taken from it, matched by file name and, between files of the same name, by folder. The font files of `Document fonts` go into the book: each face is matched to the one the document names by its PostScript name, so the text is set in the original faces. The report lists the fonts the package carries and the faces it has no file for, and names any font file the book cannot carry (Type 1, a Mac suitcase, a WOFF 1 file). A font collection (`.ttc`, `.otc`), the way macOS ships fonts such as PT Sans, is split into its faces: the ones the text is set in, with the other faces of their families, go into the book as single TrueType or OpenType files named after the face, and the collection's other faces are left out (since postext 1.83). A package that holds only an `.indd` is refused with a message that says how to get its IDML.

### Pages or flow

- **`--layout pages`** follows the document page for page. Each page becomes a [composed page](https://postext.dev/en/docs/composed-pages.md) and each frame stays at its place, size and order, with a chain of linked frames kept as a chain. Use it for documents whose pages are each made by hand.
- **`--layout flow`** writes the stories in reading order under the document's paragraph styles, and Postext sets them on pages the book's design makes. Use it for running text, such as a novel or an essay, where the pages only hold the text. Pages whose frames only read together are set whole (since postext 1.83.1). A page with no running text of its own, such as a cover or a part divider, becomes a [composed page](https://postext.dev/en/docs/composed-pages.md) in the flow, its frames where InDesign has them and its shapes and pictures as decoration. A page whose running text starts under a title with a band, a picture or a filled frame is an opener: the title becomes a heading that opens the page, and its heading style's design draws the band, the kicker and any tab on the fore edge. The report lists them as `composedPagesInFlow` and `openerDesigns`.
- **`auto`**, the default, picks one from the document and gives its reason.

### What comes through

- Paragraph and character styles become the book's paragraph and heading styles, with their font, size, leading, indents, spacing, alignment, tab stops and colour.
- Text with its emphasis, forced line breaks, tabs, footnotes, hyperlinks, ruby, emphasis marks and tate-chu-yoko.
- Tables with their merged cells, header rows, insets and pictures in cells; pictures, anchored and placed; rules, rectangles and colour swatches.
- Pages, their size and margins, master-page items and sections.
- Text wrap. Text runs round a frame that wraps it. Behind an object whose wrap is **Jump Object**, the text frame is cut into linked frames above and below the object, with the wrap's top and bottom offsets, so the text stops above it and goes on below it as in InDesign; **Jump to Next Column** stops it above the object (since postext 1.82.2).
- Spot swatches, as spot colours of the palette, each printing on its own plate. A spot ink with a finish becomes an entry of [`print.inks`](https://postext.dev/en/docs/special-inks-die-cuts.md): the finish a Postext export recorded comes back as written, and any other is guessed from the ink's name (`PANTONE 871 C` metallic, `Varnish` a varnish) and listed under `inkFinishGuessed` for you to confirm with the printer (since postext 1.87.0).
- The die line. The paths on a layer named as die lines are (Die line, Troquel, Stanzform…), or stroked with a `CutContour`, `Die` or `Dieline` swatch, on the pages or on their masters, become the book's [`dieCuts`](https://postext.dev/en/docs/special-inks-die-cuts.md): each hole a shape placed on the first recto it cuts, with `leaves` when it goes through the next leaves too, and a trimmed edge as rounded `corners` or an `outline`. The swatch's name becomes `print.dieLine.ink`. The die paths are not copied as artwork (since postext 1.87.0).

### What it reports

The `.idml` does not carry the fonts or the linked pictures. The importer lists the font families the book needs, which you then give to the build with `--font-dir`. It reads linked pictures from `--links` or from beside the file, and lists the ones it does not find. A zipped package carries both: on the command line (`postext import-idml package.zip`), in the Sandbox, and in code with `openIdmlArchive`, the importer takes the pictures from its `Links` folder and puts the font files of its `Document fonts` folder into the book.

InDesign can do things Postext has no equivalent for, such as text on a path, a rotated cell, a diagonal line in a cell, GREP and nested styles, or transparency effects. Each of these becomes a finding in the report, with a count and an example: a *loss* when it is left out, a *warning* when it is set close to the source (a table's footer rows, a gradient, a contour wrap). The report ends with a verdict:

- **`faithful`**: nothing was lost or approximated. A book exported from Postext comes back faithful. Since postext 1.85.0 the export threads the running text of the pages laid out in columns through one story, a frame per column, and the importer reads it back as the flowing book it was: its paragraphs whole, its headings, its boxes and its figures with their captions where they stood. Its column guides are the page's columns, a side column included. Since postext 1.86.0 its running heads and page numbers come back as the book's header and footer, the chapter openers' own included, and the boxes floated into a side column (glosses) come back as floats of that column. The shapes Postext draws on each page are left out and reported as a loss (`pageArtInFlow`), so a book that has them comes back `lossy` as a flowing book; its design can draw them again. Exported with `--text frames` (a frame for each block, as before 1.85.0), it comes back as composed pages, each page with its frames where the export placed them, and the book's paragraph styles, character styles, boxes and pictures (since postext 1.84.0).
- **`approximate`**: some things were set close to the source, and nothing was left out.
- **`lossy`**: something was left out.

### How close the copy is

IDML stores the text and the frames, not the lines InDesign broke them into. Postext sets the lines again with its own composer, so a line of a document made in InDesign rarely ends on the same word. What should match is which text falls on which page. The importer is tested on a corpus of documents made in InDesign: a 15-page book, magazine pages, tables, links and notes, Japanese and Arabic, anchored objects and styles. On the six of them measured, 87 to 100 per cent of the words fall on the same page as in InDesign's own PDF (since postext 1.78).

A book that Postext exported keeps its lines. Every line of the export ends with a forced break, and the importer turns on [`bodyText.justifyHardBreaks`](https://postext.dev/en/docs/configuration-text.md) so those lines stay justified.

## The skill

The [agent skill](https://postext.dev/en/docs/skill.md) ports a book in the steps that page describes: a brief, an inventory of the source, a sheet of measured facts, the configuration, the chapters, and checks of every page against the original. For an InDesign book, give it everything InDesign has.

### The source folder

In InDesign, **File › Package** gathers the document's fonts and linked pictures into one folder; tick **Include IDML** and **Include PDF (Print)**. Put that folder in the project as `source/`:

```
my-book/
  source/
    Book.indd
    Book.idml
    Book.pdf
    Document fonts/
    Links/
      cover.ai
      map-01.ai
      photo-12.psd
```

- **The `.idml`** gives the text, the styles, the tables and the anchored pictures in story order. The skill reads it with its own `idml_extract.py`, which maps every paragraph style to a role.
- **The print PDF** gives what the `.idml` lacks: where every line, box and figure landed on the printed page. The skill measures the grid, the margins and the openers there, and it compares its own pages with it at the end.
- **The fonts** let Postext set the text in the original's faces, so the measurements hold. Check that their licence allows it; the skill asks when it cannot tell.
- **The artwork** in `Links/` becomes the book's figures: Illustrator files as vector SVG, Photoshop and TIFF files as bitmaps.

Then ask the agent, for example: *"Port the InDesign book in `source/` to Postext: chapters 1 to 3 first, in Spanish, for print and EPUB."*

### How the skill uses the importer

The skill can run `postext import-idml source/Book.idml --report --json` at the start. The report gives an inventory in seconds: the styles in use, the stories, the fonts, the pictures, the tables and what has no equivalent. The skill starts from it, and it does not deliver the import itself. It replaces frames at fixed places with rules and templates, empty paragraphs and overrides with spacing and styles, and per-page positions with floats.

## The exporter

```bash
postext idml book/ -o book.idml
postext idml book.postext -o book.idml --images link --fonts
postext build book/ --pdf book.pdf --idml book.idml
```

The exporter lays the book out as the PDF does and writes the pages as an `.idml` for a designer to finish in InDesign. It runs from the command line ([`postext idml`](https://postext.dev/en/docs/command-line.md#idml), or `--idml` in `build`), from the Sandbox (**Export to InDesign (IDML)** in the Text panel header; see [Sandbox › Books and saving](https://postext.dev/en/docs/sandbox-books-saving.md)), and in code with `idmlDocument` from `postext-idml`.

- **Pages and spreads.** The pages stand at their trim size, in spreads of facing pages for a book with mirrored margins and one page to a spread otherwise; `--spreads facing` or `--spreads single` sets them whatever the margins say.
- **Lines.** `--lines keep`, the default, ends every line where Postext ended it, so InDesign shows the same lines as the PDF. `--lines reflow` leaves the paragraphs to InDesign's composer, for a book that will be set again there.
- **Text.** The running text of the pages laid out in columns runs through one story, threaded through a text frame per column, as in a book set in InDesign, and the boxes of the flow are anchored in it (since postext 1.85.0); `--text frames` writes a frame and a story for each block where Postext painted it instead. Each composed-page frame becomes a text frame with its own story, and frames chained with `next` share one. Paragraph styles carry the book's style names, indents, tab stops and spacing. Footnotes, links, ruby, emphasis marks, right-to-left and vertical stories come through.
- **Running heads.** With the text threaded, the running heads and page numbers stand on master spreads, as in a book set in InDesign (since postext 1.86.0). The page number is InDesign's current page number, `{chapterTitle}` is a running-header text variable that shows the last chapter title on the page, and other words are written as they are. Pages that show the same heads apply the same master, and the chapter openers get a master of their own, named Opener. A head InDesign cannot express, such as `{attr.place}`, stays on its page. The boxes floated into a side column (glosses) are anchored in the running text at a custom position, so they move with the paragraph they face.
- **Page items.** Rules, boxes, paths and pictures become InDesign page items; tables become InDesign tables, and inline maths, music and swatches become anchored objects. Authored CMYK colours become process swatches, and form-field chips become InDesign form fields.
- **Special inks and die line.** Each spot ink becomes a spot swatch with an ink of its own, and its finish is kept in the swatch's script label (`postext:finish`), since InDesign has no field for it. The Ink Manager gets the ink type the finish separates with: Transparent for a varnish, Opaque for a white, a metallic ink or a foil. White and varnish overprint, as in the PDF. The die-cuts are drawn on a locked layer called **Die line**, as paths stroked with the die swatch and set to overprint; the layer does not print when `print.dieLine.output` is `none`. Imported again, the package gives the same inks and die-cuts back (since postext 1.87.0).
- **Pictures and fonts.** `--images link` writes the pictures to `Links/` beside the package instead of embedding them. Each file ends in the extension of its format (`.svg`, `.png`, `.jpg`, `.pdf`…), so it opens in its own program once unpacked. `--fonts` writes the font files to `Document fonts/`, where InDesign finds them, and leaves out any family the book may not redistribute.
- **Warnings.** Whatever InDesign cannot show as Postext set it is reported as an `idml.*` warning, such as a table's rounded frame or emphasis dots in vertical text.

Exporting is not porting in reverse. The `.idml` holds the pages Postext laid out, and the rules that laid them out stay in the Postext book. A change made in InDesign comes back to Postext through the importer, as a copy of the page. Rules you change, such as the type size, are best changed in the Postext book and exported again.

## Choosing, in short

- **To keep, edit or translate a book made in InDesign**, port it with the skill from a packaged source folder.
- **To see what an `.idml` holds**, or to bring back a book Postext exported, use the importer.
- **To keep a one-off fixed page exactly as it is**, import it with `--layout pages`.
- **To send a Postext book to an InDesign studio**, export it with `postext idml`.
