authoring

编写文档

介绍如何为使用 Jotdown 的项目编写文档。项目由内容和一个配置文件组成，是 Agent 在代码旁读取的上下文。编译内容的框架、编辑内容的工作室以及向读者提供内容的网站都位于别处，这里不需要你改动它们。

内容项目

<repository>/
├── .jotdown/                   ← Jotdown's own folder, committed
│   ├── config.json             ← title, repository, content, logo, theme
│   └── vercel.json             ← a host's files, when the docs are published
└── <content>/                  ← the repository root itself when content is unset
    ├── docs/                   ← all pages
    │   ├── index.mdx           ← landing page, served at /
    │   ├── meta.json           ← the main section's title, blurb and order
    │   ├── moved.json          ← forwarding record for moved pages
    │   ├── _uploads/           ← images, files, whiteboards, fonts
    │   └── <section>/
    │       ├── meta.json       ← the section's label, description and order
    │       ├── index.mdx       ← section landing page
    │       └── <document>.mdx  ← documents

一个项目对应一个仓库，配置文件始终位于 .jotdown/config.json。.jotdown/ 是 Jotdown 的文件夹，像 .github/ 一样提交：其中包含配置，以及发布文档时主机所需的文件。这些文件不会与应用根目录下自有的 vercel.json 冲突。页面位于仓库根目录，或位于 content 指定的文件夹中，例如 "content": "handbook"。一个仓库只包含一个项目。

工作室通过项目的 owner/repo 路径提供项目内容，因此 /you/notes/guides/sections 是 you/notes 中的 docs/guides/sections.mdx 页面，任何能查看该仓库的人打开链接时，看到的都是同一个页面。/ 是工作室的欢迎页。发布站点会在 /guides/sections 提供同一个页面，因此页面之间按站点根路径互相链接，工作室会自动将这些链接移到项目路径下。参见 ADR 0017。

.jotdown/config.json 是纯数据，因此项目中不会运行任何代码：

{
  "version": 1,
  "title": "Engineering handbook",
  "description": "How our team builds and operates software",
  "repository": "https://github.com/your-org/handbook",
  "url": "https://handbook.your-org.com/docs",
  "branch": "main",
  "content": "apps/docs",
  "logo": { "alt": "Handbook", "src": "/uploads/logo.svg" },
  "favicon": "/uploads/favicon.png",
  "theme": {
    "light": { "background": "#ffffff", "foreground": "#1c1a33", "primary": "#433a86" },
    "dark": { "background": "#0d0c1b", "foreground": "#ecebf5", "primary": "#b9acff" },
    "sections": { "orders-api": "chart-2" },
    "fonts": { "sans": { "family": "Geist", "src": "/uploads/fonts/geist.woff2" } }
  }
}

所有字段都是可选的，但只有在文件存在后，工作室才会在切换器中列出该仓库。没有此文件的项目会使用仓库名作为标题。content 是存放 docs/ 的文件夹。未设置 uploads 时，上传文件默认存放在 content 下的 docs/_uploads；设置后则会将上传文件移到 content 下的其他文件夹。branch 是工作室保存编辑内容的分支；未设置时使用默认分支。url 是发布站点托管的位置，包括域名和基础路径，这样工作室就能提供页面的读者链接。favicon 是发布站点和本地预览的标签页图标；工作室始终显示自己的图标。

theme 使用 shadcn 自有的 token 名称，为项目设置每种模式的颜色。选择 background、foreground、primary、destructive 和 chart-1 到 chart-5；除非你也设置其他 shadcn token，否则其他 token 都会根据这些值计算得出。未设置的核心颜色会保留默认值。sections 通过指定 token 为各个分区设置颜色，窗口底部的色带则会依次使用 chart-1 到 chart-3。参见 品牌设置。fonts 用于指定 sans、serif 和 mono 字体，每项包含字体系列以及从哪个上传的字体文件加载字体。项目的外观完全由主题决定：除此之外不需要样式表。

上传文件存放在 docs/_uploads/，与其所属页面放在一起。docs/ 下名称以 _ 开头的文件夹不会存放页面，因此其中的内容不会显示在侧边栏。通过工作室上传的文件会存放在那里，页面通过文件的公开地址链接到它们；地址中不会包含文件夹名称：/img/docs/<file>、/files/docs/<file>、/whiteboards/<file>，或者你手动放入的其他文件所使用的 /uploads/<file>。

moved.json 会自动写入。侧边栏整理器每次移动或删除内容时都会追加一条记录。工作室会将旧地址重定向到页面的新地址，发布站点则会在旧地址生成转发页面。通过 git 重命名是唯一无法覆盖的情况：

• 不添加记录。旧 URL 会失效，这没关系。
• 修正 docs/ 下指向该页面的链接。搜索旧路径即可找到这些链接。
• 如果旧 URL 已分享给任何人，先征求同意。未经同意，绝不要添加记录。

页面可以包含的内容

页面由 Markdown 和框架提供的一组固定组件组成： 提示框、<VideoEmbed />、<LinkEmbed />、<FileAttachment />、<Whiteboard />、布局组件、内联 SVG 图形，以及 blocks 技能中列出的其他内容；该技能也包含样式规则。添加任何比 Markdown 更复杂的内容之前，请先阅读。这个列表由框架规定，项目不能自行添加内容。

组件属性必须是字面值：字符串、数字、布尔值，以及由这些值组成的数组或对象。任何会运行代码的内容都会导致页面在编译前报错：

• import 和 export 行。
• {new Date().getFullYear()} 或 {props.title} 这样的表达式。
• <script>、<iframe>、<object>、<embed>、<meta>、<link>、 <base> 和 <include> 标签。
• on* 事件处理器和 dangerouslySetInnerHTML。

添加文档

1. 在相应的章节文件夹中创建 .mdx 文件，文件名使用小写字母并以连字符分隔（code-review.mdx）。所有手动编写的页面都必须是 .mdx：.md 文件会编译为纯 Markdown，因此其中的 <VideoEmbed /> 或图形会完全不显示，也不会对此作出提示。只有两种内容会以 .md 格式出现：生成器编写的页面和变更日志；见下文。
2. 为其添加 front matter：

 ---
 title: Code review
 icon: GitPullRequest
 description: One sentence. Shows up in search results and on section cards.
 ---

title 和 description 为必填项。icon 是可选的 Lucide 组件名称，会显示在侧边栏的页面旁和页面标题旁。点击页面上的该图标会打开 Lucide 图标集搜索框，选择器会将所选内容写入同一个字段。没有图标的页面会在标题旁的边栏中提供一个图标选项。只有当图标能为页面提供清晰的视觉提示时才使用，不要仅仅为了填满空间而添加。页面的 URL 是它在 docs/ 下的路径，侧边栏标签则是其 title，因此 slug、sidebar_label 和 sidebar_position 均不起作用。 3. 将不带扩展名的文件名添加到该文件夹的 meta.json 中的 "pages" 数组里，并放在合适的位置。若不添加，页面仍会按字母顺序显示在已命名页面之后，因为每个 pages 数组都以 "..." 结尾。 4. 先用 editorial-illustration 技能绘制一幅编辑风格插图，保存为独立的 SVG 文件，并以 Markdown 图片形式展示，然后编写正文。使用标准 Markdown，以及提示框（:::note、:::warning、:::tip）和 blocks 技能中的内容。生成的页面和变更日志不需要插图。 5. 使用相对文件路径链接到其他文档（./commit-signing.mdx、../architecture/index.mdx）；也可以使用以站点根目录开头的路径，例如 /security-and-compliance/commit-signing。每当某个名词短语指向另一个页面时，都要在其于该章节中首次出现时添加链接，并尽量多添加链接：读者可能从页面中途进入，需要能找到你所讨论内容的相关页面。不要将链接放在反引号中， `[text](./foo.mdx)` 会被渲染为代码，而不是链接。编写时，链接目标缺失不会报错：读者点击后会看到 404，因此请确保所指向的文件确实存在。

添加章节

1. 在 docs/ 下创建一个名称全部小写并以连字符分隔的文件夹。
2. 添加 meta.json，填写侧边栏标签、一句话描述以及其中内容的顺序：

 {
   "title": "Observability",
   "icon": "Activity",
   "description": "How we know what production is doing, and who gets woken up.",
   "pages": ["alerting", "dashboards", "..."]
 }

描述会显示在上方页面中该章节的卡片上。省略描述后，卡片就无法告诉读者该章节是否符合他们的需求。pages 用不带扩展名的文件和子文件夹名称；末尾的 "..." 可让未列出的页面仍然显示出来，请保留。不要加入 "index"：文件夹的 index.mdx 已经是该文件夹行对应的页面，列出它会使页面从该行移到子项中。只有带有独立侧边栏的章节才会列出它。该章节在其他章节中的位置由其文件夹名称决定，即 docs/meta.json 的 pages 数组中的位置。 3. 如果章节需要介绍内容或卡片网格，请添加 index.mdx。先写前置内容，然后是介绍，最后是 <DocCardList />。description 会自动显示在页面标题下方，因此不要在开头段落中重复。 4. 要将页面放到现有页面之下，请将 name.mdx 移到 name/index.mdx，并将其他页面放在同一目录中。页面地址和位置都不会改变，因此无需添加 moved.json 条目；但要将该页面自身的相对链接向下调整一级。 5. 优先将相关内容合并到现有章节中。章节列表越短，越容易浏览。

带有独立侧边栏的章节

侧边栏树上方的切换器可让读者在不同章节间切换；章节是 meta.json 中包含 "root": true 的文件夹。在章节内部，侧边栏只显示该章节的内容，第一行始终是概览页面。如果一组内容有自己的读者，例如决策记录或生成的参考资料，就创建一个章节。如果读者会在一次阅读中往返于该内容及其相邻内容之间，则保留为普通文件夹，因为章节会隐藏相邻内容。添加章节前，请阅读章节与切换器；需要特别注意以下规则：

• 文件夹名称要与其 title 一致，并使用小写字母和连字符。
• 章节 meta.json 中的 title、icon 和 description 会组成切换器中的一行。描述控制在约三十个字符，因为过长时会被省略。只有在这里，描述才是标签。
• 在 pages 中将 "index" 放在第一位，并在旁边添加标题为 Overview 的 index.mdx。根文件夹不会自动选取其落地页，而 "pagesIndex": "index" 会将其隐藏，因此这两种简便做法都不要使用。
• 在 docs/meta.json 中使用 !<folder>，可将文件夹排除在主导航树之外；切换器会按照这些行的顺序列出章节。若直接列出文件夹，其页面就会同时出现在两个侧边栏中。
• 在项目主题的 sections 中添加一行 "<folder>": "chart-2"，即可为章节在两种模式下设置颜色。主导航树使用 primary。
• 侧边栏排列工具只能看到所在章节，因此无法在章节之间拖动页面。请手动移动文件，并修改两处 meta.json 文件。

不使用文件夹为页面添加标签

要在侧边栏中为几个页面添加标题，请在其 meta.json 的 pages 数组中、这些页面之前添加一个分隔符 "---Runbooks---"。它会为其后的所有页面显示标签，直到遇到下一个分隔符；由于不移动文件，页面地址也不会改变。Lucide 图标可以放在前面的方括号中，例如 "---[BookOpen]Runbooks---"。侧边栏排列工具可以添加、重命名、拖动和移除分隔符。如果落地页确实能提供内容，请创建带有落地页的章节和文件夹；如果落地页只是重复标签，则使用分隔符。

链接到侧边栏之外

pages 数组中的一行可以是链接，例如 "[Next.js docs](https://nextjs.org/docs)"， 前面还可以用一对方括号添加可选的 Lucide 图标， 例如 "[Rocket][Next.js docs](…)"。链接没有文件，因此不会进入任何搜索索引 或 llms.txt。请参阅 在侧边栏中添加链接。

白板

在工作室中插入 /whiteboard，即可添加 Excalidraw 绘图。页面会保存 <Whiteboard src="/whiteboards/<hash>.excalidraw" preview="/whiteboards/<hash>.png" />， 两个文件都会存放在 docs/_uploads/whiteboards/ 下。场景 JSON 包含嵌入的 图像。文件采用内容寻址，必须与引用它们的页面一同提交。有关编辑方式和 大小限制，请参阅白板。

生成的页面

从代码生成的参考文档（我们构建此功能时针对的就是 TypeDoc 输出）会以 .md 而非 .mdx 的形式存放，因为 TypeDoc 会在正文中写入 Array<string> 和 Promise<{ … }>，而 MDX 会将它们解析为组件。请在拥有代码的仓库中生成文档， 并将输出提交到 docs/。每个页面都需要 title 和 description 前置元数据， 由 typedoc-plugin-frontmatter 写入；文件夹还需要一个 meta.json。为整份参考文档 单独设立一个章节，使用 "root": true，并让生成器直接指向该文件夹，这样它写入的 index.md 就是该章节的概览。在工作室中所做的编辑，下次生成时会被覆盖， 除非同时将编辑内容更新到上游 JSDoc 中。页面编译时，框架会为 TypeDoc 的 [Form](Form.md) 链接写入 ./。

更新日志页面

前置元数据中带有 changelog: true 的页面就是更新日志，也是唯一手写但采用 .md 而非 .mdx 格式的页面：发布工具会写入其中的内容，而包含 Promise<void> 或 {foo} 的提交主题会被 MDX 解析为 JSX，导致构建失败。将项目的 CHANGELOG.md 粘贴到 前置元数据下方，这就是整个文件。读者会看到搜索框、日期范围、跳转到发布版本的 选择器，以及每个发布版本对应一个圆点的时间轴。

---
title: Changelog
description: Every release of the website, newest first.
changelog: true
---

## [2.15.6](https://github.com/o/r/compare/v2.15.5...v2.15.6) (2026-09-04)

### Bug Fixes

* **infra:** stop null query condition killing redirects ([ae6ab07](https://github.com/o/r/commit/ae6ab07))

这就是完整的内容模型：文件本身，没有第二份副本，也没有生成器。 刷新页面时，只需在相同的前置元数据下粘贴更新后的副本。不要添加脚本、镜像文件夹 或每个发布版本对应的页面；这些做法都曾被构建又被移除，因为它们各自都会生成 一份内容副本，而发布工具每次发布都会重写这份内容。

框架对该文件的处理方式：

• 发布版本以类似 ## [2.15.6](…) (2026-09-04) 的标题表示，也可以是不带链接的相同格式。 版本号由一到三个数字组成，可以带预发布后缀和前导 v；从该标题开始，到下一个此类标题 之前的所有内容，包括正文、列表、表格和图像，都是该发布版本的内容。
• 发布版本标题会被读取，组件会绘制自己的标题。发布版本内的 ### 标题会成为章节，而不是目录项。
• 即使版本升级标题下没有内容，它仍然是一个发布版本，也仍会显示一个圆点。
• 第一个发布版本标题上方的内容会保留为普通 Markdown。 请删除粘贴内容中的 # Changelog 标题，否则页面会出现两个标题。

将发布记录已有数年的项目拆分到一个文件夹中，每个主要版本对应一个页面， 例如 v2.md、v1.md；不要添加 index.mdx，并在文件夹的 meta.json 中 按从新到旧的顺序排列。每个页面只筛选自身的发布版本；长页面会将内容作为水合数据 重复约两次，因此发布版本达到约一百个时就该拆分。ChangelogTimeline、 ChangelogRelease 和 ChangelogSection 绝不需要手动编写。

语气风格

这是一个技术文档库，面向技术读者，同时带有温和引导、循循善诱的感觉。可以借鉴优秀科普作者的表达方式，或《Head First Design Patterns》这类有趣的工程类书籍：用具体但简化的示例和图示讲解。

为人和 AI 写作

我们的使命是降低认知负担。页面绝不能像枯燥的法律或技术文档，而应以友好的方式，从概念上解释发生了什么变化，就像资深同事在指导新人一样。整篇页面应当像作者在白板前带你过一遍 PR 时会说的话。如果不会当面说出来，就不值得写进去。

每个页面都要回答读者实际带着什么问题而来。 写页面之前，先用读者自己的话把这个问题写下来：“如何把它发布为网站？”“为什么我的页面编译失败了？”“要输入什么才能生成图表？”这个问题决定标题、章节、删掉哪些内容，以及读者找到答案后该在哪里停止阅读。把我们所知的一切都倾倒出来的页面只是笔记，会把本该由我们完成的梳理工作留给读者。

我们的标准是优秀的 SaaS 或开源手册：每个页面都围绕某个人要完成的任务展开：

• 标题就是答案，而不是技术名称。“将其发布为网站”，而不是“Docker 和 Vercel”。
• 章节按照读者完成任务的步骤排列。服务于其他问题的内容应放在另一个页面。
• 我们一路学到的经验不应成为页面主体。测量数据、走过的弯路和容易踩的坑都值得保留，可以放进所属章节末尾的 <Accordions> 中：页面读起来简洁，而即将重蹈覆辙的人仍能找到相关信息。
• 只有部分读者会走的路径，例如单体代码仓库或可选模块，应作为常见情形下的子章节，而不是页面主线。

ADR、会议纪要、变更日志或整个系统的概览图记录的是信息，而非答案；它们是例外。除此之外，这里的内容都应是手册页面。

• 以“你”的口吻称呼读者（例如：“你会在第 3 章再次遇到这个问题”）。
• 回答初级开发者真正会当面提出的问题（“等等，为什么这个放在 worker 里？”）。
• 以摘要开篇。此时读者的注意力最集中，但对写作意图的了解最少。摘要应从非技术角度说明故事的核心结论、修复了什么、为什么修复以及如何修复，并提供一个可信的示例。
• 摘要之后，可以再深入一些，用 2 个段落说明整体思路，并列出相关链接。
• 每个页面都要以一幅编辑插画开篇，放在 front matter 之后、摘要之前：画面要让页面的核心观点一目了然，就像杂志文章的开篇插图。使用 editorial-illustration skill 绘制，并将其保存为 :::wide 内 uploads 文件夹中的 SVG 文件；切勿将插画直接嵌入页面。插画营造氛围、体现隐喻，不解释内容，因此负责解释的图表和示意图仍应放在章节中。
• 章节标题应简短、直白，直接描述问题。（例如：“每次按键都会触发搜索请求”）
• 每章都应先陈述问题并介绍解决思路，然后再深入细节。先讲原因，再讲细节。读者应能在第一段得到答案。
• 章节中的段落、代码和图示应交织编排。
• 必须借助图示来降低认知负担，因为人类善于通过视觉学习。用视觉辅助降低认知负担是我们的首要指标。可随时在章节中加入图示和图表。
• 根据文字内容选择章节视觉素材的形式。机制、流程或一组组成部分应使用 figure skill 绘制成图示。数字应使用 chart skill 提供的 <Chart />：随时间变化的趋势用折线图，分类 breakdown 用条形图，前后对比用并列的两根条形，排名用排序后的条形图。一段中出现 3 句数字，就应该改用图表。
• 不要重述或预告将要说的内容，直接进入主题。

  bad:  "In this chapter we'll walk through how the validation logic was restructured."
  good: "The 2-character minimum was moved from the zod schema without any actual changes to the rule."
  

• 读者具备技术背景，但应假设他们对项目、代码库和领域一无所知。
• 使用 <abbr title="plain-words explanation">term</abbr>，以浅显直白的语言说明业务术语、领域术语或相关引用。
• 改写常见的 AI 写作痕迹，例如用空话填充、使用破折号或生硬的对照句式。
• 优先提供具体指导（“使用 X，因为 Y”），而非抽象地讨论权衡。
• 首次提到某个术语时，应在同一句中说明其含义。
• 如果文档记录了一项难以逆转的选择，还应在 docs/decision-records/ 中编写一份 ADR。
• 提到工具时，同时注明其版本和日期，以便看出过时的指导。
• 使用简短段落和清晰的标题。搜索索引和目录都会从标题生成。

提交前审阅页面

要阅读和编辑工作副本，请在 Jotdown studio 中打开项目文件夹。页面直接从磁盘读取，包括尚未提交的页面和被 git 忽略的文件夹；文件发生更改时，已打开的页面会自动刷新。

保存只会写入文件，不会提交任何内容，因此请像往常一样使用 git diff 审阅更改。编辑器身份以这台机器上 git 配置的名称为准。

为他人撰写页面时，建议他们在 Jotdown 中打开文件夹，以便在提交前阅读内容。

提交前

• 对修改过的页面运行 jotdown check，修复它报告的所有错误， 并修复你编写的页面中的警告。
• 不要包含秘密、凭据、API 令牌、私钥、连接字符串或 个人数据。这是文档，不是保险库。
• 内部和预发布环境的 URL 可以使用。主机名不是秘密： 如果页面介绍的是某个系统，那么 argocd.mgmt.example.net 或 *.staging.* 管理员 URL 可以写在 页面中。绝不能放在这里的是能让你进入该系统的东西。出版物本身没有密码，因此 私有文档需要在主机端进行访问控制。