When using AnQiCMS to build a website and design templates, you may encounter a common problem: when outputting some content in the template, the tags that were originally expected to be displayed as HTML effects are automatically converted to plain text, for example,<p>这是段落</p>变成了&lt;p&gt;这是段落&lt;/p&gt;This makes the content lose its original style and structure. Understanding this problem and knowing how to handle it is very important for template developers.

Why does AnQiCMS template automatically escape HTML tags?

Firstly, it is important to clarify that this automatic escaping is not a system failure, but an important security mechanism designed to prevent cross-site scripting (XSS) attacks. Imagine if the system directly outputs any user input content without distinction, malicious users might insert a segment of code into the text.<script>alert('XSS攻击');</script>代码。Once this code is rendered on the page, it will execute in other visitors' browsers, potentially stealing user information, tampering with page content, and so on.

To avoid such security risks, AnQiCMS (and many other modern template engines, such as Django, etc.) defaults to escaping variable content fetched from the backend database. This means that all special characters that could be parsed as tags by the browser, such as</>/&/"/'，will be converted to the corresponding HTML entities, ensuring they are displayed as plain text rather than executed by the browser.

However, in some scenarios, we indeed need to display content in its original HTML form, such as the content of articles edited in rich text editors, specific ad codes, or HTML fragments that we ourselves have written and confirmed to be safe.This is when you need to tell AnQiCMS template which content is trustworthy and does not require escaping.

How to output content directly: two main methods

AnQiCMS template engine provides two main methods to control the escaping behavior of HTML content, allowing you to directly output the original content according to your actual needs.

Method one: use|safeFilter

This is the most commonly used and most direct method, suitable for when you need to output the original HTML content contained in a single variable. In AnQiCMS templates, you can do this by adding|safeTo implement a filter.

For example, if you have an article content variable obtained from the backgroundarchive.ContentIt includes HTML tags, and you want these tags to be parsed and displayed normally by the browser. You can write it like this: 

<div>
    {{ archive.Content | safe }}
</div>

This is like telling the system, 'I believe this content is safe, please display it directly without any processing.'}]This filter will prevent the system from escaping the content of the variable, so that HTML tags can be rendered correctly.This method is very suitable for displaying articles, product details, and other content entered from a rich text editor.

Method two: use{% autoescape off %}tags

If you have a large code block, or you are sure that all the variables output should be displayed directly as HTML, then use{% autoescape off %}and{% endautoescape %}Wrap this part of the content with tags will be more convenient.

All the content wrapped with these tags, the variables inside will no longer be subject to the default HTML escaping rules. For example:

{% autoescape off %}
    <div>
        <!-- 这里面的所有变量输出，包括 {{ variable1 }} 和 {{ variable2 }} 等，都将直接输出原始HTML -->
        <p>欢迎来到我的网站！</p>
        {{ some_html_content_variable }}
        <p>请点击 <a href="/contact">这里</a> 联系我们。</p>
    </div>
{% endautoescape %}

This method is suitable when you need to embed a large block of known secure and preformatted HTML code, thus avoiding manual addition to each variable|safeFilter.

When and how to safely use these methods

Although|safefilters andautoescape offThe label can solve the problem of escaping HTML content, but be cautious when using them. Once escaping is disabled, you are responsible for validating the safety of the content.

  1. The reliability of the content source：Only use these methods for content sources you completely trust.The most common scenario is the content published by backend administrators through rich text editors, as this content is usually reviewed by humans.
  2. Content review and filteringEven if the content is from an administrator, it is recommended to use content security management and sensitive word filtering functions on the back end to further reduce risks. It is not recommended to use comments or other information submitted by users directly unless it has been strictly sanitized on the server side|safeorautoescape offTo prevent ordinary users from maliciously submitting HTML/JS code.
  3. Processing Markdown content.：If your content is written through the AnQiCMS background Markdown editor, you may find that even if you use|safeEnglish syntax is also not converted to HTML. This is because|safe仅仅是禁用HTML转义，而非执行Markdown到HTML的转换。对于Markdown内容，AnQiCMS提供了renderparameters, such as{{ archive.Content | render | safe }}，先通过renderConvert it from Markdown to HTML, then through|safeEnsure that the converted HTML can be output directly, rather than being escaped again.

You have mastered these methods, and you can flexibly control the display of HTML content in the AnQiCMS template, making your website more rich and dynamic, while also maintaining the security of the website.

Common Questions (FAQ)

1. Is my website safe after disabling HTML escaping?Disabling HTML encoding increases the risk of the website facing XSS (Cross-Site Scripting) attacks. You should only use it for content that you completely trust and confirm does not contain any malicious scripts.|safeFilter or{% autoescape off %}Label.For any content submitted by users that has not been strictly reviewed and purified, it should be avoided to disable escaping.AnQiCMS provides content security management and sensitive word filtering functions that can help you manage content risks to some extent.

2. I have used it in the template.|safeBut the Markdown content is not rendered into HTML. Why is that? |safeThe filter's purpose is to tell the template engine not to escape the HTML special characters in the variables, so that they are displayed in their original HTML form.It itself does not convert Markdown syntax to HTML.renderParameter conversion, for example{{ archive.Content | render | safe }}So, Markdown will be converted to HTML first, and then output safely to the page.

3.|safeand{% autoescape off %}What is the difference between tags, and which one should I use?The main difference lies in the scope of action.|safeThe filter only affects the output of a single variable, for example{{ some_variable | safe }}.{% autoescape off %}Labels apply to all content within the code block they wrap. If you only need to directly output the HTML content of a few variables, use|safeMore precise and recommended. If a large block of template code contains multiple variables, and you are sure that all the HTML content within this code block is safe, then use{% autoescape off %}Labels enclosed in pairs will be more concise. No matter which method is used, it should be fully assessed for the safety risks it brings.