Documentation Overhaul: MkDocs Website

[matthewhanson]

Overview

This PR completely overhauls the stac-server documentation through a two-stage refactoring:

1. Split the massive README.md into focused markdown files (ARCHITECTURE.md, USAGE.md, DEPLOYMENT.md, CONFIGURATION.md, CONTRIBUTING.md, SECURITY.md), recognizing the content had grown too large for a single file
2. But then, recognized the docs had grown substantial enough to warrant a dedicated site. Migrated all content to a comprehensive MkDocs-powered documentation website at stac-utils.github.io/stac-server, adding diagrams, comprehensive examples, and missing configuration documentation

This is purely a documentation restructuring and enhancement. All API functionality remains unchanged.

📚 What's New

Documentation Website

• Modern UI: Material for MkDocs theme with navigation tabs, instant loading, and built-in search
• Organized Structure: Four main sections for logical navigation:
  • 🚀 Getting Started: Overview, installation, and quickstart
  • 📖 Guides: Usage, configuration, and deployment
  • 📘 Reference: API docs, OpenAPI spec, and architecture
  • ℹ️ About: Security, changelog, license, and contributing
• Versioned Docs: Using mike for version management (v4.5 + latest)
• Interactive Navigation: Search functionality and clear navigation cards

Enhanced Content

• API Documentation: Direct links to Swagger Editor and Redoc for interactive OpenAPI exploration
• Better Examples: Comprehensive usage examples including pystac-client, filtering, aggregations, and geohash decoding
• Improved Configuration: Clarified deprecated Context Extension, fixed Morgan logging format documentation
• Clean References: Updated all STAC spec links to v1.1.0, removed broken links

📝 Evolution of Changes

This PR went through two major phases:

Phase 1: README Refactoring

• Split the monolithic README.md into focused documentation files
• Created ARCHITECTURE.md, USAGE.md, DEPLOYMENT.md, CONFIGURATION.md, CONTRIBUTING.md, SECURITY.md
• Streamlined README to serve as a concise project overview
• Recognized the documentation had grown substantial enough to benefit from a proper documentation website

Phase 2: MkDocs Migration & Enhancement

• Migrated all content to MkDocs with Material theme
• Added substantial new content:
  • Architecture diagrams and data flow visualizations
  • Comprehensive usage examples (pystac-client, filtering, aggregations)
  • Missing configuration documentation (Context Extension, Morgan logging formats, etc.)
  • Geohash decoding examples and references
  • Production deployment guidance
• Enhanced existing content with better examples and clearer explanations
• Fixed documentation issues (deprecated extensions, broken links, missing explanations)
• Set up automated deployment to GitHub Pages with versioning
• Removed intermediate markdown files, keeping only README, CHANGELOG, and LICENSE at root

🗂️ File Changes

Created Then Removed (intermediate refactoring step)

These files were created during the refactoring but ultimately migrated to docs/:

• ARCHITECTURE.md → docs/reference/architecture.md
• USAGE.md → docs/usage/index.md
• DEPLOYMENT.md → docs/deployment/index.md
• CONFIGURATION.md → docs/configuration/index.md
• CONTRIBUTING.md → docs/development/contributing.md
• SECURITY.md → docs/about/security.md

Kept in Root

• ✅ README.md - Streamlined GitHub landing page
• ✅ CHANGELOG.md - Symlinked from docs/about/changelog.md
• ✅ LICENSE - Symlinked from docs/about/license.md

New Files

• mkdocs.yml - MkDocs configuration
• requirements-docs.txt - Documentation build dependencies
• .github/workflows/docs.yml - Automated documentation deployment
• docs/ - Complete documentation structure with 12 pages

🔧 Technical Details

Build System

• MkDocs: Static site generator with Material theme
• Mike: Documentation versioning
• GitHub Actions: Automated deployment to GitHub Pages on push to main
• Dependencies: pymdown-extensions, git-revision-date-localized-plugin

Documentation Structure

docs/
├── index.md                          # Landing page with navigation cards
├── getting-started/
│   ├── overview.md
│   ├── installation.md
│   └── quickstart.md
├── usage/
│   └── index.md                      # Comprehensive usage guide
├── configuration/
│   └── index.md                      # Environment variables and collection config
├── deployment/
│   └── index.md                      # AWS deployment guide
├── reference/
│   ├── api.md                        # API overview
│   ├── openapi.md                    # OpenAPI spec with external viewers
│   └── architecture.md               # System architecture
├── development/
│   └── contributing.md               # Contributing guidelines
└── about/
    ├── security.md
    ├── changelog.md -> ../../CHANGELOG.md
    └── license.md -> ../../LICENSE

🧪 Testing

Documentation can be tested locally:

# Install dependencies
pip install -r requirements-docs.txt

# Serve locally
mkdocs serve

[Copilot]

Pull request overview

This PR completely overhauls the stac-server documentation by migrating from a monolithic README to a comprehensive MkDocs-powered documentation website hosted at stac-utils.github.io/stac-server. The content was first split into focused markdown files, then migrated to a full documentation site with enhanced content, diagrams, examples, and automated deployment.

Key changes:

• Created 12-page MkDocs documentation site with Material theme
• Added comprehensive usage examples, configuration reference, and architecture diagrams
• Set up automated GitHub Pages deployment with versioning via mike
• Streamlined README to serve as concise project landing page

Reviewed changes

Copilot reviewed 20 out of 22 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
mkdocs.yml	MkDocs configuration with Material theme, navigation structure, and plugins
requirements-docs.txt	Python dependencies for building documentation (MkDocs, Material theme, extensions)
.github/workflows/docs.yml	GitHub Actions workflow for automated documentation deployment to GitHub Pages
docs/**/*.md	12 comprehensive documentation pages covering getting started, usage, configuration, deployment, reference, and about sections
README.md	Streamlined GitHub landing page with links to full documentation
CHANGELOG.md	Added unreleased entry documenting documentation overhaul
serverless.example.yml	Added commented configuration examples for CORS, extensions, authorization, and ingest settings

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jkeifer]

This is really awesome and I love it.

I'm a bit confounded though on the use of a python docs tool with a node project. It seems like something like docusaurus would be more appropriate and integrate better than mkdocs. Maybe this is not a problem, even if it tingles my spidey sense?

I do have one thing to request: I could not figure out why there's a requirements-docs.txt file and a uv.lock file. Maybe this is just a matter of missing docs contrib documentation? Why doesn't the github action docs build use uv with the lock file? Is this intended to be committed? It's hard to know without docs contrib documentation...unless I merely missed that--there's a lot here and I couldn't read it all in depth--then just point me in that direction so I can answer my own questions.

Thanks for doing all this.