feat: rework docs corpus generator and add related links#53
Merged
Conversation
Normalize corpus slugs to a consistent all-dashes scheme and reshape the catalog: short-summary descriptions, a kind facet (guide/reference/endpoint), an endpoint facet carrying operationId, path, and method, and path-derived topics so no doc is left uncategorized. Drop nav-shell pages and strip the generated APIPage bodies while keeping the endpoint catalog entries. Add curated related links. Each page declares related URLs in frontmatter; the generator resolves internal links to doc ids, emits per-doc outbound edges, and renders a Related section in the corpus. The docs site renders the same links as Related cards at the bottom of every page.
The generator now owns the facet vocabularies. catalog.json carries a taxonomy of the distinct topics, kinds, and lifecycles present, each as a value, a human label, and a document count, so consumers read it instead of reconstructing the vocabularies and labels themselves. Manifest contract change: bump the catalog version to 3.
mollases
approved these changes
Jun 25, 2026
Rename CLAUDE.md to AGENTS.md as the canonical agent-instructions file and leave CLAUDE.md as a symlink to it. Document that every new page under content/docs must declare a related list of site-relative URLs. These power the Related cards on the docs site and the per-document edges in the generated corpus, and generated endpoint pages curate them in the openapi facets generator.
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
2 participants
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.
Summary
Reworks the documentation corpus generator and adds curated "Related"
links that surface both on the docs site and in the generated corpus.
Changes
path-derived).
catalog.json: short-summary descriptions, akindfacet(guide / reference / endpoint), an endpoint facet carrying
operationId, path, and method, and path-derived topics so no doc isleft uncategorized.
index,references,guides) and strip thegenerated
<APIPage>bodies while keeping the endpoint catalogentries.
frontmatter; the generator resolves internal links to doc ids and
emits per-doc outbound
edges. The docs site renders these as"Related" cards at the bottom of every page.
taxonomyblock incatalog.json(distinct topics, kinds,and lifecycles with human labels and counts).
Notes
The catalog manifest contract changed — new
kind,endpoint,edges, andtaxonomyfields, andversionis bumped to 3. Corpusconsumers must update their model and pinned version to match.