Add dark mode, versioned docs, navigation tabs, and PR validation

.github/workflows/docs.yml

@@ -10,16 +10,29 @@ on:
       - notebooks/**
       - mkdocs.yml
       - requirements-docs.txt
+    tags:
+      - "v*"
+  pull_request:
+    branches:
+      - main
+    paths:
+      - docs/**
+      - src/**
+      - notebooks/**
+      - mkdocs.yml
+      - requirements-docs.txt
   workflow_dispatch:
 
 permissions:
   contents: write
 
 jobs:
-  deploy:
+  docs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - uses: actions/setup-python@v5
         with:
@@ -33,5 +46,31 @@ jobs:
           sed -i "s|repo_url:.*|repo_url: https://github.com/${{ github.repository }}|" mkdocs.yml
           sed -i "s|repo_name:.*|repo_name: ${{ github.repository }}|" mkdocs.yml
 
-      - name: Deploy to GitHub Pages
-        run: mkdocs gh-deploy --force
+      - name: Validate build (PR only)
+        if: github.event_name == 'pull_request'
+        run: mkdocs build --strict
+
+      - name: Configure git for mike
+        if: github.event_name != 'pull_request'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Deploy dev docs (push to main)
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          mike deploy dev latest --update-aliases --push
+          mike set-default latest --push
+
+      - name: Deploy versioned docs (tag push)
+        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          mike deploy "$VERSION" latest --update-aliases --push
+          mike set-default latest --push
+
+      - name: Deploy docs (manual trigger)
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          mike deploy dev latest --update-aliases --push
+          mike set-default latest --push

docs/aws-batch-inference.md

@@ -120,7 +120,7 @@ python scripts/post_run_report.py --bucket my-bucket --output-prefix my-output-p
 
 ### 1. Configure & Deploy Infrastructure
 
-Follow [`infra/terraform/README.md`](../infra/terraform/README.md) to deploy infrastructure. Only the app layer is required; bootstrap and foundation are optional (see Terraform README for when to use each). Each layer has a `backend.hcl.example` and `terraform.tfvars.example` - copy both and fill in your values. For day-to-day config changes (S3 paths, model URI, instance types), only the app layer needs re-applying:
+Follow [`infra/terraform/README.md`](terraform-reference.md) to deploy infrastructure. Only the app layer is required; bootstrap and foundation are optional (see Terraform README for when to use each). Each layer has a `backend.hcl.example` and `terraform.tfvars.example` - copy both and fill in your values. For day-to-day config changes (S3 paths, model URI, instance types), only the app layer needs re-applying:
 
 ```bash
 cd infra/terraform/app && terraform plan && terraform apply
@@ -383,7 +383,7 @@ The split manifest produced by `utils/split_data.py` (`split_test_ids.txt`) is d
 
 ## Configuration Reference
 
-See [`infra/terraform/README.md`](../infra/terraform/README.md#app-variable-reference) for the full variable reference and [app outputs](../infra/terraform/README.md#app-outputs).
+See [`infra/terraform/README.md`](terraform-reference.md#app-variable-reference) for the full variable reference and [app outputs](terraform-reference.md#app-outputs).
 
 
 ---

docs/terraform-reference.md

@@ -0,0 +1 @@
+../infra/terraform/README.md

mkdocs.yml

@@ -2,26 +2,47 @@ site_name: Bridge Classification
 site_description: USGS LiDAR Bridge Point Cloud Classification Pipeline
 repo_url: https://github.com/NGWPC/bridge-classification
 repo_name: NGWPC/bridge-classification
+edit_uri: edit/main/docs/
+
+extra:
+  version:
+    provider: mike
 
 theme:
   name: material
   features:
+    - navigation.tabs
     - navigation.sections
+    - navigation.indexes
     - navigation.expand
     - navigation.top
     - search.highlight
+    - search.suggest
+    - content.action.edit
     - content.code.copy
+    - content.tooltips
   palette:
     - scheme: default
       primary: indigo
       accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
 
 nav:
   - Home: index.md
-  - Architecture: architecture.md
-  - Data Pipeline: data-pipeline.md
-  - AWS Batch Inference: aws-batch-inference.md
-  - Deployment Runbook: deployment-runbook.md
+  - Guide:
+    - Architecture: architecture.md
+    - Data Pipeline: data-pipeline.md
+    - AWS Batch Inference: aws-batch-inference.md
+    - Deployment Runbook: deployment-runbook.md
+    - Design Decisions: decisions.md
   - API Reference:
     - api/index.md
     - Core & Constants: api/core.md
@@ -34,7 +55,6 @@ nav:
     - Dataset Overview: notebooks/dataset_overview.ipynb
     - RANSAC Deck Planes: notebooks/ransac_deck_planes.ipynb
     - Training Plots: notebooks/training_plots.ipynb
-  - Design Decisions: decisions.md
 
 plugins:
   - search
@@ -66,8 +86,13 @@ markdown_extensions:
   - pymdownx.inlinehilite
   - pymdownx.tabbed:
       alternate_style: true
+  - pymdownx.snippets
+  - pymdownx.tasklist:
+      custom_checkbox: true
   - tables
   - admonition
   - pymdownx.details
+  - attr_list
+  - md_in_html
   - toc:
       permalink: true

requirements-docs.txt

@@ -2,3 +2,4 @@ mkdocs>=1.5,<2.0
 mkdocs-material>=9.0
 mkdocstrings[python]>=0.24
 mkdocs-jupyter>=0.24
+mike>=2.0