为什么开发 Beex

• 通常情况下，同样的内容，写作和发布时要转换不同的文件格式、重新排版、打包附件，很花时间，后续修订就更令人抓狂了。我想要“一次编辑，到处渲染”。如你所见，本站全站都是通过 Beex 渲染的。
• 我的文档很多，并且有我自己的整理规则，我不能为了符合常见的配置要求把全部文件都放在同一个目录里。
• 由于通用型静态站点生成器要严格遵守设计范式，导致几个功能很难实现，进而导致它们的目的虽然是通用，却最终只能将用户的文档集合构建成一个个精美的……博客。

综上三点，我自己动手写了一个生成器，并给这个项目起名叫 Beex。

通用型生成器的问题：

1. 不支持多个根目录存储源文件。
2. 不支持增量构建。
3. 不支持映射标签的名字和 slug。（这个不难，但是英语母语的人不需要实现这个功能。）
4. 文件名、标题、附件和最终生成的页面路径解耦不彻底。
5. 构建速度慢。（有几个生成器很快，但上面的问题依然存在。）
6. 大部分使用脚本语言编写，搭建环境和安装依赖不仅麻烦，而且占用大量空间。（Beex 0.1.0 的压缩包仅 1.39M。）

Beex 主要针对上述问题探索解决之道，和其他笔记软件的对比可以参考：

• 我使用的笔记应用软件
• 如何做 Kindle 电子书笔记

设计主旨

1. Beex 是我在笔记实践中的产物，所以在设计上它并不是以实现通用接口优先，而是以方便人类使用优先。在下面的每一条里，你都将看到这一思路的体现。

2. Beex 将保持“尽量小巧”、“可增量构建”、“支持多个源目录”三个特性。

3. 相较于单纯地将 Markdown 转为 HTML 并展示列表，它更侧重文档管理（比如实现每篇文章可以带着自己的附件任意移动又不影响其他文章的引用）。

特性

翻页

Beex 的列表页没有分页，当某分类文章过多的时候，你应当考虑增加分类或标签。分类的作用类似文件夹，Windows 的资源管理器有翻页功能吗？如果有，你真的愿意点很多次翻页按钮去找资料吗？

增量构建

有时候可能有一些内容在发布后又需要隐藏，为了达到完全同步全部链接和附件的目的，通用型引擎会重置整个目标目录，这有三个连锁缺点：

1. 放弃了增量构建的能力。（理论上可以通过为全部文件建立索引实现，但通用型引擎索引全部文件会过于复杂，我看了社区讨论，甚至都没有开发团队准备实现它。我也因此开始开发 Beex。2021-05-02 更新：我看到有通过缓存来实现增量构建的方案了，缺点见下面第 3 点。）
2. 随着文章越来越多，每次的构建时间会越来越慢。
3. 如果使用网盘同步生成的文件（可能还包括缓存），不支持增量同步的网盘每次都要重传整个目录，这更慢……

所以我在增量构建和私人文档保护之间找了一个平衡：

• 在 BeexMeta 内有一个 hidden 字段，当其值被设置为 1 时，这篇文章会在 target 目录中被删除。
• 对于已经渲染过的文档，转为私人文档时，附件不做处理。如果你需要删除 target 目录中的附件，请手动删除。
• 对于从未渲染过的私人文档（也就是从新建就被设置为 hidden: 1 的文档），附件也不会输出到 target 目录中，所以不用管它们。

其实 Beex 是可以做到同步删除已发布的附件的，只是这样生成速度会变慢，不划算。

多站点

几种需求：

• 你关注的领域可能有多个，文件的位置散落在硬盘不同位置，这时就需要能将多个目录设置为源目录，而不是把它们复制到同一个目录里。
• 将私人文档和公开文档分成不同的目录，公开目录的内容发布到网上，私人文档渲染成网页格式在本地浏览。同样也是需要能够设置多个目录为源目录。
• 有多个网站需要分别生成。

如果不支持多站点，就要在每一个源目录中复制一份生成器的可执行文件，或者在命令行中来回切换目录。Beex 从一开始就为支持多站点而设计。

路径

解耦了 .md 文件的路径、文件名、标题和 target（目标路径）。当你的源文件越来越多需要重新整理文件夹时，你可以放心地移动源文件，而不用担心影响输出的位置。

附件

只要一个文件夹内只有一个 .md 文件，本文件夹的其他文件就可以保持与 .md 的相对位置，随时可查看、编辑附件。如果将所有附件放在一个特定的文件夹里统一发布，素材多了以后完全无法维护。

另外，一个目录内有多个 .md 文件时，也可以将所有附件复制到每一个 .md 的 target 目录中，但这个策略很浪费空间，所以不采纳。

需要忽略的文件

以 _ 或 . 开头的文件和文件夹会被跳过，这样一些不想渲染的文章，或者想要同时保留多个版本，或者作为存档的原始文件，甚至整个文件夹，都不需要单独存放到其他目录中来避免生成，只要复制一份并在文件（夹）名前面加个下划线就可以了。

BeexMeta

我不希望在写笔记时，为了输入一些元信息而敲击很多引号、换行、缩进等等，所以 BeexMeta 不仅没有使用 YMAL 或 TOML 等语法，甚至是不区分数据类型的，全部是以 : 分隔的字符串键值对。

categories 和 tags 以中英文两种逗号切割列表。作为一个主要使用中文输入法的人，为了输入一个标签列表而频繁切换输入法也是麻烦的，尤其是这两个是元信息里被手工编辑得最多的字段。

逻辑值的 True 和 False 用 1 和 0 代替，同样是为了减少要输入的字符。

为了让任意 Markdown 引擎都能直接渲染源文件，采用了 HTML 注释语法（<!-- -->）包裹 BeexMeta。

Short

short 类似常见的 ID，是一个自增整数，不过全局只有一个序列。这样设计的理由是 Beex 支持多站点，但实际上我们的文档并不是像网站系统一样保存在相互隔离的数据库中，有时我们需要将一些文件从一个文件夹移动到另一个文件夹。

如果在 BeexMeta.target 中使用 short 作为唯一性标识，那么在多个站点的源目录之间迁移文档时，就不用担心构建时 target 冲突。比如我使用 short 来生成文章、分类、标签的 target。

如果你对这种不连续的 ID 感到不舒服，只要不在各个 format 里使用，你就可以当它不存在。

已知问题

• 如果将多站点输出至同一个 target 目录中，它们会互相覆盖列表页和首页：#9015
  • 我不确定会不会在未来增加对这一功能的支持，这是一个极少见的需求。

标签的 slug

有时候可能会修改标签，或在新文章用新的写法，这时候我不希望影响以前的固定链接，比如 sql 变为 SQL 时，比如 collections 改为中文 收集 时。

这需要对标签的名称和 slug（生成 URL 时使用的名字）进行某种映射。（在本站我使用的是 short。）

设置方式参考 Beex 配置。

笔记类软件最佳实践（Best Practices）

参考这篇两文章：

• 我使用的笔记应用软件
• 如何做 Kindle 电子书笔记