What is the specific usage of the `render` filter in Markdown content rendering?

In Anqi CMS, we often encounter the need to convert text into colorful web elements.Especially when the content is written in Markdown format, how to ensure that it can be presented correctly and beautifully to the user is a question that requires an in-depth understanding.Today, let's chatrenderHow does the filter work in the Anqi CMS Markdown content rendering.

AnQi CMS is favored for its flexible content model and support for diverse content display.It not only includes a powerful Markdown editor that allows content creators to write rich text in a concise and efficient manner, but also provides fine-grained control to handle these Markdown contents, ensuring that the final web output meets expectations.renderThe filter is the key link in this control mechanism.

In short,renderThe core function of the filter is to convert the original Markdown text content into HTML format that can be directly parsed and displayed by the browser.Imagine, you write an article with titles, lists, and code blocks using Markdown, and if it is not rendered, the user will only see a pile of plain text with special symbols. AndrenderThe filter acts like an interpreter, translating Markdown syntax into HTML that browsers can understand, so that content is displayed in the appropriate style on the page.

Why do we need thisrenderWhere is the filter? In the background content settings of AnQi CMS, there is usually an option for 'Enable Markdown Editor'.When this option is activated, the system outputs articles, products, and other core content.ContentWhen this field is used, it will default to automatically converting Markdown to HTML. This is very convenient for most standard content.

However, in certain situations, we may need to have more flexible control over the rendering process of Markdown. For example:

• Handle custom content model Markdown fields:In addition to the main content of the article, we may add some additional fields in the custom content model that also need to support Markdown syntax, such as the product's "detailed features" or the page's "service description". The content of these custom fields is usually not rendered by the system by default, at this point you need to manually userenderA filter to trigger the transformation.
• Fine control of rendering timing:Sometimes we may want to render Markdown content only under certain conditions, or to preprocess the content before rendering.renderThe filter allows us to explicitly specify when to render in the template logic.
• Avoid unnecessary rendering or forced rendering:Even if the global Markdown editor is enabled, we may sometimes need to explicitly specify whether aContentfield should be rendered as Markdown. For example, byarchiveDetailWhen getting the content of an article, you can use its built-inrenderthe parameters.

renderHow to use the filter

In AnQi CMS template syntax,renderThe filter can be applied very intuitively to any variable containing Markdown text. Its basic syntax is:{{ 变量名|render }}.

For example, suppose you have defined a custom field namedintroductionin the article content model and you want it to support Markdown. When you go througharchiveDetailAfter getting the value of this field, it can be used like thisrenderFilter:

{% archiveDetail introduction with name="introduction" %}
{{ introduction|render|safe }}

Pay special attention here|safeThis filter. In the Django template engine syntax, to prevent cross-site scripting (XSS) attacks, all HTML tags and special characters output through variables are automatically escaped.This means, ifrenderThe filter converts Markdown to HTML and outputs it directly, escaping HTML tags into plain text, which results in lost styles. Therefore, we must followrenderafter the filter uses|safeThis content is explicitly told to the system that it is safe HTML, does not need to be escaped, so that the browser can correctly parse and display the Markdown rendering effect.

In addition to directly usingrenderAs an independent filter, Anqi CMS provides built-in parameters to control rendering behavior when retrievingContentsuch core content fields,renderfor example, inarchiveDetail/categoryDetail/pageDetailandtagDetailIn these tags, you can directly specifyContentwhen you get the fieldrender=trueorrender=false:

{# 强制将当前文档内容渲染为HTML，即使后台Markdown编辑器关闭 #}
<div>文档内容：{% archiveDetail archiveContent with name="Content" render=true %}{{archiveContent|safe}}</div>

{# 不对当前文档内容进行Markdown渲染，即使后台Markdown编辑器开启 #}
<div>原始Markdown内容：{% archiveDetail archiveContent with name="Content" render=false %}{{archiveContent|safe}}</div>

Hererender=trueIt means enforced Markdown rendering,render=falseThis parameter indicates that rendering should not be performed. This parameter has a higher priority than the global setting of the background "Enable Markdown Editor", providing you with more detailed control rights.

Reasonably utilizerenderThe filter and its related parameters allow you to easily handle Markdown content in AnQi CMS, whether it's standard articles, custom fields, or conditional rendering based on specific requirements, ensuring that your website content is presented to visitors in the most elegant and accurate way, thereby providing an excellent reading experience.

Frequently Asked Questions (FAQ)

1. When should it be usedrenderFilter, rather than depending on the Markdown editor settings on the backend?Generally speaking, if your content is published in articles, products, and other standard content models,ContentFields, and you want it to be automatically rendered, just enable the background Markdown editor settings directly.renderThe filter is mainly used in the following scenarios:

   • You have added additional fields that need to support Markdown in your custom content model.
   • You need to retrieve the original Markdown text and then decide whether to render it in the template based on specific logic.
   • You want to force render the Markdown of a specific content when the global Markdown editor settings are turned off.
   • You need to preprocess or post-process Markdown content on the front end before rendering.

2. Why are you usingrenderAfter the filter, the content is still not displayed correctly as HTML?The most common reason is that you forget torenderafter the filter|safefilter. Anqi CMS for security, the default is to escape the HTML content output by variables.|safeThe filter tells the system that you trust this HTML content is safe, does not need to be escaped, so the browser can parse and display it correctly. Make sure your code looks like this{{ 变量|render|safe }}.

3. I can use it in the custom content model fieldrenderfilter?Absolutely. It isrenderThe most common application scenario for filters. When you create a text field in a custom content model and want users to enter Markdown in that field, and then render these Markdowns as HTML on the front end, you just need to get the variable of the custom field and then apply{{ 变量名|render|safe }}you can achieve it.