docs(site): render generated TypeDoc as the API reference (#3763)#3948
Merged
Conversation
Wire the generated TypeDoc markdown into the website as a dedicated, rendered API-reference section. - Add an `api` Astro content collection loading the committed generated markdown from docs/api, sharing the docs frontmatter schema. - Add website/src/pages/api/[...slug].astro rendering the collection, mapping the generated `index` page to the /api/ section root. - Exclude api/** from the `docs` collection so the API reference renders only under /api/ instead of being duplicated under /docs/api/. - Run docs:api:md as the website prebuild so markdown is regenerated before astro build; add an API Reference nav link. Frontmatter compatibility was already solved at generation time by the existing typedoc-plugin-frontmatter + scripts/typedoc-astro-title.mjs. Use astro/zod + looseObject (astro:content z export is deprecated). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…api (#3763) The prebuild ran `docs:api:md` (typedoc) at website-build time, which type-checks nexus-agents source and needs nexus-memory's dist declarations — unavailable in the website's CI build (TS7016), breaking Build/Test/Consolidation-E2E. The API markdown is committed under docs/api/, so the site renders it directly; regeneration stays the `docs:api:md` script (decoupled from the site build). Verified: website build green (110 pages, /api/ rendered). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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.
Closes #3763 (epic #3532 item).
What
Wires the generated TypeDoc markdown (JSDoc →
typedoc+typedoc-plugin-markdown, spike #3686) into the website as a dedicated, rendered API-reference section. The markdown generation already worked; the missing piece was the website wiring — an Astro content collection + a render route. Before this PR the generateddocs/api/index.mdwas being silently absorbed into thedocscollection and rendered under/docs/api/; now it has its own collection and/api/section.Collection + route wiring
apicontent collection (website/src/content.config.ts) — loads the committed generated markdown fromdocs/apivia theglobloader, sharing the same frontmatter schema asdocs.website/src/pages/api/[...slug].astro— mirrors the docs route, rendering the collection throughDocsLayout. The generatedindexpage is mapped to the/api/section root (slugundefined).docscollection now excludesapi/**(pattern: ['**/*.md', '!api/**']) so the API reference renders only under/api/, not duplicated under/docs/api/.Frontmatter compatibility
Already solved at generation time by the spike:
typedoc-plugin-frontmatter+ the localscripts/typedoc-astro-title.mjsplugin injecttitle/description/tierinto every generated page — exactly what the Astro collection schema (and theentry.data.titlefilter in the route) require. No post-processing needed.One lint adjustment: lint-staged flagged the original
import { z } from 'astro:content'+.passthrough()as deprecated (it only lints changed files). Switched toimport { z } from 'astro/zod'+z.looseObject(...)per the rule.Build wiring
docs:api:mdruns as the websiteprebuild, so the markdown is regenerated beforeastro build. Generated output stays committed underdocs/api/— matching the existing convention (docs/api/anddocs/reference/*are both committed;.gitignorenotes "TypeDoc output committed"). Regenerating produced only cosmetic formatting drift (quote style / indentation) in the committeddocs/api/index.md.Build verification
pnpm --filter nexus-agents-website build— green, 110 pages,/api/index.htmlgenerated,/docs/api/correctly absent.astro check— 0 errors (one pre-existing unrelated hint inBaseLayout.astro). No package TS touched, so notsc --noEmitneeded.Scope
The API surface stays scoped to the spike's single canonical entry point (
src/core/result.ts→ 9 exports, one page) rather than the full 8740-export surface. This proves the pipeline end-to-end and keeps the build fast; expandingtypedoc.markdown.jsonentry points is a follow-up. No MCP tool / CLI command touched;inject-governance.ts/docs-check.yml/SKILL.mduntouched.🤖 Generated with Claude Code