Skip to main content

2026-04-23-rgb-docs-site-integration

Status​

Approved

Date​

2026-04-23

Owners​

  • Platform Backend
  • Developer Experience

Goal​

Add a rendered internal docs portal for RGB without moving the repo's source documents out of docs/.

The portal should make the current document-driven workflow easier to browse, cross-link, and review while keeping Markdown in Git as the source of truth.

Current State​

  • RGB already has a well-structured docs/ tree.
  • The repo currently relies on raw Markdown browsing in Git or local editors.
  • Aggregator already ships a Docusaurus-based internal docs portal with multiple doc sections and automatic sidebars.

Decision​

RGB adopts a standalone Docusaurus site under docs/docusaurus/.

The site mounts the existing documentation tree directly through separate docs plugins instead of copying content into a second structure.

Mounted Sections​

The first version mounts these source directories as first-class site sections:

  • docs/architecture
  • docs/services
  • docs/adr
  • docs/specs
  • docs/plans
  • docs/runbooks
  • docs/reference
  • docs/templates

Non-Goals​

Not included in the first integration:

  • public internet publishing
  • product marketing pages
  • API reference generation from OpenAPI
  • multi-language translation workflows
  • auth/SSO on top of the static site

Requirements​

Content Requirements​

  • Existing Markdown files remain canonical.
  • Section landing pages must exist for every mounted section.
  • Broken links should fail the docs build.
  • The rendered site must preserve the current stable-vs-change document model.

Site Requirements​

  • Use Docusaurus 3.
  • Keep the site independent from web/blue, bo/admin, and runtime services.
  • Use autogenerated sidebars first; avoid manual IA drift.
  • Provide a clear homepage that mirrors the repo docs layout.

Operating Requirements​

  • Local preview must be one command after dependency install.
  • Build output must be static and deployment-agnostic.
  • The site should be safe to host on CF Pages, Vercel, or internal static hosting.

Future Extensions​

The site should be ready to add:

  • OpenAPI-generated API docs for gateway, admin_service, wallet_service, and other servers_v2 services
  • full-text search
  • diagram pages or generated architecture visualizations
  • docs CI checks in pull requests

Acceptance Criteria​

  • docs/docusaurus/ exists with a working local build.
  • Every current top-level docs category is mounted in the site.
  • Landing pages exist for adr and templates, which previously had no dedicated index page.
  • docs/README.md explains how the rendered site maps to the Markdown source.
  • The docs build succeeds locally with broken-link checks enabled.