Feat: markdown preview

[pandarun]

Im testing revdiff as a Claude Code plugin using a hook workflow (similar to a Zed “plan review” hook I previously used via cc-things). I’ve noticed that large plans are hard to read in the current view, and they would be much easier to scan if they could be shown using Markdown preview rendering.

It might make sense to add a Markdown Preview mode, alongside (or next to) the existing Markdown TOC mode, to improve readability for long, structured plan output.

[umputun]

if i understand right, you want glamour-style rendered output where **bold** shows as actual bold without the asterisks visible, [text](url) shows just the link text, code fences get framed, headings get block styling, bullets become •. Right now chroma colors the markdown source but the markup characters stay visible.

idea has merit, especially for plan review.

the simple version is workable. Add --markdown-preview flag plus a hotkey like P that re-renders the file through glamour, annotations disabled in that mode (toggle back to raw to mark a line). The trick even at this level is themes: glamour has its own JSON style format, so we either ship a fixed style and ignore your revdiff theme (looks inconsistent) or build a glamour style at runtime from our 23 color fields (workable but tedious to keep in sync). There's also a smaller code-fence issue where glamour does its own syntax highlighting and our chroma layer already does per-line highlighting, so we'd need to pick one path inside fenced blocks or get nested ANSI conflicts.

the proper version is harder. Rendering reflows lines: **bold** text collapses, ## heading may expand to two render rows with an underline, long paragraphs wrap. Annotations are line-anchored against the source, so a render-line to source-line map is needed. Glamour doesn't expose source positions, so this means a custom renderer or a side parser. Search becomes ambiguous (search source or rendered output?). Word-wrap gets contested between glamour's wrapper and our w toggle.

honestly, i'm not convinced the payoff is worth the complexity. Our current view isn't strictly a preview, but with chroma syntax highlighting it's already pretty close. Terminals are limited in how rich a "rendered" view can be: no font sizes for headings, no images, no actual bold beyond ANSI bold. The real delta is markup syntax (**, *, #, backticks) hidden, link URLs hidden, - bullets become •, code blocks framed, blockquotes get a left bar. Real, but to my eye, minor in day-to-day plan review.

curious what's actually hurting your scan. Is it the ** and []() clutter, or smth more specific? If it's just the markup clutter, a narrower "hide markup" mode that strips syntactic markers but keeps lines 1:1 with the source could give most of the value without dragging in a renderer, theme remap, and annotation rework.

[p4elkin]

I built this as a local patch and it has been my daily plan-review path for about a week, so here is a data point on the question you asked — what is actually hurting the scan.

You were right that hiding ** and []() is minor. That was not where the value came from. It is tables and mermaid diagrams. A plan with a mermaid fence is not slightly cluttered in source view, it is unreadable, and a table is worse. That makes this the same request as #244.

On the three complexity concerns, none of them had to be solved:

• Annotation line mapping. Not needed if preview is read-only. P renders the whole document, an allowlist limits the mode to scrolling and a few toggles, and P returns to source to place a line annotation. Two modes with a hard boundary, no render-line to source-line map anywhere. This also answers the blocker you named on feat: Better table rendering #244.
• Themes. A fixed glamour style, DarkStyleConfig, plus ASCIIStyleConfig under --no-colors. The inconsistency you predicted is real and in practice invisible, because the mode is a full-screen render you are in for a few seconds. Building a style from the 23 colors would be the tedious part and I never wanted it.
• Fence double-highlighting. No conflict. Preview is one whole-document render, so the per-line chroma layer is simply not in that path.

Gate is full-context markdown only, i.e. the whole file is present. A markdown file shown as a partial diff refuses to render, which avoids the question of what a reflowed fragment even means.

The mermaid side was the bulk of the work, via mermaid-ascii: fences are pulled out, rendered to box art, and spliced back after glamour so its word-wrap cannot touch them. That library parses only graph, flowchart and sequenceDiagram, so classDiagram and stateDiagram-v2 are transpiled to flowchart source first, and flowchart sources are normalized (shape suffixes, non---> link forms, styling directives) because the parser silently mis-parses them into stray boxes. Across 251 mermaid fences in my own plan corpus: 206 rendered before, 248 after, with gantt and quadrantChart still falling back to raw fence text. Of 138 flowchart and graph fences, 76 drew at least one stray box before the normalization pass and 2 do now.

Not proposing a PR — it is a personal patch and I am not asking you to carry it. Posting because you asked a question in this thread that deserved an answer, and because the annotation-anchoring blocker turned out to be avoidable rather than solvable.

Branch is at https://github.com/p4elkin/revdiff/tree/md-preview if any of it is useful to you or to anyone reading this later. PATCH.md at the root is the rebase playbook and lists exactly which upstream files it touches — six new files carry almost all of it, and the edits to existing files are small and enumerated there.

Example:

Tables


vs

Mermaid (not the best, but usually enough to get the gist)


vs