Today, with the increasing refinement of content management, websites not only carry text and images but also need to present complex information such as mathematical formulas and flowcharts in a professional and easily understandable way.AnQiCMS is committed to providing efficient and flexible content management solutions. When dealing with technical articles, academic content, or business process diagrams on our website, how to ensure that these special elements are displayed correctly and beautifully has become a topic worth discussing.

AnQiCMS itself provides good support for Markdown editors, which means we can use concise Markdown syntax to write formulas and flowcharts.However, in order for the browser to correctly parse and render these special Markdown syntaxes, some mature front-end libraries are needed.This article will introduce in detail how to introduce these libraries in AnQiCMS template and ensure that mathematical formulas and flowcharts can be presented perfectly.

Preparation: Enable Markdown Editor

Firstly, we need to enable the Markdown editor in the AnQiCMS backend so that we can use the relevant syntax while editing content.

Please log in to your AnQiCMS backend, navigate toGlobal Settings-Content Settings. On this page, you will find an option named “Whether to enable Markdown editor”. Be sure to set it to “Yes”。Enable it, and you can use Markdown syntax in the content editing area when you publish or edit document content.

Core steps: Introduce the front-end support library to the template

AnQiCMS uses a template engine syntax similar to Django, which means that website templates usually have abase.htmlThe file, which serves as the skeleton of all pages, carries common contents such as headers and footers. In order for mathematical formulas and flowcharts to display normally throughout the site, we need to include the required frontend libraries into thisbase.htmlthe file<head>area.

Your template file is stored in/templateThe directory, each template package has its own directory. Find the directory of the template package you are currently using.base.htmlFile (or similar public header file), then follow the steps below to add code.

1. Markdown content style beautification (optional, but highly recommended)

Although this is not necessary for the formula and flowchart display, introducing a set of beautiful Markdown styles can make your content more readable.Here we recommend using GitHub style Markdown CSS.

Inbase.htmlthe file<head>Tags within, add the following code: 

<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. English translation: Implement the correct display of mathematical formulas

The rendering of mathematical formulas usually depends on libraries like MathJax, which can convert formulas written in LaTeX, AsciiMath, or MathML syntax into clear and beautiful mathematical symbols.

Continue inbase.htmlthe file<head>Add the CDN script of MathJax inside the tag:

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

3. Implement the correct display of flowcharts

The rendering of flowcharts can be facilitated by the Mermaid library, which allows you to generate various charts, including flowcharts, sequence diagrams, Gantt charts, etc., through simple text descriptions.

Similarly inbase.htmlthe file<head>Tags inside, add CDN script and initialization code for Mermaid:

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

Render Markdown fields in the content template:

Completed the background settings and front-end library inclusion. The final step is very critical: make sure your content template can correctly parse and render Markdown formatted document content.

In AnQiCMS, when we usearchiveDetailorpageDetailtags to call documents or pages.ContentWhen fields are specified, it needs to be explicitly told to the system to perform Markdown to HTML conversion. This is done by addingrender=trueThe parameter is implemented. At the same time, since the rendered HTML code may contain tags, we need to use|safea filter to prevent HTML entity escaping.

For example, if you are on the document detail page, assuming you arearticle/detail.htmldisplaying the article content in a similar document template, your code might look like this:

<article class="markdown-body"> {# 配合上一步的github-markdown-css样式 #}
    <h1>{% archiveDetail with name="Title" %}</h1>
    <div class="article-content">
        {%- archiveDetail articleContent with name="Content" render=true %}
        {{ articleContent|safe }}
    </div>
</article>

Here:

  • {%- archiveDetail articleContent with name="Content" render=true %}This line of code tells AnQiCMS to get the current document'sContentcontent and render it in Markdown format.articleContentIt is a temporary variable defined for rendering results.
  • {{ articleContent|safe }}: Outputs the rendered HTML content safely to the page, preventing the browser from displaying it as plain text.

If you are displaying content in a single page, the calling method is similar:

<div class="page-content markdown-body">
    {%- pageDetail pageContent with name="Content" render=true %}
    {{ pageContent|safe }}
</div>

Test and verify

After completing all the above steps, you can proceed with the test:

  1. In AnQiCMS backend, create or edit a document/page.
  2. In the content editor, try inserting Markdown syntax for mathematical formulas and flow charts.
    • Mathematical formula example (LaTeX syntax):
      
行内公式：$E=mc^2$
块级公式：
$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$
    • Flowchart example (Mermaid syntax):
      graph TD;
    A[Start] --> B{Decision};
    B -- Yes --> C[Perform Operation 1];
    B -- No --> D[Perform Operation 2];
    C --> E[End];
    D --> E;
  3. Save and publish the document/page.
  4. Access the website front end, view this document/page. If everything is configured correctly, you should see beautifully rendered mathematical formulas and clear flowcharts.

If the display is not normal, please check if there are any JavaScript errors in the browser console and carefully verifybase.htmlThe code introduced by CDN and the content template inrender=trueand|safeThe usage of the filter is correct.

Through these simple configurations, your AnQiCMS website can perfectly present complex mathematical formulas and clear flowcharts, greatly enhancing the professionalism and readability of the content, and providing your visitors with a better reading experience.

Common Questions (FAQ)

Q1：I have enabled the Markdown editor and also configured CDN, but mathematical formulas and flowcharts still do not display, or display as raw Markdown text. Why is that? A1:This is likely because you are in the content template (such asarticle/detail.htmlorpage/detail.htmlWhen calling article or page content in the bracket, AnQiCMS is not told to render Markdown correctly. Make sure you add it in the tagarchiveDetailorpageDetail标签中添加了render=trueParameters, and the output content has been used|safefilter. For example:{% archiveDetail articleContent with name="Content" render=true %}{{ articleContent|safe }}.

Q2: Can I customize the style of formulas and flowcharts rendered by MathJax or Mermaid? A2：Of course you can. MathJax and Mermaid both provide rich configuration options, allowing you to customize fonts, colors, layout, and more. You can modifymermaid.initialize()The configuration parameters, or defined before the loading of the MathJax script.MathJax = { ... }Objects come from customizing their behavior and style. Moreover,