Skip to content

build(docs): generate the api references with typedoc and a mintlify navigation - #469

Merged
Exeloo merged 4 commits into
mainfrom
feat/docs-navigation
Nov 7, 2026
Merged

Exeloo merged 4 commits into
mainfrom
feat/docs-navigation

Conversation

@Exeloo

@Exeloo Exeloo commented Nov 7, 2026

Copy link
Copy Markdown
Member

What does this PR do?

Refs #462 (the 2.0.0 references reach the site at the next engine release, with the new docs-sync).

Replaces the mint-tsdocs API reference generator with one TypeDoc run, and gives the docs pages clean slugs and an explicit navigation (docs layout of NanoForge-dev/actions#117).

  • pnpm run docs = turbo run build && typedoc → docs/references/<package>/**.mdx + docs/references/navigation.json
    • typedoc + typedoc-plugin-markdown (from the existing docs catalog), sanitizeComments for MDX
    • docs/typedoc/mintlify.mjs: frontmatter (title, description from the summary) and the navigation (one group per package, subgroups by kind)
    • per-package typedoc.json only for multi-entry packages (ecs, input, network)
  • Removed: mint-tsdocs, @microsoft/api-extractor, the liquid templates, mint-tsdocs.config.json, tsdoc.json, scripts/sync-docs-references.sh, per-package docs scripts, the turbo docs task
  • docs/docs: no 1- / snake_case slugs, file-relative links, docs/docs/navigation.json, the body H1 that repeated each title removed, getting-started/documentation.mdx rewritten (it described Sphinx)
  • One TSDoc fix in common (inline code wrapping onto a line starting with { broke MDX)

Note: on pnpm 12 pnpm docs is pnpm's built-in command; use pnpm run docs (docs-sync does).

How do you test this PR?

  • Before: references imported /snippets/tsdocs/PageLink.jsx/RefLink.jsx, which the docs repo gitignores, and leaked a .tsdocs cache.
  • After: pnpm run docs: 0 errors, 14 TSDoc warnings (docs: fix the TypeDoc warnings and hide the protected internals of NetworkServerLibrary #468), 432 pages, all listed once in the navigation, all titled. Full docs-sync with references into a scratch docs clone: mint validate success, mint broken-links no broken links. docs/docs: 23 pages, all listed, validate/broken-links/a11y pass.
  • Commands run: pnpm build 13/13, pnpm run docs, pnpm lint 25/25; push hook ran unit and e2e tests (pass).

Merge danger

Door: two-way (revert). The page renames change public URLs once synced; the docs PR adds redirects.
Blast radius: engine tooling only; no package API change (one TSDoc comment).
Order: release NanoForge-dev/actions#117 as 3.2.0 first. Until then the old @v3 sync would copy these renamed pages next to the old ones and regenerate the docs repo docs.json. Then merge this PR, and NanoForge-dev/docs (opened next) last. After NanoForge-dev/actions#117, a release of this repo without this PR fails the docs step before writing anything (safe, continue-on-error).

Follow-up issues

Quality gate

Check Result Notes
Docs Updated docs/docs pages and navigation, getting-started/documentation.mdx
Correctness Pass 1 Important (release order, above), Minor filed as #468
Performance Pass pnpm run docs reuses the build cache of the release job; TypeDoc ~21 s
Accessibility Pass after fix duplicate H1s removed (d649cdb)
Security Pass new deps from the existing catalog, frontmatter written with JSON.stringify
Style Pass lint pass; Minor: commit scope docs(engine) is not a package name

@github-actions github-actions Bot added documentation Improvements or additions to documentation packages:common Related to Common library packages:core Related to Core library modules:ecs Related to ECS library modules:editor Related to Editor library modules:graphics-2d Related to Graphics2D library modules:input Related to Input library modules:music Related to Music library modules:network Related to Network library modules:sound Related to Sound library packages:asset Related to AssetManager library packages:env Related to Env library modules:scene Related to Scene library modules:graphics-3d Related to Graphics3D library labels Nov 7, 2026
@Exeloo
Exeloo merged commit 35f5644 into main Nov 7, 2026
6 of 7 checks passed
@Exeloo
Exeloo deleted the feat/docs-navigation branch November 7, 2026 00:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation modules:ecs Related to ECS library modules:editor Related to Editor library modules:graphics-2d Related to Graphics2D library modules:graphics-3d Related to Graphics3D library modules:input Related to Input library modules:music Related to Music library modules:network Related to Network library modules:scene Related to Scene library modules:sound Related to Sound library packages:asset Related to AssetManager library packages:common Related to Common library packages:core Related to Core library packages:env Related to Env library

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant