Skip to content
3 min read · 519 words

Docs Site Deployment

The docs you are reading are the repo's one live deployment: MkDocs Material, built by Vercel with uv run mkdocs build, served as static files from the site/ output.

The moving parts

File (repo root)Role
mkdocs.ymlsite config: theme, plugins, markdown extensions, navigation
docs/the markdown sources (this content)
pyproject.toml + uv.lockbuild dependencies for uv (what Vercel uses)
requirements.txtsame dependencies for pip-based workflows
vercel.jsonbuild command + output directory + URL behavior
.vercelignoreexcludes backend/, frontend/, learn_* from the docs deployment
site/build output — gitignored, regenerated every build
json
{
  "buildCommand": "uv run mkdocs build",
  "outputDirectory": "site",
  "cleanUrls": true,
  "trailingSlash": false,
  "installCommand": "echo 'Skipping default pip install'"
}

Notes: uv run resolves and installs the root pyproject.toml deps on demand (hence the no-op installCommand); cleanUrls pairs with MkDocs' use_directory_urls: true so pages serve at /getting-started/installation/.

Deploy flow

Rendering diagram…

Production deploys from main; any other branch gets a preview URL automatically. No secrets, no environment variables.

Working on docs locally

bash
# from the repository root
uv sync
uv run mkdocs serve          # live-reload at http://localhost:8000
uv run mkdocs build          # what Vercel runs; check for warnings

Treat build warnings as failures — MkDocs reports broken internal links and nav entries pointing at missing files as WARNINGs; a clean build is the docs' only test suite.

Authoring conventions for this site

  • Internal links use relative .md paths ([Schema](../database/schema.md)) — MkDocs rewrites them to final URLs and validates them at build time. Never hand-write /section/page/ URLs.
  • Every directory has an index.md (the navigation.indexes feature makes it the section landing page).
  • Mermaid diagrams via fenced ```mermaid blocks (wired through pymdownx.superfences).
  • Admonitions (!!! note, ??? failure), content tabs (=== "Tab"), and grid cards are the house style — see any existing page.
  • New pages must be added to the nav: tree in mkdocs.yml or they won't appear in navigation.

Theme features in use

Material with: light/dark palette toggle (indigo), instant navigation, sticky tabs, section indexes, breadcrumbs, integrated ToC, search with suggestions/highlighting, code copy buttons + annotations, tags, git-revision-date-localized (page timestamps from git history), and HTML/CSS/JS minification. Custom styles live in docs/assets/css/extra.css.

Troubleshooting deploys

SymptomCause / fix
Vercel build fails on dependenciesroot pyproject.toml/uv.lock drifted — run uv sync + uv run mkdocs build locally first
Page 404s in productionfile exists but missing from nav:, or the internal link was hand-written instead of a relative .md path
Mermaid not renderingfence must be exactly ```mermaid under pymdownx.superfences custom fence config
Stale timestampsgit-revision-date-localized needs git history — shallow clones fall back to build date (configured fallback)
PreviousFrontendNextTesting