developmentseed · pantierra · Oct 24, 2025 · Oct 27, 2025
diff --git a/.github/workflows/validate-docs-links.yml b/.github/workflows/validate-docs-links.yml
@@ -0,0 +1,177 @@
+name: Validate Documentation Links
+
+on:
+  push:
+    branches: [ main, master ]
+    paths: [ 'docs/**/*.md' ]
+  pull_request:
+    branches: [ main, master ]
+    paths: [ 'docs/**/*.md' ]
+
+jobs:
+  validate-links:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install markdown-link-check
+        run: npm install -g markdown-link-check@3.11.2
+
+      - name: Create markdown-link-check config
+        run: |
+          cat > .markdown-link-check.json << 'EOF'
+          {
+            "ignorePatterns": [
+              {
+                "pattern": "^https://github.com/developmentseed/eoapi-k8s"
+              },
+              {
+                "pattern": "localhost"
+              },
+              {
+                "pattern": "127.0.0.1"
+              }
+            ],
+            "replacementPatterns": [
+              {
+                "pattern": "^./",
+                "replacement": "{{BASEURL}}/"
+              }
+            ],
+            "httpHeaders": [
+              {
+                "urls": ["https://github.com"],
+                "headers": {
+                  "Accept": "text/html"
+                }
+              }
+            ],
+            "timeout": "20s",
+            "retryOn429": true,
+            "retryCount": 3,
+            "fallbackRetryDelay": "30s",
+            "aliveStatusCodes": [200, 206, 301, 302, 403, 999]
+          }
+          EOF
+
+      - name: Validate internal links
+        run: |
+          echo "Checking internal link patterns..."
+          broken_links_found=0
+
+          while IFS= read -r -d '' file; do
+            # Skip files that don't contain any internal links
+            if ! grep -q "](\./" "$file" 2>/dev/null; then
+              continue
+            fi
+            echo "Checking internal links in: $file"
+
+            # Check for broken relative links
+            while IFS=: read -r line_num link; do
+              # Extract the link path
+              link_path=$(echo "$link" | sed -n 's/.*](\.\///; s/).*//p')
+
+              # Check if it's an image link
+              if [[ "$link_path" == images/* ]]; then
+                full_path="docs/$link_path"
+              else
+                full_path="docs/$link_path"
+              fi
+
+              if [[ ! -e "$full_path" ]]; then
+                echo "❌ Broken internal link in $file:$line_num -> $link_path (resolved to: $full_path)"
+                broken_links_found=1
+              else
+                echo "✅ Valid internal link: $link_path"
+              fi
+            done < <(grep -n "](\./" "$file" || true)
+          done < <(find docs -name "*.md" -type f -print0)
+
+          if [[ $broken_links_found -eq 1 ]]; then
+            echo "❌ Found broken internal links!"
+            exit 1
+          else
+            echo "✅ All internal links are valid!"
+          fi
+
+      - name: Validate external links
+        run: |
+          echo "Validating external links..."
+          find docs -name "*.md" -type f | while read -r file; do
+            # Skip files that don't contain any links
+            if ! grep -q "](http" "$file" 2>/dev/null; then
+              echo "ℹ️  Skipping $file (no external links found)"
+              continue
+            fi
+            echo "Checking external links in: $file"
+            # Use timeout to avoid hanging and make failures non-blocking
+            timeout 30 markdown-link-check "$file" --config .markdown-link-check.json 2>/dev/null || \
+              echo "⚠️  External link validation failed for $file (non-blocking)"
+          done
+          echo "✅ External link validation completed"
+
+      - name: Check for consistent link patterns
+        run: |
+          echo "Checking for inconsistent link patterns..."
+          inconsistent_found=false
+
+          # Check for internal docs/ prefix links (exclude external URLs)
+          internal_docs_links=$(find docs -name "*.md" -type f -exec grep -H "](docs/" {} \; 2>/dev/null | grep -v "https\?://[^)]*docs/" || true)
+          if [[ -n "$internal_docs_links" ]]; then
+            echo "❌ Found links using 'docs/' prefix - use relative paths instead"
+            echo "$internal_docs_links"
+            inconsistent_found=true
+          fi
+
+          # Check for ../ patterns
+          dotdot_links=$(find docs -name "*.md" -type f -exec grep -Hn "](\.\./" {} \; 2>/dev/null || true)
+          if [[ -n "$dotdot_links" ]]; then
+            echo "❌ Found links using '../' - use relative paths from docs root instead"
+            echo "$dotdot_links"
+            inconsistent_found=true
+          fi
+
+          if [[ "$inconsistent_found" == "true" ]]; then
+            echo "❌ Found inconsistent link patterns!"
+            echo "Use these patterns instead:"
+            echo "  - [Installation Guide](./installation.md)"
+            echo "  - [AWS Setup](./aws-eks.md)"
+            echo "  - [Images](./images/diagram.png)"
+            exit 1
+          else
+            echo "✅ All link patterns are consistent!"
+          fi
+
+      - name: Validate frontmatter
+        run: |
+          echo "Checking that all markdown files have frontmatter..."
+          missing_frontmatter_found=0
+
+          while IFS= read -r -d '' file; do
+            if ! head -1 "$file" | grep -q "^---$"; then
+              echo "❌ Missing frontmatter in: $file"
+              missing_frontmatter_found=1
+            fi
+          done < <(find docs -name "*.md" -not -path "docs/_includes/*" -type f -print0)
+
+          if [[ $missing_frontmatter_found -eq 1 ]]; then
+            echo "❌ Some files are missing frontmatter!"
+            echo "Add frontmatter like:"
+            echo "---"
+            echo "title: \"Page Title\""
+            echo "description: \"Page description\""
+            echo "external_links:"
+            echo "  - name: \"Link Name\""
+            echo "    url: \"https://example.com\""
+            echo "---"
+            exit 1
+          else
+            echo "✅ All markdown files have frontmatter!"
+          fi
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+- Restructured docs with flattened structure and added portable documentation generation
+
 ## [0.7.12] - 2025-10-17
 
 - Bumped eoapi-notifier dependency version to 0.0.7

diff --git a/Makefile b/Makefile
@@ -5,7 +5,7 @@ HELM_REPO_URL=https://devseed.com/eoapi-k8s/
 HELM_CHART_NAME=eoapi/eoapi
 PGO_CHART_VERSION=5.7.4
 
-.PHONY: all deploy minikube ingest tests integration lint validate-schema help
+.PHONY: all deploy minikube ingest tests integration lint validate-schema docs help
 
 # Default target
 all: deploy
@@ -25,6 +25,11 @@ minikube:
 	@echo "eoAPI is now available at:"
 	@minikube service ingress-nginx-controller -n ingress-nginx --url | head -n 1
 
+docs:
+	@echo "Generating portable documentation package."
+	@command -v bash >/dev/null 2>&1 || { echo "bash is required but not installed"; exit 1; }
+	@./scripts/generate-portable-docs.sh
+
 ingest:
 	@echo "Ingesting STAC collections and items into the database."
 	@command -v bash >/dev/null 2>&1 || { echo "bash is required but not installed"; exit 1; }

diff --git a/README.md b/README.md
@@ -28,7 +28,7 @@
 
 ### Get started
 
-* [Quick start guide](./docs/installation/quick-start.md)
+* [Quick start guide](./docs/quick-start.md)
 
 ### `eoAPI-k8s` documentation
 

diff --git a/charts/eoapi/README.md b/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
 

diff --git a/docs/_includes/repository-links.md b/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/
diff --git a/docs/operations/autoscaling.md → docs/autoscaling.md b/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.
 
 
-> &#9432; The `eoapi-support` chart in this repository (see `../charts/eoapi-support`) is required to be installed to
+> &#9432; 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
 

diff --git a/docs/installation/providers/aws-eks.md → docs/aws-eks.md b/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`.

diff --git a/docs/installation/providers/azure.md → docs/azure.md b/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

diff --git a/docs/installation/configuration.md → docs/configuration.md b/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