Mode d’emploi
- Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
- Consultez le document original pour les outils, identifiants et environnements requis.
- Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/darkmatter/prelude --skill prelude-docsAvant de commencer
- L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
- Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.
Prelude docs in a consumer repo
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 d accelerator.
Authored pages
prelude.docs.pages is a nav tree in declaration order. Every node is exactly one of leaf / group / generate:
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).
textaccepts 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.
README as the landing page
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:
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.
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:
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
nixosOptionsvalue; 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.
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-interactivelyInside the devshell (nix develop):
docsorx 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.





