Centralized documentation repository for LEADR - the cross-platform leaderboard backend for indie game developers.
Live documentation: https://docs.leadr.gg
This repository aggregates documentation from multiple upstream repositories (API and SDKs) and publishes versioned documentation using MkDocs Material and Mike. Upstream repositories contribute documentation bundles via automated pull requests from CI/CD pipelines.
Important: All upstream documentation bundles must be provided as Markdown files (.md). The build process uses MkDocs to convert these to static HTML.
docs/
├── guides/ # Curated onboarding guides
├── reference/ # Curated key reference docs
├── api/ # Mostly generated API documentation
│ ├── .api-version # Docs version trigger file (e.g., "v1.2.3")
│ ├── openapi.json # OpenAPI specification
│ ├── http-api/ # HTTP API guides
│ └── reference/ # Generated API reference
├── sdks/ # SDK documentation
│ ├── sdk-versions.json # SDK-API compatibility matrix
│ └── {engine}/ # Per-language SDK docs
│ ├── sdk.meta.json # SDK metadata (version, commit, generator)
│ ├── {version}/ # Versioned SDK documentation
│ │ ├── index.md
│ │ ├── *.md # Documentation pages
│ │ └── assets/ # Images, diagrams, etc.
│ └── latest -> {version} # Symlink to latest version
└── *.md # General documentation pages
The mkdocs.yml file is the central configuration point for the entire documentation site. It controls:
- Site metadata (name, URL, description)
- Navigation structure and page ordering
- Theme configuration (Material theme with custom overrides)
- Plugins (search, autorefs, section-index)
- Markdown extensions (admonition, code highlighting, tabbed content)
- Build output directory (
site-md)
Any changes to site structure, navigation, or features should be made in this file.
- Format: Major.minor (e.g.,
v1.0,v1.1) - Conversion: Release
v1.2.3→ docs versionv1.2 - Patch updates: Update existing version (e.g.,
v1.2.4updatesv1.2docs) - Minor/major: Create new version (e.g.,
v1.3.0createsv1.3docs)
- Format: Full semantic versioning (e.g.,
0.1.0,0.2.1) - Location:
docs/sdks/{language}/{version}/ - Compatibility: Tracked in
docs/sdks/sdk-versions.json
- Upstream Release: When an API or SDK version is released, CI generates documentation and creates a PR to this repository
- PR Contents:
- Updated documentation files
.api-versionfile (for API releases)- Updated metadata files
- Review & Merge: Review the PR and merge to
main - Automatic Deployment: GitHub Actions detects the version and deploys with Mike to GitHub Pages
When a PR is merged, the deploy.yml workflow runs, and:
- Extract version from
.api-version(e.g.,v1.2.3) if present - Convert to major.minor format (e.g.,
v1.2) - Deploy using Mike:
mike deploy v1.2 latest --update-aliases - Set
latestas default version - Push to
gh-pagesbranch
Documentation is available at:
https://docs.leadr.gg/v1.2/- Specific versionhttps://docs.leadr.gg/latest/- Latest versionhttps://docs.leadr.gg/- Defaults to latest
- Python 3.11+
- uv package manager
# Install dependencies (uv handles this automatically)
uv sync
# Serve docs locally with hot-reload
uv run mkdocs serve
# Build static site (output to site-md/)
uv run mkdocs build
# List deployed versions
uv run mike list
# Deploy a version manually
uv run mike deploy v1.2 latest --update-aliases
# Set default version
uv run mike set-default latestTo manually deploy or update a version, the deployment workflow can be triggered manually and passed a version number as input.
- VERSIONING.md - Detailed versioning and deployment guide