How to preview Markdown in Finder

Understand macOS Quick Look, Markdown extensions and the move from a quick preview to a connected folder.

How do I preview a Markdown file in Finder?

Quick Look is Apple's file-preview feature: select a file in Finder and press Space. Apps can provide extensions that render additional formats. A Markdown extension can turn source characters into headings, tables and code inside that preview. It is not a feature invented by a particular Markdown app.

See Apple's Quick Look guide and extension documentation.

Start with a small known file

Download the Project Reading Kit, unzip it, and select specification.md in Finder. Press Space. If the content is formatted, an installed renderer is supplying that preview. If you see literal hashes and pipes, you are looking at source rather than a rendered Markdown page.

The specification is fictional. Its headings, acceptance criteria and links provide a more useful check than an empty file with a single heading.

Use a compatible extension

Install a Markdown reader or Quick Look extension that supports your macOS version, follow its registration instructions, then preview the same known file again. Several applications provide this; choose for your workflow rather than installing multiple previewers at once.

Aero Markdown includes a Quick Look extension in the project, but the Mac download is not available yet. While it is being prepared, you can read the example in the browser or use another compatible application. The browser reader does not install a Finder extension.

Check the right system setting

On macOS versions with General → Login Items & Extensions, look for Quick Look in Extensions. Earlier supported versions arrange extension controls differently; search System Settings for Extensions if that path is not present.

If a renderer is already installed but no longer appears, check that the application is installed where its instructions require, that its extension is enabled, and whether another Markdown extension is handling the file. The exact registration behaviour depends on the application and macOS version.

Default app and preview are different choices

Setting an app under Get Info → Open with determines what opens on double-click. Quick Look uses a preview extension. Changing one does not guarantee the other changes.

Use preview for a short inspection. When a specification points to architecture and decisions, open the containing folder in your reader to follow that context. The folder guide shows the next step in Aero Markdown.

What to check in the example

Find Outside this proposal in the specification. Notice that the first version excludes automatic sync and shared editing. Follow the architecture and decision-log links in a compatible app for the longer read. A useful preview should help you notice the document's structure, not encourage you to approve a proposal without reading it.