Why does AnQiCMS template default to escaping HTML code? How to safely output HTML content?

When developing templates with AnQiCMS, we may notice an interesting phenomenon: sometimes, the HTML code directly output in the template, such as a<div>Label, did not get parsed into a visible area by the browser as expected, but was displayed exactly as it is&lt;div&gt;Such characters.This might be confusing, why does AnQiCMS default to escaping HTML code?How can we safely output the HTML content we want?

一、Understand the necessity of default HTML code escaping in AnQiCMS templates

When we find that<p>tag has become&lt;p&gt;When, this is actually AnQiCMS template engine quietly protecting the website security. This default behavior is not a fault, but a well-considered security design, with the core purpose ofPrevent Cross-Site Scripting (XSS).

AnQiCMS as an enterprise-level content management system, has always placed security in a very important position since its design, with its system architecture and development language (Go language) emphasizing high concurrency and security.The document also clearly states that AnQiCMS is committed to providing efficient, customizable, and easily scalable content management solutions, and that the system design focuses on high concurrency, security, and scalability. We have always been moving towards the direction of website security, ensuring that AnQiCMS safeguards your website.This is enough to show the importance of AnQiCMS on website security.

How is HTML code escaping implemented to be secure?

Imagine if the template engine does not process the output content, any content submitted by users (such as article comments, message board information), which contains malicious scripts (such as<script>alert('您好！');</script>or<img src="invalid-image.jpg" onerror="alert('您的账户信息已被窃取！');">）may be directly injected into the page, once other users visit this page, these malicious scripts will execute on their browsers, leading to:

  • steal user information:Malicious scripts may obtain the user's Cookie and then steal the login credentials.
  • Page tampering:Malicious scripts can modify the page content and guide users to perform phishing operations.
  • Distributing malware:By诱骗点击，可能使用户下载并安装恶意软件。

By default, escape HTML special characters, such as:<Converted to&lt;,>Converted to&gt;The template engine effectively prevents the browser from interpreting these characters as executable HTML or JavaScript code.This way, even if malicious code is submitted by the user and stored in the database, it will only be displayed as plain text on the front end, losing its attackiveness.AnQiCMS uses a template engine (similar to the syntax of Django template engine) that also follows this industry-wide security practice.

How to safely output HTML content in AnQiCMS template

Although default escaping is for security, in some cases, we indeed need to output HTML content with a specific structure, such as articles generated by rich text editors, or HTML code snippets customized by administrators.This, AnQiCMS provides the corresponding mechanism to meet our needs, while ensuring it is within a controllable range.

1. Use|safeFilter (the most commonly used and direct method)

|safeThe filter is the most direct and most commonly used method in AnQiCMS templates, it explicitly tells the template engine: This content is safe, please do not perform HTML escaping, parse and output it as raw HTML.

Usage:

When your variable contains HTML code that needs to be parsed, just add it to the end of the variable name|safeas follows:

{# 假设archive.Content变量中存储了HTML格式的文章内容 #}
<div>
    {{ archive.Content|safe }}
</div>

Important reminder and risk:

  • Preconditions for trust: |safeMeans that you as a developer or content manager are fully responsible for the content in this variable.You must ensure that this content is from a reliable source and has been strictly filtered for security, without any malicious code.
  • Not to be misused:Never directly use any content directly from front-end user input without any processing and validation|safeOutput. This will reintroduce the risk of XSS attacks.
  • Applicable scenarios:通常用于后台富文本编辑器生成的内容（因为后台编辑器的内容在保存时通常已经进行了安全过滤）、管理员在后台手动配置的、确认安全的HTML代码片段（如自定义的广告位代码、统计代码等）。此外，当使用Markdown编辑器，并通过renderThe filter converts Markdown to HTML, and the converted HTML content also needs to be matched with|safeto display correctly.

2. Use{% autoescape %}tags (control the escaping behavior of local areas)

{% autoescape %}The label allows you to temporarily enable or disable the HTML auto-escape feature in specific areas of the template.

Usage:

  • Turn off automatic escaping: {% autoescape off %}…{% endautoescape %}The content between them will not be automatically escaped.
  • Enable automatic escaping (default behavior): {% autoescape on %}…{% endautoescape %}The content between them will follow the default automatic escaping rules.
{# 临时关闭自动转义，输出一段管理员提供的HTML片段 #}
{% autoescape off %}
    <div class="custom-ad-slot">
        <script>console.log('这是一个安全的广告脚本');</script>
        <p>欢迎访问我们的网站！</p>
    </div>
{% endautoescape %}

{# 某个区域需要严格的转义，确保安全 #}
{% autoescape on %}
    <p>这个区域的变量内容 {{ user_input }} 会被严格转义。</p>
{% endautoescape %}

Application considerations:

  • autoescapeLabels provide more flexible local control. Usually, we do not recommend turning off automatic escaping throughout the template as it may introduce unnecessary risks.
  • It is mainly used for those specific template files or code blocks that require outputting a large amount of HTML code, and you have ensured that these codes are completely trustworthy. For the output of a single variable,|safeThe filter is usually more convenient.

3. Auxiliary filter:striptagsandremovetags(When the content is unreliable but needs to remove HTML)

When your content source cannot be fully trusted, but you also want to remove the HTML tags to prevent potential malicious code, you can use the following filters:

  • striptags:Remove all HTML tags from the string.
  • removetags:"tag1,tag2":Remove the specified HTML tag from the string.
{# 移除所有HTML标签，只保留纯文本内容 #}
<p>{{ user_comment|striptags }}</p>

{# 移除特定的<script>标签，但保留其他标签 #}
<div>{{ article_excerpt|removetags:"script"|safe }}</div>

These filters are not directly used for "safe HTML outputThey are very useful when handling user submitted content and can serve as a supplement to background security filtering.

III. Summary

AnQiCMS template defaults to escaping HTML code for website security purposes, aiming to effectively prevent XSS attacks.Understanding this mechanism is a basic literacy for AnQiCMS developers or content operators.|safeFilter or{% autoescape off %}Tags. Always be