AI-agent support

Features

When your project opts in, these are the user-facing and machine-readable behaviors Docsy enables:

• Markdown output format support. Your project’s outputs configuration controls which page kinds publish Markdown.
• Discovery: how agents find Markdown versions and llms.txt.
• View Markdown: page meta area includes a View Markdown link to the Markdown version of the page.
• llms.txt: a per-site overview linking the site’s Markdown content.

The remainder of this page explains how to enable each feature, and discusses validation and metrics supported with examples.

Markdown output

Hugo comes with several built-in output formats, including markdown.

Docsy provides the markdown template that Hugo uses to output a Markdown version of a page, at index.md beside its index.html. The Markdown version includes:

• Page title and description
• A link to the site’s llms.txt, when the site publishes one
• Page content, with shortcodes expanded
• The list of child pages, if any

A shortcode without a Markdown variant emits its HTML there; for how to add one, see Shortcodes.

Enabling

To enable Markdown output, add markdown to the Hugo outputs configuration for the page kinds you want to support. For example:

• Configuration file:
• hugo.yaml
• hugo.toml
• hugo.json

outputs:
  home: [HTML, markdown]
  page: [HTML, markdown]
  section: [HTML, RSS, print, markdown]

[outputs]
home = [ "HTML", "markdown" ]
page = [ "HTML", "markdown" ]
section = [ "HTML", "RSS", "print", "markdown" ]

{
  "outputs": {
    "home": ["HTML", "markdown"],
    "page": ["HTML", "markdown"],
    "section": ["HTML", "RSS", "print", "markdown"]
  }
}

Opting out

To opt pages out of Markdown output, set outputs in page front matter to HTML only, or whatever your page’s default output formats are while excluding markdown. For example:

---
title: HTML-only test page
outputs: [HTML]
---
...

llms.txt files

An llms.txt file is a short overview (in Markdown) of the content under its URL path. Agents use it to discover the content rooted at that path. For details, see the llms.txt proposal.

Docsy defines an LLMS output format and a template that renders llms.txt, one per site. The file links to the following, each at the target’s Markdown version when available, otherwise its HTML version:

• A site index consisting of the following list:
  • site root
  • Main menu entries
• A documentation index consisting of the site’s top-level docs sections
• The project’s sites, by language, this one included

This organization is intended for rooted llms.txt files, not arbitrary sections.

Enabling

To enable llms.txt generation for every site root (a practice Docsy recommends), add LLMS to the Hugo home outputs configuration. For example:

outputs:
  home: [HTML, markdown, LLMS]
  page: [HTML, markdown]
  section: [HTML, RSS, print, markdown]

For this site’s llms.txt, see /fr/llms.txt.

Discovery

Agents find your Markdown content through:

• Alternate links: page heads include rel="alternate" links to the Markdown version of the page.
• describedby link: when the site publishes llms.txt, page heads include a rel="describedby" link to it, as the llms.txt proposal (v2) recommends. Projects that override the theme’s head.html partial need to add the link themselves.
• In-body directive: when the site publishes llms.txt, each page body opens with a visually-hidden directive pointing agents to it and, when the page has one, its Markdown version. Projects that override the theme’s baseof templates need to call the llms-directive.html partial themselves.

Customize output

Docsy’s templates for the two outputs are:

• layouts/all.md (Markdown output)
• layouts/all.llms.txt (llms.txt)

Both follow Hugo’s template lookup rules, so your project’s layouts/ overrides them. For llms.txt, override all.llms.txt, or add a template named for the site root page’s kind:

• home for regular sites: layouts/home.llms.txt (or index.llms.txt)
• section for doc-rooted sites: layouts/section.llms.txt for every section, or layouts/TYPE/section.llms.txt for sections of one type (docs, unless the page sets type)

Server-side support

While outside the scope of Docsy’s support, sites can facilitate agent discovery and access to Markdown content by implementing server-side content negotiation. For example, honoring Accept: text/markdown on the same URL as HTML.

Validation and metrics

We use AFDocs to assess basic structural support for agent-facing content, and to validate that generated outputs meet the configured checks. We also encourage sites to implement their own monitoring and metrics on agent access patterns—for example logging requests to Markdown URLs or llms.txt, and collecting metrics on their use. For details, see Agent-support checks.

The docsy.dev project contains AFDocs configuration and npm scripts so maintainers can score a deployed URL against checks that overlap with Docsy’s agent-support goals, including Markdown URLs, llms.txt, and related categories.

Scorecard examples

For scorecard examples, see the OpenTelemetry agent-readiness report on CLOMonitor (CLOMonitor runs AFDocs, one check per category; its llms-txt-coverage result reflects the curated-overview trade-off this site’s checks also make) and the AFDocs scorecard for this site:

Agent-Friendly Docs Scorecard
==============================

http://localhost:1313 · 8/25/2026, 4:17:55 PM

  Overall Score: 96 / 100 (A)

  Category Scores:
    Content Discoverability              100 / 100 (A+)
    Markdown Availability                 57 / 100 (F)
    Page Size and Truncation Risk        100 / 100 (A+)
    Content Structure                    100 / 100 (A+)
    URL Stability and Redirects          100 / 100 (A+)
    Observability and Content Health     100 / 100 (A+)
    Authentication and Access            100 / 100 (A+)

  Check Results:

    Content Discoverability
      PASS  llms-txt-exists                llms.txt found at http://localhost:1313/llms.txt
      PASS  llms-txt-valid                 llms.txt follows the proposed structure (H1, blockquote, heading-delimited link sections)
      PASS  llms-txt-size                  llms.txt is 1,129 characters (under 50,000 threshold)
      PASS  llms-txt-links-resolve         All 13 same-origin links resolve (13 total links)
      PASS  llms-txt-links-markdown        13/13 same-origin links point to markdown content (100%)
      PASS  llms-txt-directive-html        llms.txt directive found in HTML of all 50 sampled pages, near the top of content
      PASS  llms-txt-directive-md          llms.txt directive found in markdown of all 45 sampled pages, near the top of content; 5 had no markdown version

    Markdown Availability
      PASS  markdown-url-support           45/50 sampled pages support .md URLs (90%)
      FAIL  content-negotiation            Server ignores Accept: text/markdown header (0/50 sampled pages return markdown)
            Fix: Your server ignores Accept: text/markdown and returns HTML. Some agents (Claude Code, Cursor, OpenCode) request markdown this way. Configure your server to honor content negotiation.

    Page Size and Truncation Risk
      PASS  rendering-strategy             All 50 sampled pages contain server-rendered content
      PASS  page-size-markdown             All 45 pages under 50K chars (median 4K, max 47K)
      PASS  page-size-html                 All 50 sampled pages under 50K chars (median 54K HTML → 9K markdown (81% boilerplate))
      PASS  content-start-position         Content starts within first 10% on all 50 sampled pages (median 0%)

    Content Structure
      PASS  tabbed-content-serialization   8 tab group(s) across 7 of 50 sampled pages; all serialize under 50K chars
      SKIP  section-header-quality         7 page(s) with tabs found, but no section headers inside tab panels to evaluate
      PASS  markdown-code-fence-validity   All 157 code fences properly closed across 46 pages

    URL Stability and Redirects
      PASS  http-status-codes              All 50 sampled pages return proper error codes for bad URLs
      PASS  redirect-behavior              No redirects detected across 50 sampled pages

    Observability and Content Health
      PASS  cache-header-hygiene           All 51 endpoints have appropriate cache headers

    Authentication and Access
      PASS  auth-gate-detection            All 50 sampled pages are publicly accessible
      SKIP  auth-alternative-access        All docs pages are publicly accessible; no alternative access paths needed

Full spec: https://agentdocsspec.com/spec/

For details on how these checks are configured, see Agent-support checks.