On the day when content management is becoming increasingly refined, websites not only carry text and images but also need to present complex information in a professional and easy-to-understand way, such as mathematical formulas and flowcharts.AnQiCMS is dedicated to providing efficient and flexible content management solutions. When we handle technical articles, academic content, or business process diagrams on our websites, how to ensure that these special elements are displayed correctly and beautifully becomes a topic worth discussing.

AnQiCMS itself provides good support for Markdown editors, which means we can write formulas and flowcharts using concise Markdown syntax.However, to make the browser 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 the AnQiCMS template and ensure that mathematical formulas and flowcharts are perfectly presented.

Preparation: Enable Markdown Editor

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

Please log in to your AnQiCMS backend and navigate toGlobal Settings-u003eContent settings. On this page, you will find an option named "Enable Markdown Editor". Be sure to set it to "Is. Enable it to use Markdown syntax when publishing or editing document content.

Core steps: Introduce the frontend support library into the template.

AnQiCMS uses a template engine syntax similar to Django, which means that website templates usually have abase.htmlA file that serves as the skeleton for all pages, carrying common page headers, footers, and so on. In order for mathematical formulas and flowcharts to be displayed normally throughout the site, we need to introduce the required frontend libraries into thisbase.htmlthe file<head>area.

Your template file is located 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 add the code according to the following steps.

1. Markdown content styling (optional, but highly recommended)

Although this is not necessary for the display of formulas and flowcharts, introducing a set of beautiful Markdown styles can make your content more readable.We recommend using GitHub-style Markdown CSS.

Inbase.htmlthe file<head>Add the following code inside 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. 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 for 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 assisted by the Mermaid library, which allows you to generate various charts, including flowcharts, sequence diagrams, Gantt charts, and so on, through simple text descriptions.

Similarly, inbase.htmlthe file<head>Add Mermaid's CDN script and initialization code 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>

Render Markdown fields in the content template:

Completed the back-end setup and front-end library integration, and the final step is very critical: make sure that your content template can correctly parse and render Markdown-formatted document content.

In AnQiCMS, when we usearchiveDetailorpageDetailtags to call documents or pagesContentWhen a field needs to be explicitly told to the system to perform Markdown to HTML conversion, this is done by adding in the tag.render=trueParameters to implement. 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, assuming you are on a document detail pagearticle/detail.htmlor 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 as Markdown.articleContentIt is the temporary variable we define 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 to the test:

  1. Create or edit a document/page in the AnQiCMS backend.
  2. In the content editor, try inserting Markdown syntax for mathematical formulas and flowcharts.
    • Example of mathematical formula (LaTeX syntax):
      
行内公式：$E=mc^2$
块级公式：
$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$
    • Example of flowchart (Mermaid syntax):
      graph TD;
    A[Start] --> B{Decision};
    B -- Yes --> C[Perform Action 1];
    B -- No --> D[Perform Action 2];
    C --> E[End];
    D --> E;
  3. Save and publish the document/page.
  4. Visit the website's front end, view this document/page. If everything is configured correctly, you should be able to 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 check itbase.htmlcode introduced in CDN and content template inrender=trueand|safeIs the use of the filter correct.

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

Frequently Asked Questions (FAQ)

Q1: I have enabled the Markdown editor and also configured CDN, but the mathematical formulas and flow charts still do not display, or display as raw Markdown text. Why is that? A1: This is likely because you are in the content template (for examplearticle/detail.htmlorpage/detail.htmlWhen calling article or page content, did not correctly inform AnQiCMS to render Markdown. Make sure you have added inarchiveDetailorpageDetailtags.render=trueParameter, and the content output has been used|safea filter. For example:{% archiveDetail articleContent with name="Content" render=true %}{{ articleContent|safe }}.

Q2: Can I customize the style of the formulas and flowcharts rendered by MathJax or Mermaid? A2: Of course you can. MathJax and Mermaid both offer a rich set of configuration options, allowing you to customize fonts, colors, layouts, etc. You can modifymermaid.initialize()Configuration parameters, or defined before the MathJax script is loadedMathJax = { ... }objects to customize their behavior and style. In addition,