In AnQi CMS, writing articles in Markdown format is an efficient and elegant way of content creation, which makes our content structure clearer and layout more flexible.Especially for technical articles that need to include code, mathematical formulas, and even flowcharts, Markdown editors are an indispensable tool.How can we ensure that these meticulously written Markdown texts are correctly parsed and perfectly presented on the front end of the website?Let us explore step by step.

Enable Markdown Editor

Firstly, to enjoy the convenience brought by Markdown, we need to enable this feature in the Anqi CMS backend. The operation is very simple:

  1. Log in to your Anqi CMS backend.
  2. Find and click in the left navigation barGlobal Settings.
  3. EnterContent SettingsTab.
  4. Here, you will see an option to enable Markdown editor. Check it and save your settings.

Once enabled, when you create or edit an article, the document editor will switch to Markdown mode, and you can start using Markdown syntax to write content.

Write Markdown text in the article

In the Markdown editor, you can create using standard Markdown syntax, for example:

  • Use#Create a title (# 一级标题,## 二级标题).
  • Use*or_Italic or bold text (*斜体*,**加粗**).
  • Use-or*Create an unordered list, using1.Create an ordered list.
  • Use backticks ` to create inline code, or use triple backticks ```python`` ` to enclose a code block.
  • Insert image “。”

The Markdown editor of AnQi CMS also supports more advanced content, such as mathematical formulas and flowcharts, which is very practical for articles in many professional fields.You can directly embed LaTeX syntax mathematical formulas or Mermaid syntax flowcharts in the editor, and the system will save them as raw Markdown text.

Ensure that the Markdown content is displayed correctly on the web page

The content of the article is saved in Markdown format, and the Safe CMS will automatically convert it to HTML when outputting the content to the front-end of the web page.However, in order for the converted HTML content to not only be structurally correct but also have beautiful styles and correctly render mathematical formulas and flowcharts, some additional configurations need to be made in the website template.

Normally, these configurations need to be made in your website template'sbase.htmlfile, which is usually located in/template/{您的模板目录}/auto<head>auto

  1. autoTo make the HTML elements converted from Markdown (such as headings, lists, code blocks) have good default visual effects, you can introduce GitHub-style Markdown CSS.

    <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. Correct display of mathematical formulas (MathJax):If you have used LaTeX syntax mathematical formulas in the article, you need to introduce the MathJax library to parse and render them.

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

  3. Correctly display the flowchart (Mermaid):For flowcharts drawn with Mermaid syntax, it is necessary to import the Mermaid library and initialize it.

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

Add these code snippets tobase.htmlthe file<head>Area, it ensures that these rendering libraries are correctly referenced when the page is loaded, thereby enabling Markdown content, including complex mathematical formulas and flowcharts, to be perfectly presented on your website.

Template content rendering logic

In the Anqi CMS template, whether it is an article (archive) or a single page (pageThe content field, usually, will be automatically converted from Markdown to HTML in the background. When you call these contents in the template, for example usingarchiveDetailtags to getContentField, and when outputting it, be sure to use|safeFilter.

For example, you may display the article content like this in your article detail template:

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

Here are the|safeThe filter is very important, it tells the template engine,articleContentThe content in the variable is safe HTML and does not need to be escaped again. If missing|safeThe browser may display HTML tags as plain text, causing the article layout to be disordered and even resulting in garbled text.

In addition,archiveDetailthe tag also provides,renderParameter, allows you to manually control the conversion from Markdown to HTML. When you turn off the Markdown editor in the content settings, but the article content is still in Markdown format, you can userender=trueParameter is forced to be converted:

<div>文档内容：{% archiveDetail archiveContent with name="Content" render=true %}{{archiveContent|safe}}</div>

If you want to get the original Markdown text without any conversion (for example, if you want to use a JavaScript library for custom rendering on the front end), you can userender=false:

<div>原始Markdown内容：{% archiveDetail archiveContent with name="Content" render=false %}{{archiveContent|safe}}</div>

By following these steps, you can not only easily create content using Markdown in the AnQi CMS, but also ensure that these contents are presented professionally, accurately, and beautifully on the website front end.This will undoubtedly greatly enhance your content creation efficiency and the user experience of your website.

Common Questions (FAQ)

Q1: I have enabled the Markdown editor and written content, but the article is displayed as raw Markdown text on the website front end and is not parsed into HTML. Why is that?

A1: This is very likely because you did not use it when outputting article content in the template.|safeFilter. When the CMS converts Markdown content to HTML, for safety, the template engine defaults to escaping all output content.|safeThe filter informs the template engine that the content you output is expected HTML and does not need to be escaped again, so the browser can render HTML tags correctly. Please check your article detail template to ensure that the outputContentField was used{{ archiveContent|safe }}.

Q2: I have inserted mathematical formulas or flowcharts into the article, but they only display as raw code or text, and are not rendered as charts or formulas. How can I solve this?

A2: Rendering mathematical formulas (such as LaTeX) and flowcharts (such as Mermaid) requires specific JavaScript libraries to be processed on the client side.Although the Anqi CMS backend will convert these Markdown contents to standard HTML, the browser cannot recognize and render them if the corresponding JS library is not introduced on the frontend.base.htmlthe file<head>Tags have correctly introduced CDN links and initialization code for MathJax (used for mathematical formulas) and Mermaid (used for flowcharts).

Q3:archiveDetailTagsrenderWhat is the parameter used for? In what situations do I need to use it?

A3:renderThe parameter allows you to manually control whether Markdown content is converted to HTML in the background. By default, if your background has the Markdown editor enabled,archiveDetailThe content will automatically convert Markdown to HTML. But if you have turned off the Markdown editor in the background, and the article content itself is in Markdown format, you can userender=trueMandatory conversion. Otherwise, if you wish to obtain the original Markdown text (for example, if you plan to use a custom JavaScript library to handle Markdown on the front end), you can userender=falseTo prevent automatic conversion in the background. In most cases, if you have enabled the Markdown editor in the background, it is usually not necessary to set explicitlyrender=trueBut understanding its function can help you control the display of content more flexibly in specific scenarios.