文集 / 把博客搬回家

第 6 篇·共 17 篇

卷二 · 编辑器与格式

给博客加上 Markdown:一个字段、两套渲染层,和一堆必须小心的地方

2026年10月27日 ·查看目录

加一个渲染器容易,难的是把散落在各处的输出收敛成一个出口。

为什么要做这件事

后台用的 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。

用数据迁移而不是手工改库的好处是:换机器、重建数据库时自动完成,不依赖任何人工步骤。


七、验证:不能只看"页面没报错"

改输出型功能,最怕的是"页面看着正常,其实内容悄悄变了"。所以做了逐条比对:

  1. 改造前先把 57 条评论在两种渲染路径下的输出全部导出成基线 JSON
  2. 改造后逐条对比,剥掉标签只比文本内容
  3. 结果: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

本书目录
  1. 01 把网站从云服务器搬回家里:Django + Docker + IPv6 DDNS 迁移实录
  2. 02 评论功能迁移完善:把四处 site-packages 补丁收拢为 sitecomments 自定义 app
  3. 03 为什么 AAAA 记录指向家里的 IPv6 地址,外网就能直接访问
  4. 04 外网打不开、本机却正常:一次 IPv6 静默断网三小时的完整复盘
  5. 05 用 Markdown 写博客:一篇示例,也是本站的格式说明
  6. 06 给博客加上 Markdown:一个字段、两套渲染层,和一堆必须小心的地方
  7. 07 把编辑器打磨顺手:去掉多余确认、对齐宽度,让评论也用上 Markdown
  8. 08 收尾两件事:评论只剩 Markdown,代码高亮只剩一套
  9. 09 编辑栏合并成一套,顺手补上撤销重做
  10. 10 博客媒体全面上云:CDN 域名统一与纯云存储改造
  11. 11 把博客升级到 Django 4.2 LTS:一次低风险、却有意外收获的升级
  12. 12 网站优化记录:存储后端本地化与 Markdown 编辑器统一
  13. 13 把文章编成书:给博客加一个「文集」板块
  14. 14 网站开发里程碑小结:siliu.online 的架构与特点
  15. 15 小结之后的继续打磨:PDF 导出、悬浮目录与后台收尾
  16. 16 本站功能与使用指南:siliu.online 一览
  17. 17 外网也能传:用 Docker SFTP 把静态站点直推到家宽服务器