Skip to content

Hosting the course website

The website is a static MkDocs site: ./course site build writes it to build/site/ (math and diagrams are self-hosted, so the output needs no CDN). Any static host works; the repository is pre-configured for Vercel.

Vercel (zero configuration)

vercel.json at the repository root tells Vercel how to build:

Setting Value
Install uv sync --locked (Vercel's image ships uv; the command installs it from astral.sh if missing)
Build uv run ./course site build --site-dir build/site
Output build/site
  1. In the Vercel dashboard choose Add New → Project → Import Git Repository and pick this repository (install the Vercel GitHub app if it asks).
  2. Keep the framework preset at Other; the install/build/output settings are read from vercel.json, so leave the overrides empty.
  3. Choose the branch to deploy (Production Branch under Settings → Git) and click Deploy. The first build takes about two minutes (it fetches the pinned KaTeX and Mermaid tarballs from npm and renders ~25 chapters); later builds are the same, since MkDocs rebuilds everything.

Every push to the production branch redeploys; pull requests get preview URLs.

From a terminal instead of the dashboard:

npm i -g vercel          # or: npx vercel
vercel link              # once: pick the project
vercel --prod            # builds on Vercel using vercel.json and deploys

Other static hosts

Build locally and upload build/site/:

./course site build                  # strict: warnings are errors
./course site build --no-strict      # if you only want a quick preview
  • GitHub Pages: uv run mkdocs gh-deploy pushes build/site/ to the gh-pages branch (set site_url in mkdocs.yml first so canonical links and the sitemap are right).
  • Netlify / Cloudflare Pages: use the same install and build commands as the Vercel table above with build/site as the publish directory.

The site is about 140 MB across ~550 files (mostly the rendered chapter pages, plus a 14 MB search index and 5 MB of self-hosted KaTeX/Mermaid) and contains no server-side code, so it fits every host's free tier.