Secure CMS article content: Turn on Markdown rendering, easily control mathematical formulas and flowcharts

AnQi CMS as an efficient, customizable and easy-to-expand content management system, dedicated 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 this content, while Markdown, with its concise syntax and powerful expressiveness, has become the preferred choice for many content creators.

It is fortunate that the new version of 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 step by step explore how to enable these powerful functions in Anqi CMS.

Step 1: Enable Markdown editor

To enable Markdown syntax support for the content of Anqin CMS articles, 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 the "Back-end settings" in the left navigation bar.
  3. Go to the 'Content Settings' page.
  4. Here, you will find an option called 'Enable Markdown Editor'. Check this option and save the settings.

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

Second step: Make mathematical formulas display correctly on the web

For articles containing mathematical formulas, merely enabling the Markdown editor is not enough to make them presentable on the front page.The complex typesetting of mathematical formulas requires specialized rendering libraries, such as MathJax.Safe CMS provides a convenient integration method.

Generally, you need to be in the public template file of the website (such asbase.htmlIt defines the basic structure of the website) introduces MathJax CDN resources. The specific method is:

  1. Access the template file directory of your website via FTP or other file management tools. According to Anqi CMS template conventions, template files are usually located in/templateIn the directory, you can find the template folder you are currently using inbase.htmlfile.

  2. Open.base.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.

After completing the above configuration, you can use LaTeX syntax to write mathematical formulas in the article. MathJax supports two main methods for inserting formulas:

  • Inline formula: Use a single dollar sign$Enclose the formula, for example,$(a+b)^2 = a^2 + 2ab + b^2$The formula will be displayed in the text line.
  • Block formula: Use double dollar signs$$Enclose the formula, for example,$$E=mc^2$$The formula will be displayed in a block and centered.

You can also use a 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 through Mermaid syntax.This is very helpful for demonstrating complex concepts and workflows.AnQi 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 placebase.htmlof<head>within the tags or<body>at the bottom of the tags:

  1. Continue editing yourbase.htmlfile.

  2. Add the following code snippet at the appropriate position 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 automatically render the flowchart in Markdown when the page loads.

After the configuration is complete, you can create flowcharts in the article. Mermaid flowcharts need to be wrapped in a specific code block:

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

The fourth step: beautify the default style of Markdown content

To make the rendered content of Markdown on your website more unified and aesthetically pleasing, you can introduce GitHub-style Markdown formatting.This makes 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 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 CSS will provide a simple and universal style for your Markdown content.

Details of rendering the article content field

In the use of template tags in AnQi CMS, if the article content isContentThe field has enabled 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 it in the templatearchiveDetailused to display the article content with a tag, for example{% archiveDetail articleContent with name="Content" %}you can choose to addrenderParameters to manually control the Markdown to HTML conversion:

  • render=true: Force the content to be converted from Markdown to HTML.
  • render=false: Prevent Markdown to HTML conversion (the content will be displayed as raw Markdown text at this point).

In addition, to ensure that HTML content (whether converted from Markdown or written directly) is parsed correctly and not escaped as plain text, it is necessary to outputContentUse field when|safefor example:{{articleContent|safe}}or{{articleContent|render|safe}}.

By following these steps, your Anq CMS website will be able to perfectly support article content with Markdown syntax, not only beautifully displaying mathematical formulas but also drawing exquisite flowcharts with concise Mermaid syntax, while also having professional Markdown styles, greatly enhancing the expressiveness of your content and the reading experience of users.

Frequently Asked Questions (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: First, make sure you have checked the 'Enable Markdown Editor' in the background 'Content Settings' and saved. Second, check yourbase.htmlFile, confirm that the CDN links for MathJax and Mermaid are accurate and that the network environment can normally access these CDN resources.Sometimes, CDN links may fail to load due to network issues.Finally, ensure that you use the correct LaTeX syntax when writing mathematical formulas in the content of your article (such as$...$or$$...$$），The flowchart used the correct Mermaid code block（mermaid ...）。In addition, when outputting the article content in the template, be sure to use{{archiveContent|safe}}or{{archiveContent|render|safe}}，to ensure that the HTML content is not re-escaped.

  2. I found that the pictures in the article and some HTML tags were also covered by Markdown style, causing the layout to be a bit messy, what should I do?

    • Troubleshooting direction: GitHub Markdown CSS(github-markdown-css) is a global style that may affect existing HTML elements in the article content. If you do not want it to affect all content, there are several solutions:
      • Local application of style:Not inbase.htmlGlobally introduced ingithub-markdown-cssInstead, in the article detail page template, wrap the article content in a container with a specific class (for examplemarkdown-body）的divand 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 overrides:If you only need to adjust part of the style, you can write custom CSS rules to overridegithub-markdown-csswhich does not match your expectations.

  3. The Markdown editor switches automatically during article editing, or do I need to manually select it? What if I want to disable Markdown rendering for specific articles?

    • Answer:After you enable the Markdown editor in the background "Global Settings -> Content Settings", allnew createdorEditThe article, 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 current global settings of Anqi CMS determine the behavior of the editor.The document does not mention the option to disable Markdown rendering for a single article.If you need this feature, you may need to modify the article's template on the front end, such as the `