In AnQiCMS, Markdown is an efficient and widely popular content creation method.It uses a concise markup syntax, allowing creators to focus on the content itself without being troubled by complex layout tools.However, to present these concise Markdown texts to the user in the browser, it requires the collaboration of the AnQiCMS backend and frontend templates.Understanding this process can help you better utilize the content management capabilities of AnQiCMS, ensuring that your content is displayed in **status**.

Enable Markdown Editor: The First Step in Content Creation

First, enabling the Markdown editor in the AnQiCMS backend is the basis for writing content in Markdown.Generally, you can find the corresponding option to enable it under the "Global Settings" and "Content Settings".This step is very critical, it tells the system that you will use Markdown syntax to write the detailed content of the article, page, or category.Once enabled, when you enter Markdown text in the main editing areas such as document content, page content, or category content, the system will recognize it and prepare for subsequent rendering.

For example, you enter: 

# 欢迎来到 AnQiCMS
这是一个 **强大** 的内容管理系统。

- 部署简单
- 功能丰富
- 扩展性强

On the front-end page, we expect to see headings, bold text, and lists, rather than the original Markdown symbols.

Content writing and automatic parsing: Preliminary conversion from Markdown to HTML

When you enter Markdown content in the AnQiCMS editor and save it, the system will preliminary parse and convert these contents in the background. For main content fields such as documents, pages, and categories (such asarchive.Content/page.Content/category.Content），AnQiCMS by default, after enabling the Markdown editor, it will automatically convert Markdown text to standard HTML structure.This means that you do not need to manually perform the conversion operation, the system will intelligently complete this task.

For example, you can directly call the article content in the template:

<div>
    {{ archive.Content }}
</div>

at this point,archive.ContentThe variable already contains the HTML code converted from Markdown.

Template layer rendering control: Ensure HTML is displayed correctly

Although AnQiCMS automatically converts Markdown to HTML, some additional processing is still required on the front-end template level to ensure that the content is displayed correctly and securely.

1. Use|safeFilter prevents double escaping

The content converted by Markdown is essentially a string containing HTML tags. If these strings are output directly in a template without special handling, the template engine may, for safety, convert the following</>Escape characters as&lt;/&gt;This will cause the page to display the original HTML code rather than the rendered visual effect.

Therefore, in the AnQiCMS template, any variable containing HTML content (including HTML converted from Markdown) must be used|safeThe filter informs the template engine that the content of this variable is safe HTML and can be output directly without additional escaping.

The correct usage is: 

<div>
    {{ archive.Content|safe }}
</div>

2. Flexible application|renderManual control of the filter

In most cases, AnQiCMS will automatically handle Markdown rendering in the background. But if your Markdown content is stored in a custom field, or if you need to control the rendering time more accurately,|renderThe filter comes into play.

For example, if you have customized a field namedintroductionto store a Markdown formatted summary:

{% archiveDetail introduction with name="introduction" %}
    {{ introduction|render|safe }}
{% endarchiveDetail %}

Here|renderThe filter will force theintroductionMarkdown text in variables is rendered as HTML. It also acceptsrender=trueorrender=falseparameters to more explicitly specify whether to render:

  • render=trueForce the conversion of content from Markdown to HTML.
  • render=falseDo not perform Markdown conversion, return the original content directly.

For example, manually specify rendering:

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

3. Introducing external resources: complete presentation of mathematical formulas and flowcharts

The basic Markdown syntax can be converted to HTML to display normally, but for more advanced features such as mathematical formulas (LaTeX) and flowcharts (Mermaid), simply converting to HTML is not enough.They need to be parsed and rendered on the browser side with the help of additional JavaScript libraries.

The AnQiCMS documentation clearly mentions how to integrate these features, you need to introduce the corresponding CDN resources in the template.<head>Part of the CDN resources to be introduced:

  • Markdown default style (optional, for beautification):To make the rendered Markdown look more beautiful, 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" />
  • Mathematical formula (MathJax):If your content contains LaTeX-formatted mathematical formulas, you need to include the MathJax library.
    
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
  • Flowchart (Mermaid):If your content contains Mermaid flowchart syntax, you need 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>
    These inclusions are usually placed in the template of your websitebase.htmlfile (or similar header inclusion file)<head>tags to ensure they are executed when the page is loaded.

Summary

In AnQiCMS, Markdown content is correctly rendered as HTML from the editor to the front-end page, which is a smooth process completed by the backend processing and front-end template collaboration. By enabling the Markdown editor in the backend, using the system's automatic Markdown to HTML conversion, and using the front-end template reasonably|safeand|renderA filter, as well as on-demand introduction of external rendering libraries (such as MathJax and Mermaid), will ensure that all Markdown content, whether it is plain text, code blocks, or complex mathematical formulas and flowcharts, is presented to the visitor in a clear, beautiful, and fully functional manner.

Frequently Asked Questions (FAQ)

1. Why is the Markdown content I post displayed as raw Markdown syntax on the front end instead of rendered HTML?

This is usually because you forget to use|safethe filter. Markdown text converted to HTML, if it is not processed|safeHandle, the template engine will escape the HTML tags within it for security reasons, causing them to be displayed as raw code. Ensure that the content variable is immediately followed by|safeFor example{{ archive.Content|safe }}.

2. Why does my article contain mathematical formulas or flowcharts, but only the original LaTeX or Mermaid code is displayed on the front end, without graphical representation?

AnQiCMS is responsible for converting these special Markdown syntaxes into basic HTML structures, but their graphical rendering depends on JavaScript libraries on the browser side. You need to include in the website template's<head>Introduce the corresponding CDN resources, such as MathJax (for mathematical formulas) and Mermaid (for flowcharts) libraries, and ensure they are initialized correctly.The specific code introduction can be referred to in the relevant documents of AnQiCMS.

**3. I entered Markdown content in the custom model field, but it did not automatically render like the document content.