Press Spacebar on a Markdown file and macOS will now draw something. The latest system ships its own Markdown Quick Look plugin, so you get a tidy little preview instead of a wall of monospace. It is fine. It is also the preview equivalent of a plain cracker. If the note has a diagram, a table of contents, a house style, or one of those Markdown dialects you swore you would stop using, you are still looking at a sketch of the document.
Marked QL is the Spacebar preview I actually want open. It is a small app whose only job is to render Markdown the way Marked does, inside Quick Look.
Long notes are miserable in a preview that only scrolls. Marked QL builds a table of contents from the headings and puts it beside the page. Two or more headings and it shows up. Drag the divider, collapse it, jump to a section. Finder’s narrow column preview hides it on its own when there is no room, so a glance at a file in column view stays a glance.
A fenced block that starts with mermaid is a diagram, not a code sample you are supposed to squint at.
```mermaid
graph LR
A[Spacebar] --> B[Marked QL]
B --> C[The actual note]
```That renders in the preview. So does syntax highlighting, with a choice of themes, and math. The scripts ship inside the app. The preview does not phone home to draw a flowchart.
Nine Marked styles are built in: GitHub, Swiss, Ink, Manuscript, Grump, and the rest. Pick one in Settings and the next Spacebar uses it. If you already have a stylesheet, import it. Custom CSS is the difference between “a preview of my notes” and “a preview that looks like my notes.”
Most of my files are ordinary Markdown. Some of them are not. .qmd files can use Apex’s Quarto mode, which covers the Pandoc and Quarto bits you need for an HTML preview. It is not a full Quarto render. It is enough to read the document without exporting it first.
Under that is Apex, the processor Marked QL uses for everything. Unified mode is the default, and it is the one that swallows the dialects people actually mix together. You can switch the preview to MultiMarkdown, GitHub Flavored Markdown, CommonMark, or Kramdown when a file is picky. CriticMarkup shows up as tracked changes. The odd flavor is still a document, not a syntax error.
Installing Marked QL is not always the end of the story. macOS decides which Quick Look extension draws the file, and it is happy to keep using its own.
Here is the annoying version. You install the app, you turn the extension on, you press Spacebar, and you get Apple’s plain Markdown preview. Or raw source. Marked QL can be registered and enabled while the system plugin still handles .md. Recent macOS tags Markdown with its own types (public.markdown, and on newer systems public.utf8-plain-text), and the built-in preview claims those. Other apps do the same thing. Folder Quick Look, a notes app, an editor. Whoever claimed the type last, or loudest, gets the Spacebar.
Preferring your plugin in System Settings is supposed to fix this. Often it does not. pluginkit will show Marked QL with a + and the preview on screen will still be someone else’s. I have stared at that output long enough to stop pretending the Settings checkbox is the whole tool.
That is what Quick Look Doctor is for. It is free, it is not just for Markdown, and it does not ask you to memorize Terminal flags.
Drop the file that is previewing wrong. Doctor lists every extension that claims it and shows which one is actually serving the preview. Prefer Marked QL. It will ignore the others that are in the way, ask first, and let you undo. There is also a list of every Quick Look plugin on the machine if you want to see the whole crowd: Use, Ignore, or back to Default.
A couple of honest limits. Doctor does not tattoo Marked QL onto the file forever. macOS can still change its mind after an OS update, and another app can register itself again the next time it launches. You run Doctor, you point the preview at the handler you want, you get on with the note. If you would rather read the long version first, the troubleshooting page has the manual steps Doctor is saving you from.
Marked QL is the preview. Quick Look Doctor is how you get macOS to use it when Apple’s own plugin, or anyone else’s, has stepped in front. Spacebar should show the document you wrote, diagrams and all.
Brett is a writer and developer living in Minnesota, USA. You can follow him as ttscoff on GitHub, Mastodon, and elsewhere.
Sign up for the email newsletter, and keep up with this blog by adding it to your favorite news reader, or following it on Bluesky or Mastodon at @brettterpstra.com@web.brid.gy.