In Anqi CMS, the Markdown editor brings great flexibility to content creation, and when we need to embed dynamic and intuitive charts such as flowcharts and sequence diagrams in articles, Mermaid is undoubtedly a powerful tool to enhance the expression of content.How can I elegantly embed Mermaid flowcharts in the Markdown content of Anqi CMS and ensure that they can be displayed normally on the front-end page?This is actually the process of extending backend editing capabilities to frontend rendering, the whole configuration process is very intuitive.

The first step is to ensure that the AnQi CMS Markdown editor is enabled

AnQi CMS was designed with modern content management needs in mind, and it comes with built-in support for Markdown.To make the Mermaid flowchart recognizable and renderable, you first need to confirm that your CMS backend has enabled the Markdown editor.

This is usually inBackend -> Global Settings -> Content SettingsConfigure within. Find the relevant options, check or ensure that the Markdown editor is enabled.Once enabled, you can enjoy the convenience of Markdown while editing articles, including inserting code blocks, lists, links, and of course, the specific code block syntax required by Mermaid.

Second step: Write Mermaid flowchart code in the content

Mermaid chart is generated based on a specific text syntax.After enabling the Markdown editor, you can insert Mermaid code in the content field of any article, single page, or custom content model in the form of a Markdown code block.The key is that Mermaid code needs to be enclosed in triple backticks () and explicitly declare its language type on the first line asmermaid.

For example, a simple Mermaid flowchart code may look like this:

graph LR
    A[Start] --> B(Processing);
    B --> C{Condition judgment?};
    C -- Yes --> D[Operation 1];
    C -- No --> E[Operation 2];
    D --> F[End];
    E --> F;

After you insert this code into the content editor, the Anq CMS Markdown renderer will recognize this special code block in the background and convert it to the corresponding HTML structure.However, simply converting it to HTML is not enough to make the browser display a beautiful flowchart, because the final rendering of Mermaid charts requires the use of a JavaScript library on the client side.

The third step: Configure the front-end template to support Mermaid rendering

This is the most critical step to implement Mermaid flowchart display on the front end. Although Anqi CMS can handle Markdown and generate HTML, the JavaScript library of Mermaid itself needs to be introduced to your website's front-end page in order to display those withmermaidThe marked HTML elements are dynamically converted into visual charts.

You need to modify the template file used by the current website, which is usually the public header file of the website, for examplebase.htmlorbash.htmlBecause these files are inherited by all pages, make sure that the Mermaid library is loaded on all possible pages that may contain flowcharts.

The specific steps are:

  1. Log in to the AnQi CMS backend and navigate toTemplate design -> Template management.

  2. Find the template you are currently using (usually marked as "In use").

  3. Click the template name to view details, then find and editbase.htmlorbash.htmlFiles. These files usually define the structure of the<head>Regions and common structures.

  4. In<head>bottom of the tags, but in</head>Insert the following JavaScript code snippet before the tag closes:

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

    This code includes the Mermaid library via CDN and throughmermaid.initialize({ startOnLoad: true });Instruct Mermaid to automatically scan and render all code blocks marked with Mermaid after the page has loaded.

  5. Save your modifications to the template file.

Validate and optimize.

After completing these steps, you can visit the page containing the Mermaid flowchart to verify that the chart is displayed correctly.If everything goes well, you should see a clear and professional flowchart appear before you.

If the chart does not display or there are error messages in the browser console, you can check the following:

  • Check the Markdown code block syntax:Ensure that the Mermaid code is strictly enclosed inmermaid` 和between.
  • Check the JavaScript inclusion:Confirmbase.htmlThe Mermaid code snippet is correct in the corresponding template file, and the network connection is normal, the CDN resources can be loaded.
  • Clear the cache:Click in the AnQi CMS backend.Update CacheSometimes, the browser cache also needs to be cleared manually.
  • Mermaid version:The Mermaid version specified in the CDN link (@10) May be updated over time. If you encounter compatibility issues, try to view the official Mermaid documentation and update to the latest stable version.

With such configuration, Anqi CMS can not only help you efficiently manage content, but also leverage the powerful capabilities of Mermaid to visually display complex logic and processes to your readers in an intuitive manner, greatly enhancing the reading experience and understanding efficiency of the content.

Frequently Asked Questions (FAQ)

1. Why did I enable Markdown editor and insert Mermaid code in the background, but the front-end page still doesn't display the flowchart, only the text of the code block?

This is usually because you forget to include the Mermaid JavaScript rendering library in the website's frontend template.The Anqi CMS Markdown editor recognizes and processes Mermaid code blocks, but it only converts them to a specific HTML structure.You need to make the browser render these HTML structures into actual flowcharts, bybase.htmlIn a similar public template file, manually add the CDN link and initialization code for the Mermaid library.Please refer to the section 'Configure the front-end template to support Mermaid rendering' in the article for instructions.

2. Can I directly insert HTML in the Markdown editor to replace the Mermaid flowchart? For example, using SVG code.

In theory, Markdown editors can directly display SVG or plain HTML elements after rendering to HTML.However, directly writing SVG or complex HTML to draw flowcharts can be very cumbersome and difficult to maintain.The advantage of Mermaid lies in its concise text syntax, allowing you to quickly generate complex diagrams as if you were writing code, and then automatically convert them into beautiful SVG images with a JavaScript library.If you are pursuing efficiency and maintainability, Mermaid is the better choice.For simple static HTML content, directly inserting HTML is feasible, but for dynamic charts, Mermaid combined with the JavaScript library is the correct choice.

3. Does Mermaid flowchart support dynamic data, such as reading data from a database to generate charts?

Mermaid itself is a client-side rendered JavaScript library that generates charts based on the static text syntax you provide in Markdown. This means that itDoes not support directlyDynamically read data from the database to build charts. If you need to generate charts based on dynamic data, you may need to combine the following two methods: one is to process the dynamic data through the template engine of an enterprise CMS (such as the Django template engine), generate Mermaid's text syntax, and then render it by the front-end Mermaid library;The second is to get data through JavaScript on the front end, then use Mermaid's API to dynamically create and insert charts.This usually requires more advanced custom development.