This tutorial aims to solve the problem of HTML content in Django templates being automatically escaped, causing HTML tags to be displayed as plain text rather than actually rendered. This article will explain Django's automatic escaping mechanism, and demonstrate in detail how to safely and effectively render dynamically generated HTML content onto the page by using the |safe filter in the template, ensuring that the user interface displays as expected.

1. Problem phenomenon and background

When developing web applications, we often need to display rich text content (such as Markdown-converted HTML) dynamically generated or obtained from a database on the page. However, when these content containing HTML tags are passed to the Django template and rendered directly, we may encounter a common problem: HTML tags (such as

,

, ) are not parsed and rendered by the browser, but are displayed directly on the page as plain text.

For example, when the following rendering effect is expected:

 CSS
===

CSS is a language that can be used to add style to an [HTML](/wiki/HTML) page.

The actual page may directly display its original HTML string:

 <h1>CSS</h1> <p>CSS is a language that can be used to add style to an <a href="/wiki/HTML">HTML</a> page.</p>

The root cause of this phenomenon is that for security reasons, the Django template system will HTML escape all variable contents output through the {{ variable }} syntax by default. This means that all , ', " and & characters will be converted into corresponding HTML entities (for example,

Consider the following typical Django view and template code structure, which attempts to convert Markdown content to HTML and display it:

views.py snippet:

 import markdown
from.importutil
from django.shortcuts import render

def entry(request, name):
    entry_content_md = util.get_entry(name) # Get Markdown format content if entry_content_md is not None:
        # Convert Markdown to HTML
        converted_html = markdown.markdown(entry_content_md)
        context = {
            'entry': converted_html, # Pass HTML content to the template 'name': name
        }
        return render(request, 'encyclopedia/entry.html', context)
    else:
        return render(request, "encyclopedia/404.html")

# Auxiliary function in util.py, used to read the content of Markdown files # def get_entry(title):
# try:
# f = default_storage.open(f"entries/{title}.md")
# return f.read().decode("utf-8")
# except FileNotFoundError:
# return None

entry.html fragment:

 {% block body %}
<div class="entry-container">
    <div class="left">
        {{ entry }} {# Variables are output directly here#}
    </div>
    <div class="right">
        <a href="%7B%%20url%20'edit'%20%%7D" class="edit-btn">
            <button class="edit">EDIT</button>
        </a>
    </div>
</div>
{% endblock %}

In the above code, views.py successfully converts Markdown to HTML and assigns the HTML string to the entry variable in the template context. However, in entry.html, the default behavior of {{ entry }} causes the HTML tag to be escaped and ultimately displayed as text.

2. Django’s automatic escaping mechanism and its security

Django's automatic HTML escaping is a vital security feature designed to protect web applications from XSS attacks. XSS attacks allow attackers to execute malicious scripts in the victim's browser, steal user data, hijack sessions, or tamper with page content. Django greatly reduces this risk by escaping all output by default.

However, this default behavior is "too safe" when our intention is to render legal, expected HTML content. In this case, we need a way to explicitly tell Django: "This content is safe HTML, please do not escape it and render it directly."

3. Solution: Use |safe filter

Django provides a template filter called safe to solve the above problem. When a variable is processed by the |safe filter, Django marks it as "safe" HTML, skipping the automatic HTML escaping process of its content and outputting it directly to the page as raw HTML.

To apply the safe filter, just add |safe after the template variable:

Modified entry.html fragment:

 {% block body %}
<div class="entry-container">
    <div class="left">
        {{ entry | safe }} {# Key change: Added | safe filter#}
    </div>
    <div class="right">
        <a href="%7B%%20url%20'edit'%20%%7D" class="edit-btn">
            <button class="edit">EDIT</button>
        </a>
    </div>
</div>
{% endblock %}

With this simple change, when the entry variable contains HTML content generated by the markdown.markdown() function, these HTML tags will no longer be escaped, but will be correctly parsed and rendered by the browser, thereby achieving the expected display effect.

4. Precautions and Best Practices

Although the |safe filter can solve HTML content display problems, it must be used with extreme caution because it can bypass Django's security protection mechanisms. Improper use of |safe is a common reason for introducing XSS vulnerabilities.

• Only use |safe for trusted HTML content: Use |safe only if you are sure that the HTML content contained in the variable is completely safe and harmless. This means that this HTML content must come from reliable, controlled sources, such as:

  • Generated from your own code, and you have ensured that it does not contain any malicious scripts.
  • It is read from the database and has been strictly sanitized before storage.
  • Generated by a safe third-party library (such as a Markdown parser), and you trust the library's output.

• Never use |safe directly with user input: If your website allows users to submit content containing HTML tags (e.g. comments, forum posts), and you use these unsanitized user input directly with |safe, then your website is extremely vulnerable to XSS attacks. A malicious user can submit content containing <script> tags or other attack code that will be executed in other users&#39; browsers.</script>

• Content Sanitization: If you need to display user-submitted content that may contain HTML, it is highly recommended to strictly sanitize it before storing it in the database or using |safe in the template. Content sanitization refers to removing or escaping all potentially malicious HTML tags and attributes, leaving only a safe subset of HTML. Commonly used Python libraries such as Bleach can help you do this.

  Example: Using Bleach to sanitize user input

   import bleach
  
  def process_user_content(raw_content):
      # Allowed HTML tags and attributes allowed_tags = ['p', 'a', 'strong', 'em', 'ul', 'ol', 'li', 'h1', 'h2']
      allowed_attrs = {'a': ['href', 'title']}
  
      # Clean the content, remove disallowed tags and attributes cleaned_html = bleach.clean(
          raw_content,
          tags=allowed_tags,
          attributes=allowed_attrs,
          strip=True # Remove disallowed tag content)
      return cleaned_html
  
  # In the view:
  # user_input_html = request.POST.get('description')
  # safe_html_for_db = process_user_content(user_input_html)
  # context = {'user_generated_content': safe_html_for_db}
  # return render(request, 'my_template.html', context)
  # In template: {{ user_generated_content | safe }}

5. Summary

The |safe filter is a powerful and necessary tool in the Django template system, which allows developers to bypass the default HTML escaping mechanism and directly render HTML content when needed. However, its use comes with important safety responsibilities. Developers must always remember that |safe should only be used if the content comes from a reliable source and has been verified to be safe. Any HTML content that may contain user input or other untrusted sources must be rigorously sanitized to ensure the security of the application and prevent potential XSS attacks. Correctly understanding and applying |safe filters is a key part of building robust and secure Django applications.

The above is the detailed content of Solution to displaying HTML tags as text in Django templates: |Detailed explanation of safe filter. For more information, please follow other related articles on the PHP Chinese website!