darkmatter/prelude

prelude-docs

Manage a consumer repo's Prelude docs viewer content — prelude.docs.pages, groups, mdSplit README hero, and generated nixosOptions pages.

Quelltext ansehen

Verwendung

  1. Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
  2. Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
  3. Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/darkmatter/prelude --skill prelude-docs

Vor dem Start

  • Die Installation umfasst weder Modellabo noch API-Kontingent oder Dateizugriffsrechte.
  • Sterne und Installationen zeigen Aktivität, keine unabhängige Qualitäts- oder Sicherheitsprüfung.
Originales Skill-Dokument

Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.

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:

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.

README as the landing page

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.

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.

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:

sh
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.

Verwandte Aufgaben

aus demselben Repository

Weitere Skills

Alle Skills
darkmatter
Community

prelude

Context map of Prelude, the Nix devshell UI suite (MOTD banner, x command catalogue, docs viewer, themed prompt). Use for any task in a prelude-enabled repo, or when the user mentions prelude, x/motd/docs commands, the prelude wizard, or its flake-parts options. Enriches the task with accurate public-interface knowledge; never installs or reconfigures on its own.

Installationen / 1h
2
GitHub Stars
1
Aktualisiert
10. Okt.
darkmatter
Community

prelude-install

Install and configure Prelude (darkmatter/prelude) in any repository — run the setup wizard, wire it into an existing or new flake (the flake-parts module, or prelude.lib.evalModule for blueprint and other flakes), activate packages.prelude-shell in the devshell, and verify with real smoke checks. Use for adding devshell UI (MOTD, x command picker, docs viewer, themed prompt), integrating the generated prelude.nix sidecar, or activation questions (nix develop, direnv, lorri).

Installationen / 1h
2
GitHub Stars
1
Aktualisiert
10. Okt.
darkmatter
Community

prelude-just

Use when authoring or editing Justfile recipes in a repository wired to Prelude, when the user asks to add just recipes or make them discoverable in the x menu, or when a recipe needs descriptions, typed arguments, groups, aliases, or module namespacing. Covers recipe authoring for Prelude's runtime Justfile import and verification through x.

Installationen / 1h
2
GitHub Stars
1
Aktualisiert
10. Okt.