nicemd

Guides

Previewing a README on your Mac

The commit-push-refresh loop to check whether your README looks right is a slow way to proof a document. It renders locally in one keystroke.

Updated September 11, 2026

A README is one of the few documents that gets written once and read by everyone. It is also, on a Mac, strangely hard to look at. The usual workflow is: edit, commit, push, switch to the browser, refresh, notice the table is wrong, edit again.

That loop exists because GitHub renders Markdown and your Mac does not. Closing it locally takes about a minute of setup and removes a surprising amount of friction — not just for your own repos, but for every README sitting in a folder you cloned and never read.

The fast path: Space in Finder

Select README.md in Finder, press Space, read it, press Space again. That is the whole interaction, and it works from any folder without opening a project.

macOS does not render Markdown in Quick Look on its own — it has no preview generator for the format, so you get raw source until you install an app that provides one. Markdown Quick Look on macOS covers the how and the why; the short version is install, launch once, done.

This matters most for repos you did not write. Cloning something, opening the folder, and pressing Space on the README is a far lower-effort way to find out what a project is than opening it in an editor.

The proofing path: a window you leave open

When you are actively writing the README, Quick Look is the wrong shape — you want a window that stays up and updates. Open the file in a Markdown viewer that reloads on change, put it beside your editor, and the loop becomes: save, glance.

One thing to check when choosing: whether the viewer survives how your editor saves. Many tools — and essentially every coding agent — write a temporary file and rename it over the original rather than editing the file in place. Naive file watchers follow the old file and go quiet. Why previews go stale explains the mechanism and how to test yours in about ten seconds.

What local rendering will and will not match

GitHub renders GitHub Flavored Markdown, which is CommonMark plus a specific set of extensions. A viewer built on the same spec gets you an accurate preview of nearly everything that matters:

  • Tables, including alignment — the thing people most often get wrong and want to check.
  • Task lists, rendered as checkboxes.
  • Fenced code blocks with language-tagged syntax highlighting.
  • Strikethrough, autolinked URLs and footnotes.
  • Mermaid diagrams, which GitHub has rendered in Markdown for years and which most local viewers still do not — see viewing Mermaid on a Mac.

Some things are GitHub-specific and will not match locally, and it is better to know which:

  • Relative links to other files in the repo resolve against the repository on GitHub. Locally they resolve against the folder, which is usually equivalent — but links into blob/main/… paths are not.
  • Badges are remote images. They render only if the preview can reach the network, and Quick Look previews generally cannot load images at all.
  • Alerts (> [!NOTE] and friends) are a GitHub extension. A local viewer may show them as a plain blockquote.
  • Emoji shortcodes like :rocket: are GitHub's, not CommonMark's.
  • Auto-generated heading anchors exist locally, but the exact slug GitHub produces for a heading with punctuation in it may differ.

For proofing structure — headings, tables, code, lists, the overall shape of the document — local rendering is exact. For the last five percent of polish on a public README, one final look on GitHub after pushing is still worth doing. The point is to make that the last step rather than the only one.

Images in a README

READMEs usually reference a screenshot or two stored next to the file. In a full viewer window those show once the app has access to the folder. In Quick Look they generally do not: a preview extension runs sandboxed and cannot ask you for permission to read the surrounding folder, so a well-behaved one falls back to alt text.

That is a reason to keep alt text meaningful, and a reason to open the file properly when you are specifically checking how the images sit.

nicemd

nicemd renders GitHub Flavored Markdown through cmark-gfm — the same parser family GitHub's own rendering is built on — with Mermaid, math and syntax highlighting bundled offline. Reading and Quick Look are free, so previewing a README costs nothing and needs no account.

Related: opening .md files on a Mac and reading the Markdown your coding agent writes.