IDML creation, editing, and analysis

Overview

designmap.xml

• All helper scripts are in

  scripts/

  . If a model says “no python scripts,” have it list the directory to confirm:

  • ls scripts

  • ls skills/idml/scripts

    (if running from repo root)

• IDML package structure:

  references/idml-structure.md

• IDML XML overview:

  references/idml-xml.md

• IDML document library:

  references/idml-document.md

• IDML translation workflow:

  references/idml-translation.md

• Track changes guidance:

  references/idml-track-changes.md

• Schemas and validation:

  references/idml-schemas.md

• Tooling:

  references/tools.md

Example prompts

• "Extract all story text from this IDML and prepare it for translation."
• "Apply translated text back into Stories/*.xml without changing layout."
• "Map stories to spreads and pages for review."
• "Validate this IDML package and run a roundtrip smoke test."
• "Generate an observed schema and report unknown elements."

Workflow decision tree

Reading/analyzing content

• Unpack and inspect

  designmap.xml

  , story files, and spreads.
• Use the XML reference to understand component boundaries.

Creating a new document

• Preferred: create in InDesign and export to IDML.
• If generating from scratch, follow the IDML specification and component schemas.

Editing an existing document

• Text-only edits: edit

  Stories/*.xml

  .
• Layout edits: edit

  Spreads/*.xml

  or

  MasterSpreads/*.xml

  .
• Styles/resources: edit

  Resources/*.xml

  and keep references consistent.

Reading and analyzing content

Unpacking

python scripts/unpack_idml.py file.idml unpacked

Key files

references/idml-structure.md

Editing workflows

Library-based edits (recommended)

scripts/idml_document.py

references/idml-document.md

Raw XML edits (advanced)

1. MANDATORY - READ ENTIRE FILE: Read

   references/idml-xml.md

   before editing XML directly.
2. Unpack the file:

   python scripts/unpack_idml.py file.idml unpacked

3. Edit the specific component XML (stories/spreads/resources).
4. Repack:

   python scripts/pack_idml.py unpacked out.idml

5. Validate:

   python scripts/validate_idml.py unpacked --original out.idml

Translation workflow

references/idml-translation.md

Track changes

references/idml-track-changes.md

Validation and smoke tests

• Package validation:

  python scripts/validate_idml.py <unpacked_dir> --original <file.idml>

• Full roundtrip smoke test:

  python scripts/smoke_test.py <file.idml> <work_dir>

• Translation extract:

  python scripts/extract_story_text.py <unpacked_dir> translations.jsonl

• Prepare translation JSONL:

  python scripts/prepare_translation_jsonl.py translations.jsonl translations_for_translation.jsonl

• Translation apply:

  python scripts/apply_story_text.py <unpacked_dir> translations.jsonl

• Story count report:

  python scripts/compare_story_counts.py english.jsonl khmer.jsonl --out story_counts.json

• Alignment file:

  python scripts/align_story_text.py english.jsonl khmer.jsonl --out alignment.jsonl

• Story/spread map:

  python scripts/map_story_spreads.py <unpacked_dir> --out story_spreads.json

• Resource report:

  python scripts/check_resources.py <unpacked_dir> --out resources_report.json

• Content-only validation:

  python scripts/validate_content_only_changes.py <original_unpacked> <modified_unpacked>

• Observed schema report:

  python scripts/observe_idml_schema.py <idml_or_unpacked> --out idml_observed_schema.json

• Observed schema validation:

  python scripts/validate_observed_schema.py <schema.json> <idml_or_unpacked> --out idml_schema_report.json

• Observed schema coverage:

  python scripts/observed_schema_report.py <schema.json> --out idml_schema_coverage.json

• Observed schema delta:

  python scripts/schema_delta_report.py <base_schema.json> <new_schema.json> --out idml_schema_delta.json

• Coverage checklist:

  python scripts/coverage_checklist.py <schema_delta.json> --out idml_schema_checklist.md

• Combined coverage plan:

  python scripts/coverage_plan.py Label=delta.json ... --out idml_schema_plan.md

Code style guidelines

• Write concise code.
• Avoid verbose variable names and redundant operations.
• Avoid unnecessary print statements.

Dependencies

• defusedxml:

  pip install defusedxml

  (safe XML parsing)

• InDesign: export IDML from source documents
• jing: Relax NG validator for strict schema checks