How to use Markdown formatting in document content and ensure it is correctly rendered as HTML?
AnQi CMS provides flexible content editing methods for content creators, and the support for Markdown formats greatly enhances the efficiency and expressiveness of content creation.Understanding how to use Markdown correctly in document content and ensure that it is perfectly rendered as HTML on the website front-end is the key to leveraging this functional advantage.
Enable and use the Markdown editor
To start using Markdown in AnQiCMS, you first need to make simple configurations in the background. This is usually inGlobal settings -> Content settingsChinese is completed. After enabling the Markdown editor, when you edit documents, single pages, or categorized content, the content input box will switch from the traditional rich text editor to a pure text editor that supports Markdown syntax.
Once enabled, you can use Markdown syntax in the content editing area. For example, you can use#Indicates the title,**粗体**to indicate bold text,[链接](URL)to create a hyperlink,插入图片，以及-或*`Create a list and other. These basic syntax will be automatically parsed and converted into corresponding HTML structure by AnQiCMS template engine.
For more advanced Markdown applications, such as mathematical formulas and flowcharts, AnQiCMS also provides support.To make these advanced elements parse and display correctly in the browser, you need to include some third-party JavaScript libraries and style files.These code snippets are usually placed in the public header file of your website template (such asbase.htmlorheader.html）的<head>or within tags.</body>Before the end tag.
For example, if you want to display Markdown styles, mathematical formulas, and flowcharts correctly on a website:
Basic Markdown style: To make the rendered Markdown content have clear formatting and style, you can introduce 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" />Math formula displayFor mathematical formulas written in LaTeX or MathML, the MathJax library can be introduced to parse and display them beautifully.
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>Flowcharts and charts: Mermaid is a popular JavaScript library that can convert Markdown-style text descriptions into flowcharts, sequence diagrams, and other charts.
<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 will be able to write the corresponding syntax in Markdown, for example, using$$...$$Enclose mathematical formulas or use Mermaid code block syntax (such asmermaid) to create charts.
Ensure 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 ensuring that Markdown content is rendered correctly.
After you enable the Markdown editor in the background, througharchiveDetail/categoryDetail/pageDetailThe label getsContentField content, the AnQiCMS template engine will usually automatically convert it from Markdown to HTML. This means that you can directly output it in the template{{ archive.Content }}In most cases, you can see the rendered HTML.
However, in certain specific scenarios, you may want 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 provides this feature.renderParameters and|safefilter.
renderParameterInarchiveDetail/categoryDetail/pageDetailto getContentWhen specifying a field, you can addrendera parameter to explicitly specify whether to perform Markdown to HTML conversion.render=trueit will enforce the conversion, andrender=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 the AnQiCMS template system, to prevent potential cross-site scripting (XSS) attacks, all content output to the page via variables is default HTML entity encoded. This means that, like<Such HTML special characters will be converted to<, to ensure that the browser displays it as text instead of parsing it as an HTML tag.Therefore, for content that has been rendered in Markdown or you wish to output as HTML (such as through
render=trueprocessed content), you must use|safeThe filter explicitly informs the template engine that the content is safe HTML code and does not require further escaping. If missing|safeFilter, you might see the original HTML code (for example<p>我的段落</p>) rather than the rendered effect in the browser (an actual paragraph).The correct approach is:
{# 确保渲染后的HTML内容被浏览器正确解析 #} <div>文档内容：{% archiveDetail archiveContent with name="Content" render=true %}{{archiveContent|safe}}</div>|safeThe filter is a critical step to ensure that Markdown content is ultimately parsed and displayed correctly by the browser as HTML.
By following these steps, that is, enabling Markdown in the background, introducing the necessary third-party libraries in the template, and using them as needed when outputting contentrenderParameters and|safeFilter, you can fully utilize the AnQiCMS Markdown function, efficiently create and display high-quality document content.
Frequently Asked Questions (FAQ)
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 output content in the template is missing
|safeFilter. AnQiCMS defaults to escaping HTML special characters. If Markdown content is converted to HTML and output without|safeFilter, these HTML tags will also be escaped, causing them to be displayed as raw code on the page. Make sure to output the Markdown converted content (such as{{ archiveContent }}when added}|safeFor example{{ archiveContent|safe }}.How do I display my mathematical formula or flowchart and not as code block instead of graphics?The Markdown editor itself is responsible for parsing the text syntax of mathematical formulas and flowcharts, but browsers do not natively support their rendering. You need to include the template file for the website (usually
base.htmlor import the corresponding third-party JavaScript library in the public header file.For mathematical formulas, MathJax needs to be included; for flowcharts, Mermaid needs to be included.Please refer to the code snippet provided in the article to ensure that these libraries are correctly included in your website.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, that is, 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 switch independent editors for different content types directly in the background.However, even if you have enabled the Markdown editor globally, through the template
render=falseParameters can also be optional