[jdx]

Summary

• generate docs/public/llms.txt from the VitePress sidebar and page introductions
• share the sidebar between VitePress and the generator
• integrate generation with mise run render and publish it through the existing docs build

Implements the request in Discussion #1271.

Testing

• mise run render (run twice; second run produced no diff)
• mise run docs:build
• verified docs/.vitepress/dist/llms.txt matches docs/public/llms.txt
• PATH="$PWD/target/debug:$PATH" mise x shellcheck@0.11.0 -- target/debug/hk check --all

AI-assisted — Tool: Codex; model: openai/gpt-5; version: unavailable.

---

Note

Low Risk
Docs-only tooling and static asset generation; no runtime or security-sensitive code paths.

Overview
Adds a machine-readable llms.txt index at https://hk.jdx.dev/llms.txt so coding agents can discover hk docs with short blurbs per page.

Sidebar is moved from config.mts into shared sidebar.ts (still driven by commands.json for CLI pages). VitePress imports that module; a new llms.ts script walks the same tree, maps links to Markdown, pulls the first prose paragraph after each H1 (with stripping/truncation), and writes docs/public/llms.txt. Generation is wired as mise run render:llms (depends on render:usage) so it runs with the rest of render; the committed file ships via VitePress public/. docs/package.json sets "type": "module" for the JSON import attribute in sidebar.ts.

^{Reviewed by Cursor Bugbot for commit 511f51c. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• New Features

  • Added a plain-text llms.txt documentation index covering guides, configuration, CLI commands, reference material, and project documentation.
  • Added automatic generation of the index with organized sections, page links, and descriptions.
  • Updated the documentation sidebar to dynamically include available CLI commands while excluding hidden subcommands.

• Chores

  • Configured the documentation package for modern module support.
  • Added a task for regenerating the documentation index.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 162bb3bc-7f48-4ccb-9fa1-26d1e7108510

📥 Commits

Reviewing files that changed from the base of the PR and between 69b18f0 and 511f51c.

📒 Files selected for processing (3)

• docs/.vitepress/llms.ts
• docs/.vitepress/sidebar.ts
• docs/public/llms.txt

🚧 Files skipped from review as they are similar to previous changes (2)

• docs/.vitepress/sidebar.ts
• docs/public/llms.txt

Included review availability: Your plan provides up to 4 included reviews per hour; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

Changes

The VitePress sidebar now lives in a separate module. A generator creates docs/public/llms.txt from sidebar links and page descriptions. A mise task runs the generator, and the docs package uses ES modules.

Documentation index

Layer / File(s)	Summary
Sidebar modularization docs/.vitepress/sidebar.ts, docs/.vitepress/config.mts	The CLI-aware sidebar moves to sidebar.ts. VitePress imports and uses the exported sidebar.
llms.txt generator docs/.vitepress/llms.ts, docs/package.json	The generator flattens sidebar links, extracts and cleans lead descriptions, groups links, and writes llms.txt. The docs package is marked as an ES module.
Generation task and checked-in index mise-tasks/render/llms, docs/public/llms.txt	The mise task invokes the generator. The checked-in index contains Getting Started, Configuration, Guides, CLI Reference, Reference, and Project sections.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 511f5

This localized documentation change generates and publishes an llms.txt index while sharing the existing sidebar configuration; no actionable merge-blocking risk remains after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant Sidebar
  participant LLMGenerator
  participant DocumentationSources
  participant LLMIndex
  Sidebar->>LLMGenerator: Provide linked sidebar pages
  LLMGenerator->>DocumentationSources: Read page sources
  DocumentationSources-->>LLMGenerator: Return lead descriptions
  LLMGenerator->>LLMIndex: Write grouped documentation links

Loading

Poem

A rabbit sees the sidebar split,
Commands hop into ordered rows.
Page summaries fill the index,
A mise task starts the flow.
llms.txt grows ears and goes.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: generating and publishing the docs/public/llms.txt index.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 3 files. (1 skipped: 1 …
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 3 files. (1 skipped: 1 unsupported.)

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

The PR adds a generated llms.txt documentation index and shares sidebar metadata between VitePress and the generator.

• Extracts the VitePress sidebar into a reusable module.
• Generates page links and introductory summaries in docs/public/llms.txt.
• Integrates generation into the repository’s render task graph.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
docs/.vitepress/llms.ts	Adds the generator that converts shared sidebar entries and Markdown introductions into the published documentation index.
docs/.vitepress/sidebar.ts	Extracts the existing navigation structure and generated CLI command links into a shared typed module.
docs/.vitepress/config.mts	Replaces the inline sidebar definition with the shared sidebar import.
mise-tasks/render/llms	Adds an incremental render task ordered after CLI usage documentation generation.
docs/package.json	Marks the documentation package as ESM for the new generator modules.
docs/public/llms.txt	Adds the generated public index covering the documentation sidebar pages.

_{Reviews (2): Last reviewed commit: "fix(docs): preserve CLI placeholders in ..." | Re-trigger Greptile}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 69b18f0. Configure here.}

Dismissed because a newer commit was pushed; Greptile will re-review the current head.

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
builtins	▅▄▅▃▃▄▂▆▁▂▂▄▄▅▇▇█	1,989,871 → 1,990,767	+0.05%	2.92 → 3.14ms	+7.50%
check	—	—	—	21.50 → 21.30ms	-0.94%
usage	▆▆▆▄▄▆▂█▁▁▁▅▅▅███	4,650,086 → 4,650,350	+0.01%	3.16 → 3.31ms	+4.72%
validate	—	—	—	5.48 → 5.44ms	-0.62%

No instruction-count regression above 1%.

_{Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.}

_{Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.}

_{511f51c2e877 vs a15fcdfb197f · measured on the runner, not pushed to the history.}