How to enable or disable Markdown rendering in the category detail page's `Content` field?

AnQi CMS provides high flexibility for users, especially in terms of content display. For the category detail page ofContentField, the system allows us to finely control whether it is rendered in Markdown format.This means that website operators can choose the most suitable processing method according to different content types and display requirements.

Understanding the category detail page'sContentfields and Markdown rendering

In AnQi CMS, each category has oneContentfield, used to store the detailed description or introductory content of this category.This field usually supports rich text editing, and Markdown, as a lightweight markup language, is often used for quick content entry due to its simplicity and ease of use.After we edit the content using Markdown syntax in the background, the system needs to 'render' it into standard HTML code so that the style can be displayed correctly on the front-end page.

AnQi CMS provides two levels of control methods to manageContentField Markdown rendering: first is the global setting, which determines the default behavior of all content fields; second is the template-level tag parameters, which allow us to specify particularContentField control is precise, even if the global settings are different.

Global settings: Control the default rendering behavior

Firstly, we can affect the global settings through the backend.ContentThe default Markdown rendering behavior of the field. EnterAnqi CMS backend, Navigate toGlobal Settingsand then selectContent settings. In this interface, you will find a field named "Enable Markdown editorThe options

• Check the 'Enable Markdown Editor' option:If this option is checked, the system will default to trying to convert all content fields that support Markdown editing (including the category detail page'sContentField) performs Markdown to HTML conversion.This means that the content you write in Markdown syntax in the background will be rendered into HTML with the corresponding styles without any additional operation on the front end.
• Uncheck the 'Enable Markdown Editor' checkbox:If this option is not checked, the system will not default to rendering the content field as Markdown.At this time, even if you enter Markdown syntax in the background, the front end will only display the original Markdown text and will not convert it to HTML style.

This global setting provides a unified handling strategy across the website, but sometimes we may need more specific control.

Template level: precise control of Markdown rendering

The Anqi CMS template tags provide strong local control capabilities. Even if the global settings have been determined, we can still use specific template code tocategoryDetaillabel'sContentadd a fieldrenderSpecify the parameter to explicitly determine whether Markdown rendering is to be performed.

When you are on the category detail page (for examplecategory/detail.html)categoryDetailtags to retrieveContentfield, you can operate like this:

• Enable Markdown rendering (render=true)If you want to categorize a certain fieldContentregardless of the global settings, you can force it to be rendered in Markdown by addingrender=trueParameter.

  {# 强制启用Markdown渲染，将Markdown内容转换为HTML #}
  <div>分类内容：{% categoryDetail categoryContent with name="Content" render=true %}{{categoryContent|safe}}</div>
  

  This needs to be paid special attention to,{{categoryContent|safe}}of|safeThe filter is crucial.|safeTell the template engine,categoryContentThe content in the variable is safe HTML code that can be output directly without escaping HTML entities. If missing|safeEven if Markdown is rendered into HTML, it may still be displayed as raw HTML code due to further escaping, rather than the expected style.

• Disable Markdown rendering (render=false)On the contrary, if you do not want a categoryContentField to render Markdown, only display raw text (even if the global settings enable Markdown editor), you can addrender=falseParameter.

  {# 强制禁用Markdown渲染，显示原始Markdown文本或纯文本 #}
  <div>分类内容：{% categoryDetail categoryContent with name="Content" render=false %}{{categoryContent|safe}}</div>
  

  In this case,ContentThe variable will contain the original text that has not been processed by the Markdown parser.|safeThe filter is still useful here, especially when your original text may contain some HTML tags and you want these HTML tags to be parsed correctly by the browser. If your goal is to display plain text without any HTML tags, then|safeThe impact may not be so obvious, but for the universality of the code and to avoid accidents, it is usually recommended to retain it.

Why do we need this flexibility?

This flexible control method is very practical in actual operation:

• Content diversity:Some category descriptions may require rich Markdown formatting (such as lists, code blocks, quotes), while others may just be simple plain text introductions.
• Compatibility:If you have migrated content from other systems, it may contain already formatted HTML, or you may have specific HTML code that you do not want to be misinterpreted by the Markdown parser.
• Performance optimization:For fields that are simple and do not contain Markdown syntax, disabling rendering can avoid unnecessary processing overhead (although this overhead is usually negligible).
• Special display requirements:In some cases, you may need to display the Markdown text itself as part of the presentation, rather than its rendered effect, such as displaying Markdown syntax examples in tutorials.

Through the global settings of the background and the template inrenderthe parameters, Anqi CMS has given us control over the category detail pageContentThe dual control of field rendering behavior. Understanding and skillfully using these features will make it easier for you to manage content and display on your website.

Frequently Asked Questions (FAQ)

1. Question: About the product classification detail page of Anqi CMS.ContentField, if the global setting has enabled Markdown rendering, but the template has setrender=falseHow will it be displayed in the end?Answer: The template containsrenderThe parameter priority is higher than the global setting. In this case, although the global setting has enabled Markdown rendering, it is explicitly specified in the template thatrender=false,ContentThe content of the field will not be rendered by the Markdown renderer but will be displayed as raw text.

2. Question: I have set up in the templaterender=trueBut why does the category detail page still display the original Markdown text?Answer: It's likely that you forgot to add it when outputting the variable.|safeFilter. For example, it should be written as{{categoryContent|safe}}instead of{{categoryContent}}.|safeThe filter tells the template engine that the output content is safe HTML, which does not need to be escaped again, so that the browser can correctly parse and render the HTML style.

3. Ask: What categories are on the detail page?ContentWhat Markdown syntax does the field support? Does it support mathematical formulas or flowcharts?Answer: The Anqi CMS built-in Markdown editor supports common Markdown syntax, such as headings, lists, links, images, code blocks, citations, and so on.As for mathematical formulas and flowcharts, according to the system documentation, they need to be rendered on the front end by introducing third-party JavaScript libraries (such as MathJax and Mermaid).This means that even if Markdown is rendered, these special elements still need to be manually added the corresponding JS code in the template to be displayed correctly.