How to share markdown docs with clients (without giving them your repo)

You write documentation in markdown — in Cursor, Claude Code, or your editor of choice — and commit it to a repo. Then a client needs to review it. They don't have GitHub, shouldn't have repo access, and "just open the .md file" isn't a thing for a non-technical person. Here's every realistic way to share it, with the honest trade-offs, ending with the setup that takes about 30 seconds.

The five options

1. Export to PDF

Quick and universal, but a dead end. The moment you edit the source, the PDF is stale. Links, search, and any sense of structure degrade. Fine for a one-time deliverable; wrong for living documentation.

2. Copy-paste into Google Docs

The most common hack — and the most painful. You're now maintaining the doc twice: once in the repo, once in Docs. They drift within a week. Comments live in a place disconnected from your source of truth. Agencies do this every week and quietly hate it.

"I'm sending .md files in Slack and non-coding people can't even open them, let alone comment."

a real complaint from developers sharing docs with clients

3. Invite the client to GitHub / GitLab

Technically possible, practically a mess. It triggers a security review you don't want to run, exposes far more than the one folder they need, and the GitHub UI is hostile to non-technical readers. Comments on .md happen in pull requests or issues — useless for a client.

4. Build a static site (Docusaurus, etc.)

A real docs site you fully control. The cost is that you build, host, deploy, and maintain it, and adding client comments means bolting on something like Giscus — which requires every commenter to log in with GitHub. Good if you have engineering time and the docs are public.

5. Put a viewer over your repo

Connect a hosted viewer to the repo. It renders the markdown as a portal, the client signs in by email, reads in the browser, and comments per section — no GitHub account, no repo access, no migration. Every git push updates what they see. This is the option built specifically for the problem.

How the options compare

The fastest setup, step by step

If you choose a viewer over your repo (the option Miradorly is built for), the flow is:

1. Connect the repo — install the GitHub or GitLab app and pick the markdown folders.
2. **Add a .docignore** — exclude anything internal so it's never rendered or indexed.

# .docignore — internal files the client should never see
CLAUDE.md
**/secrets/**
drafts/
*.internal.md

1. Invite the client by email with a viewer or commenter role, scoped to their project only.
2. Keep writing docs in your editor. Push commits as usual; the portal updates live.

That's it. No second editor, no duplicated content, no GitHub account for the client.

What about AI agents?

If the client (or your team) wants to ask the docs questions through an AI agent, a role-aware MCP server lets them — scoped to exactly what their account can see. That's a bonus the PDF and Google Docs routes can never offer, and it's covered in our guide to role-aware MCP for docs.

The takeaway

PDFs and Google Docs are where shared docs go to rot. Inviting clients to GitHub solves the wrong problem. A static site is real work. If your docs already live in a repo, the lowest-effort, always-current answer is a viewer over that repo with email login and per-section comments — your editor unchanged, your internal files protected.