HTML

:html

Compatible with ODT, DOCX, HTML and PDF.

The :html formatter converts HTML content into native document formatting for DOCX and ODT templates, enabling rich text, structured layouts, and semantic document elements. List of Supported HTML Elements:

Category	Elements	Documentation
Text formatting	<b>, <strong>, <i>, <em>, <u>, <s>, <del>	/
Structure	<p>, <br>	/
Lists	<ul>, <ol>, <li>	/
Headings	<h1>,<h2>,<h3>,<h4>,<h5>, <h6>	Heading Elements
Tables	<table>, <tr>, <th>, <td> (with colspan, rowspan)	Table Element
Links	<a href="...">	Anchor Element
Media	<img src="...">	Image Element

Note: Unsupported tags and attributes are ignored during conversion.

Usage

Note: The :html formatter renders the HTML content in a new paragraph. To inject HTML in the current paragraph, enable the inline mode.

Options

Option	Description	Usage	Supported Elements
inline	Render HTML within the current paragraph without creating new paragraphs or line breaks. Example	{d.value:html(inline)}	<a>, <b>, <strong>, <em>, <i>, <s>, <del>, <u>
nospace	Remove automatic spacing after HTML block elements. Example	{d.value:html(nospace)}	All supported elements
headingtheme	Apply custom heading styles using a theme prefix. Learn More.	{d.value:html(headingtheme:custom-)}	<h1> - <h6>
tabletheme	Apply custom table style (DOCX only). Learn more.	{d.value:html(tabletheme:GridTable2)}	<table>

Note: Options can be combined by separating them with commas, e.g., {d.value:html(nospace,headingtheme:custom-)}

CSS Styles

The :html formatter supports inline CSS styling via the style attribute on HTML elements.

Example of inline style attributes

<p style="color:green;background-color:#FF00FF"><b>OK</b></p> 

Supported CSS Properties
Text and background colors:

• color: Text color
• background-color: Background color
• Note: Additional CSS properties will be supported in future releases.

Page breaks (Learn More):

• break-before="page": Insert a page break before paragraph
• break-after="page": Insert a page break after the paragraph

Not supported
External stylesheets, <style> elements, CSS classes, and IDs are ignored.

Supported Color Formats

Format	Description	Examples
Hexadecimal	Six-digit hex notation (RGB)	#FF00BB, #faebd7
RGB	Red, green, blue values (0-255)	rgb(31 120 50), rgb(31,120,50)
HSL	Hue, saturation, lightness	hsl(120deg 75% 25%), hsl(120 75 25), hsl(120,75,25)
Named colors	CSS color keywords	red, blue, lightseagreen (full list)

Page Breaks

The :html formatter supports CSS page break properties to control pagination. Page break properties currently apply only to Paragraph Elements (<p>).

Enabling Page Break Support

This is a beta feature since version 5.2.0. To enable this functionality, add the following pre-release tag to your template: {o.preReleaseFeatureIn=5002000}. Without this tag, page break styles are ignored.

Example Usage

<!-- Page break before paragraph -->
<p style="break-before: page;">This paragraph starts on a new page</p>

<!-- Page break after paragraph -->
<p style="break-after: page;">This paragraph ends the page</p>

Font Inheritance

HTML content automatically inherits font properties from the template paragraph, where it's inserted. For example, if you apply "Noto Sans" font at 20px to a Carbone tag, e.g. {d.content:html}, the injected HTML content will render using "Noto Sans" at "20px", regardless of any font styling in the HTML itself.

Note: Carbone does not retain text alignment for the rendered HTML content.

Paragraph Handling

When the HTML tag is placed inside a paragraph and mixed with other content, the content will be pushed in a new paragraph above or below the rendered HTML, e.g. HTML Usage. Use the inline mode, to inject the HTML inside a paragraph, e.g. HTML Inline Example.

Tab Entities

Use the character entities &ensp; or &emsp; to create a tab. Avoid using 	, as HTML parsers will collapse it into a single space due to the whitespace collapse principle. To control tab spacing in text editors:

• LibreOffice: Select the paragraph where the HTML formatter is > Right Click > Click on "Paragraph" > Paragraphs… > Click on the "Tabs" tab > Define a position value in Inch unit > Save.
• MS Word: Select the paragraph where the HTML formatter is > Right Click > Paragraph > Click on the "Tabs…" button at the bottom of the menu > Change the default stops or add a new tab stop > Save by clicking on "OK".

Hyperlink Element <a>

When the anchor tag <a href="URL"> is included, Carbone verifies the URL format before injecting it into the document. Learn more about hyperlink validation.

Image Element <img>

Embed images in documents using the <img> tag. The source and sizing attributes are required:

• Source: The image source attribute can be an URL or Data-URL, such as <img src="https://carbone.io/img/favicon.png"/> or <img src="data:image/jpeg;base64,/9j...."/>
• Sizing: The image size is determined by the width and height attributes provided in the HTML tag, such as <img src="" width="300" height="100"/>. These values must be in pixels. If the width or height attributes are missing, a default size of 5 cm (1.96 inches) is applied while retaining the image's aspect ratio.

Table Element <table>

HTML table elements enable structured data presentation with rows, columns, and cell spanning in both DOCX and ODT formats.

Enabling Table Support

This is a beta feature since version 5.0.9. To enable this functionality, add the following pre-release tag to your template: {o.preReleaseFeatureIn=5000009}. Without this tag, table content renders as a single paragraph.

Supported Elements and Attributes

Structural elements:

• Table container <table>, Table rows <tr>, Header cells <th>, Data cells <td>.
• Cell spanning: Merge cells horizontally colspan attribute, and vertically rowspan attribute.

Not supported: <tbody>, <thead>, <caption> - These elements are ignored during conversion.

Dimensions

Tables render at 100% of document body width with columns distributed evenly by default.

Custom Theme

Tables use the "TableGrid" style (black solid borders) unless customized. Custom themes are available only for DOCX template only. It is not available for ODT template due to technical format constraints.

It exists 2 solutions to provide a theme, in priority order:

1. Explicit theme via tabletheme option: {d.content:html(tabletheme:GridTable2-Accent3)}
2. Define a Document default theme (if set in template) in Microsoft Word:
   • Insert a temporary table in your DOCX template
   • Go to Table Design tab
   • Right-click a theme → Set as Default → This Document Only
   • Delete the temporary table and save
   • The generated table will take the default table theme!
3. Default theme: "TableGrid" (used if no other theme is specified).

Heading Elements

The HTML heading elements (<h1>, <h2>, <h3>, <h4>, <h5>, <h6>) enable semantic document structure and support automatic table of contents generation in both DOCX and ODT formats.

Enabling Heading Support

This is a beta feature since version 5.2.0 To enable this functionality, add the following pre-release tag to your template: {o.preReleaseFeatureIn=5002000}. This feature flag also enables Table HTML Element support. Without this tag, heading content renders as plain paragraphs

Document Heading Mapping

HTML headings map to document styles with preserved semantic structure:

HTML	DOCX/ODT Style	Use Case
<h1>	Heading1	Main title, chapter titles
<h2>	Heading2	Major sections
<h3>	Heading3	Subsections
<h4>	Heading4	Sub-subsections
<h5>	Heading5	Detailed breakdowns
<h6>	Heading6	Lowest level headings

Spacing Behaviors

By default, an empty paragraph is inserted after each heading to mimic web browser spacing behavior. To remove it, use the "nospace" option with the HTML formatter, e.g., {d.content:html(nospace)}.

Custom Heading Themes

Apply custom styling to headings using the headingtheme option: {d.content:html(headingtheme:theme-custom-)} This tells Carbone to use your custom styles (theme-custom-1, theme-custom-2, etc.) instead of the default heading styles. The formatter automatically appends the heading level (1-6) to your prefix. To create custom heading styles in your document editor:

Microsoft Word:

1. Home → Styles pane → New Style
2. Set "Name" to theme-custom-1 (or theme-custom-2, etc.) Note: Missing styles fall back to defaults.
3. Set "Style" based on to the corresponding default heading (Heading 1, Heading 2, etc.)
4. Customize formatting, font, sizing, colors, and click OK.
5. Use in template: {d.content:html(headingtheme:theme-custom-)}

LibreOffice Writer:

1. Press F11 (or Format → Styles) → Right-click Headings → New
2. Set Name to theme-custom-1 (or theme-custom-2, etc.) Note: All heading levels (1-6) must have corresponding styles, or rendering will fail.
3. Set Inherit from to the corresponding default heading (Heading 1, Heading 2, etc.)
4. Customize formatting, font, sizing, colors, in the Font tab and click OK.
5. Use in template: {d.content:html(headingtheme:theme-custom-)}

Headings Limitations

For DOCX Templates Only: Heading elements within list items (<ul>, <ol>) are converted to styled text with list formatting rather than semantic headings, due to Microsoft Word format constraints.

Inject HTML in HTML

The :html formatter allows you to inject raw HTML content into HTML templates without encoding, preserving all tags and CSS styles. Example template:

<html>
  <body>
    <h3 style="font-size:15px">Customer Testimonials</h3>
    {d.content:html}
    <p>This is additional content around the injected HTML.</p>
  </body>
</html>

Learn more: HTML templates documentation.

HTML Nospace Example

HTML Inline Example