How to render the custom field `introduction` in Markdown content to HTML?

In AnQiCMS, custom fields provide us with great flexibility, allowing us to expand the content structure according to actual business needs. For example, you may have set up a field namedintroductionCustom field, and I hope to write a Markdown formatted introduction in this field.How can you correctly render these Markdown contents into HTML on the front end of the website, making it present rich formatting on the page?This article will detail how to easily achieve this goal.

Understand the custom fields and Markdown in AnQiCMS

One of the core strengths of AnQiCMS is its flexible content model.You can customize various fields for different content models (such as articles, products) in the background.When you create a多行文本Custom field of type, and when editing content, select Enable Markdown Editor, you can enjoy the convenient formatting experience brought by Markdown. For example, we created a field namedintroductionThe field, in which you entered Markdown text with headings, lists, or links.

By default, if you output the content of this custom field directly in the template, it will be displayed as plain text with the original Markdown syntax, rather than the formatting we expect.To make it display as a beautiful HTML format on the front end, we need to perform additional processing.

Get Markdown custom field content

In AnQiCMS templates, there are usually two ways to obtain custom field content: througharchiveDetailtags directly, or througharchiveParamstags in a loop.

If you know the name of the custom field (for exampleintroduction), you can use it directlyarchiveDetailusing the tag:

{% archiveDetail introductionContent with name="introduction" %}
<div>
    {{ introductionContent }}
</div>

Here, introductionContentthe variable will contain yourintroductionThe original Markdown text. If your content model defines multiple custom fields and you want to iterate through them, you can usearchiveParamsTags:

{% archiveParams params %}
<div>
    {% for item in params %}
        {% if item.FieldName == "introduction" %}
            <div>
                {{ item.Value }}
            </div>
        {% endif %}
    {% endfor %}
</div>

No matter which way, the output is still the original Markdown text.

Core: Render Markdown content to HTML

To convert these original Markdown texts into browser-readable HTML, AnQiCMS provides a very practical filter:render. This filter can parse Markdown syntax and convert it to the corresponding HTML structure.

However, simply usingrenderThe filter is not enough. For safety reasons, the AnQiCMS template engine defaults to escaping all output content as HTML entities. This means that evenrenderThe filter converts Markdown to HTML (for example<h1>标题</h1>), and these HTML tags will be escaped again<h1>标题</h1>Finally, it is still displayed on the page as source code, rather than the actual rendering effect.

To solve this problem, we need to use another important filter:safe.safeThe filter tells the template engine that this content is safe, no HTML entity encoding is required, and it can be output directly as HTML on the page.

Therefore, the key to rendering Markdown custom fields as HTML is to userenderandsafetwo filters. The order of their use isrender, thensafe:

{{ 您的Markdown变量 | render | safe }}

a complete example

Let's take the aboveintroductioncustom field as an example, let's see how to render it completely in a template:

Method 1: Directly obtainintroductionfield and render

<article>
    <h1>{{ archive.Title }}</h1>
    <div class="article-meta">
        <!-- 其他文章元数据 -->
    </div>
    <div class="article-introduction">
        <h2>文章简介</h2>
        {% archiveDetail introductionContent with name="introduction" %}
        {{ introductionContent | render | safe }}
    </div>
    <div class="article-content">
        <h2>文章详情</h2>
        {% archiveDetail articleContent with name="Content" %}
        {{ articleContent | safe }} {# 主内容字段通常已自动渲染，这里仅用safe确保输出 #}
    </div>
</article>

Method 2: Loop to obtain custom field and render

If you have many custom fields or are unsure of their specific names, you can use a loop and check the field names:

<article>
    <h1>{{ archive.Title }}</h1>
    <div class="article-meta">
        <!-- 其他文章元数据 -->
    </div>
    {% archiveParams customFields %}
    {% for field in customFields %}
        {% if field.FieldName == "introduction" %}
            <div class="article-introduction">
                <h2>文章简介</h2>
                {{ field.Value | render | safe }}
            </div>
        {% endif %}
        {# 如果有其他Markdown自定义字段，也可以在这里添加渲染逻辑 #}
        {% if field.FieldName == "additional_notes" %}
            <div class="additional-notes">
                <h3>补充说明</h3>
                {{ field.Value | render | safe }}
            </div>
        {% endif %}
    {% endfor %}
    <div class="article-content">
        <h2>文章详情</h2>
        {% archiveDetail articleContent with name="Content" %}
        {{ articleContent | safe }}
    </div>
</article>

In these examples,introductionContentorfield.ValueVariables store Markdown text, after| renderConverted to HTML structure, then through| safeEnsure that these HTML can be normally parsed and displayed by the browser.

Configure Markdown Editor (optional)

To better use the Markdown feature, you may need to make some settings in the AnQiCMS backend:

• Enable Markdown Editor:In后台->全局设置->内容设置Ensure that the Markdown editor is enabled. This way, your custom fields will support Markdown input when editing content.
• Supports mathematical formulas and flowcharts:If your Markdown content includes MathJax mathematical formulas or Mermaid flowcharts, you also need to include in the template'sbase.htmlthe file<head>Partially introduce the corresponding third-party JavaScript library and CSS styles, for specific methods, please refer to the relevant document description of AnQiCMS.

By following these steps, you can flexibly use Markdown custom fields in AnQiCMS, and render them perfectly into rich HTML content, greatly enhancing the quality and diversity of website content display.

Frequently Asked Questions (FAQ)

Q1: Why is the original Markdown text displayed instead of the rendered HTML when outputting custom field content directly in the template?

This is because of the default behavior of the AnQiCMS template engine.When you output a variable directly, it treats it as plain text and performs HTML entity escaping to prevent potential security issues (such as XSS attacks).Even if the field content itself is Markdown, it needs to be explicitly allowed.|renderThe filter converts it to HTML and uses|safeThe filter tells the template engine that this content is safe HTML, and it does not need to be escaped again to render correctly on the front end.

Q2: BesidesintroductionField, can I also render other custom fields that contain Markdown as HTML?

Of course you can.|renderThe filter is a general-purpose content rendering tool, as long as the custom field you store is in Markdown format, whether it isproduct_description/activity_notesany custom field, you can use it too{{ 您的字段变量 | render | safe }}The way to render it as HTML. The key is to ensure that the field content is valid Markdown text and that it is correctly applied in the template.|render|safeFilter chain.

Q3: If my Markdown custom field content includes MathJax mathematical formulas or Mermaid flowcharts, will they be rendered correctly?

Yes, AnQiCMS's Markdown editor supports these advanced features. To make MathJax and Mermaid display correctly on the front-end page, you need to include the template file's<head>Partially import the corresponding JavaScript library. AnQiCMS provides detailed documentation (help-markdown.md) guidance on how tobase.htmlAdd these CDN resources. Once configured correctly, the mathematical formulas and flowcharts contained in your Markdown custom fields can be perfectly rendered on the page.