DZ Markdown Review Syntax

VS Code syntax highlighting for Markdown review loops between an agent and a human reviewer, plus Obsidian-flavoured Markdown and custom review annotations.

This extension injects into VS Code's built-in Markdown language. It does not contribute a separate language mode, so it can compose with other Markdown syntax extensions.

It also highlights Obsidian comments, wikilinks, embeds, callouts, tags, block references, ==highlights==, and custom review additions, deletions, substitutions, highlights, and comments.

This repository is also an agent plugin source:

• .codex-plugin/plugin.json exposes it as a Codex plugin.
• .claude-plugin/plugin.json exposes it as a Claude Code plugin.
• skills/markdown-review-workflow teaches agents how to create, answer, resolve, and clean inline Markdown review conversations.

The default review syntax stays valid Markdown by using one HTML comment block per conversation. Each message starts on its own line:

The generated text stays normal Markdown.
<!--
@agent I chose this wording because it matches the glossary.
@me Can we make this less categorical?
@agent Done. I softened the wording and kept the glossary term.
-->

The opening <!-- may appear after paragraph text, a list item, or a heading. Only comments that contain review lines are treated as active conversations.

The extension also supports a custom conversation block:

{??
@agent I chose this wording because it matches the glossary.
@me Can we make this less categorical?
??}

Set dzMdReview.commentSyntax to custom to create new conversations with {?? ... ??}. The default is html. Existing conversations in HTML and {?? ... ??} syntaxes are recognized.

Canonical roles:

• @agent: agent rationale or note about generated content.
• @me: human review comment.

Older notes that use a colon after the role marker are still recognized, but commands generated by the extension use the colonless form: @agent Note and @me Note.

For fast manual review, a line that starts with a bare @ inside the block is highlighted as a temporary human comment:

{??
@ This is a quick review note while reading.
??}

The agent should normalize these quick notes when processing the review:

{??
@me This is a quick review note while reading.
??}

When a review is resolved, the agent should replace the conversation block with a validated note. The default validated note is a plain Markdown HTML comment:

<!-- I chose this wording because it matches the glossary. -->

For Obsidian notes, the agent may use an Obsidian comment instead:

%%
I chose this wording because it matches the glossary.
%%

Validated notes no longer contain @agent or @me, so this extension ignores them when navigating or deleting active review conversations. Obsidian comments are highlighted by the bundled Obsidian syntax injection.

Conversation blocks should not be nested, so replies should be new @agent or @me lines inside the same block. The document remains readable in source form, while the extension can color each role differently.

The extension contributes default token colors for the two review roles: agent notes and human comments. They remain normal TextMate scopes, so local VS Code settings or themes can override them.

For Catppuccin Latte, it also contributes default colors for the bundled Obsidian and custom review annotation scopes.

Active review conversations also receive editor decorations:

• a subtle background on the conversation content;
• a marker in the overview ruler;
• a 💬 gutter marker on the line where the conversation starts.

Commands:

• Markdown Review: Add Human Comment inserts an indented @me reply before the closing marker when used on the last non-empty content line, or on the closing marker line, of a multiline conversation. On compact inline notes, it expands the note to multiline and adds @me. Elsewhere, it keeps the normal new-line behavior. This command has no default keybinding.
• Markdown Review: Add Quick Comment adds a bare human reply. Outside a conversation, it creates a compact <!-- @ --> note, with {==...==} around a selection when present. Inside an inline conversation, it appends @ before the closing marker. Inside a multiline conversation, it inserts a new @ line before the closing marker.
• Markdown Review: Add OK Reply adds a trailing @me ok reply without toggling it off when it already exists.
• Markdown Review: Remove OK Reply removes a trailing @me ok reply without adding one when it is absent.
• Markdown Review: Create Multiline Quick Comment or Toggle Conversation Layout creates multiline <!-- ... --> quick comments outside conversations. With a selection it writes {==selection==}<!--\n@ \n-->. Inside conversations, it toggles between inline and multiline forms. When compacting, it joins distinct review messages with spaces but preserves continuation lines inside each message.
• Markdown Review: Create Review Discussion creates a compact {?? @me ??} discussion note regardless of dzMdReview.commentSyntax.
• Markdown Review: Add Review Addition wraps the selection with {++...++}, or inserts {++++} with the cursor inside.
• Markdown Review: Add Review Deletion wraps the selection with {--...--}, or inserts {----} with the cursor inside.
• Markdown Review: Add Review Substitution wraps the selection with {~~old~>new~~} and places the cursor on the replacement side.
• Markdown Review: Add Review Highlight wraps the selection with {==...==}, or inserts {====} with the cursor inside.
• Markdown Review: Add Review Comment wraps the selection with {>>...<<}, or inserts {>><<} with the cursor inside.
• Markdown Review: Cancel Review Annotation cancels the annotation at the cursor: additions and comments are removed, deletions and substitutions keep the old text, highlights keep their text, and discussions are removed.
• Markdown Review: Apply Review Annotation applies the annotation at the cursor: additions keep the new text, deletions and comments are removed, substitutions keep the replacement, highlights keep their text, and discussions are removed.
• Markdown Review: Delete Conversation removes the current review conversation.
• Markdown Review: Go to Next Review Block moves to the next custom review annotation or review conversation.
• Markdown Review: Go to Previous Review Block moves to the previous custom review annotation or review conversation.
• Markdown Review: Go to Next Conversation moves to the next review conversation.
• Markdown Review: Go to Previous Conversation moves to the previous review conversation.
• Markdown Review: Toggle Review Mode enables a modal review pass for the active Markdown editor. While it is active, the status bar shows Review and single-key review shortcuts are enabled. Use escape to leave the mode.

Default macOS shortcuts:

• cmd+alt+k m: toggle review mode.
• cmd+alt+enter: add quick @ comment.
• cmd+alt+shift+enter: create a multiline quick comment or toggle conversation layout.
• cmd+alt+k a: add custom review addition.
• cmd+alt+k s: add custom review deletion.
• cmd+alt+k r: add custom review substitution.
• cmd+alt+k h: add custom review highlight.
• cmd+alt+k c: add custom review comment.
• cmd+alt+k d: create custom review discussion note.
• cmd+alt+k o: add @me ok.
• cmd+alt+k shift+o: remove trailing @me ok.
• cmd+alt+k x: cancel custom review annotation.
• cmd+alt+k shift+x: apply custom review annotation.
• cmd+alt+k n: next custom review annotation or review conversation.
• cmd+alt+k shift+n: previous custom review annotation or review conversation.
• cmd+alt+backspace: delete conversation.
• cmd+alt+down: next conversation.
• cmd+alt+up: previous conversation.

Review mode shortcuts:

• n: next custom review annotation or review conversation.
• shift+n: previous custom review annotation or review conversation.
• x: cancel custom review annotation.
• shift+x: apply custom review annotation.
• o: add @me ok.
• @: add quick @ comment.
• escape: exit review mode.