Enable the complete guide to Markdown, rendering mathematical formulas and flowcharts in AnQiCMS

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 seems inadequate.Luckyly, the new version of AnQiCMS has integrated support for Markdown editors and can render mathematical formulas and flowcharts well, greatly enhancing the efficiency and expressiveness of content creation.

Next, we will explore together how to enable these powerful features in AnQiCMS, 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 Settings" in the left menu, and then click to enter the "Content Settings" page.On this page, you will see an option, usually about the type of content editor.Find and check the Enable Markdown Editor, then save your changes.After completing this step, when you create or edit a document again, the rich text editor will automatically switch to the Markdown editor.

The correct rendering of Markdown content

After enabling the Markdown editor, the content you write in the background will be stored in Markdown syntax.However, merely using Markdown syntax in the background is not enough to make them perfectly presented on the front-end page.In order to give Markdown text a clear and consistent visual style on your website, we need to introduce a style file.

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 for 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 LaTeX, AsciiMath, and other formats into high-quality typesetting, whether in-line formulas or independent block-level formulas, they can be presented perfectly.

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

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

After adding, 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-level formula:

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

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

Drawing and rendering of flowcharts

Markdown can handle text and formulas and can also draw various flowcharts, sequence diagrams, etc. by integrating the Mermaid.js library.Mermaid.js allows you to describe chart structures with concise text syntax and then automatically render them into beautiful graphics.This is very helpful for explaining complex processes or system architectures.

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

<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 expected way on the front page.

It should be noted that AnQiCMS is used on the document detail pagearchiveDetailits tag to retrieve contentContentThe field defaults to detecting and rendering Markdown syntax as HTML. If you are placing Markdown content in a custom field or have some special requirements and want to manually control the rendering process, you can userenderFilter. For example, if you have a custom 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|renderEnsure Markdown is converted to HTML,|safethen inform the template engine that this is safe HTML content, no further escaping is needed.

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

Frequently Asked Questions (FAQ)

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

This is usually because you have not included on the website'sbase.htmlfile inclusiongithub-markdown-cssThe stylesheet. Although the backend 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 headings, lists, code blocks, and other content will have a unified and beautiful default style.

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

First, please carefully check what you havebase.htmlwhether the included script is complete, and whether the location is correct (usually in<head>Within tags). For Mermaid.js, it also needs to ensuremermaid.initialize({ startOnLoad: true });This line of code is executed correctly, it is responsible for starting Mermaid rendering.In addition, the Markdown syntax for formulas and flowcharts is very strict, any minor spelling errors or formatting issues can cause rendering to fail.Please refer to the official documentation of MathJax and Mermaid.js to check if your code block conforms to the standard format (for example, inline formulas in MathJax use$..$or\(..\), use block-level formulas$$..$$or\[..\]; The chart content of Mermaid.js must be wrapped inmermaid` 和` code blocks).

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

AnQiCMS's Markdown editor usually has a toggle 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 this HTML code is usually parsed and displayed normally by the browser and is 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 it, or ensure that your Markdown rendering configuration does not negatively affect pure HTML.