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.
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 <link rel="alternate" type="text/markdown"> tag in <head> 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 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:

_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:

_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 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.

Was this page helpful?