Markdown templates

Any Markdown file can be a template. Write Carbone tags in its text and tables, send your JSON data to the API, and convert the Markdown to PDF, DOCX, ODT, PNG or JPG. AI models write Markdown natively, so Carbone turns their output into finished documents.

Basic

Carbone needs two elements to generate a document:

• JSON data from your application, database or API, like the following JSON.
• A Markdown template written in any text or code editor. The following template includes Carbone tags: {d.user.firstName}, {d.user.lastName}, {d.user.email}, and {d.membershipLevel}. These tags will be replaced with the corresponding values from the JSON data.

In {d.user.firstName}, d is the root of the JSON data and user.firstName is the path to the value. This path must match the structure of your JSON. Use any valid Markdown structure: Carbone replaces only the tags and keeps the rest of the text.

Style

A Markdown template can take the look of a DOCX or ODT template: text styles, page, header and footer. Design your company layout once in Word or LibreOffice, and every Markdown document uses it, including reports drafted by an AI model.

1. Create the style template in Word or LibreOffice. Style the headings, the body text and the table text, then set up the page, header and footer.
2. Upload it in Carbone Studio or with the upload API. Copy its template ID to use the latest deployed version, or its version ID to use one exact version.
3. Add the tag {o.styleSource=ID} anywhere in the Markdown template, for example on the first line.

The style template sets:

• Text styles: the headings (Heading 1, Heading 2...), Body Text for paragraphs and list items, and Table Heading and Table Contents for the text in table cells. In Word, create the last two as paragraph styles with these exact names.
• Page: size, margins, header and footer, with their pictures and page numbers.

The style template is also a Carbone template. Its tags receive the data of the report, like {d.quarter} in the header. Its body is not copied into the report.

The style is applied when the Markdown template is converted to PDF. Table borders are not part of the style: tables keep thin black borders.

Loops

A loop repeats a part of the template for each item of an array in your JSON data. In Markdown templates, loops are supported inside tables. Insert the loop tags inside table cells, start the repeated row with its first tag (no leading |), and place the end iterator tag alone on the next line.

A loop needs two tags:

• Start tag: marks the beginning of the repeated block, like {d.users[i].id}. i is the loop iterator, managed by Carbone.
• End tag: marks the end of the repeated block, like {d.users[i+1]}. i+1 does not refer to an array item: it signals the end of the pattern. This line is removed from the final output.

All the content between the start and end tags is repeated: text, Carbone tags and styles.

Carbone loops need no keyword like "for" or "foreach". The tags define the loop.

Conditions

Conditions show or hide content based on the data:

• Inline conditions print one value or another in the text, with the condition formatters.
• Conditional sections show or hide several paragraphs, tables or headings, with :showBegin/showEnd or :hideBegin/hideEnd.
• HTML blocks with :drop() and :keep() are coming soon.

Inline conditions

Use :ifEQ, :show and :elseShow to print one value or another, depending on the data.

Conditional sections

Use :showBegin/:showEnd or :hideBegin/:hideEnd to show or hide a whole section, with its paragraphs, tables or headings, depending on the data:

• :showBegin or :hideBegin marks the start of the section to show or hide when the condition is true.
• :showEnd or :hideEnd marks the end of the section.

showBegin / showEnd Example

The showBegin/showEnd formatters show the details section, with its list, only if the showDetails field is true: here it is false, so the section is removed.

hideBegin / hideEnd Example

The greetings section is deleted when the field name is undefined/null/empty.

Drop / keep via HTML blocks

Pictures

Write a tag as the source of a Markdown image to insert a picture from the data:

![Alt text]({d.imageUrl})

The image source can be:

• An absolute URL, like https://carbone.io/img/carbone-logo.svg. Relative paths, like /images/logo.png or ../assets/photo.jpg, are not supported.
• A Base64 data URI, like data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD....

To set the size of the image, write an HTML <img> tag in the template:

<img src="{d.userProfile.profilePictureUrl}" width="200" height="auto" alt="Profile Picture">

Charts

The :chart formatter draws a chart from an ECharts configuration object in the data. Chain it to the tag of this object, and use the tag as the image source: Carbone replaces it with an SVG image of the chart.

Use an HTML <img> tag to set the width and height of the chart in the converted PDF, DOCX or ODT:

<img src="{d.chartOptions:chart}" width="600" height="400" alt="Sales Overview"/>

The Markdown image syntax ![Sales Overview]({d.chartOptions:chart}) also works, but it cannot set the size, and the chart appears as a very small image.

The top-level width and height properties of the ECharts configuration set the size of the generated image, not its size in the document. Set the size in the document with the width and height attributes of the <img> tag.

Learn more about charts.

Colors

Markdown has no syntax for colors. Write tags in the style attribute of an HTML element that starts the line, like <p> or <div>, to set the colors of the text from the data.

To color a word inside a sentence, put the <span> in a <p> element: <p>Status: <span style="color: {d.alertColor};">{d.status}</span></p>.

Formatters

Formatters transform a value before Carbone prints it. Chain them to a tag with :, like {d.value:formatterName(args)}. The sections below cover the most common formatters, for dates, numbers and currencies. For the full list, see the Formatters documentation.

Date formatting

:formatD() prints a date in the format of your choice. The pattern uses Day.js tokens, like YYYY, MM, DD or dddd.

For all the date patterns and options, see the Date formatter documentation.

Number formatting

:formatN() sets the number of decimals and adds the thousands separators. The output follows the lang option passed at render time.

For all the options, see the Number formatter documentation.

Currency formatting

:formatC() prints an amount with its currency symbol and decimals, formatted for the language of the report.

For all the currencies and options, see the Currency formatter documentation.

Barcodes

The :barcode(type) formatter draws a barcode from a value. type is the barcode symbology, like qrcode, ean13 or code128.

Use an HTML <img> tag to set the width and height of the barcode in the converted PDF, DOCX or ODT:

<img src="{d.productCode:barcode(qrcode)}" width="150" height="150" alt="Product QR code"/>

The Markdown image syntax ![Product QR code]({d.productCode:barcode(qrcode)}) also works, but it cannot set the size, and the barcode appears as a very small image.

Pass the barcode options as extra arguments, like {d.productCode:barcode(qrcode, includetext:false)}. Their width and height options set the size of the generated barcode, not its size in the document. Set the size in the document with the width and height attributes of the <img> tag.

Learn more about barcodes.

Hyperlinks

Write tags in the address or the text of a Markdown link to build personalized links from the data.

Inject HTML in Markdown

By default, Carbone encodes the < and > characters of a value, so HTML from the data, like {d.richText}, is printed as literal text. Add the :html formatter to render it as formatted content in the converted document.

Learn more about the :html formatter.

Translations and i18n

One Markdown template can generate documents in any language. Define a localization dictionary and pass the lang option at render time. Carbone replaces the text with its translation:

• {t( )} translates the static text of the template, like labels and headings.
• The :t formatter translates values from the JSON data, used as dictionary keys.

:formatD(), :formatN() and :formatC() follow the language too.

Pass the localization dictionary in the translations field of the API request body. For the complete reference, including the CLI tools and the dictionary generation, see the Translations i18n documentation.

Comments

Carbone reads all the text of the template, including HTML comments (<!-- -->). A tag inside a comment, like {d.user.name}, is replaced with data before the Markdown is rendered.

To mention a tag in a note, break its syntax so Carbone ignores it: <!-- Note: Use d.user.name (escaped) for the username -->.

Automate a Markdown file

Store the template once, then generate a Markdown file for each set of data. These commands use the files of the Style example.

1. Upload the template. Carbone returns its template ID in data.id:

curl --request POST 'https://api.carbone.io/template' \
  --header 'carbone-version: 5' \
  --header 'Authorization: Bearer API_TOKEN' \
  --form 'versioning=true' \
  --form 'template=@quarterly-report-template.md'

2. Generate the document with the template ID and the JSON data:

curl --request POST 'https://api.carbone.io/render/TEMPLATE_ID?download=true' \
  --header 'carbone-version: 5' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer API_TOKEN' \
  --data-raw "{ \"data\": $(cat quarterly-report-data.json) }" \
  --output report.md

Without convertTo, the report has the format of the template. To get a PDF or a DOCX, see Convert Markdown to PDF. Learn more about template storage.

Convert Markdown to PDF

Using Carbone with AI-generated content: AI assistants like ChatGPT, Gemini and Mistral Vibe write Markdown natively. Ask the assistant for a structured document, add Carbone tags for the dynamic fields, like {d.clientName} or {d.date}, then call the Carbone API with your JSON data to render the PDF or DOCX. It fits automated reports, personalized proposals, AI-drafted contracts and weekly summaries.

To generate a PDF from a Markdown template with the Carbone API:

1. Prepare two files: a Markdown template with Carbone tags, like {d.name}, and the JSON data to populate it.
2. Generate the PDF 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\": {},
    \"template\": \"$(base64 -i document.md)\",
    \"convertTo\": \"pdf\",
    \"converter\": \"L\"
  }" \
  --output result.pdf

💡 Linux users: replace base64 -i document.md with base64 -w 0 document.md

Key parameters

Parameter	Description
template	Your Markdown template, encoded as a Base64 string.
data	JSON data used to populate the template.
convertTo	Output format: pdf, docx, odt, jpg, png or md.
?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.

Markdown templates do not support the PDF conversion options of HTML templates, like the paper size, margins, headers and footers. Set them with a style template instead, or use an HTML template for advanced control of the PDF layout.