Skip to content

Add an agent-facing llms.txt directive to page HTML - #2741

Merged
chalin merged 9 commits into
google:mainfrom
chalin:chalin-m24-llms-directive-2026-0825
Aug 26, 2026
Merged

Add an agent-facing llms.txt directive to page HTML#2741
chalin merged 9 commits into
google:mainfrom
chalin:chalin-m24-llms-directive-2026-0825

Conversation

@chalin

@chalin chalin commented Aug 25, 2026

Copy link
Copy Markdown
Collaborator
  • Contributes to Improve support for AI-agent doc consumption #2614 (phase 2 opener).
  • Emits a hidden llms.txt directive at the top of every page body, the primary discovery mechanism agents use to find a site's Markdown path (afdocs: the directive reaches all agents, unlike content negotiation).
  • Free for every Docsy site: gated on the site already publishing llms.txt (the LLMS output format), no new configuration; non-opted sites render byte-identically. Sites overriding the theme's baseof templates must call the new partial themselves (documented on the agent-support page).
  • docsy.dev adoption: drops the fr home's stale outputs override (it masked the site config's LLMS output, so fr pages emitted no directive) and refreshes the published scorecard: 88 (B) -> 96 (A). Two causes: the directive check passes on all sampled pages, and content-start-position flips to PASS because the checker counts the directive itself as first content; the underlying nav-before-content DOM order is unchanged and stays tracked under Improve support for AI-agent doc consumption #2614.
  • Preview:

chalin added 8 commits August 25, 2026 16:20
- Gated on the site publishing llms.txt (LLMS output format on the
  current language's home page), so sites that don't opt in are
  byte-identical
- Hidden from visual and assistive presentation (visually-hidden +
  aria-hidden, no focusable content); agents converting HTML to text
  read it ahead of any navigation
- Fixture tests pin both gate sides, position, and the per-page
  Markdown pointer (verified red-first with the partial unwired)
- The fr home's front-matter outputs override lacked LLMS, so fr pages
  had no index for the new directive to point at
- Scorecard: 88 (B) -> 96 (A); the directive check passes on all
  sampled pages and the markdown-undiscoverable diagnostic clears
- Adversarial-review round: assertions now pin the hidden div's markup
  (a11y attributes) and cover the blog baseof; docs note that custom
  baseof overrides must call the partial, and the Markdown pointer line
  is per-page conditional
- data-pagefind-ignore keeps the hidden text out of consumer-site search
  indexes (Pagefind indexes the whole body by default and honors
  neither aria-hidden nor visually-hidden); inert for sites without it
- Tests: an HTML-only fixture page pins the conditional Markdown
  pointer the docs describe
The override's only effect was to lag the site config's home outputs
(how fr lost LLMS in the first place); removing it lets the base config
apply and prevents the next drift.
- The Discovery bullet had outgrown the Features list; Features now
  links it like the other feature sections
- llms.txt is a per-language index (e.g. /fr/llms.txt), not one
  site-root file
- Per-shortcode customization links this site's readfile.markdown.md as
  a worked example
@chalin
chalin marked this pull request as ready for review August 26, 2026 00:37
@chalin chalin added this to the 0.17.0 milestone Aug 26, 2026
@chalin
chalin merged commit c5cc2c2 into google:main Aug 26, 2026
18 checks passed
@chalin
chalin deleted the chalin-m24-llms-directive-2026-0825 branch August 26, 2026 00:44
chalin added a commit to chalin/docsy that referenced this pull request Aug 27, 2026
… nav-page anchor

- Release post: new NEW section for the in-body agent directive, Release-summary
  line, skim-list entry, and sanity-check item; applies-if action for sites
  overriding baseof templates, delegating details to the agent-support docs.
- Changelog: Other-changes line citing the google#2614 arc.
- navigation.md: point the docs-section-landing-pages ref at adding-content,
  where the anchor actually resolves.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant