Markdown templates

Carbone supports Markdown as both an input template and an output format, enabling you to generate PDFs, DOCX, ODT, PNG, JPG, and other formats directly from Markdown templates. Since large language models like ChatGPT, Claude, and DeepSeek natively output Markdown, Carbone is the ideal bridge between AI-generated content and professional documents, turning raw LLM output into polished, data-injected deliverables in a single API call.

Markdown templates support a wide range of features, including substitutions, repetitions, formatters, translations, conditions, and all enterprise features, making them a lightweight and versatile choice for automated document generation.

Basic

Carbone needs 2 elements to generate a document:

• A JSON data: coming from your application / database / API (e.g. the following JSON)
• A Markdown Template: made from any text editor 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.

The d in {d.user.firstName} refers to the root of your JSON data. The path after d (e.g., user.firstName) must match the structure of your JSON. You can use any valid Markdown structure; Carbone will only replace the tags with the corresponding data.

Loops

Loops in Carbone allow you to repeat a section of your template for each item in an array from your JSON data. In Markdown templates, loops are supported inside tables. Insert the loop tags inside table cells, and place the end iterator tag in the following row.

A loop in Carbone requires two tags:

• Start Tag: Marks the beginning of the repeated block (e.g., {d.users[i].id}). The i is the loop iterator (automatically managed by Carbone).
• End Tag: Marks the end of the repeated block (e.g., {d.users[i+1]}). The end tag i+1 does not refer to an actual array item but signals the end of the pattern. This row is removed from the final output.

All content (text, Carbone tags, and styles) between the start and end rows is repeated.

Unlike traditional programming, Carbone loops do not require keywords like "for" or "foreach". The loop is defined implicitly by the tags.

Conditions

Three methods are available to conditionally show, hide, or style elements in your Markdown templates. Each method is suited to different use cases, depending on the complexity of your conditions and the structure of your content:

• Inline Conditions: Use Carbone's conditional formatters to show or hide inline content based on a data field.
• Conditional Blocks: Use :showBegin/showEnd or :hideBegin/hideEnd for showing or hiding large sections of content, including multiple paragraphs, tables, or headings.
• HTML Blocks in Markdown: Support for :drop(), :keep(), and CSS injection via embedded HTML elements is coming soon.

Inline Conditions

Carbone supports inline conditional logic directly within Markdown content. Use the :ifEQ, :show, and :elseShow formatters to render different values based on your data.

Conditional Sections

The pair of :showBegin/:showEnd and :hideBegin/:hideEnd formatters allow you to conditionally display a section of content in your Markdown templates. These formatters are useful when you want to show or hide whole groups of paragraphs, tables, or headings based on data conditions. Syntax:

• :showBegin or :hideBegin: Marks the start of a block to show/hide if the condition is true.
• :showEnd or :hideEnd: Marks the end of the block.

showBegin / showEnd Example

The details section containing a list is hidden using the showBegin/showEnd formatters, only if the showDetails field is true.

hideBegin / hideEnd Example

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

Drop / Keep via HTML Blocks

Pictures

Dynamic pictures allow you to inject images into your documents using data from your JSON input. In Markdown templates, use the standard Markdown image syntax with a Carbone tag as the src:

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

Carbone supports the following image sources:

• Absolute URLs (e.g., https://carbone.io/img/carbone-logo.svg). Carbone does not support relative paths (e.g., /images/logo.png or ../assets/photo.jpg).
• Data-URIs (Base64 encoded, e.g., data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD...).

To control image dimensions, use an HTML <img> tag directly in your Markdown template (Markdown supports inline HTML):

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

Charts

Colors

You can dynamically set text colors and styles in your Markdown templates using Carbone tags combined with inline HTML. Since Markdown itself has limited native styling, use HTML <span> or <div> elements for color control.

Formatters

Carbone provides built-in formatters to transform data values directly inside your Markdown templates. Formatters are chained to a Carbone tag using the : operator (e.g. {d.value:formatterName(args)}). The sections below cover the most commonly used formatters for dates, numbers, and currencies. For the full list of available formatters, see the Formatters documentation.

Date Formatting

Use the :formatD() formatter to display dates in any format. The pattern follows Day.js tokens (e.g. YYYY, MM, DD, dddd).

For the full list of supported date patterns and options, see the Date formatter documentation.

Number Formatting

Use the :formatN() formatter to control decimal precision and thousands separators. The output format automatically adapts to the lang option passed at render time.

For the full list of options, see the Number formatter documentation.

Currency Formatting

Use the :formatC() formatter to display monetary values with the correct currency symbol, decimal precision, and locale-aware formatting.

For the full list of supported currencies and options, see the Currency formatter documentation.

Custom Styling

Barcodes

Hyperlinks

You can dynamically set the URL in Markdown links using Carbone tags. This is useful for generating personalized or data-driven links.

Inject HTML in Markdown

Page Breaks

Table of Content

Convert Markdown to PDF

Using Carbone with AI-generated content: LLMs like ChatGPT, Gemini and Le Chat (Mistral) natively output Markdown. A typical workflow is: prompt your LLM to generate a structured document → inject dynamic fields with Carbone tags (e.g. {d.clientName}, {d.date}) → call the Carbone API with your JSON data to render the final PDF or DOCX. This is particularly effective for automated reports, personalised proposals, AI-drafted contracts, and weekly summaries.

To generate a PDF from a Markdown template using the Carbone API, follow this workflow:

1. Prepare Two Files: Create a Markdown Template (with Carbone tags e.g. {d.name}) and a JSON dataset to populate the template.
2. Generate a PDF. You have three options:
   • Use the official Carbone integrations for platforms like N8N, Make, Zapier, Airtable, or Bubble.
   • Or, Use one of the Carbone SDKs (Node.js, Go, Python, Java, JavaScript, or PHP).
   • Or, Send a POST /render/template HTTP request to the Carbone API. Here's an example using curl:

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 dataset used to populate the template.
convertTo	The desired 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.

Unlike HTML templates, Markdown templates do not support PDF conversion options (paper size, margins, headers, footers, etc.). For advanced PDF layout control, use an HTML template instead.

Translations and i18n

Carbone can generate documents in any language from a single Markdown template. Instead of maintaining one template per language, you define a localization dictionary and pass a lang option at render time — Carbone automatically substitutes all translated strings.

Two mechanisms are available:

• {t( )} for static text in the template (labels, headings, fixed strings).
• :t formatter for dynamic text values coming from your JSON dataset (translated via a dictionary key).

Locale-aware formatters such as :formatD(), :formatN(), and :formatC() automatically adapt their output to the target language as well.

The localization dictionary can be passed directly in the API request body (translations field). For the complete reference including CLI tools and dictionary generation, see the Translations i18n documentation.

Comments

Carbone processes all text in your Markdown template, including HTML comments (<!-- -->). If you include Carbone tags (e.g., {d.user.name}) inside comments, they will be evaluated and replaced with data before the Markdown is rendered.

Best Practices for Notes: If you must include Carbone tags in comments for taking notes, you can "escape" them by breaking the syntax so Carbone won't interpret them: <!-- Note: Use d.user.name (escaped) for the username -->.