AutoCMS provides flexible content editing methods for content creators, where support for Markdown format greatly enhances the efficiency and expressiveness of content creation.Understanding how to correctly use Markdown in document content and ensure it renders perfectly as HTML on the website frontend is the key to leveraging this feature advantage.

Enable and use the Markdown editor

To start using Markdown in AnQiCMS, you first need to perform a simple configuration. This is usually inGlobal Settings -> Content SettingsCompleted.Enable Markdown editor after, when you edit documents, single-page or categorized content, the content input box will switch from the traditional rich text editor to a plain text editor that supports Markdown syntax.

Once enabled, you can use Markdown syntax in the content editing area. For example, you can use#to represent headings,**粗体**to indicate bold text,[链接](URL)to create a hyperlink,插入图片，以及-或*`Create lists and more. These basic syntaxes will be automatically parsed and converted to corresponding HTML structures by AnQiCMS template engine.

For more advanced Markdown applications, such as mathematical formulas and flowcharts, AnQiCMS also provides support.To ensure that these advanced elements can be properly parsed and displayed by the browser, you need to include some third-party JavaScript libraries and style files.base.htmlorheader.html) of<head>tags or</body>Before the end tag.

For example, if you want to display Markdown styles, mathematical formulas, and flowcharts correctly on a website:

  • Basic Markdown StylesTo make the rendered Markdown content have clear formatting and style, you can introduce a Markdown CSS similar to GitHub.

    <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 display：For mathematical formulas written in LaTeX or MathML, the MathJax library can be introduced to parse and beautifully display them.

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

  • Flowcharts and chartsEnglish:Mermaid is a popular JavaScript library that can convert Markdown-style text descriptions into diagrams such as flowcharts and sequence diagrams.

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

Add this code to your template file, and you can write the corresponding syntax in Markdown content, for example, using$$...$$Wrap mathematical formulas or use Mermaid's code block syntax (such asmermaid) to create charts.

Ensure that the content is rendered correctly as HTML

In AnQiCMS, the final display effect of content is determined by template tags and filters.Understand how to use them correctly is the key to ensure the correct rendering of Markdown content.

After enabling the Markdown editor in the background, througharchiveDetail/categoryDetail/pageDetailTags obtained with autoContent字段内容，AnQiCMS的模板引擎通常会自动将其从Markdown转换为HTML。这意味着您在模板中直接输出English{{ archive.Content }}In most cases, you can see the rendered HTML.

However, in certain specific scenarios, you may wish to manually control the rendering process of Markdown content, or ensure that the content is not interfered with by the default escaping mechanism of the template engine. AnQiCMS providesrenderparameters with|safeFilter.

  • renderParameters: InarchiveDetail/categoryDetail/pageDetailEnglish tags obtainedContentwhen a field is specified, you can addrenderparameters to explicitly specify whether to perform Markdown to HTML conversion.render=truewill enforce the conversion, whilerender=falseIt will prevent conversion and directly output the original Markdown text. For example：

    {# 强制将Markdown内容渲染为HTML #}
<div>文档内容：{% archiveDetail archiveContent with name="Content" render=true %}{{archiveContent|safe}}</div>
{# 不进行Markdown渲染，显示原始Markdown文本 #}
<div>原始Markdown：{% archiveDetail archiveContent with name="Content" render=false %}{{archiveContent}}</div>

    This parameter is very useful when you need to process the same Markdown content differently.

  • |safeFilterIn AnQiCMS template system, to prevent potential cross-site scripting (XSS) attacks, all content output to the page through variables is default escaped as HTML entities. This means that like<Such HTML special characters will be converted to&lt;to ensure that the browser displays it as text instead of parsing it as an HTML tag.

    Therefore, for content rendered with Markdown or that you wish to output as HTML (such as throughrender=truethe processed content), you must use|safeThe filter is used to explicitly inform the template engine that this content is safe HTML code and does not require further escaping. If it is missing|safeFilter, you may see the original HTML code (for example<p>我的段落</p>) instead of the rendered effect (an actual paragraph).

    The correct approach is:

    {# 确保渲染后的HTML内容被浏览器正确解析 #}
<div>文档内容：{% archiveDetail archiveContent with name="Content" render=true %}{{archiveContent|safe}}</div>

    |safeThe filter is a crucial step to ensure that Markdown content is correctly parsed and displayed as HTML by the browser.

Through the above steps, that is, enabling Markdown in the background, introducing the necessary third-party libraries in the template, and using them as needed during content outputrenderparameters with|safeFilter, you can fully utilize the Markdown function of AnQiCMS to create and display high-quality document content efficiently.

Common Questions (FAQ)

  1. Why did I enable the Markdown editor, but the content is displayed as raw Markdown syntax on the front-end rather than rendered HTML?This is usually because the content is missing when outputting in the template|safeFilter. AnQiCMS defaults to escaping HTML special characters for security reasons. Markdown content is converted to HTML, and if it is output directly without|safeFilter, these HTML tags will also be escaped, causing them to be displayed as raw code on the page. Please make sure to add them when outputting Markdown converted content (such as{{ archiveContent }}）|safefor example{{ archiveContent|safe }}.

  2. How do I solve the problem that my mathematical formula or flowchart does not display or displays as a code block instead of a graphic?Markdown editor itself is responsible for parsing the text syntax of mathematical formulas and flow charts, but browsers do not natively support their rendering. You need to use the template files of the website (usually)base.htmlor include the corresponding third-party JavaScript library in the public header file.For mathematical formulas, MathJax needs to be introduced; for flowcharts, Mermaid needs to be introduced.Please refer to the code snippets provided in the article and ensure that these libraries are correctly imported into your website.

  3. Can AnQiCMS's Markdown editor and rich text editor be used at the same time?Can I use Markdown in some content types and rich text in others?Currently, the Markdown editor and rich text editor in AnQiCMS are globally switched, meaning that after you enable the Markdown editor in "Global Settings -> Content Settings", all modules that support content editing (such as documents, single pages, category descriptions, etc.) will use the Markdown editor uniformly.You cannot directly switch to independent editors for different content types in the background.render=falseThe parameter can also be optional