stable URL: /l/doc-agent-support

Agent-Friendly Documentation

How AI agents and LLMs can discover and consume the Project Hummingbird documentation site.

The documentation site provides several features that make it easier for AI agents and LLMs to discover, index, and consume its content.

Discovery and access methods

llms.txt

The site publishes an llms.txt file at the root, following the llmstxt.org specification. This file is a Markdown-formatted index of all documentation pages, grouped by section, with links to each page’s markdown URL. It serves as the primary entry point for agents discovering the site.

llms-full.txt

The site also publishes llms-full.txt – a full content dump of all documentation pages in a single file. This is intended for LLMs with large context windows that want to ingest the entire site in a single request without crawling individual pages.

Pages whose rendered content exceeds a size threshold (currently 50,000 characters) are replaced with a placeholder that includes the page title, description, and a link to the individual page’s markdown URL for on-demand fetching. This keeps the file at a manageable size while ensuring no content is completely inaccessible.

Per-page markdown output

Every page on the site is available in clean markdown format by appending /index.md to its URL. For example:

  • HTML: https://hummingbird-project.io/docs/contributing/quickstart/
  • Markdown: https://hummingbird-project.io/docs/contributing/quickstart/index.md

The markdown output resolves all shortcodes (such as file includes from other repositories) while preserving the content as markdown rather than converting to HTML. Each markdown page includes links to both llms.txt and llms-full.txt so agents can discover the site-wide indexes from any page.

Content negotiation

A CloudFront distribution sits between DNS and the site’s page host. A viewer-request CloudFront Function inspects the Accept header on every request: when the header includes text/markdown, the function rewrites the URI to serve the pre-built .md equivalent. Only HTML-like patterns (trailing slash, .html, bare paths) are rewritten; all other URIs pass through unchanged.

This means agents can use standard HTTP content negotiation on any page URL without needing to know the /index.md convention:

GET /docs/contributing/quickstart/ HTTP/1.1
Accept: text/markdown

Pages referenced from external sources have stable short URLs under the /l/ prefix (e.g., /l/adding-images). These return HTTP 301 to the canonical page URL, so pages can move without breaking incoming links. The Writing Documentation guide describes how to add aliases.

The CloudFront viewer-request function recognizes /l/ paths and normalizes them before they reach the origin. Content negotiation (Accept header) is skipped for /l/ paths — instead, the URL form determines the response: /l/foo and /l/foo/ redirect to the HTML page, while /l/foo.md and /l/foo/index.md redirect to the markdown file. If no matching alias exists, the origin returns a 404.

Specifications and tools

The site aims to follow the emerging standards for agent-friendly documentation:

  • llmstxt.org – the llms.txt specification
  • Agent-Friendly Documentation Spec – broader specification for documentation sites that serve AI agents
  • AFDocs – scoring tool that evaluates a site’s compliance with the Agent-Friendly Documentation Spec

Planned features

HTML llms-directive (HUM-6571)

A Docsy upgrade to v0.17.0 will embed a pointer to llms.txt inside the HTML <body> of every page, so agents landing on any HTML page can discover the LLMS index without prior knowledge of the site structure.

Documentation quality evaluation (HUM-6575)

A promptfoo-based evaluation harness will measure how accurately LLMs can answer questions about Hummingbird using the published documentation. This provides a feedback loop for identifying documentation pages that need improvement for agent consumption.