Change Log
Carbone Enterprise Edition is one major version ahead of the Community Edition.
v5.0.0-beta.14
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-5.0.0-beta.14
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-5.0.0-beta.14
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-5.0.0-beta.14
Contact us to enable all Enterprise Features [EE]
Release July 17th 2024
Support for SVG image templates (backend + Studio).
Update SVG by modifying specific attributes based on the provided data with these new formatters::svgUpdate(attrName, selectorValue, selectorType)
Updates an SVG attribute (e.g.,fill
,stroke
) of the selected SVG nodes.:svgSelectiveUpdate(attrName, attrValue, selectorType)
Selects SVG nodes and injects a value. This formatter works like the previous one but uses a selector as input instead of a direct attribute value.
Parameters:
attrName
: The SVG attribute to update. This can be:- A fixed string in quotes (e.g.,
fill
,stroke
). - A relative path to a property of the parent object (e.g.,
.siblingObj.id
).
- A fixed string in quotes (e.g.,
attrValue
: The attribute value(s) to insert into the SVG. (e.g., a color value like'#F00'
).selectorValue
: The value used to select the target SVG element(s). This can be:- A fixed string (e.g.,
10
). - A data path (e.g.,
.siblingObj.id
).
- A fixed string (e.g.,
selectorType
: The SVG attribute used to identify and select shape(s) to modify. Default:id *
. Options:id
: selects only the node with the exactid
.id > *
: selects the node and its direct children.id *
: selects the node and all its descendants.
Template example:
<!-- {d.myTable[].width:svgUpdate('width', .id)} --> <!-- {d.myTable[active=true].id:svgSelectiveUpdate('fill', .color)} --> <svg width="100%" height="100%" viewBox="0 0 596 842" version="1.1"> <circle id="B12" cx="220" cy="434" r="149" style="fill:#ebebeb;"/> <circle id="B10" cx="379" cy="232" r="122" fill="#ababab"/> <circle id="B11" cx="406" cy="638" r="95" fill="#ebebeb"/> </svg>
After data injection:
<svg width="100%" height="100%" viewBox="0 0 596 842" version="1.1"> <circle id="B12" cx="220" cy="434" r="149" style="fill:#ebebeb;" width="200"/> <circle id="B10" cx="379" cy="232" r="122" fill="#66a200" width="100"/> <circle id="B11" cx="406" cy="638" r="95" fill="#aa66aa" width="300"/> </svg>
Data sample
{ "id" : "B10", "myTable" : [ { "id" : "B10", "color" : "#66a200", "active" : true , "width" : 100}, { "id" : "B12", "color" : "#aa66aa", "active" : false , "width" : 200}, { "id" : "B11", "color" : "#aa66aa", "active" : true , "width" : 300} ] }
Only basic SVG shapes are updated:
rect
,circle
,line
,ellipse
,polygon
,polyline
, andpath
.
🚨 Major Release 🚨
All changes described below mainly concern developers who integrate Carbone Studio into their own solutions.
Some of these changes may evolve based on feedback from early users. For all other users, everything will continue to work as before (plugins, SDKs, API, document generation, etc.).[Studio] New Studio starting modes:
<carbone-studio carbone-mode="embedded">
embedded
(default): Displays only the designer page, without template version management. Intended for integrators embedding the Studio.light
: Same asembedded
, but with the Carbone title bar. This is the default Studio interface when opened in a browser without any database configured.full
: Displays all pages and full navigation. Available only if a database is defined (see below). This mode is the complete interface that will replace the Studio in the Cloud Edition.
[Studio] Add the ability to override fetch requests made by the Studio
const studio = document.createElement('carbone-studio'); window.addEventListener('DOMContentLoaded', function() { document.body.appendChild(studio); studio.setConfig({ fetchOverride : fetchHandler // Override fetch behavior in the Studio }); function fetchHandler(url, options) { console.log('Override fetch called:', url, options); const newOptions = { ...options, headers: { ...options.headers, 'X-From-Studio': 'true' } }; if (url.startsWith('/template/')) {} if (url.startsWith('/templates/')) {} if (url.startsWith('/render/')) {} return fetch(url, newOptions); } });
[Studio] New live reload behavior and new events for integrators embedding the Studio
When live reload is active and the user is editing a template, the Studio now sends ephemeral templates (technically, only
POST /render
is called, noPOST /template
).
When live reload is turned off, the user is prompted to save their changes.
They can view a list of their changes and switch between the previous and current template versions.
For integrators, a new event can be listened to in order to detect when the user clicks theSave
button:// Listen for the `template:saved` event to get the new template Id studio.addEventListener('template:saved', handler); // Event object: // { // detail: { // templateId: 'af42af42af42af42af42af42af42af42af42af42af42af42' // type : 'docx' // } // } // The `template:updated` event is still emitted, but it contains the template as a Base64 string (no template ID) studio.addEventListener('template:updated', handler); // Event object: // { // detail: { // dataURI : '', // template in base64 // type : 'docx' // } // }
[Studio] Customize Studio CSS theme
The component accepts a custom attribute where CSS variables can be passed to override default colors.
- Method 1: JavaScript
studio.setAttribute('carbone-theme', 'main { --primary: #000; }');
- Method 2: HTML
<carbone-studio carbone-theme="main { --primary: #000; }"></carbone-studio>
Here is a quick overview of all available CSS variables:
/* Beer CSS main colors - Material Design */ --primary:#a544c5; --on-primary:#ffffff; --primary-container:#eecafc; --on-primary-container:#350040; --secondary:#6b586b; --on-secondary:#ffffff; --secondary-container:#cac5ca; --on-secondary-container:#251626; --tertiary:#9e9e9e; --on-tertiary:#ffffff; --tertiary-container:#ffdad2; --on-tertiary-container:#32110c; --error:#ba1b1b; --error-container:#ffdad4; --on-error:#ffffff; --on-error-container:#410001; --background:#fcfcfc; --on-background:#1e1a1d; --surface:#f5f5f5; --on-surface:#1e1a1d; --surface-variant:#e8e5e9; --on-surface-variant:#1e1a1d; --outline:#a7a7a7; --inverse-surface:#323639; --inverse-on-surface:#f7eef3; --inverse-primary:#fbaaff; --inverse-on-primary: #371E73; --outline-variant: var(--outline); --surface-dim: #f4f4f4; --surface-bright: #fdf8fd; --surface-container-lowest: #ffffff; --surface-container-low: #f7f2f7; --surface-container: #fff; --surface-container-high: #ece7eb; --surface-container-highest: #e6e1e6; --active: rgba(0,0,0,.1); --overlay: rgba(0,0,0,.5); /* Studio tab colors */ --tab-preview-border-color: #999; --tab-border-color: #c0aabf; --tab-text-color: #999; /* JSON Editor colors */ --json-editor-active-line: rgb(235 204 255 / 27%); --json-editor-active-bracket: rgb(193 96 255 / 27%); --json-editor-search-match-selected: rgb(237 178 255 / 51%); --json-editor-search-match: rgb(255 211 0 / 35%);
- Method 1: JavaScript
[Studio] New JavaScript API for interacting with the embedded Studio
Get or set the rendering options in the Studio using the
studio.setRenderOptions(object)
andstudio.getRenderOptions()
functions.
CallingsetRenderOptions()
updates the user interface but does not trigger rendering events. A message will indicate to the user that the preview must be refreshed manually. Example:studio.setRenderOptions({ data : {}, // Object or Array complement : {}, // Object or Array enum : {}, // Object translations : {}, // Object lang : 'en-us', // Lowercase Language Culture Code timezone : 'Europe/Paris', // Timezone Identifier currencySource : 'EUR', // Currency CODE currencyTarget : 'EUR' // Currency CODE })
[Studio] Miscellaneous User Experience Improvements
- Improved drag-and-drop design: you can now also click the drop zone to upload a file
- Added support for dragging and dropping JSON directly into the JSON panel (automatically replaces the previously loaded JSON)
- Improved icon weight and colors
- Fixed a bug that caused double extensions when downloading the generated report
- Fixed various other bugs
- UX reworked with two clear actions, "New" button to create a new template, "Edit" button to update an existing template
- Warns users before leaving the Studio without saving their current work
- Fixed white page issue by respecting the
Accept-Encoding
header. Now supports Brotli, Gzip, and uncompressed requests
[Studio] New HTML Editor + HTML Viewer
Modify HTML templates directly from the Studio instead of using an external tool, with live reload. The Studio includes a lightweight WYSIWYG HTML editor. Ideal for playground use or quick edits to existing HTML templates. More features (such as image support) will be added in the future.
[Studio] New XML/TXT Viewer
A new viewer for previewing generated TXT and XML files directly in the Studio. The Studio now supports 3 viewers:
HTML
,PDF
, andXML/TXT
. It automatically selects the best viewer based on your template.⚡️ [Studio+Backend] Template management embedded in the On-Premise solution
A new parameter
databaseName: "database.sqlite"
can be defined in the configuration (or using the environment variableCARBONE_DATABASE_NAME
).If this database is set, it enables all features related to template management, including:
- Listing templates
- Storing metadata with templates
- Using both
templateId
(constant id) andversionId
- The full version of the studio
In this version, the database is stored in the
config/
directory.
This will change in the final release: the database will be stored like a template and automatically synchronized across multiple nodes if needed.[Backend] New API for managing templates
👋 Available only for:
- On-Premise version (Cloud support coming soon)
- When "stateful" mode is enabled - technically, if a database name is defined in the configuration
- Experimental use only: all existing data may be deleted in the next stable release
What problem does it solve?
- Allows keeping a "constant" template ID
- Lets you decide when a new version of a template is deployed to production
- Enables listing and managing all templates via the API
- Allows storing optional metadata (name, comment, etc.) and sample data alongside templates
- Unifies the user interface (Studio) between the On-Premise and Cloud versions
What's new?
All API endpoints now support two types of IDs when targeting a template:
Version ID
A SHA-256 hash of the template file, automatically generated by Carbone.
This is the default behavior in Carbone v2, v3, and v4.
It matches the filename of the template stored on disk (or S3).
Formerly calledtemplateId
in our documentation.Template ID A short and constant 64-bit ID, automatically generated by Carbone, and optionally defined by the user.
Multiple template versions can share the sametemplate ID
.
When calling endpoints with atemplate ID
(e.g.,POST /render/{ID}
), Carbone will use the latest deployed version (based on thedeployedAt
timestamp). The previous behavior is still available: you can callPOST /render
with theversionId
to target a specific version.
To summarize:
To maintain backward compatibility, this new method for storing templates is only enabled if the boolean
versioning: true
is set when creating a template viaPOST /template
. In that case, the response ofPOST /template
is updated to avoid confusion:Type No Versioning Versioning Enabled Carbone Version SHA-256 hash of the file templateId
– v5, v4, v3, v2 SHA-256 hash + random salt – versionId
v5 + versioning: true
64-bit constant ID – id
v5 + versioning: true
API updates summary
# Updated endpoints: POST /template # Create a new template or a new version of an existing template GET /template/{templateId-or-versionId} # Download the template file DELETE /template/{templateId-or-versionId} # Delete a template POST /render/{templateId-or-versionId} # Generate reports using templateId or versionId # New endpoints: PATCH /template/{templateId-or-versionId} # Update metadata: name, comment, tags, expireAt, deployedAt GET /templates # List all deployed templates and their versions GET /templates/categories # List all categories used in templates GET /templates/tags # List all tags used in templates
POST /template
- Adds the ability to store metadata along with the template.
- Allows attaching multiple template versions to the same
templateId
. - Lets you specify which version is currently deployed using
deployedAt
. When a report is generated using the new template ID, Carbone selects the template version with the highestdeployedAt
timestamp that is not in the future. - For backward compatibility, the new parameter
versioning: true
must be set in the request body to enable these features.
Request body:
{ // Required template : base64 or multipart/form-data, // Optional versioning : true, // Enables new versioning mode. Disabled if undefined or false, and if "id" is undefined id : "4242", // Template ID. Generated if not provided and versioning = true () name : "", // Template name comment : "", // Template comment tags : [], // List of tags samples : [], // Sample input data expireAt : 0, // UTC Unix timestamp; values ≥ 42000000000 (year 3300) are interpreted as "NOW". 0 means it never expires. deployedAt : 0 // UTC Unix timestamp; values ≥ 42000000000 (year 3300) are interpreted as "NOW". Value in the future are not allowed. }
Reponse body
The new response when
versioning = true
is used{ success : true, data : { id : "4242" versionId : "af42af42af42af42af42af42af42af42af42af42af42af42af42af42af42af42", type : "docx", size : 12012, createdAt : 21545451 } }
For backward compatibility, when
versioning
is set tofalse
or is undefined,
Carbone returns only the SHA-256 hash of the template file like in Carbone v4.{ success : true, data : { templateId : "af42af42af42af42af42af42af42af42af42af42af42af42af42af42af42af42" } }
PATCH /template/{templateId-or-versionId}
- Same documentation as
POST /template
, except: - Only the metadata fields
name
,comment
,tags
,expireAt
, anddeployedAt
can be modified. All other fields are ignored.
GET /template/{templateId-or-versionId}
Accepts both the new
templateId
and theversionId
(as in Carbone v4).GET /template/{templateId}
downloads the latest deployed template file (64-bit number).GET /template/{versionId}
downloads a specific version of the template (SHA-256 file hash).GET /template/{templateId}_sample.json
downloads the data sample stored with this template (used in the Studio).GET /template/{versionId}_sample.json
downloads the data sample stored with this specific version (used in the Studio).
DELETE /template/{templateId-or-versionId}
Accepts both the new
templateId
and theversionId
(as in Carbone v4).DELETE /template/{templateId}
deletes the latest deployed template and all its previous versions (64-bit number).DELETE /template/{versionId}
deletes only the specified version (SHA-256 file hash). Technically, Carbone updates theexpireAt
field when this endpoint is called and garbage-collects the template after a delay (default: 24 hours). This has the same effect as callingPATCH /template/{id}
withexpireAt = NOW
.
GET /templates
List all templates. By default, it returns all deployed template only, sorted by createdAt DESC, with expireAt > now
Reponse body
{ success : true, hasMore : false, // Whether or not there are more elements available after this set. If false, this set comprises the end of the list. nextCursor : "", data : [ { id : "4242", versionId : "af42af42af42af42af42af42af42af42af42af42af42af42af42af42af42af42", createdAt : 1751385172, expireAt : 0, deployedAt : 1751385172, size : 12012, type : "docx", name : "template name", comment : "comment" category : "clientA" tags : ["prod", "other"] } ] }
Query parameters
?id=number
filter by template id?versionId=number
filter by version Id?category=string
filter by category?includeVersions=boolean
By default equals to false, Use true to list all versions for a specific template Id?search=string
search in template name (fuzzy search), version Id (exact) or template id (exact)?limit=number
limit the number of items (100 by default)?cursor=string
A cursor to use in pagination.nextCursor
is an object ID that defines your place in the list. For example, if you make a list request and receive 100 objects withnextCursor=abcdef
, your subsequent call can includecursor=abcdef
to fetch the next page of the list.
v5.0.0-beta.13
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-5.0.0-beta.13
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-5.0.0-beta.13
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-5.0.0-beta.13
Contact us to enable all Enterprise Features [EE]
- Release: June 30th, 2025
- [EE] New features and improvements for the :html formatter available for ODT/DOCX/PDF:
- CSS Style Attributes: Added support for rendering inline CSS style attributes
color
andbackground-color
, even when the HTML is ininline
mode, for example:<p style="color:green;background-color:#ff0000">OK</p>
. Styles defined within a<style>
element, or those applied through classes and IDs, are not supported. If a color is already applied to the template paragraph, the CSS color style will override it. Supported color formats include:- Hexa: The hexadecimal color syntax of an sRGB color. Example:
#FF00BB
. - HSL: Expresses a color in the sRGB color space according to its hue, saturation, and lightness components. Examples:
hsl(120deg 75% 25%)
,hsl(120 75 25)
orhsl(120,75,25)
. - RGB: Expresses a color in the sRGB color space according to its red, green, and blue components. Examples:
rgb(31 120 50)
orrgb(31,120,50);
. - Named Color: The name of a color. Example:
red
,blue
,black
, orlightseagreen
.
- Hexa: The hexadecimal color syntax of an sRGB color. Example:
- Support for Optional End Tags: Optional end tags "p" and "li" are now supported. An example structure:
<ol><li><p>text<li><p>text2</ol>
. - Support Tab Entities: Include the character entities
 
or 
to create a tab in an ODT/DOCX/PDF. Do not use	
, as HTML parsers will collapse it into a single space due to the whitespace collapse principle. - Bug Fix: Fixed an issue with nested ordered/unordered list items mixed with empty paragraphs.
- CSS Style Attributes: Added support for rendering inline CSS style attributes
v5.0.0-beta.12
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-5.0.0-beta.12
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-5.0.0-beta.12
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-5.0.0-beta.12
Contact us to enable all Enterprise Features [EE]
- Release: June 27th, 2025
- [EE] Improved support for filling PDF forms:
- Ignore errors when the PDF form contains buttons or undefined text fields
- Accept
/Text
and/FreeText
annotations - Remove annotations that contain Carbone tags with the
:checkField
and:fillField
formatters
(previously, only tags with:check
and:fill
formatters were removed)
v5.0.0-beta.11
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-5.0.0-beta.11
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-5.0.0-beta.11
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-5.0.0-beta.11
Contact us to enable all Enterprise Features [EE]
Release June 17th 2025
[EE] Resolved an issue with the
:html
formatter whenol/ul
lists are mixed withbr
tags.[EE] 📄 PDF templates are supported to fill forms with your data. This is a low-level feature to update PDF forms. A more user-friendly solution will be available in the final version of the Studio. Three methods are available:
Place Carbone tags directly in the form fields
Insert Carbone tags into the text fields of your PDF form. Carbone replaces them with data from your dataset. Loops are allowed in text fields.Add annotations above the fields you want to update, using formatters like
:fill
,:check
, or:uncheck
. Carbone will:- Detect the form field below the annotation,
- Remove the annotation,
- Update the corresponding field. If the field is not found, an error is returned. In that case, move your annotation to make sure it overlaps the target field.
Examples:
{d.myText:fill}
fills the text field behind the tag.{d.myCondition:ifEQ(true):check}
checks the radio button or checkbox behind the tag.
Directly target form fields by name using formatters
Place Carbone tags anywhere in a PDF annotation using formatters like:fillField('fieldName')
or:checkField('fieldName')
. Examples:{d.text:fillField('fieldName')}
fills the text field with the provided value. It can also check a checkbox (any non-empty value will check it).{d.genre:ifEQ('boy'):show(male):ifEQ('girl'):show(female):fillField('fieldName')}
selects the corresponding option in a radio group ('male' or 'female'). If the option does not exist, an error is returned.{d.text:ifEQ(true):checkField('fieldName')}
checks the checkbox if the condition is true.
Known limitations:
- In the Studio, the embedded PDF viewer cannot display filled forms. To preview results, uncheck the "Use embedded PDF viewer" option in the preview panel.
- Currently, Carbone supports only Text fields, Radio buttons, and Checkboxes.
- Warning: The native macOS PDF viewer can break PDF forms that include radio buttons.
⚡️ Define custom HTML templates for PDF headers and footers, specifically for generated PDF with the Chrome converter (
converter: 'C'
). Templates must include the custom HTML elements<carbone-pdf-header>
and<carbone-pdf-footer>
, for example:<carbone-pdf-header> <div style="font-size:12px; font-family:Arial; width:100%; text-align:center;"> My Header text </div> </carbone-pdf-header> <carbone-pdf-footer> <div style="font-size:12px; font-family:Arial; width:100%; text-align:center;"> My footer text </div> </carbone-pdf-footer>
- Special tags can be used to show the current page number and the total number of pages:
- Current page number:
<span class="pageNumber"></span>
- Total number of pages:
<span class="totalPages"></span>
- Current page number:
- These sections can include Carbone tags, allowing your headers and footers to display dynamic content.
- They are processed correctly even if they are:
- Inside HTML comments (
<!-- -->
) - Hidden using CSS (
display: none
)
- Inside HTML comments (
- CSS styles must be inlined and placed directly inside the header and footer sections.
- Special tags can be used to show the current page number and the total number of pages:
👌 Change the output page format when converting from HTML to PDF using the Chrome converter (
converter: 'C'
). Add a custom HTML element called<carbone-pdf-options>
in your template:<carbone-pdf-options paper-size="A3" landscape="true" margin-bottom="2.5" />
This section can include Carbone tags
They are processed correctly even if they are:
- Inside HTML comments (
<!-- -->
) - Hidden using CSS (
display: none
)
- Inside HTML comments (
Below is a list of all available options:
Option Type Description landscape
boolean Paper orientation. Defaults to false
.display-header-footer
boolean Display header and footer. Defaults to false
, ortrue
if header/footer is providedprint-background
boolean Print background graphics. Defaults to true
.scale
number Scale of the webpage rendering. Defaults to 1
.paper-size
string Letter, Legal, Tabloid, Ledger, A0, A1, A2, A3, A4, A5, A6 paper-width
number Overwrite Paper width in inches. Defaults to 8.27
inches (A4)paper-height
number Overwrite Paper height in inches. Defaults to 11.7
inches (A4)margin-top
number Overwrite Top margin in inches. Defaults to 0.5
inches.margin-bottom
number Overwrite Bottom margin in inches. Defaults to 0.5
inches.margin-left
number Overwrite Left margin in inches. Defaults to 0.5
inches.margin-right
number Overwrite Right margin in inches. Defaults to 0.5
inches.page-ranges
string Paper ranges to print, e.g., 1-5, 8, 11-13
. Pages are printed in document order. No pageappears more than once. Empty string prints entire document. Invalid ranges are ignored. An error is thrown if start > end. prefer-css-page-size
boolean Prefer CSS-defined page size. Defaults to false
,in which case the content will be scaled to fit the paper size
v5.0.0-beta.10
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-5.0.0-beta.10
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-5.0.0-beta.10
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-5.0.0-beta.10
Contact us to enable all Enterprise Features [EE]
- Release May 16th 2025
- Includes changes from v4.25.9
v4.25.9
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-4.25.9
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-4.25.9
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-4.25.9
Contact us to enable all Enterprise Features [EE]
- Release May 16th 2025
- Fixed batch processing for On-Premise environments
- Added support for base64 data-URI in
appendFile
andattachFile
v5.0.0-beta.9
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-5.0.0-beta.9
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-5.0.0-beta.9
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-5.0.0-beta.9
Contact us to enable all Enterprise Features [EE]
- Release April 24th 2025
- Fix: The
:appendFile(position)
formatter now inserts pages in the correct order, as in v4.25.8
v4.25.8
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-4.25.8
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-4.25.8
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-4.25.8
Contact us to enable all Enterprise Features [EE]
- Release April 24th 2025
- The formatter
:appendFile(position)
now accepts a position parameter that determines where the external document is inserted in the generated output. Valid values for position are "start" (to insert at the beginning) and "end" (default, inserts at the end).
v5.0.0-beta.8
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-5.0.0-beta.8
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-5.0.0-beta.8
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-5.0.0-beta.8
Contact us to enable all Enterprise Features [EE]
- Release: April 22nd, 2025
- The formatter
:appendFile(position)
now accepts a position parameter that determines where the external document is inserted in the generated output. Valid values for position are "start" (to insert at the beginning) and "end" (default, inserts at the end). - Improved stability of signature position detection
- Detecting multiple signatures in large documents is now about 100 times faster
v5.0.0-beta.7
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-5.0.0-beta.7
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-5.0.0-beta.7
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-5.0.0-beta.7
Contact us to enable all Enterprise Features [EE]
- Release April 14th 2025
- Includes v4.25.7
- Print logs when Chrome fails to start.
- Avoid generating a public/private key pair when a public key is already provided via the
CARBONE_AUTHENTICATION_PUBLIC_KEY
orCARBONE_EE_AUTHENTICATION_PUBLIC_KEY
environment variable
v4.25.7
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-4.25.7
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-4.25.7
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-4.25.7
Contact us to enable all Enterprise Features [EE]
- Release April 14th 2025
- Fix: Prevent a crash when a barcode is empty and the
svg: true
option is used. - Fix: LibreOffice changed the default value of
ExportFormFields
. It used to betrue
, but in the latest version, it is nowfalse
. This release restores the previous default value to avoid breaking changes when generating PDFs with forms.
v5.0.0-beta.6
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-5.0.0-beta.6
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-5.0.0-beta.6
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-5.0.0-beta.6
Contact us to enable all Enterprise Features [EE]
- Release March 20th 2025
- Improved support for HTML5 templates. Side effect: Carbone adds a trailing slash to void elements (e.g.,
<br>
becomes<br/>
). - Studio updates:
- Show metrics in logs: time spent on merging, converting, and downloading images/files, as well as the size of downloaded images/files.
- Added an option to switch between all converters and an option to display the preview as HTML instead of PDF.
- ⚡️ New Document converters: Chrome for more robust HTML to PDF conversion, along with OnlyOffice and LibreOffice (default) for all other documents.
Now, you can choose from three different document converters, all managed directly by Carbone.
A newconverter
option is added in v5 to select the document converter in the studio or directly from the API:
Historically, when Carbone started, it automatically tried to detect a LibreOffice binary on the system for document conversion. Three new parameters have been added to control this behavior for LibreOffice, OnlyOffice, and Chrome. By defaults, Carbone starts with these values:{ "converter": "L", // L: LibreOffice (default), O: OnlyOffice, C: Chrome "convertTo": "pdf", "data": {} }
These parameters can also be set using the corresponding environment variables:libreOfficePath : 'auto', // Auto-detects LibreOffice. Leave empty to disable, or set "sofficeExecPath, pythonExecPath". onlyOfficePath : '', // Disabled. Use "auto" or set "x2tPath, AllFontsPath, fontPath". chromePath : '', // Disabled. Use "auto" or set "pathToChrome".
CARBONE_EE_LIBRE_OFFICE_PATH
,CARBONE_EE_ONLY_OFFICE_PATH
,CARBONE_EE_CHROME_PATH
More details will be available in the documentation. Carbone automatically manages multiple threads for each converter, ensures that all security barriers are active, manages timeouts, and more. Current Limitations for Chrome:- JavaScript execution is disabled.
- Only A4 format output is supported (more formats, with custom margins, headers, and footers, will be available in future releases).
- All outgoing traffic is limited to GET requests for documents, stylesheets, images, media, and fonts.
v5.0.0-beta.5
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-5.0.0-beta.5
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-5.0.0-beta.5
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-5.0.0-beta.5
Contact us to enable all Enterprise Features [EE]
- Release March 11th 2025
- Includes v4.25.6
- When the
:sign
formatter is used, the signatures array is accessible at the root of the object in the body response ofPOST /render
.{ "renderId" : "random-string.pdf", "signatures": [ { "data" : "Bob", "page" : 1, "x" : 72.1, "y" : 693.436 } ] }
v5.0.0-beta.4
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-5.0.0-beta.4
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-5.0.0-beta.4
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-5.0.0-beta.4
Contact us to enable all Enterprise Features [EE]
- Release February 18th 2025
- [EE] Improve the position values returned by the
:sign
formatter:- Return integers instead of floats. Since a point is 1/72 inch, integer precision is sufficient.
- Set the origin
(x = 0, y = 0)
at the top-left corner of the page to simplify integration with third-party solutions. - Define the x-axis as extending to the right and the y-axis as extending downward.
- Enhance the precision of the X/Y position by ensuring the returned position corresponds to the top-left corner of the tag.
- [EE] For DOCX and ODT templates, two new HTML formatter options are available:
- inline: Render HTML within the current DOCX paragraph, at the same location, without moving or adding paragraphs. This option will only render the following HTML tags:
a
,b
,strong
,em
,i
,s
,del
,u
. Other HTML tags are skipped and not rendered. Example usage:{d.value:html(inline)}
- nospace: Render HTML without adding extra DOCX paragraphs at the end of each
<p>
tags.
- inline: Render HTML within the current DOCX paragraph, at the same location, without moving or adding paragraphs. This option will only render the following HTML tags:
- [EE] For DOCX templates, the HTML formatter has been updated with the following improvements:
- Hyperlinks (a
a
tags) are now rendered in headers and footers. - Images (a
img
tags) are now rendered in headers and footers. - If the HTML contains ordered (
ol
) or unordered (ul
) lists, there is no need to pre-create a list in the template using your text editor. Carbone will render the list directly in the DOCX format without any manual intervention. - When injecting multiple HTML lists using the HTML formatter, numbered lists now maintain consistent ordering. Previously, numbering might continue across multiple different lists.
- Hyperlinks (a
- [EE] For ODT templates, the HTML formatter is now supported in headers and footers.
v5.0.0-beta.3
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-5.0.0-beta.3
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-5.0.0-beta.3
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-5.0.0-beta.3
Contact us to enable all Enterprise Features [EE]
- Release February 3rd 2025
- The new templating engine preserves line breaks in templates! Now, you can create CSV or TXT templates. It fixes line breaks in XLSX files.
- [EE] Added the
batchOutput
option to thePOST /render
endpoint, to allow returning a single assembled PDF file instead of a ZIP file during batch processing. Accepted values:pdf
orzip
(default). - [EE] New formatter
:sign
. This can be used with PDF generation to place signatures at specific positions in a document. ThePOST /render
endpoint returns additional details indicating where each signature should be placed in the final PDF, along with its associated data. This information can be shared with any third-party tool to manage the signature process. For example, if the template contains the tags{d.owner:sign}
and{d.buyer:sign}
, the API returns the following information:
In a standard PDF coordinate system, the origin{ "debug": { "signatures": [ { "data" : "Bob", // Content of {d.owner}. Can be a string, number, object, or array "page" : 1, "x" : 72.1, "y" : 693.436 }, { "data" : "Alice", // Content of {d.buyer} "page" : 1, "x" : 72.1, "y" : 693.436 } ] } }
(x = 0, y = 0)
is at the bottom-left corner of the page. The x-axis extends to the right, and the y-axis extends upward. The API returns an error, and the report is not generated in the following cases:- If the number of injected signatures exceeds 999.
- If a signature position cannot be determined.
The
:sign
formatter prints a text in the final document in the format "ʕ010". Our recommendation is to set the text color to white in the template to make it invisible in the generated PDF.
v5.0.0-beta.2
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-5.0.0-beta.2
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-5.0.0-beta.2
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-5.0.0-beta.2
Contact us to enable all Enterprise Features [EE]
- Release January 30th 2025
- 👋 This is a minor release. A major update is coming soon with exciting features such as Signatures, PDF Merging, a Chrome converter, and Markdown/HTML templates in just a few days.
- Fixed a crash that occurred during a graceful exit when the systemd watchdog was activated.
- Includes all fixes from v4 up to v4.25.3.
- Show an error message if the studio is not running in a secure context.
- Improved Studio:
- Added text search functionality with a search button and shortcuts:
Ctrl+F
(open search)Ctrl+G
(next occurrence)Shift+Ctrl+G
(previous occurrence)
- Fixed inconsistent icon widths.
- Added functionality to switch between data/complement/enum/translations.
- Replaced the save button with a refresh button.
- Scroll position in the JSON editor/viewer is now preserved.
- Optimized JSON parsing between JSON editors for better performance.
- Modifications are now preserved when switching between JSON editor and viewer modes.
- Fixed language icon display issues on Windows.
- Prevent leaving the JSON editor when an error occurs.
- Updated PDF.js from version 4.7.76 to 4.10.38.
- Reduced gaps between icons for better alignment.
- Improved the design of the page input field in preview mode.
- Added text search functionality with a search button and shortcuts:
v5.0.0-beta.1
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-5.0.0-beta.1
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-5.0.0-beta.1
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-5.0.0-beta.1
Contact us to enable all Enterprise Features [EE]
- Release December 17th 2024
- Includes v4.25.0
v5.0.0-beta.0
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-5.0.0-beta.0
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-5.0.0-beta.0
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-5.0.0-beta.0
Contact us to enable all Enterprise Features [EE]
- Release October 29th 2024
- Check out the full release notes is here
v4.25.6
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-4.25.6
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-4.25.6
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-4.25.6
Contact us to enable all Enterprise Features [EE]
- Release March 11th 2025
- It is no longer necessary to repeat array filters on all tags to filter a loop.
Now, if the filter is defined only on the
i+1
tag, it is applied globally to the entire loop. This change is activated only when the prerelease tag{o.preReleaseFeatureIn=4024000}
is set (by default in v5). To maintain backward compatibility, if at least one filter is defined on thei-th
part, the previous rule still applies.- Before:
{d.myArray[i, i>0].id} {d.myArray[i, i>0].name} {d.myArray[i+1, i>0]}
- After:
{d.myArray[i].id} {d.myArray[i].name} {d.myArray[i+1, i>0]}
- Before:
v4.25.5
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-4.25.5
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-4.25.5
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-4.25.5
Contact us to enable all Enterprise Features [EE]
- Release February 8th 2025
- Fix: Carbone did not escape some forbidden characters in XML when an array was printed in the template without using the
arrayJoin
formatter. This fix is activated only when the prerelease tag{o.preReleaseFeatureIn=4024000}
is set.
v4.25.4
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-4.25.4
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-4.25.4
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-4.25.4
Contact us to enable all Enterprise Features [EE]
- Release February 6th 2025
- Fix: Carbone tags in sheet names were not updated since v4.25.3
v4.25.3
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-4.25.3
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-4.25.3
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-4.25.3
Contact us to enable all Enterprise Features [EE]
- Release January 28th 2025
- Fixed an issue with corrupted XLSX files caused by defined range names.
- Accepts array filters with colons and
&
, such as{d.myArray[filter='string&with:colons'].id}
, when{o.preReleaseFeatureIn=4022011}
is activated. Note: Array filters with commas are still not supported in v4. This will be addressed in v5. - Formatters containing '&' do not print '&' in the generated document, when
{o.preReleaseFeatureIn=4022011}
is activated.
v4.25.2
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-4.25.2
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-4.25.2
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-4.25.2
Contact us to enable all Enterprise Features [EE]
- Release January 20th 2025
- [EE] Fixed some issues with the
:set
formatter when{o.preReleaseFeatureIn=4022011}
is activated, especially in combination with array filters and conditions. The fix resolves the following cases for:set
:{d.myArray[filter=2].val:set(d.result)}
: Stores the first valueval
found in the array that matches the array filterfilter=2
(Now the behavior is the same with or without:set
).{d.myArray[filter=2].val:ifEM:show(10):set(d.result)}
: Stores the first valueval
found that matches the filterfilter=2
, otherwise stores "10".{d.myArray[filter=2].val:ifEM:show(10):set(.newAttribute)}
: Adds a new attribute inmyArray
(copy of.val
), setting its value to "10" for all items inmyArray
that do not match the filterfilter=2
.
- The
:convCRLF
option is now supported in ODP templates. - [EE] For ODT/ODS templates, you can now create dynamic bookmarks. To add a dynamic bookmark to a template, right-click on the selected text, navigate to the 'Insert' menu, select 'Bookmark,' and then write the Carbone tag. The value can be a single tag
{d.bookmark}
or a loop expression{d.list[i].bookmark}
. Please note that the following characters are not allowed in a bookmark:/@*?",#
. - Fixed invalid metrics for
fetchImageTime
,fetchFileTime
,fetchImageBytes
v4.25.1
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-4.25.1
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-4.25.1
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-4.25.1
Contact us to enable all Enterprise Features [EE]
- Release December 19th 2024
- [EE] Fixed a random crash occurring when multiple documents fail to download while using
:appendFile
. - [EE] Fixed crash when using an invalid image URL in injected HTML
v4.25.0
Show download links
Binaries Getting started
Docker Getting started
- Ready to use:
carbone/carbone-ee:full-4.25.0
- Includes 2GB of fonts :
carbone/carbone-ee:full-fonts-4.25.0
- Only Carbone (without document converters) :
carbone/carbone-ee:slim-4.25.0
Contact us to enable all Enterprise Features [EE]
- Release December 9th 2024
- Add a new option to the API endpoint
POST /render/:idTemplate
. The query parameter?download=true
can be used to download the rendered report directly.- When this option is used, the file is not stored on our servers. A single API call is enough to download the file. There is no need to call
GET /render
. - Important: The
Content-Disposition
header changes based on the HTTP status:- If the status is 200 (OK):
Content-Disposition: 'attachment; filename="report.pdf"' Content-Type: 'application/pdf'
- For all other statuses:
The response remains in
application/json
format as before.
- If the status is 200 (OK):
- When this option is used, the file is not stored on our servers. A single API call is enough to download the file. There is no need to call
v4.24.2
- Release November 7th 2024
- [EE] Fix: Accept array filters with commas enclosed in quotes when using the
:set()
formatter with the prerelease tag{o.preReleaseFeatureIn=4022011}
in ODT templates (enabled by default in Carbone v5). - Fix: Prevent generating corrupted documents when a custom iterator contains a
null
orundefined
value in a loop (e.g.,{d[sort].id} -> {d[sort+1].id}
). This fix is activated only if{o.preReleaseFeatureIn=4024000}
(enabled by default in Carbone v5).
v4.24.1
- Release November 6th 2024
- [EE] Fix: the
:html
formatter in DOCX templates where the default template style might not have been applied. - [EE] Fix: Accept array filters with commas enclosed in quotes when using the
:set()
formatter with the prerelease tag{o.preReleaseFeatureIn=4022011}
.
v4.24.0
- Release October 25th 2024
- Accept
xls
(Excel 2003) template files only for document conversion. - [EE] Fix the
:html
formatter in ODT templates where ordered and unordered lists contain mixed line break tags. - [EE] Generate a fully compliant Factur-X PDF when the attached XML file is named 'factur-x.xml' (
:attachFile('factur-x.xml')
). It automatically detects the Conformance Level from the attached XML ('MINIMUM', 'BASIC WL', 'BASIC', 'EXTENDED', 'EN 16931') and adjusts the PDF metadata accordingly. Additionally, it setsSelectPdfVersion = 3
(PDF Version 3B) by default if not specified and if the output file is a PDF. - [EE] Add a
type
parameter to theattachFile(filename, type)
formatter to specify the PDF AFRelationship. Options fortype
include: "Source", "Data" (default), "Alternative", "Supplement", "Unspecified", "FormData", and "Schema". - Close all pending TCP connections on exit to prevent indefinite waiting times.
- Fix: Allow
:convCRLF
to be used after:aggStrD
and:aggStr
. - New formatter
:preserveCharRef
to preserve character references. By default, Carbone removes all forbidden characters before injecting data into XML (e.g.,&
,>
,<
,