The markdown directive is a custom FreeMarker directive implemented in Fanurio that allows you to convert a block of Markdown text into HTML. It works as a wrapper around the commonmark-java library that renders text according to the CommonMark specification.
It is particularly useful when notes, descriptions, or other texts are written using Markdown syntax but need to be rendered seamlessly inside HTML documents like reports or invoices.
If you are new to Markdown, this quick interactive tutorial covers the basics.
This directive does not accept any parameters. The content to be converted must be placed entirely within the body of the directive.
[@markdown] ### Project Overview This is the first paragraph. It introduces the project updates and demonstrates how standard text blocks are automatically converted into separate HTML paragraph elements. In this second paragraph, we can emphasize text easily. For instance, we can highlight an **extremely critical milestone** using bold text, or point out *minor stylistic changes* using italics. Here is a breakdown of the core project features: * **Performance:** Up to 40% faster rendering times. * *Compatibility:* Seamless integration with existing legacy templates. * **Portability:** Fully compliant with the [CommonMark Specification](https://commonmark.org/). If you have any questions or want to see the full repository, check out the [Official Website](https://commonmark.org/) for extra resources. [/@markdown]
The above Markdown text will be converted into the following HTML text:
<h3>Project Overview</h3>
<p>This is the first paragraph. It introduces the project updates and demonstrates how standard text blocks
are automatically converted into separate HTML paragraph elements.</p>
<p>In this second paragraph, we can emphasize text easily. For instance, we can highlight an
<strong>extremely critical milestone</strong> using bold text, or point out <em>minor stylistic changes</em> using italics.</p>
<p>Here is a breakdown of the core project features:</p>
<ul>
<li><strong>Performance:</strong> Up to 40% faster rendering times.</li>
<li><em>Compatibility:</em> Seamless integration with existing legacy templates.</li>
<li><strong>Portability:</strong> Fully compliant with the <a href="https://commonmark.org/">CommonMark Specification</a>.</li>
</ul>
<p>If you have any questions or want to see the full repository, check out the
<a href="https://commonmark.org/">Official Website</a> for extra resources.</p>If you prefer to write your notes and descriptions with Markdown, you can easily render them as formatted HTML by wrapping the placeholder variable inside the body of the [@markdown] directive.
Because FreeMarker automatically escapes HTML characters (like < and &) in placeholders, you must append the ?no_esc built-in to the variable. This ensures the raw Markdown string is passed cleanly to the directive for conversion.
Let's assume you write the description for one of your projects in Markdown like this:
Review the immediate requirements: * Complete **Phase 1** integration tests. * See the [Deployment Guide](https://example.com/deploy).
If you include it in a template using the standard ${project.description} placeholder (which inserts standard <br/> line breaks for every new line), the resulting document will produce the following raw HTML text:
Review the immediate requirements:<br/> * Complete **Phase 1** integration tests.<br/> * See the [Deployment Guide](https://example.com/deploy).
But if you place the ${project.description} placeholder inside the markdown directive like [@markdown]${project.description?no_esc}[/@markdown], the Markdown syntax will be converted to HTML to produce a much cleaner, more expressive text:
<p>Review the immediate requirements:</p> <ul> <li>Complete <strong>Phase 1</strong> integration tests.</li> <li>See the <a href="https://example.com/deploy">Deployment Guide</a>.</li> </ul>