In AnQiCMS, Markdown is an efficient and widely popular content creation method.It allows creators to focus on the content itself with a concise markup syntax, without being troubled by complex layout tools.However, presenting these concise Markdown texts to the user in the browser requires collaborative processing between the AnQiCMS backend and the front-end template.Understanding this process can help you better utilize the content management capabilities of AnQiCMS, ensuring that your content is displayed in **status**.

Enable Markdown Editor: The First Step of Content Creation

Firstly, enabling Markdown editor in AnQiCMS backend is the foundation for writing content in Markdown.Generally, you can find the corresponding option to enable it under 'Global Settings' -> 'Content Settings'.This step is very important, it tells the system that you will use Markdown syntax to write the detailed content of articles, pages, or categories.Once enabled, after you input Markdown text in the main editing areas such as document content, page content, or category content, the system will recognize it and prepare for subsequent rendering.

For example, you enter in the article content:

# 欢迎来到 AnQiCMS
这是一个 **强大** 的内容管理系统。

- 部署简单
- 功能丰富
- 扩展性强

On the frontend page, we expect to see headings, bold text, and lists, rather than the original Markdown symbols.

Content writing and automatic parsing: Initial conversion from Markdown to HTML

When you enter Markdown content in the AnQiCMS editor and save it, the system will perform preliminary parsing and conversion of these contents in the background. For main content fields such as documents, pages, and categories,archive.Content/page.Content/category.Content），AnQiCMS 默认在启用 Markdown 编辑器后，会自动将 Markdown 文本转换为标准的 HTML 结构。This means that you do not need to manually perform the conversion operation, the system will intelligently complete this task.

For example, you can directly call the article content in the template:

<div>
    {{ archive.Content }}
</div>

At this time,archive.ContentThe variable already contains HTML code converted from Markdown.

Template layer rendering control: Ensure HTML is displayed correctly

Although AnQiCMS will automatically convert Markdown to HTML, some additional processing is still required on the frontend template level to ensure that the content is displayed correctly and securely.

1. Use|safeFilter prevents double escaping

Markdown 转换后的内容本质上包含 HTML 标签的字符串。如果在模板中直接输出这些字符串而没有做特殊处理，模板引擎可能会为了安全起见，将其中的</>This character is escaped as&lt;/&gt;. This will result in the page displaying the original HTML code, rather than the rendered visual effect.

Therefore, in the AnQiCMS template, any variable containing HTML content (including HTML converted from Markdown) must be used|safeFilter. This filter tells the template engine that the content in this variable is safe HTML and can be output directly without additional escaping.

The correct usage is:

<div>
    {{ archive.Content|safe }}
</div>

2. English|renderFilter manual control

In most cases, AnQiCMS will automatically handle Markdown rendering in the background. But if your Markdown content is stored in a custom field, or you need to control the rendering time more precisely,|renderThe filter comes into play.

For example, if you have customized a field namedintroductionto store a Markdown-formatted introduction:

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

Here are the|renderThe filter will force theintroductionVariable Markdown text is rendered as HTML. It also acceptsrender=trueorrender=falseparameters to more explicitly specify whether to render:

  • render=true：Force the conversion of content from Markdown to HTML.
  • render=false：Do not convert Markdown, return the original content directly.

For example, manually specify rendering:

<div>文档内容：{% archiveDetail archiveContent with name="Content" render=true %}{{archiveContent|safe}}</div>

3. Introduce external resources: full presentation of mathematical formulas and flowcharts

The basic Markdown syntax can be converted to HTML and displayed normally, but for more advanced features such as mathematical formulas (LaTeX) and flowcharts (Mermaid), simply converting to HTML is not enough.They need to be parsed and rendered on the browser side with the help of additional JavaScript libraries.

AnQiCMS's documentation explicitly mentions how to integrate these features, you need to include the corresponding CDN resources in the template,<head>partly:

  • Markdown Default Style (optional, for beautification):To make the rendered Markdown look more beautiful, you can introduce Markdown CSS in GitHub style.
    
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/5.2.0/github-markdown.min.css" crossorigin="anonymous" referrerpolicy="no-referrer" />
  • 数学公式 (MathJax):如果您的内容包含 LaTeX 格式的数学公式，需要引入 MathJax 库。
    
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
  • 流程图 (English):如果您的内容包含 English 流程图语法，需要引入 Mermaid 库并初始化。
    
<script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
</script>
    These introductions are usually placed in the template of your website.base.htmlThe file (or similar file responsible for header introduction) of.<head>Tags to ensure they are executed when the page is loaded.

Summary

In AnQiCMS, Markdown content is correctly rendered as HTML from the editor input to the front-end page, which is a smooth process completed by the backend processing and front-end template collaboration. By enabling the Markdown editor on the backend, utilizing the system's automatic Markdown to HTML conversion, and using the front-end template reasonably|safeand|renderFilter, as well as on-demand external rendering libraries (such as MathJax and Mermaid), you will be able to ensure that all Markdown content, whether it is plain text, code blocks, or complex mathematical formulas and flowcharts, can be presented to visitors in a clear, beautiful, and fully functional manner.

Common Questions (FAQ)

1. Why does the Markdown content I post display the original Markdown syntax in the front-end, rather than the rendered HTML?

This is usually because you forgot to use|safefilters. Markdown text is converted to HTML, and if it is not|safeProcessing, the template engine will escape the HTML tags again for security reasons, causing them to be displayed as raw code. Ensure that your content variable is immediately followed by|safefor example{{ archive.Content|safe }}.

2.My article contains mathematical formulas or flowcharts, but only the original LaTeX or Mermaid code is displayed on the front end without graphical representation. Why is that?

AnQiCMS is solely responsible for converting these special Markdown syntaxes to basic HTML structures, but their graphical rendering depends on JavaScript libraries on the browser side. You need to add them to the website template's<head>Area introduces the corresponding CDN resources, such as MathJax (used for mathematical formulas) and Mermaid (used for flowcharts) libraries, and ensures they are correctly initialized.The specific code introduction can be referred to in the relevant documents of AnQiCMS.

**3. I entered Markdown content in the custom model field, but it did not automatically render like the document content.