Skip to content

[docs] Add MkDocs documentation site and deploy to GitHub Pages #499

@cendhu

Description

@cendhu

Summary

Set up MkDocs with the Material theme to publish project documentation to GitHub Pages. The project already has comprehensive markdown documentation in docs/ but
no documentation site.

What

  • Add mkdocs.yml with Material theme configuration (search, syntax highlighting, navigation tabs, light/dark mode)
  • Create docs/index.md landing page with project overview
  • Add GitHub Actions workflow to build and deploy to GitHub Pages on push to main
  • Organize existing docs under structured navigation:
    • Getting Started
    • Architecture
    • Deployment (Deployment Guide, Performance Tuning)
    • Services (Sidecar, Coordinator, Verifier, Validator-Committer, Query Service, Notification Service)
    • Configuration (TLS, Logging, Metrics Reference, Namespace Policy)
    • Development (Core Concurrency Pattern, Load Generator Artifacts)

Why

Documentation is currently only readable by browsing the repo. A hosted docs site improves discoverability and usability for contributors and operators.

Acceptance Criteria

  • mkdocs serve builds locally without errors
  • GitHub Actions workflow deploys to gh-pages branch on push to main
  • All 16 existing docs are accessible via navigation
  • Site is available at the GitHub Pages URL

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationenhancementNew feature or request

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions