In AnQiCMS template, correctly rendering Markdown format content is a key factor in enhancing content presentation and editing efficiency for website operators.Markdown as a lightweight markup language, with its concise, readable and writable features, is deeply loved by content creators.AnQiCMS system not only supports the creation of Markdown content, but also provides a flexible template rendering mechanism to ensure that these contents are presented in the expected way on the front-end page, and can even integrate third-party libraries to display mathematical formulas and flow charts.

Enable and understand Markdown content editing

To make full use of the Markdown feature in AnQiCMS, you first need to make relevant settings in the background.The operation personnel should go to the 'Global Settings' menu of the 'AnQi CMS Backend' and then enter the 'Content Settings' page, where they can find and enable the Markdown editor.After enabling, the content editing area will allow you to write articles, pages, and category descriptions in Markdown syntax, thus achieving more efficient and structured content creation.

When the Markdown editor is enabled, the system will automatically convert the content entered through the Markdown editor to HTML format by default, so that it can be displayed correctly on the front-end page. This means that when you call articles, pages, or categories in your template file,ContentWhen the field is, such{{ archive.Content|safe }}, its Markdown syntax will be converted to the corresponding HTML structure.

AnQiCMS also provides more fine-grained control methods, allowing you to use template tags inrenderParameters to manually control whether Markdown content is converted to HTML. This parameter acceptstrueorfalsetwo values. For example, when usingarchiveDetailtags to call the content of the article, you can explicitly specifyrender=trueto perform Markdown to HTML conversion, orrender=falseto retain the original Markdown text without conversion.

The following code example demonstrates how to call document content in a template and control Markdown rendering:

{# 默认情况下，如果Markdown编辑器已启用，Content字段会自动渲染Markdown #}
<div>文档内容：{% archiveDetail with name="Content" %}{{archiveDetailContent|safe}}</div>

{# 明确指定进行Markdown转换 #}
<div>文档内容：{% archiveDetail archiveContent with name="Content" render=true %}{{archiveContent|safe}}</div>

{# 明确指定不进行Markdown转换，内容将以原始Markdown格式显示 #}
<div>文档内容：{% archiveDetail archiveContent with name="Content" render=false %}{{archiveContent|safe}}</div>

Please note that for security reasons and to prevent potential XSS attacks, it is usually necessary to use in conjunction with the HTML content displayed by the Markdown conversion.|safeFilter. This filter informs the template engine that the output content is safe HTML and does not require additional escaping.

Enhance the display effect of Markdown content.

The conversion of Markdown to HTML may not be sufficient to meet all content display needs, especially when it comes to complex mathematical formulas or flowcharts.AnQiCMS allows the integration of third-party JavaScript libraries to further enrich the rendering effects of Markdown content.base.html）中添加相应的CDN资源链接来实现，从而使这些功能在全站范围内生效。

Apply Markdown default style

In order to make the rendered content of Markdown have better visual effects and readability, such as GitHub-style Markdown formatting, you can introduce external CSS files. In yourbase.htmlin the file<head>Tags within, add the following CDN link:

<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" />

In this way, all text rendered by Markdown will automatically apply GitHub-style CSS styles.

正确显示数学公式

For Markdown content that includes mathematical formulas, the MathJax library can be used for professional typesetting and display.MathJax can render mathematical formulas in LaTeX, MathML, or AsciiMath formats into high-quality images or text.base.htmlthe file<head>Tags inside, add MathJax CDN script:

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

After adding this script, mathematical formulas contained in Markdown content (such as using$$...$$or$...$The wrapped LaTeX formula) will be parsed and beautifully displayed on page load by MathJax.

正确显示流程图

If your Markdown content needs to display flowcharts, sequence diagrams, Gantt charts, and other similar diagrams, Mermaid is a very powerful JavaScript library.It allows you to define these charts using simple text syntax and render them as SVG on the web.base.htmlthe file<head>Add the following script inside 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>

This script will integrate Mermaid into your website. When Markdown content contains Mermaid chart code blocks (for example, usingmermaid...When wrapping）, these charts will render automatically.

Through the above steps, AnQiCMS users can create various and rich Markdown content, and present it perfectly through the frontend template, whether it's standard text, beautiful style, complex formulas, or clear charts.

Frequently Asked Questions

Q1: Why does my Markdown content display as raw text on the page without being rendered as HTML?A1: This situation may occur for several reasons.Firstly, make sure you have enabled the Markdown editor in the "Global Settings" -> "Content Settings" of the AnQiCMS background.renderparameter settingsfalseIt prevents Markdown from being converted to HTML. Additionally, please check if your template code is using it correctly.|safeFilter, for example{{ archiveContent|safe }}Q2: To ensure that the browser recognizes the content as HTML.

Q2: I have alreadybase.htmlEnglish added CDN links for MathJax and Mermaid, but mathematical formulas and flowcharts still cannot be displayed normally, why is that?A2: Even if CDN links are added, it is still necessary to ensure that your Markdown content uses the correct syntax supported by MathJax and Mermaid. For example, mathematical formulas usually need to be$$...$$or$...$package, while Mermaid charts need to be placed inmermaid ...English block. Moreover, please check the browser console for any JavaScript errors that may cause the script to fail to load or execute. Ensurebase.htmlThe script tag does not have syntax errors or is blocked by other JS scripts.

Q3: Does AnQiCMS support the behavior of custom Markdown renderers, such as adding custom Markdown extensions?A3: AnQiCMS的模板系统和Markdown渲染功能主要通过内置机制和集成现有库（如MathJax和Mermaid）来提供。文档中提及的EnglishrenderThe parameter allows control of the basic Markdown to HTML conversion.For deeper custom Markdown parsing behaviors (such as adding non-standard Markdown extensions), this usually requires modifying the backend code of AnQiCMS or integrating more advanced Markdown processing libraries, which is beyond the scope of direct template-level operations.If there is such a need, it is recommended to refer to the AnQiCMS development documentation or seek technical support for secondary development.