docs: migrate mkdocs site to Docusaurus#181
Merged
Merged
Conversation
Replace mkdocs-material with a Docusaurus classic (TypeScript) site in docs-site/. Port all guides/getting-started/developer/about pages; convert admonitions to :::callouts and the collapsible to <details>. Homepage rewritten as index.mdx. TypeDoc still generates the API reference markdown (now into docs-site/docs/reference/api, git-ignored). Mermaid via theme-mermaid; .md parsed as CommonMark (format: detect) to keep the code-heavy guides and TypeDoc output MDX-safe. CI: replace mkdocs-deploy.yml with docs-deploy.yml (npm ci -> docs:check -> docs:api -> docusaurus build -> Pages). docs:serve/docs:build now drive Docusaurus. Preserve planning specs + excalidraw diagrams under dev-docs/; remove mkdocs.yml and old docs/. Exclude docs-site/ from root eslint. 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.
Summary
Migrates the documentation site from mkdocs-material to Docusaurus (classic preset, TypeScript) in
docs-site/, deployed to GitHub Pages.What changed
docs-site/(Docusaurus 3.x). Docs served at the site root (routeBasePath: '/'), deep-purple/amber theme carried over.!!! note) → Docusaurus:::callouts; the??? examplecollapsible →<details>. Homepage rewritten asindex.mdx.@docusaurus/theme-mermaid..mdparsed as CommonMark (markdown.format: 'detect') so the code-heavy guides and TypeDoc output stay MDX-safe;.mdx(homepage) still gets JSX.typedoc-plugin-markdown, now intodocs-site/docs/reference/api/(git-ignored, regenerated in CI).mkdocs-deploy.ymlreplaced bydocs-deploy.yml(npm ci→docs:check→docs:api→ docusaurus build → Pages).docs:serve/docs:buildnow drive Docusaurus.mkdocs.ymland olddocs/. Preserved planning specs + excalidraw diagrams underdev-docs/.docs-site/from root ESLint/Prettier (it has its own tooling).Verification
npm run docs:build(TypeDoc + Docusaurus) builds clean —onBrokenLinks: throw, zero broken links.Manual step required
GitHub Pages must be set to deploy from Actions: Settings → Pages → Source = "GitHub Actions" (one-time, cannot be set from the workflow).
🤖 Generated with Claude Code