In AnQi CMS, using Markdown format to write content not only improves editing efficiency but also maintains the structured and readability of the content.When the content involves complex mathematical formulas or needs to display clear flowcharts, the powerful features of Markdown can be demonstrated.AnQi CMS provides good support for this, let's take a look at how to properly render and display these advanced contents on the website.

Step 1: Enable Markdown Editor

Firstly, make sure that your security CMS system has enabled the Markdown editing feature. This setting is usually in the background'sGlobal SettingsFound in 【en】.

Enter the AnQi CMS backend, find the left menu bar of 【en】.Backend settingsClick to enter 【en】.Content Settings.On this page, you will see an option, typically labeled as "Enable Markdown Editor" or a similar description.Make sure this option is checked or set to enabled, and save your changes.This is the foundation for the system to recognize and process Markdown content.

Step 2: Write Markdown content in the document 【en】.

When the Markdown editor is enabled, you can use Markdown syntax to write content when creating or editing documents.Markdown is concise and intuitive, allowing us to focus on the content itself.

For mathematical formulas, Markdown usually combines LaTeX syntax for writing:

  • Inline formulaUse a single dollar sign$to wrap, for example:$\sum_{i=1}^n i = \frac{n(n+1)}{2}$It will be rendered as[en](\(\sum_{i=1}^n i = \frac{n(n+1)}{2}\)).
  • [en]Block Formula[en](Displayed on an independent line): Use double dollar signs$$to wrap, for example:
    
$$
E=mc^2
$$
    will be rendered as: $\( E=mc^2 \)$

For flowcharts, the Anqi CMS supports generating them using Mermaid syntax.Mermaid allows you to describe charts using text and then automatically render them into graphics.mermaidKeyword starts, followed by chart type and definition, and enclosed in three backticks . For example, a simple flowchart might look like this: 

graph TD;
    A[Start] --> B{Decision};
    B --> |Yes| C[Perform Action];
    B --> |No| D[End];
    C --> D;

You can directly paste or write these Markdown codes in the document content editor of AnQi CMS.

Step 3: Adjust the website template to support rendering

Markdown content, especially mathematical formulas and flowcharts, require the use of front-end JavaScript libraries to be rendered correctly in the browser.The template system of Anqi CMS is very flexible, allowing us to easily integrate these libraries.base.htmlTo introduce the necessary CSS and JavaScript.

base.htmlThe file is usually located in the root directory of your theme folder, for example./template/default/base.htmlIn the file,<head>Within the tag, we need to add the following code:)

  1. Provide basic styles for Markdown content:In order to make the rendered content of Markdown more visually appealing and compliant with standards, you can introduce GitHub-style Markdown CSS.

    <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. Support the display of mathematical formulas:MathJax is a powerful JavaScript rendering engine that can render LaTeX-formatted mathematical formulas into high-quality typesetting.

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

  3. Support the display of flowcharts:The Mermaid library can parse Mermaid syntax and convert it into SVG graphics.It should be noted that Mermaid usually needs to be imported and initialized as an ES module.

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

    Make sure these scripts are placed in<head>tags so that the page can be processed in time during loading. Among them, the initialization code of Mermaid:mermaid.initialize({ startOnLoad: true });Tell Mermaid to automatically find and render all Mermaid diagrams after the page is loaded.

Step 4: Make sure the content is displayed correctly on the document detail page.

In AnQi CMS, document content (such asarchive.Contenttypically be automatically rendered as HTML. However, if you are storing Markdown content in custom fields or want to explicitly control the rendering behavior, you can do so in the template byarchiveDetaillabel combined withrenderparameters.

For example, in your article detail template (usually{模型table}/detail.html), the display of document content fragments may be as follows:

{%- archiveDetail articleContent with name="Content" render=true %}
{{articleContent|safe}}

Here,render=trueensuring that Markdown content is processed into HTML.|safeThe filter is crucial, it tells the template engine that this content is safe HTML, which does not need to be escaped again. Otherwise, you might see the original HTML tags instead of the rendered effect.

If your Markdown content is stored in a custom field (for example, you have created a field namedintroduction(Use a custom field to store Markdown introduction) so you may need to use it similarlyrenderFilter:

{% archiveDetail introduction with name="introduction" %}
{{introduction|render|safe}}

After completing these steps, you can publish a document containing Markdown, mathematical formulas, and flowcharts, and then visit the front-end page for testing.Remember to clear your browser cache before checking the effect, to ensure that the latest template file and script are loaded.

By the above configuration, your security CMS website can not only publish standard text content, but also present complex mathematical formulas and dynamic flowcharts in a professional and intuitive manner, greatly enriching the expressiveness of the website content.

Common Questions (FAQ)

1. Why is my mathematical formula or flowchart not displayed and only the original code is shown?This is usually because the front-end JavaScript rendering library has not been loaded or initialized correctly. Please check the following points:

  • Is the Markdown editor enabled?Please confirm that the Markdown editor is enabled in the 'Content Settings' section of the AnQi CMS backend.
  • Is the template file modification correct?Please check carefully.base.htmlIn the file, are the CDN links for MathJax and Mermaid complete, are the paths correct, and are they all placed in<head>the tags. Especially the Mermaid'sscript type="module"andmermaid.initialize()Have all been added?
  • Did you use when outputting content?|safeFilter: In{% archiveDetail %}Make sure to use when outputting tag content, otherwise the HTML code will be escaped and cannot be rendered.|safeFilter, for example{{articleContent|safe}}, otherwise the HTML code will be escaped and cannot be rendered.
  • Network connection issueConfirm that both your server and visitors can connect to the CDN service (cdnjs.cloudflare.comandcdn.jsdelivr.net), if the network is restricted, these scripts may fail to load.

2. I just want to use Markdown's text formatting, not mathematical formulas or flowcharts, is that okay?Of course you can. If you only need the text formatting and styling of Markdown (such as headings, lists, code blocks, etc.), and do not need support for mathematical formulas and flowcharts, then you just need tobase.htmlAdd the GitHub Markdown CSS link.You can omit the JavaScript introduction of MathJax and Mermaid, which can reduce the resources loaded by the page.

3. Will these third-party CDN resources affect the loading speed or stability of the website?Using a CDN (Content Delivery Network) typically speeds up resource loading, as the CDN distributes resources to servers all over the world, allowing users to access resources from the nearest node. Likecdnjs.cloudflare.comandcdn.jsdelivr.netSuch mainstream CDN services have very high stability and speed.However, any external dependency carries potential risks, such as temporary interruption of CDN services or network congestion.For most small and medium-sized enterprise websites, this impact is usually negligible and the benefits outweigh the drawbacks.If you have very high requirements for performance and stability, and possess the relevant technical capabilities, you can also consider downloading these JS/CSS files to your local server for hosting, but this will increase the maintenance cost.