For a documentation change, review both the readable result and the source difference. Check the branch and path first so you do not compare a proposed edit with the wrong version.
Choose the view that answers your question
GitHub's non-code file documentation, checked October 24, 2026, describes switching Markdown between rendered and source views and reviewing rich differences in prose. Source view exposes the characters and destinations; the rendered view shows what readers will encounter.
If a heading looks wrong, inspect its Markdown markers. If linked text looks unchanged but its destination changed, inspect the URL in the source difference. A readable label can conceal a consequential change to another destination.
Do not expect GitHub's repository Markdown renderer to run arbitrary HTML applications. Supported embedded markup can render, but a Markdown document is a different viewing surface from an executable standalone HTML page.
Resolve a relative link from the Markdown file
Here is an original fictional repository layout:
repo/
assets/diagram.png
docs/guide.md
docs/setup.md
Inside docs/guide.md, this image reference looks in the wrong directory:
Its relative target is docs/assets/diagram.png. In the supplied layout the image actually sits one directory above docs, so the intended reference is:
[Setup instructions](setup.md)
The image path moves up to the repository root and then into assets. The setup link stays alongside guide.md in docs. GitHub's formatting reference documents repository-relative links and images. This example demonstrates path resolution; it does not refer to a real uploaded repository or a completed GitHub test.
Check the branch as well as the spelling
A file can exist in a local working tree while being absent from the branch your reviewer is reading. Confirm that the target is present in the same proposed change, or already exists in the intended branch. Match filename case and extension rather than assuming a local operating system's behavior will carry across.
If the image still fails, open its target directly from the repository file list. Check whether you have the expected file, not just a similarly named one. Keep an explanatory alt description for the diagram; a fixed path does not explain the image to someone who cannot see it.
For an external destination, read the actual address before opening it and verify it belongs to the intended source. For an internal target, compare the resolved location with the supplied tree.
Review a prose change in both forms
Imagine a change that leaves the label “Setup instructions” intact but replaces setup.md with an external download address. The rendered sentence may look almost identical. The source difference exposes the destination change, so review it explicitly before treating the edit as a minor wording correction.
Use the rich difference for reading order, deleted qualifications and formatting changes. Return to the source difference for URLs, code fences, hidden comments or markup that the readable view does not fully expose. Neither view replaces checking the documented commands in their actual environment.
The README template guide covers what a newcomer needs in project instructions. GitHub Pages conversion concerns a separately built website. For repository review, finish by opening the intended links on the correct branch and confirming that the rendered change and source change tell the same story.