文档规范

本规范适用于所有 Luna Flow 仓库。它规定文档存放在哪里、如何划分页面，以及以哪个来源为准。仓库可以在 doc/manual/conventions.md 中添加自己的规则，但不得放宽这些规则。

原则

描述已有的东西。 页面记录当前分支上的实现：公开名称、行为以及背后的设计决策。计划应写在 issue 中，而不是手册里。

英文是源文本。 页面只用英文编写一次。译文通过 gettext 翻译目录从该文本生成，绝不作为页面副本进行编辑。

接口文件具有权威性。 对于 MoonBit 包，pkg.generated.mbti 定义了公开接口。不在接口文件中的名称不得作为公开内容写入文档。

一页，一个目的。 一个页面只能是 API 参考、设计说明、教程或指南之一，不能混合。

仓库布局

doc/
├── conf.json                      title, summary and locales
├── manual/                        English source pages
│   ├── index.md                   overview of the repository
│   ├── conventions.md             optional repository-specific rules
│   ├── <guide>.md                 optional guides (getting_started, architecture, ...)
│   ├── api/<package>.md           one chapter per document type,
│   ├── design/<package>.md        one page per package inside it
│   └── tutorial/<package>.md
├── attachments/                   Typst sources, PDFs and images, shared by all locales
└── locale/
    ├── manual.pot                 generated template, never edited
    ├── zh_CN/LC_MESSAGES/manual.po
    └── ja_JP/LC_MESSAGES/manual.po

doc/ 中不应有其他内容。按语言分目录的旧布局（doc/en_US、doc/zh_CN 等）会被 lunadoc check 拒绝。

`conf.json`

{
  "title": "luna-generic",
  "summary": "Algebraic traits and default numeric instances for Luna Flow math packages.",
  "locales": ["zh_CN", "ja_JP"]
}

title 是仓库在文档库中显示的名称。summary 是出现在文档库目录中的一句话简介；它与其他页面文本一样会被翻译。locales 列出仓库维护的译文语言。

章节与包

手册按读者要找什么来划分，而不是按代码所在位置。每种文档类型是一章，每个有文档的 MoonBit 包在每一章中都有一个页面：

章节	回答的问题	包页面包含
`api/`	我能调用什么？	所有公开的类型、trait 和函数，按用途分组，并附签名与语义。
`design/`	为什么是这样？	目标、约束、所做的决策以及被否决的替代方案。
`tutorial/`	我该如何使用？	一个从头到尾完成的任务，配有可编译的小示例。

页面按包相对于源代码根目录的路径命名：src/core 中的包记录在 api/core.md、design/core.md 和 tutorial/core.md 中；src/backend/dense 中的包记录在 api/backend/dense.md 等页面中。每个有文档的包在全部三章中都有页面。

仓库可以添加以下章节：conformance/（某个标准或规范有哪些要求，以及包如何满足它们）、performance/（测量结果及其方法）和 integration/（其他包如何使用某个包）。章节可以有一个介绍该章的 index.md。其他章节需要在 conventions.md 中制定规则。

指南

直接位于 manual/ 下的页面是跨包的指南：getting_started.md、architecture.md、verification.md 等。文件名使用小写，单词之间用下划线分隔。

页面结构

页面以恰好一个一级标题开头，它就是页面标题。
标题使用句子式大小写：写作“Design decisions”，而不是“Design Decisions”。
不要跳过标题级别。
API 页面将每一项列在以其名称（以代码形式书写）命名的标题下：## `Hom::then` 。标题后的第一句说明该项的作用。
设计页面以其边界结尾：说明该包有意不做的事情。
教程在第一段说明其目标，并在结尾指出接下来该去哪里。

Front matter 是可选的。如果存在，它可以设置 title（当导航标签需要与标题不同时）和 description（用于搜索结果的一句话）。两者都会被翻译。

链接

使用指向 Markdown 文件的相对路径链接到其他页面：[design](../design/core.md)、[overview](../index.md)。站点会为每种语言将它们转换为正确的路由。使用站点的绝对 URL 链接到其他仓库，例如 https://lunaflow.cn/en/luna-generic/。使用从 doc/ 向外的相对路径链接到源代码，例如 ../../src/hom.mbt；站点会将其转换为 GitHub 链接。

检查

lunadoc check 在以下情况下会失败：

缺少 conf.json 或 manual/index.md；
存在已废弃的按语言分目录布局；
翻译目录与英文源不一致；
相对链接指向不存在的文件，或指向仓库之外；
Typst 附件无法编译（使用 --compile 时）。

它还会对 fuzzy 译文和缺失的摘要发出警告。