The short answer
To check how a file will look on GitHub, use GitHub's own preview, or a tool that calls GitHub's renderer. To read a Markdown file that is still on your disk, private, not yet committed, or being rewritten by an agent, open it in MarkdownPaper.
Where GitHub is the better choice
- It is the real thing. GitHub's rendering is, by definition, what visitors to your repository will see. MarkdownPaper's is close, with its own typography, but it is not GitHub's.
- GitHub's own syntax. Emoji shortcodes such as
:rocket:,@mentionsand#123references, and GeoJSON and TopoJSON maps and STL models. MarkdownPaper leaves these as plain text. GitHub's alerts,> [!NOTE]and its four siblings, it does render, as callouts set in the page's own ink rather than in GitHub's colours. - Relative images and links. GitHub rewrites a relative path such as
docs/logo.pngfor whichever branch you are on, so it always works. MarkdownPaper loads relative images in a README opened from a GitHub link, and in the desktop app from beside a file on your disk, but not in the browser for a local file, and not paths that start at the repository's root. It follows links to other documents you have opened. - The repository around the file. History, blame, pull request review, comments and the Outline menu on a README are all a click away.
Both render Mermaid diagrams, and both render math, including GitHub's
math code fence; GitHub draws math with MathJax and MarkdownPaper with
KaTeX.
Where MarkdownPaper is the better choice
- Before you push. A draft, a local branch, or a file that will never be committed renders the moment you open or paste it. The MarkdownPaper desktop app keeps the page current while you, or a coding agent, rewrite the file.
- Nothing leaves your machine. The document is rendered in your browser or the desktop app. Tools that match GitHub exactly do so by asking GitHub: grip, the best known, sends your file to GitHub's Markdown API to render it, within GitHub's hourly rate limits.
- Reading long documents. Text is set to a measure counted in characters, 74 by default, in a serif made for reading, with the contents in the page margin and the few controls faded out while you read.
- Handing it to someone without access. A share link carries the whole document inside the link, so a colleague can read one file without being given the repository. Print gives real page margins for a PDF, and a rendered page copies into Google Docs with its tables intact.
Side by side
| GitHub | MarkdownPaper | |
|---|---|---|
| Renders | Files on GitHub, and the Preview tab while editing there | Files on your disk, pasted text, public GitHub links |
| Matches GitHub exactly | Yes | Close, with its own typography |
| Alerts | Coloured boxes | Callouts in the page's ink |
| Emoji shortcodes, mentions | Rendered | Shown as plain text |
| Relative images | Resolved for the branch | From a GitHub link, or beside the file in the desktop app |
| Math and diagrams | MathJax, Mermaid, maps and 3D models | KaTeX and Mermaid |
| Private files | Need access to the repository | Never leave your machine |
| Print and PDF | The browser's own print | Print with page margins |
Previewing a README before you push
Three ways, depending on what you need:
- Exactly as GitHub will show it: edit the file on GitHub and use the Preview tab, or run grip locally, knowing that grip sends the file to GitHub to render.
- While writing in a code editor: VS Code's built-in preview sits beside the source. The VS Code comparison covers it.
- To read it properly, privately: open the file in MarkdownPaper, or drop it on the web reader. Expect emoji shortcodes and mentions to differ from GitHub, and relative images to show only in the desktop app.
Price
Reading Markdown on GitHub is free, and public repositories need no account. grip is free and open source. The MarkdownPaper web reader is free too, with no account and no limits.
The MarkdownPaper desktop app: Coming soon to the Mac App Store and the Microsoft Store. $6.99 launch price, paid once, with no subscription. About the desktop app.
Questions
Why does my README look different on GitHub?
Usually for one of three reasons: GitHub renders syntax of its own, such as emoji shortcodes and mentions, that other renderers do not; relative image paths resolve against the repository on GitHub and against something else elsewhere; and GitHub applies its own stylesheet. The Markdown is the same; the renderer is not.
Does MarkdownPaper support GitHub alerts?
Yes. All five kinds, Note, Tip, Important, Warning and Caution, are set as callouts with a label and an icon. They take the page's own ink rather than GitHub's colours, with Warning and Caution in the accent, so they print cleanly on any of the three paper stocks.
Can MarkdownPaper open a file from a GitHub link?
Yes, for public files. Paste a GitHub file link, a raw link or a gist, and the reader fetches the Markdown behind it; the README viewer page covers this. Private repositories are not reachable, because MarkdownPaper never asks for your GitHub account.