Add LLMS output and llms.txt support, enables it over docsy.dev (#2605)

Author: chalin

.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.