English CMS article content: Easily render Markdown and handle mathematical formulas and flowcharts

Auto CMS is an efficient, customizable, and easy-to-expand content management system, committed to providing users with a convenient content publishing and management experience.In daily content creation, we often encounter scenarios where we need to insert code, tables, even complex mathematical formulas and flowcharts.Traditional rich text editors often struggle to handle such content, while Markdown has become the preferred choice for many content creators with its concise syntax and powerful expressiveness.

It is fortunate that the new version of the AnQi CMS has deeply integrated the Markdown editor, and supports rendering mathematical formulas and flowcharts through simple configuration, greatly enhancing the flexibility and professionalism of content editing.Next, we will explore step by step how to enable these powerful features in the Anqi CMS.

Step 1: Enable Markdown Editor

To make the article content of AnQi CMS support Markdown syntax, you first need to enable the Markdown editor at the system level. This process is very intuitive:

  1. Log in to your Anqi CMS backend.
  2. Find and click on 'Backend Settings' in the left navigation bar.
  3. Enter the "Content Settings" page.
  4. Here, you will find an option named "Enable Markdown Editor". Check this option and save the settings.

After completing this step, when you create or edit an article, the document content editor will switch to Markdown mode, and you can use Markdown syntax to organize and write the content.

第二步：让数学公式在网页上正确显示

For articles containing mathematical formulas, simply enabling the Markdown editor is not enough to make them look beautiful on the front page.The complex layout of mathematical formulas requires the use of special rendering libraries, such as MathJax.Security CMS provides a convenient integration method.

通常，您需要在网站的公共模板文件（例如base.htmlIt defines the basic structure of the website by introducing the CDN resources of MathJax.

  1. Access your website's template file directory through FTP or other file management tools. According to the template conventions of Anqi CMS, template files are usually located/templateUnder the directory, you can find the template folder you are currently using.base.htmlfile.

  2. Openbase.htmlfile, in<head>Add the following code snippet inside the tag:

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

    This code will asynchronously load the MathJax library, enabling it to parse and render mathematical formulas on the page.

Complete the above configuration and you can use LaTeX syntax to write mathematical formulas in the article. MathJax supports two main ways to insert formulas:

  • Inline formulaUse a single dollar sign$Wrapper formula, for example$(a+b)^2 = a^2 + 2ab + b^2$The formula will be displayed within the text line.
  • [en]Block FormulaUse double dollar signs$$Wrapper formula, for example$$E=mc^2$$The formula will be displayed as a block and centered.

or you can also use the more formal block-level formula in the LaTeX environment, such as\begin{equation} \sum_{i=1}^{n} i = \frac{n(n+1)}{2} \end{equation}.

Step 3: Integrate and display the Markdown flowchart

In addition to mathematical formulas, Markdown also supports drawing flowcharts, sequence diagrams, and more with Mermaid syntax.This is very helpful for demonstrating complex concepts and workflows.Auto CMS also supports integration with Mermaid.

Similar to MathJax, you need to include Mermaid's CDN resources in your template file. It is usually recommended to place it inside.base.htmlof<head>the tag or<body>at the bottom of the tag:

  1. Continue editing yourbase.htmlfile.

  2. Add the following code snippet at the appropriate location in the file

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

    This code will load the Mermaid library and initialize it to render Markdown flowcharts automatically when the page loads.

Configuration completed, you can create flowcharts in the article. Mermaid flowcharts need to be enclosed in specific code blocks: English

```mermaid
graph TD;
    A[开始] --> B{决策};
    B -- 是 --> C[执行操作];
    B -- 否 --> D[结束];
    C --> D;
```

Step 4: Beautify the default style of Markdown content

To make the rendered content of Markdown more unified and visually appealing on your website, you can introduce GitHub-style Markdown styles.This can make your code blocks, citations, lists, and other elements look more professional and readable.

  1. Continue editing yourbase.htmlfile.

  2. In<head>Add the following CSS stylesheet link inside the label:

    <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 CSS will provide a simple and universal style set for your Markdown content.

Details of rendering the article content field

In the template tag usage of AnQi CMS, if the article content isContentField enables Markdown editor, the system will automatically convert the Markdown syntax in it to HTML.But in some special cases, you may need to explicitly control this behavior, for example when you import content from other data sources.

When you use a templatearchiveDetaildisplayed using tags, for example{% archiveDetail articleContent with name="Content" %}you can choose to addrender参数来手动控制Markdown到HTML的转换：

  • render=true：强制对内容进行Markdown到HTML的转换。
  • render=false：Prevent Markdown from being converted to HTML (the content will be displayed as raw Markdown text).

Additionally, to ensure that HTML content (whether converted from Markdown or written directly) is parsed correctly rather than escaped as plain text, it is imperative to do so in the outputContentField when using|safeFilter, for example:{{articleContent|safe}}or{{articleContent|render|safe}}.

Through these steps, your CMS website will be able to perfectly support Markdown syntax for article content, not only beautifully display mathematical formulas, but also draw exquisite flowcharts with concise Mermaid syntax, while also featuring professional Markdown styles, greatly enhancing the expressiveness of your content and the reading experience of users.

Common Questions and Answers (FAQ)

  1. I have enabled the Markdown editor and added CDN links according to the steps, but why are the mathematical formulas and flowcharts in the article still not displaying, or displaying as raw text?

    • Troubleshooting direction: Firstly, please make sure that you have checked the 'Enable Markdown Editor' in the 'Content Settings' backend and saved. Secondly, check yourbase.htmlFile, confirm whether the CDN links of MathJax and Mermaid are accurate and error-free, and whether the network environment can access these CDN resources normally.Sometimes, CDN links may fail to load due to network issues.$...$or$$...$$），流程图使用了正确的Mermaid代码块（Englishmermaid ...）。另外，在模板中输出文章内容时，务必使用English{{archiveContent|safe}}or{{archiveContent|render|safe}}，确保HTML内容未被二次转义（English）

  2. I found that the images in the article and some HTML tags were also covered by Markdown style, resulting in some confusion in layout. What should I do?

    • Troubleshooting direction: GitHub Markdown CSS（English）github-markdown-css）is a global style that may affect existing HTML elements in the content. If you do not want it to affect all content, there are several solutions:
      • Local application of style:Not inbase.htmlglobally imported ingithub-markdown-css, but in the article detail page template, wrap the article content in a container with a specific class (for examplemarkdown-body) ofdivand then only apply to this containergithub-markdown-css. For example:<div class="markdown-body"> {{articleContent|safe}} </div>.github-markdown-cssIt is usually designed to act upon.markdown-bodyclass.
      • Custom CSS Override:If you only need to adjust some styles, you can write custom CSS rules to overridegithub-markdown-cssparts that do not match your expectations.

  3. Is the Markdown editor automatically switched during article editing, or do I need to manually select it? How can I disable Markdown rendering for specific articles?

    • Answer:When you enable the Markdown editor in the background "Global Settings -> Content Settings", allNewly createdorEdit的文章，its content editor will default to Markdown mode.This means you do not need to select manually.As for disabling Markdown rendering for specific articles, the global settings of Anqi CMS currently determine the behavior of the editor.The option to disable Markdown rendering for a single article is not mentioned in the document.