Skip to content

Add llms.txt to documentation site #397

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Circadian-agent wants to merge 2 commits into from
Closed

Add llms.txt to documentation site #397

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2e91fdb
Add llms.txt to docs site, document it in AGENTS.md
Circadian-agent Aug 6, 2026
8e2c1b8
I, Circadian <ops@circadian-agent.com>, hereby add my Signed-off-by t…
Circadian-agent Aug 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -862,6 +862,11 @@ The docs site is built with [Starlight](https://starlight.astro.build/) (Astro).
- **Do not use frontmatter `sidebar.label` or `sidebar.order` to control group/section headings.** Frontmatter only controls individual page labels, not the group name shown in the sidebar for a directory. Use explicit `items` with `label` in `astro.config.mjs` instead (see "Send Data" and "Get Started" sections as examples).
- Sections using `autogenerate` derive group labels from directory names (lowercase). Replace `autogenerate` with explicit `items` when proper casing or custom ordering is needed.

**llms.txt:**
- `docs/public/llms.txt` is a maintained artifact, served at the site root (`https://observability.opensearch.org/llms.txt`). It lists every docs page with a one-line description, for AI assistants and other automated readers.
- It is generated, not hand-written. Regenerate it whenever a page is added, removed, or renamed, or a page's `title`/`description` frontmatter changes. Do not hand-edit `docs/public/llms.txt` directly.
- The generator config lives in `docs/starlight-docs/llms-txt/`. All links in the file are fully qualified `https://observability.opensearch.org/...` URLs, not relative paths, because the file is read out of page context.

### Icons

Use OpenSearch UI (OUI) icons for documentation components. Browse the full set at https://oui.opensearch.org/1.23/#/display/icons. SVG sources are at https://github.com/opensearch-project/oui/tree/main/src/components/icon/assets. Prefer 32x32 icons over 16x16 for consistent sizing.
Expand Down
9 changes: 9 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -391,6 +391,15 @@ AI coding assistants are welcome to contribute! When contributing as an AI agent
- Include configuration patterns
- Keep AI-assistant focused

### llms.txt

`docs/public/llms.txt` is a first-class doc artifact, on the same footing as README.md and AGENTS.md. It lists every page in the docs site with a one-line description, served at the site root for AI assistants and other automated readers.

Update it whenever you change something it reflects: adding, removing, or renaming a docs page, or changing a page's `title` or `description` frontmatter.

- Do not hand-edit `docs/public/llms.txt`. It is generated; regenerate it instead using the config in `docs/starlight-docs/llms-txt/`.
- After regenerating, check that every link is a fully qualified `https://observability.opensearch.org/...` URL, not a relative `/docs/...` path, and that the title and tagline lines at the top are unchanged.

### Code Comments

- Explain *why*, not just *what*
Expand Down
Loading