feat(ai): add navigable /sitemap.md site map - #2254
Merged
Merged
Conversation
Mirror CAP/Capire's sitemap.md with a human- and AI-navigable map: verb-lane navigation plus every mission expanded to its ordered tutorials. Distinct from sitemap.xml (flat crawler XML) and llms-full.txt (flat metadata dump) — this is a navigable hierarchy. - scripts/fetch-sitemap-catalog.ts: build-time GET /build/catalog fetch into hugo/data/sitemap_catalog.json; fail-open (empty -> /missions/ index fallback) when CAP_BASE_URL absent, like llms.txt. - hugo.toml: sitemapmd output format on home; dedicated text/x-web-markdown media type so the file is written as .md. - sitemapmd.md template: Navigation / Missions / Topics / Reference. - Cross-links from llms.txt, public AGENTS.md, ai-consumption.md (#16). - Smoke test for /sitemap.md (sparse-catalog tolerant).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a human- and AI-navigable
/sitemap.md, mirroring CAP/Capire's sitemap.md: a Markdown map of the whole site so AI tools (and humans) can find what's available and go straight to the right page.Requested by Tom after seeing CAP's sitemap.md. Scope approved: Nav + missions expanded.
Why a fourth AI surface
It's a navigable hierarchy, distinct from what we already ship:
sitemap.xml— flat XML URL list for crawlersllms-full.txt— flat metadata dump of every resourcesitemap.md— the site's structure: verb lanes + each mission expanded to its ordered tutorialsHow
scripts/fetch-sitemap-catalog.ts— build-timeGET /build/catalog, flattens missions + ordered tutorial slugs intohugo/data/sitemap_catalog.json. Wired intobuild:allafterfetch-topic-clusters. Fail-open: noCAP_BASE_URL(dev / plainbuild:hugo) or a fetch error → empty list → template falls back to the/missions/index link, exactly likellms.txt. Missions aren't Hugo pages (served dynamically from CAP), so this build-time fetch is the only way a static map can enumerate them.hugo.toml—sitemapmdoutput format onhome. Uses a dedicatedtext/x-web-markdownmedia type (suffixes = ['md']) so Hugo writes the file assitemap.md— the sharedtext/markdownliststxtfirst (which is whyllms.txtis.txt). WireContent-Typeis set by the approuter from the.mdextension (markdown negotiation, feat(content): Accept: text/markdown negotiation on primary tutorial URL #2252).sitemapmd.mdtemplate — Navigation (6 verb lanes from the section pages + shelves, best-effort) / Missions (expanded, with fallback) / Topics (top 30 tags) / Reference.llms.txtReference, publicAGENTS.md, andai-consumption.md(documented as feature feat: tutorial feedback form + AEM cutover follow-ups #16 + TL;DR row)./sitemap.mdinseo-files.test.js, tolerant of a sparse catalog (asserts nav + Missions heading + a/tutorials|missions/link).Verification
hugo --source hugo --minifylocally produceshugo/public/sitemap.md(.md, not.txt) with the brand header, all six verb lanes, the mission fallback (no CAP locally), and Reference links. Missions expand and Topics populate in a full build withCAP_BASE_URLset.