加一个渲染器容易,难的是把散落在各处的输出收敛成一个出口。
为什么要做这件事
后台用的 CKEditor 是所见即所得的富文本编辑器。写随笔够用,但写带表格、带代码块的技术文章时,用鼠标去拖表格单元格、调整缩进,是一件相当痛苦的事。
更根本的问题是:富文本编辑器存的是一团 HTML,没有源码。写错了没法用文本工具改,没法 diff,也没法在本地用编辑器写好再一条命令发出去。
所以决定加 Markdown 支持。目标有三个:
- 用纯文本源码写文章,标题、表格、代码、引用都是可见、可改、可 diff 的
- 既能后台可视化编辑,也能命令行一条命令发表
- 已有的 220 篇文章和 57 条评论一个字都不能变
第三条是硬约束,下面所有的设计都围着它转。
一、先把「格式」写进数据模型
最直接的做法是加一个字段:
class Post(models.Model):
CONTENT_FORMAT_CHOICES = (
(FORMAT_HTML, 'HTML(富文本)'),
(FORMAT_MARKDOWN, 'Markdown'),
)
content_format = models.CharField(
'正文格式', max_length=16,
choices=CONTENT_FORMAT_CHOICES,
default=FORMAT_HTML,
)
默认值必须是 html。这样存量记录在迁移时全部落到默认值,一条都不用写库、都不用重新发布,渲染行为和改造前一模一样。这是整个改造「零回归」的起点——如果默认值选成 markdown,那 220 篇老文章会在上线瞬间集体变形。
生成迁移后,容器内执行:
python manage.py makemigrations blog
python manage.py migrate blog
迁移文件在容器内生成后记得 docker cp 取回主机,否则下次重建镜像就丢了。
二、最关键的一步:收敛成唯一渲染出口
如果没有这一步,Markdown 支持会变成一场灾难。
原来的模板里到处是 {{ post.body|safe }}。加 Markdown 之后,如果只改其中一个地方,就会出现同一个帖子在详情页是渲染好的、在列表页却露出 ** 和 # 的情况——这种 bug 极难排查,因为两个页面看起来"属于同一个功能"。
所以先抽一个渲染层,让所有输出点都走它:
# blog/content.py
@lru_cache(maxsize=512)
def render_body(body, content_format):
if not body:
return mark_safe("")
if content_format == FORMAT_MARKDOWN:
try:
return mark_safe(_markdown_to_html(body))
except Exception:
# 渲染器炸了也不能让整页 500
return mark_safe("<p>%s</p>" % escape(body).replace("\n", "<br>\n"))
return mark_safe(body)
然后逐个替换调用点:
| 位置 | 改造前 | 改造后 |
|---|---|---|
detail2.html |
{{ post.body|safe }} |
{{ post.rendered_body }} |
index2.html |
{{ post.excerpt|default:post.body|striptags|safe|truncatechars:120 }} |
{{ post.summary_text }} |
feeds.py |
直接输出 body | item.rendered_body |
三处都必须改。RSS 那处最容易漏——很多博客的订阅源平时没人看,直到某天改版了才发现订阅里全是 **。
几个细节:
- 带缓存(
lru_cache):列表页一次渲染几十篇,重复解析同样的源码是浪费 - 失败降级:Markdown 渲染器出任何异常,都退回"转义 + 保留换行",绝不因为一篇文章把整页搞挂
- 摘要单独一个出口(
build_summary):它要做的是"去标签、压空白、截断",不是渲染。列表页要纯文本,订阅源要 HTML,两个需求不能混在一个函数里
Markdown 扩展用了 extra(表格、围栏代码块)、toc、sane_lists、nl2br,代码高亮交给 Pygments 的 codehilite,用 noclasses=True 直接输出内联样式——不引入额外 CSS 文件,少一次静态资源请求。
三、文章和评论,必须是两套渲染层
这是本次改造里最重要的一个决策,也是最容易被"顺手统一"掉的一个。
| 文章 | 评论 | |
|---|---|---|
| 作者 | 博主本人 | 任意访客 |
| 信任级别 | 可信 | 不可信 |
| 是否净化 | 否 | 是 |
| 渲染模块 | blog/content.py |
sitecomments/content.py |
文章正文是博主自己写的,直出 HTML 没问题(要支持嵌入 <iframe> 之类的嵌入代码)。评论是读者输入的,必须走白名单净化。
如果图省事把评论也接到 blog/content.py 上,等于给全站开了一个存储型 XSS 洞。
净化放在渲染层,不是表单层
一开始的想法是在表单里净化:提交时洗一遍,存进库的就是干净 HTML。这样存量 25 条历史富文本评论不受影响。
但这个设计有个隐患:存量评论日后若被改成可编辑(比如后台加个编辑功能),旧数据重新直出就又是漏洞。 表单层只保护新提交,管不住历史数据。
所以净化下沉到渲染层,每次输出时都洗一遍:
ALLOWED_TAGS = ['p', 'br', 'strong', 'b', 'em', 'i', 'u', 's',
'code', 'pre', 'blockquote', 'ul', 'ol', 'li',
'a', 'img', 'hr', 'h1', 'h2', 'h3',
'table', 'thead', 'tbody', 'tr', 'th', 'td']
ALLOWED_ATTRS = {'a': ['href', 'title', 'rel', 'target'],
'img': ['src', 'alt', 'title']}
白名单里故意不包含 style 和任何 on* 事件属性,链接协议限制为 http / https / mailto。
还有一个细节:缺 bleach 时要降级为全部转义,而不是放行。宁可显示成字面量,也不能因为一个依赖没装就把 XSS 防线打开。
顺带修掉一个老 bug
改造时发现:顶层评论用 {{ comment.comment|safe }} 直出,楼中楼回复用 {{ reply.comment }} 自动转义。同样的内容放顶层能显示 HTML,放回复里变成字面量 <p>——两条路径行为不一致,一直没人发现。
统一成 {{ x.rendered_comment }} 之后,这个 bug 顺手消失了。
四、后台:按格式切换编辑器
后台要能编辑 Markdown 文章。有个前提条件必须搞清楚:
CKEditor 接管 textarea 之后,原来的 textarea 仍然留在 DOM 里,且
name属性不变。
这是整个"动态切换编辑器"能成立的基础。切换时的处理:
- HTML → Markdown:调
inst.destroy()。CKEditor 会把编辑器内容写回原 textarea,源码因此得以保留 - Markdown → HTML:从 textarea 的
data-config里读出配置,调CKEDITOR.replace()重启编辑器
还有个坑:CKEditor 会把 Markdown 源码当 HTML 规范化,从而改写源码本身。 所以 Markdown 文章必须用普通的 Textarea 控件,不能共用 CKEditor。
class PostAdminForm(forms.ModelForm):
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
fmt = None
if self.is_bound and 'content_format' in self.data:
fmt = self.data.get('content_format')
if not fmt and self.instance and self.instance.pk:
fmt = self.instance.content_format
if not fmt:
fmt = FORMAT_HTML
body_field = self.fields['body']
if fmt == FORMAT_MARKDOWN:
body_field.widget = forms.Textarea(attrs={'rows': 28, 'class': 'markdown-source'})
else:
body_field.widget = CKEditorUploadingWidget(config_name='awesome_ckeditor')
五、命令行发表:一条命令把文章推上线
后台点点点点也能发文章,但写技术文章的习惯是本地写好文件再发。所以加了个管理命令:
docker exec deploy-web-1 python manage.py publish_post article.md \
--title "文章标题" \
--tags "Markdown,Django" \
--category "Django技术"
支持 YAML front-matter 声明元信息:
---
title: "文章标题"
excerpt: "文章摘要"
tags: [Markdown, Django]
category: Django技术
status: p
---
正文从这里开始……
几个设计点:
- 幂等:按标题
get_or_create,同标题更新既有文章而不是重复创建 - 格式按扩展名判断:
.md走 Markdown,.html走 HTML,也可用--format强制 - 摘要缺省自动截取,从正文里提取纯文本
--dry-run只解析不写库,写之前能先确认解析结果- 支持 stdin:
cat article.md | python manage.py publish_post -
这条命令本身有个坑值得记下来:它按标题做幂等,所以想改一篇已有文章的标题时不能靠它——标题一变就变成新建文章,URL 会变、旧文还留着。重写既有文章必须按主键(pk)原地更新。
六、存量数据的格式标记
评论这边有个额外的活儿:57 条历史评论里,有 25 条是富文本 HTML(含 <p>、<strong>),32 条是纯文本。
- 富文本的必须标成
html,否则<p>标签会被 Markdown 当普通文字处理,标签会露出来 - 纯文本的标成
markdown,读者的**粗体**才会生效
这个标记写成了数据迁移,跟着代码走:
def mark_formats(apps, schema_editor):
Comment = apps.get_model('sitecomments', 'Comment')
for c in Comment.objects.filter(root_id=0).iterator():
if re.search(r'</?[a-zA-Z][^>]*>', c.comment):
c.content_format = 'html'
else:
c.content_format = 'markdown'
c.save(update_fields=['content_format'])
判断条件只看成对的 HTML 标签,不看单个 <。否则 a < b 这种正常写法会被误判成 HTML。
用数据迁移而不是手工改库的好处是:换机器、重建数据库时自动完成,不依赖任何人工步骤。
七、验证:不能只看"页面没报错"
改输出型功能,最怕的是"页面看着正常,其实内容悄悄变了"。所以做了逐条比对:
- 改造前先把 57 条评论在两种渲染路径下的输出全部导出成基线 JSON
- 改造后逐条对比,剥掉标签只比文本内容
- 结果:20 条字节级完全一致,37 条文本内容完全一致(只是多了
<p>包裹、换行归一),文本差异 0 条
为什么要剥标签再比?因为 bleach 会把 \r\n 归一成 \n,这属于无害的格式归一,如果按字节比对会淹掉真正的问题。
XSS 拦截也做了实测。构造一条含各种攻击构造的评论:
<script>alert(1)</script><img src=x onerror=alert(2)>
[点我](javascript:alert(3))<a href="javascript:alert(4)">链接</a>
<iframe src=evil></iframe>
渲染结果:<script> 和 <iframe> 标签被剥离、onerror 属性被移除、javascript: 链接的 href 被清空(<a> 标签保留但没有链接目标)。剩下的 alert(1) 只是无害的纯文本残留。
八、踩坑清单
| 坑 | 现象 | 解法 |
|---|---|---|
散落的 |safe |
改一处漏一处,列表页露出原始标记 | 先抽唯一渲染出口,再逐个替换 |
| 默认值选错 | 老文章上线集体变形 | default=FORMAT_HTML,存量零改写 |
| CKEditor 改写源码 | Markdown 源码被当 HTML 规范化 | Markdown 必须用普通 Textarea |
| 净化放表单层 | 历史数据日后可编辑则漏洞复现 | 净化下沉到渲染层 |
| 依赖缺失时放行 | 少装一个 bleach 就开洞 | 缺依赖时降级为全部转义 |
publish_post 幂等 |
改标题变成新建文章 | 重写旧文按 pk 更新 |
| 容器内模块名 | import Pygments 报 ModuleNotFoundError |
PyPI 包名是 Pygments,模块名是小写 pygments |
| 渲染异常 | 一篇文章把整页搞挂 | 渲染层 try/except 降级 |
写在最后
这次改造的核心体会只有一句:
加一个渲染器不难,难的是让"格式"这件事在系统里只有一种说法。
字段是格式的说法,渲染层是格式的说法,输出点必须全部经过渲染层——三者对齐了,Markdown 支持就是个小工程;少对齐任何一环,就会变成"详情页正常、列表页变形、订阅源漏标记"这种连环 bug。
文章和评论分成两套渲染层,看起来是重复,其实是最省事的做法——它们的信任级别根本不同,硬合在一起才是真的麻烦。
定稿于 2026.10.27
本书目录
- 01 把网站从云服务器搬回家里:Django + Docker + IPv6 DDNS 迁移实录
- 02 评论功能迁移完善:把四处 site-packages 补丁收拢为 sitecomments 自定义 app
- 03 为什么 AAAA 记录指向家里的 IPv6 地址,外网就能直接访问
- 04 外网打不开、本机却正常:一次 IPv6 静默断网三小时的完整复盘
- 05 用 Markdown 写博客:一篇示例,也是本站的格式说明
- 06 给博客加上 Markdown:一个字段、两套渲染层,和一堆必须小心的地方
- 07 把编辑器打磨顺手:去掉多余确认、对齐宽度,让评论也用上 Markdown
- 08 收尾两件事:评论只剩 Markdown,代码高亮只剩一套
- 09 编辑栏合并成一套,顺手补上撤销重做
- 10 博客媒体全面上云:CDN 域名统一与纯云存储改造
- 11 把博客升级到 Django 4.2 LTS:一次低风险、却有意外收获的升级
- 12 网站优化记录:存储后端本地化与 Markdown 编辑器统一
- 13 把文章编成书:给博客加一个「文集」板块
- 14 网站开发里程碑小结:siliu.online 的架构与特点
- 15 小结之后的继续打磨:PDF 导出、悬浮目录与后台收尾
- 16 本站功能与使用指南:siliu.online 一览
- 17 外网也能传:用 Docker SFTP 把静态站点直推到家宽服务器