How to force-render Markdown content in a single-page `Content` field as HTML?

When using Anqi CMS to manage website content, the single page (Page) is a very practical feature, which can flexibly create static content such as 'About Us', 'Contact Information', etc.Many friends like to write the content of these pages using Markdown, because it is simple and efficient, and can quickly format the layout.However, sometimes we may find that even if the content is written in Markdown, the frontend of the page still displays as plain text without being rendered by HTML.This is often because the template does not correctly instruct the system to render.

Don't worry, AnQi CMS provides a very simple and powerful way to solve this problem, allowing your Markdown content to be rendered as beautiful HTML.This mainly involves two methods, both of which allow you to flexibly control the display of content.

Understand the Markdown processing mechanism of AnQi CMS

Before we delve into the operation, let's briefly understand how Anqi CMS processes Markdown content.Generally, if you have enabled the Markdown editor in the "Global Settings" -> "Content Settings" on the backend, then the document content created or edited through this editor will be automatically rendered as HTML by default on the frontend.

However, in certain specific scenarios, such as when you close the Markdown editor, or the content is imported from elsewhere, and you want to have more fine-grained control at the template level, you will need to manually force rendering.The AnQi CMS template engine is very flexible, allowing you to explicitly tell the system when retrieving content: 'Please render this Markdown text into HTML!'

Method one: Directly inpageDetailthe tagrenderParameter

When we usepageDetailWhen using the tag to get the content of a single page, this tag itself providesrendera parameter that can directly control the rendering behavior of Markdown content.

pageDetailTags are used to retrieve detailed information about a single page, such as the page title, description, and content. Their basic usage is:

{% pageDetail 变量名称 with name="字段名称" id="1" %}

If we need to retrieve the details of a single page,ContentField, and you want it to be rendered as HTML, you canname="Content"Add an extra one after thatrender=truethe parameter. At the same time, in order to prevent the template engine from escaping the rendered HTML code again (which will cause HTML tags to be displayed as plain text), we also need to use it in conjunction with|safefilter.

For example, suppose we want to display the single page content with ID 1 in the template and ensure that its Markdown is rendered correctly:

{# 假设当前页面是单页面，或者你知道单页的ID，比如ID为1 #}
<div>
    {# 获取单页面内容，并明确指定render=true来强制渲染Markdown为HTML #}
    {% pageDetail pageContent with name="Content" id="1" render=true %}
    {# 使用|safe过滤器确保HTML代码不会被转义，而是直接输出 #}
    {{ pageContent|safe }}
</div>

The logic of this code is clear:

1. {% pageDetail pageContent with name="Content" id="1" render=true %}This line of code will retrieve the content of the single page with ID 1 from the database.ContentField content.render=trueIt plays a key role, indicating the internal processor of Anqie CMS to convert Markdown content into HTML before passing the variable.pageContentVariable before, convert it into HTML.
2. {{ pageContent|safe }}: Due torender=trueAlready converted Markdown to HTML,pageContentThe variable now contains a piece of HTML code. For security reasons, the Anqi CMS template engine automatically escapes HTML tags to prevent cross-site scripting attacks (XSS).|safeThe filter tells the template engine: "This HTML content is safe, please output it directly without escaping the HTML tags."

In this way, your Markdown content can be displayed on the page in HTML form.

Method two: use|renderThe filter is processed twice.

Sometimes, you may have already got the Markdown content into a variable, or this content is a custom field that does not support it directlyrender=trueThe parameter. In this case, you can use|renderThe filter to process the variable later.

|renderFilter is a general-purpose content rendering tool that can render variables containing Markdown text into HTML. It also needs to work with|safeto use the filters together.

Assuming you have a single-page application, there is a custom field calledintroductionIt stores a Markdown-formatted introduction. You can handle it like this:

{# 获取单页面的自定义字段内容，此时pageIntroduction变量中是原始Markdown文本 #}
{% pageDetail pageIntroduction with name="introduction" %}

<div>
    <h3>页面简介 (Markdown渲染为HTML):</h3>
    {# 使用|render过滤器将pageIntroduction变量中的Markdown内容渲染为HTML，再使用|safe过滤器确保HTML被正确显示 #}
    {{ pageIntroduction|render|safe }}
</div>

Here are two steps performed:

1. {% pageDetail pageIntroduction with name="introduction" %}: First, we use thepageDetaillabel to obtain the namedintroductioncustom field content and store it in thepageIntroductionvariable. At this point,pageIntroductionThis is the original Markdown text.
2. {{ pageIntroduction|render|safe }}Then, we considerpageIntroductionvariable application|renderThe filter will convert the Markdown text in the variable to HTML. Then, as before,|safeThe filter ensures that the HTML code is properly parsed and displayed by the browser.

When to choose which method?

• When you access directly fromContentthe field to obtain the main content, it is recommended to usepageDetaillabel'srender=trueParameter.This method is more direct, it completes rendering at the content acquisition stage, and the code is also more concise.
• When content comes from a custom field, or you have assigned content to a variable and need to process it later, use|rendera filter is more suitable.This method provides greater flexibility, allowing for rendering after obtaining the content as needed.

No matter which method you choose, the key is to clearly tell AnQi CMS: 'This is a Markdown, and I want it to be displayed as HTML.'

Cautionary notes and **practice

1. |safeThe filter is indispensable: As mentioned before,|safeThe filter is crucial to prevent HTML tags from being escaped and displayed as plain text. Without it, even if Markdown is rendered as HTML, you might only see<p>Hello World</p>Such a style, not a paragraph like "Hello World".
2. Consideration of security: |safeThe filter, as the name implies, is to inform the system that this content is "safe". This means that if the Markdown content you render is from user input and has not been strictly filtered for security, then it can be used directly.|safeThere may be a risk of XSS (cross-site scripting attack).Although AnQi CMS has its own security mechanisms during backend editing, please be cautious when handling content from unknown sources or highly sensitive user-generated content.
3. Markdown style:Forcing rendering as HTML only solves the problem of converting content from Markdown to HTML. If you want the rendered Markdown content to have a beautiful style like GitHub, you may also need to customize the template's<head>Partially include GitHub Markdown CSS style sheet. For example, you can add in yourbase.htmlfile:

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

   This will make your Markdown content display more professionally on the front end.

By using these simple methods, you can easily manage and display your Markdown single-page content in the Anq CMS, making the website presentation more colorful and varied.

Frequently Asked Questions (FAQ)

Q1: Why does my Markdown content sometimes display as plain text instead of HTML?A1: This is usually because the template does not explicitly indicate that the Aanq CMS should render Markdown text as HTML. If the Markdown editor is not enabled in the background, or if you directly retrieve the content without using itrender=trueParameter (forpageDetailorarchiveDetailtag) or|renderIf a filter is applied, the Markdown source code will be output as is. The solution is to add the correspondingrender=trueor|renderfilter and use it with|safefilter usage.

Q2:|safeWhat is the function of the filter, is it safe?A2: |safeThe filter tells the AnQi CMS template engine that the content before it is safe HTML code and does not require the default HTML escaping. If there is not|safesuch as<p>Such HTML tags may be escaped into<p>which may cause the page to display as plain text. Regarding security, using|safeIt means you trust this HTML content. It is usually safe for Markdown content manually entered by backend administrators.But if the content is from a frontend user submission or an unreliable third-party source, and it has not been strictly reviewed for security, it should not be used directly|safeThe risk of introducing XSS (Cross-Site Scripting) may occur. Therefore, it is necessary to judge according to the source and sensitivity of the content when using it.

Q3: How to make the Markdown content style more beautiful after forced rendering to HTML?A3: It is responsible for rendering Markdown syntax into HTML structure.To make these HTML have better visual effects, you need to introduce CSS styles.A common practice is to introduce a third-party Markdown style library, such as GitHub's Markdown style.You can use your website template (usuallybase.htmlof similar files)<head>Inside the tag, add a link to reference its CDN resource, for example: `<link rel=”stylesheet" href=”https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/5.2.