Quick Look and a reader answer different questions
Press Space on a Markdown file in Finder and macOS shows a Quick Look preview. Out of the box, many Macs show the raw text. QLMarkdown is a free extension that turns that preview into a formatted page, and it is one of the most common answers to "how do I preview Markdown in Finder?".
That job is deliberately narrow. QLMarkdown's own README says the application "is not intended to be used as a standalone markdown file editor or viewer". It gives you a fast look at one file without opening anything. A reader such as Aero Markdown is for the next step: opening the file, or the folder it lives in, and reading through it.
So the useful question is not which one is better. It is whether a Finder preview is enough for the documents you deal with, or whether you also need somewhere to read them.
Features compared
Scroll sideways to compare both apps →
| Need | QLMarkdown | Aero Markdown |
|---|---|---|
| Preview in Finder (Space) | Its main purpose: a configurable Quick Look extension. | Includes a Finder Quick Look extension for Markdown. |
| Rendering engine | cmark-gfm, GitHub's fork of cmark, with tables and GitHub alerts. | Its own renderer, with tables, task lists, GitHub alerts and footnotes. |
| Diagrams and formulas | Mermaid and MathJax, linked from a CDN or embedded in the output. | Mermaid and KaTeX bundled inside the app; nothing is fetched to render. |
| Navigation | Optional table-of-contents sidebar in a wide preview. | Persistent file tree, heading outline, relative links, back and forward. |
| Reading a whole folder | Not its job: one file per preview. | Open a file or a folder and move between documents. |
| Changed files | Re-open the preview to see changes. | Reloads the open file at the current heading; unsaved edits are kept. |
| Other formats | Also previews .rmd, .qmd, .mdx (without JSX) and textbundles. | Markdown files (.md, .markdown). |
| Export | Command-line tool and Shortcut action that convert Markdown to HTML. | Print, export to PDF or save a local HTML file. |
| Cost | Free download; source on GitHub. | Aero Markdown is $14.99 USD, one-time, for a lifetime Aero 1.x license for one Mac. Download and checkout are not available yet. |
Features change between releases. Check the QLMarkdown releases for the version you install.
When QLMarkdown is enough
If you mostly need to glance at a README before deciding what to do with it, a Quick Look extension is the lightest tool there is. There is no window to manage and nothing to switch to. QLMarkdown is free, installs from its releases page or with brew install --cask qlmarkdown, and lets you choose a theme and which extensions run. Its README notes that you must launch the app once so macOS discovers the extension.
It also covers formats that a Markdown reader may not, such as R Markdown and Quarto files, which matters if you work with notebooks.
One detail is worth knowing if you work offline or with private files. QLMarkdown's README explains that its Math and Mermaid extensions need external JavaScript libraries, which you can either load from cdn.jsdelivr.net (an internet connection is required) or embed in the preview, at the cost of a larger file. Choose the embedded option if previews must work without a network.
When you need a reader as well
A preview ends when you press Space again. If the document links to an architecture note, a decision record or an image in another folder, you are back in Finder looking for the next file. That is where a reader earns its place.
Aero Markdown keeps the folder in a file tree, the document in the middle and its headings in an outline. Relative links open the next document in the same window, and back returns you to where you were. When a coding agent rewrites the file you have open, the page reloads at the same heading instead of jumping to the top.
The two are not exclusive. Aero Markdown includes its own Quick Look extension, so the Space-bar preview and the reading window come from the same app. If you already like QLMarkdown's preview, you can keep it for Finder and use a reader only when a document turns into a project.
Try both with the same files
Download the Project Reading Kit, a fictional project of six linked Markdown files. Select README.md in Finder and press Space. Then try to follow its link to the specification and come back. The preview shows the page; the reader shows the path between pages. Decide which of those you need more often.
For the Finder side specifically, see how to preview Markdown in Finder and the checklist for when Quick Look doesn't work.
BEFORE YOU CHOOSE
Questions, answered.
Is QLMarkdown a Markdown viewer?
It is a Quick Look extension for Finder previews. Its README says it is not intended to be used as a standalone Markdown editor or viewer.
Does QLMarkdown render Mermaid and math?
Yes, with Mermaid and MathJax. Its README explains that these libraries are either loaded from cdn.jsdelivr.net, which needs an internet connection, or embedded in the preview.
Does Aero Markdown have a Quick Look extension?
Yes. Aero Markdown includes a Finder Quick Look extension for Markdown, alongside its reading window with a file tree, outline and relative links.
Sources & method.
- QLMarkdown: README, features and installation ↗
- QLMarkdown: Releases ↗
- Aero Markdown: current product facts
HOW WE COMPARE
Written by the team building Aero Markdown. Official product documentation reviewed . These are documented workflow comparisons, not hands-on performance tests. Aero Markdown’s Mac app and checkout are not public yet.
We link the sources, acknowledge shared capabilities and leave unverified behavior open. Prices and releases can change; check the developer’s current terms.