refactor: documentation structure.

.github/workflows/ci.yml

@@ -114,3 +114,47 @@ jobs:
         run: |
           helm uninstall "$RELEASE_NAME" -n eoapi || true
           kubectl delete namespace eoapi || true
+  validate-docs:
+    name: Validate documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Check internal links
+        run: |
+          broken=0
+          find docs -name "*.md" | while read -r file; do
+            if grep -q "](\./" "$file" 2>/dev/null; then
+              grep -n "](\./" "$file" | while IFS=: read -r line link; do
+                path=$(echo "$link" | sed -n 's/.*](\.\///; s/).*//p')
+                if [[ "$path" == images/* ]]; then
+                  full="docs/$path"
+                else
+                  full="docs/$path"
+                fi
+                if [[ ! -e "$full" ]]; then
+                  echo "❌ $file:$line -> $path"
+                  broken=1
+                fi
+              done
+            fi
+          done
+          exit $broken
+
+      - name: Check external links
+        run: |
+          npm install -g [email protected]
+          echo '{"timeout":"10s","retryCount":2,"aliveStatusCodes":[200,301,302,403,999]}' > .mlc.json
+          find docs -name "*.md" -exec timeout 30 markdown-link-check {} --config .mlc.json \; || true
+
+      - name: Check frontmatter
+        run: |
+          missing=0
+          find docs -name "*.md" -not -path "docs/_includes/*" | while read -r file; do
+            head -1 "$file" | grep -q "^---$" || { echo "❌ Missing frontmatter: $file"; missing=1; }
+          done
+          exit $missing

.gitignore

@@ -4,5 +4,7 @@
 charts/config.yaml
 charts/eoapi/charts/*.tgz
 config_ingress.yaml
+dist
+site
 __pycache__
 CLAUDE.md

CHANGELOG.md

@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Unified local cluster management with `CLUSTER_TYPE` variable
 - Improved CI and local debugging; added debug-deployment.sh script
 - Added knative in CI to test eoapi-notifier.
+- Restructured docs with flattened structure and added portable documentation generation
 
 ## [0.7.12] - 2025-10-17
 

Makefile

@@ -7,7 +7,7 @@ TEST_SCRIPT := ./scripts/test.sh
 # Default cluster type (can be overridden)
 CLUSTER_TYPE ?= minikube
 
-.PHONY: help deploy clean tests integration lint validate-schema
+.PHONY: help deploy clean tests integration lint validate-schema docs serve-docs
 .DEFAULT_GOAL := help
 
 help:
@@ -30,6 +30,8 @@ help:
 	@echo "QUALITY:"
 	@echo "  lint            Run linting and code quality checks"
 	@echo "  validate-schema Validate Helm schemas"
+	@echo "  docs            Generate portable documentation package"
+	@echo "  serve-docs      Serve docs with mkdocs at http://localhost:8000"
 	@echo ""
 	@echo "VARIABLES:"
 	@echo "  CLUSTER_TYPE    Local cluster type: minikube or k3s (default: minikube)"
@@ -104,3 +106,13 @@ validate-schema:
 
 ingest:
 	@./scripts/ingest.sh
+
+docs:
+	@command -v mkdocs >/dev/null 2>&1 || { echo "❌ mkdocs required. Run: pip install mkdocs-material"; exit 1; }
+	@echo "📚 Building documentation with mkdocs"
+	@mkdocs build
+
+serve-docs: docs
+	@echo "📚 Serving docs with mkdocs at http://localhost:8000"
+	@echo "Press Ctrl+C to stop"
+	@mkdocs serve --dev-addr localhost:8000

README.md

@@ -28,11 +28,11 @@
 
 ### Get started
 
-* [Quick start guide](./docs/installation/quick-start.md)
+* [Quick start guide](./docs/quick-start.md)
 
 ### `eoAPI-k8s` documentation
 
-* [Overview of docs](./docs/index.md)
+* [Overview of docs](https://eoapi.dev/deployment/kubernetes)
 
 ### General eoAPI documentation
 * [eoapi.dev](https://eoapi.dev) website.

charts/eoapi/README.md

@@ -114,9 +114,9 @@ postgresql:
 
 For detailed configuration and usage:
 
-- [Configuration Guide](https://github.com/developmentseed/eoapi-k8s/blob/main/docs/installation/configuration.md)
-- [Data Management](https://github.com/developmentseed/eoapi-k8s/blob/main/docs/operations/manage-data.md)
-- [Autoscaling Guide](https://github.com/developmentseed/eoapi-k8s/blob/main/docs/operations/autoscaling.md)
+- [Configuration Guide](https://github.com/developmentseed/eoapi-k8s/blob/main/docs/configuration.md)
+- [Data Management](https://github.com/developmentseed/eoapi-k8s/blob/main/docs/manage-data.md)
+- [Autoscaling Guide](https://github.com/developmentseed/eoapi-k8s/blob/main/docs/autoscaling.md)
 
 ## License
 

docs/_includes/repository-links.md

@@ -0,0 +1,8 @@
+<!-- Reusable repository references -->
+[Main eoapi Repository]: https://github.com/developmentseed/eoapi
+[eoapi-k8s Repository]: https://github.com/developmentseed/eoapi-k8s
+[Report Issues]: https://github.com/developmentseed/eoapi-k8s/issues
+[eoAPI Documentation]: https://eoapi.dev/
+[Helm Charts]: https://github.com/developmentseed/eoapi-k8s/tree/main/charts
+[PostgreSQL Operator]: https://access.crunchydata.com/documentation/postgres-operator/
+[Kubernetes Documentation]: https://kubernetes.io/docs/

docs/operations/autoscaling.md → docs/autoscaling.md

@@ -1,11 +1,25 @@
+---
+title: "Autoscaling & Monitoring"
+description: "HPA setup with custom metrics, Grafana dashboards, Prometheus configuration, and load testing"
+external_links:
+  - name: "eoapi-k8s Repository"
+    url: "https://github.com/developmentseed/eoapi-k8s"
+  - name: "Kubernetes HPA Documentation"
+    url: "https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/"
+  - name: "Prometheus Documentation"
+    url: "https://prometheus.io/docs/"
+  - name: "Grafana Documentation"
+    url: "https://grafana.com/docs/"
+---
+
 # Autoscaling / Monitoring / Observability
 
 Autoscaling is both art and science. To test out your application's autoscaling requirements you often need to consider
 your data volume, data usage patterns, bottlenecks (such as the database) among many, many other things. Load testing,
 metrics, monitoring and observability will help you explore what those needs are.
 
 
-> ⓘ The `eoapi-support` chart in this repository (see `../charts/eoapi-support`) is required to be installed to
+> ⓘ The `eoapi-support` chart in this repository is required to be installed to
 enable any of the eoAPI service autoscaling. It cannot be listed as a dependecy of `eoapi` chart
 b/c of the limitations in `prometheus-adapter` and `grafana` for constructing the Prometheus internal
 service domains dynamically.
@@ -17,7 +31,7 @@ might want to read through the verbose walkthrough material below to familiarize
 
 ## Helm Install `eoapi-support`
 
-The following instructions assume you've gone through the [AWS](../installation/providers/aws-eks.md) or [GCP](../installation/providers/gcp-gke.md) cluster set up
+The following instructions assume you've gone through the [AWS](./aws-eks.md) or [GCP](./gcp-gke.md) cluster set up
 and installed the `eoapi` chart.
 
 
@@ -99,9 +113,9 @@ manual step that cannot be automated
 
 ---
 
-### Review [Default Configuration and Options](../installation/configuration.md)
+### Review [Default Configuration and Options](./configuration.md)
 
-[This document](../installation/configuration.md) will explain the differences in the `autoscaling` block for each service:
+[This document](./configuration.md) will explain the differences in the `autoscaling` block for each service:
 
    ```yaml
    autoscaling:
@@ -199,15 +213,15 @@ with the `release` name we installed the chart with below `<release-name>-grafan
 
 3. Login and you should be default be able to see the eoapi-k8s grafana dashboard. The Prometheus datasource will already be configured for you:
 
-   ![Grafana Datasource Configuration](../images/datasource.png)
+   ![Grafana Datasource Configuration](./images/datasource.png)
 
    You can then view the main eoAPI dashboard:
 
-   ![](../images/gfdashboard.png)
+   ![](./images/gfdashboard.png)
 
    To add additional custom dashboards, you can use the dashboard import functionality:
 
-   ![Adding Custom Grafana Dashboards](../images/add-grafana-dashboard.png)
+   ![Adding Custom Grafana Dashboards](./images/add-grafana-dashboard.png)
 
 ### Install or Upgrade Autoscaling Changes to `eoapi` Chart
 
@@ -361,7 +375,7 @@ that you're deploying using `ingress.className: "nginx"`.
 
 4. **Monitor autoscaling in Grafana** - Go back to your Grafana dashboard and watch your services autoscale for the endpoints you're hitting:
 
-   ![Grafana Autoscaling Dashboard](../images/grafanaautoscale.png)
+   ![Grafana Autoscaling Dashboard](./images/grafanaautoscale.png)
 
 ### Load Testing Best Practices
 

docs/installation/providers/aws-eks.md → docs/aws-eks.md

@@ -1,3 +1,17 @@
+---
+title: "AWS EKS Setup"
+description: "Complete EKS cluster setup with OIDC, node autoscaling, EBS CSI, and NGINX ingress"
+external_links:
+  - name: "eoapi-k8s Repository"
+    url: "https://github.com/developmentseed/eoapi-k8s"
+  - name: "AWS EKS Documentation"
+    url: "https://docs.aws.amazon.com/eks/"
+  - name: "eksctl Documentation"
+    url: "https://eksctl.io/"
+  - name: "Terraform Alternative"
+    url: "https://github.com/developmentseed/eoapi-k8s-terraform"
+---
+
 # AWS EKS Cluster Walkthrough
 
 This is a verbose walkthrough. It uses `eksctl` and assumes you already have an AWS account, have the [eksctl prerequisites installed](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-eksctl.html) including `eksctl` and `helm`.

docs/installation/providers/azure.md → docs/azure.md

@@ -1,3 +1,17 @@
+---
+title: "Azure AKS Setup"
+description: "Azure configuration with managed PostgreSQL, Key Vault integration, and Workload Identity"
+external_links:
+  - name: "eoapi-k8s Repository"
+    url: "https://github.com/developmentseed/eoapi-k8s"
+  - name: "Azure Kubernetes Service Documentation"
+    url: "https://docs.microsoft.com/en-us/azure/aks/"
+  - name: "Azure CLI Documentation"
+    url: "https://docs.microsoft.com/en-us/cli/azure/"
+  - name: "Azure PostgreSQL Documentation"
+    url: "https://docs.microsoft.com/en-us/azure/postgresql/"
+---
+
 # Microsoft Azure Setup
 
 ## Using Azure Managed PostgreSQL

docs/installation/configuration.md → docs/configuration.md

@@ -1,3 +1,13 @@
+---
+title: "Configuration Options"
+description: "Complete reference for Helm values, database types, ingress setup, and service configuration"
+external_links:
+  - name: "eoapi-k8s Repository"
+    url: "https://github.com/developmentseed/eoapi-k8s"
+  - name: "Helm Values Documentation"
+    url: "https://helm.sh/docs/chart_best_practices/values/"
+---
+
 # Configuration Options
 
 ## Required Values
@@ -116,7 +126,7 @@ raster:
 ## Deployment Architecture
 
 When using default settings, the deployment looks like this:
-![](../images/default_architecture.png)
+![](./images/default_architecture.png)
 
 The deployment includes:
 - HA PostgreSQL database (via PostgreSQL Operator)
@@ -138,7 +148,7 @@ All services include health check endpoints with automatic liveness probes:
 | Raster API | `/raster/healthz` | HTTP 200, no auth required |
 | Vector API | `/vector/healthz` | HTTP 200, no auth required |
 
-The Kubernetes deployment templates automatically configure `livenessProbe` settings for regular health checks. See the [deployment template](../../charts/eoapi/templates/services/deployment.yaml) for probe configuration details.
+The Kubernetes deployment templates automatically configure `livenessProbe` settings for regular health checks. See the [deployment template](https://github.com/developmentseed/eoapi-k8s/blob/main/charts/eoapi/templates/services/deployment.yaml) for probe configuration details.
 
 ## Advanced Configuration
 

docs/docs-config.json

@@ -0,0 +1,54 @@
+{
+  "structure": "flat",
+  "assets_dir": "images",
+  "external_repo": "https://github.com/developmentseed/eoapi-k8s",
+  "files": {
+    "index.md": { "title": "Kubernetes Deployment", "slug": "index" },
+    "quick-start.md": { "title": "Quick Start", "slug": "quick-start" },
+    "helm-install.md": { "title": "Helm Installation", "slug": "helm-install" },
+    "configuration.md": { "title": "Configuration Options", "slug": "configuration" },
+    "unified-ingress.md": { "title": "Unified Ingress", "slug": "unified-ingress" },
+    "aws-eks.md": { "title": "AWS EKS Setup", "slug": "aws-eks" },
+    "gcp-gke.md": { "title": "GCP GKE Setup", "slug": "gcp-gke" },
+    "azure.md": { "title": "Azure AKS Setup", "slug": "azure" },
+    "manage-data.md": { "title": "Data Management", "slug": "manage-data" },
+    "autoscaling.md": { "title": "Autoscaling & Monitoring", "slug": "autoscaling" },
+    "stac-auth-proxy.md": { "title": "STAC Auth Proxy", "slug": "stac-auth-proxy" },
+    "release.md": { "title": "Release Workflow", "slug": "release" },
+    "README.md": { "title": "Documentation Guide", "slug": "docs-readme" }
+  },
+  "nav_structure": [
+    { "title": "Overview", "file": "index.md" },
+    { "title": "Quick Start", "file": "quick-start.md" },
+    {
+      "title": "Installation",
+      "children": [
+        { "title": "Helm Installation", "file": "helm-install.md" },
+        { "title": "Configuration Options", "file": "configuration.md" },
+        { "title": "Unified Ingress", "file": "unified-ingress.md" }
+      ]
+    },
+    {
+      "title": "Cloud Providers",
+      "children": [
+        { "title": "AWS EKS", "file": "aws-eks.md" },
+        { "title": "GCP GKE", "file": "gcp-gke.md" },
+        { "title": "Azure AKS", "file": "azure.md" }
+      ]
+    },
+    {
+      "title": "Operations",
+      "children": [
+        { "title": "Data Management", "file": "manage-data.md" },
+        { "title": "Autoscaling & Monitoring", "file": "autoscaling.md" }
+      ]
+    },
+    {
+      "title": "Advanced",
+      "children": [
+        { "title": "STAC Auth Proxy", "file": "stac-auth-proxy.md" },
+        { "title": "Release Workflow", "file": "release.md" }
+      ]
+    }
+  ]
+}

docs/installation/providers/gcp-gke.md → docs/gcp-gke.md

@@ -1,4 +1,18 @@
- # GCP GKE Cluster Setup
+---
+title: "GCP GKE Setup"
+description: "GKE cluster creation with CSI driver, NGINX ingress, and cert-manager"
+external_links:
+  - name: "eoapi-k8s Repository"
+    url: "https://github.com/developmentseed/eoapi-k8s"
+  - name: "Google Cloud Documentation"
+    url: "https://cloud.google.com/kubernetes-engine/docs"
+  - name: "gcloud CLI"
+    url: "https://cloud.google.com/sdk/gcloud"
+  - name: "Terraform Alternative"
+    url: "https://github.com/developmentseed/eoapi-k8s-terraform"
+---
+
+# GCP GKE Cluster Setup
 
 This is a verbose walkthrough. It uses `gcloud` and assumes you already have an GCP account and project where you want to run eoapi. We also assume that you have some prerequisites installed including `gcloud`, `kubectl` and `helm`.
 
@@ -109,4 +123,4 @@ helm upgrade --install cert-manager jetstack/cert-manager \
   --set installCRDs=true
 ```
 
-Now we are ready to install eoapi. See the [eoapi installation instructions](../README.md/#helm-installation) for more details.
+Now we are ready to install eoapi. See the [eoapi installation instructions](./helm-install.md) for more details.

docs/installation/helm-install.md → docs/helm-install.md

@@ -1,3 +1,15 @@
+---
+title: "Manual Helm Installation"
+description: "Step-by-step Helm deployment process with custom configurations"
+external_links:
+  - name: "eoapi-k8s Repository"
+    url: "https://github.com/developmentseed/eoapi-k8s"
+  - name: "PostgreSQL Operator Documentation"
+    url: "https://access.crunchydata.com/documentation/postgres-operator/"
+  - name: "Helm Charts Repository"
+    url: "https://devseed.com/eoapi-k8s/"
+---
+
 # Manual Helm Install
 
 0. `eoapi-k8s` depends on the [Crunchydata Postgresql Operator](https://access.crunchydata.com/documentation/postgres-operator/latest/installation/helm). Install that first: