prelude-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Prelude docs in a consumer repo

使用方仓库中的 Prelude 文档

Treat the user's argument as the task description (e.g. "add a recipes page under a Guides group"), not a shell command. Manage the requested Markdown sources and existing

prelude.docs.*

configuration; preserve unrelated settings.

Prerequisite: the repo imports

prelude.flakeModules.default

(see the

prelude-install

skill). The docs viewer has no enable flag — it activates automatically when

prelude.docs.pages

is non-empty, which also installs the

docs

command, its

x docs

dispatch, and the

accelerator.

将用户参数视为任务描述（例如“在 Guides 分组下添加一个 recipes 页面”），而不是 shell 命令。管理所请求的 Markdown 源文件和现有的

prelude.docs.*

配置；保留无关设置。

前置条件：仓库导入了

prelude.flakeModules.default

（参见

prelude-install

skill）。文档查看器没有启用开关——当

prelude.docs.pages

非空时会自动激活，同时安装

docs

命令、

x docs

分派和

快捷键。

Authored pages

手动编写的页面

prelude.docs.pages

is a nav tree in declaration order. Every node is exactly one of leaf / group / generate:

nix

prelude.docs.pages = [
  { text = ./docs/getting-started.md; }        # leaf
  { title = "Guides";                          # group: nests, renders no body
    children = [ { text = ./docs/guides/a.md; } ]; }
];

Leaf
```
{ text = <markdown path>; }
```
— the file's first H1 labels the sidebar; an optional
```
title
```
overrides it.
Group
```
{ title; children; }
```
— sidebar-only nesting. A hand-written group should not set
```
text
```
(that field is mdSplit provenance, not a body).
```
text
```
accepts any store path, so external dependency docs need no vendoring:
```
{ text = inputs.some-dep + "/docs/api.md"; }
```
renders the upstream page at your flake's pinned revision.

prelude.docs.pages

是按声明顺序排列的导航树。每个节点只能是 leaf / group / generate 三者之一：

nix

prelude.docs.pages = [
  { text = ./docs/getting-started.md; }        # leaf
  { title = "Guides";                          # group: nests, renders no body
    children = [ { text = ./docs/guides/a.md; } ]; }
];

Leaf
```
{ text = <markdown path>; }
```
——文件中的首个 H1 用作侧边栏标签；可选的
```
title
```
会覆盖它。
Group
```
{ title; children; }
```
——仅用于侧边栏嵌套。手动编写的 group 不应设置
```
text
```
（该字段用于记录 mdSplit 来源，而不是正文）。
```
text
```
接受任意 store path，因此外部依赖文档无需 vendoring：
```
{ text = inputs.some-dep + "/docs/api.md"; }
```
会在 flake 锁定的 revision 上渲染上游页面。

README as the landing page

将 README 作为落地页

nix

prelude.docs.rootReadme = ./README.md;

When a leaf's

text

equals

rootReadme

(exact path match, not basename), the viewer styles it as the project hero: FIGlet wordmark of

prelude.project

plus the HTML intro, with the body kept as authored. To also give the README's H2 sections their own sidebar entries:

nix

prelude.docs.pages = [
  (inputs.prelude.lib.mdSplit ./README.md)
  { text = ./docs/getting-started.md; }
];

prelude.lib.mdSplit

(the flake's

lib

output) splits one Markdown file at fence-aware H2 boundaries into

{ title; text; children; }

— preamble first, one leaf per H2. The preamble leaf is renamed to the project name and gets the README hero when its provenance matches

rootReadme

. It accepts a path, a path string, or raw Markdown.

nix

prelude.docs.rootReadme = ./README.md;

当某个 leaf 的

text

与

rootReadme

相等时（要求路径精确匹配，而不是仅匹配 basename），查看器会将其设置为项目 hero：显示

prelude.project

的 FIGlet 字标和 HTML 简介，同时正文保持原样。若还需让 README 的各个 H2 章节在侧边栏中拥有独立条目：

nix

prelude.docs.pages = [
  (inputs.prelude.lib.mdSplit ./README.md)
  { text = ./docs/getting-started.md; }
];

prelude.lib.mdSplit

（flake 的

lib

输出）会在能够识别代码围栏的 H2 边界处拆分一个 Markdown 文件，生成

{ title; text; children; }

——先放置 preamble，再为每个 H2 放置一个 leaf。preamble leaf 会重命名为项目名；当其来源与

rootReadme

匹配时，还会获得 README hero。它接受 path、path string 或原始 Markdown。

Generated option docs

生成选项文档

Only when the project defines its own module options. Never hand-maintain an option table — generate it from the evaluated option tree:

nix

prelude.docs.nixosOptions = {
  inherit (eval) options;   # lib.evalModules side-eval, not the live flake-parts
  transformOptions = o: o // { declarations = []; };  # any nixosOptionsDoc arg
};
prelude.docs.pages = [ /* … */ { generate = "nixosOptions"; title = "Options"; } ];

Side-evaluate options with
```
lib.evalModules { modules = [ … ]; }
```
— closing over the live flake-parts option tree risks cycles and noise.
```
split = "allLeaves"
```
(default): nested sidebar, one leaf per terminal option.
```
split = "shallow"
```
: one full
```
pkgs.nixosOptionsDoc
```
page.
Never JSON-serialize the
```
nixosOptions
```
value; it feeds nixosOptionsDoc directly and only Markdown store paths enter the bundle.

Authored vs generated: authored leaves/groups are prose the repo maintains;

generate

nodes derive from option definitions at build time and are never edited by hand. Upstream's checked-in

docs/reference/options.md

is a maintainer artifact. Do not assume downstream has

x sync-docs

; follow its own generation workflow when one exists.

仅当项目定义了自己的 module options 时使用。绝不手动维护选项表——应从求值后的选项树生成：

nix

prelude.docs.nixosOptions = {
  inherit (eval) options;   # lib.evalModules side-eval, not the live flake-parts
  transformOptions = o: o // { declarations = []; };  # any nixosOptionsDoc arg
};
prelude.docs.pages = [ /* … */ { generate = "nixosOptions"; title = "Options"; } ];

使用
```
lib.evalModules { modules = [ … ]; }
```
对选项进行侧向求值——闭包捕获 live flake-parts 选项树可能导致循环和噪声。
```
split = "allLeaves"
```
（默认）：使用嵌套侧边栏，每个末端选项对应一个 leaf。
```
split = "shallow"
```
：生成一个完整的
```
pkgs.nixosOptionsDoc
```
页面。
绝不将
```
nixosOptions
```
值 JSON 序列化；它会直接传给 nixosOptionsDoc，且只有 Markdown store path 会进入 bundle。

**手动编写与生成：**手动编写的 leaf/group 是仓库自行维护的说明性内容；

generate

节点在构建时从选项定义派生，绝不能手工编辑。上游仓库中已提交的

docs/reference/options.md

是维护者产物。不要假设下游存在

x sync-docs

；如果下游有自己的生成工作流，应遵循该工作流。

Verify

验证

Make newly referenced files visible to Git-backed flake evaluation by staging only the intended files; no commit is required. Preserve existing docs pages when merging the examples above.

From the repo root, without entering the devshell:

nix build .#prelude-docs   # evaluates the pages tree and builds the bundle
./result/bin/docs 1        # prints leaf 1 non-interactively

Inside the devshell (

nix develop

```
docs
```
or
```
x docs
```
— TUI: digits 1–9 jump top-level pages, Tab/Shift-Tab moves focus, j/k scroll, q quits.
```
docs <page>
```
prints one window; page is a 1-based depth-first leaf index (groups are not pages).
```
docs next
```
/
```
docs prev
```
page through. Piped output strips ANSI, so this works in scripts and CI logs.

Reference (pin to your flake.lock's

github:darkmatter/prelude

revision): https://github.com/darkmatter/prelude —

docs/your-own-repo.md

(consumer wiring),

docs/configuration.md

, and

docs/reference/options.md

under

prelude.docs.*

. For catalogue command edits see the

prelude-just

skill;

x --list

shows the installed surface.

通过仅暂存预期文件，使新引用的文件对基于 Git 的 flake 求值可见；无需 commit。合并上述示例时，保留现有 docs pages。

在仓库根目录中，无需进入 devshell：

nix build .#prelude-docs   # evaluates the pages tree and builds the bundle
./result/bin/docs 1        # prints leaf 1 non-interactively

在 devshell（

nix develop

）中：

```
docs
```
或
```
x docs
```
——TUI：数字 1–9 可跳转到顶层页面，Tab/Shift-Tab 移动焦点，j/k 滚动，q 退出。
```
docs <page>
```
打印一个窗口；
```
page
```
是从 1 开始、按深度优先顺序计算的 leaf 索引（group 不是页面）。
```
docs next
```
/
```
docs prev
```
用于逐页浏览。管道输出会去除 ANSI，因此适用于脚本和 CI 日志。

参考文档（请固定到你的 flake.lock 中

github:darkmatter/prelude

对应的 revision）： https://github.com/darkmatter/prelude——`prelude.docs.*` 下的

docs/your-own-repo.md

（使用方接入）、

docs/configuration.md

和

docs/reference/options.md

。如需编辑 catalogue 命令，请参阅

prelude-just

skill；

x --list

会显示已安装的命令界面。