AnQiCMS provides a convenient and efficient Markdown editor for content creators, allowing us to easily organize article structure, insert code blocks, and images.However, when our content needs to display complex mathematical formulas or clear flowcharts, relying solely on Markdown syntax itself is not enough to make them look beautiful on the web.These advanced features require the introduction of specific JavaScript libraries on the browser side to be correctly parsed and rendered.

How can you introduce these necessary JavaScript libraries into your AnQiCMS website to ensure perfect display of Markdown content? The key is to modify the public template file of the websitebase.html.

Enable Markdown Editor

Before starting to modify the template file, we first need to confirm a premise: you have enabled the Markdown editor in the AnQiCMS backend.This is usually found in the corresponding options under 'Content Settings' in 'Global Settings'.Please make sure the Markdown editor is turned on, so that the system can correctly identify and process the content you write in Markdown format.

Why choosebase.html?

In the template system of AnQiCMS,base.html文件扮演着基石的角色。它包含了网站的公共头部（<head>）、底部（<footer>）et al areas, almost all other page templates will inherit this basic skeleton. Therefore, general JavaScript libraries and CSS styles are introduced tobase.htmlthe file<head>The label inside is the most reasonable and efficient approach. This ensures that these features can be loaded and executed on all pages of your website without the need to add them repeatedly.

To introduce necessary scripts for Markdown content

Next, we will proceed step by step inbase.htmlthe file<head>The tag internally includes three parts of code, which are used to enhance the style of Markdown, support rendering of mathematical formulas, and support the display of flowcharts.

1. Introduce Markdown content styles (optional)

To make the rendered content of Markdown more visually readable, we can introduce a set of commonly used GitHub style Markdown stylesheet.This will provide a set of simple and professional formatting for your Markdown content, enhancing the reading experience of users.

Please add the following line of code tobase.htmlthe file<head>tags:

<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" />

2. Support MathJax for mathematical formula rendering

If you need to insert and display LaTeX syntax mathematical formulas correctly in an article, MathJax is a very powerful solution.It can parse and render mathematical formulas in web pages into high-quality images or text, ensuring clear display on different browsers and devices.

Please add the following JavaScript reference tobase.htmlthe file<head>Inside the tag:

<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

Here, we useasyncThis means that the script will be loaded asynchronously, without blocking the rendering of the page, which helps improve the user experience.

3. Supports flowchart rendering (Mermaid.js)

For scenarios that require displaying flowcharts, sequence diagrams, Gantt charts, and other structured information, Mermaid.js is an ideal choice.It allows you to generate complex charts with simple text descriptions.

The way to integrate Mermaid.js is as follows, placed in the same waybase.htmlthe file<head>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 is throughtype="module"The library Mermaid was introduced and automatically initialized at page load, enabling it to recognize and render Mermaid syntax in Markdown code blocks.

Check the results

Add and save the code as specifiedbase.html文件后，您可以登录 AnQiCMS 后台，创建或编辑一篇文档。在 Markdown 编辑器中尝试插入数学公式（例如使用 English）$$...$$or$...$wrap LaTeX syntax) and Mermaid diagrams (usingmermaid ...` wrap Mermaid syntax).

For example, you can try:

Mathematical formula:

这是一个内联公式：$E=mc^2$
这是一个块级公式：
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

Flowchart:

graph TD
    A[Start] --> B{Decision};
    B -- Yes --> C[Perform Operation];
    B -- No --> D[End];
    C --> D;

After publishing the document, visit the front-end page and check whether these elements are rendered and displayed correctly.If everything is normal, congratulations, your AnQiCMS website now has powerful Markdown content display capabilities, which can present various complex information in a more professional and vivid way.

Common Questions (FAQ)

  1. Why is my mathematical formula or flowchart not displayed correctly and only the original code is shown?Firstly, make sure you have enabled the Markdown editor in the 'Global Settings' -> 'Content Settings' of AnQiCMS backend. Secondly, checkbase.htmlFile has correctly included the MathJax and Mermaid.js code, and the location is in<head>tags. In addition, within your content template (such asarchive_detail.htmlorpage_detail.html）中，ensure that the variable (such as{{archive.Content}}）you added after|render|safeFilter, for example{{archive.Content|render|safe}}So the system will convert Markdown to HTML and allow the browser to parse the scripts within.

  2. Can I use other Markdown styles or libraries for rendering math formulas/process diagrams?Theoretically, it is possible.AnQiCMS provides high-level template customization capabilities, you can completely replace or add other compatible JavaScript libraries according to your needs.For example, you can choose different Markdown CSS frameworks, or other rendering engines for mathematical formulas.Please note that after replacement, you need to ensure that the new library you introduce is compatible with AnQiCMS's template rendering mechanism and the syntax of your Markdown content, and that it has been fully tested to avoid rendering errors or functional conflicts.

  3. Will introducing these external scripts affect the website's loading speed?The loading of external scripts indeed increases page requests and some network latency.However, the MathJax and Mermaid.js we refer to here both use CDN (Content Delivery Network), which means that users can load scripts from the server closest to their geographical location, thus reducing latency.asyncProperties, allow scripts to be loaded asynchronously, try not to block the initial rendering of the page.For most AnQiCMS users, the functionality enhancement brought by these libraries far outweighs the minor impact on loading speed, and the impact has been minimized through reasonable CDN and asynchronous loading.