darkmatter/prelude

prelude-docs

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

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/darkmatter/prelude --skill prelude-docs

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

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.

관련 작업

같은 저장소의 Skills

더 많은 Skills

모든 Skills
darkmatter
커뮤니티

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.

1시간 설치 수
2
GitHub Stars
1
업데이트
10월 10일
darkmatter
커뮤니티

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

1시간 설치 수
2
GitHub Stars
1
업데이트
10월 10일
darkmatter
커뮤니티

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.

1시간 설치 수
2
GitHub Stars
1
업데이트
10월 10일