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: page HTML headers include rel="alternate" links to the Markdown version of the page.
• View Markdown: page meta area includes a View Markdown link to the Markdown version of the page.
• llms.txt: site-root file listing.

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 llms.txt at the 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.

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 emit Markdown-friendly content when appropriate.
• 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:

• OpenTelemetry agent score online report

• An AFDocs scorecard for this site:

  docsy.dev scorecard

  Running in docsy.dev…
    
  Agent-Friendly Docs Scorecard
    
  http://localhost:1313 · 4/26/2026, 5:43:59 AM
    
  Overall Score: 100 / 100 (A+)
    
  Category Scores:
    Content Discoverability              100 / 100 (A+)
    Markdown Availability                100 / 100 (A+)
    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 1 location(s)
      PASS  llms-txt-valid                 llms.txt follows the proposed structure (H1, blockquote, heading-delimited link sections)
      PASS  llms-txt-size                  llms.txt is 1,131 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             llms.txt directive found in all 13 pages, near the top of content
    
    Markdown Availability
      PASS  markdown-url-support           13/13 pages support .md URLs (100%)
      PASS  content-negotiation            13/13 pages support content negotiation (100%)
    
    Page Size and Truncation Risk
      PASS  rendering-strategy             All 13 pages contain server-rendered content
      PASS  page-size-markdown             All 13 pages under 50K chars (median 2K, max 9K)
      PASS  page-size-html                 All 13 pages convert under 50K chars (median 2K, 0% boilerplate)
    
    Content Structure
      PASS  tabbed-content-serialization   No tabbed content detected across 13 pages
      PASS  section-header-quality         No tabbed content found; header quality check not applicable
      PASS  markdown-code-fence-validity   All 1 code fences properly closed across 14 pages
    
    URL Stability and Redirects
      PASS  http-status-codes              All 13 pages return proper error codes for bad URLs
      PASS  redirect-behavior              No redirects detected across 13 pages
    
    Observability and Content Health
      PASS  cache-header-hygiene           All 14 endpoints have appropriate cache headers
    
    Authentication and Access
      PASS  auth-gate-detection            All 13 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.