从DokuWiki迁到Hugo

• 本文约7156字,阅读大致需要15分钟 • SysAdmin, Development

我最近找了些零碎的时间,把运行了十二年的个人Wiki从DokuWiki迁移到了Hugo。

想要搬到Hugo上这个想法其实已经有很久了,但如果说最后一根稻草的话,还是得说是最好的编程语言最近这一堆漏洞,整体上,这个Wiki基本上只有我一个人编辑(早年周师傅还有个账号),对外来说则完全是一个只读的知识库和笔记站;然而为了维持这样一个访问量不大、内容极少变动的站点,我却不得不在服务器上常驻一套PHP运行环境,还需要时时担心因此引入的攻击面,颇有些「为了一碟醋包了一整锅饺子」的感觉,这还不算PHP应用本身往往是由一些草台班子临时凑合写成的,在网上各路教程中时不时就可以看到诸如建议部署者「chmod 777」这样的雷霆建议,插件之类的本身也会成为攻击面,这就很不合算了。

这里记录一下迁移的背景和做法,为什么直接复用了本博客采用的Chaos主题,在这个过程中对主题做的一些改进,以及GeoGebra与SVG配图等几个稍微花了一点心思的细节。

背景

2014年2月搭建Wiki的时候,我选择了DokuWiki,最核心的原因是它没有使用数据库或是自行发明一套存储,所有页面和修订历史都直接以纯文本文件存放在磁盘上。

彼时可供选择的还有另外几个开源产品:MediaWiki、MoinMoin和PmWiki。整体上,当时DokuWiki是同等级别的Wiki软件中最为活跃也最为轻便的。

我认为当时在选型的时候把使用文本文件存储作为一个必要条件是比较明智的,因为这样一来就不需要在迁移的时候写一套适配器去读取数据,少一个环节便可以减少出错的机会,也更容易在一个独立的环境中去做转换操作从而避免生产环境上的误操作。

不过,DokuWiki的局限在过去十年里也越来越明显:

  1. 非主流的标记语法:DokuWiki使用自己的一套语法(例如 ====== 表示一级标题、[[ns:page|文字]] 表示链接、<code> 表示代码块)。如今几乎所有的编辑器、笔记软件、代码托管平台以及AI工具都以Markdown为通用语言,每次在DokuWiki里写东西都要做一次脑内语法切换,用起来很不顺手。不过,最近DokuWiki也实现了Markdown的支持,但如果我已经要改Markdown了似乎也没有什么理由继续留在DokuWiki了。
  2. 功能不够全面,高度依赖插件:像数学公式、流程图、几何作图这类需求,DokuWiki都是通过插件支持的,这些插件是由「社区」维护的,除了它们可能自己发明一些新的语法之外,还有个问题是会增加额外的攻击面。我当时用了mathpublish、graphviz和geogebra这几个插件。插件年久失修的问题在于有时意味着会锁死一个PHP版本,而我又不太想每次升级PHP的时候都在生产系统上直接现场去改,发生过几次之后我感觉到耐心基本上都磨没了。
  3. 阅读与排版体验陈旧:移动端适配、暗色模式、中文排版细节、代码高亮以及打印样式,都不是DokuWiki的强项。平时自己查笔记时,看着已经比自己维护的静态博客差了一截。

既然平时编辑本来就习惯在本地写完再发布,而Hugo+Git的静态站点工作流已经在我自己的博客上稳定跑了很久,把Wiki也收拢到同一套技术栈下,自然就省心不少。

迁移过程:把十二年历史完整搬进Git

这次迁移我不想只把最新版本的页面导出来就了事,而是希望保留自2014年2月18日第一条记录以来的完整修订历史,这些历史未来未必还会开放给公众去看,但我觉得作为一个长期兼职从事代码版本管理系统管理的开发者来说,「能够在需要的时候考古找到来龙去脉」对我来说是一项刚需。

仓库分层与隐私隔离

开工之前,我和AI讨论了具体的实施方案并写了一份文档。大致分成这几步:

  1. 将生产环境的DokuWiki打包放到开发环境去做,从而实现风险隔离。AI只被允许操作这份开发环境中的内容。
  2. 由AI去实现具体的迁移脚本,验证转换好之后的版本和原来的版本一致。迁移脚本大致采取「一次成型」,即迁移过程中每次修改都翻译成Markdown,令结果可以直接通过Hugo完成渲染的做法,这样如果发现问题的话修改迁移脚本重新做一次转换就可以了。
  3. 转换好的「毛坯」继续用AI去做细节修复。

因此我做了几个不同的Git仓库,避免原始数据和转换结果的混同,并分离以前通过ACL保护的内容:

  • archive/:生产环境DokuWiki的逐字节只读快照(包含代码、插件和wiki-data),作为一切转换的唯一数据源。
  • content-private/:原先的一些受ACL保护的私有数据。保持原格式,准备未来迁往别处。
  • site/:最终的Hugo站点仓库。私有命名空间和DokuWiki自带的wiki:、playground: 在转换阶段直接滤掉。

另外,DokuWiki的 *.changes日志里默认记录了每次编辑的来源IP地址。在生成Git提交时,我丢弃了IP字段,只在提交信息末尾保留了DokuWiki-Change: <类型> <时间戳>作为溯源标记。

确定性转换

使用AI工具我很快做了包含三个脚本的工具:

  • tools/dokuwiki2git.py:扫描meta/**/*.changes与media_meta/**/*.changes,结合attic/ 与media_attic/ 按时间顺序生成git fast-import流,还原原始Unix时间戳(显示时区为America/Los_Angeles)、作者映射,以及删除、删除后重建、页面改名等操作。相比逐条调用git commit,用fast-import管道几秒钟就能重建全部历史,也让反复修改转换脚本、推倒重来变得几乎没有成本。
  • tools/dw2md.py:确定性的DokuWiki到Markdown转换器,负责把标题、内部链接、列表、表格、箭头符号、代码块等转成标准Markdown。例如对于bash/sh代码块,如果每一非空行都以 # 、$ 或 % 提示符开头,脚本会自动将其改标为console,避免root身份执行的 # command被语法高亮误判为注释。
  • tools/build.py:从archive/ 重建整个仓库并运行校验。

前面提到我采用的是「一次成型」的转换策略,而不是先导入DokuWiki的 .txt历史,再将其改为Markdown。这种做法有利有弊,前面提到,我的一项核心诉求是历史容易追溯,如果先导入DokuWiki的格式再转换,意味着类似git blame这样的操作看到的可能全都是迁移那一次的提交,我觉得这样会很难看。当然这么做也有弊端:如果脚本写得有问题而没有及时发现,等过几年发现的时候可能就不太容易找到到底是在哪个环节引入的问题了。

由于转换脚本是比较机械的转换,这个过程中要允许一些不完美。为了方便AI工具,转换之后原有的文本文件也一并放入了每个页面的bundle目录,命名为dokuwiki.txt;同时在hugo.toml中配置ignoreFiles = ['dokuwiki\.txt$'],防止误发布。

修正转换器形成一个大致能看的「毛坯」版本之后,就可以固定转换器和这份版本,并在其基础上进行更为精细的AI修复了。整个公开仓库最终保留了551个提交,全部由转换器完成。

URL兼容、插件内容与分类重构

网站改版时,原有内容的URL能继续访问,或者至少做好自动跳转,我觉得很重要——这也是Cool URIs don’t change的老道理(之前在《写给未来的blog》里也聊过类似想法)。例如,原来形如/notes/r/prng_scalability的canonical URL需要原样保留。在Hugo里,普通页面转成leaf bundle(index.md),而像notes、kb/usa/california/santaclara、kb/usa/prc/sfconsulate这类下面还有子页面的节点,则必须转成branch bundle(_index.md)。Hugo生成的URL带结尾斜杠,不带斜杠的旧链接由nginx通过try_files指令(try_files $uri $uri/index.html)直接返回内容,如此也就不需要手工再做重定向了。至于DokuWiki时代用来手工维护目录的各个start页面,则干脆不再迁移,交给分类与索引页面自动生成。

原来依赖的三个主要插件也各自有了替代方案:

  • 数学公式(mathpublish):全站共151处 <m>…</m>,全部集中在数学笔记的9个页面里。转换器自动把PhpMathPublisher语法(如 / 分式、pi、mod、n C r等)转写成了标准KaTeX行内公式 \( … \),服务端渲染失败即报错,相当于自带校验;原文里没加 <m> 标记的纯文本公式(例如AB=BD=12、∠AEF),则在精修阶段用AI逐一补齐。
  • Graphviz:公开内容里其实只有《生娃之后的事项》一页里有一张办理证件的依赖关系图,转换时先保留为dot代码块,精修时直接改写成了Mermaid流程图,顺便也就原生支持了暗色模式。
  • GeoGebra:这部分稍微特殊,后面会继续展开。

精修完所有页面后,我也顺手重构了分类体系。过去DokuWiki里只有kb(知识库)和notes(技术笔记)两大块,而这些是与目录结构绑定的。现在在保持URL路径完全不变的前提下,我把文章重新归类到了五个主题分类下:「技术笔记」、「理财与税务」、「移民与证件」、「生活指南」和「小学数学题系列」,并为每篇文章添加了标签来方便检索。

为什么复用Chaos主题,以及这次做了哪些改进

我博客用的Chaos主题是自己维护的(见之前的重构记录与近期细节改进),其中已经积累了不少我在博客中用过的东西,直接拿来给Wiki复用,可以节省大量重新造轮子的工作:

  • 服务端KaTeX数学公式:构建期直接渲染成HTML和MathML,前端无需加载庞大的渲染脚本。
  • 三态明暗主题:基于日本传统和色的亮色/暗色/自动切换,对比度按WCAG AA校验过。
  • 中文排版与剧本式排版:包括自动中西文间距、标点排版细节、楷体斜体与着重号分离,以及此前为了某个访谈制作,最终做成完整剧本式排版等细节。
  • 打印支持:脚注与跨页链接统一编号、代码行号悬挂换行,以及文末自动附上二维码。
  • 轻量与基础配套:不使用臃肿的前端框架,内置静态站内搜索、Remark42评论(刚好取代旧站里早已废弃的 ~~DISQUS~~)以及Mermaid图表支持。

需要说明的是,博客和Wiki的使用场景有许多不同。博客按时间线排列,Wiki则是按主题查资料。因此这次迁移过程中,我把Wiki暴露出来的通用需求全部做进了上游的Chaos主题,而不是在站点仓库里打补丁:

  1. 目录式列表布局(listStyle = "index"):新增了紧凑、不分页的目录列表风格,配合categoryPreviewCount = 0,首页可以直接按分类展开全部条目,右侧还带ScrollSpy定位的分类导航栏,取代了DokuWiki时期手工维护的start目录页。
  2. 面向知识库的元信息开关:新增了hidePostDate、hideReadingStats和alwaysShowLastmod三个选项。查阅技术笔记或办事指南时,读者更关心的是「最后一次更新是什么时候」(直接通过Hugo的enableGitInfo从Git历史自动获取),而文章十年前的首次创建日期,或「预计阅读3分钟」这类信息对Wiki则没那么重要。站内搜索索引脚本build_search_index.py也做了与此相关的适配。
  3. 可定制的文章翻页范围与顺序:新增pagerScope(支持section、mainSections、site)与pagerOrder(支持按日期、目录、分类、标题排序)。对于kb和notes并存的Wiki,配置pagerScope = "mainSections"就能让全站文章连成一条完整的翻页序列。
  4. KaTeX与中文排版的边界修复:在把大量数学笔记导进Hugo后,踩到了两个之前博客文章里没暴露出来的边界bug。一是排版后处理脚本typeset-content.html会扫描正文做注音([base]{ruby})和色块替换,这会把KaTeX生成的MathML <annotation> 里的 \sqrt[3]{2} 也误认成注音;修复方案是在正文改写前先用占位符把所有KaTeX子树保护起来,最后再线性还原。二是行内公式原先设为inline-block,导致稍长的公式在中文段落里整块折行、拉出难看的空白「河流」;现在改回inline让KaTeX内部在运算符处自然断行,并统一用0.15em处理公式与汉字间的留白,并用 .math-bind防止紧挨着短公式的中文标点被孤立到行首。
  5. 表格标题与等宽列:为Markdown表格补上了 {caption="..."} 标题支持与 {.fixed} 等宽列布局。之前博客文章里的表格大多没有标题,而Wiki里的表格用法更多,这帮我发现了一些排版方面的细节问题。
  6. 图片灯箱:此前点击图片会直接跳转到原图,现在基于浏览器原生的<dialog>元素实现了一个无第三方依赖的灯箱浮层,支持拖拽平移、滚轮和按钮缩放以及键盘Esc关闭,查看细节丰富的几何图示或高分辨率截图时顺手不少。
  7. SVG页面资源支持与构建期暗色适配:这个直接关系到下面要说的GeoGebra与SVG方案。

GeoGebra的处理:为什么不直接嵌入

GeoGebra是一款常见的动态数学软件,可以把几何构图、代数方程和函数图像做成可交互的网页组件,拖动点或滑块就能实时看到图形与数值的联动(早年靠Java applet嵌入,后来迁到了HTML5),在数学教学和解题演示里用得很多。不过,整个Wiki里其实只有《多边形面积问题》这一页用到了两个GeoGebra applet,而且两者都是静态几何构图,并没有用到滑块、动画或交互脚本。

迁移时我认真考虑过要不要在Hugo里继续内嵌GeoGebra,最后的决定是不嵌入,也不在Chaos主题中增加直接的GeoGebra支持。这里的考虑包括:

  • 许可证一致性:Chaos主题以Apache-2.0协议开源,并且有其他用户在用;而GeoGebra的应用授权仅限非商业使用,把它的前端资源或加载逻辑塞进主题,会给下游用户带来不必要的许可隐患。
  • 长期可维护性:我希望这些静态页面在五年、十年之后依然能独立正常显示。虽然可以自己host一套GeoGebra(我最后就是这样做的),但下游用户未必用得上。

这部分我最终采取了一个折衷的松耦合方案。在文章正文里,直接嵌入从GeoGebra导出的静态SVG图示,同时在page bundle里保留原始的 .ggb文件并注明「Made with GeoGebra®」;如果读者确实想动手拖一拖图形,每张图下方都附有一个指向独立路径 /_ggb/?filename=... 的链接,由一个单独托管的GeoGebra Math Apps查看服务来加载对应的 .ggb文件。这样一来,即便未来某个时候那个交互查看服务停掉了,Wiki页面本身和几何配图依然完整可读。

为什么选择SVG作为配图,以及暗色模式的坑

在《多边形面积问题》的旧版页面里,原本采用的是嵌入的GeoGebra图,早期还使用过导出的PNG。这些PNG每张大约有300 KB,以SVG导出,体积则只有14 KB和20 KB,缩小了一个数量级。而且几何图形、框图、示意图这类由线条、多边形和文字构成的图,用矢量SVG存储后,不管是在高DPI屏幕上阅读、在灯箱里放大到800%看细节,还是打印成PDF,边缘都是锐利的,不会像PNG那样放大发虚。

不过,把SVG真正用进Hugo和明暗双主题站点里,还有两个实际问题需要解决:

第一,Hugo的图像处理流水线无法对矢量SVG调用 .Width或 .Resize,之前主题的render-image.html假设所有page bundle里的图片都是位图,碰到SVG就会直接报错。这次顺手补上了SVG直出分支,交由CSS的max-width: 100%自适应宽度;同时在挑选Open Graph和Twitter Card的社交分享封面图时,自动跳过SVG(主流社交平台只认位图,为此我也给Wiki单独配了一张彩铅风格的默认分享图default-social-card.jpg)。

第二,暗色模式适配。像GeoGebra这类工具默认导出的SVG,往往自带一个铺满画布的纯白色背景 <rect>,有时还会漏掉viewBox属性。直接放进页面里,在亮色模式下还能勉强凑合,一旦切到暗色模式,整张图就会像一块刺眼的白砖贴在深色页面上。

懒惰是人类最大的美德,而且,如果手工去改每一张SVG源码,还有可能会破坏原始导出文件。因此我在Chaos主题里做了一套默认开启、可选择关闭的构建期SVG主题适配:

  • 在Hugo构建渲染阶段读取page bundle里的SVG内容,原始 .svg源文件保持不动;
  • 如果 <svg> 有数值型的width/height但缺少viewBox,自动补全viewBox以便正确响应式缩放;
  • 检测并剔除位于(0, 0)且铺满整个画布的纯白色背景 <rect>;
  • 将处理后的副本输出为 .adapted.svg,并在 <img> 上加上 .svg-adapt类,在暗色模式下通过CSS滤镜invert(0.88) hue-rotate(180deg) 反转明暗——invert(0.88) 把黑线翻亮的同时避免纯白在深色背景上过于刺眼,再由hue-rotate(180deg) 把反转成补色的彩色辅助线转回原本的色相倾向。

如果某张SVG本身是彩色插画、徽标或者已经手动适配过暗色模式,主题不应再对其进行处理,只需要在图片链接末尾加上 #raw(例如![图示](diagram.svg#raw)),或者在页面/站点配置中设置svgAdapt = false即可原样输出。

结语

如此,我的服务器上就又少了一个PHP服务;顺带的好处是,博客里不少旧文章的显示效果也跟着好了些。整个迁移加上给Chaos主题补齐这些边角功能,靠AI帮忙两天就做完了,放在几年前大概又会拖成「下次一定」。