4. InDesign Formatting Guide

To ensure high-quality conversion of an IDML file, it must be properly formatted. Otherwise, the quality of the conversion will be lower, and this will inevitably lead to additional work on the resulting files. To minimize the amount of work after conversion, it is recommended to follow a few best practices when working in InDesign.

Recommendations

This list is not exhaustive and will be expanded as special cases arise.

Avoid style overrides

As it stands, the converter ignores style overrides (when an element has a paragraph style with a +). There are ways to easily remove these overrides.

One semantic unit = one paragraph or character style

InDesign allows a certain form of semantic structure through paragraph and character styles. In InDesign, concepts commonly found in markup languages (headings, quotes, emphasis, etc.) do not exist. It is therefore necessary to specify the semantic meaning of each paragraph and character style.

The JSON files loaded into the converter allow mapping paragraph and character styles to element types, but each stylistic unit must be associated with a semantic unit. In other words, each style must correspond to an output element type.

Threading content

To ensure that content appears in the correct order in the converted result, it is best to properly thread the blocks together and [anchor images within the blocks](https://helpx.adobe.com/indesign/using/anchored-objects.html.

Naming files and styles

To avoid any issues, it’s best to use only unaccented alphanumeric characters in your filenames, image file names (links break easily), and style names, for example:

❌ Jane's über super-file.idml
✔️ Janes_uber_super_file.idml

Footnotes, lists, and alternative text

The converter supports footnotes, lists, and alternative text for images. However, for these to be recognized properly, they must first be correctly formatted in InDesign.

Hyperlinks

In the case of a print-ready PDF, it is often necessary to display the full URL. If the URL is properly entered in InDesign (i.e., with the URL and its display text being the same), then this will work without issues.

However, this task can be tedious. To make handling URLs easier (e.g., in justified paragraphs), we automatically reconstruct URLs that contain line breaks, provided they start with http:// or https://. For example:

https://www.example
.org

Will be converted to https://www.example.org, but not https://www.example .org, or if the URL didn’t start with https://.

Line breaks and paragraph breaks

Line breaks are automatically converted to space characters .

Paragraph breaks—two blocks separated by an empty block—are removed, unless the --empty option is enabled or the block has a paragraph style with the empty attribute in the JSON mapping file. See Style Mapping.

Limitations

Tabs and IDML metadata are currently ignored by the converter.