AnQiCMS provides a convenient and efficient Markdown editor for content creators, allowing us to easily organize the structure of articles, 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 present beautifully 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 integrate 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 already enabled the Markdown editor in the AnQiCMS backend.This is usually found under the 'Global Settings' under the 'Content Settings' option.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.htmlFiles play a foundational role. They contain the public header of the website (<head>) and the footer (<footer>In these areas, almost all other page templates inherit this basic skeleton. Therefore, the general JavaScript library and CSS styles are introduced tobase.htmlthe file<head>Tags inside are the most reasonable and efficient approach. This ensures that these features can be loaded and executed on all pages of your website without repetition.

Introduce necessary scripts for Markdown content

Next, we will proceed step by step inbase.htmlthe file<head>The tag internally introduces three parts of code, each used to enhance the Markdown style, support mathematical formula rendering, and support flowchart display.

1. Introduce Markdown content style (optional)

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

Add the following line of code tobase.htmlthe file<head>within 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" />

2. Support mathematical formula rendering (MathJax)

If you need to insert and correctly display mathematical formulas with LaTeX syntax, MathJax is a very powerful solution.It can parse and render mathematical formulas on the page 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>

This has been usedasyncthe attribute, which means the script will load asynchronously, not block the rendering of the page, and help improve the user experience.

3. Supports flowchart rendering (Mermaid.js)

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

The way to integrate Mermaid.js is as follows, placed inbase.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 passes throughtype="module"Introducing the Mermaid library, which initializes automatically when the page loads, enabling it to recognize and render Mermaid syntax in Markdown code blocks.

Check the results

Complete the addition of the above code and savebase.htmlAfter the file, you can log in to the AnQiCMS backend, create or edit a document. Try inserting a mathematical formula in the Markdown editor (for example, using$$...$$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 action];
    B -- No --> D[End];
    C --> D;

After publishing the document, visit the front-end page and check if 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.

Frequently Asked Questions (FAQ)

  1. Why is my mathematical formula or flowchart not displaying correctly and only showing the original code?First, make sure you have enabled the Markdown editor in the "Global Settings" -> "Content Settings" of the AnQiCMS backend. Next, checkbase.htmlDid the code for MathJax and Mermaid.js get correctly included in the file and is it positioned in<head>the tag inside. Moreover, in your content template (for examplearchive_detail.htmlorpage_detail.htmlMake sure you use the variables (such as{{archive.Content}}) added at the end|render|safeFilter, for example{{archive.Content|render|safe}}This is how the system will convert Markdown to HTML and allow the browser to parse the script inside it.

  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, and 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 math formula rendering engines.Please note that after replacement, you must ensure that the new library is compatible with the template rendering mechanism of AnQiCMS 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 loading speed of the website?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 users can load scripts from the server closest to their geographical location, thereby reducing latency.MathJax also particularly usedasyncProperty, allows scripts to be loaded asynchronously, try not to block the initial rendering of the page.For most AnQiCMS users, the functional enhancements brought by these libraries far outweigh the minor impact they may have on loading speed, and through reasonable CDN and asynchronous loading, the impact has been minimized.