4. Formatting Guide

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.

Naming files and styles

To avoid any issues, it’s best to use only unaccented alphanumeric characters in your filenames and style names, for example:

❌ Mon super-étonnant fichier InDesign.indd
✔️ Mon_super_etonnant_fichier_InDesign.indd

Footnotes, lists, and alternative text

The converter supports footnotes, lists, and alternative text. 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 if the https:// was not present.

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 are currently ignored by the converter.