Next, we will explore how to correctly render Markdown content as HTML in the Anqi CMS template, and elegantly display your mathematical formulas and flowcharts.
Firstly, enable the Markdown editor
In AnQi CMS, enabling the Markdown feature is the first step to achieve these cool effects.You just need to log in to the backend, go to the "Content Settings" page under "Global Settings", and here you can find and enable the Markdown editor.After completing this setting, you can directly use Markdown syntax to create content when publishing or editing articles, pages, and other content.
Prepare the rendering environment for the template
Markdown content, especially involving mathematical formulas and flowcharts, requires additional JavaScript libraries to parse and render on the front-end page. The template system of Anqi CMS is based on Django template engine syntax, files are usually in.htmlFor suffix, and stored uniformly/templateThe directory. You may have a file namedbase.htmlwhich contains the common header and footer of the website.<head>We will discuss on the page.<head>Label the necessary external resources within the tag to ensure that all pages can correctly render these special contents.
Add style to Markdown content
To ensure that the HTML content rendered by Markdown has good readability and aesthetics, we can introduce a universal Markdown style library, such as
github-markdown-cssThis style library allows your Markdown content to be displayed on the web with a style similar to GitHub.In
base.htmlof<head>Add the following code 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" />Make mathematical formulas come to life on paper.
If you need to display complex mathematical formulas in content, MathJax is a very powerful solution that can render mathematical expressions in LaTeX, MathML, and other formats into high-quality typesetting effects.
Similarly,
base.htmlof<head>Add the MathJax CDN reference inside the tag,<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>Now, you can use LaTeX syntax to write formulas in Markdown content, for example, inline formulas
$\alpha + \beta = \gamma$or independent formula blocks$$\sum_{i=1}^{n} i = \frac{n(n+1)}{2}$$They will all be correctly rendered by MathJax.Draw a clear flow chart
The flowchart is an excellent way to display business logic and algorithm steps.Mermaid is an English-based Markdown diagram and chart tool that allows you to create various charts using simple text syntax.
In
base.htmlof<head>Tags inside, followed by MathJax, add Mermaid's CDN reference and its initialization script:<script type="module"> import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs'; mermaid.initialize({ startOnLoad: true }); </script>Configuration completed, use Mermaid syntax blocks (such as
mermaid` ...`) in your Markdown content to draw flowcharts.
Display Markdown content correctly in the template
Now, when your backend and frontend templates are ready, let's focus on how to convert Markdown content into HTML that can be rendered by the browser on specific pages (such as article detail pages, single pages, etc.).
Auto CMS template tags, such asarchiveDetail/categoryDetailorpageDetail, used to get detailed information of different types of content. Among them,Contentfields usually carry text in Markdown format.
By default, if you have enabled the Markdown editor in the background, the system will getContentWhen a field is set, it will attempt to automatically convert Markdown to HTML. But for more precise control, or when you need to render Markdown in other custom fields, Anqi CMS provides two flexible methods:
Use
render=true参数（Recommended for main content fields）When you callContenta field, you can addrender=trueparameters to explicitly instruct the system to perform Markdown to HTML conversion. For example:{% archiveDetail articleContent with name="Content" render=true %} {{ articleContent|safe }}Here are the
articleContentThe variable will contain HTML converted from Markdown.Use
|renderFilter (for any variable containing Markdown)If your Markdown content is stored in a custom field, or if you want to render only specific content while globally disabling the Markdown editor,|renderThe filter will be a good helper. It can convert any variable containing Markdown syntax into HTML. For example, suppose you have a variable namedintroductionThe custom field contains Markdown:{% archiveDetail introduction with name="introduction" %} {{ introduction|render|safe }}
An important reminder:Whether usingrender=trueThe parameter is still|renderFilter, the converted content is all in HTML format. To prevent the template engine from escaping HTML special characters again (for example, converting <with<），导致HTML代码无法正确显示，您需要在输出时加上|safe过滤器。这样，浏览器才能将其识别为正常的HTML结构并进行渲染。
Practice Case: Displaying Markdown Content on a Page
Suppose you are editing a file namedarticle_detail.htmlThe article detail page template. Combined with the steps mentioned earlier, your template might look like this:
{# 假设这是您的文章详情页模板：/template/default/article_detail.html #}
{# 继承基础模板，基础模板中已引入必要的CDN资源 #}
{% extends 'base.html' %}
{% block title %}
<title>{% tdk with name="Title" siteName=true %}</title>
{% endblock %}
{% block head_extra %}
{# 如果您的CDN资源是直接在base.html中引入，这里可以省略。
如果是在block中引入，确保其在<head>内。 #}
<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" />
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>
{% endblock %}
{% block content %}
<article class="markdown-body"> {# 添加 markdown-body 类以应用 GitHub Markdown 样式 #}
<h1>{% archiveDetail with name="Title" %}</h1>
<div class="article-meta">
<span>分类: <a href="{% categoryDetail with name='Link' %}">{% categoryDetail with name='Title' %}</a></span>
<span>发布日期: {% archiveDetail with name="CreatedTime" format="2006-01-02" %}</span>
<span>浏览量: {% archiveDetail with name="Views" %}°</span>
</div>
<div class="article-content">
{# 获取文章内容并确保渲染Markdown为HTML且安全输出 #}
{% archiveDetail articleContent with name="Content" render=true %}
{{ articleContent|safe }}
</div>
{# 如果您有自定义Markdown字段，例如一个叫 'supplementary_info' 的字段 #}
{% archiveDetail supplementaryInfo with name="supplementary_info" %}
{% if supplementaryInfo %}
<div class="supplementary-section">
<h2>补充信息</h2>
{{ supplementaryInfo|render|safe }}
</div>
{% endif %}
</article>
{% endblock %}
In this code,{% archiveDetail articleContent with name="Content" render=true %}The statement retrieves the Markdown format content from the current article,render=trueParameters ensure that they are converted to HTML, then{{ articleContent|safe }}Translate it to English.While the CSS and JavaScript libraries externally introduced are responsible for styling these HTML contents, rendering mathematical formulas, and flowcharts.
Some practical suggestions
- Stability of CDN resources:The CDN link used in the above example (
cdnjs.cloudflare.comandcdn.jsdelivr.netIt is usually stable and reliable, but in very few cases, network issues may affect the loading of resources.If your website has very high requirements for loading speed and stability, consider downloading these JavaScript and CSS files to your local server and distributing them through the static resource management feature of Safe CMS. - Content writing and testing:When writing mathematical formulas and flowcharts in Markdown, it is recommended that you preview them in some online Markdown editors first.