每天都要面对的东西,值得为它多花一晚上的时间。
引子
上一篇文章写的是「给博客加上 Markdown:一个字段、两套渲染层」。架构落地之后,每天真正要面对的其实是更琐碎的东西:切一下格式要不要弹窗确认、编辑框的宽度对不对得上、评论框还是不是光秃秃一个 textarea。
这篇文章记录第二轮打磨:三处体验问题、两条通用经验,以及最后把评论的格式开关也一并去掉——只留 Markdown。
一、切换不该再问一遍
第一版实现里,从富文本(CKEditor)切回 Markdown 时会弹一个确认框,理由是「转换有损」:HTML 的行内样式、复杂表格结构无法一比一映射成 Markdown,怕用户不知情就把内容转坏了。
自己用下来觉得别扭:切换这个动作本身就是确认。用户主动把格式切到 Markdown,意图已经很明确,再弹窗多问一遍只是多一道手续;而且弹窗里那句「转换可能有损」,在用户已经点了切换之后才说,本来就已经晚了。
真正值得守住的是另一条:失败时别把内容弄丢。所以这一版直接去掉了 window.confirm,把兜底放在转换环节——转换失败就保留原文,并在预览区提示原因。转换成功则照常把 CKEditor 序列化出来的 HTML 转成干净 Markdown 源码。
顺带修掉一个更隐蔽的 bug。原来的逻辑是「进入 Markdown 模式就转换一次」,但页面直接以 Markdown 模式打开时也会走这条路径——等于把已经是 Markdown 的源码当成 HTML 再转一遍,内容会被二次转换搞坏。现在按初始格式判断:只有从 HTML 切到 Markdown 才触发转换。
实测:一篇 10006 字的 HTML 文章切过去,得到 7750 字干净 Markdown,7 个二级标题、10 个三级标题、4 张表格、43 处加粗、11 段代码块,一个没丢。
二、宽度对不齐,真凶不是分屏
用户反馈「编辑框和编辑栏宽度不一致,可能是分屏导致」。查下来分屏只是表象,真凶有两条:
其一,Django 4.0 的后台是浮动布局,不是 flex。
.aligned label { float: left; width: 160px; }
.aligned label + div.help { margin-left: 160px; padding-left: 10px; }
也就是说字段内容列是从 x=170 开始的。我第一版把工具条、预览直接插进字段容器,一开分屏就把 label 和 help 也变成了 flex 项目,宽度自然对不上。
其二,CKEditor 渲染出的 textarea 只有 cols="40",折算下来约 287px,而且没有宽度内联样式。所以切到 Markdown 源码模式后,编辑框就停在 287px,而旁边的编辑栏有 1090px。
改法是把所有 Markdown 控件收进一个 .md-editor 容器,用 margin-left:170px 对齐字段列,分屏的 flex 只作用在这一层;切到源码模式时再补一句 style.width = '100%',切回富文本时清掉。
| 场景 | 改前 | 改后 |
|---|---|---|
| 非分屏 | 编辑框 287px,编辑栏 1090px | 编辑框与编辑栏同宽 1090px |
| 分屏 | 编辑框 287px,预览区被挤到右侧 | 编辑框 539px、预览 539px,左右对称 |
三、后台:Markdown 也有编辑栏了
富文本有工具条,Markdown 只有光秃秃一个文本框,这个落差得补上。后台这一版加了四样东西:
- 快捷插入:粗体、斜体、删除线、行内代码、二级/三级标题、引用、列表、链接、图片、代码块、表格、分隔线
- 语法速查:折叠面板,忘了怎么写随时展开对照
- 状态栏:光标行列、字符数,以及「没写完」的标记提醒——未闭合的代码围栏、落单的
**、没配对的行内反引号,都会实时提示 - 实时预览:走服务端同一个渲染层,所见即所得;支持分屏,
Ctrl+Enter手动刷新
预览接口复用了前台的渲染函数 render_body,所以后台看到的效果和读者看到的一模一样,不存在「编辑器里好看、发布后变样」的问题。
四、前台:评论与楼中楼回复
评论框原来只是一个 textarea,读者写的纯文本里就算有换行和缩进,展示出来也是一坨。这一版给评论也挂上了 Markdown 编辑栏:快捷插入、实时预览、状态栏、语法速查,四件套齐全。
这里有个必须分清的地方:预览接口和后台是两套。
- 文章是作者自己写的,可信,渲染时不净化,HTML 能原样保留
- 评论是读者输入的,不可信,必须走
bleach白名单净化——不允许style和各种on*事件属性,链接协议只允许http/https/mailto
净化放在渲染层而不是表单层,这样即便哪天把存量富文本评论改成可编辑,依然是安全的。
另外,评论和楼中楼回复用的是同一套表单(点回复时 JS 把 #reply_form 整块搬到该条评论下面),所以编辑栏挂一次就够了——实测回复框里的文本框父节点就是 .md-comment-editor,回复自动继承,不用再写一份。
五、收尾:评论只留 Markdown
上一版给评论做了「纯文本 / Markdown」二选一,默认 Markdown。上线后觉得这个开关是多余的:
- 纯文本写出来的内容,在 Markdown 下照样正常——只是不触发语法而已
- 多一个开关就多一次误选的可能,读者还得先理解「这两个有什么区别」
所以这次直接去掉:表单里的格式字段改成隐藏字段固定 markdown,界面上只留一行提示,告诉读者可以用工具条插入 **粗体**、`代码` 之类。底层仍兼容旧提交(万一哪个角落的缓存页面还带着 html,不会被校验拦下)。
改完实测:页面上可见的单选按钮 0 个,隐藏字段值为 markdown;端到端提交一条带 **粗体** 和列表的评论,落库格式 markdown,渲染出 <strong>、<code>、<ul>,前台零 JS 错误。
六、两条踩坑
其一:改了静态文件没生效,先查收集产物。
static/ 是绑定挂载,collectstatic 只在容器启动时执行。有那么一阵子我反复改 CSS,页面上就是没变化——因为只重建了镜像没重启容器,收集产物还停在二十分钟前。本次编辑框宽度迟迟修不好,真正的拦路虎就是这条:width:100% 那行代码从来没上线。
规矩很简单:改了 blog/static/**、templates/** 或 Python 代码,一律 docker compose build web && docker compose up -d web,然后核对源文件和收集产物的 diff 为空。
其二:无头浏览器的 profile 目录别放在中文路径下。
--user-data-dir 指向含中文的路径时,Chrome 无头模式会直接卡死——连 file:// 的简单页面都不返回,连 --version 都会报 updater 命名管道「拒绝访问」。换成纯 ASCII 路径立刻正常。另外 --dump-dom 的输出必须落到文件再读,直接管道给 head 会丢结果。
小结
三轮改下来最大的感受是:架构搭好只是开始,体验是抠出来的。
- 去掉一道多余的确认,比在弹窗里多写一句免责声明有用
- 宽度对不齐时,先去看框架自己的布局规则(Django 4.0 后台是浮动布局,不是 flex),别急着给自己的容器加样式
- 同一个 Markdown,作者和读者要用两套渲染层——这是安全边界,不是重复劳动
- 评论只留一种写法,反而更省事
目前站内 221 篇文章(219 篇 HTML + 2 篇 Markdown)、59 条评论都在正常服务。下一轮如果有改动,大概是给 Markdown 文章补一个目录导航——先把坑踩完再说。
定稿于 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 把静态站点直推到家宽服务器