How to correctly render Markdown content (including formulas, flowcharts) as HTML display in AnQiCMS?
AnQiCMS has always been committed to providing efficient and flexible solutions in content display. For the increasingly popular Markdown format in modern content creation, especially for complex content that includes mathematical formulas and flowcharts, AnQiCMS also provides a comprehensive support mechanism to ensure that these contents are correctly parsed and beautifully presented on the web.
To implement the correct rendering of Markdown format (including formulas and flowcharts) content, it mainly involves two aspects: Firstly, the internal HTML conversion of Markdown text in the AnQiCMS system, and secondly, the client browser further parses and renders these special elements (such as mathematical formulas and flowcharts) by introducing specific JavaScript libraries.
First step: Make sure the Markdown editor is enabled
Firstly, we need to ensure that the Markdown editor function of AnQiCMS backend is enabled.This is the foundation of content operation.You can log in to the AnQiCMS backend and find the 'Content Settings' option under 'Global Settings.'In here, there is usually an option to 'Enable Markdown Editor', make sure it is checked.After turning on, you can use Markdown syntax to create content when creating or editing documents (articles, products, single pages, etc.).
Second step: Markdown to HTML conversion within AnQiCMS
When you enter content in the Markdown editor on the AnQiCMS backend and save it, the system is responsible for converting this Markdown text into standard HTML structure when the content is published. This means that titles like#）、list（-), link ([]()）、image（”）et cetera basic Markdown syntax, AnQiCMS will automatically process and output the corresponding HTML tags.
For document content fields, for examplearchive.Content/category.Contentorpage.ContentThe template engine of AnQiCMS provides|renderA filter specifically used to ensure that content is correctly parsed as HTML when output. Although the system usually automatically handles most Markdown conversions after enabling the Markdown editor, it is explicitly used in certain custom fields or specific scenarios|render|safeThe filter ensures that the content is correctly parsed and safely output.|safeThe filter here is used to inform the template engine that the output HTML content is safe and does not require further HTML entity escaping.
For example, in your template file (such asdetail.html), you might call the document content in this way:
<div>
{{ archive.Content|render|safe }}
</div>
Or for custom fields:
<div>
{{ params.introduction.Value|render|safe }}
</div>
Step 3: Client-side script support for rendering special elements
Although AnQiCMS has already converted Markdown to HTML, special markers such as mathematical formulas (such as LaTeX syntax) and flowcharts (such as Mermaid syntax) still need to be further parsed and rendered with front-end JavaScript libraries to be displayed normally in the browser as expected visual effects.These libraries usually need to be manually imported into the template files of the website.
AnQiCMS template files are based on the Django template engine syntax, usually there will be onebase.htmlOr similar public template files, which carry the common header, footer, and resources that need to be globally introduced on the website.We will add the required JavaScript and CSS references here.
Markdown default style:To make the rendered Markdown content more visually consistent and beautiful, you can introduce a set of GitHub-style Markdown styles.This is done by adding an external CSS file.
base.htmlthe file<head>Within the area, add the following code:<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" />Correct display of mathematical formulas (via MathJax):Mathematical formulas are usually written in LaTeX or AsciiMath syntax, for example
$$ E=mc^2 $$。MathJax is a powerful JavaScript rendering engine used to display mathematics in web browsers. In yourbase.htmlthe file<head>Within the area, add the following script:<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>After the configuration is complete, for example, the mathematical formulas you write in Markdown content:
$$ \int_a^b f(x) dx $$or inline formulas$\alpha + \beta = \gamma$All will be rendered as beautiful mathematical symbols in the browser by MathJax.The correct display of flowcharts (via Mermaid):Process diagrams usually use a simple text syntax like Mermaid to describe, for example:
graph TD A[Start] --> B{Operation}; B -- Yes --> C[Result 1]; B -- No --> D[Result 2]; C --> E[End]; D --> E;Mermaid is a JavaScript-based library that can generate charts and flowcharts from text. In your
base.htmlthe file<head>Within the area, add the following script:<script type="module"> import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs'; mermaid.initialize({ startOnLoad: true }); </script>When you insert the code block marked with "`" in Markdown content
mermaidThe Mermaid library will recognize and render it as an interactive flowchart.
An example of Markdown syntax when creating content
In the AnQiCMS backend Markdown editor, you can write content that includes formulas and flowcharts in the following way:
- Inline formula:Use a single dollar sign to enclose, for example
这是行内公式 $E=mc^2$ 。 - Block-level formula:Use double dollar signs to enclose, displayed on a separate line, for example:
$$ \sum_{i=1}^n i = \frac{n(n+1)}{2} $$ - Flowchart:Use
mermaid` 代码块包裹 Mermaid 语法，例如：graph LR A[Submit document] --> B{Approved?}; B -- Yes --> C[Publish]; B -- No --> D[Return for modification]; C --> E[Update website]; D --> A;""
By following these steps, AnQiCMS combines the power of client-side scripts to perfectly present your Markdown content (including complex mathematical formulas and flowcharts) on the web page, providing readers with a richer visual experience and clearer information delivery.
Frequently Asked Questions (FAQ)
1. Why does AnQiCMS already support Markdown, and do I still need to manually introduce external CDN scripts to display formulas and flowcharts?AnQiCMS is responsible for converting Markdown text (including$$...$$or “`mermaidThis special mark) converts to the basic HTML structure.However, these special markers are not standard HTML tags, and browsers cannot directly understand and render them into complex formula graphics or flowcharts.Therefore, we need to introduce client-side JavaScript libraries such as MathJax and Mermaid.These libraries will scan the specific HTML structure (converted by AnQiCMS) in the page after the browser loads, and then dynamically parse and render it into the final visual effect.AnQiCMS is responsible for content management and initial conversion, while these external libraries are responsible for advanced client-side rendering.
2.I have followed the steps to introduce the script and enabled the Markdown editor, but the formula or flowchart is still displayed as plain text, or an error occurs on the page. How should I troubleshoot?First, please check yourbase.htmlIs the CDN link included in the file complete and correct, ensuring there are no typing errors. Next, confirm that the script is placed in<head>the tag andmermaidOf the scripttype="module"the attributes as wellmermaid.initialize({ startOnLoad: true });The code is complete.
Please double-check the formula (such as$$...$$) or flowchart (such asmermaid ...Does the syntax conform to MathJax or Mermaid standards.The wrong syntax will cause them not to be recognized correctly.Finally, check the browser developer tools (F12) console for any error messages, as this usually helps you locate whether the script failed to load, there are syntax errors, or other issues.|render|safeA filter to ensure that the HTML content converted by AnQiCMS can be processed correctly by the browser and allows script execution.
3. Can I use locally deployed MathJax and Mermaid libraries instead of loading through CDN links?Absolutely. CDN links provide a convenient and efficient way to introduce, but if you consider factors such as website loading speed, security, or offline access, you can also choose to download the MathJax and Mermaid libraries to your server and then modifybase.htmlof<script>and<link>Label itsrcorhrefThe attribute points to the path of your local deployment. For example, if you place the library file in/public/static/js/directory, you can modify it as follows:
<script id="MathJax-script" async src="/static/js/mathjax/tex-mml-chtml.js"></script>
<script type="module">
import mermaid from '/static/js/mermaid/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>
Please note that you need to manage the updates and maintenance of these library files yourself for local deployment.