How to preview your readme the way github will render it
- Step 1Load your README — Switch to Upload and drop your local
README.md, or paste its contents into the editor. One file per run. - Step 2Run the preview — Click Run. marked converts the Markdown with GFM enabled and the dark Primer theme is applied in the iframe preview. There are no options to set.
- Step 3Scan the layout — Read top-to-bottom for the usual offenders: tables that did not align, lists that lost nesting, badge rows that wrapped, headings at the wrong level.
- Step 4Check GitHub-only syntax — If you used
[!NOTE]alerts, footnotes, or math, confirm how they degrade here (they stay literal) so you are not surprised on github.com. - Step 5Fix in your editor and re-run — Edit the source, paste again, and re-run. Iterate until the preview is clean — far cheaper than a fixup commit after the push.
- Step 6Optional: keep a styled copy — Download
<name>-github.htmlto share the rendered look with a teammate. Remember it needs internet for the CDN theme; for an offline artifact use md-to-html.
README problems this preview catches (and misses)
What you can reliably verify in the preview versus what you cannot, based on marked 14.1.4 default behaviour and the dark Primer stylesheet.
| README element | Caught in preview? | Why |
|---|---|---|
| Pipe table alignment / column count | Yes | marked renders GFM tables; misaligned or short rows are visible immediately |
| Nested / ordered list structure | Yes | List nesting is rendered faithfully by marked |
Task-list checklists (- [ ]) | Yes | Rendered as checkboxes, like GitHub |
| Badge / shield image rows | Yes (absolute URLs) | Shields.io and raw.githubusercontent URLs load in the preview |
Relative image paths (./img.png) | No | iframe srcDoc has no base origin, so relative paths show broken |
[!NOTE] / [!WARNING] callouts | No | Not a callout here — [!NOTE] shows as literal blockquote text |
| Footnotes | No | Not implemented by marked default — links break |
| Light-mode appearance | No | Preview is dark-only; layout matches but colours differ in light mode |
Preview vs. saved file
Two different artifacts. The in-app preview always has network access via the iframe; a downloaded file depends on the viewer's connection.
| Concern | In-app preview | Downloaded .html |
|---|---|---|
| Primer CSS source | CDN <link> (loads in sandboxed iframe) | Same CDN <link> — needs internet to style |
| Theme | Dark (fixed) | Dark (edit <link> for light) |
| Relative images | Broken (no base origin) | Broken unless served from a matching path |
| Best for | Pre-push layout check | Sharing the rendered look with a teammate |
Cookbook
Real pre-push checks, shown as the README snippet you paste and what the preview reveals. The <head> boilerplate is identical every run and is omitted.
Spotting a short table row before it ships
A row with one fewer cell than the header is easy to miss in raw Markdown but obvious in the rendered table.
Input: | Name | Type | Default | |------|------|---------| | port | int | 8080 | | host | string | Preview reveals: the 'host' row renders with an empty third cell (Default column blank) — fix the source before pushing so the table reads correctly on github.com.
Badge row with absolute URLs renders
Shields and raw GitHub image URLs are absolute, so they load in the preview iframe.
Input: [](https://github.com/acme/acme/actions) [](https://npmjs.com/package/acme) Preview: both badges render side by side and are clickable, matching how the README header will look once pushed.
Relative logo path shows broken — switch to raw URL
A common surprise. Relative image paths cannot resolve in the preview, so swap to an absolute raw URL to confirm the image works.
Broken in preview:  Works in preview (and on GitHub):  On github.com the relative path resolves once committed, but the preview cannot resolve it — use the raw URL to verify.
Review-checklist README
Contributor-guide READMEs often embed a checklist. The preview confirms the checkboxes render before the first PR author sees it.
Input: ## Before opening a PR - [ ] Tests pass locally - [ ] Docs updated - [ ] Changelog entry added Preview: three unchecked, disabled checkboxes under the heading — exactly the GitHub appearance.
An alert you thought would be a callout
Maintainers migrating to GitHub's alert syntax should preview here to see it does NOT become a callout in this tool.
Input: > [!IMPORTANT] > Run `npm run build` before publishing. Preview output: <blockquote> <p>[!IMPORTANT] Run npm run build before publishing.</p> </blockquote> The coloured callout box appears on github.com, not here.
Edge cases and what actually happens
Preview needs internet for the theme
By designThe iframe loads github-markdown-dark.min.css from cdnjs. Offline, the preview shows the body unstyled. The structure is still correct, so layout checks (table shape, list nesting) still work — only the GitHub look is missing.
Relative image paths look broken
ExpectedThe preview iframe uses srcDoc with no base URL, so ./img.png cannot resolve and shows a broken image. On github.com the same path resolves once committed. To verify an image in the preview, use its absolute raw.githubusercontent.com URL.
Preview is dark-only
By designThere is no light/dark toggle. If your README viewers use GitHub light mode, the colours differ but the layout is identical, so the preview is still valid for catching structural problems.
GitHub alert callouts are not rendered
Not supported[!NOTE], [!TIP], [!WARNING], [!IMPORTANT], [!CAUTION] show as literal text in a plain blockquote. Preview here mainly to confirm you understand the degradation — they will only become callouts on github.com.
Footnotes do not link
Not supportedmarked default does not implement footnotes, so [^1] becomes a broken link and the definition is loose text. Restructure footnotes inline if they must read correctly in the preview and saved file.
Math renders as plain text
Not supported$...$ and $$...$$ are printed verbatim — no math engine is loaded. GitHub renders math server-side; the preview cannot replicate that.
Code blocks are not colour-highlighted
ExpectedFenced blocks get a language-xxx class but no highlighter runs, so the preview shows monospaced, boxed code without syntax colours. This is faithful to layout, just not to GitHub's coloured tokens.
README exceeds the free character cap
rejectedFree tier limits input to 500,000 characters / 1 MB. A very large monorepo README can exceed this and is rejected before preview. Pro raises the cap to 5,000,000 / 10 MB.
Trying to preview several READMEs at once
rejectedOne file per run. To preview a docs set as a single page, merge first with md-merger and preview the combined file.
Empty README
ExpectedAn empty input produces a styled but blank page with no error — useful to confirm the wrapper, not the content.
Frequently asked questions
Will this preview match what contributors see on GitHub?
For headings, tables, lists, blockquotes, code, task lists, strikethrough, and autolinks — yes, because it uses GitHub's own dark Primer stylesheet over marked's GFM output. It will differ for [!NOTE] alert callouts, footnotes, math, and @mention links, which marked does not implement.
Do I need to be online?
The preview loads Primer CSS from CDN, so yes — online the styling appears, offline you see the correct structure unstyled. A downloaded file is likewise styled only when the viewer is online.
Can I preview in light mode?
Not in the tool — the theme is fixed dark. Layout is mode-independent, so dark preview still catches structural bugs. For a light file, edit the downloaded <link> to the light Primer build.
Why are my relative images broken in the preview?
The iframe has no base origin, so ./img.png cannot resolve. They will work on github.com once committed. To verify in the preview, point the image at its absolute raw.githubusercontent.com URL.
Does it render my task-list checkboxes?
Yes — - [ ] and - [x] become disabled checkboxes, exactly as GitHub shows them. This makes it reliable for previewing contributor checklists.
What about GitHub's NOTE/TIP/WARNING callouts?
They are not rendered as callouts. marked treats > [!NOTE] as an ordinary blockquote and leaves [!NOTE] visible. Expect the coloured box only on github.com.
Is anything uploaded?
No. The whole conversion runs in your browser, so unreleased README content stays local. If the README might contain a token, sanitise it first with md-secret-redactor.
What files can I drop?
.md, .mdx, .markdown, .txt, or pasted text — one at a time. Multiple files are not accepted.
How big can the README be?
Free: 1 MB / 500,000 chars. Pro: 10 MB / 5,000,000. Pro-media: 50 MB / 20,000,000. Developer: 500 MB / unlimited. Both byte and character limits apply.
I want a PDF of the README to attach to a release — how?
Use md-to-pdf-modern. This tool only emits HTML.
My heading anchor links do not jump correctly — why?
marked's heading slugs may differ from the hand-written anchors you targeted for GitHub. Regenerate the TOC against this engine with md-toc-generator so links resolve.
How do I make a fully self-contained preview to email?
Use md-to-html, which inlines its styles into one portable document. This GitHub tool links the theme from CDN by design.
Privacy first
All Markdown processing runs locally in your browser using JavaScript. No file is ever uploaded to JAD Apps servers — only metadata counters are saved for signed-in dashboard stats.