文集 / 把博客搬回家

第 8 篇·共 17 篇

卷二 · 编辑器与格式

收尾两件事:评论只剩 Markdown,代码高亮只剩一套

2026年10月28日 ·查看目录

「能用」和「做干净」之间,差的是以后每一次改动的成本。

上一篇 《把编辑器打磨顺手》 讲的是怎么让 Markdown 写起来不别扭:去掉多余的确认弹窗、把编辑框和工具条对齐宽度、让评论框也用上 Markdown 编辑栏。

做完那一轮,站上其实还留着两处"能用,但没做干净"的地方:

  1. 评论层还有一个格式字段——界面上看不见了,但数据库有列、表单有值、渲染层有分支。只要分支还在,"顶层渲染、楼中楼转义"那种两条路径不一致的老 bug 就有机会重演。
  2. 代码块有两套着色方案——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,丢了就丢了。但文本不能丢。

上线前的试算里踩到一个挺典型的坑:第一次逐条比对,报出两条"文本丢失",查下来是 &hellip; 和 … 被当成了差异——比对前忘了先 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

本书目录
  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 把静态站点直推到家宽服务器