Preview GitHub Markdown Before You Push

To preview GitHub Markdown before you commit, you have four options. Use GitHub's own Preview tab, install the GitHub Markdown Preview pack in VS Code, paste the file into an online editor, or render it through the Markdown API. This guide walks through each one and shows which GFM features it gets right.

Does GitHub Have a Built-In Markdown Preview?

Yes, and it's the most accurate one available because it uses GitHub's real renderer. Open any .md file in your repository, click the pencil icon, and a Preview tab appears above the editor. Nothing is committed until you press "Commit changes", so you can preview, tweak and abandon the edit freely. The same tab exists in every issue, pull request and discussion comment box, and in gists.

The GitHub Docs page on editing files describes the flow. The catch is that it only works for content already on GitHub. If you're writing a README locally and want to check it before the first push, you need one of the next three methods. A fast middle ground: press the period key on any repo page to open github.dev, a browser copy of VS Code with the built-in preview.

Method 2: GitHub Markdown Preview in VS Code

VS Code's default preview (Ctrl+Shift+V, or Cmd+Shift+V on a Mac) renders CommonMark plus tables and strikethrough. The rest of GFM is missing. The GitHub Markdown Preview extension pack by Matt Bierner fixes that. As of version 0.4.0 it installs four extensions:

• bierner.markdown-preview-github-styles (Markdown Preview GitHub Styling) applies GitHub's CSS so headings, tables and code blocks look the same.
• bierner.markdown-emoji renders :tada: style shortcodes.
• bierner.markdown-checkbox renders - [ ] task lists.
• bierner.markdown-footnotes renders [^1] footnotes.

Install it from the Marketplace listing, then open the preview to the side with Ctrl+K V. Mermaid diagrams and math still need separate extensions, and GitHub alerts don't render at all. For the wider VS Code setup, including linting and pasting images, see our VS Code Markdown guide. This post sticks to preview fidelity.

Method 3: Preview GitHub Markdown Online

When you don't want to install anything, paste the file into a browser-based GitHub Markdown viewer such as our editor. Our editor renders GFM tables, task lists, strikethrough, fenced code, Mermaid diagrams and $...$ math, so the bulk of a README looks the way GitHub shows it. The sample below is deliberately tricky: it mixes an alert, a task list, a right-aligned table, a footnote and an emoji shortcode.

In our testing the table, task list and math render identically to GitHub. The alert shows as a plain blockquote with a literal [!NOTE], the emoji shortcode stays as text, and the footnote marker stays as [^1]. Knowing exactly which three things differ is the point: everything else you see is what GitHub will show.

Method 4: Render Locally with the GitHub Markdown API

GitHub exposes the same renderer over REST. POST your text to /markdown with mode set to gfm and you get back the HTML GitHub would produce, alerts and task lists included. In our testing the endpoint answers without a token, though authenticating raises the rate limit.

curl -s -X POST https://api.github.com/markdown \
  -H "Accept: application/vnd.github+json" \
  -d '{"text":"> [!TIP]\n> Rendered by GitHub.\n\n- [ ] task","mode":"gfm"}' > preview.html

Open preview.html in a browser. The markup carries GitHub's class names (markdown-alert, task-list-item), so it looks unstyled until you add a stylesheet such as the open source github-markdown-css. This is the most faithful local option and the least convenient, which is why we reach for it only when an alert or a diagram misbehaves. Details and limits are on the Markdown REST API page.

Which GFM Features Do Generic Previewers Get Wrong?

GitHub layers a lot on top of CommonMark, and this list is where previews diverge. Check each row against the tool you're using.

Feature	Syntax	GitHub	VS Code default	VS Code plus pack	Our editor
Alerts	> [!NOTE]	Yes	No	No	No
Task lists	- [ ]	Yes	No	Yes	Yes
Footnotes	[^1]	Yes (not in wikis)	No	Yes	No
Emoji shortcodes	:tada:	Yes	No	Yes	No
Mermaid	```mermaid	Yes	Needs extension	Needs extension	Yes
Math	$x^2$	Yes	Needs extension	Needs extension	Yes
Relative image paths		Yes	Yes	Yes	No

Two behaviours deserve a closer look. GitHub renders math with MathJax using $, $$ and ```math fences in issues, discussions, pull requests, wikis and Markdown files, per the docs on mathematical expressions.

Single line breaks differ by context. In a .md file GitHub folds a lone newline into the paragraph, while in issue comments it becomes a hard break. Our editor treats every newline as a break, so a README that relies on wrapped source lines will look tighter on GitHub than in the preview.

For diagrams specifically, GitHub also renders GeoJSON, TopoJSON and STL fences. If a flowchart looks wrong after pushing, the Mermaid diagrams guide covers the version differences that cause it.

Which Preview Should You Use Before Pushing?

We prefer the VS Code pack for day-to-day writing and the Preview tab for the final check, because the two together cover every GFM feature. If you're on a machine without VS Code, the online editor gets you most of the way and the API closes the gap. Whichever you choose, preview the file in the same context it will live in: a README in the file editor, an issue template in an issue.

One limitation applies to all four methods. None of them show GitHub's dark theme, the repo sidebar, or the fixed content width that decides where long tables scroll. If layout matters, push to a branch and look at the rendered file on GitHub before merging.

Then run through this checklist in whichever preview you chose. It takes two minutes and catches the problems that survive most previewers.

1. Heading anchors. GitHub lowercases headings and swaps spaces for hyphens, so ## Getting Started becomes #getting-started. Test every table-of-contents link.
2. Table alignment. The delimiter row needs at least three dashes per column, with colons where you expect them.
3. Image paths. Relative paths resolve against the file's folder on the current branch. A leading / will 404 on GitHub.
4. Line breaks. For a real break in a .md file, end the line with two spaces or a backslash.
5. Alerts. One per blockquote, never nested. GitHub Docs states that alerts cannot be nested within other elements.
6. Code fences. Every opening fence has a closing fence and a language tag GitHub's highlighter knows (js, ts, sh).

The syntax behind each item is in the GitHub Markdown cheat sheet, and the content side of a README is covered in the README Markdown guide.

Common GitHub Markdown Preview Mistakes

Trusting a CommonMark-only preview. Many editors, and many extensions marketed as a markdown viewer GitHub style, stop at CommonMark. A README that looks fine there can lose its checkboxes and alerts on GitHub. Use one of the four methods above, all of which are GFM-aware or GitHub itself.

Previewing in an issue, shipping in a file. Because issues turn single newlines into breaks and .md files don't, a comment-box preview can hide spacing problems. Preview file content in the file editor.

Absolute image paths. ![logo](/assets/logo.png) resolves to the site root on GitHub, not your repo. Write assets/logo.png or ./assets/logo.png.

Preview GitHub Markdown FAQ

Any of the four methods lets you preview GitHub Markdown before it lands in the repo. Use the Preview tab for accuracy, the VS Code pack for daily editing, and the API for the odd alert or diagram. Open the editor when you want a zero-install check right now. Paste your README in, run the checklist above, and push with the formatting already confirmed.