Content creators often choose Markdown as their preferred tool because it can organize content in a concise and clear manner, while also making it easy to achieve formatting effects.However, merely entering content in Markdown format in the background is not enough to allow the website front-end to correctly display them; we need some additional steps to ensure that this content is correctly rendered as HTML.This article will introduce in detail how to make Markdown content elegant in AnQiCMS templates and display it to users as HTML.

一、Ensure the Markdown editor is enabled on the backend

Firstly, for the template to correctly render Markdown content, the prerequisite is that the content itself is input in Markdown format.AnQiCMS knows that the flexibility of content editing is crucial, so it provides the Markdown editor option.

二、Apply Markdown rendering in the template

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

1. Auto-rendering for core content fields

For articles (archive）Categories（category）and single-page（page）etc., the core content models come withContentfields, the template tags of AnQiCMS have built-in Markdown rendering logic. When these contentsContentThe field stores Markdown format, you need to specify in the templatearchiveDetail/categoryDetailorpageDetailwhen calling tagsrender=trueParameter.

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

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

Here are therender=trueThe parameter tells the template engine,Contentto convert the content of the field from Markdown to HTML. At the same time,|safeThe filter is crucial, it indicates that the template engine outputs the converted HTML code as safe content directly, instead of escaping the special HTML characters (such as converting<to escape as&lt;），thus ensuring that the page can correctly display bold, links, images, and other HTML elements.

2. Use the generalrenderfilter to process any Markdown content

In addition to the core content field, we may sometimes 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, and you want this introduction to also support Markdown format.

AnQiCMS provided a generalrenderFilter, which can render HTML for any variable containing Markdown format. Its usage is very intuitive, simply apply the filter to the corresponding variable.

Suppose you have a custom fieldintroductionand it stores Markdown content, you can render it in the template using the following method:

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

Or, if you go througharchiveParamsThe tag has retrieved a custom field, for example, one namedparams.introduction.Valuea variable:

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

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

Three, Enhance Display Effects: Support Mathematical Formulas and Flowcharts

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

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

1. Correct display of mathematical formulas on the web page

To make mathematical formulas (such as LaTeX syntax) display correctly on web pages, you can use libraries like MathJax.base.htmlthe file<head>Label the following code in 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 flow chart on the web page

For Markdown flowcharts (such as Mermaid syntax), you can introduce the Mermaid.js library for rendering. Similarly,base.htmlthe file<head>Label the following code in 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>

Complete 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 the template tags arerender=trueparameters orrenderThe flexible application of filters, as well as the introduction of external JavaScript libraries for special elements (such as mathematical formulas and flowcharts).Master these skills, and 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.

Common Questions (FAQ)

1. How can 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 are usingarchiveDetail/categoryDetailorpageDetailwhen adding tagsrender=trueParameter, for example: {% archiveDetail articleContent with name="Content" render=true %}.
  • for custom fields or other Markdown contentmake sure you use|render|safeFilter combination, for example:{{ my_markdown_variable|render|safe }}.

2. Why is the mathematical formula or flowchart not displayed, but only the Markdown code?

This situation is mostly because you did not correctly introduce the corresponding third-party JavaScript library in the template. Please check the theme directory under yourbase.htmlFile (or any template file used as the basis for a page layout)<head>Part:

  • Mathematical formula: Make sure MathJax has been included.<script>Label.
  • Flowchart: Make sure Mermaid has been included.<script type="module">code block.
  • Also, make sure that the formula and flowchart syntax you use in Markdown is correct and conforms to the requirements of these libraries.

3. Markdown content with HTML tags (such as<b>) is displayed escaped, not directly parsed 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 parsed correctly by the browser, you need to add them when outputting the rendered content.|safefilter. 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.