Nicholas Clooney

Subspace Builder：从草稿到数字花园

所属系列

自上次回顾以来，Subspace Builder 变化很大。从 v1.13.0 到 v1.20.0，项目有了更好的编辑流程、更好的代码展示，以及更适合日益增长的网站的浏览方式。下面简要回顾这些版本中最重要的变化。

草稿在开发环境可见，在生产环境隐藏（v1.13.0）

v1.12.0 之后，第一项显著改善体验的功能是草稿支持。任何 front matter 中带有 draft: true 的文章，现在都会收录到专门的 /drafts/ 页面，方便在本地开发服务器运行时查看未完成的内容。

听起来不大，却让写作流程清爽了很多。不用再来回管理临时文件，也不用猜哪些文章可以安全发布，你可以把真实的在写内容留在仓库里，像网站其他部分一样浏览。关键是生产环境仍然干净：npm run build 和 npm run prod 仍会从发布输出中排除草稿。

开发服务器中的草稿页，将未发布文章集中展示

开发服务器中的草稿页，将未发布文章集中展示。

代码块终于跟随当前主题了（v1.14.0、v1.19.0、v1.20.0）

这几个版本也让代码展示更像经过认真设计。普通围栏代码块和 GitHub 嵌入现在采用统一的 GitHub 风格视觉，并随网站主题自动调整。浅色主题保持明亮，深色主题自动切换代码区域的背景，而 v1.20.0 的最新打磨进一步改善了深色代码块和移动端嵌入效果。

GitHub 短代码仍然是我最喜欢的新增功能之一，因为它让代码示例始终关联到权威来源。文章不用把容易过时的片段粘贴进 Markdown，而是直接渲染 GitHub 上的真实文件或行范围，同时提供高亮、行号、复制操作，以及长片段折叠。

npm run dev
npm run prod
npm run build

上排是普通代码块，下排是 GitHub 嵌入。

浅色主题 深色主题
浅色主题中的普通代码块 深色主题中的普通代码块
浅色主题中的 GitHub 嵌入 深色主题中的 GitHub 嵌入

这是终端吗？

除此之外，Subspace Builder 现在也自带 terminal 主题。它把近黑底、绿字的风格延伸到整个网站，尤其适合代码密集的文章，因为代码片段区域和 GitHub 嵌入都与整体配色保持一致。

整个网站应用了终端主题

整个网站应用了终端主题。

Docker 让本地和共享预览更容易（v1.14.0、v1.15.0）

运行网站不必再依赖宿主机安装 Node。项目现在为开发和本地生产预览都提供了 Docker Compose 定义，包括独立服务、挂载的工作目录、命名卷和固定端口。这样更容易快速获得可用环境，也方便把网站放在共享反向代理后持续运行。

最初发布后，这套配置也进一步完善了：加入重启策略、整理 compose 文件，并为 Caddy 等其他服务负责入口的环境提供 edge 覆盖配置。实际效果是，无论在本地、共享机器，还是家庭实验室式的环境里使用 builder，都不用改写项目结构。

compose.yml
view raw 
		
  1. services:
    2. 

  2.   dev:
    3. 

  3.     image: node:25-bookworm-slim
    4. 

  4.     restart: unless-stopped
    5. 

  5.     working_dir: /app
    6. 

  6.     volumes:
    7. 

  7.       - ./:/app:cached
    8. 

  8.       - node_modules:/app/node_modules
    9. 

  9.       - _site_dev:/app/_site
    10. 

  10.     ports:
    11. 

  11.       - "127.0.0.1:8080:8080"
    12. 

  12.     expose:
    13. 

  13.       - "8080"
    14. 

  14.     healthcheck:
    15. 

  15.       test: ["CMD-SHELL", "node -e \"require('http').get('http://localhost:8080', r => process.exit(r.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))\""]
    16. 

  16.       interval: 10s
    17. 

  17.       timeout: 3s
    18. 

  18.       retries: 5
    19. 

  19.       start_period: 20s
    20. 

  20.     command: >
    21. 

  21.       sh -lc "npm install && npm run dev"
    22. 

  22.   prod:
    23. 

  23.     image: node:25-bookworm-slim
    24. 

  24.     restart: unless-stopped
    25. 

  25.     working_dir: /app
    26. 

  26.     volumes:
    27. 

  27.       - ./:/app:cached
    28. 

  28.       - node_modules:/app/node_modules
    29. 

  29.       - _site_prod:/app/_site
    30. 

  30.     ports:
    31. 

  31.       - "127.0.0.1:8090:8080"
    32. 

  32.     expose:
    33. 

  33.       - "8080"
    34. 

  34.     healthcheck:

标签现在按真实使用情况分组（v1.16.0）

标签页也更聪明了。/tags/ 不再把所有标签按字母顺序堆成一个长列表，而是按照使用各标签的文章数量分组。最常写的话题排在前面，让页面更像内容地图，而不只是原始索引。

网站越大，这项变化越有用。博客积累了足够多内容后，值得问的不只是“有哪些标签”，还有“我写得最多的是什么”。按数量分组可以立刻回答这个问题。

标签页按使用各标签的文章数量分组

标签页按使用各标签的文章数量分组。

系列页面把相关文章连成阅读路径（v1.17.0）

另一项重要新增功能是 /series/ 栏目。系列页面让我们可以整理一组相关文章，配上介绍，安排有意义的阅读顺序，为读者提供比简单倒序浏览更清晰的话题路径。

详情页尤其方便，因为它不局限于一种顺序。系列可以默认采用手动编排的顺序，读者也能直接在页面上切换为反向顺序、最早优先或最新优先。文章还会链接回所属系列，读者可以从一篇文章跳到更大的集合，不用到处寻找背景。

现在 Subspace 文章也按这个方式组织：它们不再像零散的发布说明，而是能连成一份持续的开发日志。

系列页面展示一组精心编排的相关文章

系列页面展示一组精心编排的相关文章。

文章多了，分页就不可避免（v1.18.0）

首页终于也有了构建时分页。第一页仍在 /，后续页面位于 /page/2/、/page/3/ 等路径，导航中增加了清晰的上一页、下一页链接和页码提示。

这项改动与其说亮眼，不如说必要。blog.nicholas.clooney.io 的内容已经多到不适合默认全塞进一个首页。分页让首页更轻，同时允许归档自然增长。

笔记让网站更接近数字花园（v1.19.0）

这一阶段最新的内容形式是笔记。现在有了专门的 /notes/ 页面和对应集合，容纳不必写成完整博客文章的短内容。参考资料、片段、实验，以及那些即使还不是“完整文章”也值得公开保存的小想法，都有了更合适的位置。

这可能是让博客从单纯的发布日志走向数字花园最明显的一步。文章可以继续保持长篇、结构化，而笔记给更轻快的公开学习留出空间。笔记专用的 OG 图片处理也让它们自然融入现有发布流程。

笔记页展示数字花园式的内容集合

笔记页展示数字花园式的内容集合。

v1.20.0 的 Subspace Builder 走到了哪里

这些版本合在一起，让项目远远超出了一个简单 Eleventy 起步模板的范围。它现在有更安全的草稿流程、更好的代码展示、适合容器的本地配置、更方便发现内容的标签与系列、支持增长的分页，以及笔记带来的第二种内容形式。

这是一段扎实的版本进展。如果你在 v1.12.0 之后又回来使用 builder，v1.20.0 已经是一套完整得多的发布工具。