## Developer Workflow
How to Preview GitHub README.md Locally on Mac
Published March 2026
You edited the README. Now you want to see how it looks before pushing. Here are three ways to do it, from heavyweight to instant.
## Why Preview Locally
Why preview locally?
- Check formatting before pushing. Broken tables, busted links, and mangled code blocks are embarrassing in a public repo. Catch them before
git push. - Work offline. Planes, trains, coffee shops with bad wifi. Your README shouldn't need an internet connection to review.
- Review PR documentation changes. When a pull request updates the README, you want to see the rendered result alongside the code diff.
- Avoid the commit-push-check cycle. Pushing a commit just to see how your README renders on GitHub pollutes your git history and wastes time.
## Method 1
grip (CLI tool)
pip install grip grip README.md
grip renders your Markdown using the GitHub API, so you get pixel-perfect GitHub rendering in your browser at localhost:6419.
Pros
- Exact GitHub rendering (uses their API)
Cons
- Requires Python installed
- Needs a GitHub API token for heavy use (rate-limited otherwise)
- Runs a local server you have to start and stop
- Not offline-friendly (calls the GitHub API)
## Method 2
VS Code built-in preview
Open README.md in VS Code Cmd + Shift + V → preview pane
VS Code has a built-in Markdown preview. Open the file, hit the keyboard shortcut, and a side panel shows the rendered output.
Pros
- Already installed for most developers
- Works offline
Cons
- Launching a full IDE to preview a README is heavy-handed
- Preview rendering doesn't match GitHub exactly (no callout support, different table styling)
- Tied to your editor — can't just double-click a file
## Method 3 (Recommended)
ShowMeMyMD — just double-click
git clone <repo> Double-click README.md Done.
ShowMeMyMD is a native macOS Markdown viewer. Set it as your default app for .md files and every README opens as a rendered preview instantly. No CLI. No server. No setup.
Full GitHub-Flavored Markdown support:
- Tables with alignment
- Task lists with checkboxes
- Fenced code blocks with syntax highlighting
- GitHub-style callouts:
NOTE,TIP,WARNING,IMPORTANT,CAUTION
Clone, double-click README.md, done.
## Comparison
Side-by-side comparison
| Tool | Setup | GFM Accuracy | Speed | Offline |
|---|---|---|---|---|
| grip | Python + pip install | Exact (GitHub API) | Slow (network) | No |
| VS Code | Already installed | Partial | Fast | Yes |
| ShowMeMyMD | Install once from Mac App Store | Full GFM + callouts | Instant | Yes |
## Keep Reading
Learn more about ShowMeMyMD as a Markdown viewer for Mac. See how it fits into a developer workflow. Or read our guide to GitHub-style callouts.
Stop pushing to check your README
Double-click any .md file and see it rendered instantly. GitHub-Flavored Markdown, syntax highlighting, four themes. $2.99 on the Mac App Store.