How to enable or disable Markdown rendering for the `Content` field on the category details page?

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

Understanding the category detail page ofContentfields and Markdown rendering

In AnQi CMS, each category has oneContentField used to store the detailed description or introductory content of the 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.When we use Markdown syntax to edit content in the background, the system needs to 'render' it into standard HTML code to display the styles correctly on the frontend page.

AnQi CMS provides two levels of control methods for managingContentThe Markdown rendering of the field: it is a global setting that determines the default behavior of all content fields; it is also a tag parameter at the template level, which allows us to specify particularContentField is controlled precisely, even if the global settings are different.

Global settings: Control default rendering behavior

Firstly, we can affect the background global settingsContentThe default Markdown rendering behavior of the field. EnterAnQi CMS backend Navigate toGlobal Settingsthen selectContent Settings. In this interface, you will find a name called “Enable Markdown EditorThe option of “”.

• Tick the "Enable Markdown editor":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's content)ContentConvert the field to Markdown to HTML.This means that the content you write using Markdown syntax in the background will be rendered into HTML with the corresponding styles without any additional operation on the frontend.
• Deselect the 'Enable Markdown Editor':If this option is not checked, the system will not render the content field with Markdown by default.At this moment, 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 for the entire site, but sometimes we may need more specific control.

Template level: Precise control of Markdown rendering

The template tags of AnQi CMS provide strong local control capabilities. Even if the global settings have been determined, we can still control the specific template code bycategoryDetailTagsContentField additionrenderParameters, to explicitly specify whether to render Markdown.

when you are on the category detail page (such as)category/detail.html)usingcategoryDetailTag to gainContentfield, you can operate like this:

• Enable Markdown rendering (render=true)If you want to mark a category asContentthe field will always be rendered in Markdown regardless of global settings, you can addrender=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 and can be output directly without HTML entity escaping. 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 certain category toContentField is rendered as Markdown, only the raw text is displayed (even if the global setting has enabled 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 was not parsed by the Markdown renderer.|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 normally by the browser. If your goal is to display plain text without any HTML tags, then|safeThe impact may not be as obvious, but for the universality of the code and to avoid unexpected issues, it is usually recommended to retain.

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 costs (although this cost is usually negligible).
• Specific 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 showing Markdown syntax examples in tutorials.

Through the global settings of the background and the template inrenderparameters, Anqi CMS has given us control over the category detail pageContentDouble control of field rendering behavior. Understanding and making good use of these features will enable you to be more agile in content management and website presentation.

---

Common Questions (FAQ)

1. Question: The details page of Anqi CMS classification.ContentField, if the global setting has enabled Markdown rendering, but the template has setrender=falsehow will it ultimately be displayed?Answer: The template in therenderParameter priority overrides the global settings. In this case, although Markdown rendering is enabled globally, it is overridden by an explicit specification in the template.render=false,ContentThe content of the field will not be processed by the Markdown renderer but will be displayed as raw text.

2. Question: I have set in the template.render=trueBut the content of the category detail page still displays the original Markdown text, why is that?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{{categoryContent}}.|safeThe filter tells the template engine that the output content is safe HTML and does not need to be escaped again, allowing the browser to correctly parse and render the HTML styles.

3. Question: What are the details of the category page?ContentWhich Markdown syntax is supported by the field? Does it support mathematical formulas or flowcharts?Answer: The Markdown editor built into Anqi CMS supports common Markdown syntax, such as headings, lists, links, images, code blocks, quotes, etc.As for mathematical formulas and flowcharts, according to the system documentation, they need to be implemented through the introduction of third-party JavaScript libraries (such as MathJax and Mermaid) to achieve additional rendering on the front-end.This means that even if Markdown is rendered, these special elements still require you to manually add the corresponding JS code in the template to display them correctly.