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 are automatically converted to plain text, for example,<p>这是段落</p>Became&lt;p&gt;这是段落&lt;/p&gt;This has lost the original style and structure of the content. Understanding this issue and knowing how to handle it is very important for template developers.

Why does AnQiCMS template automatically escape HTML tags?

It should be clearly stated 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 were to output any user input without distinction, malicious users might insert a segment<script>alert('XSS攻击');</script>Code. Once this code is rendered on the page, it will execute in the browsers of other visitors, potentially stealing user information, tampering with page content, and so on.

To avoid such security risks, AnQiCMS (and many other modern template engines like Django) defaults to escaping HTML content retrieved from the backend database. This means that all special characters that may be parsed as tags by the browser, such as</>/&/"/'It will be converted to the corresponding HTML entity, ensuring that they are displayed as plain text and not executed by the browser.

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

How to output content directly: two main methods.

AnQiCMS template engine provides two main ways 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 the AnQiCMS template, you can add|safeTo implement a filter.

For example, if you have a variable of article content fetched from the backendarchive.ContentIt contains HTML tags, and if 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, thereby allowing HTML tags to be rendered correctly.This method is very suitable for displaying articles, product details, and other content entered from rich text editors.

Method two: use{% autoescape off %}Tag

If you have a large code block, or you are sure that all variable outputs should be displayed directly as HTML, then use{% autoescape off %}and{% endautoescape %}The tag pair will make it more convenient to wrap this part of the content.

All the content wrapped in this pair of tags 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 safe and preformatted HTML code, thus avoiding manual addition to each variable|safefilter.

When and how to safely use these methods

Though|safeFilters andautoescape offTags can solve the problem of HTML content escaping, but be cautious when using them. Once escaping is disabled, you are responsible for verifying content safety.

  1. Reliability of content sourceUse these methods only 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 manually reviewed.
  2. Content Review and FilteringEven content from administrators should be recommended to use content security management and sensitive word filtering functions on the background to further reduce risks. It is not recommended to use comments or other information submitted by users directly unless it is strictly purified on the server side|safeorautoescape offIn order to prevent normal users from maliciously submitting HTML/JS code.
  3. Processing Markdown content.If you have content written through the AnQiCMS backend Markdown editor, you may find that even if you have used|safe, Markdown syntax has not been converted to HTML. This is because|safemerely disable HTML escaping, not executing Markdown to HTML conversion. For Markdown content, AnQiCMS providesrenderparameters, for example{{ archive.Content | render | safe }}first pass throughrenderConvert 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 ensuring the safety of the website.

Frequently Asked Questions (FAQ)

1. Is my website safe after disabling HTML escaping?Disabling HTML encoding increases the risk of a website facing XSS (cross-site scripting) attacks. You should only use content that you completely trust and confirm does not contain any malicious scripts.|safeOr filter.{% autoescape off %}Label. Any content submitted by users that has not been strictly reviewed and purified should avoid disabling escaping.AnQiCMS provides content security management and sensitive word filtering features that can help you manage content risks to a certain extent.

2. I used it in the template|safeBut why is the Markdown content not rendered as HTML? |safeThe filter's role is to inform the template engine not to escape the special HTML characters in the variables, so that they are displayed in their original HTML form.It itself does not convert Markdown syntax to HTML.If your content is in Markdown format, you need to go through the AnQiCMS providedrenderParameters are converted, for example{{ archive.Content | render | safe }}. So, Markdown will be converted to HTML first, and then safely output 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 acts on the output of a single variable, for example{{ some_variable | safe }}However{% autoescape off %}The tag applies to all the content within the code block. 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 %}Label pairs will make it more concise. No matter which method is used, it should fully assess the security risks it brings.