prelude-docs

利用側リポジトリの Prelude ドキュメント

ユーザーの引数はシェルコマンドではなく、タスクの説明（例：「Guides グループの下にレシピページを追加する」）として扱ってください。要求された Markdown ソースと既存の prelude.docs.* 設定を管理し、無関係な設定は保持してください。

前提条件：リポジトリが prelude.flakeModules.default をインポートしていること（prelude-install スキルを参照）。ドキュメントビューアーに有効化フラグはありません。prelude.docs.pages が空でない場合に自動的に有効になり、docs コマンド、その x docs ディスパッチ、および d アクセラレーターもインストールされます。

作成するページ

prelude.docs.pages は宣言順のナビゲーションツリーです。各ノードは leaf／group／generate のいずれか1つです。

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; } — サイドバー専用の階層です。手書きのグループでは text を設定しないでください（このフィールドは mdSplit の由来情報であり、本文ではありません）。
• text は任意のストアパスを受け付けるため、外部依存関係のドキュメントをベンダーとして取り込む必要はありません。{ text = inputs.some-dep + "/docs/api.md"; } とすると、flake の固定リビジョンにある上流ページがレンダリングされます。

ランディングページとしての README

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

leaf の text が rootReadme と一致する場合（ベース名ではなくパスが完全一致）、ビューアーはプロジェクトのヒーローとして表示します。prelude.project の FIGlet ワードマークと HTML のイントロを表示し、本文は作成時のまま保持します。README の H2 セクションにもそれぞれサイドバー項目を設けるには、次のようにします。

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

flake の lib 出力である prelude.lib.mdSplit は、フェンスを考慮した H2 境界で1つの Markdown ファイルを { title; text; children; } に分割します。最初に前文が入り、その後に各 H2 ごとの leaf が1つずつ続きます。前文の leaf はプロジェクト名に変更され、由来が 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"（デフォルト）：階層化されたサイドバーを作成し、末端の各オプションに leaf を1つ設けます。split = "shallow"：pkgs.nixosOptionsDoc の全内容を1ページにまとめます。
• nixosOptions の値を JSON にシリアライズしないでください。これは nixosOptionsDoc に直接渡され、Markdown のストアパスのみがバンドルに含まれます。

作成するページと生成されるページの違い： 作成する leaf／group は、リポジトリが管理する文章です。generate ノードはビルド時にオプション定義から生成され、手作業で編集することはありません。上流リポジトリにチェックインされている docs/reference/options.md はメンテナー向けの成果物です。下流リポジトリに x sync-docs があるとは限りません。生成ワークフローが存在する場合は、それに従ってください。

検証

新たに参照するファイルを Git ベースの flake 評価で認識できるよう、意図したファイルのみをステージングしてください。コミットは不要です。上記の例をマージする際は、既存のドキュメントページを保持してください。

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> は1つのウィンドウ分を出力します。page は深さ優先の leaf インデックスで、1から始まります（group はページとして数えません）。docs next／docs prev でページを切り替えます。パイプに渡すと ANSI が除去されるため、スクリプトや CI ログでも使用できます。

リファレンス（flake.lock の github:darkmatter/prelude リビジョンに固定してください）： https://github.com/darkmatter/prelude — 利用側リポジトリの設定は docs/your-own-repo.md、prelude.docs.* の設定は docs/configuration.md と docs/reference/options.md を参照してください。カタログコマンドの編集については prelude-just スキルを参照してください。インストール済みのコマンド一覧は x --list で確認できます。