How to correctly render Markdown-formatted article content as HTML and display mathematical formulas in AnQiCMS?
In AnQi Content Management System (AnQiCMS), we are committed to making content creation and display more flexible and efficient.For users accustomed to writing articles in Markdown format, we provide powerful support, ensuring that Markdown content is correctly rendered into HTML, and can easily handle complex mathematical formulas and flowcharts, making technical documents, tutorial articles, and other content come alive.
Enable Markdown Editor: The First Step of Content Creation
To enjoy the convenience of Markdown in AnQiCMS, you first need to make a simple setting.In AnQiCMS backend, go to the 'Global Settings' under the 'Content Settings' area, and you will find an enabled option for the 'Markdown Editor'.Check this option and save it, then you can directly use Markdown syntax to write when creating or editing articles.
When you write an article in the Markdown editor, such as entering Markdown text in the "Document Content" field, AnQiCMS will automatically parse and render the Markdown syntax content into standard HTML by default.This means you do not need to manually convert, the system will automatically handle most of the rendering work.
In your template file, to safely output HTML content that has been converted with Markdown, you usually use something like{% archiveDetail articleContent with name="Content" %}{{articleContent|safe}}Such a label. Here is|safeThe filter is crucial, it informs the template engine that this part of the content is safe HTML, which does not require additional escaping, thus ensuring that the final rendering effect is consistent with expectations.
If you need more fine-grained control, such as deciding whether to perform Markdown rendering in a specific scenario,archiveDetailLabels also providedrenderparameter. Set it torender=trueIt will force Markdown rendering, andrender=falseSkip rendering and directly output the original Markdown text. Additionally, if you also want to support Markdown rendering for your custom content fields, you can directly use the template output of the field,|renderFilter, for example{{params.introduction.Value|render|safe}}.
To make the rendered Markdown content more visually appealing, especially when adhering to common code styles or documentation habits, we can place the public template file (usuallybase.html）的<head>Introduce a set of CSS style libraries in the region, such as GitHub Markdown CSS:
<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 will present your Markdown article on the front end in a clear and professional style.
Elegantly display mathematical formulas
For technical articles or academic content that includes complex mathematical formulas, AnQiCMS also provides excellent support.This is mainly due to the integration with the MathJax library, MathJax is a powerful JavaScript rendering engine that can render LaTeX, MathML, and AsciiMath representations of mathematical formulas in high quality.
To make the web page display mathematical formulas correctly, you need tobase.htmlthe file<head>Add the MathJax script reference to the area. This is usually introduced from a CDN to ensure loading speed and stability:
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
After adding this line of code, you can directly use LaTeX syntax to write mathematical formulas in Markdown content. For example, inline formulas can be used as$E=mc^2$Independent block-level formulas are used.$$E=mc^2$$:
这是行内公式 $a^2 + b^2 = c^2$，非常方便。
$$
x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}
$$
这是一个块级公式，显示效果更为突出。
When the page loads, MathJax automatically identifies and renders these formulas, presenting them beautifully and clearly in the browser.
Easily display flowcharts and charts
In addition to mathematical formulas, AnQiCMS also supports the display of processes, structures, and other visual information in scenarios, which can be achieved by integrating the Mermaid.js library.Mermaid.js allows you to create various diagrams using simple text and Markdown-like syntax, such as flowcharts, sequence diagrams, Gantt charts, and so on.
Similarly, to enable this feature, you need tobase.htmlthe file<head>Add the Mermaid.js script reference in the region:
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>
Then, you can draw charts in Markdown content using a specific Mermaid syntax. For example, a simple flowchart can be written like this:
```mermaid
graph TD;
A[开始] --> B{决策?};
B -- 是 --> C[执行操作];
B -- 否 --> D[结束];
C --> D;
These charts will be automatically parsed and rendered into visual SVG graphics by Mermaid.js at page load time, greatly enhancing the expressiveness of the content.
The integration of these features greatly enhances the work efficiency of content creators, allowing complex documents, tutorials, and technical articles to be presented clearly and beautifully on AnQiCMS.By simple backend settings and a few template adjustments, you can bring richer interaction and visual experience to your website.
Frequently Asked Questions (FAQ)
1. Why did I enable the Markdown editor but the article content still does not render, or the mathematical formula/process chart does not display?
First, make sure you have enabled the Markdown editor in the "Global Settings" > "Content Settings". Secondly, when outputting the article content in the template file, ensure that you have used|safeFilter, for example{{archive.Content|safe}}If the content is a custom field, it may need to be specified explicitly|render|safe.
You need to confirm that for mathematical formulas and flowcharts,base.htmlof<head>The area has correctly added the CDN reference scripts for MathJax and Mermaid.js.These scripts are the key to page rendering formulas and charts. Additionally, check the browser console for any JS errors that may prevent the normal loading and execution of these libraries.
2. The MathJax and Mermaid scripts should be placedbase.htmlwhere is the most appropriate position?
The scripts for MathJax and Mermaid are usually recommended to be placedbase.htmlthe file<head>within the area. Especially MathJax, itsid="MathJax-script"attribute indicates that it is a script that needs to be loaded early in the document parsing. Place it in<head>Ensure that these libraries are already prepared for rendering when the page content loads, to avoid problems such as content 'flicker' or rendering delay.
How can I customize content fields so that they support Markdown rendering and formula display?
AnQiCMS provides a|renderA filter that can manually render any string content into Markdown. If your custom field (such as a field defined in "Other Parameters") stores Markdown text and you want to render it as HTML on the frontend, you can call it in the template like this:{{archive.自定义字段名|render|safe}}If the custom field contains mathematical formulas or flowchart syntax, as long as the page'sbase.htmlChinese has introduced MathJax and Mermaid.js scripts, and they are also rendered correctly.