How to correctly render Markdown document content as HTML in a template?

Content creators often choose Markdown as their preferred tool because it can organize content in a concise and clear manner, while also easily achieving formatting effects.However, merely entering content in Markdown format in the background is not enough to allow the website's front end to display it correctly; we need some additional steps to ensure that the content is rendered as HTML properly.This article will introduce in detail how to make Markdown content turn into a beautiful transformation in AnQiCMS templates, and present it to users in the form of HTML.

One, make sure the Markdown editor is enabled on the backend

First, for the template to correctly render Markdown content, the content itself must be input in Markdown format.AnQiCMS knows that the flexibility of content editing is crucial, therefore it provides the Markdown editor option.

You need to navigate to the "Global Settings" -> "Content Settings" page in AnQiCMS backend.Here, you will find an option to enable Markdown editor.Check and save, then you can directly use Markdown format to enter when editing articles, pages, or category content.This step is fundamental, it ensures that the original data you input is in Markdown format, laying the foundation for subsequent rendering.

Two, apply Markdown rendering in the template

It is not enough to use Markdown format to input content only in the background, the template engine will not automatically parse all content into HTML.AnQiCMS offers several flexible ways to ensure that Markdown content is rendered correctly as HTML on the front end.

1. Automatic rendering for core content fields

For the article (archive）、Category（category) and single page (page)Core content model built-inContentfield, AnQiCMS template tags have built-in Markdown rendering logic. When these contentsContentWhen storing fields in Markdown format, you need to use the templatearchiveDetail/categoryDetailorpageDetailExplicitly set when calling the tagsrender=trueParameter.

For example, on the article detail page, you might call the article content like this:

{% archiveDetail articleContent with name="Content" render=true %}
{{ articleContent|safe }}

Hererender=trueThe parameter tells the template engine to handle theContentcontent of the field from Markdown to HTML conversion. At the same time,|safeThe filter is crucial, it indicates that the template engine should output the transformed HTML code as safe content directly, rather than escaping the HTML special characters (such as converting<Escape as<), so that the page can correctly display bold, links, images, and other HTML elements.

2. Use generic.renderFilter any Markdown content.

In addition to the core content fields, we may also want to use Markdown in custom fields or content from other sources.For example, you may have added a custom field named "Introduction" to the content model for an article, and you want this introduction to also support Markdown formatting.

AnQiCMS provides a generalrenderThe filter can render HTML for any variable containing Markdown format. Its usage is very intuitive, just apply the filter to the corresponding variable.

Suppose you have a custom fieldintroductionAnd it stores Markdown content, you can render it in the template in the following way:

{% archiveDetail introduction with name="introduction" %}
{{ introduction|render|safe }}

Or if you go througharchiveParamsThe tag obtained a custom field, such as a namedparams.introduction.Value：“

<div>
    {% archiveParams params with sorted=false %}
        {% if params.introduction %}
            <span>{{params.introduction.Name}}:</span>
            <span>{{params.introduction.Value|render|safe}}</span>
        {% endif %}
    {% endarchiveParams %}
</div>

By|render|safeThe combination, regardless of the content from which it comes, as long as it is in Markdown format, can be correctly converted to HTML and safely displayed on the page.

Enhance display effects: Support mathematical formulas and flowcharts

If you want to go further, you can also include complex mathematical formulas or beautiful flowcharts in your Markdown content, and AnQiCMS also provides corresponding extension support.These advanced features usually require the use of front-end JavaScript libraries to render.

You need to include these libraries in the template file<head>part, usually in the current theme of yourbase.htmlthe file.

1. Correct display of mathematical formulas on web pages

To display mathematical formulas (such as LaTeX syntax) correctly on the web page, you can use libraries like MathJax.base.htmlthe file<head>Add the following code to the tag:

<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

2. Correct display of the flowchart on the web page

For Markdown flowcharts (such as Mermaid syntax), you can introduce the Mermaid.js library for rendering. Similarly, inbase.htmlthe file<head>Add the following code to the tag:

<script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
</script>

After completing these configurations, as long as your Markdown content follows the corresponding syntax (such as MathJax's$$...$$or Mermaid'smermaid...Blocks), they will be correctly parsed and rendered on the front-end page.

Summary

In AnQiCMS template, the key to correctly render Markdown content is to enable the Markdown editor in the background and use template tags,render=trueorrenderFlexible application of filters, as well as the introduction of external JavaScript libraries for special elements (such as mathematical formulas and flowcharts).Master these skills, your website content will be presented to visitors in a more rich, vivid, and structured form, greatly enhancing the readability and visual appeal of the content.

Frequently Asked Questions (FAQ)

1. How do I make my Markdown content display as plain text without being converted to HTML?

This is usually because you did not correctly indicate AnQiCMS to perform Markdown rendering when calling content in the template. Please check your template code:

• For the core content field (such asContent), make sure you usearchiveDetail/categoryDetailorpageDetailtags, you have addedrender=truefor example:{% archiveDetail articleContent with name="Content" render=true %}.
• for custom fields or other Markdown content, make sure you use|render|safeFilter combination, for example:{{ my_markdown_variable|render|safe }}.

2. Why are mathematical formulas or flowcharts not displayed, but only Markdown code is shown?

This is most likely because you have not correctly introduced the corresponding third-party JavaScript library in the template. Please check the theme directory belowbase.htmlThe file (or other template file used as the page basic layout)'s<head>Part:

• a mathematical formulaEnsure MathJax has been included<script>.
• FlowchartEnsure Mermaid has been included<script type="module">code block."),
• At the same time, also confirm that the syntax of the formulas and flowcharts you use in Markdown is correct and meets the requirements of these libraries.

3. For example, HTML tags in Markdown content (such as<b>) are displayed as escaped, not directly interpreted as bold, how to deal with it?

This indicates that the template engine treats the rendered HTML content as plain text, usually to prevent potential security risks (such as XSS attacks). To have these HTML tags correctly parsed by the browser, you need to add|safea filter. For example:{{ articleContent|safe }}or{{ my_markdown_variable|render|safe }}.|safeThe filter tells AnQiCMS that you trust this HTML content is safe and can be output directly without escaping.