HTML

:html

Compatible with DOCX, ODT and HTML templates. The generated document can be exported to 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>, <sup>, <sub>, <mark>, <code>, <kbd>, <samp>	Formatting Elements
Structure	<p>, <br>, <pre>	Structure Elements
Lists	<ul>, <ol>, <li>	List Elements
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

Notes

• Tags and attributes not listed above are ignored during conversion. Their content is still rendered as unformatted text.
• Each element must have a matching opening and closing tag. An unclosed tag (for example a <pre> without </pre>) produces invalid HTML.

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	Applies to
inline	Render HTML within the current paragraph without creating new paragraphs or line breaks. Learn more.	{d.value:html(inline)}	<a>, <b>, <strong>, <em>, <i>, <s>, <del>, <u>, <sup>, <sub>, <mark>, <code>, <kbd>, <samp>
nospace	Remove automatic spacing after HTML block elements. Learn more.	{d.value:html(nospace)}	<p>, <h1> - <h6>, <ul>, <ol>, <table>, <pre>
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. A style applied to the Carbone tag takes priority over the same property defined in the HTML content, learn more on Style Inheritance.

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, except on <mark> which always renders a yellow highlight
• Note: Additional CSS properties will be supported in future releases.

Page breaks (Learn More):

• break-before="page": Insert a page break before the 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>

Style Inheritance

HTML content automatically inherits the styles applied to the Carbone tag, 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".

Inherited styles

• Font family and font size
• Text color
• Background color
• Text alignment
• Text direction (RTL)

Priority

A style applied to the Carbone tag takes priority over the same property defined in the HTML content. If the tag does not define the property, the CSS provided in the HTML content applies, e.g. <p style="color:green">.

Paragraph Handling

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

Inline Option Example

Spacing Behaviors

An empty paragraph is automatically injected after each paragraph, heading, list, table and preformatted block (<pre>). It mimics the bottom padding applied by default by web browsers on these elements. Use the nospace option to remove the empty paragraph, and therefore the space, e.g. {d.content:html(nospace)}.

Nospace Option Example

Entities

The :html formatter supports the following entity formats:

• Named entities: &, ©,  , etc.
• Decimal numeric entities: ©, 😀
• Hexadecimal numeric entities: ©, 😀

Emoji characters are supported as literal Unicode or as numeric entities.

Tabs

Use the character entities   or   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 inches > 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".

Formatting Elements

Element	Rendering	Availability
<b>, <strong>	Bold
<i>, <em>	Italic
<u>	Underline
<s>, <del>	Strikethrough
<sup>	Superscript	Pre-release
<sub>	Subscript	Pre-release
<mark>	Yellow highlight (fixed color, not customizable)	Pre-release
<code>, <kbd>, <samp>	Monospaced font (Courier New)	Pre-release

Pre-release: add {o.preReleaseFeatureIn=5011000} to your template to enable these elements; without it, their content is rendered without formatting.

Structure Elements

Element	Rendering	Availability
<p>	Paragraph
<br>	Line break
<pre>	Preformatted text: monospaced font (Courier New), line breaks kept. With the inline option, line breaks become single spaces.	Pre-release

Pre-release: add {o.preReleaseFeatureIn=5011000} to your template to enable <pre>; without it, its content is rendered without formatting.

A blank paragraph is added after block elements such as <p> and <pre>, see Spacing Behaviors.

List Elements

<ul>, <ol> and <li> render as native bulleted and numbered lists in DOCX and ODT documents. No pre-release tag is required.

Element	Rendering
<ul>	Unordered list (bulleted)
<ol>	Ordered list (numbered)
<li>	List item

A blank paragraph is added after the list, see Spacing Behaviors.

Hyperlink Element

Use <a href="URL">link text</a> to insert a hyperlink. Only the href attribute is used; others (such as target) are ignored.

Carbone validates the URL before injecting it:

• The http:// or https:// protocol is optional; https:// is prepended when it is missing.
• A domain and a top-level domain are required (for example carbone.io).

An invalid URL is replaced with the default error URL https://carbone.io/documentation.html#hyperlink-validation. To set your own fallback, chain the :defaultURL formatter before :html:

{d.content:defaultURL('https://carbone.io'):html}

Image Element

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

• Source: The image source attribute can be a 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

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.2.0. To enable this functionality, add the following pre-release tag to your template: {o.preReleaseFeatureIn=5002000}. 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.

A blank paragraph is added after the table, see Spacing Behaviors.

Custom Theme

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

There are 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

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.