前情

随着知识管理工具和超文本的复兴，这段时间，一种叫做「数字花园 (digital garden) 」的网站范式悄然兴起。早在上个世纪，「花园」就已经是超文本的隐喻了。2015 年，Mike Caulfield 的一篇文章把互联网信息分成两种模式：花园和流。和按时间排列的博客等「流」式信息不同，花园拥有一种空间上的结构，能够体现作者思考、安排、灌溉的过程，例如按主题归类、定期更新的个人维基。

不用说，我看了这个介绍就相当心动，打算自己也整一个。究其本质，数字花园的基本结构，就是一坨彼此链接的静态网页而已，技术上没有难点，关键在于怎么撰写和维护。

制作静态网页并发布到网上，一般有三个步骤：

  1. 首先用常见格式（如 markdown，纯文本等）编辑好内容
  2. 找一个静态站点生成器（如 jekyll, hugo, eleventy, gitbook, …）帮你把内容转换成彼此链接的 html 文件
  3. 发布到静态网站托管平台（如 github pages, netlify, vercel, …）

因为前几年和静态站点生成器有过太多孽缘，我现在一打开文档眼前就发黑，完全不想再理解、配置、修补别人做的框架了。所以，这次我准备走一条邪路——设计自己的静态网页生成流程，就像这位、这位、这位和其他许多选择了自力更生的网友一样。

正片

那么，这和 Trilium 有什么关系？

Trilium 是我目前手头最常用的笔记工具，详情可见我之前几篇文章。由于它用的是富文本编辑器，笔记的默认存储和导出格式恰好就是 html。

而如果右键一则笔记或一个文件夹，选择「export → this note and all of its descendants → HTML in ZIP archive」，就可以导出一个含有很多 html 的压缩包。

解压这个目录，在浏览器里打开 index.html ，会发现导出的全部笔记已经被 Trilium 打包成了一个可以浏览的网站：

测试下来，内部链接跳转和图片引用等都十分完美。

如果我们把这个目录托管到 netlify 等平台，设置好域名，就可以访问了！

那么，拜 Trilium 的原生导出功能所赐，我们已经完成了前两步，立刻拥有了一堆可用的 html 文件。不过，随便测试一下，就发现了好几个问题：

  • 首页用的是老掉牙的 frameset 元素，左右各一个 frame，所以：
    • 移动端适配很烂
    • 缺乏路由，跳转页面时看不到单独的地址
    • 浏览器一般默认禁止 frame 中打开外部链接
  • 太丑，网页设计亟待改进

网页布局和风格大改造

接下来是大刀阔斧地整改花园的布局和装修。

我新建了一棵范例文档树「Garden」来说明这个过程，导出后的目录内容大致如下：

Garden/
index.html
navigation.html
Garden.html
style.css
...（杂物）

其中 navigation.html 是图中左边一栏的树状导航。

树状导航会暴露出所有页面和文件，这不符合我对数字花园的期待——自定义首页内容，「曲径通幽处」，给访客几条精心选择过的浏览路线。所以，导航栏直接不要了，index.html 也可以砍掉，我们用原本的根笔记 Garden 来做首页。

一番删改后：

Garden/
index.html（原名 Garden.html）
style.css
...（杂物）

好了，现在这个网站终于摆脱了 frameset 的荼毒。然后我又从 github 乞讨拼凑了一些 css 代码，外加自己手写的 css，捯饬完毕后，首页变成了这样：

至少能看了。

只是在浏览器的开发者工具里测试移动端效果之后，发现网页缩放比例过小。这是因为当前版本 Trilium 的 html 导出没有写入调整 viewport 的 meta tag。加入下面这行代码就能解决：

<meta name="viewport" content="width=device-width, initial-scale=1">

问题是，这就涉及到修改已经生成的 html 文件，而且每次生成新的 html，就要再添加一次。这种事情，当然不能手动操作。所以我写了一个简陋的 python 脚本，来自动处理新生成的 html：trilium-garden/prune.py at main · idelem/trilium-garden

部署到 vercel

我选择的发布方案是直接把 git repo 部署到 vercel。对于有相关基础的读者来说，步骤非常简单。

首先是在 github 或 gitlab 建立仓库，clone 到本地，把上述生成的内容塞进去，add commit push 等等，在此不赘述。

然后登录 vercel，选择 import project，填写仓库地址，选择要部署的分支和目录即可。静态网站的入口是目录里的 index.html。

这样，每次 push 到远程仓库时，vercel 都会自动更新网站内容。

全文搜索

最小可用版本的数字花园已经搭好了，也上线了，不过隔天我琢磨了一下，感觉这类站点没有全文搜索还是不行，读者在花园里走着走着就会迷路。所以决定再度折腾，给它加上一点基础的全文搜索功能。

我用的是一个叫 lunr 的库，它的原理是：

  1. 每次内容更新后，手动跑一个脚本，建立静态的索引文件
  2. 用户提交搜索表单时，就在这个索引文件里检索，返回结果

在 github 上逛了一圈，我看到了这个项目，它提供了一个 lunr+cheerio 实现简单搜索的范例（cheerio 用来解析 html）。

那么先把这些代码放进目录，没有 nodejs 就先安装 nodejs，然后执行

npm install lunr
npm install cheerio

把依赖安装到了 node_module。在 .gitignore 里添加 node_module/ 这个目录，不要让它混进 git repo。

根据自己的需要对代码进行了一些修改后，执行下面的命令生成索引：

node search/build_index.js

这时打开 search.html，键入搜索词，应该已经能看到下面的内容：

可惜现在 lunr 还不支持中文分词，所以暂时只能搜索英文内容。上个月有人给 lunr 提了中文搜索的 pr，现等待合并中，到时候再迭代吧。

自定义页脚

既然制作了搜索页，当然要让它和其他页面连通。我的计划是再给所有页面添加一个页脚 <footer></footer>，用来放这些常用链接。于是我再度修改 prune.py，写了个自动添加页脚的功能。

添加后的效果：

最终流程

这一切完成后，从 Trilium 笔记生成数字花园的全流程如下：

  1. 在 Trilium 里编辑内容，想要发布时，导出 html zip，把需要的内容（此例中是 Garden.html 和 Garden/）复制到 git repo 所在的目录
  2. 重命名首页为 index.html
  3. 执行 python prune.py
  4. 执行 node search/build_index.js
  5. commit 并 push 到远程仓库

其中 2-5 步还可以写成自动批处理脚本，不过手动操作也不复杂。

复盘

如果你也想采用这一套流程，但不知道它是否适合自己，我在这里总结了配置过程中的一些感受，可供参考：

优势

  • （相对）不折腾，一次配置，永远享受；涉及到的技术简单，理解成本低
  • 可以从 Trilium 数据库的其他位置克隆笔记到站点的文档树，实现思考、写作和发布一体化，又可以随时增删页面，非常灵活
  • Trilium 内置版本控制
  • 自动链接图片、媒体，无需到处找图床
  • 获得一种「自携手瓮灌苔盆」的乐趣

局限

  • 需要一定的编程和 web 开发知识
  • 需要熟悉 Trilium 使用
  • 不方便协作
  • 无法自定义导出格式
  • 编辑内容时没有实时预览
  • 没有自动 backlink，需要自己链接页面（虽然在 Trilium 里链接别的页面很方便）

最后，附上范例中的站点和 git repo 地址，代码比较简陋，请谨慎使用：