How to correctly render Markdown formatted content in AnQiCMS templates?
In AnQiCMS templates, correctly rendering Markdown content is a key factor for website operators to enhance content presentation and editing efficiency.Markdown is a lightweight markup language that is favored by content creators for its simplicity, readability, and ease of writing.The AnQiCMS system not only supports the creation of Markdown content, but also provides a flexible template rendering mechanism to ensure that this content is 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 function in AnQiCMS, you first need to make relevant settings in the background.Staff should go to the "AnQi CMS backend" under the "Global Settings" menu, then enter the "Content Settings" page, where you 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, thereby 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 files,Contentfield, such as{{ archive.Content|safe }}Its Markdown syntax is converted to the corresponding HTML structure.
AnQiCMS also provides a more refined control method, allowing you to use template tags in therenderParameters to manually control whether Markdown content is converted to HTML. This parameter acceptstrueorfalsetwo values. For example, when usingarchiveDetailtags to call article content, you can explicitly specifyrender=trueConvert Markdown to HTML orrender=falseKeep 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, for security reasons and to prevent potential XSS attacks, it is usually necessary to use in conjunction with displaying HTML content converted from Markdown|safeThe 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.
It may not be enough to convert Markdown to HTML to meet all content display needs, especially when it comes to complex mathematical formulas or flowcharts.AnQiCMS allows integration with third-party JavaScript libraries to further enrich the rendering effects of Markdown content.These enhanced features are usually implemented in the common header template file of the website (for examplebase.htmlAdd the corresponding CDN resource link to achieve this, so that these functions take effect throughout the site.
Apply Markdown default style
To render Markdown content with better visual effects and readability, such as GitHub-style Markdown, you can introduce an external CSS file. In yourbase.htmlin the file<head>Add the following CDN link inside the tag:
<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" />
This way, all text rendered with Markdown will automatically apply GitHub-style CSS.
Correctly displays mathematical formulas
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.Similarly, atbase.htmlthe file<head>Add MathJax CDN script within the tag:
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
After adding this script, Markdown content will contain mathematical formulas (for example, using$$...$$or$...$The enclosed LaTeX formula will be parsed and beautifully displayed when the page is loaded by MathJax.
Display the flowchart correctly
If your Markdown content needs to display flowcharts, sequence diagrams, Gantt charts, and so on, 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.Enable Mermaid support in the AnQiCMS template, please,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 includes Mermaid chart code blocks (for example, usingmermaid...When wrapped, these charts will be automatically rendered.
By following these steps, AnQiCMS users can create a variety of Markdown content and present it perfectly through the front-end template, be it standard text, exquisite style, complex formulas, or clear charts.
Frequently Asked Questions
Q1: Why is my Markdown content displayed as raw text on the page and not rendered as HTML?A1: There may be several reasons for this situation. First, please make sure that you have enabled the Markdown editor in the "Global Settings" -> "Content Settings" of the AnQiCMS background.If the editor is enabled, then when calling the content template tag, it is necessary to confirm that there is norenderthe parameter tofalseIt prevents Markdown from being converted to HTML. Additionally, please check if your template code is using it correctly.|safeFilter, for example{{ archiveContent|safe }}To ensure that the browser recognizes the content as HTML.
Q2: I have alreadybase.htmlWhy are mathematical formulas and flowcharts still not displaying normally after adding CDN links for MathJax and Mermaid?A2: Even after adding CDN links, 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$...$packaging, while the Mermaid chart needs to be placed inmermaid ...Blocks in. Moreover, check the browser console for any JavaScript errors that may cause the script to load or execute failed. Ensurebase.htmlThe script tag does not have syntax errors or is blocked by other JS scripts.
Q3: Does AnQiCMS support custom Markdown renderer behaviors, such as adding custom Markdown extensions?A3: The template system and Markdown rendering function of AnQiCMS mainly provide through built-in mechanisms and integration of existing libraries (such as MathJax and Mermaid). As mentioned in the documentation.renderThe parameter allows controlling the basic Markdown to HTML conversion.For deeper customization of Markdown parsing behavior (such as adding non-standard Markdown extensions), this usually requires modifying the backend code of AnQiCMS or integrating a more advanced Markdown processing library, which goes beyond the scope of direct operations at the template level.If there is such a need, it is recommended to consult the AnQiCMS development documentation or seek technical support for secondary development.