# AI visibility The theme ships defaults that help AI agents and LLM-based tools discover, fetch, and cite ScyllaDB documentation. ## What the theme provides At build time, the theme automatically generates: * An `llms.txt` index file at the project root, following the [llms.txt proposal](https://llmstxt.org). * An `llms-full.txt` file containing the full documentation concatenated into a single Markdown document. * A Markdown version of every page (`page.md` and `page.html.md`), so agents can request the content in plain Markdown instead of parsing HTML. In every HTML page rendered by the theme, the layout also injects: * A `` tag in `` pointing to the Markdown version of the page. * A visually hidden directive near the top of the content area pointing AI agents to `/llms.txt` and to the Markdown version of the current page. ## How it works The theme bundles [sphinx-llm](https://github.com/NVIDIA/sphinx-llm) and registers its `sphinx_llm.txt` extension automatically. No configuration is required in your project’s `conf.py`. ## Output layout For a single-version project, files are generated at the build root: ```default _build/dirhtml/ ├── llms.txt ├── llms-full.txt ├── index.html ├── index.md ├── index.html.md ├── getting-started.html ├── getting-started.md └── getting-started.html.md ``` For a multiversion project, each version gets its own set: ```default _build/dirhtml/ ├── stable/ │ ├── llms.txt │ ├── llms-full.txt │ └── ... └── master/ ├── llms.txt ├── llms-full.txt └── ... ``` ## Configuration options sphinx-llm exposes a options you can override in `conf.py` if needed: | Option | Type | Default Value | Description | |------------------------|--------|---------------------|-------------------------------------------------------------------------------------------------------------------------------------| | `llms_txt_enabled` | bool | true | Enables or disables the extension. | | `llms_txt_description` | string | Project description | Description shown at the top of `llms.txt`. | | `llms_txt_full_build` | bool | true | Whether to also generate the `llms-full.txt` concatenated file. | | `llms_txt_suffix_mode` | string | auto | Which Markdown filename pattern to generate. `auto` produces both `page.md` (URL-suffix) and `page.html.md` (file-suffix) variants. | See the [sphinx-llm documentation](https://github.com/NVIDIA/sphinx-llm#readme) for the full list. ## Caveats Some AI-readiness checks remain unsatisfied by design or by hosting constraints: * **Content negotiation** (`Accept: text/markdown`) — GitHub Pages and the Fastly CDN in front of it do not honor the `Accept` header. Serving Markdown when this header is present requires a CDN-level rule (Cloudflare Worker, Fastly VCL, or similar). * **Root meta-refresh redirect** — The `index.html` at the project root that redirects to the latest version is generated by this theme’s multiversion extension (see `sphinx_scylladb_theme/extensions/multiversion.py`). It is an intentional, per-project feature for multiversion sites. Agent-readiness audits will flag it as a JavaScript redirect, but the meta-refresh is the most portable option for static hosting (GitHub Pages) and is kept by design.