Docsy moves to the Linux Foundation with experimental output built for AI agents

Docsy is a theme for the Hugo static site generator ^[3]. Each agent feature is extra output from the site build, and each one stays off until the site owner enables it ^[5]. Of these, the llms.txt index decides where an agent goes. "You can redirect your LLMs and agents to the text that tells them how to use the project," McKean said ^[6].

Since 0.17.0, a hidden directive at the top of every page points agents to that index ^[8]. Because it is hidden, clicking through the rendered site in a browser will not show it. It is in the generated HTML, where a diff between a 0.16.0 build and a 0.17.0 build will find it.

The features came out over three minor releases between May and August ^[15]. The one I would copy outside Docsy is the 0.16.0 upgrade guide. It was written so an AI assistant could follow it, with conditions, steps and checks built into the instructions ^[7]. I think a stated precondition and a check after each step help the person upgrading as much as the assistant. McKean made the same argument about audience. "When we're making technical documentation, it really doesn't matter how the information becomes useful to humans, as long as it does it," she said ^[12]. "If someone told me that there was evidence that said opera is the best way to reach your project users, I'd be writing operas." ^[12]

The New Stack's report does not include figures on how often agents fetch llms.txt or follow the page directive. The agent-friendly scores on the roadmap are the maintainers' answer to that gap ^[9]. "You won't have to guess," McKean said. "You can measure how agent friendly your docs are." ^[10]

The foundation move follows the existing user base. McKean's case is that Docsy is already used widely inside Linux Foundation communities ^[14]. Kubernetes, OpenTelemetry, gRPC and Jaeger are among the CNCF projects using it ^[4]. "Open source projects work best when they are close to the users," she said ^[11]. She also made the maintainer case: "When you have good docs, it reduces the number of questions that can be easily answered by documentation, reducing the burden on maintainers." ^[13]

For a project whose users lean on coding assistants, I would turn on the Markdown copy and llms.txt on a branch. Then I would edit the index by hand so it points at the pages that explain usage ^[5][6]. I would move to 0.17.0 only after someone has read the directive in the page source ^[8]. For a site with little agent traffic, the experimental label on the Markdown output, llms.txt and the directive is enough reason to wait ^[5][8].