← Markdown Review

Blog

Reviewing Markdown, in depth

The human review layer for Markdown-heavy and AI-generated pull requests. These are field notes on reading changes closely: source and rendered result together, section by section, without losing your place.

  1. How to review Markdown changes in a GitHub pull request

    What GitHub actually gives you for reviewing a Markdown PR, the order to use it in, and what to do when the document gets too long for it.

    review markdown changes in github

  2. How to review AI-generated specifications without rubber-stamping them

    AI can write a 1,500-line specification in minutes. The review still has to be done by a human. Here is a workflow for reviewing large AI-generated specs carefully instead of skimming them.

    reviewing AI-generated specifications

  3. Source diff vs. rich diff: why reviewing Markdown in a GitHub PR is harder than it should be

    GitHub's source diff is reviewable but hard to read. Its rich diff is readable but hard to review. Here is why that trade-off exists and how to stop making it.

    source diff vs rich diff