# Share a MkDocs Site Privately — A Build, Not a Deployment

Canonical: https://commareports.com/share-mkdocs-site
Published: 2026-08-25

> mkdocs build gives you a site/ folder and then a hosting decision you didn't want to make. Publish the build to Comma for an access-controlled link with comments on the page itself.

# 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

```yaml
# mkdocs.yml
use_directory_urls: false
```

```bash
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](https://commareports.com/):

- `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](/html-report-broken-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](/docs/sharing).

## Review, in the document

Docs review by ticket is where documentation efforts go to die.
[Anchored comments](/comment-on-html) put the correction on the
paragraph, the author sees them in place, and the next build appends a
[revision](/docs/ci) 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](/docs/routines) 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 →](https://commareports.com/)**

### Related

- [Share Sphinx docs](/share-sphinx-docs) · [Share OpenAPI docs](/share-openapi-docs)
- [Share dbt docs](/share-dbt-docs) · [GitHub Pages alternatives](/alternatives/github-pages-alternatives)
- [Sharing model](/docs/sharing)