Unified Documentation Site Structure¶

Overview¶

The unified documentation site at docs.syrf.org.uk aggregates documentation from 3 repositories using the MkDocs monorepo plugin. This document shows the exact hierarchical structure.

docs.syrf.org.uk/
│
├── 🏠 Home
│   ├── Introduction (syrf/docs/index.md)
│   ├── Team Structure (syrf/docs/team.md)
│   └── Tags (syrf/docs/tags.md)
│
├── 🏗️ Architecture (syrf/docs/architecture/)
│   ├── Overview (syrf/docs/architecture/index.md)
│   ├── Dependency Map (syrf/docs/architecture/dependency-map.md)
│   ├── System Overview (syrf/docs/architecture/system-overview.md)
│   ├── GitOps Architecture (syrf/docs/architecture/gitops-architecture.md)
│   ├── GKE Cluster Analysis (syrf/docs/architecture/gke-cluster-analysis.md)
│   ├── Multi-Repo Docs Publishing (syrf/docs/architecture/multi-repo-docs-publishing.md)
│   └── Web NPM Vulnerabilities (syrf/docs/architecture/web-npm-vulnerabilities.md)
│
├── 📋 Decisions (syrf/docs/decisions/)
│   ├── Overview (syrf/docs/decisions/index.md)
│   ├── ADR-001: CI/CD Approach (syrf/docs/decisions/ADR-001-ci-cd-approach.md)
│   ├── ADR-002: GitVersion Mode (syrf/docs/decisions/ADR-002-gitversion-mode.md)
│   ├── ADR-003: Cluster Architecture (syrf/docs/decisions/ADR-003-cluster-architecture.md)
│   └── ADR-004: Version Continuity (syrf/docs/decisions/ADR-004-version-continuity-strategy.md)
│
├── 🎯 Features (syrf/docs/features/)
│   └── Overview (syrf/docs/features/index.md)
│
├── 📖 How-To Guides (syrf/docs/how-to/)
│   ├── Overview (syrf/docs/how-to/index.md)
│   ├── CI/CD Workflow (syrf/docs/how-to/ci-cd-workflow.md)
│   ├── Cluster Setup (syrf/docs/how-to/cluster-setup-guide.md)
│   ├── Feature Planning (syrf/docs/how-to/feature-planning-workflow.md)
│   ├── GKE MCP Usage (syrf/docs/how-to/gke-mcp-usage.md)
│   ├── Version Continuity (syrf/docs/how-to/implement-version-continuity.md)
│   ├── Resource Optimization (syrf/docs/how-to/resource-optimization-guide.md)
│   ├── GitOps GitHub App Setup (syrf/docs/how-to/setup-gitops-github-app.md)
│   ├── Sentry Integration (syrf/docs/how-to/setup-sentry-integration.md)
│   ├── PR Preview Environments (syrf/docs/how-to/use-pr-preview-environments.md)
│   └── Using MkDocs (syrf/docs/how-to/use-mkdocs.md)
│
├── 📅 Planning (syrf/docs/planning/)
│   ├── Overview (syrf/docs/planning/index.md)
│   ├── Migration/
│   │   ├── Overview (syrf/docs/planning/migration/README.md)
│   │   ├── Backlog (syrf/docs/planning/migration/backlog.md)
│   │   ├── Current Sprint (syrf/docs/planning/migration/sprint-current.md)
│   │   └── Status (syrf/docs/planning/migration/status.md)
│   └── Templates/
│       └── Sprint Summary (syrf/docs/planning/templates/sprint-summary-template.md)
│
├── 🚀 GitOps Operations (cluster-gitops/docs/) ← INCLUDED VIA MONOREPO PLUGIN
│   ├── Overview (cluster-gitops/docs/README.md)
│   ├── Deploying Services (cluster-gitops/docs/deploying-services.md)
│   └── Promotion Workflow (cluster-gitops/docs/promotion-workflow.md)
│
└── 🏗️ Infrastructure (camarades-infrastructure/docs/) ← INCLUDED VIA MONOREPO PLUGIN
    ├── Overview (camarades-infrastructure/docs/README.md)
    └── Guides/
        ├── Terraform Guide (camarades-infrastructure/docs/terraform-guide.md)
        └── Cluster Configuration (camarades-infrastructure/docs/cluster-config.md)

How the Monorepo Plugin Works¶

Main mkdocs.yml (syrf/)¶

nav:
  - Home: ...
  - Architecture: ...
  - Decisions: ...
  - Features: ...
  - How-To Guides: ...
  - Planning: ...

  - GitOps Operations:
      - '!include': ../cluster-gitops/mkdocs.yml

  - Infrastructure:
      - '!include': ../camarades-infrastructure/mkdocs.yml

cluster-gitops/mkdocs.yml¶

nav:
  - Overview: README.md
  - Deploying Services: deploying-services.md
  - Promotion Workflow: promotion-workflow.md

Result: The plugin merges this into the "GitOps Operations" section of the main site.

camarades-infrastructure/mkdocs.yml¶

nav:
  - Overview: README.md
  - Guides:
    - Terraform Guide: terraform-guide.md
    - Cluster Configuration: cluster-config.md

Result: The plugin merges this into the "Infrastructure" section of the main site.

URL Structure¶

Root URLs (from syrf/)¶

https://docs.syrf.org.uk/ → Home
https://docs.syrf.org.uk/architecture/system-overview/ → System Overview
https://docs.syrf.org.uk/decisions/ADR-003-cluster-architecture/ → ADR-003
https://docs.syrf.org.uk/how-to/cluster-setup-guide/ → Cluster Setup Guide

GitOps Operations URLs (from cluster-gitops/)¶

https://docs.syrf.org.uk/gitops-operations/ → GitOps Overview
https://docs.syrf.org.uk/gitops-operations/deploying-services/ → Deploying Services
https://docs.syrf.org.uk/gitops-operations/promotion-workflow/ → Promotion Workflow

Infrastructure URLs (from camarades-infrastructure/)¶

https://docs.syrf.org.uk/infrastructure/ → Infrastructure Overview
https://docs.syrf.org.uk/infrastructure/guides/terraform-guide/ → Terraform Guide
https://docs.syrf.org.uk/infrastructure/guides/cluster-config/ → Cluster Config

Visual Hierarchy¶

Top-Level Navigation Tabs:
┌─────────┬──────────────┬───────────┬──────────┬───────────┬──────────┬──────────────────────┬────────────────┐
│  Home   │ Architecture │ Decisions │ Features │  How-To  │ Planning │  GitOps Operations   │ Infrastructure │
└─────────┴──────────────┴───────────┴──────────┴───────────┴──────────┴──────────────────────┴────────────────┘
   ▲            ▲             ▲          ▲          ▲          ▲              ▲                      ▲
   │            │             │          │          │          │              │                      │
syrf/docs/  syrf/docs/   syrf/docs/ syrf/docs/ syrf/docs/ syrf/docs/ cluster-gitops/docs/  camarades-infrastructure/
                                                                                                    docs/

When viewing any page, the left sidebar shows:

📚 SyRF Documentation
├─ 🏠 Home
├─ 🏗️ Architecture
│  ├─ Overview
│  ├─ Dependency Map
│  ├─ System Overview
│  └─ ...
├─ 📋 Decisions
├─ 🎯 Features
├─ 📖 How-To Guides
├─ 📅 Planning
├─ 🚀 GitOps Operations          ← Expandable section
│  ├─ Overview
│  ├─ Deploying Services
│  └─ Promotion Workflow
└─ 🏗️ Infrastructure              ← Expandable section
   ├─ Overview
   └─ Guides
      ├─ Terraform Guide
      └─ Cluster Configuration

Cross-Repository References¶

From syrf/ → cluster-gitops/¶

Use full URLs for cross-repository references:

See [Deploying Services](https://docs.syrf.org.uk/gitops-operations/deploying-services/) for details.

From cluster-gitops/ → syrf/¶

See [ADR-003: Cluster Architecture](https://github.com/camaradesuk/syrf/blob/master/docs/decisions/ADR-003-cluster-architecture.md)

Or once published:
See [ADR-003: Cluster Architecture](https://docs.syrf.org.uk/decisions/ADR-003-cluster-architecture/)

From camarades-infrastructure/ → cluster-gitops/¶

See [How to Deploy](https://github.com/camaradesuk/cluster-gitops/blob/master/docs/deploying-services.md)

Or once published:
See [How to Deploy](https://docs.syrf.org.uk/gitops-operations/deploying-services/)

Search Integration¶

The unified search indexes all pages across all 3 repos:

Search: "deploy api"

Results:
  1. 🚀 Deploying Services → GitOps Operations
     How to deploy and update SyRF services using ArgoCD...

  2. 📖 CI/CD Workflow → How-To Guides
     ...builds Docker images and tags them for deployment...

  3. 🏗️ GitOps Architecture → Architecture
     ...ArgoCD continuously deploys services to Kubernetes...

Breadcrumbs¶

Each page shows breadcrumbs indicating its location:

Example 1: Page from syrf/¶

Home > How-To Guides > Cluster Setup Guide

Example 2: Page from cluster-gitops/¶

Home > GitOps Operations > Deploying Services

Example 3: Page from camarades-infrastructure/¶

Home > Infrastructure > Guides > Terraform Guide

Material Theme Features¶

All pages across all repos inherit the same theme:

Dark/Light Mode Toggle: Works across all sections
Instant Navigation: Fast page transitions
Code Copy Buttons: Present in all code blocks
Table of Contents: Auto-generated for all pages
Last Updated Dates: Shows git revision dates
Edit Links: Links back to GitHub for each source file

Adding New Documentation¶

To Add to GitOps Operations Section¶

Create new file in cluster-gitops/docs/
Add to cluster-gitops/mkdocs.yml:

nav:
  - Overview: README.md
  - Deploying Services: deploying-services.md
  - Promotion Workflow: promotion-workflow.md
  - Rollback Procedures: rollback-procedures.md  # NEW

Commit to cluster-gitops repo
Trigger docs rebuild (manual or automated)
New page appears at docs.syrf.org.uk/gitops-operations/rollback-procedures/

To Add to Infrastructure Section¶

Create new file in camarades-infrastructure/docs/
Add to camarades-infrastructure/mkdocs.yml:

nav:
  - Overview: README.md
  - Guides:
    - Terraform Guide: terraform-guide.md
    - Cluster Configuration: cluster-config.md
    - Disaster Recovery: disaster-recovery.md  # NEW

Commit to camarades-infrastructure repo
Trigger docs rebuild
New page appears at docs.syrf.org.uk/infrastructure/guides/disaster-recovery/

Build-Time Integration¶

What Happens During `mkdocs build`¶

Load Main Config: Read syrf/mkdocs.yml
Process Includes:
Find '!include': ../cluster-gitops/mkdocs.yml
Load cluster-gitops/mkdocs.yml
Merge navigation under "GitOps Operations"
Process Includes:
Find '!include': ../camarades-infrastructure/mkdocs.yml
Load camarades-infrastructure/mkdocs.yml
Merge navigation under "Infrastructure"
Render Pages: Build HTML for all markdown files from all 3 repos
Generate Indexes: Create search index across all pages
Apply Theme: Apply Material theme to all pages
Output: Single static site in _docs_build/

File Paths in Build Output¶

_docs_build/
├── index.html                                    (syrf/docs/index.md)
├── architecture/
│   ├── index.html                                (syrf/docs/architecture/index.md)
│   ├── system-overview/index.html                (syrf/docs/architecture/system-overview.md)
│   └── ...
├── decisions/
│   ├── ADR-003-cluster-architecture/index.html   (syrf/docs/decisions/ADR-003-cluster-architecture.md)
│   └── ...
├── how-to/
│   ├── cluster-setup-guide/index.html            (syrf/docs/how-to/cluster-setup-guide.md)
│   └── ...
├── gitops-operations/
│   ├── index.html                                (cluster-gitops/docs/README.md)
│   ├── deploying-services/index.html             (cluster-gitops/docs/deploying-services.md)
│   └── promotion-workflow/index.html             (cluster-gitops/docs/promotion-workflow.md)
└── infrastructure/
    ├── index.html                                (camarades-infrastructure/docs/README.md)
    └── guides/
        ├── terraform-guide/index.html            (camarades-infrastructure/docs/terraform-guide.md)
        └── cluster-config/index.html             (camarades-infrastructure/docs/cluster-config.md)

Key Takeaways¶

Flat Top-Level: All 3 repos appear as top-level navigation sections
Preserved Hierarchy: Each repo's internal structure is maintained
Seamless Integration: Users don't know which repo a page comes from
Unified Search: One search box finds content across all repos
Consistent URLs: Predictable URL structure based on navigation
Clear Ownership: File paths show which repo owns each page
Independent Updates: Each repo can update its docs independently
No Duplication: Each piece of content lives in exactly one place

Unified Documentation Site Structure¶

Overview¶

Final Site Navigation¶

How the Monorepo Plugin Works¶

Main mkdocs.yml (syrf/)¶

cluster-gitops/mkdocs.yml¶

camarades-infrastructure/mkdocs.yml¶

URL Structure¶

Root URLs (from syrf/)¶

GitOps Operations URLs (from cluster-gitops/)¶

Infrastructure URLs (from camarades-infrastructure/)¶

Visual Hierarchy¶

Sidebar Navigation Example¶

Cross-Repository References¶

From syrf/ → cluster-gitops/¶

From cluster-gitops/ → syrf/¶

From camarades-infrastructure/ → cluster-gitops/¶

Search Integration¶

Example 1: Page from syrf/¶

Example 2: Page from cluster-gitops/¶

Example 3: Page from camarades-infrastructure/¶

Material Theme Features¶

Adding New Documentation¶

To Add to GitOps Operations Section¶

To Add to Infrastructure Section¶

Build-Time Integration¶

What Happens During `mkdocs build`¶

File Paths in Build Output¶

Key Takeaways¶

Unified Documentation Site Structure¶

Overview¶

Final Site Navigation¶

How the Monorepo Plugin Works¶

Main mkdocs.yml (syrf/)¶

cluster-gitops/mkdocs.yml¶

camarades-infrastructure/mkdocs.yml¶

URL Structure¶

Root URLs (from syrf/)¶

GitOps Operations URLs (from cluster-gitops/)¶

Infrastructure URLs (from camarades-infrastructure/)¶

Visual Hierarchy¶

Sidebar Navigation Example¶

Cross-Repository References¶

From syrf/ → cluster-gitops/¶

From cluster-gitops/ → syrf/¶

From camarades-infrastructure/ → cluster-gitops/¶

Search Integration¶

Breadcrumbs¶

Example 1: Page from syrf/¶

Example 2: Page from cluster-gitops/¶

Example 3: Page from camarades-infrastructure/¶

Material Theme Features¶

Adding New Documentation¶

To Add to GitOps Operations Section¶

To Add to Infrastructure Section¶

Build-Time Integration¶

What Happens During mkdocs build¶

File Paths in Build Output¶

Key Takeaways¶

Related Documentation¶

What Happens During `mkdocs build`¶