迁移到wiki
文章目录
1. 前言
这个博客一直以来处于鱼与臭豆腐兼得的状态，有时候会写一些深入研究的东西，有时候就水一些偏门玩意。
2023 年整整一年都没写博客，因为工作实在是太忙了，忙到离职前的一个月高烧不退，差点见阎王爷。
工作中的文档主要输出到 confluence，而工作外的都记录到 usememos 和 bookstack，这样下来就没有写博客的心情了，偶尔想着写一些总结，马上就被紧急问题追着离不开身。
好在当下已经离职，经过几个月的休养，身体健康也恢复得差不多，终于有时间整理下积累的文档。
于是新建了一个站点：wiki.wbuntu.com，依旧使用 hugo，依旧托管在 Cloudflare Pages 上，最近在把技术文档转移到这个站点。
2. 选择合适的wiki框架
重度使用了一年多 confluence 后，笔者对 wiki 框架的要求有几个：
- 树状导航：便于文章分类，层级结构也更清晰
- 检索功能：必备选项，具体效果需要看 wiki 框架，confluence 的检索能力太抽象，一般搜索出的干扰项较多，booksatck 的检索功能就很强
- 易于插入图片和附件：大多数的 WYSIWYG（所见即所得）编辑器都支持这个功能，而 Markdown 编辑器需要一些配置，在 hugo 下启用 page bundles 可以满足要求
- 评论功能：很多时候写了一个方案后，都会在文档下讨论问题，如果无法评论，那么创建一个公开的站点也没有意义
按照以上要求，前后测试过了几个框架：
- confluence：目前私有化部署的版本需要收费，资源占用较高，2C4G 的轻量服务器撑不住
- WordPress：免费的 wiki 类型主题无法满足要求，自带的评论框架容易被垃圾评论填满
- wiki.js：GitHub 上一个星星数非常高的项目，实际部署下来感觉并没有那么好，感觉需要熟悉前端技术的用户自行做一些定制化修改
- bookstack：适合作为内部 wiki 使用，缺少树状导航
- hugo：最后又回到了熟悉的 hugo，接下来的任务改为寻找合适的主题
最后又花了一些时间把 Docs 类型的主题都测试一遍，筛选了出几个可用的主题：
- Docsy：来自谷歌的让人头大的主题，尝试按照文档创建了几次项目都卡壳，但 docsy-example 站点却可以正常运行，文档里推荐基于 docsy-example 做修改......
- Relearn：Learn 的 fork 分支，但是界面风格不是笔者喜欢的类型
- GeekDoc：最终选定的主题，但缺少评论功能，做了一些修改将 giscus 集成进去后感觉够用了
3. 使用giscus作为评论
众所周知的网络问题导致访问许多国外评论服务都不正常，但 giscus 是基于 GitHub 项目的 Discussions 功能开发的，如果具备访问 GitHub 的条件，那么也就满足使用 giscus 的条件。
博客里集成 giscus 评论的操作是相对简单的，可以参考 giscus 的官方文档：giscus.app。
giscus 的原理是将一个固定的 GitHub 仓库的授权给 giscus，然后根据选定的映射方式（如 URL、pathname、title 等）来查找与当前页面关联的 discussion，展示评论内容。
对于本身已经具备评论模块的主题，找到评论模块对应的 html，然后在当前项目的 layouts 下创建同名文件覆盖主题模板配置即可，当前博客使用的是 hugo-clarity 主题，修改如下：
GeekDoc 主题不具备评论模块，需要自行添加，笔者在摸索了一下后，选择覆盖 baseof.html 文件，除主页以外的所有页面都启用评论，如下：
注意这里需要将 data-strict 设置为 1，giscus 创建的 discussion 中包含一个当前页面 title 的 sha256，可用于准确关联页面对应的 discussion。
对于 wiki 类的站点，往往 url 也是层级结构的，如父级页面 URL 为：https://wiki.wbuntu.com/cncf/，可能存在多个子级页面如：https://wiki.wbuntu.com/cncf/docker/、https://wiki.wbuntu.com/cncf/k3s/ 等。
如果未设置 data-strict，会出现父级页面展示子页面评论的现象。