How to automatically render Markdown format content to HTML when AnQiCMS displays article content?

In Anqi CMS, automatically rendering Markdown content into HTML is a core feature provided by the system, aimed at helping content creators publish rich text content in a concise and efficient manner.This process is not a mysterious black box operation, but is achieved through clear settings and flexible template tags.

Core Mechanism: Automatic Rendering of Markdown Content

The core reason why AnQi CMS can transform your Markdown content into a beautiful web page layout lies in its intelligent backend processing and frontend template parsing capabilities.When you write articles, product descriptions, or page content using Markdown syntax in the content editor, the system will automatically convert them during content display.

To implement this feature, you need to make a key setting in the Anqi CMS backend. Please navigate to“Global Settings”of"Content Settings". Here you can find an option to enable Markdown editor.Once you enable the Markdown editor, the system will know that the content edited using this editor needs to be parsed according to the Markdown rules.

This means that when the user visits your article detail page, category introduction page, or standalone page, the system will retrieve the Markdown text stored in the database and convert it to standard HTML code using the built-in Markdown parser.This conversion process is automatically completed, you do not need to manually write any conversion scripts, greatly simplifying the content publishing process.

For example, you used the Markdown syntax when editing the article# 标题/**粗体文字**/- 列表项After saving, the front-end page will automatically display as<h1>标题</h1>/<strong>粗体文字</strong>/<ul><li>列表项</li></ul>the corresponding HTML structure.

Flexibly control Markdown rendering in the template

Although by default, when the Markdown editor is enabled, the content is automatically rendered.But AnQi CMS also provides options for more fine-grained control at the template level.This is very useful in certain specific scenarios, such as when you want the Markdown format of some content not to be rendered, or to force render some content even if it was not originally input through the Markdown editor.

In AnQiCMS template tags, such asarchiveDetail(Used for article details),categoryDetail(Used for category details) andpageDetail(Used for single page details) and other tags, itsContentAll fields support arenderThe parameter allows you to manually specify whether to convert content from Markdown to HTML.

In particular:

• render=true: Even if the Markdown editor is not enabled on the back-end, or the content is not entered through the Markdown editor, this parameter will force the system to parse and render the obtained content into HTML.
• render=false: Regardless of whether the Markdown editor is enabled on the backend or the content is in Markdown format, this parameter will prevent the system from converting Markdown to HTML, and the content will be output in its original text form (including the original Markdown syntax).

Usage example:

Suppose you want to display the article content and ensure that its Markdown format is always rendered:

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

Please note here|safeFilter. This is a very important security measure. Markdown rendering results in HTML code, and if it is output directly, the browser may escape it out of security considerations, causing the HTML tags to not display normally.|safeThe filter tells the template engine that you trust this content is safe HTML and can be output directly without escaping. You should be cautious when handling any code that may contain HTML.|safe.

On the contrary, if you want to display the original Markdown text without rendering:

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

There is none here|safeFilter, because we want to display the original text, even if it contains<or>such characters should be escaped and displayed, rather than being parsed as HTML tags by the browser.

Enhance content display: Extend the advanced features of Markdown

The Anqi CMS not only supports basic Markdown rendering, but also provides extended features to make your content more expressive, such as support for displaying mathematical formulas and flowcharts.These advanced features also rely on Markdown syntax, but their rendering usually requires additional front-end resources (such as JavaScript libraries and CSS styles) support.

You need to display mathematical formulas in Markdown (such as LaTeX) and flowcharts (such as Mermaid) correctly on your website:

1. Enable Markdown editor:Ensure that the Markdown editor is enabled in the background "Global Settings" -> "Content Settings."
2. Insert specific code:In your article content, insert mathematical formulas or flowcharts according to the Markdown specification.
3. Add frontend support:To make the browser able to parse and render these special Markdown elements, you need to include the template file (usuallybase.htmlInclude the corresponding third-party CDN resources (CSS and JavaScript) in the header of the template that includes the article content.These resources will provide the necessary parsing and rendering capabilities. For example,help-markdown.mdThe document explains in detail how to introduce the relevant scripts for MathJax and Mermaid.

With these configurations, your Markdown content can not only be automatically converted to HTML, but also carry more complex structures and visual effects when needed.

In short, the Anqi CMS displays article content by enabling the Markdown editor status in the background and coordinating with template tags.renderThe parameter has implemented automatic rendering of Markdown content, and has provided flexible control capabilities, even being able to expand the advanced features of Markdown by introducing external resources, providing users with a powerful and convenient content publishing experience.

Frequently Asked Questions (FAQ)

1. What is the reason that I have published an article in Markdown format, but it is displayed as raw Markdown text on the front-end page instead of being rendered into HTML?Answer: There are usually several reasons. First, make sure you have enabled the Markdown editor in the "Global Settings" -> "Content Settings" of the AnQi CMS backend.If the editor is not enabled, the system will not automatically parse Markdown.The next, in the front-end template, display the tags of the article content (such asarchiveDetailMay not have been used correctlyrender=trueOr more commonly, missing a parameter|safefilter.|safeThe filter is crucial for correctly outputting rendered HTML code to the browser, otherwise the browser may escape it as plain text.

2. Ask: Does AnQi CMS support mixing HTML tags with Markdown content?Answer: Yes, one of the advantages of Markdown is that it is compatible with HTML. You can directly insert standard HTML tags into Markdown content, such as<div>/<span>/<table>When the system parses Markdown, these HTML tags will be retained and output to the final HTML page.This provides a flexible combination of Markdown's concise syntax and HTML's powerful presentation.

3. Ask: If I don't want to Markdown render some custom fields (such as the 'Summary' field of articles), how should I operate?Answer: If you want to customize the content of a field so that it is not rendered as Markdown, you can use template tags such asrender=falseparameters. For example, for a field namedintroductionYou can use this custom field{% archiveDetail introduction with name="introduction" render=false %}{{introduction}}to retrieve its content and prevent rendering. This field will always be output in plain text form (or its original HTML code).