「能用」和「做干净」之间,差的是以后每一次改动的成本。
上一篇 《把编辑器打磨顺手》 讲的是怎么让 Markdown 写起来不别扭:去掉多余的确认弹窗、把编辑框和工具条对齐宽度、让评论框也用上 Markdown 编辑栏。
做完那一轮,站上其实还留着两处"能用,但没做干净"的地方:
- 评论层还有一个格式字段——界面上看不见了,但数据库有列、表单有值、渲染层有分支。只要分支还在,"顶层渲染、楼中楼转义"那种两条路径不一致的老 bug 就有机会重演。
- 代码块有两套着色方案——Markdown 文章和 HTML 文章用的是不同的高亮器,配色不一样,而且主题文件还挂在 CKEditor 插件的目录底下。
这篇就是把这两件事收掉。
一、评论:从"默认 Markdown"到"只有 Markdown"
1.1 为什么非删不可
上一轮把评论格式默认成了 Markdown,界面上也只剩一种写法。但字段还在,麻烦就还在:
render_comment()得接两个参数,内部按格式走两条路;- 老页面的浏览器缓存可能还提交
content_format=html,照样走另一条路; - 后台的
list_filter里多一个毫无意义的筛选项。
真正的收益不是少一列数据,而是渲染出口只剩一条路径,没有分支可以出错。删完之后函数长这样:
def render_comment(text):
"""评论正文 -> 可安全输出的 HTML。固定 Markdown + bleach 净化。"""
单参数,固定流程。读者输入是不可信的,所以评论层始终要过 bleach 白名单;这一点跟文章层(作者可信,不做净化)是刻意分开的,之前那篇 《给博客加上 Markdown》 里写过原因。
1.2 存量 25 条富文本评论怎么办
字段不能说删就删。删掉之后,所有评论都会被当成 Markdown 源码渲染——历史富文本评论里的 <p>、<strong> 就会以字面量的形式直接糊在读者脸上。
所以顺序必须是:先转数据,再删字段。
转换直接复用了文章层那套 blog.html2md.html_to_markdown(markdownify + BeautifulSoup),和后台"从富文本切回 Markdown"是同一个实现,不另起炉灶。
转换是有损的:行内样式、class、复杂的表格结构没法一比一映射回 Markdown,丢了就丢了。但文本不能丢。
上线前的试算里踩到一个挺典型的坑:第一次逐条比对,报出两条"文本丢失",查下来是 … 和 … 被当成了差异——比对前忘了先 html.unescape() 解码实体。这是假阳性。修正比对逻辑后,25 条全部 100% 文本保留。
降级策略也想清楚了:万一 markdownify / bs4 没装,html_to_markdown() 会返回 None,这时退化为剥标签留纯文本,而不是原样保留 HTML。
宁可丢样式,也不能让标签以字面量形式出现在读者面前。本次实测兜底 0 条。
1.3 四步迁移链
| 迁移 | 作用 |
|---|---|
0002_comment_content_format |
加字段(默认 html) |
0003_mark_comment_content_format |
给存量 57 条打标记(25 富文本 / 32 纯文本) |
0004_convert_comments_to_markdown |
数据迁移:富文本转 Markdown 源码 |
0005_remove_comment_content_format |
删字段(django_comments 表列一并 DROP) |
0004 的反向操作是 noop——转换不可逆,回滚不假装能还原,需要还原请用迁移执行前的数据库备份。这次执行前正好有一份 backup-20261028-0719 快照兜底。
1.4 代码清理清单
顺着字段删下去,六处要一起改:
sitecomments/content.py:render_comment(text)改单参数,删掉三个格式常量sitecomments/models.py:删字段和is_markdown属性,rendered_comment改调用sitecomments/forms.py:删content_format字段和get_comment_create_data()覆盖sitecomments/views.py:预览接口改render_comment(body)sitecomments/admin.py:fieldsets/list_display/list_filter去掉该字段templates/blog/detail2.html:格式提示行整行删除
1.5 编辑栏顺手又改了四处
- 输入即自动展开预览:读者不必先点一下"预览"才知道自己写的东西长什么样。手动收起后,本页内不再自动展开(
autoPreview标志),不打扰想静静写字的人。 - 新增
{ }代码块按钮:选中文字一键包成围栏,光标自动落在代码内容开头。 - 速查表补两条:代码块写法、
### 三级标题。 - 删掉"支持 Markdown"提示行:编辑栏本身就是说明,再写一行字是废话。占位提示改成「方寸之间自有天地,评论之余才华四溢(支持 Markdown,边写边看预览)」。
工具条现在 11 个按钮:粗体、斜体、删除线、行内代码、引用、无序列表、有序列表、链接、图片、代码块,加一个预览。
二、代码高亮:两套方案在打架
2.1 之前是什么状态
| 来源 | 作用范围 | 机制 |
|---|---|---|
Pygments(content.py 的 codehilite) |
仅 Markdown 文章 | 服务端渲染时内联 style 着色 |
highlight.js 9.12(base2.html) |
全站 pre code |
客户端着色 |
github.css 主题 |
配套 highlight.js | 但路径取自 CKEditor 插件目录 |
prettify.css |
—— | 死文件,全站没有任何引用 |
也就是说:Markdown 文章和 HTML 文章的代码块配色不一致,同一个站点里两种风格;主题文件还挂在插件目录下,想换个主题得去动别人的目录。
2.2 一个差点写进注释里的误判
我一开始的判断是"Markdown 文章被上了两次色,Pygments 先上、highlight.js 再覆盖一遍,谁压过谁全看运气"。
查了实际输出才发现不是这么回事。Pygments 的 codehilite 输出结构是:
<pre class="codehilite"><span style="color: #...">...</span></pre>
没有 <code> 子元素。而 highlight.js 的默认选择器是 pre code,压根匹配不上。
所以真相不是"覆盖",是各管一块:Markdown 文章走 Pygments 的配色,HTML 文章走 highlight.js 的配色。结论一样(配色不一致),但原因完全不同——如果只是"覆盖",调一下 CSS 优先级就能解决;"各管一块"则必须砍掉其中一套。
这个教训挺朴素:先看输出结构,再下结论。猜出来的原因会带你去修一个不存在的问题。
2.3 改法
第一步,blog/content.py 去掉 codehilite 扩展和 _has_pygments(),围栏代码块交给 extra 里的 fenced_code:
extensions = ["extra", "toc", "sane_lists", "nl2br"]
# 输出:<pre><code class="language-python">...</code></pre>
正好是 highlight.js 认的格式。
第二步,把主题文件复制成站点自己的 blog/static/blog/css/highlight-github.css,base2.html 改引用它,不再依赖 CKEditor 的静态路径。
第三步,也是最容易漏的一步:后台预览要同步。PostAdmin.Media 加上同一份 highlight.js 和同一份主题,admin-markdown.js 在预览 HTML 写入后调用 hljs.highlightBlock()。这样后台看到的配色就是读者看到的配色——否则作者在后台预览里看到的是白板,发出去才发现有色,等于没预览。
第四步,requirements.txt 注释掉 Pygments(代码里已经没人 import 它)。
2.4 代价
上色交给 JS 之后,RSS 阅读器里的代码块没有颜色了。
我认为这个取舍是值得的:换来的是 HTML 文章、Markdown 文章、前台页面、后台预览四者配色完全一致,而且不再往 HTML 里塞一堆内联 style(RSS 的 description 是 XML 转义过的,内联样式在里面纯属噪音)。
三、两个不大但会咬人的坑
3.1 静态文件改了,读者看不到
改完评论编辑栏,反馈是"看不到 Markdown 编辑框"。查下来文件确实是新的——浏览器缓存。
解法是给静态文件加版本串:
<link rel="stylesheet" href="{% static 'blog/css/md-editor.css' %}?v=2">
<script src="{% static 'blog/js/md-editor.js' %}?v=2"></script>
以后改这两个文件就把 v 加一,读者不必强刷。
顺带记一条相关规矩:static/ 是绑定挂载,collectstatic 在容器启动时才执行。改了源文件必须 docker compose build web && docker compose up -d web,而且最好 diff 一下源码和收集产物,确认产物真的更新了。这一轮最早那个"编辑框只有 287px"的问题,真因就是源码 22:53 改的、收集产物还停在 22:37。
3.2 迁移文件差点丢了
0005 是在容器里生成的,重建镜像后宿主机源码没了,但库里已经应用过了——迁移状态和源码对不上,下次换台机器部署就会缺文件。
规矩:迁移要么在宿主机源码里写好再 build,要么生成后立刻 docker cp 取回来。这次是手写落回的。
四、验证
- 存量 25 条富文本评论转换完成,59 条评论渲染正常,页面上看不到任何标签字面量
django_comments表已无content_format列;makemigrations --check→ No changes detected- Markdown 文章渲染输出
<pre><code class="language-css">;全站class="highlight"0 个、内联style="color:0 个 - 浏览器实测前台:
class="language-css hljs",13 个hljs-*语法 span - 后台预览接口输出
<pre><code class="language-python"> - 13 个页面(首页 / 详情页 / RSS / 归档 / 分类 / 标签 / 作者 / 搜索 / 联系)全 200,零 JS 错误
五、现在的状态
本站目前 222 篇文章(219 篇 HTML + 3 篇 Markdown),59 条评论全部走 Markdown,代码块只有一套 highlight.js 着色。
文章层保留双格式是必要的(历史存量不能强转,CKEditor 也还要用);评论层只剩一种写法是应该的(读者输入本来就该收敛,多一个字段就多一条出错路径)。
剩下的待办还是那个老熟人:HTTPS。前置条件已经查清楚了——七牛 CDN 要先开 HTTPS,再改 settings 里的 PREFIX_URL、替换存量文章里的 http://cdn... 链接,最后跑 enable-https.ps1。等哪天有整块时间再动它。
定稿于 2026.10.28
本书目录
- 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 把静态站点直推到家宽服务器