Add Google Docs-style inline comments
MDXG solves navigation really well. One thing still missing from the markdown experience though: being able to attach a comment to a specific word or phrase, like Google Docs or Word do.
No one's really solved this for local markdown files. The tools that exist (StackEdit, SideMarkr) are web-only and don't store comments in the file itself.
A sketch
Since MDXG doesn't touch the format, comments could follow the same idea — use things that are already valid markdown/HTML and invisible to standard renderers:
The <a class="note" id="n1">proposed architecture</a> needs more detail.
<!-- n1: needs a diagram, flagged in review -->- The
<a class="note">is valid inline HTML, invisible to most renderers, gives you a real DOM hook to highlight - The
<!-- id: text -->comment is invisible in standard rendering - A conforming viewer matches the IDs and renders comments in a sidebar or at the bottom
Degrades gracefully — anchor renders as plain text, comment is invisible — so existing files are untouched.
Why this matters for agents
MDXG already frames markdown as the format between humans and AI. Comments extend that naturally: an agent delivers a planning doc, a human leaves a comment on a specific section, the agent reads it and responds in-thread. Antigravity allows for such a workflow when presenting implementation plans. It would be powerful to have the same pattern for markdown artifacts — no external tool, everything stays in the file.
I built almost exactly this as MDXG Redline, and the tradeoffs turned out to be the interesting part.
MDXG Redline (https://github.com/oubakiou/mdxg-redline) is a third-party MDXG Viewer-profile implementation that adds human inline comments on top of the reading experience. The loop you describe at the end (an agent delivers a doc, a human comments on a specific span, the agent reads it and responds) is what it's built for: a human selects any text range and leaves a comment, and the comments are exported as structured JSON that the agent applies back to the exact lines.
Where it differs from the sketch here is in-file vs sidecar:
<a class="note">anchor plus an HTML comment), which is good for portability: the annotation travels with the document and needs no external tool.**bold**boundary). It also exports headingPath, sourceLine, and the quoted text, so an agent (or a human) can locate it without the viewer. Design notes are in §6 of the design doc (in Japanese; the link doubles as a live demo of the viewer itself): https://mkdn.review/?url=https%3A%2F%2Fraw.githubusercontent.com%2Foubakiou%2Fmdxg-redline%2Frefs%2Fheads%2Fmain%2Fdocs%2Fdesign%2FDESIGN.md#p:6The reason I went sidecar, which matters most for the agent case: the agent reads only the compact JSON (the comments plus their anchors), not the whole document re-serialized with inline annotations, so a review round stays cheap on tokens/context. The cost is that sidecar comments are tied to a content hash of the document and are dropped when the source changes. That fits an agent loop that replaces the document each round, but it's the opposite of your "everything stays in the file" goal. Both make sense for different lifecycles: durable in-file annotation vs. a per-round review artifact.
Sharing as prior art in case the offset-based anchoring or the JSON export schema is useful for the spec discussion. Happy to go into either.