QLMarkdown vs MDViewer
QuickLook extension vs full Markdown viewer — do you need both?
Quick Overview
QLMarkdown is a free, open-source macOS QuickLook extension. It adds Markdown rendering to Finder’s Quick Look — press Space on an .md file and see a formatted preview. It is one of the most popular Homebrew installs for developers (~29K installs/year) and has been around for years.
MDViewer is a native macOS Markdown viewer that opens files in its own window with tabs, a smart table of contents, Git history, inline editing, and more. It also includes its own QuickLook extension.
These are fundamentally different kinds of software. QLMarkdown adds a capability to Finder. MDViewer is a standalone application. But since MDViewer includes QuickLook support, it can do everything QLMarkdown does — plus a lot more.
Feature Comparison
| MDViewer | QLMarkdown | |
|---|---|---|
| Price | Lite: Free / Pro: $9.99 | Free (GPL-3.0) |
| Type | Standalone app + QuickLook | QuickLook extension only |
| Technology | Native SwiftUI | QuickLook extension |
| Platform | macOS 13+ | macOS 11+ (Big Sur) |
| QuickLook in Finder | Yes | Yes |
| Standalone viewer | Yes (own window, tabs) | No |
| Inline editing | Yes (double-click to edit) | No |
| Git history & diff | Yes (built-in) | No |
| Table of contents | Yes (auto, tracks scroll) | No |
| Tabs | Yes | No |
| File tree | Yes | No |
| Mermaid diagrams | Yes (interactive SVG with zoom) | Yes (since v1.0.24) |
| Math rendering | Yes (KaTeX) | Yes (MathJax) |
| Syntax highlighting | Yes | Yes (221 languages) |
| PDF export | Yes (⌘⇧E) | No |
| Custom CSS | Light & Dark (system) | Yes (custom stylesheets) |
| File formats | .md | .md, .mdx, .qmd, .rmd, .mdc, .apib, .mermaid, textbundle |
| CLI tool | No | Yes |
| App size | ~15 MB | 20.6 MB |
When to Choose MDViewer
- You need a standalone Markdown viewer — open files in their own window, keep multiple files in tabs
- You want QuickLook and a full app in one install instead of separate tools
- You need Git history and diffs to see how a file changed over time
- You want a table of contents that tracks your scroll position in long documents
- You need inline editing for quick fixes without opening a code editor
- You need to export to PDF directly from the viewer
- You want a file tree to browse an entire project’s Markdown files
When to Choose QLMarkdown
- You only need QuickLook previews — press Space, glance at the file, move on
- You need to preview non-standard formats like
.mdx,.qmd,.rmd, or standalone.mermaidfiles - You want custom CSS for your QuickLook previews
- You need the CLI tool or Shortcuts action for automation workflows
- You are on macOS 11 or 12 (MDViewer requires 13+)
- You prefer open-source software you can inspect and modify
Understanding the Difference: Extension vs App
The most important distinction between QLMarkdown and MDViewer is not about features — it’s about what they are.
QLMarkdown is a system extension. It hooks into Finder’s Quick Look to render Markdown when you press Space. The preview is modal: it closes the moment you click elsewhere or press Space again. You cannot scroll through a long document comfortably, open multiple files side by side, or do anything beyond a quick glance.
MDViewer is an application. It opens files in a persistent window. You can read at your own pace, navigate with the table of contents, open related files in tabs, check the Git history, and make quick edits. The file stays open until you close it.
This matters for workflow. QuickLook is great for answering “what’s in this file?” in two seconds. But the moment you need to read a document — a long README, an API spec, a meeting summary — you need an actual viewer. QLMarkdown cannot fill that role because it was never designed to.
Do You Need Both?
Probably not. MDViewer includes its own QuickLook extension, so installing MDViewer gives you both Quick Look previews in Finder and a full viewer app. QLMarkdown becomes redundant.
There are a few edge cases where you might keep QLMarkdown alongside MDViewer:
- You work with
.mdx,.qmd, or.rmdfiles that MDViewer does not handle - You use QLMarkdown’s CLI tool or Shortcuts action in automation
- You prefer QLMarkdown’s rendering style or custom CSS for Quick Look specifically
For most developers, though, MDViewer covers the entire use case. You get Finder previews through MDViewer’s QuickLook extension and a proper viewer for everything else.
For a comparison with another lightweight Mac viewer, see MDViewer vs Simply Markdown.
FAQ
Is QLMarkdown a standalone Markdown viewer?
No. QLMarkdown is a macOS QuickLook extension. It renders Markdown previews when you press Space on a file in Finder, but it does not open files in its own window. You cannot edit, browse folders, or use tabs. For a standalone viewer, you need a separate app like MDViewer.
Can I use QLMarkdown and MDViewer together?
Yes, but MDViewer already includes its own QuickLook extension. If you install MDViewer, you get Finder QuickLook previews plus a full viewer app. QLMarkdown becomes redundant unless you prefer its specific rendering style or need its CLI tool.
Does QLMarkdown support Mermaid diagrams?
Yes, since version 1.0.24. QLMarkdown renders Mermaid diagrams in its QuickLook previews. MDViewer also supports Mermaid with interactive SVG rendering and zoom controls.
How do I install QLMarkdown?
QLMarkdown is typically installed via Homebrew with brew install qlmarkdown. It is free and open source under GPL-3.0. MDViewer is downloaded from the Mac App Store or the MDViewer website.
Try MDViewer
MDViewer Lite is free and includes QuickLook support. Pro adds editing, Git history, and PDF export for $9.99. Download and get both Quick Look previews and a full viewer in one app.
Requires macOS 13.0 or later. Intel and Apple Silicon.