In website content management, especially when content includes rich formatting or comes from user input, how to safely output HTML tags is a crucial issue.The AnQiCMS (AnQiCMS) has fully considered this from the beginning of its design, and its template engine defaults to escaping output variables to effectively prevent security risks such as cross-site scripting attacks (XSS).
Understanding the default behavior of template engines
The template engine of Anqi CMS borrows the syntax from mainstream frameworks like Django, one of its core concepts being "security first." This means that when you directly use{{ 变量 }}When outputting content, all characters that can be interpreted as HTML tags by the browser (such as</>/&/"/') will be automatically converted to the corresponding entity characters (such as</>/&）。This automatic escaping mechanism is a powerful security shield that can prevent malicious users from attacking your website visitors by injecting malicious scripts into the content.
However, in the actual content operation, we inevitably encounter situations where it is necessary to display the real HTML content.For example, the main content of the article is usually edited through a rich text editor, which may contain paragraphs, images, links, and other HTML structures; or in some custom fields, we hope to embed specific styles or HTML code for widgets.In this case, if the content is escaped by default, then the user will see the original HTML code, rather than the rendering effect we expect.
When is it necessary to avoid escaping?
In the following common scenarios, we may need to explicitly indicate to the template engine that HTML tags should not be escaped:
- Content generated by rich text editors:Website articles, product descriptions, single page content, etc., these contents are usually created through the rich text editor (such as the one provided by AnQiCMS) on the backend, and they inherently contain HTML structure.
- Markdown 渲染后的内容：EnglishIf the backend has enabled the Markdown editor and the content is stored in Markdown format, the system will convert it to HTML when rendering.To ensure that these HTML elements display correctly, it is necessary to avoid escaping.
- 少量安全且受控的HTML片段：EnglishIn some cases, you may need to directly output a short segment of HTML code in the template, such as specific ad code, social sharing button code, or complex layout structures, and you are confident that these codes are safe.
Important reminder:Only when you fully trust the source of the content and are sure that it does not contain any malicious code, should you consider avoiding escaping.Direct non-escaped output of untrusted input can pose serious security risks to the website.
The solution in AnQiCMS:safefilters andautoescapetags
AnQiCMS provides two main ways to control the escaping behavior of HTML tags:
1. Use|safeFilter
This is the most commonly used, most direct method, suitable for non-escaped output of a single variable. When you are sure that the content of a variable is safe HTML and you want the browser to render it, you can add it to the variable name after|safeFilter.
For example, on the article detail page, we usually displayarchive.ContentIf the content comes from a rich text editor, it is likely to contain HTML. At this point, we can output it like this:
<div>
{%- archiveDetail articleContent with name="Content" %}
{{ articleContent|safe }}
</div>
Here{{ articleContent|safe }}Explicitly tell the template engine,articleContentThe content in the variable is “safe”, no need for HTML escaping, output directly in HTML format.
For fields that may contain HTML, such as category descriptions and single-page content, this also applies:
{# 输出分类描述，假设其中可能包含HTML #}
<div>分类描述：{% categoryDetail categoryDescription with name="Description" %}{{categoryDescription|safe}}</div>
{# 输出单页内容，如果启用了Markdown渲染且需要避免转义 #}
<div>单页内容：{% pageDetail pageContent with name="Content" render=true %}{{pageContent|safe}}</div>
Please note,render=true参数仅指示系统对Markdown内容进行HTML转换，但转换后的HTML是否被转义，最终仍由English决定。|safe过滤器决定。
2. Use{% autoescape off/on %}tags
autoescapeTags allow you to control the escape behavior of all variables within a template code block. This is very convenient when there are a large number of variables that need non-escaped output in a specific area.
{% autoescape off %}：Within this tag block, all variables are not escaped by default.{% autoescape on %}：Within this tag block, all variables are escaped by default (the same as the default behavior).
For example, if you have an area that needs to display multiple custom HTML snippets, and all these snippets have been strictly reviewed:
{% autoescape off %}
<div class="custom-html-block">
{# 这里的 {{ variable_a }} 和 {{ variable_b }} 都不会被转义 #}
{{ variable_a }}
<p>这是一个不需要转义的文本。</p>
{{ variable_b }}
</div>
{% endautoescape %}
autoescapeThe tags have the following priority rules:
- In
autoescape offWithin the block,{{ 变量 }}The default does not escape. - Even if
autoescape offwithin a block,{{ 变量|escape }}you can still use - In
autoescape onto force a specific variable to be escaped, unless you explicitly use{{ 变量|safe }}Declare it as safe content.
Practical suggestions in content management
- Define the purpose of the field:Add or edit the content model field in the background and make it clear whether the field allows HTML content. If allowed, prepare to use it in the template output
|safe. - Default to secure, allow as needed:Always treat content escaping as the default safety mechanism. Only use it when the rendering effect does not meet expectations and you have carefully reviewed content safety.
|safeorautoescape off. - Treat third-party content with caution:Any HTML content coming from external sources or direct user input should be strictly disinfected and filtered, even if it has been used
|safeAlso, be vigilant. The sensitive word filtering and anti-crawling security mechanisms provided by the Anqi CMS can be used as an auxiliary, but the control of output at the template level is still the key thing you need to master.
Through reasonable use|safefilters andautoescapeTags, you can flexibly control the output of HTML tags in the AQS CMS, ensuring the richness of website content while maintaining the maximum level of website security.
Common Questions (FAQ)
1. Why does my article content, which is obviously in HTML format, show the raw tags after publishing, such as<p>or<strong>?
This is because the template engine of Anqi CMS defaults to escaping all output variables to prevent XSS attacks.When you see the original HTML tags, it means that the template engine has escaped them as plain text.|safefilters, such as{{ archive.Content }}Change to{{ archive.Content|safe }}.
2.|safefilters and{% autoescape off %}What is the difference between tags, and how should I choose?
They are all used to avoid HTML escaping, but with different scopes.|safeFilters act on a single variable, when you output{{ variable|safe }}at this time, only thisvariablecontent will not be escaped. But{% autoescape off %}Tags are applied to a code block, and all variables output within the tag pair are not escaped by default. If you only need to unescape one or two variables, use|safeMore precise; if you have a large number of variables that need to be output without escaping in a certain template area, useautoescape offThis can avoid adding duplicates|safeHowever, please ensure that all content within the area is safe.
3. I am usingContentfields, and found that Markdown rendering did not work, or the rendered HTML was still escaped, why is that?
Markdown rendering whether effective, usually depends on whether the Markdown editor is enabled on the backend. If Markdown is enabled,archiveDetailtags in obtainingContentField when, will contain arenderparameters (such as)render=true），indicating the system will convert Markdown to HTML.However, even though the content is successfully converted to HTML, the template engine will still default to escaping when outputting.ContentVariable also apply|safeFilter, for example{{ articleContent|safe }}, so that the converted HTML can be displayed normally.