Integrate MathJax and Mermaid.js in the AnQiCMS page: easily display mathematical formulas and flowcharts

AnQiCMS is an efficient and flexible content management system that performs exceptionally well in meeting various content display needs.With the increasing richness of technical content, many users may encounter scenarios where they need to elegantly display mathematical formulas and flowcharts on websites.AnQiCMS integrates a built-in Markdown editor and flexible template support, making it very simple to integrate MathJax and Mermaid.js. It can help you present complex mathematical expressions and logic diagrams intuitively on web pages.

Below, we will introduce in detail how to integrate these tools into the AnQiCMS page to make your website content more expressive.

Step 1: Enable Markdown Editor

To ensure that MathJax and Mermaid.js work properly, first you need to make sure that AnQiCMS's content editing feature supports Markdown.AnQiCMS provides a built-in Markdown editor, which is the basis for displaying mathematical formulas and flowcharts.

Log in to the AnQiCMS admin panel, navigate toGlobal Settings -> Content Settings.Here, you will find an option to enable or disable the Markdown editor.Ensure that this option is enabled.Once the Markdown editor is enabled, you can use Markdown syntax to create content while editing articles or pages.

Second step: Modify the basic template file to include MathJax and Mermaid.js

The rendering capabilities of MathJax and Mermaid.js depend on loading their respective JavaScript libraries in the page.base.htmlWe will modify this file,<head>Introduce necessary CDN resources within the tag so that they can take effect on all pages.

The template files of AnQiCMS are located on the server./templateUnder the directory. You need to find the directory of the currently used template, and locate tobase.htmlthe file. If your template is the default template, the path is usually/template/default/base.html.

Inbase.htmlthe file<head>Translate the content within the array as follows: Find a suitable position inside the tag (usually after all CSS files but before other JavaScript files), and add the following code snippet:

1. Introduce MathJax to render mathematical formulas

MathJax can render mathematical formulas written in LaTeX syntax into high-quality layouts. You need to add the followingscriptTags:

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

This code will asynchronously load the core script of MathJax 3.asyncThe property means that the script will load in the background without blocking the parsing of other content on the page, thereby optimizing the page loading speed.

2. Introduce Mermaid.js to Render Flowcharts and Diagrams

Mermaid.js allows you to create various charts, such as flowcharts, sequence diagrams, Gantt charts, and more, through simple text syntax.scriptTags:

<script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
</script>

Please note that Mermaid.js scripts usetype="module"This indicates that it is an ES module.mermaid.initialize({ startOnLoad: true });This line of code will instruct Mermaid to automatically find and render Mermaid diagrams on page load.

Please save after making the changes.base.htmlfile.

Third step: Write mathematical formulas and flowcharts in the content

Now, the Markdown editor is enabled, and MathJax and Mermaid.js scripts have been introduced to the page.You can create or edit any article or page in the AnQiCMS backend, and use their respective syntax directly in the Markdown content area.

1. Write mathematical formulas (MathJax)

MathJax supports two main ways of writing formulas:

  • Inline Formula (Inline Math):Using a single dollar sign$To enclose a formula. For example:$ E=mc^2 $It will be rendered as\( E=mc^2 \).
  • Block Formula (Display Math):Use double dollar signs$$Wrap the formula, the formula will be displayed on a separate line and centered. For example:$$ x = \frac{-b \pm \sqrt{b^2-4ac}}{2a} $$It will be rendered as $\( x = \frac{-b \pm \sqrt{b^2-4ac}}{2a} \)$

2. Write Flowcharts and Diagrams (Mermaid.js)

Mermaid.js charts need to be placed in a special Markdown code block, specifying the language asmermaid.

For example, create a simple flowchart:

```mermaid
graph TD;
    A[开始] --> B{判断};
    B -- 是 --> C[执行操作];
    C --> D[结束];
    B -- 否 --> D;
```

Save your content and then visit the front-end page, MathJax and Mermaid.js will automatically parse and render the formulas and charts you have written.

Tips and precautions

  • Clear cache:After modifying template files or system settings, to ensure that the changes take effect immediately, please go to the AnQiCMS admin panel.Update the cacheFeature, clear all system cache.
  • CDN Advantages:The text uses public CDN links, which typically have faster loading speeds and higher availability./public/static/Under the directory, then modify accordingly.base.htmlPath in.
  • Syntax check:If your formula or chart is not displaying correctly, please carefully check if the syntax of MathJax (LaTeX) and Mermaid is correct.They are sensitive to syntax errors.You can check the official documentation of MathJax and Mermaid for more detailed syntax guides.

By following these steps, you can easily integrate MathJax and Mermaid.js into the AnQiCMS website, adding professional mathematical formulas and clear charts to your technical articles, tutorials, or reports, thus greatly enhancing the quality of the content and the reading experience of users.

Common Questions (FAQ)

1. I followed the steps, but the mathematical formulas or flowcharts on the page did not display. What could be the reason for this?The most common reasons include:

  • Markdown editor is not enabled: Ensure that the Markdown editor is enabled in the "Global Settings -> Content Settings" of the AnQiCMS backend.
  • Template file modification is incorrect:Checkbase.htmlDoes the script inclusion code in the file complete and accurate, and is it located in<head>the tags. Note Mermaid.js'stype="module"properties andmermaid.initialize()invocations.
  • AnQiCMS cache not cleared:After modifying the template or setting, you need to manually clear the cache on the backend to make the changes take effect.
  • Incorrect content format:Ensure that the syntax you use to write formulas and charts in the Markdown editor is consistent with MathJax ($...$or$$...$$) and Mermaid (mermaid ...) requirements.

2. Can the scripts for MathJax and Mermaid.js be hosted locally?Of course, you can./public/static/js/）in it. Then, you just need to modifybase.htmlthe corresponding one inscriptTagssrcPath, point to the local file.

3. My Mermaid diagram code is long, or the MathJax formula is very complex. Is there a way to debug the reason they don't render?For complex code, it is recommended to test and verify in the online editor or official documentation of MathJax or Mermaid first to ensure that the syntax is correct.For example, Mermaid provides an official real-time editor where you can enter code and view the rendered effect instantly.If the grammar is confirmed to be correct but there are still issues on the AnQiCMS page, you can try opening the browser's developer tools (usually by pressing F12), check if there are any error messages in the console, which usually helps you locate whether the script failed to load, there was a syntax parsing error, or other issues.