Documentation Overhaul: MkDocs Website (#1013)

* Initial refactor of docs

* move some docs to DEPLOYMENT

* Add configuration to deployment, more readme changes

* updates docs again

* remove npm badge

* Add missing envvars, update CONFIGURATION and serverless example

* add USAGE.md

* refactor documentation into docs directory and create docs site with CI/CD for deployment

* remove old docs and update README

* update CHANGELOG

* fix misspelling

* remove old files from docs github workflow

* misc fixes in serverless example

* remove elasticsearch in docs and misc doc updates

* rename api spec html, remove outdated github workflow

* remove extra link from docs main page

* remove unused uv.lock

* add in documentation contribution section

* fix vulnerability

Author: matthewhanson

.eslintignore

@@ -1,6 +1,9 @@
 **/node_modules/**
 **/dist/**
+**/build/**
 **/webpack.config.js
 **/.nyc_output/**
 **/coverage/**
 tmp/**
+docs/api-spec.html
+site/**

.github/workflows/docs.yml

@@ -0,0 +1,85 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'README.md'
+      - 'CONTRIBUTING.md'
+      - 'CHANGELOG.md'
+      - 'src/lambdas/api/openapi.yaml'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch all history for git revision dates
+
+      - name: Create symlinks for root docs
+        run: |
+          ln -sf ../../CHANGELOG.md docs/about/changelog.md
+          ln -sf ../../LICENSE docs/about/license.md
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install Node dependencies
+        run: npm ci
+
+      - name: Build OpenAPI documentation
+        run: npm run build-api-docs
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install MkDocs dependencies
+        run: pip install -r requirements-docs.txt
+
+      - name: Configure Git for MkDocs
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git fetch --depth=1 origin gh-pages || true
+
+      - name: Deploy documentation with mike
+        run: |
+          mike deploy --push --update-aliases 4.5 latest
+          mike set-default --push latest
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/pages.yaml

@@ -18,4 +18,9 @@ _book
 serverless*.yml
 !serverless.example.yml
 tsconfig.tsbuildinfo
-docs/
+
+# MkDocs
+site/
+.cache/
+docs/api-spec.html
+

.gitignore

@@ -1,8 +1,19 @@
+#!/usr/bin/env sh
+
+# Load nvm
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
+
+# Use project's Node version
+if [ -f .nvmrc ]; then
+  nvm use
+fi
+
+# Run checks
 npm run lint
 npm run typecheck
 npm run check-openapi
 npm run audit-prod
 npm run test:unit
 npm run test:system
 npm run build
-npm run build-api-docs

.husky/pre-commit

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Changed
+
+- **Documentation Overhaul**: Migrated all documentation to a new MkDocs-powered documentation website at [stac-utils.github.io/stac-server](https://stac-utils.github.io/stac-server/)
+  - Comprehensive documentation now organized into Getting Started, Guides, Reference, and About sections
+  - Removed top-level markdown files (ARCHITECTURE.md, USAGE.md, DEPLOYMENT.md, CONFIGURATION.md, CONTRIBUTING.md, SECURITY.md) - all content migrated to docs/
+  - Updated README.md to serve as GitHub landing page with links to full documentation
+
 ## [4.5.0]
 
 ### Added
@@ -437,7 +446,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Landing Page (root) now has links for both GET and POST methods of search link relation
 - The STAC API version is now 1.0.0-rc.2
 - AWS OpenSearch Service OpenSearch 2.3 is used as the default instead of Elasticsearch 7.10.
-  See [migration section in README.md](README.md#04x---05x).
+  See [migration section in README.md](https://github.com/stac-utils/stac-server/blob/main/README.md#04x---05x).
 - The serverless.example.yml file now has zone awareness enabled and an even number of
   Elasticsearch nodes
 - Upgrade serverless to 3.x