How to ensure that HTML code is correctly parsed and not escaped when using the `safe` filter to display rich text content?

In AnQi CMS, rich text content usually carries various information such as articles, product descriptions, or page details, which often includes various HTML tags such as bold, italic, images, links, tables, etc.If this HTML code is not parsed correctly and is simply displayed as plain text, then what users see on the front end is a pile of code, not beautiful and structured content. This will obviously severely affect the reading experience and professionalism of the website.

The template engine of Anqi CMS adopts a syntax style similar to Django, and its default behavior, for security reasons, will escape all output variable content. This means that when you enter text in the backend rich text editor,<p>这是一段<b>加粗</b>的文字。</p>When such content is directly output in the template without special processing, the browser may receive<p>这是一段<b>加粗</b>的文字。</p>At this point,pTags andbTags will be escaped as their HTML entities, so they can be displayed directly on the page<p>and<b>Characters, rather than being parsed and presented as bold text style by the browser.This escaping mechanism effectively prevents cross-site scripting (XSS) attacks, and avoids malicious code from being directly injected and executed on the page.

However, for the content we expect to be displayed as rich text by default, this default escaping mechanism becomes an obstacle. To solve this problem, Anqi CMS providessafeFilter.safeThe core function of the filter is to explicitly tell the template engine: "This content is safe, please do not escape it as HTML, and parse and render it directly according to the HTML code within it."

safeThe core function and usage of the filter

UsesafeThe filter is very intuitive, you just need to add it after the variable that needs to be output and contains HTML code|safeYou can. The basic syntax is:{{ 变量名|safe }}.

For example, in the template of AnQi CMS, when you need to display the detailed content of the article, you will usearchiveDetailtag to get the document content fieldContent. At this point, you will getarchiveContentThe variable may contain HTML code edited by the rich text editor. To ensure that this HTML code is correctly parsed, you should use it in this way:

{%- archiveDetail articleContent with name="Content" %}
{{articleContent|safe}}

Similarly, if you need to display the detailed introduction of the category (categoryDetailofContentfield), the content of a single page (pageDetailofContentfield), or the description of a tag (tagDetailofContentfield), it also needs to be applied|safeFilter:

• Category content:

  {%- categoryDetail categoryContent with name="Content" %}
  {{categoryContent|safe}}
  

• Single page content:

  {%- pageDetail pageContent with name="Content" %}
  {{pageContent|safe}}
  

• Label content：

  {%- tagDetail tagContent with name="Content" %}
  {{tagContent|safe}}
  

By such processing, the template engine will no longer perform HTML escaping when outputting these variables. Instead, it will send the original HTML code directly to the browser, which will be responsible for parsing and presenting the expected rich text style.

Safety considerations and practice

AlthoughsafeThe filter solves the display problem of rich text content, but it must be used with caution as it essentially turns off the default security protection of the template engine. This means that if you willsafeThe filter applied to user input content from untrusted sources or not strictly filtered may introduce XSS vulnerabilities.Malicious users may submit rich text content containing JavaScript code and execute these scripts on the page, thereby stealing user information, tampering with page content, and so on.

Therefore, **practice is:**

1. Only applies to trusted content: safeThe filter should only be used when you are sure that the content is safe and harmless, such as rich text content reviewed by backend administrators or generated by the system.
2. Utilize the built-in security mechanisms of the CMS:The AutoCMS itself provides multi-layer security mechanisms, such as sensitive word filtering, content security management, and other functions. When usingsafeBefore the filter, please ensure that the relevant content has passed these built-in security checks.
3. Markdown content processing:If you enable the Markdown editor, Safe CMS will automatically convert Markdown syntax to HTML when saving or outputting content. In this case,safeThe filter is still necessary to ensure that the converted HTML code can be correctly parsed. The document mentions that,archiveDetailtags can even acceptrender=trueParameters to explicitly specify the Markdown to HTML conversion, then cooperate with|safeEnsure rendering.

In short,safeThe filter is an indispensable tool in the Safe CMS for handling rich text content, allowing pages to display beautiful and structured content correctly.But while enjoying its convenience, always keep in mind its safety features and apply them to trusted, disinfected content, which is the key to ensuring the stable operation of the website.

---

Common Questions (FAQ)

1. Q: If I forget to use for rich text content|safeFilter will happen?A: If you forget to use|safeFilter, all HTML tags in rich text content (such as<p>,<b>,<img>etc.) will be escaped by the template engine into HTML entities (such as<p>,<b>,<img>），then it is displayed as plain text on the page. The user will see the original HTML code, not the rendered bold text, images, or formatting effects.

2. Q:|safefilters and{% autoescape off %}What is the difference between tags?A:|safeFilter is forIndividual variablesIt is effective, it will cancel the HTML escaping of the variable content. Usually,{% autoescape off %}is aTemplate tagsit can be used to turn offa template code blockinside, the automatic HTML escaping function of all variables. Normally,|safeUsed to precisely control the output of a specific variable, while{% autoescape off %}it is used for a wide range of known safe template areas. For safety reasons, it is recommended to use as much as possible|safeFilter, to minimize the range of automatic escaping.

3. Q: I inserted JavaScript code into the backend rich text editor, then used|safeFilter, why did this JS code execute on the front-end? Is it safe?A: That's exactly|safethe reason to use the filter carefully. When you use|safeThe filter is telling the template engine that this content is "safe", and no escaping is needed.If the content contains JavaScript code, the template engine will output it directly to the page, and the browser will execute it as part of the page script.This is very insecure because malicious users can exploit this mechanism to perform XSS attacks.neverto|safeThe filter is applied to any content that may contain JavaScript code submitted by or not verified by users, even if it is inserted in the background. It should ensure the reliability of the content source. The rich text editor of an enterprise CMS usually has some filtering mechanism, but as developers and operators, it is important to understand|safeThe risk is crucial.