Summary
Refactor the documentation homepage from one monolithic React page into a writer-friendly composition layer backed by focused, reusable React components.
The current src/pages/index.tsx implementation is valid Docusaurus, but it embeds editorial copy, page composition, component markup, and a manually maintained operation list in one file. That was reasonable for the initial bootstrap and will become increasingly awkward as the documentation site grows.
Proposed direction
- Use MDX for homepage narrative and section composition where Docusaurus layout behavior permits it.
- Extract structured presentation into focused React components, such as:
Hero
SupportSummary
ArchitectureFlow
OperationsGrid
IndependenceDisclaimer
- Keep complex behavior and reusable markup in TypeScript rather than defining components inline in MDX.
- Centralize homepage operation metadata so it is not manually duplicated across the page and operation documentation.
- Preserve ordinary documentation as Markdown unless a page actually needs MDX capabilities.
A thin React page shell plus imported MDX content is acceptable if a pure index.mdx page cannot preserve the required full-width layout cleanly. Document the chosen boundary.
Acceptance criteria
Notes
This is an architecture and maintainability change, not the visual redesign itself. Coordinate its component boundaries with the separate design-system issue so the new visual language can be implemented without another structural rewrite.
Summary
Refactor the documentation homepage from one monolithic React page into a writer-friendly composition layer backed by focused, reusable React components.
The current
src/pages/index.tsximplementation is valid Docusaurus, but it embeds editorial copy, page composition, component markup, and a manually maintained operation list in one file. That was reasonable for the initial bootstrap and will become increasingly awkward as the documentation site grows.Proposed direction
HeroSupportSummaryArchitectureFlowOperationsGridIndependenceDisclaimerA thin React page shell plus imported MDX content is acceptable if a pure
index.mdxpage cannot preserve the required full-width layout cleanly. Document the chosen boundary.Acceptance criteria
.md,.mdx, and React components.npm run typecheckandnpm run buildpass.Notes
This is an architecture and maintainability change, not the visual redesign itself. Coordinate its component boundaries with the separate design-system issue so the new visual language can be implemented without another structural rewrite.