Guide
How to add comments to markdown files (that clients can use)
Markdown has no built-in commenting. Here are the real ways to add comments to markdown docs — PR reviews, Giscus, Google Docs round-trips, or a viewer with per-section comments — and which works for non-technical clients.
The short answer
Markdown itself has no commenting, so your options are: GitHub/GitLab pull-request reviews (developer-only, needs accounts), Giscus or similar (ties comments to GitHub Discussions, needs a GitHub login), copy into Google Docs (manual, drifts from the source), or render the markdown in a viewer that adds per-section threaded comments. For non-technical clients, only the last works well: a viewer like Miradorly lets anyone sign in by email and comment on any section, with a resolved status and one inbox — while the source stays as markdown in your repo.
Markdown is great for writing and terrible for feedback: there's no built-in way for a reader to leave a comment. So every team eventually asks the same question — how do non-technical people actually comment on our markdown docs? Here are the real options and the one that works for clients.
First: markdown has no commenting
You can hide notes with HTML comment syntax (<!-- like this -->), but that's an author trick, not reader feedback. Visible, reviewable comments must come from whatever renders or hosts the markdown. So the question is really which tool you wrap around the file.
The options
1. Pull-request / merge-request reviews
If the reviewer is a developer, PR review comments are excellent — inline, threaded, resolvable. But they require a GitHub/GitLab account and comfort with a code-review UI. For a client, this is a non-starter.
2. Giscus (or utterances)
These map comments to GitHub Discussions/Issues under your static site. Clean for an open-source or developer audience — but every commenter needs a GitHub login. Again, wrong for clients.
3. Copy into Google Docs
Universal commenting, zero technical barrier — and a maintenance nightmare. You're now keeping the doc in two places; the Google Doc and the repo drift apart immediately, and feedback lives disconnected from your source of truth.
4. Render in a viewer with built-in comments
Wrap the repo's markdown in a viewer that adds per-section threaded comments. The reader signs in by email (no GitHub), comments on the exact section, and you triage from one inbox with a resolved status. The source stays markdown in your repo; comments live alongside the rendered view, not in a fork of the content.
Which works for clients
| Option | Client-friendly | Needs GitHub | Comments tied to source | Effort |
|---|---|---|---|---|
| PR review | ❌ | ✅ | ✅ | Low (dev-only) |
| Giscus | ❌ | ✅ | ⚠️ Discussions | Medium setup |
| Google Docs | ✅ | ❌ | ❌ drifts | High (manual) |
| Viewer w/ comments | ✅ | ❌ | ✅ | Very low |
Only the viewer route is both client-friendly and keeps comments connected to the real document.
How it works with a viewer
With Miradorly:
- Connect the repo; the markdown renders as a portal with a section structure.
- Invite the client by email with a
commenterrole (scoped to their project). - They click any section and leave a threaded comment; teammates reply; you mark it resolved.
- All comments across projects land in one inbox — no more "I emailed John for review" loops.
Your writers never leave their editor; the docs are still .md in git. Comments are a layer on top, not a second copy of the content.
Bottom line
You can't add real comments inside markdown — you add them with the tool that renders it. For developers, PR reviews are fine. For clients and non-technical stakeholders, you need a viewer with per-section commenting and email login, so feedback stays attached to the source instead of rotting in a Google Doc.
Frequently asked questions
Does markdown support comments?
Not visible review comments. You can hide text with HTML comment syntax, but there's no native way for a reader to leave feedback on a markdown document. Commenting has to come from the tool that renders it.
How can a non-technical client comment on markdown?
Render the markdown in a viewer that adds commenting. With Miradorly, clients sign in by email (no GitHub) and leave threaded comments per section, which you resolve from a single inbox — the source stays as .md in your repo.
Can I use GitHub pull request comments for client feedback?
Technically, but it's a poor fit — PR reviews require GitHub accounts and developer fluency, and the feedback lives in a code-review UI a client won't navigate. It works for engineers, not clients.
What about Giscus comments?
Giscus maps comments to GitHub Discussions, so every commenter needs a GitHub login. Fine for an open-source audience, wrong for clients without GitHub accounts.