QLMarkdown: a Quick Look extension for Markdown on macOS

Who QLMarkdown is for, and the gap it fills

On macOS, pressing Space on a file in Finder opens Quick Look. Text files get a plain preview. Markdown files, without an extension, get that same plain text, so a README with tables, fenced code and images reads as raw source. QLMarkdown installs a Quick Look extension that renders Markdown instead, using the cmark-gfm library from GitHub's fork of cmark. The README describes the project as a Mac OS application that provides a Quick Look extension, an experimental Shortcut extension for converting Markdown to HTML, a command-line executable for the same conversion, and a graphical interface for configuring preview display settings. The audience is narrow and specific: people who already keep Markdown files on a Mac and want to check them without launching an editor. The README states in a blockquote that the application is not intended to be used as a standalone markdown file editor or viewer, and repeats that warning in the settings section. That is worth taking at face value. The inline editor in the settings window exists to test formatting, not to write documents.

The rendering pipeline: cmark-gfm plus a list of extensions

The README is explicit about the core choice. For maximum compatibility with the Markdown format, the cmark-gfm library is used, described as a GitHub fork of the standard cmark tool to process Markdown files. On top of that, the project adds its own extensions: definition lists, GitHub alerts, emoji shortcodes such as :smile:, heading anchors, highlight between == markers, inline local images, subscript with ~, superscript with ^, MathJax for math, Mermaid for diagrams, MkDocs admonitions, syntax highlighting in fenced blocks, wikilinks, and YAML header rendering for rmd and qmd files. Inline local images is the one that matters most for the Quick Look use case: the README notes it is required for the Quick Look preview, because a preview surface has no document base URL to resolve relative image paths against. The extension set is where QLMarkdown diverges from a plain cmark render, and it is also where the compatibility question lives. The README has a dedicated section on differences with GitHub's Markdown engine. It explains that GitHub does not use cmark-gfm directly in its rendering process, and that its Ruby parsing and formatting libraries cannot easily be converted into a compiled library. The consequence stated in the README is that syntax highlighting uses a different library, so formatting, color scheme and language token recognition are potentially different from what GitHub shows. If you expect a preview to match a GitHub pull request byte for byte, it will not.

Installing QLMarkdown and getting a first preview

The README gives two routes: download the latest compiled release from the releases page, or install with Homebrew. The cask command is:

brew install --cask qlmarkdown

The README notes that the precompiled app is notarized and signed. After installing, the step that people miss is launching the app at least once. The README states this in bold: you must launch the application at least once, so the Quick Look extension is discovered by the system and shared files are installed for the Shortcut extension. After that first execution the extension should appear, already enabled, in System Settings under Extensions. The app has a button labelled to open the System Settings Quick Look panel, which is the fastest way to confirm it is there. Support files land in ~/Library/Group Containers/group.org.sbarex.qlmarkdown. The README warns that the contents of the highlight and js subfolders may be overwritten by the app, so do not treat them as a place for your own edits. Once the extension is registered, select a Markdown file in Finder and press Space. You should see rendered output rather than raw text. The repository ships example files that exercise the extensions, including examples/test-github-alerts.md, examples/test-mermaid.md, examples/test-definition-list.md and examples/test-admonition.md, which are useful for checking that a given extension is enabled in your settings. Uninstalling is dragging the app to the trash; the support folder is removed separately.

Settings, themes and the extensions you have to turn on

The settings window is where the preview is configured. The README says you can set options, enable the desired extensions and choose a theme. Changes only take effect when saved with cmd-s, via File > Save settings, or when autosave is enabled. That is a real friction point: toggling an extension and closing the window does nothing. Themes are CSS. The app ships with a predefined theme derived from the GitHub style that is valid for both light and dark appearance, and the README indicates you can also supply your own style. Extensions are opt-in individually, which is the right default for a preview tool because Mermaid and MathJax pull in external JavaScript libraries. The README has a dedicated note about those external libraries, so anyone enabling the math or diagram extensions should read it before assuming previews work offline or in a sandboxed context. Syntax highlighting, YAML header rendering, emoji and inline local images are all separate switches. A file that previews badly is more often a disabled extension than a rendering bug, and the example files in the repository are the quickest way to tell the difference.

Command line conversion, and what it does not do

Beyond the Finder preview, the project ships a command-line executable for converting Markdown files to HTML, and the README lists a Shortcut extension for the same job, marked experimental. That combination is the part of the project with the least documentation in the README: the CLI section exists, but the README does not give the binary name, the flags or the output behaviour, so anyone planning to script conversions should read that section directly rather than assume a cmark-compatible interface. The Shortcut extension is labelled experimental by the project itself, which is a fair signal about how much to build on it. The honest framing is that the CLI is a convenience attached to a preview tool, not a general-purpose static site generator. If your goal is a build pipeline that converts a documentation tree to HTML, this is the wrong tool, and the README's own description of the app's scope supports that reading.

Limitations, failure modes and the wrong use cases

The most important limitation is stated by the project: it is not an editor. There is an inline editor in the settings window for testing, but the README explicitly says the application is not intended as a standalone markdown file editor or viewer, only to set Quick Look preview formatting preferences. Anyone who installs it expecting a replacement for a Markdown editor will be disappointed. Second, the Quick Look extension only exists after the app has been launched once, and it lives in System Settings under Extensions. If a preview shows plain text, the extension is missing or disabled, not the file. Third, the syntax highlighting differs from GitHub's, as the README explains, so code blocks will not match GitHub's colors or language detection. Fourth, the rmd and mdx support is partial by design: the README says rmarkdown previews do not evaluate R code, and MDX previews do not render JSX. A .qmd or .rmd file with executable chunks will show the source of those chunks, not their output. Fifth, the README's note about security is worth reading before enabling extensions that load external JavaScript. Finally, the software is provided as is, without warranty of any kind, in the project's own words.

How this differs from the older Quick Look plugins

The related searches around this project include qlgenerator and Toland qlmarkdown, which points at the real alternative space: earlier Quick Look generators for Markdown on macOS. The difference in approach is architectural. Older generators were typically installed as .qlgenerator bundles and relied on the Quick Look generator API, which Apple has been moving away from. QLMarkdown is built as an app with a Quick Look extension, which is the model current macOS expects, and that is why the install instructions centre on launching the app once so the system registers the extension. The rendering approach also differs: rather than calling out to an external Markdown processor, QLMarkdown links cmark-gfm and layers its own extension set on top, which is what allows inline local images to work inside a preview. If you are migrating from a generator-based plugin, the practical difference you will notice is the install and enablement flow, not the Markdown dialect. If you need a full editor or a documentation build system, neither this project nor the older generators is the right category of tool.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-23. Releases are frequent: 1.5.5 is dated 2026-09-23, 1.5.4 is dated 2026-09-18 and 1.5.3 is dated 2026-09-11. That cadence suggests the project is being kept current with macOS and with its dependency. The licence is GPL-3.0, and the repository contains LICENSE.txt at the top level. GPL-3.0 matters if you plan to redistribute the app or build a derivative: the licence carries copyleft obligations, and the README notes the app bundles external JavaScript libraries for MathJax and Mermaid, which have their own licensing. That is a question for your own legal review, not something to settle from a README. On upgrade cost, the app is distributed as a signed and notarized bundle, so Homebrew upgrades are the normal path and there is no configuration migration described. The one thing to re-check after an upgrade is the support folder at ~/Library/Group Containers/group.org.sbarex.qlmarkdown, since the README warns that the highlight and js subfolders may be overwritten by the app. If you have placed custom assets there, an upgrade can replace them.

Editorial conclusion

Adopt QLMarkdown if you keep Markdown on a Mac and want Finder previews without opening an editor, or if you need a local Markdown to HTML converter for rmd, qmd, mdx, mdc and apib files. Do not adopt it as an editor: the README states plainly that it is not intended as a standalone Markdown editor or viewer, and the settings window is for preview formatting only. Before relying on it, verify that the Quick Look extension appears in System Settings after the first launch, and check the contents of ~/Library/Group Containers/group.org.sbarex.qlmarkdown/highlight and /js, because the README warns the app may overwrite them.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. sbarex/QLMarkdown on GitHub