Auto CMS provides powerful and flexible content management capabilities for users, among which the support for Markdown format greatly enhances the efficiency of content creators.Whether it is necessary to display complex mathematical formulas in technical articles or clear flowcharts in product documents, Anqi CMS can help you beautifully present these contents on the frontend page.

To achieve this goal, we need to go through several steps, from backend settings to frontend template adjustments, to ensure that the content can be correctly parsed and rendered.

Step 1: Enable Markdown Editor in the Background

Firstly, you need to enable the Markdown editor in the backend management interface of Anqi CMS. This is the foundation for creating content that includes mathematical formulas and flowcharts.

  1. Log in to the Anqi CMS backend.
  2. Go to the "Global Settings" menu and then click on "Content Settings".
  3. On the Content Settings page, find the "Enable Markdown Editor" option and turn it on.
  4. Save your settings.

After enabling, you can choose to use the Markdown editor for creating articles, single pages, category descriptions, and more.

Second step: Create mathematical formulas and flowcharts in the content

Enable Markdown editor, and you can use Markdown syntax to write mathematical formulas and flowcharts in the text content.

  • Mathematical formula:通常，Markdown中的数学公式可以使用LaTeX语法，并用特定的符号包裹。
    • 行内公式：使用单个美元符号包裹，例如$E=mc^2$.
    • Block-level formula (centered on a single line): Enclosed in double dollar signs, for example$$ \int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2} $$.
  • Flowchart:Flowcharts are usually implemented in Markdown code blocks using Mermaid syntax.
    • In the Markdown editor, create a code block and specify the language as Englishmermaid, for example:
      graph TD;
    A[Start] --> B{Decision};
    B -- Yes --> C[Execute Operation];
    C --> D[End];
    B -- No --> E[Wait];
    E --> A;
      This content will be stored in the database in its original Markdown text form after you save it, waiting to be parsed and rendered by the front-end.

Third step: Ensure the front-end page renders Markdown content correctly

The Markdown editor of Anqi CMS has already converted Markdown content to HTML, but complex rendering of mathematical formulas and flowcharts requires additional JavaScript libraries to handle.This is just like how a browser can parse HTML, but to display beautiful charts or interactive components, you need to introduce the corresponding scripts.You need to include the necessary CDN resources in the front-end template file.

Find the directory of the template you are currently using (usually in/template, for exampledefault), then open the template under it.base.htmlFile. This file usually contains the common header of the website.<head>) and the footer area, which is an ideal place to include global scripts and stylesheets.

Please add the following code snippet tobase.htmlthe file<head>Inside the tag:

  1. Apply Markdown default style:To make the HTML content rendered by Markdown have good formatting and style, we can introduce a general Markdown stylesheet.

    <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:MathJax is a powerful JavaScript rendering engine used to display mathematical formulas in web browsers.

    <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:Mermaid is a JavaScript library that can create charts and visualizations from text definitions similar to Markdown.

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

    Finish these additions and savebase.htmlFile. So, when the browser loads your page, these scripts and stylesheets will be included, thus enabling parsing and rendering of mathematical formulas and flowcharts.

Fourth step: Control the rendering method of content fields in the template

Even if you use the Markdown editor in the background, how the final content is displayed on the front end still needs to be called and controlled in the template file.The AutoCMS provides flexible template tags, allowing you to decide whether to convert content fields from Markdown to HTML.

Taking the document detail page as an example, you will usually usearchiveDetailtags to display article content. The tag'sContentthe field supports onerenderParameter, used to control the behavior of Markdown conversion.

  • By default, if the Markdown editor is enabled on the backend,ContentThe field will automatically convert Markdown to HTML when called. You would typically call it like this:

    {% archiveDetail archiveContent with name="Content" %}
{{ archiveContent|safe }}

    Here are the|safeThe filter is crucial, as it tells the template engine,archiveContentThe HTML content is safe and does not require further escaping; it can be output directly.

  • If you want to explicitly control whether Markdown rendering should occur,"renderParameters:

    • render=true：Force rendering of Markdown content.
    • render=false：Do not render Markdown, output the original Markdown text directly.
    {# 强制进行Markdown转换，并安全输出HTML #}
{% archiveDetail archiveContent with name="Content" render=true %}
{{ archiveContent|safe }}


{# 不进行Markdown转换，输出原始Markdown文本 #}
{% archiveDetail rawContent with name="Content" render=false %}
{{ rawContent }}

    Thisrender参数在处理一些特殊情况时非常有用，例如您可能希望在页面上展示Markdown语法本身而不是渲染后的效果，或者您的内容中包含了部分由其他系统生成的HTML，不希望被Markdown解析器再次处理。

Through these four steps, your CMS website can perfectly display Markdown formatted content on the front end, including complex mathematical formulas and clear flowcharts.

Common Questions (FAQ)

Q1: I have enabled the Markdown editor according to the steps and written mathematical formulas and flowcharts in the content, but these contents are still displayed as raw text on the front-end page and are not rendered. Why is that?

A1:This situation commonly occurs due to not having in the front-end template file (base.htmlor other files containing your website<head>Parts template file) correctly introduce the CDN resources used for rendering mathematical formulas (MathJax) and flowcharts (Mermaid), or the location of introduction is incorrect. Please carefully check whether the three CDN links provided in the third step have been added tobase.htmlof<head>Labels within, and no syntax errors. Also, make sure you call it in the templateContentField was used|safeFilter, for example{{ archiveContent|safe }}to prevent HTML content from being escaped.

Q2: I find that the Markdown content style on the page is somewhat chaotic, or the formulas and flowcharts can be displayed but the style is not good, how to unify the display effect of these contents?

A2:Ensure that the default style of Markdown content is beautiful, which depends on you inbase.htmlthe first CDN resource introduced ingithub-markdown-css.This CSS file provides a set of simple and universal Markdown rendering styles.If the style is still not satisfactory, you can choose: 1.查找其他更符合您网站风格的Markdown CSS库进行替换；2.markdown-bodyClass or its internal elements write additional CSS rules, covering or enhancing the default styles.For formulas and flowcharts, MathJax and Mermaid usually come with decent default styles, but if you have specific requirements, you can refer to their respective official documents to learn how to customize the configuration.

Q3: How should I set up so that both Markdown-written content and some directly pasted HTML code can be displayed correctly without errors in an article of mine?

A3:In such a mixed content scenario, it is recommended to enable the Markdown editor in the background, and ensure that it is called in the templateContentField when usingrender=trueparameter, and always attached|safeFilter, for example{{ archiveContent|safe }}. The Markdown editor of Anqi CMS usually recognizes and retains HTML tags in Markdown content,render=trueAttempts to convert the Markdown part to HTML,|safeThen it ensures that whether the HTML converted by the editor or the HTML you paste directly can be parsed as the original HTML by the browser. If the HTML part is still escaped, please confirm again|safeFilter has been used correctly.