Building a read-only docs portal on top of a Git repo (without forcing anyone into GitHub)

In part 1 I described the wall: docs in Git, readers who can't touch Git. This is how we built the overlay that fixed it — a tool we now call Miradorly (miradorly.com).

We set four hard constraints up front:

1. The writer's flow doesn't change. Whatever the team writes in Cursor / Claude Code today must just work. No migration, no second editor, no WYSIWYG bolted onto Git. (This is the one thing GitBook and Mintlify both get wrong — they make you migrate into their editor.)
2. The reader needs zero repo access. Email sign-in, a clean URL, nothing else.
3. Permissions are per-project and non-negotiable. A client sees their project and nothing else. Internal files never reach the browser.
4. It stays in sync automatically. Push a commit, the portal updates. No manual export, ever.

Connecting the repo. You install a GitHub or GitLab app and pick the Markdown folders. The portal is always a mirror of the repo — there's no separate copy to keep in sync, which is the whole point. A new commit re-renders the affected pages; no build step or deploy for the writer to think about.

Rendering. Standard Markdown + GFM, code blocks with syntax highlighting, Mermaid diagrams, tables of contents, cross-page links. The reader gets a fast, navigable site, not a raw file tree.

The access model. Docs are grouped into projects. People are invited as viewer or commenter per project. Anything can optionally be published publicly — per page or per whole project — handy for marketing docs or an open handbook. Everyone else sees only what their account allows.

.docignore. This is the piece that made us comfortable pointing clients at a live repo. Files matched by .docignore are excluded from the index entirely — not hidden in the UI, but never served. Internal notes, credentials, half-written specs: invisible, because they're never part of what the portal can see.

Comments. Readers comment directly on a section. Threads are grouped by section and land in a single inbox for the owner, who can mark them resolved. That kills the “I emailed it to John for review” loop — feedback lives on the doc, in context, at the same URL as the source of truth. No GitHub account required from the commenter, unlike Giscus or GitHub Wiki.

The result is boring in the best way: the team keeps writing exactly as before, and a client just reads and comments, like it's Notion — except the content is your repo. It's free to try on your own repo for 30 days, no card.

There's one part I'm most proud of, and it's the one most doc tools get wrong: giving an AI agent access to these same private docs without leaking anything. That's the final post — role-aware MCP.