When using the AanQi CMS to manage website content, the Single Page (Page) is a very practical feature, which can flexibly create static content such as 'About Us' and 'Contact Information'.Many friends like to use Markdown to write the content of these pages, because it is simple and efficient, and can quickly format.However, sometimes we may find that even though 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 diving into the operation, let's first get a brief understanding of how the Aanqi CMS handles Markdown content.通常，if you have enabled the Markdown editor in the 'Global Settings' -> 'Content Settings' on the backend, 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 wish to have more refined control at the template level, you need to manually force rendering.The template engine of AnQi CMS is very flexible, it allows you to clearly tell the system when fetching content: 'Please render this Markdown text into HTML!'
Method one: directly inpageDetailtags to specifyrenderparameters
when we usepageDetailLabel to get single-page content, this tag itself providesrenderparameter, which can directly control the rendering behavior of Markdown content.
pageDetailTags are used to obtain detailed information about a single page, such as the title, description, content, etc. Its basic usage is:
{% pageDetail 变量名称 with name="字段名称" id="1" %}
If we need to obtain information about a single page,Contentfield, and you hope it to be rendered as HTML, you canname="Content"Add an extra one after,render=trueThe parameter. In order to avoid the template engine from escaping the already rendered HTML code again (which would cause HTML tags to be displayed as plain text), we also need to use it in conjunction with|safeFilter.
For example, let's say 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:
{% pageDetail pageContent with name="Content" id="1" render=true %}This line of code will retrieve a single page with ID 1 from the database.ContentField content.render=trueIt plays a crucial role here, indicating to the internal processor of the security CMS that it should convert the Markdown content to HTML before passing it to the variable.pageContentBefore the variable, it should be converted to HTML.{{ pageContent|safe }}Due torender=trueThe Markdown has been converted to HTML,pageContentThe variable now contains a block of HTML code.The template engine of Anqi CMS automatically escapes HTML tags for security reasons to prevent cross-site scripting (XSS) attacks.|safeFilter tells the template engine: "This HTML content is safe, please output it directly without escaping HTML tags."
This way, your Markdown content can be displayed on the page in HTML format.
Method two: use|renderfilter for secondary processing
Sometimes, you may have already obtained the Markdown content into a variable, or this content is some custom field that does not support it directlyrender=trueParameter. In this case, you can use|rendera filter to post-process this variable.
|renderThe filter is a general content rendering tool that can render variables containing Markdown text into HTML. It also needs to be used together with|safethe filter.
Assuming you have a single page, with a custom field namedintroductionIt contains a brief introduction in Markdown format. 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 operations performed:
{% pageDetail pageIntroduction with name="introduction" %}Firstly, we obtained the custom field content namedpageDetailby using the tagintroductionand stored it in the variable.pageIntroductionAt this point,pageIntroductionThis is the original Markdown text.{{ pageIntroduction|render|safe }}Then, we applypageIntroductionvariable|renderFilter. This filter will convert Markdown text in variables to HTML. Then, as before,|safeThe filter ensures that this HTML code is normally parsed and displayed by the browser.
When to choose which method?
- When you directly from
Contentthe field to get the main content, it is recommended to usepageDetailthe tag'srender=trueparameter.This method is more direct, completing rendering during the content acquisition phase, and the code is also more concise. - When content comes from a custom field, or you have assigned content to a variable that requires further processing, use
|rendera filter is more suitable.This method provides greater flexibility, allowing for rendering at any time after content is retrieved.
No matter which method you choose, the key is to clearly tell the CMS: 'This is a Markdown, and I want it to be displayed as HTML.'
Cautionary notes and **practice
|safeThe filter is indispensable:As mentioned earlier,|safeThe filter is used to prevent HTML tags from being escaped and displayed as plain text. Without it, even if Markdown is rendered into HTML, you might only see<p>Hello World</p>Such text, rather than the paragraph of 'Hello World'.- Security considerations:
|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 should not be used directly.|safeThere may be a risk of XSS (cross-site scripting attack).Although the Anqi CMS has its own security mechanism during back-end editing, please be cautious when dealing with content from unknown sources or highly sensitive user-generated content. - Markdown style:Rendering as HTML only solves the conversion problem from Markdown to HTML. If you want the rendered Markdown content to have a beautiful style like GitHub, you may also need to add styling in the template.
<head>Partially introduce GitHub Markdown CSS stylesheet. For example, you can add:base.htmlto your file:
So, your Markdown content will display more professionally on the front end.<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" />
Through these simple methods, you can easily manage and display your Markdown single-page content in the Anqi CMS, making the website presentation more colorful and rich.
Common Questions (FAQ)
Q1: Why does my Markdown content sometimes display as plain text instead of HTML?A1: This is usually because the template did not explicitly indicate that the CMS should render Markdown text as HTML. If the Markdown editor is not enabled in the background, or if you directly obtained the content without using itrender=trueParameter (for)pageDetailorarchiveDetaillabel) or|renderfilter, the Markdown source code will be output as is. The solution is to add the correspondingrender=trueparameter or|renderfilter, and work with|safeFilter usage.
Q2:|safeWhat is the role of the filter, is it safe?A2:|safeThe filter tells the security CMS template engine that the content before it is safe HTML code and does not need to be escaped by default. If not|safelike<p>Such HTML tags may be escaped.<p>This may cause the page to display as plain text.
Regarding security, using|safeIt means you trust this HTML content.For Markdown content manually entered by the backend administrator, it is usually safe.|safeThere is a risk of XSS (Cross-Site Scripting) attacks. Therefore, when using it, one needs to judge based on the source and sensitivity of the content.
Q3: How to make Markdown content more stylish after rendering it into HTML?A3: The forced rendering is responsible for converting Markdown syntax to HTML structure.To make these HTML elements have better visual effects, you need to introduce CSS styles.An common practice is to introduce a third-party Markdown style library, such as GitHub's Markdown style.base.htmlor similar files)<head>Label within, add a link to reference its CDN resource, for example:
`