Skip to main content

12. Multi-Site Documentation Architecture

Status: Accepted Date: 2025-07-06

Context​

The project requires two distinct types of documentation with different audiences and purposes:

  1. Internal Technical Documentation (toma): This site is for the development team. It needs to contain in-depth technical details, architectural decision records (ADRs), feature-driven development (FDD) documents, API documentation, and internal development guides.
  2. Public-Facing Website (kaido.team): This site is for external stakeholders, potential users, and the public. It needs to present a high-level overview of the project, its goals, blog posts, and marketing materials.

Combining these two different sets of content and audiences into a single website would create a confusing experience for both user groups and mix public content with internal documentation.

Decision​

We will implement a multi-site architecture using Docusaurus's multi-instance feature. We will maintain two separate Docusaurus instances within the platform/docs directory: toma for internal documentation and public (which builds the kaido.team site) for the external website. They will share some common configuration and plugins but will have separate content, navigation, and theming to cater to their specific audiences.

Consequences​

Positive:

  • Audience Segmentation: Provides a tailored and optimized experience for each distinct audience (developers vs. the public).
  • Content Separation: Keeps sensitive or highly technical internal documentation strictly separate from public-facing content.
  • Focused Navigation: Each site has a clear and relevant navigation structure for its target users, improving usability.
  • Independent Deployment: The two sites can be built and deployed independently, allowing for different release cycles.

Negative:

  • Increased Complexity: Managing two separate Docusaurus instances adds some configuration and maintenance overhead.
  • Configuration Duplication: There might be some duplication in configuration files, although Docusaurus allows for shared base configurations.
  • Content Siloing: Developers must be mindful of placing content in the correct site to avoid duplication or misplacement of information.

Mitigation:

  • Shared Tooling: Create shared Docusaurus components, themes, and plugins where applicable to reduce code duplication and maintain consistency.
  • Clear Guidelines: Maintain clear, documented guidelines for developers on where to place new documentation (e.g., "All ADRs and FDDs go into toma").
  • Automated Checks: Implement scripts as part of the CI/CD pipeline to validate that content is in the correct location and that there are no broken cross-site links.