@kaos-intelligence/idml-parser

Parse Adobe InDesign IDML packages into a fully-typed document model.

IDML (InDesign Markup Language) is InDesign's interchange format: a ZIP of XML files describing everything in a document — text stories, page spreads, master spreads, the paragraph/character style cascade, linked assets, and the XML backing story. This parser unzips the package, parses every part, and returns one resolved IDMLDocument ready to be mapped into an EPUB (or any other target).

What it extracts

• Stories — Stories/Story_*.xml: text content as paragraphs and runs
• Spreads — Spreads/Spread_*.xml: page geometry, page items, anchored objects
• Master spreads — MasterSpreads/MasterSpread_*.xml: templates
• Style cascade — Resources/Styles.xml: resolved paragraph/character styles
• Backing story — XML/BackingStory.xml: semantic structure (when present)
• Reading order — resolved from the backing story, with a geometric spread-order fallback
• Assets — linked images from Links/ and fonts from Resources/Fonts.xml
• CSS — generated from the resolved styles (points → em, configurable base)
• EPUB semantic mapping — InDesign styles → XHTML elements, epub:type, and ARIA roles

Install

npm install @kaos-intelligence/idml-parser

Requires Node.js ≥ 20.

Usage

import { parseIDML } from '@kaos-intelligence/idml-parser';

const doc = await parseIDML('/abs/path/to/book.idml');

console.log(doc.meta.title, doc.meta.pageWidth, 'x', doc.meta.pageHeight);
console.log('stories:', doc.stories.length);
console.log('spreads:', doc.spreads.length);
console.log('styles:', doc.styles.length);
console.log('assets:', doc.assets.length);
console.log('reading order nodes:', doc.readingOrder.length);
console.log(doc.css); // generated stylesheet (when styles were resolved)

parseIDML(idmlPath) runs the full pipeline: container → designmap → stories → spreads → masters → backing story → styles → fonts → assets → reading order → CSS, and returns the assembled IDMLDocument.

Lower-level helpers are also exported for custom pipelines:

import {
  generateCss,
  mapStyleToEpub,
  resolveReadingOrder,
  parseFonts,
  extractAssets,
} from '@kaos-intelligence/idml-parser';

// CSS from resolved styles (base font size in pt, default 12)
const css = generateCss({ styles: doc.styles, baseFontSizePt: 12 });

// Map one resolved style to its EPUB equivalent:
// { styleId, styleName, element, className?, epubType?, role? }
const mapping = mapStyleToEpub(doc.styles[0]);

// Re-resolve reading order with custom options
const order = resolveReadingOrder({
  backingStory: doc.backingStory,
  spreads: doc.spreads,
  stories: doc.stories,
  emitPageBreaks: true, // default
});

All model types (IDMLDocument, Story, Spread, MasterSpread, Paragraph, Run, PageItem, AnchoredObject, ResolvedStyle, IdmlAsset, ReadingOrderNode, BackingStory, …) are exported from the package root and from @kaos-intelligence/idml-parser/types.

Development

pnpm build       # tsc → dist/
pnpm test        # vitest run
pnpm typecheck   # tsc --noEmit

License

MIT © 2026 kaOS Intelligence Inc. See LICENSE.