How to correctly render Markdown content as HTML and display mathematical formulas and flowcharts in the Anqi CMS template?
The content is the soul of the website, and how to present these contents efficiently and beautifully is a topic that every operator cares about.In Anqi CMS, using Markdown to write content can not only greatly improve writing efficiency, but also easily achieve complex formatting needs, such as inserting mathematical formulas and drawing flowcharts. This is undoubtedly a powerful feature for technical blogs, educational websites, or corporate websites that need to display complex business processes.
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.
First, enable the Markdown editor
In Anqi CMS, enabling Markdown is the first step to achieving these cool effects.You just need to log in to the back end, go to the "Global Settings" under the "Content Settings" page, and here you can find and enable the Markdown editor.After completing this setting, you can directly use Markdown syntax to create articles, pages, and other content when publishing or editing.
Prepare the template for rendering
Markdown content, especially involving mathematical formulas and flowcharts, needs to be parsed and rendered on the front-end page through additional JavaScript libraries. The Anqi CMS template system is based on the Django template engine syntax, files are usually named with.htmlwith suffix, and stored uniformly in/templateIn the directory. You may have a file namedbase.htmlwhich contains the common header of the website (<head>) and the footer area. We will be working on the page's<head>Introduce necessary external resources within the tag to ensure that all pages can correctly render these special content.
Add styles to Markdown content
To make the HTML content rendered by Markdown have good readability and aesthetics, we can introduce a universal Markdown style library, such as
github-markdown-cssThis style library can make your Markdown content display in a style similar to GitHub on the web.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" />Let mathematical formulas leap off the page.
If you need to display complex mathematical formulas in content, MathJax is a very powerful solution that can render LaTeX, MathML, and other formats of mathematical expressions into high-quality typesetting effects.
Similarly, in
base.htmlof<head>Add the MathJax CDN reference within 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, such as inline formulas
$\alpha + \beta = \gamma$or a standalone formula block$$\sum_{i=1}^{n} i = \frac{n(n+1)}{2}$$They will all be correctly rendered by MathJax.Draw a clear flow chart.
Flowcharts are an excellent way to demonstrate business logic and algorithm steps.Mermaid is a Markdown-based flowchart and diagram tool that allows you to create various charts using simple text syntax.
In
base.htmlof<head>Within the tag, add the Mermaid CDN reference and its initialization script immediately after MathJax:<script type="module"> import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs'; mermaid.initialize({ startOnLoad: true }); </script>After configuration, use the Mermaid syntax block (for example
mermaid` ...`) to draw a flowchart in your Markdown content.
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.).
Template tags of Anqi CMS, such asarchiveDetail/categoryDetailorpageDetailUsed to obtain detailed information about different types of content. Where,ContentThe field usually carries Markdown formatted text.
By default, if you have enabled the Markdown editor in the background, the system is retrievingContentWhen a field is rendered, 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=trueParameter (recommended for main content fields)When you callContentwhen a field is added, it can be annotatedrender=trueParameter, explicitly indicating the system to perform Markdown to HTML conversion. For example:{% archiveDetail articleContent with name="Content" render=true %} {{ articleContent|safe }}Here
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, then|renderThe filter will be your helpful assistant. It can convert any variable containing Markdown syntax to 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 it is usingrender=trueIs the parameter|renderFilter, the converted content is all in HTML format. To prevent the template engine from escaping HTML special characters again (for example, turning<to<)， resulting in the HTML code not being displayed correctly. You need to add it in the output so that the browser can recognize it as normal HTML structure and render it properly|safeFilter. In this way, the browser can recognize it as a normal HTML structure and render it.
Practice case: Display Markdown content on the page
Assuming you are editing a namedarticle_detail.htmlThe article detail page template. By combining 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 block,{% archiveDetail articleContent with name="Content" render=true %}The statement retrieves the Markdown format content from the current article,render=trueEnsure the parameter is converted to HTML then{{ articleContent|safe }}Output it securely to the page. While external CSS and JavaScript libraries will be responsible for styling the HTML content, 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 rare cases, network issues may affect the loading of resources.If your website has very high requirements for loading speed and stability, you can consider downloading these JavaScript and CSS files to the local server and distributing them through the static resource management function of Anqi CMS. - Content writing and testing:When writing mathematical formulas and flowcharts in Markdown, it is recommended that you first preview them in some online Markdown editors.