md-review

Converts markdown code reviews with diff blocks into single-file two-column HTML review pages.

25.3k|3.6k|Updated Oct 19, 2025
One-click install
npx skills add https://github.com/alirezarezvani/claude-skills --skill md-review
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: md-review
Source: https://github.com/alirezarezvani/claude-skills/tree/main/markdown-html/skills/md-review
Command: npx skills add https://github.com/alirezarezvani/claude-skills --skill md-review

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve?

Markdown PR writeups with diff blocks and severity callouts are hard to read and share; this Skill turns them into a polished, self-contained HTML review artifact with a findings jump-nav, side-by-side diff and annotation layout, and a mandatory named reviewer footer.

Core Features & Use Cases

  • Three-stage stdlib pipeline: diff_parser.py extracts unified-diff hunks from ```diff fenced blocks, annotation_extractor.py attaches severity-tagged callouts (BLOCKER/MAJOR/MINOR/NIT) to the nearest hunk, and review_html_renderer.py emits the final single-file HTML.
  • Accessible severity badges: every badge ships color plus icon plus aria-label plus text, enforcing WCAG 1.4.1 so severity is never conveyed by color alone.
  • Strict refusal rules: refuses to render without a --reviewer name, without diff hunks (routes to md-document instead), or for inputs under 100 lines.
  • Use Case: A reviewer writes PR feedback in markdown with ```diff blocks and > [!MAJOR] callouts, then runs the pipeline to produce review.html with a jump-nav listing findings, per-hunk annotation cards, and a reviewer footer ready to share with the team.

Quick Start

Convert my markdown PR review file review.md into a single-file HTML code review with reviewer name Jane Doe and title PR #123.

Frequently Asked Questions about md-review

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I convert a markdown code review to HTML?

Run three stdlib Python scripts in sequence: diff_parser.py extracts diff hunks to JSON, annotation_extractor.py attaches severity callouts to hunks, and review_html_renderer.py renders the final single-file HTML. The renderer requires a --reviewer name and refuses to run without one.

What severity levels does the code review converter support?

The default convention is BLOCKER, MAJOR, MINOR, and NIT, following the Google Code Review Developer Guide. You can pass a custom tier list via --severity-convention, where position 0 is the most severe tier.

Does the HTML review output require external dependencies?

No. All three scripts are Python standard library only, and the output is a single HTML file with inline CSS. The only external reference is a Google Fonts stylesheet for typography.

Why does the renderer refuse to generate my review HTML?

Rendering is refused when --reviewer is missing (exit 3), when no diff hunks exist in the input (exit 4, route to md-document instead), or when the input is under 100 lines. A code review must name a human reviewer and contain actual diffs.

How are review annotations matched to diff hunks?

Each severity callout or inline marker is attached to the nearest preceding diff block by source line number. Annotations with no preceding diff are treated as unanchored and rendered in a general comments section at the bottom.

Is the severity color coding accessible for colorblind readers?

Yes. Every severity badge combines color, a distinct Unicode icon, the severity text label, and an aria-label, satisfying WCAG 1.4.1 so color is never the sole signal. Diff lines also use plus/minus mark columns alongside tinted backgrounds.