从 Org 到 Web：建站记

我不想把 Org 当成一种比较奇怪的 Markdown

最顺手的方案是把 Org 转成 Markdown，再交给成熟的静态站点生成器。标题、段落、列表和代码块通常都能顺利通过，问题出在我实际依赖的那部分 Org。

我的 Org 文件里有 ID、CUSTOM_ID、property drawer、tags、TODO、source block、target、footnote，以及 id: / fuzzy / file 等不同类型的链接。org-roam 又把稳定的 ID 作为节点身份。Majutsu 的手册本身就是 Org；TouchDeck 的笔记会继续连到 niri、fcitx5 和 librime。这些内容共同组成一张持续变化的图。

如果中间加入 Markdown，我还要定义一套映射规则：

• Org ID 在 Markdown 里如何表示？

• CUSTOM_ID 和标题 slug 谁决定最终锚点？

• 跨文件 id: 链接在哪一层解析？

• 反向链接根据哪一份数据生成？

• 原始文件里的源码区间能否继续追踪？

• Org parser 的行为变化以后，哪一层负责同步？

ox-hugo 和 Quartz 已经证明这条路线可以工作。放到我的网站里，Markdown 会成为一份需要长期维护的公共中间模型。我更希望下游直接接收 Emacs 解析出来的 Org。

三层管线各自负责什么

现在的构建过程是：

Org
 │  Emacs / org-element + ox-edn
 ▼
Envelope v1 / EDN
 │  Loam
 ▼
Manifest + Search + Graph + HTML + Org source
 │  SvelteKit
 ▼
Static website

三层各自只处理一类问题：

• ox-edn 解析单份 Org，并把结果编码成 EDN；

• Loam 汇总所有文档，决定页面边界，解析跨文件链接，再生成全站产物；

• SvelteKit 读取这些产物，负责布局、交互和静态页面。

TypeScript 不解析 Org，Emacs 不决定页面长什么样，Loam 也不维护浏览器组件。多出来的两层就是用来守住这些边界的。

ox-edn：让 Emacs 负责解释 Org

ox-edn 的边界很窄：调用 org-element 解析单份 Org，再把 AST 和导出信息编码成 EDN。它不决定 URL，也不生成网站。

核心入口仍然是 Org 自己的 parser：

(org-element-parse-buffer)

我没有在 JavaScript、Rust 或 Clojure 里再实现一个「足够像 Org」的 parser。headline、property、link 和 target 先由正在运行的 Emacs/Org 解释，ox-edn 只负责把结果带出 Emacs。

生产构建输出带版本的数据结构 Envelope v1，大致长这样：

{:ox-edn/schema-version 1
 :ox-edn/exporter
 {:name "ox-edn"
  :version "..."
  :emacs-version "..."
  :org-version "..."}

 :ox-edn/source
 {:path "content/posts/building-this-site.org"
  :sha256 "..."
  :encoding "utf-8"}

 :ox-edn/document {...}
 :ox-edn/diagnostics []}

这里有三条刻意收紧的约束：

• source path 必须是相对仓库根目录的 POSIX path，/home/... 之类的机器绝对路径不能进入公开产物；

• ox-edn 按字节读取源文件，验证内容可以无损往返 UTF-8，并计算 SHA-256，下游因此能确认 AST 对应的是哪一份源文件；

• 生产导出默认使用 strict diagnostic policy，源码区间越界、property 读取失败、未知节点和不可序列化的值都会让导出失败，已有产物不会被半成品覆盖。

链接也按同样的边界处理。对于 Org 能在当前文档中解析的 ID、custom ID、fuzzy 和 radio link，ox-edn 会附上目标 ID 与源码区间等提示。跨文档解析留给 Loam，因为它需要看到完整的内容集合。

{:provider :emacs-font-lock
 :mode "svelte-ts-mode"
 :runs [{:start 1
         :end 7
         :faces ["font-lock-keyword-face"]}]}

Loam：从 Org AST 得到全站页面

ox-edn 回答一份 Org 写了什么，Loam 处理这些 Org 在同一个网站里的关系。

严格编译管线大致是：

load
  → validate
  → normalize
  → partition
  → index
  → resolve
  → render
  → emit

其中最重要的一步是 partition。一棵 Org AST 不必对应一个网页：页面可以来自完整的 Org 文件，也可以来自某个文件中的一个 subtree，这两种形态也正好对应 org-roam 的文件节点和标题节点。

personal profile 目前采用两条页面归属规则：

• 文档根节点同时声明 ID 和 EXPORT_FILE_NAME 时，整个 Org 文件构成一个页面；

• 文档根节点没有声明这组属性时，带有页面身份和发布路径的一级 headline 各自构成一个页面，其 subtree 是该页面拥有的源码。

页面归属只能由一个 :partitioner 提供。这样，哪个 subtree 属于哪个 URL 不会受 extension 加载顺序影响。已有的 :page-partitioners 仍可在分页后追加转换，但不能重新定义页面身份。

文档页的 metadata 继续写在 Org 里：

:PROPERTIES:
:ID: 0d3edb2c-00ce-4e89-8f69-bcd6acd34bb3
:EXPORT_FILE_NAME: posts/building-this-site
:LOAM_KIND: post
:LOAM_STATUS: stable
:LOAM_PUBLISHED_AT: 2026-08-08
:END:
#+FILETAGS: :org:emacs:sveltekit:

Loam 随后为页面、Org ID、CUSTOM_ID、headline、target 和 anchor 建立全局索引，再解析跨文件链接。正向链接、反向链接和 graph edge 都来自同一次解析，不需要由 Web 层重新推断。

最终构建产物包括：

manifest.json
build-report.json
search-index.json
graph.json
pages/*.html
source/**/*.org

manifest.json 记录 route、title、description、tags、status、源码区间、headings、backlinks 和 outgoing links；search-index.json 是搜索需要的精简数据；graph.json 只保留节点和边；source/**/*.org 保存每个公开页面实际拥有的 Org source。正文在这一层已经变成确定的 HTML fragment。

emit 之前，Loam 会递归检查公开 manifest、report 和 HTML fragment。发现机器绝对路径就拒绝发布。strict renderer 遇到未知 Org node 也不会只渲染 children 后继续构建，任意 HTML export block 同样不能直接穿透到页面。

SvelteKit 只消费构建产物

Loam 生成完整的一代产物后，SvelteKit 只读取 .cache/loam。TypeScript 不读 EDN，也不重新解释 Org AST。catch-all route 从 manifest 枚举路径，构建时加载对应的 HTML fragment，再由 adapter-static prerender 成普通静态文件。

页面组件的核心接近这样：

<article class="org-content">
  {@html data.html}
</article>

{@html} 的信任边界在构建阶段。HTML 来自受控 Org source，并经过 Loam 的严格 renderer。外部内容一旦进入这条管线，就必须重新设计这层安全边界。

bb bundle --profile personal ...

把这套架构放回 Org publishing 生态里

比较 ox-edn 时，需要把视角从代码高亮扩展到完整的 Org publishing：谁解释 Org，什么构成公开页面，全站关系又在哪一层建立。

Worg 的 Blogs and Wikis with Org 收录了不少不同年代的方案。我用它观察各个项目如何安排 Org parser、页面边界和 Web 层，功能数量只作参考。

Org / org-roam
      ↓ ox-hugo
Hugo-flavored Markdown + front matter
      ↓ Hugo / Quartz
Web content model

发布边界：知识库与公开网站分开管理

我的日常工作本来就在代码和 Org 之间来回。Majutsu 有 Org 手册和 Elisp 源码，TouchDeck 有 Rust/Wayland 实现和与 niri、fcitx5、librime 相连的设计笔记。很多文章在动笔之前，已经以代码、设计文档或 org-roam note 的形式存在。

网站不应该迫使我为了发布再维护一套内容。但这也不意味着整个 ~/org 都应该公开。

目前 personal-site/content/ 是明确的发布边界：知识库负责思考和积累，content 负责选择哪些内容成为公开作品。以后可以加入更方便的选取、引用和 transclusion，但自动化不能取消这条安全边界。公开页面中隐藏的 drawer 和 comment 仍会保留在 /source/...org 里，因此放进 content 的文件本身就必须适合公开。

我更愿意把这个网站叫作 personal technical workbench。项目、长文、持续更新的 notes、backlinks、threads 和搜索，是同一批知识在不同阶段的视图。

页面身份、内容修订和构建结果分开计算

文章发布以后，正文、链接关系和网站外壳会以不同速度变化。只用一个文件哈希无法同时表达这些变化。

:ID: 的 UUID 是页面的稳定身份，:EXPORT_FILE_NAME: 决定稳定 URL。:LOAM_PUBLISHED_AT: 记录第一次公开的日期，修改正文时保持不变；只有读者值得注意的实质修改才设置 :LOAM_UPDATED_AT:。错别字、CSS 和部署脚本的改动不必把文章标记为更新。

构建侧使用三个 digest：

sourceRevision

公开 Org source 的 SHA-256。一文件一文章时，它覆盖完整文件；collection page 则只覆盖该页面拥有的 subtree。

contentRevision

标题、公开 metadata 和渲染正文的内容版本。comment 等不进入公开内容的改动不会产生新的 editorial revision。

pageBuildDigest

页面内容及其关系依赖的构建版本。正文没变，但另一篇文章新增了指向它的 backlink，这一项仍然会变化。

SvelteKit 默认使用构建时间作为 app version。相同输入连续构建两次时，runtime chunk 名称和页面里的 bootstrap script 也可能变化。我改用 src/ 和 Svelte 配置计算稳定的 site-shell revision，并把搜索索引改成按需加载。在相同构建环境中，连续两次相同构建现在会生成字节一致的文章 HTML。

每次 release 仍然是一代完整、不可变、可以原子回滚的静态文件。部署时用：

rsync --checksum --link-dest=<previous-release> build/ <new-release>/

没有变化的文件直接 hardlink 到上一代，只有变化的文件需要传输。删除旧 release 时，只要新 release 仍引用相同 inode，文件数据就不会消失。完整 generation 与跨代复用可以同时成立。

公开的页面更新历史只跟踪 editorial revision。一个 jj change 可能同时修改网站代码和几篇文章，也可能只做重构。每次正式部署会合并上一代的 revision-history.json 与当前 manifest；同一页面 UUID 的 contentRevision 变化时，才追加一条公开修订记录。

每个页面还有对应的 /source/...org。文章页公开完整原始文件，collection page 公开原文件中的精确 subtree，不把 AST 重新导出成「看起来像 Org」的文本。

Tag 则被投影成 thread。/threads/emacs/、/threads/wayland/ 按 writing、project 和 field note 分组，related threads 来自 tag co-occurrence；搜索中输入 #emacs 时也优先匹配 tag。这些页面仍然来自同一份 Org corpus，不需要另一套内容数据库。

语法展示留在单独的回归测试里

完整的语法展示有两百多行，覆盖链接、列表、special block、LaTeX、source block、表格、脚注和 drawer。全部塞进正文会把建站文章变成 renderer fixture。

这些内容现在放在单独的 Org 语法陈列室。那个页面通过正常内容管线发布，同时充当真实的回归测试；这里则只保留与架构有关的例子。

这篇文章就是一次端到端构建

这篇文章的源文件是：

content/posts/building-this-site.org

网页侧栏里的 view Org 指向本次构建实际发布的 /source/posts/building-this-site.org。这份源文件先由 Emacs 解析，经 ox-edn 编码成 EDN；Loam 为它分配 /posts/building-this-site/，解析链接并生成正文；SvelteKit 最后把页面 prerender 成静态 HTML。

本文直接使用自己的源文件走完整条管线，也成了这个网站的第一份端到端构建测试。