Magma Devs Documentation

Documentation site for Smart Router — the centralised RPC routing gateway with QoS-based selection, caching, and failover policies.

Built with MkDocs Material. All content lives under docs/; the site is configured in mkdocs.yml.

Preview locally

pip install -r requirements.txt
mkdocs serve            # http://127.0.0.1:8000

Build

mkdocs build --strict   # output in site/ (gitignored); --strict fails on broken links

Design

The look lives in four files under docs/stylesheets/, loaded in this order:

File	Holds
tokens.css	Every raw color, size and typeface, plus the mapping onto the theme's own variables
shell.css	Header, search, left navigation, table of contents, footer
content.css	Article type, links, code, tables, callouts, tabs
widgets.css	Copy-page menu, chains explorer, floating prompts, 404 page

Two rules keep it maintainable:

• Raw values go in tokens.css only. The other three files use var(--…). No hex codes, no typeface names, no !important.
• Sizes and spacing come from the scales in tokens.css (type: 12.5 · 14 · 16 · 19 · 24 · 32; spacing: 4 · 8 · 12 · 16 · 24 · 32 · 48). Nothing in between.

All text uses one sans face; code uses a mono face. Both are system fonts, so nothing is downloaded.

Diagrams

The diagrams in docs/assets/diagrams/ are animated SVGs generated by scripts/diagrams.py. Edit the script, not the SVG files, then run:

python3 scripts/diagrams.py

They animate with CSS only, so they play inside a normal image tag. Readers who turn on reduced motion get a still diagram and a one-line summary.

Asset URLs are fingerprinted

hooks/asset_fingerprint.py rewrites every local extra_css / extra_javascript entry at build time to <path>?v=<sha256 prefix> of the file's content. The site sits behind Cloudflare, whose edge caches static assets for hours without knowing when a deploy happened; a content hash makes a changed file a new URL, so a deploy is visible on the first request. Nothing to maintain — add the bare path to mkdocs.yml and the hook stamps it.

Deployment

Pushing to main triggers .github/workflows/docs.yml, which builds the site and publishes it to GitHub Pages at https://magma-devs.github.io/docs/.

One-time setup: in the repo's Settings → Pages → Build and deployment, set Source to "GitHub Actions" for the deploy job to publish.