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.

Appliquer des styles de paragraphe aux paragraphes, et des styles de caractère aux caractères

The main limitation of the style mapping feature of this converter is that it is currently impossible to convert a paragraph style (block element) into a character style (inline element), and vice versa. For the mapping to work, the InDesign document must use paragraph and character styles correctly.

Avoid style overrides

Style overrides are local modifications applied to paragraph or character styles defined in an InDesign document. They appear as a + sign next to the style name and can be easily identified using the “Style Override Highlighter”.

The converter automatically detects these overrides and treats them as variants of the original style. For example, the first override applied to the NormalParagraphStyle will be named NormalParagraphStyle paragraph-override-1. All paragraphs with the same style overrides will receive this designation. When a new combination of overrides is encountered, it will be identified as paragraph-override-2, and so on.

Even though these overrides are correctly identified and style mapping can be applied like any other style, they complicate post-processing after conversion. It is therefore recommended to avoid them as much as possible by “clearing overrides” or “redefining the style” directly in InDesign.

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

Pour garantir que les contenus apparaissent dans le bon ordre lors de la conversion, il est recommandé de chaîner les blocs et d’ancrer les images dans ces blocs.

The converter reads each block to the end before moving to the next. It is therefore possible to thread several consecutive blocks, for example, threading by section. However, for large documents, it is best to avoid threading the entire document: overly long threads can slow down InDesign.

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

Do not embed images

InDesign allows you to manage images in two ways: either by linking them to an external file (for later assembly) or by embedding them. Embedding images significantly increases the size of the IDML file, and currently, this image management mode is not supported by the converter. It is possible to unembed a linked file to make an IDML file convertible.

Notes, 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

IDML file metadata is currently ignored by the converter.