In the display of the `Content` field of the article, how can I manually control the rendering conversion from Markdown to HTML?

When managing website content in AnQi CMS, we often use Markdown's concise and efficient features to write articles.However, ensuring that this Markdown-formatted content is rendered correctly and beautifully on the front-end page can sometimes be a focus for operators.ContentMarkdown content of the field, and how to manually control this rendering transformation process in the template.

How does AnQiCMS handle Markdown content?

A security CMS handles articlesContentWhen processing fields, it provides an intelligent Markdown to HTML conversion mechanism. This mechanism's default behavior is consistent with the settings you have in the background全局设置-u003e内容设置Is closely related to whether Markdown editor is enabled.

1. When Markdown editor is enabledIf you choose to use the Markdown editor on the background article editing page, the system will usually default to automatically converting the Markdown content to HTML when you save the article, and directly output the converted HTML when it is displayed on the front end.This means that as long as you use the Markdown editor, the content will be automatically rendered in most cases.

2. When Markdown editor is not enabledIf the Markdown editor is disabled, or if you directly input plain text or raw HTML, the system will not automatically handleContentField performs Markdown to HTML conversion and directly outputs the original content.

Manual control of Markdown rendering:renderParameter

Even though there are global settings to control the default rendering behavior of Markdown content, but in actual content display, we may need more fine-grained control.For example, sometimes we want certain content to be rendered even if the global setting has disabled the Markdown editor; or conversely, even if the editor is enabled, certain content should be displayed in raw Markdown format.

At this time, Anqi CMS provides a very practicalrenderparameter, which can manually control the rendering behavior of Markdown in template tags. Thisrenderparameter is applicable for calling articlesContentIncluding multiple template tags of the fieldarchiveDetail/pageDetail/categoryDetailandtagDetailetc.

renderParameter acceptstrueorfalsetwo values:

• render=true: Enforces the transformation ofContentThe content of the field is converted from Markdown to HTML. Regardless of the status of the Markdown editor in the background, as long as the template specifiesrender=trueThis field's content will be rendered as HTML.
• render=falsePrevent on.ContentThe content of the field is converted from Markdown to HTML. Even if the Markdown editor is enabled in the background, as long as it is specified in the templaterender=falseThis field's content will be output in its original Markdown text (or any other original format) without HTML rendering.

The following is usedarchiveDetailTag calls articleContentField, and utilizerenderAn example of manually controlling the parameters:

{# 示例1：强制开启Markdown渲染 #}
<div>
    <h3>渲染后的文章内容：</h3>
    {% archiveDetail articleContent with name="Content" render=true %}{{articleContent|safe}}
</div>

{# 示例2：强制关闭Markdown渲染，显示原始Markdown文本 #}
<div>
    <h3>原始Markdown内容：</h3>
    {% archiveDetail rawContent with name="Content" render=false %}{{rawContent|safe}}
</div>

It should be noted that, regardless of whether you choose to turn on or off the rendering, in the outputarticleContentorrawContentwhen using variables, they should be used in conjunction|safeFilter.This is to inform the template engine that the output content is safe HTML, which does not require additional escaping processing to ensure that it is displayed correctly and not treated as plain text by the browser.|safeEven if Markdown is rendered into HTML, the browser may display it as HTML tag code rather than actual web elements.

Why do you need manual control?

Manually control the rendering of Markdown content, bringing greater flexibility to website operations:

1. Display the original Markdown code: For some technical tutorials or blogs, it may be necessary to demonstrate the Markdown syntax itself as an example to the readers, at this timerender=falseIt is particularly important, as it can prevent the content from being automatically converted and losing its teaching significance.
2. Optimize page loading or avoid unnecessary processingIf:ContentThe field stores plain text or formatted HTML, forcing Markdown rendering would unnecessarily increase the server load. Throughrender=falseCan be directly output to enhance efficiency.
3. Ensure specific content is rendered as expected.When you want a specific article content to maintain consistent rendering status regardless of the global settings of the background Markdown editor,renderParameters provide a reliable coverage mechanism to ensure the stability of the page display effect.

Points to note

While usingrenderParameters for Markdown rendering control, in addition to the aforementioned.|safeOutside of the filter, there is also something worth your attention: AnQi CMS mainly handles basic grammar for Markdown rendering.If your Markdown content includes advanced elements such as mathematical formulas (MathJax) or flowcharts (Mermaid), this usually requires the use of frontend JavaScript libraries for client-side rendering.帮助文档-u003e安企CMS如何在网页正确使用Markdown以及显示数学公式和流程图Find more detailed configuration methods, these client rendering are independent ofrenderbeyond the control range of the parameters.

Summary

By flexible applicationrenderParameters and the global settings of the Markdown editor on the backend, we can precisely control the display of different content requirementsContentThe Markdown rendering method of the field. This not only enhances the flexibility of content management, but also helps us better optimize the presentation effect and user experience of the website content.

Frequently Asked Questions (FAQ)

1. Why did I setrender=trueBut the Markdown content is still not displayed as HTML?This is likely because you forgot to use the output variable when|safefilter.|safeThe filter informs the template engine that the current output HTML content is safe and does not require escaping processing.If it is missing, even if Markdown has been rendered into HTML internally by the CMS, the template engine may still output it as plain text, resulting in the original HTML tags being displayed on the page instead of the actual web elements.

2. Why do I need to write in the template when I have already enabled the Markdown editor in the backgroundrender=true?The background Markdown editor settings control whether the default Markdown to HTML conversion is performed when the article is saved. And the template inrender=trueThe parameter is the rendering behavior of this field in the content display layerForced control. Usually when you want a specific content to be rendered in HTML format regardless of the background global settings (for example, even if the administrator accidentally turns off the Markdown editor), you should userender=trueEnsure consistency and expected effects display.

3. renderDoes the parameter apply to all?ContentField call?According to the documentation of Anqi CMS,renderParameters are mainly applicable to various detail tags of the content subject (Content) such asarchiveDetail(Article Details),pageDetail(Single Page Details),categoryDetail(Category content details) andtagDetail(Tag content details). These tags are used in callingname="Content"When a fieldrenderParameters can be used to control the Markdown to HTML rendering transformation.