Comparison
Miradorly vs MkDocs: publishing docs vs controlling who reads them
MkDocs (with Material) is the docs-as-code default for publishing markdown as a site — but a static site is public by default. Compare MkDocs with Miradorly for private, client-facing docs with roles and comments.
The short answer
MkDocs solves publishing: it turns the markdown in your repo into a clean static site, for free. What it deliberately doesn't solve is access — a static site is public by default, has no per-client permissions, and no comments a client can use without extra tooling. Miradorly is a hosted layer over the same repo that adds exactly that: email sign-in, viewer/commenter roles per project, section comments, .docignore, and a role-aware MCP — for $29/mo flat. Use MkDocs for public docs; use Miradorly when different clients must see different things.
MkDocs — especially with the Material theme — is the default answer whenever someone asks "how do I publish the markdown in my repo as a site?" And it's a good answer: free, fast, git-native. But it answers a publishing question. The question agencies actually hit is an access question: how do I show this client their docs — and nothing else? That's a different layer, and it's the one MkDocs deliberately doesn't have.
What MkDocs is genuinely great at
Public documentation. If your docs can be open to the whole internet — an open-source project, a public product manual — MkDocs + Material + GitHub Pages is arguably the best free stack there is. You keep writing markdown in your editor, CI builds the site, done. If that's your whole requirement, you don't need Miradorly; stop reading and go set up MkDocs.
The part MkDocs doesn't do: gating
A static site generator produces files. Files don't check who's asking. As one r/technicalwriting commenter put it: "static site generators are great at publishing and bad at gating, because a static site is public by default."
The moment your requirement includes "clients must not see each other's docs" or "internal notes stay internal," you're building custom infrastructure on top:
| DIY approach | What it costs you |
|---|---|
| Reverse proxy + auth (oauth2-proxy, basic auth) | Setup + user management forever; one shared password is not per-client isolation |
| Per-client builds (one site per client) | A build matrix that grows with every client; onboarding/offboarding becomes a CI task |
Jinja2 role templating ({% if user_role == "admin" %}) | Content forked inside the source; easy to leak with one wrong tag |
| Private hosting per client | N hosting setups, N domains or paths to manage |
People really do all of these — every one of the above came up as a real workaround in the same threads. And the warning that came with them: "retrofitting isolation onto a public site is a rebuild."
The same repo, with an access layer
Miradorly connects to the repo MkDocs would build from and renders the same markdown — but behind sign-in:
- Per-project roles. Invite a client by email as viewer or commenter; they see their project, never their neighbor's.
- **
.docignore.** Internal files are never indexed — not hidden by CSS, absent from the system. - Comments without GitHub. Threaded by section, resolved statuses, email sign-in.
- Role-aware MCP. Your AI agents (and your client's) query the docs and get only what their account can see. A static site has no equivalent.
Your writing workflow doesn't change at all — which is the same promise MkDocs makes. The difference is what happens after the push.
Cost, honestly
MkDocs is $0 in licenses and very much not $0 in hours once privacy enters the picture: an auth layer, a per-client build matrix, and someone who owns that pipeline. Miradorly is $29/mo flat (10 projects) or $79/mo (unlimited) with a 30-day free trial and no card. If your docs are public, MkDocs wins on price forever. If they're private and per-client, count your engineering hours first.
Bottom line
MkDocs solves publishing. Miradorly solves access. If everyone may read everything — MkDocs. If different people must see different things, and some of them should comment without a GitHub account — that's Miradorly.
Frequently asked questions
Does MkDocs have access control?
Not built in. MkDocs generates a static site, which is public by default. Teams bolt on access control with reverse proxies, per-client builds, or Jinja2 role templating — all custom engineering you maintain yourself. Miradorly ships per-project roles out of the box.
Can clients comment on an MkDocs site?
Not natively. The common add-on is giscus or Disqus; giscus requires every commenter to have a GitHub account, which defeats the point for non-technical clients. Miradorly has threaded, per-section comments with email sign-in.
Is MkDocs really free?
The software is free. The total cost is the engineering time: build pipeline, hosting, an auth layer if docs must be private, per-client builds if clients must be isolated, and ongoing maintenance. That DIY stack is what a flat $29/mo replaces.
Can I keep MkDocs and add Miradorly?
Yes — they don't conflict. Some teams keep a public MkDocs site for open docs and use Miradorly on the same repo for private, per-client documentation with comments and MCP.