# How to see .md files formatted in Quick Look on a Mac > Why the spacebar preview shows .md files as raw symbols, which Quick Look extensions fix it (free and paid), and how to turn one on. Source: https://oneclearreader.com/guides/quick-look-markdown-mac · Updated 28 September 2026 · One Clear Reader (Northlight Group Pty Ltd) > [!answer] Quick Look, the preview you get by pressing Space in Finder, shows .md files as plain text because macOS has no Markdown view built in. To get a formatted preview, install a Quick Look extension such as the free QLMarkdown, open its app once, then turn it on in System Settings under Login Items & Extensions. ## Why does Quick Look show a .md file as # and ** symbols? Quick Look shows a .md file as # and ** symbols because it shows each file the way macOS knows how, and macOS doesn't know Markdown. Apple describes Quick Look as "a fast, full-size preview of nearly any kind of file without opening the file" ([Apple Support](https://support.apple.com/guide/mac-help/view-and-edit-files-with-quick-look-mh14119/mac)). For a .md file, "nearly any" means the raw text. You see the symbols, not the page they describe. Apps can teach Quick Look new tricks. A developer adds a **Quick Look extension**, a small add-on that tells Quick Look how to draw a file type ([Apple developer docs](https://developer.apple.com/documentation/quicklook)). Install one for Markdown and the spacebar shows headings, lists and tables. > [!note] One Clear Reader doesn't have a Quick Look extension. This page covers the ones that do, including free ones. ## Which Quick Look extension should I use for .md files? For most people, **QLMarkdown** is the Quick Look extension to use for .md files on a Mac. It's free, open source, still updated, and it draws tables, diagrams and math. This table compares five ways to get a formatted Markdown preview in Quick Look. | Option | Price | Needs | Draws diagrams (Mermaid) | Where to get it | |---|---|---|---|---| | [QLMarkdown](https://github.com/sbarex/QLMarkdown) | Free, open source | macOS 12 or later | Yes | GitHub, or Homebrew (`brew install --cask qlmarkdown`) | | [Imark](https://imarkmd.com/) | Free, open source | macOS 14 or later | Yes | GitHub. A full reader app that includes a Quick Look extension | | [Markdown Preview](https://apps.apple.com/us/app/markdown-preview-quick-look/id6739955340) | $1.99 once | macOS 12 or later | Yes | Mac App Store | | [PreviewMarkdown](https://apps.apple.com/us/app/previewmarkdown/id1492280469) | $2.99 once | macOS 11.5 or later | Not listed | Mac App Store | | [Marked Quick Look](https://markedapp.com/help/Quick_Look) | $9.99 once | macOS 13 or later | Yes | Mac App Store, Setapp, or direct with a free trial. Works without Marked | Prices and requirements checked 28 September 2026. "Not listed" means the developer's page doesn't mention it, not that we tested it and it failed. A few honest notes: - **QLMarkdown** has had regular releases through September 2026 (version 1.5.4 on 18 September), and its developer says the app is signed and notarized by Apple since version 1.5.0 ([release notes](https://github.com/sbarex/QLMarkdown/releases)). It isn't meant as a reader on its own. Its app is where you change settings. - **Imark** is a young app (version 0.6.2), so expect some rough edges. - **PreviewMarkdown** shows a placeholder instead of images, because macOS only lets it read the file you're previewing ([developer's page](https://smittytone.net/previewmarkdown/index.html)). - **Marked Quick Look** lists the most extras, such as a table of contents for long files and a tidy view of the details block some files start with (called frontmatter). It also costs the most. Some full Markdown apps include a Quick Look extension too. Peekdown ($4.99, macOS 15 or later) and MacMD Viewer ($19.99, macOS 14 or later) both do (checked 28 September 2026). ## How do I turn on a Markdown Quick Look extension? To turn on a Markdown Quick Look extension on a Mac, install its app, open it once, then switch the extension on in System Settings. That last step is in a different place depending on your macOS version. 1. **Install the app.** Drag it into your Applications folder, or install it from the App Store. 2. **Open the app once.** This is how your Mac finds the extension inside it. QLMarkdown's instructions say you "must launch the application at least once" ([QLMarkdown README](https://github.com/sbarex/QLMarkdown)). You can close it straight after. 3. **Turn the extension on.** - **macOS 15 or later** (including macOS 26 and 27, checked 28 September 2026): choose `Apple menu › System Settings`, click **General**, then **Login Items & Extensions**. Find **Quick Look** under Extensions, click the ⓘ button next to it, turn on the extension, and click **Done** ([Apple Support](https://support.apple.com/guide/mac-help/change-login-items-extensions-settings-mtusr003/mac)). - **macOS 13 or 14**: choose `Apple menu › System Settings`, click **Privacy & Security**, then **Extensions** on the right, then **Quick Look** ([Apple Support](https://support.apple.com/guide/mac-help/change-extensions-settings-on-mac-mchl8baf92fe/14.0/mac/14.0)). 4. **Test it.** Select a .md file in Finder and press Space. You should see a formatted page. Not sure which macOS you have? Choose `Apple menu › About This Mac`. > [!scribble] open it once. that's the step everyone skips. ## What if Quick Look still shows a .md file as plain text? If Quick Look still shows a .md file as plain text after you install an extension, work down this list. Most fixes take seconds. - **You haven't opened the app yet.** Open it once, quit it, then try Space again. - **The extension is switched off.** Check the Quick Look list in System Settings, using the steps above. - **Two Markdown extensions are on.** Turn off the ones you're not using, so you know which one you're seeing. - **Another app has claimed .md files.** PreviewMarkdown's developer notes that if another app owns the Markdown file type on your Mac, their extension can't preview it ([developer's page](https://smittytone.net/previewmarkdown/index.html)). If .md files open in Xcode or something unexpected, [change the default app for .md files](/guides/change-default-app-md-mac) first. - **You followed an old guide.** Older add-ons ended in `.qlgenerator` and were copied into a QuickLook folder. Those stopped working in macOS 15, which only uses the newer kind that lives inside an app ([The Eclectic Light Company](https://eclecticlight.co/2024/10/31/how-sequoia-has-changed-quicklook-and-its-thumbnails/)). Use one of the options in the table above instead. - **Still nothing.** Restart your Mac. If you're comfortable in Terminal, `qlmanage -r` resets Quick Look. It's harmless, though thumbnails may be slow for a little while afterwards ([The Eclectic Light Company](https://eclecticlight.co/2026/05/20/tackle-quicklook-problems/)). ## What can't a Quick Look preview of a .md file do? A Quick Look preview of a .md file can't be edited, searched or navigated by heading. Quick Look is built for a quick peek, and that's by design. - **It's temporary.** Press Space again, or click the close button, and it's gone ([Apple Support](https://support.apple.com/guide/mac-help/view-and-edit-files-with-quick-look-mh14119/mac)). - **You can't edit.** To fix a line you still need to open the file in an app. - **You can't search it.** There's no Find bar for jumping to the one word you need in a long file. - **There's no outline.** You scroll a long plan top to bottom with no list of sections. - **Each extension draws things differently.** A diagram or wide table can look fine in one and cramped in another. For "is this the right file?", a preview is all you need. For a 3,000-word plan you need to understand before you approve it, it gets tiring fast. ## When is a Markdown reader better than Quick Look? A Markdown reader is better than Quick Look when you actually need to read the .md file, not just check it. A reader app stays open, remembers where you were, and gives you tools the preview doesn't. Here's what that looks like in One Clear Reader, which opens .md files when you double-click (or paste a path, or type part of the name): - **Find** with ⌘F, with every match highlighted. - **An outline** of the headings in a sidebar, so you can jump to a section. - **Wide tables** that scroll sideways with "More columns" buttons, and diagrams drawn from Mermaid code. - **Reading settings**, like the Neuro-friendly profile with the Atkinson Hyperlegible font and extra spacing, or larger text. - **Editing** the Markdown when you spot a mistake, free, with a check of the changes before anything is saved. Plenty of people use both. Quick Look for a glance in Finder, a reader for anything longer than a screen. If you're choosing a reader, [Markdown readers for Mac, compared](/compare/markdown-readers-mac) lays out the options side by side. ## What's the free way to fix the spacebar preview for .md files? The free way to fix the spacebar preview for .md files is QLMarkdown: install it, open it once, switch it on, and press Space. That costs nothing and fixes the preview in Finder. When you want a proper page for longer documents, One Clear Reader is free for reading, search and editing Markdown, with no account and no time limit on the free version. Set it as your default with one click, and double-click does the rest. [How to open a .md file on a Mac](/guides/open-md-file-mac) walks through the first open. ## Questions ### Can a Mac show Markdown formatted in Quick Look without an add-on? No. Without an extension, Quick Look shows a .md file as plain text with the # and ** symbols visible. A Markdown Quick Look extension adds the formatted view. ### Is QLMarkdown free? Yes, QLMarkdown is free. QLMarkdown is open source, published on GitHub under the GPL-3.0 license. You can also install it with Homebrew. ### Does One Clear Reader have a Quick Look extension? No. One Clear Reader opens .md files as a formatted page when you double-click them, but it doesn't add a spacebar preview. Use a Quick Look extension alongside it for previews in Finder. ### Can Quick Look show Mermaid diagrams? Yes, Quick Look can show Mermaid diagrams with the right extension. QLMarkdown, Imark, Markdown Preview and Marked Quick Look all list Mermaid diagram support. ### Why did my old Markdown Quick Look plugin stop working? Older plugins ending in .qlgenerator no longer work from macOS 15 onwards. Install a current extension that comes inside an app, such as QLMarkdown, and turn it on in System Settings. ### Where are Quick Look extensions in System Settings? Quick Look extensions are in System Settings under General, then Login Items & Extensions, then Quick Look, on macOS 15 and later. On macOS 13 and 14, go to Privacy & Security, then Extensions, then Quick Look.