From 6dd0431db0c8c720e12ced35bcb32bb04b3994a0 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 27 Aug 2026 09:19:09 +0000 Subject: [PATCH] docs: document hidden sidebar sections The agent guide did not explain how sidebar recursion and sitemap filtering interact for hidden pages and sections. Document tree construction, discovery exclusions, subtree cascading, and branch-scoped hidden navigation. --- AGENTS.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index e28d4883b9..d335fddbe7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -126,6 +126,54 @@ Additional common fields: - `linkTitle:` — sidebar label (keep under 30 chars) - `weight:` — ordering within a section +## Sidebar navigation + +The section sidebar is rendered by +`layouts/_partials/sidebar/sections.html`. It starts at `.FirstSection` and +recursively walks each section's `.Pages`. Page weight controls the default +order. Section front matter can group entries with `sidebar.groups`, reverse +their order with `sidebar.reverse`, override a link with `sidebar.goto`, and +add a badge with `sidebar.badge`. + +The sidebar expands the current page's ancestor sections and marks the current +page with `aria-current`. When changing the recursive templates, pass all +navigation state through both `renderChildren` and `renderList`. Keep the page +filter and the `$hasChildren` calculation aligned so an expand control never +points to an empty list or disappears for a rendered list. + +## Hidden pages + +Set `sitemap: false` to hide a page from site-wide discovery. This setting: + +- Excludes the page from `sitemap.xml`, `metadata.json`, and `llms-full.txt` +- Excludes the page body from the site search index +- Adds a `noindex` robots meta tag + +The page is still built and remains available through direct links. This is +not an access control mechanism. + +Hugo does not automatically apply `sitemap: false` from a section page to its +descendants. To hide an entire subtree, cascade the value from the section's +`_index.md`: + +```yaml +sitemap: false +cascade: + sitemap: false +``` + +## Hidden sections in the sidebar + +The sidebar uses `sitemap` as a navigation visibility filter. A hidden page is +absent from the sidebar outside its active navigation path. The current page +and its ancestors remain visible so direct links to hidden pages do not produce +an empty navigation path. + +When the active path enters a hidden section, `revealHidden` propagates down +that branch and renders the whole hidden subtree. This keeps the section's +navigation available while you are in it. The state must remain scoped to that +branch so unrelated hidden pages stay hidden. + ## Hugo shortcodes Shortcodes are defined in `layouts/shortcodes/`. Syntax reference is in