AI-agent support

Features

When your site 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: alternate links and a hidden in-body directive lead agents to each page’s Markdown version and to llms.txt.
• View Markdown: page meta area includes a View Markdown link to the Markdown version of the page.
• llms.txt: per-language site index of links to Markdown content.

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

Enable Markdown output

Hugo comes with several built-in output formats, including markdown. 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"]
  }
}

Opt pages 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]
---
...

Enable llms.txt

The llms.txt format is a simple text format for listing machine-readable links to site content. It is designed to be easy for agents to discover and parse, and to complement the richer but more complex Markdown outputs. To learn more, see llmstxt.org.

Docsy generates an llms.txt index at each language’s site root, and includes links to the home page, main menu pages, and Markdown alternates where they exist. To enable it, add LLMS to the Hugo outputs configuration for the home page. For example:

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

For an example of the generated llms.txt for this site, see /llms.txt.

Discovery

Agents find your Markdown content through:

• Alternate links: page HTML headers include rel="alternate" links to the Markdown version of the page.
• In-body directive: when llms.txt is enabled, each page body opens with a visually-hidden directive pointing agents to the language’s llms.txt index and, when the page has one, its Markdown version. Sites that override the theme’s baseof templates need to call the llms-directive.html partial themselves.

Customize output

Docsy renders Markdown output via layouts/all.md and generates llms.txt via layouts/index.llms.txt. You can override these defaults at several levels:

• Per kind — Add templates such as home.md or _default/single.md under layouts/ in your project to tailor Markdown output for specific Hugo kinds.
• Per shortcode — Add output-format-specific shortcode templates to project-local shortcodes so they render Markdown-friendly content when appropriate. For example, this site’s readfile.markdown.md is the Markdown-output variant of the theme’s readfile shortcode.
• Per page — Provide page-specific content or structure for high-value pages that need a curated agent-facing view.

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 score online report 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.