Add LLMS output and llms.txt support, enables it over docsy.dev

.vscode/cspell.json

@@ -28,6 +28,7 @@
     "hugo",
     "isset",
     "lastmod",
+    "llms",
     "markdownify",
     "mentees",
     "navbars",

docsy.dev/agent-docs.config.yml

@@ -0,0 +1,50 @@
+# Agent-Friendly Docs — https://afdocs.dev/reference/config-file.html
+
+url: https://www.docsy.dev # Site to check. CLI flag overrides this
+
+checks:
+  # --- Content Discoverability ---
+  - llms-txt-exists
+  - llms-txt-valid
+  - llms-txt-size
+  - llms-txt-links-resolve
+  - llms-txt-links-markdown
+  - llms-txt-directive
+
+  # --- Markdown Availability ---
+  - markdown-url-support
+  - content-negotiation
+
+  # --- Page Size and Truncation Risk ---
+  - rendering-strategy
+  - page-size-markdown
+  - page-size-html
+  # - content-start-position
+
+  # --- Content Structure ---
+  - tabbed-content-serialization
+  - section-header-quality
+  - markdown-code-fence-validity
+
+  # --- URL Stability and Redirects ---
+  - http-status-codes
+  - redirect-behavior
+
+  # --- Observability and Content Health ---
+  # - llms-txt-freshness
+  # - markdown-content-parity
+  - cache-header-hygiene
+
+  # --- Authentication and Access ---
+  - auth-gate-detection
+  - auth-alternative-access
+
+# options:
+#   maxLinksToTest: 50
+#   samplingStrategy: random # random | deterministic | none
+#   maxConcurrency: 3
+#   requestDelay: 200
+#   requestTimeout: 30000
+#   thresholds:
+#     pass: 50000
+#     fail: 100000

docsy.dev/config/_default/hugo.yaml

@@ -12,7 +12,7 @@ ignoreLogs:
   - warning-frontmatter-params-overrides # cSpell:disable-line
 
 outputs:
-  home: [HTML, markdown]
+  home: [HTML, markdown, LLMS]
   page: [HTML, markdown]
   section: [HTML, RSS, print, markdown]
 

docsy.dev/content/fr/_index.md

@@ -5,6 +5,7 @@ description: >-
 params:
   body_class: td-navbar-links-all-active
   ui: { navbar_theme: dark }
+outputs: [HTML, markdown]
 ---
 
 {{% blocks/cover

docsy.dev/package.json

@@ -4,6 +4,7 @@
   "private": true,
   "scripts": {
     "_build": "npm run _hugo-dev --",
+    "_check:afdocs": "npx afdocs check --config agent-docs.config.yml --format scorecard",
     "_check:format": "npx prettier --config ../.prettierrc.json --check .",
     "_check:links--warn": "npm run _check:links || (echo; echo 'WARNING: see link-checker output for issues.'; echo)",
     "_check:links": "make --keep-going check-links",
@@ -39,6 +40,7 @@
     "update:packages": "npx npm-check-updates -u"
   },
   "devDependencies": {
+    "afdocs": "^0.9.2",
     "autoprefixer": "^10.4.27",
     "cross-env": "^10.1.0",
     "hugo-extended": "0.157.0",
@@ -47,5 +49,5 @@
     "postcss-cli": "^11.0.1",
     "rtlcss": "^4.3.0"
   },
-  "cSpell:ignore": "- docsy htmltest postbuild precheck refcache rtlcss -"
+  "cSpell:ignore": "- afdocs docsy htmltest postbuild precheck refcache rtlcss -"
 }

docsy.dev/tests/md-output/golden.test.mjs

@@ -8,14 +8,21 @@ const goldenDir = fileURLToPath(new URL('./goldens/', import.meta.url));
 const publicDir = fileURLToPath(new URL('../../public/', import.meta.url));
 
 // `kind` is descriptive only (for readable test names); it doesn't affect test logic.
+// `skip: true` omits the assertion (manifest entry is kept for docs / update-goldens).
 const manifest = JSON.parse(
   readFileSync(new URL('./goldens.json', import.meta.url), 'utf8'),
 );
 
-for (const { path, kind, covers } of manifest) {
-  test(`${path} (${kind}) — ${covers.join(', ')}`, () => {
+for (const { path, kind, covers, skip } of manifest) {
+  const name = `${path} (${kind}) — ${covers.join(', ')}`;
+  const run = () => {
     const expected = readFileSync(join(goldenDir, path), 'utf8');
     const actual = readFileSync(join(publicDir, path), 'utf8');
     assert.equal(actual, expected);
-  });
+  };
+  if (skip) {
+    test.skip(name, run);
+  } else {
+    test(name, run);
+  }
 }

docsy.dev/tests/md-output/goldens.json

@@ -1,37 +1,50 @@
 [
+  {
+    "path": "llms.txt",
+    "kind": "home output",
+    "covers": [],
+    "skip": false
+  },
   {
     "path": "index.md",
     "kind": "home",
-    "covers": ["description", "body", "children"]
+    "covers": ["description", "body", "children"],
+    "skip": false
   },
   {
     "path": "blog/index.md",
     "kind": "section",
-    "covers": ["!description", "!body", "children"]
+    "covers": ["!description", "!body", "children"],
+    "skip": false
   },
   {
     "path": "docs/index.md",
     "kind": "section",
-    "covers": ["!description", "body", "children"]
+    "covers": ["!description", "body", "children"],
+    "skip": false
   },
   {
     "path": "docs/content/index.md",
     "kind": "section",
-    "covers": ["description", "!body", "children"]
+    "covers": ["description", "!body", "children"],
+    "skip": false
   },
   {
     "path": "docs/get-started/index.md",
     "kind": "section",
-    "covers": ["description", "body", "children"]
+    "covers": ["description", "body", "children"],
+    "skip": false
   },
   {
     "path": "blog/2022/hello/index.md",
     "kind": "page",
-    "covers": ["description", "body", "!children"]
+    "covers": ["description", "body", "!children"],
+    "skip": false
   },
   {
     "path": "fr/index.md",
     "kind": "home",
-    "covers": ["description", "body", "children", "i18n:fr"]
+    "covers": ["description", "body", "children", "i18n:fr"],
+    "skip": false
   }
 ]

docsy.dev/tests/md-output/goldens/blog/2022/hello/index.md

@@ -4,6 +4,10 @@
 
 ---
 
+LLMS index: [llms.txt](/llms.txt)
+
+---
+
 ## Hello
 
 It may seem strange to see a "Hello" post from a project that's several years

docsy.dev/tests/md-output/goldens/blog/index.md

@@ -1,5 +1,9 @@
 # Blog
 
+LLMS index: [llms.txt](/llms.txt)
+
+---
+
 Section pages:
 
 - [Release 0.14.0 report and upgrade guide](/blog/2026/0.14.0/)

docsy.dev/tests/md-output/goldens/docs/content/index.md

@@ -4,6 +4,10 @@
 
 ---
 
+LLMS index: [llms.txt](/llms.txt)
+
+---
+
 Section pages:
 
 - [Adding Content](/docs/content/adding-content/): Add different types of content to your Docsy site.

docsy.dev/tests/md-output/goldens/docs/get-started/index.md

@@ -4,6 +4,10 @@
 
 ---
 
+LLMS index: [llms.txt](/llms.txt)
+
+---
+
 As you saw in our introduction, Docsy is a [Hugo](https://gohugo.io) theme,
 which means that if you want to use Docsy, you need to set up your website
 source so that the Hugo static site generator can find and use the Docsy theme

docsy.dev/tests/md-output/goldens/docs/index.md

@@ -1,5 +1,9 @@
 # Welcome to Docsy
 
+LLMS index: [llms.txt](/llms.txt)
+
+---
+
 <!-- markdownlint-disable-next-line no-space-in-links -->
 
 <span class="badge bg-primary text-bg-primary fs-6">v0.14.4-dev

docsy.dev/tests/md-output/goldens/fr/index.md

@@ -4,6 +4,10 @@
 
 ---
 
+LLMS index: [llms.txt](/llms.txt)
+
+---
+
 <link rel="preload" as="image" href="/background-pexels-quang-nguyen-vinh-222549-2131841_hu_cc01584da1b14539.jpg" media="(max-width: 1200px)">
 <link rel="preload" as="image" href="/background-pexels-quang-nguyen-vinh-222549-2131841_hu_b69ccedf938815cf.jpg" media="(min-width: 1200px)">
 <style>

docsy.dev/tests/md-output/goldens/index.md

@@ -4,6 +4,10 @@
 
 ---
 
+LLMS index: [llms.txt](/llms.txt)
+
+---
+
 <link rel="preload" as="image" href="/background-pexels-quang-nguyen-vinh-222549-2131841_hu_cc01584da1b14539.jpg" media="(max-width: 1200px)">
 <link rel="preload" as="image" href="/background-pexels-quang-nguyen-vinh-222549-2131841_hu_b69ccedf938815cf.jpg" media="(min-width: 1200px)">
 <style>

docsy.dev/tests/md-output/goldens/llms.txt

@@ -0,0 +1,26 @@
+# Docsy
+
+> A Hugo theme for creating great technical documentation sites
+
+## Site index
+
+- [Home page](http://localhost/index.md)
+- [AGENTS.md](http://localhost/project/repo/agents/index.md)
+- [About](http://localhost/about/index.md): Docsy is a pre-configured Hugo theme that provides the core features and behaviors needed to create a technical documentation site
+- [Docs](http://localhost/docs/index.md)
+- [Examples](http://localhost/examples/index.md): Get started with a template or explore some Docsy-based sites
+- [Community](http://localhost/community/index.md)
+- [Blog](http://localhost/blog/index.md)
+
+## Documentation index
+
+- [Get started](http://localhost/docs/get-started/index.md)
+- [Content and Customization](http://localhost/docs/content/index.md)
+- [Deployment and previews](http://localhost/docs/deployment/index.md)
+- [Update Docsy](http://localhost/docs/updating/index.md)
+- [Best Practices](http://localhost/docs/best-practices/index.md)
+
+## Site locales
+
+- [English](http://localhost/index.md)
+- [Français](http://localhost/fr/index.md)

hugo.yaml

@@ -8,6 +8,11 @@ params:
   rss_sections: [blog]
 
 outputFormats:
+  LLMS:
+    baseName: llms
+    isPlainText: true
+    mediaType: text/plain
+    notAlternative: true
   print:
     baseName: index
     # FIXME: leave isHTML unset (i.e. false) until we get a Hugo fix for

layouts/all.md

@@ -1,5 +1,17 @@
+{{/*
+
+Template design:
+
+- This file generates a title followed by zero or more sections.
+- The title, and each section, are designed under the assumption that it is the
+  last page element, and so does not add extra trailing newlines.
+- Each section, other than the first, shall introduce a separator line.
+
+*/ -}}
+
 # {{ .Title | strings.TrimSpace -}}
 
+{{ $includeLlmsIndex := true -}}
 {{ $needSeparator := false -}}
 
 {{/* Description ------------------------------------------------------- */ -}}
@@ -10,22 +22,37 @@
 {{ $needSeparator = true -}}
 {{ end -}}
 
+{{/* Site index -------------------------------------------------------- */ -}}
+
+{{ if $includeLlmsIndex }}
+{{ if $needSeparator }}
+---
+
+{{ else }}
+{{ end -}}
+
+{{ $llmsTxt := "llms.txt" -}}
+LLMS index: [ {{- $llmsTxt -}} ]( {{- $llmsTxt | relURL -}} )
+{{ $needSeparator = true -}}
+{{ end -}}
+
 {{/* Page content ------------------------------------------------------ */ -}}
 
-{{ with .RenderShortcodes | strings.TrimSpace }}
+{{ with .RenderShortcodes | strings.TrimSpace -}}
 {{ if $needSeparator }}
 ---
 
 {{ else }}
 {{ end -}}
 
-{{ . -}}
+{{ . }}
 {{ $needSeparator = true -}}
 {{ end -}}
 
 {{/* Section index, if any --------------------------------------------- */ -}}
 
-{{ with .Pages }}
+{{ with .Pages -}}
+
 {{ if $needSeparator }}
 ---
 
@@ -41,5 +68,4 @@ Section pages:
   {{ end }}
 {{ end -}}
 
-{{ else }}
 {{ end -}}

layouts/blog/baseof.html

@@ -13,7 +13,15 @@
       {{ partial "navbar.html" . }}
     </header>
     <div class="container-fluid td-outer">
-      <div class="td-main" {{- partialCached "td/scrollspy-attr.txt" . .Section | safeHTMLAttr }}>
+      {{/*
+        <!--
+        There a bug that causes Hugo to escape the scrollspy attributes.
+        FIXME: Hard coding the scrollspy attributes for now.
+         -->
+        <div class="td-main" {{- partialCached "td/scrollspy-attr.txt" . .Section | safeHTMLAttr }}>
+      */ -}}
+      {{ $attr := ` data-bs-spy="scroll" data-bs-target=".td-toc" data-bs-root-margin="0px 0px -10%"` -}}
+      <div class="td-main" {{- $attr | safeHTMLAttr }}>
         <div class="row flex-xl-nowrap">
           <aside class="col-12 col-md-3 col-xl-2 td-sidebar d-print-none">
             {{ partial "sidebar.html" . }}

layouts/docs/baseof.html

@@ -13,7 +13,15 @@
       {{ partial "navbar.html" . }}
     </header>
     <div class="container-fluid td-outer">
-      <div class="td-main" {{- partialCached "td/scrollspy-attr.txt" . .Section | safeHTMLAttr }}>
+      {{/*
+        <!--
+        There a bug that causes Hugo to escape the scrollspy attributes.
+        FIXME: Hard coding the scrollspy attributes for now.
+         -->
+        <div class="td-main" {{- partialCached "td/scrollspy-attr.txt" . .Section | safeHTMLAttr }}>
+      */ -}}
+      {{ $attr := ` data-bs-spy="scroll" data-bs-target=".td-toc" data-bs-root-margin="0px 0px -10%"` -}}
+      <div class="td-main" {{- $attr | safeHTMLAttr }}>
         <div class="row flex-xl-nowrap">
           <aside class="col-12 col-md-3 col-xl-2 td-sidebar d-print-none">
             {{ partial "sidebar.html" . }}