Sign in Subscribe
3 min read Obsidian

Obsidian 通用发布插件

最近做了 Obsidian 的插件，用来将 Obsidian 文档库发布成网页以供公网访问，取名为“通用发布”。之所以取这个名字，是因为插件本身并不做实际的网页生成的工作，而是将文档库的文件上传到服务端，由服务端程序生成静态网页文件。

这个插件主要是给像我这种不喜欢将文档库保存到 Git 仓库而又需要将文档公网发布分享的人使用的。相比于现目前主流的开源发布模式，即将文档库提交到 Git 仓库，由 Git 触发运行 CI （比如 Github Actions）来进行发布，“通用发布”插件则需要依赖后端接口。

这个项目我建了三个仓库，分别是：

详细的插件工作流程如下图所示：

sequenceDiagram box purple Obsidian participant PUBLISH_PLUGIN as Publish Plugin end box darkblue Server participant PUBLISH_SERVER as Publish Server participant WEB_GENERATOR as Web Generator end rect rgb(141, 139, 9) PUBLISH_PLUGIN->>+PUBLISH_SERVER: POST /publish/prepare
Send full file list of Obsidian Vault, Including file path and SHA1 value. PUBLISH_SERVER->>+PUBLISH_SERVER: Group files into cached and uncached lists. PUBLISH_SERVER->>+PUBLISH_PLUGIN: 200 OK /publish/prepare
Return the lists of grouped files. end rect rgb(24, 121, 13) PUBLISH_PLUGIN->>+PUBLISH_SERVER: POST /publish
Pack the uncached files in the original directory structure into Zip.
Send grouped file lists and Zip file. PUBLISH_SERVER->>+PUBLISH_SERVER: Add cache files to the Zip to make a complete source zip. rect rgb(126, 11, 85) PUBLISH_SERVER->>+WEB_GENERATOR: POST /generate
Send complete source zip. WEB_GENERATOR->>+PUBLISH_SERVER: 200 OK /generate
Return generated website zip. end PUBLISH_SERVER->>+PUBLISH_PLUGIN: 204 OK /publish
Publish success. end

说几个重点：

  • “通用发布”以 Zip 包的形式在客户端和服务端之间传递数据；
  • 服务端使用文件的 SHA1 值作为缓存标识；
  • 插件只会打包服务端没有被缓存的文件，以文件对于文档库的相对路径打包进 Zip 文件；
  • 服务端收到不完整的文档库 Zip 包，会将包里未缓存的文件进行缓存操作，并且根据文件列表从缓存里拿到相关文件填进 Zip 包里；
  • 网页生成器服务端只有一个接口 POST /generate，接收文档库 Zip 包，返回生成的静态网页文件 Zip 包。

由于这个插件依赖服务端，所以可能只适用于拥有并会使用服务器部署程序的群体。由于这个插件会将你的本地文档库上传到服务端用于生成网页，不推荐使用不受信任的第三方部署的服务端接口。

一般来说，你不需要修改插件和服务端的代码，可以直接进行部署；当然你也可以实现自己的服务端版本来用，服务端本身只需要支持两个接口，太过简单，瞅一眼源代码就懂了，我就不再细说了。

目前我实现了支持使用 MkDocs 的网页生成器服务端，如果你希望用 Gatsby 一类的工具来生成发布自己的文档，可以自行实现相应的网页生成器服务端。