add llms.txt and llms-full.txt for LLM agent consumption #12

New issue

Closed

opened 2026-05-26 01:00:42 +00:00 by coding-agent-marvin8 · 1 comment

coding-agent-marvin8 commented

2026-05-26 01:00:42 +00:00

(Migrated from codeberg.org)

LLM agents consuming this library have no machine-friendly entry point to the documentation. Adding two files addresses this:

llms.txt — a lightweight index (llmstxt.org standard) listing all doc pages with short descriptions, placed at the site root.
llms-full.txt — the complete documentation concatenated into a single plain-text file, generated at build time via a MkDocs hook.

Both are served at the root of the versioned docs site (e.g. /latest/llms.txt) so LLM tools can fetch the full context in one request rather than crawling individual pages.

LLM agents consuming this library have no machine-friendly entry point to the documentation. Adding two files addresses this: - `llms.txt` — a lightweight index (llmstxt.org standard) listing all doc pages with short descriptions, placed at the site root. - `llms-full.txt` — the complete documentation concatenated into a single plain-text file, generated at build time via a MkDocs hook. Both are served at the root of the versioned docs site (e.g. `/latest/llms.txt`) so LLM tools can fetch the full context in one request rather than crawling individual pages.

coding-agent-marvin8 commented

2026-05-26 01:01:21 +00:00

(Migrated from codeberg.org)

Exploration findings:

docs_hooks.py has one hook (on_config) that updates the copyright year — good pattern to follow for on_post_build.
MkDocs nav is flat (no nested sections), so _flatten_nav just needs to extract values from the list of single-key dicts.
.txt files in docs/ are copied as-is to site_dir by MkDocs (no processing), so llms.txt can live there as a static file.
Mike deploys everything in site_dir to the versioned path, so both files will land at .../latest/llms.txt and .../latest/llms-full.txt automatically.

Plan of attack:

Write failing test in tests/test_docs_hooks.py (TDD RED): mock config with temp dirs, call on_post_build, assert llms-full.txt is generated in correct order.
Add static docs/llms.txt (hand-written, llmstxt.org format, links use latest alias).
Extend docs_hooks.py with on_post_build + private _flatten_nav helper that extracts file paths from the nav list.
Verify GREEN, pass ruff/ty/nox, then commit and open PR.

**Exploration findings:** - `docs_hooks.py` has one hook (`on_config`) that updates the copyright year — good pattern to follow for `on_post_build`. - MkDocs nav is flat (no nested sections), so `_flatten_nav` just needs to extract values from the list of single-key dicts. - `.txt` files in `docs/` are copied as-is to `site_dir` by MkDocs (no processing), so `llms.txt` can live there as a static file. - Mike deploys everything in `site_dir` to the versioned path, so both files will land at `.../latest/llms.txt` and `.../latest/llms-full.txt` automatically. **Plan of attack:** 1. Write failing test in `tests/test_docs_hooks.py` (TDD RED): mock config with temp dirs, call `on_post_build`, assert `llms-full.txt` is generated in correct order. 2. Add static `docs/llms.txt` (hand-written, llmstxt.org format, links use `latest` alias). 3. Extend `docs_hooks.py` with `on_post_build` + private `_flatten_nav` helper that extracts file paths from the nav list. 4. Verify GREEN, pass ruff/ty/nox, then commit and open PR.