Skip to content

Docs site — the fine print

The highest-staleness details behind the browsable, searchable docs site option page: the real cost, what a static site can't do, the site_url gotcha, and the announced MkDocs 2.0 rewrite.

Last verified: 2026-06-07

It's free, end to end

MkDocs and the Material theme are open source and run on your machine; the built site is static files that host free on every deploy host. The only spend is the recipient's ~0 — they open a link. [confirmed]

Static files only — no forms, no logins inside the page

A docs site can't take a submission or sign someone in; it just shows pages. Need those? That's a deployed app, and the login itself is a gated website. [confirmed]

Set the final web address before you deploy

A few Material features (instant navigation, the sitemap search uses) want site_url in the config — your agent sets it, but it's why a hastily-deployed site can have broken links until rebuilt. [confirmed]

A breaking rewrite (MkDocs 2.0) is announced but still pre-release

Material's team calls it "a ground-up rewrite" with "potentially significant breaking changes," and it's "still in pre-release." [confirmed] Material for MkDocs won't run on MkDocs 2.0 — the team states it plainly: a Material-built site "will cease to work with MkDocs 2.0." [confirmed] It doesn't matter yet: today's build still pulls MkDocs 1.6.x (the live sites linked from the option page are built on it), so everything there works. [confirmed]

Sources