How do I share a MkDocs build without deploying it?

Run `mkdocs build` and publish the `site/` directory. Drag the folder into Comma and you get a URL with access control on it — no Pages repo, no bucket, no DNS.

Do the internal links work?

Set `use_directory_urls: false` in mkdocs.yml before building. MkDocs then emits `page.html` instead of `page/index.html`, so every internal link resolves to a real file rather than relying on a web server's directory-index behaviour.

Does search still work?

The search plugin's index is a JSON file in the build, and it uploads with the rest of the directory, so search works at the link. It's one of the things that breaks when you open a MkDocs build from `file://`, because the index is fetched.

Why not just use GitHub Pages?

For public docs, do. Pages has no per-viewer access control on a free plan, so it's the wrong surface for an internal handbook, a customer-specific runbook, or a draft you want three people to read before it ships.

Can reviewers comment on a specific paragraph?

Yes. Threads anchor to the rendered content, so review feedback lands on the sentence it's about rather than arriving as a list of page-and-paragraph references.

Share a MkDocs site privately

mkdocs build takes twenty seconds and produces site/. Then comes the part that takes a week: deciding where it goes. Pages means a public repo or a paid plan; a bucket means a bucket policy; the internal Kubernetes ingress means a ticket.

For a draft, an internal handbook, or a runbook one customer should see, none of that is the point. You want a link with a fence around it.

Publish the build

# mkdocs.yml
use_directory_urls: false

mkdocs build      # → site/

use_directory_urls: false is the flag that matters here. By default MkDocs writes page/index.html and links to page/, which only resolves if a server is doing directory-index lookups for you. With it off you get page.html and links that point at real files — the same change that makes a build browsable offline.

Then drag site/ (or a zip of it) into the app:

index.html becomes the report body.
The theme's CSS and JS, the search index, and every built page upload alongside, with relative references rewritten to the uploaded copies.
Search works, because the index is fetched from the same origin rather than from file:// — background in why the report lost its CSS.

Access control is the whole reason

Per report: private, your team, any signed-in user, anyone with the link, or named reviewers — plus whether link holders can view, comment or edit. That's a docs surface for a handbook that shouldn't be indexed and a draft that isn't ready. See sharing & access control.

Review, in the document

Docs review by ticket is where documentation efforts go to die. Anchored comments put the correction on the paragraph, the author sees them in place, and the next build appends a revision instead of replacing the link.

Rebuild on a schedule

If the docs are generated from a source that changes — an API spec, a changelog, a data dictionary — a routine can rebuild and republish on a cron. The URL doesn't change; the content does.

Limits

Entry HTML: 5 MB. Assets: 25 MB per file, 250 MB and 500 files total. A large handbook can pass 500 files — publish the section under review rather than the whole manual, or split by top-level nav entry.
60 requests/minute per token.

Try it

Comma is free — unlimited reports, unlimited commenters, unlimited revision history.

Publish a docs build →