How to set the Markdown rendering parameters for the `Content` field in the Tag detail content?

In Anqi CMS, tags (Tag) are an important part of content management, not just simple keyword indexes. Many operators may want to provide a detailed introduction or thematic content for each tag, which involves how to elegantly display the tag detail page in theContentField, especially when this content is written in Markdown format.AnQi CMS provides flexible template tags and configuration options, allowing us to accurately control the rendering behavior of Markdown.

Understanding the label detail page'sContentfield

In Anqi CMS, when we talk about labels,Contentfield, usually refers to the detailed description or dedicated content field of the tag.Although when editing tags in the background management interface, you may mainly see basic information such as "Tag Name" and "Tag Description", but the system supports reserving tags or extending through custom fields to store more rich text content that supports Markdown formatting. ThisContentfield, similar to the article detail page'sContentis the core that carries deep information of the label.

Enable the global settings of the Markdown editor

To makeContentThe Markdown syntax in the front-end page is correctly parsed and rendered as HTML, first ensure that the security CMS Markdown editor feature is enabled.This setting is usually located under the "Global Settings" in the background, find the "Content Settings" section.Here, you can choose to turn on or off the Markdown editor.Once globally enabled, the system will default to all supported MarkdownsContentFields are automatically converted.

Invoke the tag in the templateContentfield

In the detail page template of the tag (usuallytag/detail.htmlortag/list.htmlBased on your template design, we can usetagDetailtags to get the details of the current tag, including itsContentfield.

InvokeContentthe basic way to get the field is:

{# 假设我们已经通过tagDetail标签获取了当前标签的内容，并将其赋值给tagContent变量 #}
{% tagDetail tagContent with name="Content" %}
{# 这里需要使用 |safe 过滤器来避免HTML代码被转义，确保浏览器能正确解析渲染 #}
{{tagContent|safe}}

It is important to note that this is the case:|safeA filter that tells the template engine,tagContentThe content in the variable is safe HTML code and does not need to be automatically escaped. If missing|safeEven if Markdown has been successfully converted to HTML, the original HTML tags will be displayed as plain text, rather than rendered effects.

Fine control over Markdown rendering:renderParameter

The strength of Anqi CMS lies in its not only depending on global settings, but also allowing us to have more detailed control at the template level. ForContentThe Markdown rendering of the field,tagDetailTags provide arenderparameter, allowing us to manually specify whether to perform Markdown to HTML conversion without being affected by the global settings.

ThisrenderParameter acceptstrueorfalseTwo boolean values:

1. Force rendering Markdown(render=true)When you are going torenderthe parameter totrueEven if Markdown editor is turned off in the background global content settings,tagDetailthe tag will still force to renderContentThe Markdown syntax in the field is parsed and converted to HTML.This is very useful in certain specific scenarios, for example, you want the content of a specific tag to always be rendered in Markdown, while other content remains in its original text.

   {# 强制将tagContent中的Markdown内容渲染为HTML #}
   {% tagDetail tagContent with name="Content" render=true %}
   {{tagContent|safe}}
   

2. Prevent Markdown rendering (render=false)On the contrary, if you userenderthe parameter tofalse, then even if the Markdown editor is enabled globally,tagDetailTags also prevent Markdown syntax from being converted and output directlyContentThe original Markdown text. This is used when you only want to display the Markdown source code, or intend to customize rendering through a front-end JavaScript library.

   {# 阻止tagContent中的Markdown内容渲染，直接输出原始Markdown文本 #}
   {% tagDetail tagContent with name="Content" render=false %}
   {{tagContent|safe}}
   

   Please note that even if rendering the original Markdown text is blocked, it is usually recommended to use|safeIn case the text contains special HTML entities that need to be output as is.

Additional steps to enhance the reading experience: integrating Markdown style and advanced features.

Just rendering Markdown content into HTML may not be enough. To provide a better user experience, you may also need to apply appropriate styles to the rendered Markdown content.AnQi CMS also considered this point, allowing us to beautify the display effect of Markdown by introducing a third-party CSS library.

For example, you can add GitHub-style Markdown styles to the<head>area (such asbase.html)

<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" />

If you are in the tag'sContentUsed mathematical formulas (LaTeX) or flowcharts (Mermaid), Anqi CMS also supports displaying them normally by introducing the corresponding JavaScript libraries. These configurations are usually alsobase.htmlthe file<head>or<body>Before tag closes:

"`html {# Mathematical formula support, introduces MathJax #} <script id="MathJax-script" async src=""}https://cdn.jsdelivr.net/npm/mathjax@3/es5/