Your README Renders Differently on GitHub and in VS Code: What Works Where

You write a README in VS Code, check the preview, push, and the repo page looks different. Sometimes better: the checkboxes you typed are real checkboxes now. Sometimes it goes the other way, and the note you were proud of in the preview turns out to need syntax the preview never understood.

The reason is simple. GitHub and VS Code use different Markdown renderers, and each one supports a different set of extras on top of the basics. We rendered the same README through both to see exactly where they split.

How we tested

We wrote one README with every feature people reach for: an alert, a task list, a table, inline math, a Mermaid diagram, a footnote and a collapsible <details> block. Then we rendered it two ways on October 30, 2026:

• GitHub: through GitHub's own Markdown API in gfm mode, the same renderer the repo page uses.
• VS Code: through markdown-it, the engine behind VS Code's built-in preview, with the options VS Code sets (HTML on). We checked the extension's source to see which plugins it loads. Out of the box it adds front matter and math (the built-in Markdown Math extension, on by default), and nothing else.

You can reproduce the GitHub half yourself with the GitHub CLI:

jq -Rs '{text: ., mode: "gfm"}' README.md | gh api -X POST /markdown --input - > preview.html

Open preview.html and you're looking at the HTML GitHub would put on your repo page, minus the styling.

Same file, both renderers. Tables, code and <details> match, but alerts, task lists and footnotes don't.

What renders where

VS Code's built-in preview with no extensions installed.

The pattern: everything from CommonMark plus tables and strikethrough works in both. Four GitHub extras don't show up in VS Code's preview.

Task lists

- [x] Streaming parser
- [ ] Worker threads

GitHub draws checkboxes. VS Code's preview shows a bullet followed by [x] or [ ]. Nothing is broken, the preview just doesn't know the syntax, so a roadmap looks unfinished in the editor and fine on the repo page.

Alerts

> [!NOTE]
> Requires Node 20 or later.

GitHub turns this into a colored callout with an icon. There are five types: NOTE, TIP, IMPORTANT, WARNING and CAUTION. In VS Code's preview it's a normal blockquote that starts with the literal text [!NOTE]. That's also what most other Markdown renderers will show, so if your README gets read in places other than GitHub, keep the sentence inside the alert readable on its own.

Footnotes

[^1] becomes a superscript link and a Footnotes section on GitHub. In VS Code it stays as [^1], and the footnote definition shows as an ordinary paragraph.

Mermaid diagrams

A fenced block marked mermaid becomes a diagram on GitHub. In VS Code's preview it's a code block. If the diagram is the only place a piece of information lives, add one sentence of text next to it.

What works everywhere

These rendered identically in both, and they're the safe core for any README:

• Headings, lists, links, emphasis and ~~strikethrough~~.
• Fenced code blocks with a language tag. Always tag them (bash, js, json), because that's what turns on syntax colors.
• Tables, which are the clearest way to document options and flags.
• <details> with a <summary> for long sections like a changelog or a full config reference. Leave a blank line after <summary> so the Markdown inside is still parsed.
• Math, with $...$ inline and $$ blocks.

Three habits that keep a README portable

Use absolute URLs for images that leave GitHub. A relative path like ./docs/screenshot.png works on the repo page, because GitHub resolves it against the repo. Anywhere the file is copied on its own, that path points at nothing. If your README also ships inside a package, link images with full https:// URLs.

Remember the package page is a snapshot. npm shows the README that was inside the version you published. Fixing a typo on GitHub doesn't change npm until you publish again, so read the README once more before npm publish.

Don't lean on raw HTML for layout. GitHub sanitizes HTML: no <style>, no scripts and no style attributes. <details>, <summary>, <picture>, <img width> and align on a paragraph are the parts that reliably make it through.

Previewing closer to GitHub

If you want VS Code's preview to match GitHub, the fix is extensions. Matt Bierner's preview extensions add checkboxes, Mermaid, emoji and GitHub's styles to the built-in preview, one feature each. They're worth it if READMEs are a big part of your week.

If you'd rather not set up an editor at all, our free online README editor opens on a README.md template with the sections people look for: what it is, features, install, usage, configuration, contributing and license. Task lists render as checkboxes, code blocks get syntax colors and a copy button, and tables get handles for adding rows and columns. It saves in your browser as you type, and File > Download > Markdown gives you README.md to commit. There's no account, and your draft is never uploaded.

The usage and configuration sections of the template, formatted while you type.

For alerts and footnotes, the last check is still GitHub itself, so push to a branch and look before you merge. Our GitHub Markdown guide has the full syntax for all five alert types, footnotes and the line break rules that catch everyone.

On a Mac, there's one more shortcut: select README.md in Finder and press Space. With TypeFire installed, Quick Look shows it formatted instead of as raw text:

The short version

• GitHub and VS Code use different renderers. Tables, code, <details> and math match, but task lists, alerts, footnotes and Mermaid render on GitHub only.
• jq -Rs '{text: ., mode: "gfm"}' README.md | gh api -X POST /markdown --input - shows you GitHub's output before you push.
• Use full image URLs if the README travels, and re-read it before you publish a package.

Which GitHub-only syntax has caught you out in a preview?