问题描述
在使用Django开发Web应用时，经常需要将用户输入的Markdown文本渲染为HTML内容。常见的做法是使用Python的Markdown库（如markdown）将Markdown文本转换为HTML字符串，然后在Django模板中输出这个字符串。然而，很多开发者会遇到一个问题：生成的HTML标签（如<p>、<h1>等）在模板中显示为纯文本，而不是被浏览器解析为HTML元素。这是因为Django模板引擎默认会对输出的变量进行HTML转义，将<转义为<，导致浏览器将标签内容当作普通文本显示。
例如，在视图函数中：
import markdown
def article_detail(request, article_id):
article = Article.objects.get(id=article_id)
# 将Markdown内容转为HTML
html_content = markdown.markdown(article.content, extensions=['extra'])
return render(request, 'article_detail.html', {'html_content': html_content})在模板article_detail.html中：
<div>
{{ html_content }}
</div>页面显示的结果不是带格式的HTML，而是类似<p>这是一段文本</p>的原始字符串。这是因为Django的模板变量默认会被自动转义。
原因分析
Django模板引擎为了安全起见，默认对所有变量输出进行HTML转义，防止跨站脚本攻击（XSS）。当变量中包含HTML标签时，这些标签会被转义为相应的实体字符，从而失去语义。例如<变成<，>变成>。而Markdown转换后的HTML内容恰好是纯文本格式的HTML，因此如果不加处理，就会在模板中被转义。
解决方案
以下是三种常见且有效的解决方案，推荐在理解原理后根据实际场景选用。
方案一：使用safe过滤器
Django模板提供了safe过滤器，可以标记变量为安全的，从而跳过转义。该方法最简单直接，只需在模板输出时加上|safe。
<div>
{{ html_content|safe }}
</div>这样浏览器就能正确解析html_content中的HTML标签，渲染出预期的页面样式。注意：使用safe前必须确保变量内容已经过充分的清洗和过滤，否则可能存在XSS风险。建议只在信任的、由系统生成的Markdown转换结果上使用。
方案二：使用markdown库的扩展关闭自动转义
有些开发者希望在后端就避免转义问题，通过配置markdown库的扩展来实现。实际上，markdown库默认输出的HTML就是原始字符串，不存在额外转义。转义是Django模板引擎的行为。因此该方法并不是直接关闭markdown的转义，而是通过Django的mark_safe函数将转换后的字符串标记为安全。
在视图函数中，使用mark_safe：
from django.utils.safestring import mark_safe
import markdown
def article_detail(request, article_id):
article = Article.objects.get(id=article_id)
raw_html = markdown.markdown(article.content, extensions=['extra'])
safe_html = mark_safe(raw_html)
return render(request, 'article_detail.html', {'safe_html': safe_html})然后在模板中直接输出：
<div>
{{ safe_html }}
</div>因为safe_html已经被标记为安全字符串，Django在模板渲染时不会对其进行转义。这种方法将安全标记前置到后端，使模板更干净。
方案三：自定义模板过滤器
如果需要在多个模板中重复进行Markdown转换并输出安全HTML，可以创建一个自定义过滤器，将转换和标记安全合并为一个操作。
首先在应用的templatetags目录下创建Python文件（例如markdown_extras.py）：
from django import template
from django.utils.safestring import mark_safe
import markdown
register = template.Library()
@register.filter(name='markdown_to_html')
def markdown_to_html(value):
"""将Markdown文本转换为安全的HTML字符串"""
if not value:
return ''
# 使用extra扩展支持更多语法
html = markdown.markdown(value, extensions=['extra'])
return mark_safe(html)然后在模板中加载该自定义标签库并应用过滤器：
{% load markdown_extras %}
<div>
{{ article.content|markdown_to_html }}
</div>这种方式封装性强，便于维护，且过滤器内部已经使用了mark_safe，模板中无需再添加|safe。注意自定义过滤器要放在已注册的app中，模板加载时路径正确。
总结
Django模板中Markdown转换后的HTML被转义的根本原因是模板引擎默认的自动转义机制。解决此问题最常用的三种方法：
- 使用
safe过滤器简单快速，但要注意安全性。 - 使用
mark_safe在后端预先标记安全字符串，思路清晰。 - 自定义模板过滤器将Markdown转换与安全标记整合，适合重复使用。
实际开发中，推荐在视图函数中完成Markdown转换并使用mark_safe，或者采用自定义过滤器，这样既保持了模板的简洁，又统一了处理逻辑，更符合Django的设计哲学。在涉及用户输入时，务必先对原始Markdown内容进行清理（例如过滤XSS攻击的脚本），再转换为HTML，以确保应用安全。