Skip to content

Add params.llms.rootNote for extra root llms.txt text - #95

Open
artberger wants to merge 2 commits into
mainfrom
llms-root-note
Open

artberger wants to merge 2 commits into
mainfrom
llms-root-note

Conversation

@artberger

@artberger artberger commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor
AI-generated summary

Why

  • agentgateway.dev needs one paragraph in the root llms.txt that tells agents how to install its agent skills (an open agentgateway website PR).
  • The only way to add it today is to shadow the whole template. That PR's copy came from v0.4.x, which brought back the 42 inlined blog posts and the build timestamp that v0.5.0 removed. The root file grew from 2.9 KB to 13.2 KB.

What

  • layouts/llms.txt: prints rootNote as Markdown, in its own block after the "This is the root documentation index" sentence and before the section links. With the param unset, the output is byte-identical.
  • docs/content/configuration/llms-txt.md: documents the param.
  • hugo-oss.toml sets a two-line note and hugo-enterprise.toml leaves it unset, so the new llms-index.spec.ts check covers both cases.
  • CHANGELOG.md: an Unreleased entry. This is patch-level, because nothing changes unless a site sets the param.

Verification

  • Fixture builds before and after: the enterprise build has no changed files. The OSS build changes only llms.txt.
  • The new spec check fails on main and passes on both brands. llms-index, llms-directive, docs-coverage, override-parity, and slot-order pass.
  • agentgateway.dev with this template and the paragraph in params.llms.rootNote: the root /llms.txt and /docs/llms.txt are byte-identical to a shadow copy rebased on v0.5.0. After the pin bump, the site can delete its layouts/llms.txt.

A consumer could only add a sentence to the root llms.txt by shadowing
layouts/llms.txt, and a shadow copy drops every later template change.
agentgateway.dev's first copy came from v0.4.x and brought back the
inlined blog posts and build timestamp that v0.5.0 removed.

The optional param is Markdown that prints as its own block after the
index sentence and before the section links. Unset, the output is
byte-identical.

Signed-off-by: Art Berger <art.berger@solo.io>
Comment thread tests/llms-index.spec.ts Outdated
test("renders the note as its own block before the links, or nothing when unset", () => {
const text = read();
if (target.name.endsWith("-oss")) {
expect(text).toContain(`${INDEX_SENTENCE}\n\n${NOTE}\n\n- [`);

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This assertion depends on the first line after the note being a version link (- [). llms-index-tree.html prints a ## Heading for a section without versions, so adding or reordering a fixture section would fail this test even though rootNote still works. Could you check the order instead? For example, assert that the note's index is after the index sentence and before the first - [ or ## line, and that it is surrounded by blank lines.

Comment thread tests/llms-index.spec.ts Outdated

test("renders the note as its own block before the links, or nothing when unset", () => {
const text = read();
if (target.name.endsWith("-oss")) {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Other specs branch on target.brand (see book-document.spec.ts: target.brand !== "oss"). target.name.endsWith("-oss") works today only because the fixture is named docs-theme-extras-fixture-oss. Suggest target.brand === "oss" so a target rename doesn't silently flip the branch.

Comment thread layouts/llms.txt Outdated
no rootNote the output is byte-identical to a build without this param, so
a consumer no longer needs to shadow this file to add one paragraph. */ -}}
{{- $prodHost := partial "utils/prod-host.html" . -}}
{{- $rootNote := site.Params.llms.rootNote | default "" | strings.TrimSpace -}}

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If a site sets rootNote to something that isn't a string, such as a list or a map, strings.TrimSpace fails the build with an error that doesn't name the param. Minor, but a type check with errorf "params.llms.rootNote must be a string" (or printf "%v") would give a clearer failure.

A design question too: a param can only hold static text. If a site later needs computed content here (a link per version or language), it's back to shadowing the whole template. An empty hook partial that sites can override, for example _partials/llms/root-note.txt, would cover both cases. The param is simpler, so I'm fine either way, just flagging the tradeoff.

Comment thread docs/content/configuration/llms-txt.md Outdated
```

`llms.rootNote`
: Markdown added to the root `/llms.txt` as its own block, after the "This is the root documentation index" sentence and before the section links. Use it for site-wide text that an agent should read before it follows the links, such as where to install the site's agent skills. Without it, the root file is unchanged. Use `>-` to fold one paragraph, or `|` to keep line breaks.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you say explicitly that the note only goes in the root /llms.txt, not in section files like /docs/llms.txt? An agent that starts at a section's llms.txt never sees it, which matters for the agentgateway use case ("install the skills").

Comment thread CHANGELOG.md

## [Unreleased]

### Add — `params.llms.rootNote` adds a block of text to the root llms.txt (`layouts/llms.txt`, `hugo-oss.toml`, `tests/llms-index.spec.ts`, `docs/content/configuration/llms-txt.md`)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit, optional: this entry is one long paragraph, and most of the verification detail is already in the PR body. A shorter entry (what changed, why, and that it's a no-op when unset) would be easier to scan. Ignore if this matches how you want the changelog to read.

Signed-off-by: Art Berger <art.berger@solo.io>
@artberger
artberger marked this pull request as ready for review November 16, 2026 21:33

This branch has not been deployed

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

3 participants