QLMarkdown: GitHub's own Markdown parser, a different syntax highlighter

Four products in one app, and the same warning twice

The opening paragraph lists four things this application is, and the differences between them matter.

A Quick Look extension for viewing Markdown files, which is the reason the app exists. An experimental Shortcut extension for converting Markdown to HTML, and the word experimental is doing real work there. A command line executable for the same conversion. And a graphical interface for configuring how the preview is displayed.

So it is an application in the macOS sense, a preview generator, a converter and a settings tool, rather than one of those things alone. The Shortcut extension is the odd one out because the rest can be exercised from a shell or from Finder, while that one needs the system's automation surface.

Then the warnings. The first is in bold at the top: the application is not intended to be used as a standalone Markdown editor or viewer. The second is that the software is provided as is, without any warranty of any kind.

The first warning appears a second time in the settings section, attached to the inline editor, which is the one place a reader would be tempted to ignore it. So the author has told readers twice, in the two places where the temptation arises, not to treat this as an editor. There is also a donation link near the top.

The parser is GitHub's own fork, with fifteen extensions on top

The Markdown processing section explains the choice of engine before it lists anything.

For maximum compatibility, the file says the library used is a GitHub fork of the standard tool, with a link to both the fork and the specification it processes. So the base behaviour is whatever GitHub's own renderer does, and everything this project adds is an explicit extension.

The list has fifteen entries. Definition lists. GitHub-style alerts. Emoji shortcode translation. Hashtags. Anchors for headings, with the file spelling the word as heads twice. Text highlighting between double equals markers. Inline local images, which it notes are required for the preview to work at all. Subscript between tilde markers and superscript between caret markers. Mathematical expressions through one library and diagrams through another. An admonition extension named after a documentation generator. Syntax highlighting inside fenced blocks. Wikilinks. And a YAML front matter block rendered at the start of two of the file types it supports.

Two of those matter more than the rest for a preview tool. Inline local images are embedded into the output rather than referenced, which is what lets a preview work from a temporary file with no path resolution. And the emoji and diagram extensions are the reason the settings window has extension toggles at all: each one is a library you can leave switched off.

The one documented difference from GitHub is syntax highlighting, and the reason is Ruby

There is a section whose entire job is to say where this project differs from the service whose parser it borrows, and it is more useful than a compatibility matrix would be.

The first point is that GitHub has customised the same forked library, but does not use it directly when rendering Markdown files. It links to the repository where that happens, and gives the reason: GitHub uses a number of libraries written in Ruby for parsing and formatting source code, which cannot easily be converted into a compiled library.

That is the whole constraint. A native preview application has to compile its highlighter; GitHub cannot, so the two run different highlighters over the same Markdown.

The consequence is then stated as a single difference: the formatting of source code. The formatting, the colour scheme and the language token recognition are described as potentially different.

Everything else, the file implies by contrast, is shared. Same parser, same fifteen extensions on top, same Markdown semantics. So if you are comparing previews and the difference is prose layout, this is not where it comes from; if it is code colours and indentation, this is exactly where it comes from.

Six extra file types are previewed, two of them without executing anything

The extension registers itself for more than plain Markdown, and the list is worth reading for what it says about the boundaries.

It previews research Markdown files, explicitly without evaluating the R code inside them. It previews MDX files, explicitly without rendering JSX. So those two are treated as text and laid out, not executed.

Then three more formats by extension: a rules format used by one editor, the format used by one publishing tool, and an API description format. Plus textbundle packages, which are a directory rather than a file, so a preview there means reading a bundle.

The last entry is the interesting one. Files with the diagram extension are rendered wrapped inside a fenced block of the same name, and the file notes the corresponding extension has to be enabled for it to work. So a diagram file does not preview as a diagram; it previews as a code block containing the diagram source, and the settings decide whether the block is then rendered.

Read together with the extension toggles in the settings window, the design is consistent: everything that needs a library is opt-in, and everything that needs an interpreter is deliberately refused.

You have to launch it once, and two support subfolders are disposable

Installation has a step that catches people out, and the file states it in bold.

You must launch the application at least once. The reason given is mechanical: that is how the system discovers the Quick Look extension and how some shared files get installed for the Shortcut extension. Only after that first run does the extension appear among those present in the system settings, and the file tells you to check using a button in the main app that opens the right panel.

So a fresh install that you never open looks broken, because the preview simply is not registered.

The other operational detail is where the files go: a group container path under the user's library directory. And two of its subfolders are flagged. The contents of the folders for highlighting and for scripts may be overwritten by the app.

That is a fair warning to put in bold, because both names invite exactly the wrong thing. A user who drops a custom highlighter stylesheet into the highlighting folder will lose it on the next launch.

Uninstalling, by contrast, is undemanding: drag the application to the trash, and delete the group container folder if you want the support files gone too.

Custom styling is appended after the highlighter, and only pixel values count

The theming section is where this application gives you more control than a preview tool strictly needs, and also where it gives you a way to break the code view by accident.

A theme is a stylesheet. One is provided, derived from the GitHub look and valid for both light and dark appearance. You can also supply your own, either to extend the standard one or to override it, and a custom stylesheet is required to handle both appearances with a media query:

@media (prefers-color-scheme: dark) {
    /* … */
}

Then the sentence that matters. The custom style is appended after the stylesheet used for source code highlighting, which means your prose theme also lands on top of the highlighter's colours. The file presents that as a feature, since it lets you restyle code as well, and it is worth restating as a hazard, since a rule written for a paragraph will apply to every code block too.

One more escape hatch, for layouts. If your stylesheet uses a content column of a different width, you declare a custom property so the preview window sizes itself to match. And the constraint is exact: only pixel values are recognised.

Release titles carry a build counter, and two documentation sections are named but absent

The last details are about how this project is packaged and how its documentation is arranged.

The three most recent releases are four days apart at the start and two days at the end, and their titles carry a parenthesised number that increments by one: the build counter. So the version tells you the release and the counter tells you the build, which is what an automated pipeline tracking continuous integration produces.

The table of contents names more sections than the visible file contains. There is a security note and a note about the developer, and neither is in the text here. The two screenshot subsections are present as headings with nothing under them. So a reader working from the contents will find three promises the file does not yet keep in the part that is visible, and two of those are the ones a cautious adopter most wants.

The tree explains the build shape. It is an Xcode project with a target directory per component: the extension, the application, a helper, and the command line tool. The parser is a directory of its own alongside a directory for the added extensions and a wrapper around the highlighter. One directory in the root has a space in its name, which is the kind of thing that survives from an early rename and then breaks every script that has to quote it.

The examples directory is the documentation that survives the sections that do not: nine Markdown files, one per extension, named after what each one tests.

Editorial conclusion

QLMarkdown fits someone who previews Markdown in Finder and wants the result to match what they will publish rather than what a generic viewer produces, since that parity is the whole design choice. Three things to know. You have to launch it once before the extension is discovered, and two of its support subfolders are overwritten by the app, so anything you put there is disposable. Its custom styling is appended after the highlighter's stylesheet, so a theme meant for prose also changes how code looks, and only pixel values are accepted for the width override. And it says twice that it is not an editor or a viewer, which is worth believing: the settings window has an inline editor for testing, and that is the limit of it.

Frequently asked questions

Official sources

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