Integrate MathJax and Mermaid.js on AnQiCMS page: Easily display mathematical formulas and flowcharts

AnQiCMS as an efficient and flexible content management system performs excellently in meeting various content display needs.With the increasing richness of technical content, many users may encounter the need to elegantly display mathematical formulas and flowcharts on websites.AnQiCMS integrates its built-in Markdown editor and flexible template support, making it very simple to integrate MathJax and Mermaid.js, which can help you present complex mathematical expressions and logic charts intuitively on the web.

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

First step: Enable Markdown editor

To make MathJax and Mermaid.js work properly, first ensure that the content editing function of AnQiCMS supports Markdown.AnQiCMS provides an integrated Markdown editor, which is the basis for displaying mathematical formulas and flowcharts.

Please log in to the AnQiCMS backend and navigate toGlobal settings -> Content settings. Here you will find an option to enable or disable the Markdown editor.Make sure this option is enabled. Once the Markdown editor is enabled, you can use Markdown syntax to create content when editing articles or pages.

Step 2: 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.In AnQiCMS, all pages usually inherit a basic template file, usuallybase.html. We will modify this file, in<head>Include the 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.htmlfile. If your template is the default template, the path is usually/template/default/base.html.

Inbase.htmlthe file<head>Inside the tag, find a suitable position (usually after all CSS files but before other JavaScript files), add the following code snippet:

1. Introduce MathJax to render mathematical formulas

MathJax can render mathematical formulas written in LaTeX syntax into high-quality typesetting. 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 attribute 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 using simple text syntax, such as flowcharts, sequence diagrams, Gantt charts, and so on.In order to integrate Mermaid.js, you need to add the followingscriptTags:

<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 it is an ES module.mermaid.initialize({ startOnLoad: true });This line of code will indicate that Mermaid will automatically search and render Mermaid diagrams on the page after it is loaded.

Please save after completing the modification.base.htmlfile.

Step 3: Write mathematical formulas and flowcharts in the content

Now, the Markdown editor has been 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):Use a single dollar sign$Enclose the formula. For example：$ E=mc^2 $Will render as( E=mc^2 ).
  • Block formula (Display Math):Use double dollar signs$$Enclose the formula, the formula will be displayed on a separate line and centered. For example:$$ x = \frac{-b \pm \sqrt{b^2-4ac}}{2a} $$Will render 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 special Markdown code blocks and specify the language asmermaid.

For example, create a simple flowchart:

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

After saving your content, visit the front page, MathJax and Mermaid.js will automatically parse and render the formulas and charts you have written.

Tips and注意事项

  • Clear the cache:After modifying the template file or system settings, in order to ensure that the changes take effect immediately, please be sure to go to the AnQiCMS background.Update Cachefunction, clear all system caches.
  • CDN Advantages:The links used in the text are all public CDN links, which usually have faster loading speeds and higher availability.If special requirements necessitate local hosting of scripts, files can be downloaded from the official websites of MathJax and Mermaid.js and placed in the AnQiCMS's/public/static/Under the directory, then modify accordinglybase.htmlPath in.
  • Syntax check:If your formula or chart does not display correctly, please check the syntax of MathJax (LaTeX) and Mermaid carefully.They are sensitive to syntax errors. You can refer to the official documentation of MathJax and Mermaid for more detailed syntax guidelines.

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, thereby greatly enhancing the quality of the content and the reading experience of users.

Frequently Asked Questions (FAQ)

1. I followed the steps, but the mathematical formulas or flowcharts on the page did not display. What could be the reason?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.
  • The template file modification is incorrect:Checkbase.htmlIs the script inclusion code in the file complete and accurate, and located<head>within the tag. Note the call to Mermaid.js.'type="module"attributes andmermaid.initialize()Call.
  • AnQiCMS cache not cleared:After modifying the template or settings, you need to manually clear the cache on the backend for the changes to take effect.
  • The content format is incorrect:Make sure the syntax you write for formulas and charts in the Markdown editor conforms to MathJax （$...$or$$...$$）and Mermaid (mermaid ...) requirements.

2. Can the scripts for MathJax and Mermaid.js be hosted locally?Of course you can. If your website has special restrictions on external CDN access or you want to have full control over resource loading, you can download the release files of MathJax and Mermaid.js to your server, and then place them in the static resource directory of AnQiCMS (for example/public/static/js/）。Then, you just need to modifybase.htmlcorrespondingscriptlabel'ssrcthe path, pointing to the local file.

3. How can I debug the reason why my Mermaid diagram code is very long, or the MathJax formula is very complex and does not render?For complex code, it is recommended to first test and verify in the online editor or official documentation of MathJax or Mermaid to ensure that the syntax is correct.For example, Mermaid officially provides a real-time editor where you can enter code and see the rendering effect immediately.If the grammar is confirmed to be correct but there are still problems on the AnQiCMS page, you can try to open the browser's developer tools (usually press F12 key), check if there are any error messages in the console, which usually helps you locate whether the script failed to load, there is a syntax parsing error, or other issues.