In AnQi CMS, automatically rendering Markdown format content to 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 convert your Markdown content into exquisite web layouts lies in the intelligent processing in the backend and the parsing capability of the front-end templates.When you write articles, product descriptions, or page content using Markdown syntax in the content editor, the system will automatically convert it during content display.

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

This means that when a 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, and you do not need to manually write any conversion scripts, greatly simplifying the content publishing process.

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

Flexible control of Markdown rendering in templates

Although by default, the content is automatically rendered when the Markdown editor is enabled.But Butanqi 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 to prevent certain content from being rendered in Markdown format, or to force the rendering of certain content, even if it was not originally input in Markdown editor.

In AnQiCMS template tags, such asarchiveDetail(Used for article details),categoryDetail(Used for category details) andpageDetail[Used for single page detail] tags, such as,Contentall fields support onerenderparameter. This parameter allows you to manually specify whether to convert content from Markdown to HTML.

In particular:

  • render=trueEven if the Markdown editor is not enabled in the backend, or the content is not input through the Markdown editor, this parameter will still force the system to parse the retrieved content as Markdown and render it into HTML.
  • render=falseThe parameter will prevent the system from converting Markdown to HTML regardless of whether the Markdown editor is enabled on the backend or the content is in Markdown format. The content will be output in its original text form (including the original Markdown syntax).

Example Usage:

Assume you want to display 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:|safe|safeThe filter tells the template engine that you trust this content is safe HTML and can be output directly without escaping. It should be used cautiously when handling any code that may contain HTML.|safe.

In contrast, if you want to display the original Markdown text of the content 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 Presentation: Expand Advanced Markdown Features

The Anqi CMS not only supports basic Markdown rendering but also provides extended features to enhance the expressiveness of your content, such as displaying mathematical formulas and flowcharts.These advanced features also depend on Markdown syntax, but their rendering usually requires additional frontend resources (such as JavaScript libraries and CSS styles) support.

To correctly display mathematical formulas (such as LaTeX) and flowcharts (such as Mermaid) on your website, you need:

  1. Enable Markdown Editor:Ensure that Markdown Editor is enabled in the "Global Settings" -> "Content Settings" in the background.
  2. Insert specific code:In your article content, insert mathematical formulas or flowchart syntax according to the Markdown specification.
  3. Add front-end support:To enable the browser 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) at the beginning of the template that includes or contains the article content.These resources will provide the necessary parsing and rendering capabilities.help-markdown.mdThe document details how to introduce the scripts for MathJax and Mermaid.

Through 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 summary, the Anqi CMS enables the Markdown editor status in the background to display article content with template tags.renderParameters have implemented automatic rendering of Markdown content and provided flexible control capabilities. Even the advanced features of Markdown can be extended through the introduction of external resources, offering users a powerful and convenient content publishing experience.

Common Questions (FAQ)

  1. Question: I have published an article in Markdown format, but the original Markdown text is displayed on the front-end page without being rendered into HTML. Why is that?Answer: There are usually several reasons for this.Firstly, please make sure that 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.archiveDetailMay not have been used correctlyrender=trueParameter, or more commonly, missing|safeFilter.|safeThe filter is crucial for correctly outputting rendered HTML code to the browser, otherwise the browser may escape it as plain text.

  2. Question: Does AnQi CMS support the use of HTML tags in 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>

  3. Question: How can I prevent certain custom fields (such as the 'summary' field of an article) from being Markdown rendered?Answer: If you want to customize the content of fields without Markdown rendering, you can use template tags.render=falseFor example, for a field namedintroductionCustom field, you can use{% archiveDetail introduction with name="introduction" render=false %}{{introduction}}to get its content and prevent rendering. This field will always be output in plain text (or its original HTML code).