In AnQiCMS enable Markdown, render mathematical formulas and flowcharts complete guide

AnQiCMS as an efficient and flexible content management system has always been striving to provide content creators with more convenient and powerful content editing and display capabilities.For those who often need to write technical documents, academic papers, or descriptions containing complex logical processes, the original rich text editor sometimes feels inadequate.幸运的是，新版的 AnQiCMS 已经集成了对 Markdown 编辑器的支持，并且可以很好地渲染数学公式和流程图，极大地提升了内容创作的效率和表现力。

Next, let's take a look at how to enable these powerful features in AnQiCMS together, bringing new vitality to your website content.

Enable Markdown Editor

To start using Markdown to create your content, you first need to make a simple setting in the AnQiCMS backend.

You just need to log in to the backend, find the "Global SettingsIn this page, you will see an option, usually about the type selection of the content editor.Find and check the Enable Markdown editor, then save your changes.After completing this step, when you create or edit documents again, the rich text editor will automatically switch to the Markdown editor.

Markdown content is rendered correctly

Enabled Markdown editor, the content you write in the background will be stored in Markdown syntax.However, using Markdown syntax in the background is not enough to make them perfectly displayed on the front page.In order to have a clear and consistent visual style for Markdown text on your website, we need to introduce a style sheet.

We recommend usinggithub-markdown-cssIt can provide elegant styles similar to GitHub for your Markdown content. You can use it in website templates.base.htmlThe file (usually the header file used by all pages) of<head>Add the following line 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" />

This way, your Markdown content (such as headings, lists, code blocks, etc.) will have a unified and beautiful style on the front end.

Display of mathematical formulas

For users who need to display mathematical formulas, Markdown editors combined with the MathJax library can easily achieve professional-level formula rendering.MathJax can convert mathematical expressions in formats such as LaTeX and AsciiMath into high-quality typesetting, whether inline formulas or independent block-level formulas, they can be presented perfectly.

To enable math formula rendering, you also need to add the MathJax CDN script in the website template.base.htmlin the file<head>In the tag, add the MathJax CDN script.

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

Add it, and you can use LaTeX syntax to write formulas in Markdown content. For example:

Inline formula:$E=mc^2$It will be rendered as\(E=mc^2\).

Block formula:

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

will be rendered as: $\( \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi} \)$

The drawing and rendering of flowcharts

Markdown not only handles text and formulas, but also can draw various flowcharts, sequence diagrams, and so on through the integration of the Mermaid.js library.Mermaid.js allows you to describe chart structures with concise text syntax, and then automatically render beautiful graphics.This is very helpful for explaining complex processes or system architectures.

To make your website support flowchart rendering, pleasebase.htmlthe file<head>Tags within, add the Mermaid.js CDN script. Please note that this istype="module"a script of type.

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

Once introduced successfully, you can use Mermaid syntax to create flowcharts in Markdown content. For example:

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

It will be rendered as:

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

Content publishing and advanced rendering

When you add the above mathematical formula or flowchart content in the Markdown editor in the background, save and publish the document, they will be rendered in the front-end page as expected.

It should be noted that AnQiCMS usesarchiveDetailtags to get content whenContentThe field will automatically detect and render Markdown syntax as HTML. If you are placing Markdown content in a custom field or have some special requirements to manually control the rendering process, you can userenderFilter. For example, if you have a custom multi-line text field namedcustom_markdown_fieldThe custom field contains Markdown content, you can call it in the template like this to ensure it is rendered correctly: 

{{ archiveDetail customMarkdownField with name="custom_markdown_field" | render | safe }}

Here are the|renderEnsure Markdown is converted to HTML,|safethen inform the template engine that this is safe HTML content and does not need to be escaped again.

By using these settings, you can fully utilize the powerful features of Markdown on the AnQiCMS website to create more expressive and easier-to-read professional content.

Common Questions (FAQ)

1. Why do I enable Markdown editor, but the content on the front end still does not have style and is displayed as plain text?

This is usually because you haven't included it in the website'sbase.htmlfilegithub-markdown-cssStyle sheet.Although the background editor allows you to use Markdown syntax, the browser itself does not know how to beautify these Markdown elements.After introducing this CSS file, your Markdown titles, lists, and code blocks will have unified and beautiful default styles.

2.I have already introduced the CDN scripts for MathJax and Mermaid.js according to the steps, but after entering formula or flowchart code in the article, they are still displayed as the original code and not rendered. Why is that?

Firstly, please check carefully whether the scripts you have includedbase.htmlare complete and in the correct position (usually in the<head>Label inside). For Mermaid.js, it also needs to ensure thatmermaid.initialize({ startOnLoad: true });This line of code is executed correctly, it is responsible for starting the Mermaid rendering.Moreover, the Markdown syntax for formulas and flowcharts is very strict, and any minor spelling errors or formatting issues can lead to rendering failure.$..$or\(..\)Block-level formulas use$$..$$or\[..\]; The chart content of Mermaid.js must be wrapped inmermaid` 和` code block).

3. If my article content is in pure HTML format, not Markdown, will it be affected if the Markdown editor is enabled?

AnQiCMS's Markdown editor usually has a switch mode, or it automatically recognizes when you paste pure HTML content. If you paste or write pure HTML code directly in the Markdown editor, and the content field is eventually|safeorrender|safeFilter processing (or the default rendering logic within AnQiCMS allows), then these HTML codes are usually parsed and displayed normally by the browser and not treated as plain text.However, to avoid potential style conflicts or unnecessary parsing issues, if you are sure that the content is pure HTML, it is best to use a traditional rich text editor to edit, or ensure that your Markdown rendering configuration does not have a negative impact on pure HTML.