Skip to content

Refactor the documentation homepage into MDX composition and reusable React components #6

Description

@davidalucas

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

  • Homepage editorial content and page composition are no longer concentrated in one TSX file.
  • Reusable homepage sections live under a clearly named component directory.
  • Supported-operation metadata has one documented source within the docs repository; homepage cards cannot silently drift from the operation documentation.
  • The implementation preserves existing routes, page metadata, responsive behavior, keyboard navigation, semantic heading order, and reduced-motion behavior.
  • Components work in both light and dark modes.
  • Contributor documentation explains when to use .md, .mdx, and React components.
  • npm run typecheck and npm run build pass.
  • The refactor does not change Briosa protocol claims or broaden the documented supported operation surface.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions