27 lines
2.1 KiB
Markdown
27 lines
2.1 KiB
Markdown
# LLM documentation
|
|
|
|
A running instance serves its own documentation for language models, versioned with the binary:
|
|
|
|
| URL | Content |
|
|
| --- | --- |
|
|
| `/llms.txt` | Short index with links, following llmstxt.org. |
|
|
| `/llms-full.txt` | Every page below in one file. |
|
|
| `/llms/<page>.md` | One page: `api-reference`, `api`, `articles`, `api-keys`, `gotchas`, `recipe-articles`, `recipe-media`, `recipe-sites`, `recipe-pagination`, `configuration`. |
|
|
| `/openapi.json` | OpenAPI 3.1 description of the routes in the catalogue. |
|
|
|
|
All of them are public. `{{VERSION}}` and `{{BASE_URL}}` in the sources are replaced by the binary's version and `PUBLIC_URL` when served.
|
|
|
|
## How it is built
|
|
|
|
`task build:llms` runs `scripts/generate-llms.ts` (bun) and writes into `internal/infrastructure/llmdocs/generated/`, which is gitignored and embedded in the binary. `task build`, `task release`, `task dev:api` and the Docker image run it first. Without it the routes answer 404 with a notice.
|
|
|
|
- The API reference and `openapi.json` come from `web/src/data/apiCatalogue.ts`, the same file the Integration page renders. Edit the catalogue, not the output.
|
|
- `docs/api.md`, `docs/api/*.md`, the variables table of `docs/configuration.md` and every `docs/llm/*.md` are included as written. A page in `docs/llm/` starts with `# Title`, then a `> one-line summary` used by `llms.txt`.
|
|
- Recipes in `docs/llm/` hold real responses. Re-capture them when a response shape changes.
|
|
|
|
`TestRouterRoutesAreInTheCatalogue` fails when a route of `api/router.go` is missing from the catalogue. Routes still undocumented are listed in `routesNotYetInTheCatalogue` in `test/api_catalogue_drift_test.go`; remove an entry once the route is documented.
|
|
|
|
## Languages in the generated output
|
|
|
|
The article object carries `lang` and `story_id`, and the public language routes `GET /v1/public/site/{key}/lang/{lang}/article/{slug}` and `GET /v1/public/site/{key}/story/{story_id}` return `alternates` and, for the second, `requested_lang` and `fallback`. They are described in `docs/api/article-localization.md`, in the catalogue and in the recipes, so `/llms-full.txt` and `/openapi.json` include them after `task build:llms`.
|