mcpField
P
prelude-docs

prelude-docs

github.com/darkmatter文档处理1261 次安装3 天前更新
代码仓库

关于 prelude-docs

这是一项用于在采用 Prelude Nix flake 模块的仓库中配置 Markdown 文档的 Skill，涵盖页面导航、手写内容、选项文档生成和构建验证。

主要功能

  1. 01配置文档页面树
  2. 02将 README 设为入口页
  3. 03按 H2 标题拆分 Markdown
  4. 04生成 NixOS 选项文档
  5. 05构建并验证文档包

适用场景

  1. 01为 Prelude 仓库添加指南
  2. 02无需复制即可展示依赖文档
  3. 03根据模块选项生成参考页

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/darkmatter/prelude --skill prelude-docs

安装后在 Claude Code 中输入/prelude-docs确认已加载。

详细介绍

消费者仓库中的 Prelude 文档

将用户的参数视为任务描述（例如“在 Guides 组下添加一个 recipes 页面”），而不是 shell 命令。管理所需的 Markdown 源文件和现有的 prelude.docs.* 配置；保留无关设置。

前提：仓库导入了 prelude.flakeModules.default（参见 prelude-install 技能）。文档查看器没有启用标志——当 prelude.docs.pages 非空时会自动启用，同时安装 docs 命令、其 x docs 分派入口和 d 快捷键。

编写页面

prelude.docs.pages 是按声明顺序排列的导航树。每个节点只能是叶节点、组或生成节点之一：

prelude.docs.pages = [
  { text = ./docs/getting-started.md; }        # leaf
  { title = "Guides";                          # group: nests, renders no body
    children = [ { text = ./docs/guides/a.md; } ]; }
];
  • 叶节点 { text = <markdown path>; }——文件中的第一个 H1 会用作侧边栏标签；可选的 title 字段可以覆盖它。
  • 组 { title; children; }——仅用于侧边栏嵌套。手动编写的组不应设置 text（该字段是 mdSplit 的来源信息，不是正文）。
  • text 接受任何 store 路径，因此外部依赖文档无需 vendoring：{ text = inputs.some-dep + "/docs/api.md"; } 会按 flake 固定的版本呈现上游页面。
将 README 用作首页
prelude.docs.rootReadme = ./README.md;

当叶节点的 text 等于 rootReadme 时（路径必须完全匹配，而非仅文件名相同），查看器会将其设为项目主页：显示 prelude.project 的 FIGlet 字标和 HTML 简介，正文则保持原样。若还要让 README 的 H2 章节在侧边栏中拥有各自的条目：

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

prelude.lib.mdSplit（flake 的 lib 输出）会在识别代码围栏的 H2 边界处分割一个 Markdown 文件，生成 { title; text; children; }：先是前言，然后每个 H2 对应一个叶节点。前言叶节点会重命名为项目名称；若其来源信息与 rootReadme 匹配，则会显示 README 主页样式。它接受路径、路径字符串或原始 Markdown。

生成选项文档

仅当项目定义了自己的模块选项时才使用。切勿手动维护选项表——应从求值后的选项树生成：

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 = [ … ]; } 单独求值选项——闭包捕获实时 flake-parts 选项树可能导致循环依赖和冗余内容。
  • split = "allLeaves"（默认）：嵌套侧边栏，每个末级选项对应一个叶节点。split = "shallow"：生成一个完整的 pkgs.nixosOptionsDoc 页面。
  • 切勿将 nixosOptions 值序列化为 JSON；它会直接传入 nixosOptionsDoc，只有 Markdown store 路径会进入打包内容。

手动编写与生成： 手动编写的叶节点和组是由仓库维护的说明文字；generate 节点则在构建时根据选项定义生成，绝不手动编辑。上游仓库中检入的 docs/reference/options.md 是维护者使用的产物。不要假设下游有 x sync-docs；若存在自己的生成工作流，请遵循该工作流。

验证

仅暂存所需文件，使新引用的文件在 Git 支持的 flake 求值中可见；无需提交。合并上面的示例时，请保留现有文档页面。

在仓库根目录中执行，不要进入开发环境：

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

在开发环境（nix develop）中：

  • docs 或 x docs——TUI：按数字 1–9 跳转到顶层页面，Tab/Shift-Tab 切换焦点，j/k 滚动，q 退出。
  • docs <page> 会打印一个窗口；页面索引从 1 开始，按深度优先顺序排列叶节点（组不算页面）。docs next / docs prev 可翻页。通过管道输出时会去除 ANSI 转义码，因此可用于脚本和 CI 日志。

参考（固定到 flake.lock 中的 github:darkmatter/prelude 版本）： https://github.com/darkmatter/prelude — docs/your-own-repo.md（消费者接入说明）、docs/configuration.md，以及 prelude.docs.* 下的 docs/reference/options.md。要编辑目录命令，请参阅 prelude-just 技能；x --list 会显示已安装的命令。

评论

支持 Markdown