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 namedintroductionThe custom field, and I hope to write an introduction in Markdown format in this field.How can you correctly render Markdown content into HTML on the website front-end so that it appears in the page with rich formatting?This article will introduce how to easily achieve this goal.

Understanding 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.多行文本Custom fields of types, and when editing content, if you choose to enable the Markdown editor, you can enjoy the convenient formatting experience brought by Markdown in this field. For example, we have created a field namedintroductionEnter the title, list, or link in the field, and input the Markdown text containing it.

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

Get custom field content of Markdown

In AnQiCMS templates, there are usually two ways to get 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 directly,archiveDetailuse the tag to get its value:

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

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

{% 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 text to HTML that browsers can recognize, AnQiCMS provides a very practical filter:renderThis filter can parse Markdown syntax and convert it to the corresponding HTML structure.

However, using onlyrenderThe filter is not enough. For safety, the AnQiCMS template engine defaults to escaping all output content to HTML entities. This means that evenrenderFilter converts Markdown to HTML (for example<h1>标题</h1>），these HTML tags will also be escaped again&lt;h1&gt;标题&lt;/h1&gt;，The source code is still displayed on the page instead of 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 and does not need to be HTML entity escaped, and 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 is firstrender, thensafe:

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

a complete example

Let us take the above as anintroductionexample of a custom field, and see how to fully render it in a template:

Method one: directly getintroductionthe field 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 two: loop to get custom fields 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 the Markdown text, after| renderConverted to HTML structure, then through| safeEnsure these HTML can be normally parsed and displayed by the browser.

Configure Markdown editor (optional)

In order to better use the Markdown features, 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 during content editing.
  • Supports mathematical formulas and flowcharts: EnglishIf your Markdown content contains MathJax mathematical formulas or Mermaid flowcharts, you also need to include in the template'sbase.htmlthe file<head>Partly introduce the corresponding third-party JavaScript libraries and CSS styles, specific methods can refer to the relevant document description of AnQiCMS.

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

Common Questions (FAQ)

Q1: Why does the raw Markdown text instead of the rendered HTML appear when custom field content is directly output in the template?

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

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

Of course you can.|renderFilter is a general content rendering tool, as long as your custom field stores Markdown formatted text, whether it isproduct_description/activity_notesYou can use any other custom field, as well{{ 您的字段变量 | 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 applied correctly in the template.|render|safeFilter chain.

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

Yes, AnQiCMS's Markdown editor supports these advanced features. To display MathJax and Mermaid correctly on the front-end page, you need to add them in the template file.<head>部分引入相应的 JavaScript 库。AnQiCMS 提供了详细的文档 (English)help-markdown.md) 指导您如何在 (English)base.htmlAdd these CDN resources.Once configured correctly, the mathematical formulas and flowcharts included in your Markdown custom fields can be rendered perfectly on the page.