IDML templates

Any IDML file can be a template. Design the document in Adobe InDesign, write Carbone tags in its text frames, tables and parent pages, and export it as InDesign Markup (File > Export > InDesign Markup (IDML)). Send your JSON data to the API: you get back an IDML file with the layout, styles and colors of the template, ready to open in InDesign and export to PDF.

Basic

Write a tag in a text frame to insert a value from the JSON data. In {d.name}, d is the root of the data and name is the path to the value. The value takes the formatting of its tag: paragraph style, character style, size and color, like the product name in 50 pt.

• Tags work in table cells, like the battery life, and on parent pages, like the dealer in the footer.
• A tag can be the URL of a hyperlink (Window > Interactive > Hyperlinks > New Hyperlink), like {d.dealer.url} on the website of the dealer.
• A line break in a value, like "12 Main St\nSpringfield", starts a new line in the same paragraph.
• Turn off typographer's quotes (Preferences > Type > Use Typographer's Quotes). Formatters need straight quotes, like :formatD('LL').
• All Caps is safe: InDesign displays {D.CATEGORY} in the header, but the file keeps the tag as typed, {d.category}.

Learn more about tags.

Loops

A loop repeats paragraphs for each item of an array. Write the [i] tags in the paragraphs to repeat, like {d.products[i].name}, and an [i+1] tag in the paragraph after them: {d.products[i+1].name}. Carbone repeats the paragraphs with their styles and removes the [i+1] paragraph.

• Give the [i+1] paragraph its own paragraph style, used by no paragraph around it, like Loop end. Otherwise an empty paragraph stays under the last item.
• The paragraph above the loop needs another style than the first repeated paragraph, like Columns here. Otherwise it is repeated too.
• Loops on table rows are not supported: InDesign ignores the copied rows. Align the columns with tab stops, like the prices.

Learn more about loops.

Nested loops

A loop can contain another loop. In this catalog, {d.lines[i].name} repeats the product lines, and {d.lines[i].items[i].name} repeats the products of each line. Write the two [i+1] tags in the same Loop end paragraph: {d.lines[i].items[i+1].name}{d.lines[i+1].name}.

The template has one page and the report has two: InDesign adds the pages, see Text flow.

Text flow

InDesign opens the report with the pages and frames of the template, and flows the text like in any document. Here, one story runs through the four badges, in threaded text frames. The first paragraph of each attendee starts in the next frame (Paragraph panel menu > Keep Options > Start Paragraph: In Next Frame), so each attendee gets a badge.

• New pages: turn on Smart Text Reflow (Preferences > Type) and put the text in a primary text frame. InDesign adds the pages when it opens the report in a window, like page 2 of the catalog.
• Frames that grow: a text frame with auto-sizing (Object > Text Frame Options > Auto-Sizing > Height Only) grows with its text.
• Overset text: text that does not fit stays hidden.

Conditions

Conditions print a value or remove paragraphs, depending on the data:

• Inline conditions print one value or another: {d.growth:ifGTE(0):show('+'):elseShow('−')} prints the sign of the growth, and {d.record:ifEQ(true):show('· Record year'):elseShow('')} labels a record year.
• Conditional blocks keep the paragraphs between :showBegin and :showEnd only when the condition is true. Write the begin tag at the end of the paragraph above the block, and the end tag at the end of its last paragraph. guidance is empty, so the Guidance update block is removed.

:hideBegin and :hideEnd remove a block when the condition is true. Learn more about inline conditions and conditional blocks.

Translations

Write static text in {t( )} tags, and add :t to translate values from the data, like the session types. Carbone uses the translations of the lang of the report. This example uses "lang": "fr-fr" and the dictionary of the Translations tab. Dates and amounts follow the language: :formatD('dddd D MMMM YYYY') prints jeudi 15 octobre 2026, and :formatC prints 290,00 €.

A translation can be longer than the original text: leave room in the frames, or let them grow with auto-sizing. Learn more about translations.

Best practices

• Use paragraph and character styles. A value takes the style of its tag, and loops find the paragraphs to repeat by their styles.
• Keep each tag in one style. Select the whole tag, braces included, before you change its font or color: a tag with two styles prints nothing.
• Anchor what must repeat. An icon or a rule placed inline in the repeated paragraphs, after the first [i] tag, repeats with them. A floating frame stays in place.
• Install the fonts where the report opens. An IDML file does not contain its fonts.

Automate an IDML file

To generate an IDML file from an IDML template with the Carbone API:

1. Prepare two files: an IDML template with Carbone tags, like {d.name}, and the JSON data to populate it. You can use the files of the Loops example.
2. Generate the IDML file in one of three ways:
   • Use an official Carbone integration, like N8N, Make, Zapier, Airtable or Bubble.
   • Use a Carbone SDK: Node.js, Go, Python, Java, JavaScript or PHP.
   • Send a POST /render/template HTTP request to the Carbone API, like this curl command:

curl --location --request POST 'https://api.carbone.io/render/template?download=true' \
  --header 'carbone-version: 5' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer API_TOKEN' \
  --data-raw "{
    \"data\": $(cat loops-data.json),
    \"template\": \"$(base64 -i loops-template.idml)\",
    \"lang\": \"en-us\"
  }" \
  --output report.idml

💡 Linux users: replace base64 -i loops-template.idml with base64 -w 0 loops-template.idml

Key parameters

Parameter	Description
template	Your IDML template, encoded as a Base64 string.
data	JSON data used to populate the template.
lang	Language of the report, used by the formatters and translations: "en-us" prints {d.price:formatC(0)} as $349.
convertTo	Omit it: an IDML template generates an IDML file.
?download=true	Query parameter to download the document as a stream.
Authorization	Header required for the Carbone Cloud API. Get your API key here.

For more details, refer to the Carbone API Documentation.