How to preview a README before pushing it to GitHub

Updated 15 October 2026. Tool details follow each project’s own documentation.

What a local preview can get wrong

GitHub adds things that general Markdown renderers don’t know about:

• Relative links and images. GitHub rewrites relative links to match the branch you are viewing, so docs/setup.md works on any branch.
• Alerts. A blockquote starting with [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] or [!CAUTION] becomes a coloured alert. Elsewhere it is usually a plain quote.
• Diagrams. GitHub draws Mermaid, GeoJSON, TopoJSON and ASCII STL code blocks.
• Which README wins. If there is more than one, GitHub shows the one in .github, then the root, then docs. Content past 500 KiB is cut off.

Option 1: GitHub’s renderer, on your machine

The gh-markdown-preview extension renders the HTML returned by GitHub’s Markdown API and styles it with CSS taken from github.com. Its author describes the result as “almost the same” as GitHub.

1. Install the extension

   With the GitHub CLI installed, run gh extension install yusukebe/gh-markdown-preview.

2. Start the preview

   In the repository folder, run gh markdown-preview. With no file name it looks for the README in the current directory. It serves the page at localhost:3333.

3. Edit and watch

   Keep the browser tab open while you edit. Live reload is on by default, so saved changes appear without refreshing.

4. Check the result on GitHub

   After pushing, open the repository page once to confirm images, relative links and anything GitHub-specific.

Because rendering happens on GitHub’s servers, you need a connection, and your README’s text is sent to GitHub. Grip (pip install grip, then grip, served at localhost:6419) works the same way and may hit GitHub’s hourly API limit unless you give it credentials.

Option 2: the Preview tab on github.com

For a small fix you can skip the local preview. On github.com, open the file, click the pencil icon, make your change and click Preview above the text. Nothing is saved until you click Commit changes. This is GitHub’s real renderer, but you edit in the browser rather than in your own editor.

Option 3: VS Code’s preview

Open the README in VS Code and press Ctrl+K then V (⌘K V on a Mac) for a preview beside the source that updates as you type. It works offline and draws Mermaid diagrams and math. It is VS Code’s renderer, not GitHub’s, so check alerts and relative links on GitHub afterwards.

Option 4: read it in Chrome with Quire Markdown

Quire Markdown is our extension, free on the Chrome Web Store. Choose Open file and pick the README, then turn on Follow file: the rendered page updates each time you save. The heading outline shows at a glance whether your sections are in the order you meant, and tables, task lists and highlighted code look finished.

It is a reader, so it deliberately skips some of what GitHub does:

• Images show as “[Image not loaded: …]” with their alt text, which at least confirms each one has alt text.
• Relative links such as docs/setup.md appear as plain text, because there is no repository to resolve them against.
• Alerts appear as ordinary quotes, footnotes aren’t rendered, and diagrams and math aren’t drawn.
• It opens UTF-8 files up to 2 MB, and it never changes your file.

Questions

More guides

• How to view Markdown (.md) files in Chrome
• How to watch a Markdown file update live while it is edited
• How to get syntax highlighting in Markdown code blocks
• Why images don’t show in a Markdown preview
• How to view Mermaid diagrams in a Markdown file

All guides · Quire homepage