How to safely display HTML content retrieved from a database on the frontend without escaping?

In website operation, we often need to display some content with rich formatting, such as mixed text and images on article detail pages, HTML tables on product introduction pages, or interactive codes embedded in custom pages.This content is usually stored in a database and rendered on the front-end page.However, many content management systems (including the familiar AnQiCMS) by default, for website security, will escape the HTML content retrieved from the database, causing the front-end to display the original HTML code instead of the expected effect.

Today, let's talk about how to safely display the HTML content from these databases on the front end in AnQiCMS, while avoiding unnecessary escaping.

Understand the default behavior and security considerations of AnQiCMS

Firstly, we need to understand why AnQiCMS (and many modern CMS) defaults to escaping HTML content.This is mainly for security reasons, especially to prevent cross-site scripting attacks (XSS).<script>alert('XSS')</script>Such code, and if the system does not escape it directly to the front end, then other users visiting the page may be attacked.AnQiCMS is a Go language CMS that focuses on security, one of its design philosophies is to make "all websites in the world safe", therefore, the default automatic escaping mechanism is an important part of its security protection.

When AnQiCMS's template engine retrieves content from the database and outputs it to the front end, it will<to<,>to>,"to"Entities in HTML, so that the browser will not parse them as HTML tags or execute the script within them, but display them as plain text.

When do you need to display unescaped HTML content?

Of course, not all HTML content is malicious. In many legitimate scenarios, we indeed need to display rich text content stored in databases, such as:

• Rich text editor (WYSIWYG) output content:When editing articles in the background, titles, paragraphs, images, links, and other elements created using the rich text editor are inherently valid HTML structures.
• Complex layout of the product detail page:May contain tables, lists, special styles, etc.
• Custom embedded code for pages:For example, embedding third-party video players, map components, etc.

In this case, we need to explicitly inform the AnQiCMS template engine that this content is "safe" and does not require escaping, and can be parsed directly as HTML.

AnQiCMS solution:|safeFilter

In the AnQiCMS template system, the most commonly used and direct method to display unescaped HTML content is to use|safefilter.

When you output a variable in a template, just add|safe，AnQiCMS will skip the HTML escaping process for this part of the content, and output it directly as HTML code to the browser, thereby achieving the desired effect.

For example, if there is one in our article detail page template,articleContenta variable stores the HTML content of the article, we would usually use it in this way:

<div>
    {%- archiveDetail articleContent with name="Content" %}
    {{ articleContent|safe }}
</div>

Here, archiveDetailThe tag is used to get document details and assign the document content toarticleContent. Then,{{ articleContent|safe }}ensuring that this HTML content can be correctly parsed and rendered by the browser. Whether it is the content of the article'sContentfield, or categorizedContentfield, even single-pageContentfield, can be displayed safely in this way

Additional processing for Markdown content:|renderwith|safecombination

With the popularity of Markdown editors, many operators are accustomed to writing content in Markdown format.AnQiCMS also supports enabling Markdown editor in the background.Markdown itself is a lightweight markup language that needs to be rendered into HTML before it can be displayed as rich text in a browser.

If your database stores content in Markdown format and you want to render it as HTML on the front end, you need to use|renderThe filter converts it to HTML, then, it also needs to use|safea filter to ensure that the converted HTML is not escaped.

For example, if you have a custom fieldintroductionThe text stored is Markdown:

{% archiveDetail introduction with name="introduction" %}
{{ introduction|render|safe }}

Here|renderThe Markdown text will be parsed and generated into HTML, followed by the|safeIt ensures that the generated HTML can be directly parsed by the browser, rather than displayed as plain text.

Greater control:autoescapeTag

Besides using individual variables|safeOutside the filter, AnQiCMS's template engine also providesautoescapetags to control the automatic escaping behavior of a certain block in the template.

You can use{% autoescape off %}and{% autoescape on %}Enclose a piece of code to explicitly turn off or on automatic escaping.

{% autoescape off %}
    {# 在这里的所有变量输出都将默认不被转义 #}
    {{ someHtmlContent }}
    <div>
        {{ anotherHtmlSnippet }}
    </div>
{% autoescape on %}
    {# 再次开启自动转义，恢复默认安全行为 #}
    {{ plainText }}
{% endautoescape %}

However, please be cautious in using it.{% autoescape off %}.It will turn off the automatic escaping feature of the block, if the block contains content from user input or other untrusted sources, it will greatly increase the risk of XSS attacks. Usually, we recommend using|safeThe filter, as it precisely allocates 'unescaped' permissions to each variable, making code easier to review and less prone to errors. It should only be considered when absolutely necessary and when there is absolute confidence in the source of the content.autoescape off.

Summary and **practice**

In AnQiCMS, safely displaying HTML content from the database without being escaped mainly depends on|safethe filter. For Markdown content, you need to|render|safeUse in combination.

• Clarify your intention:Use HTML parsing only when you are sure that the content is valid and needs to be parsed as HTML.|safe.
• Input purification:Though|safeAllow HTML content to be displayed, but frontend rendering is just the final step.The most critical protection should be completed before the content enters the database.Ensure that all user inputs (especially content from rich text editors) are strictly sanitized and validated on the server side, filtering out potential malicious scripts.AnQiCMS includes content security management and sensitive word filtering functions, which are a good first line of defense, but as operators and developers, we also need to be vigilant about the source and security of the content.
• Local control:Use as much as possible|safeThe filter processes specific variables instead of globally closing themautoescapeto minimize safety risks.

By these methods, we can not only take advantage of the powerful functions of AnQiCMS to display a variety of content, but also effectively maintain the security of the website.

---

Frequently Asked Questions (FAQ)

Q1: If I forget to use HTML content|safeWhat will happen to the filter? A1:If I forget to use|safeThe filter, AnQiCMS template engine will default escape HTML tags and special characters retrieved from the database. This means that your users will see the original HTML code on the frontend page, for example<p>这是一个段落</p>It will be displayed as<p>这是一个段落</p>It is not the actual rendered paragraph effect. The page layout may become chaotic, or lose the appropriate style and interaction.

Q2: Use|safeIs my website completely safe after the filter? A2:Not entirely.|safeThe filter just tells AnQiCMS template engine that this content is considered safe and does not need to be escaped.But the actual security of the content depends on its source.|safeThe filter allows these malicious scripts to execute on the front end, leading to XSS attacks.Therefore, ensuring the reliability of the content source and cleaning user input on the server side (filtering out malicious HTML tags and attributes) is the first crucial step.