Marked Quick Look Troubleshooting

Quick Look issues usually fall into one of three categories. Knowing which one you have saves time.

How to tell Marked Quick Look is active: the preview shows styled HTML and an Open in Marked toolbar at the top (when that option is enabled). If you see a different layout, another app's styling, or raw source, a different handler is probably winning.

Work through these before running Terminal commands.

1. Confirm you installed Marked Quick Look, not Marked 3.
2. Confirm the app is in /Applications/Marked Quick Look.app (not in Downloads or on an external volume).
3. Launch Marked Quick Look once from Applications. Do this after every install or update.
4. Test in Finder: select a .md file, then press Spacebar. Some apps trigger Quick Look differently than Finder.
5. Confirm your Mac is running macOS 13 or later.

On macOS Ventura and later:

1. Open System Settings
2. Go to General → Login Items & Extensions → Quick Look Extensions
3. Enable Marked Quick Look Preview
4. Launch Marked Quick Look once from /Applications
5. Try Spacebar on a .md file again

If the extension is disabled or greyed out, toggle it on, launch the container app, and retry.

Run these commands in Terminal (Applications → Utilities → Terminal):

pluginkit -a "/Applications/Marked Quick Look.app/Contents/PlugIns/MarkedQuickLookPreview.appex"
pluginkit -e use -i com.brettterpstra.MarkedQuickLook.preview
killall quicklookd QuickLookUIService 2>/dev/null
qlmanage -r cache

Then relaunch Finder: Option-right-click Finder in the Dock → Relaunch.

Press Spacebar on a .md file again.

pluginkit -m -D -p com.apple.quicklook.preview -A -v | grep -i MarkedQuickLook

You should see com.brettterpstra.MarkedQuickLook.preview in the output. A + prefix means the extension is explicitly enabled.

Note: Do not grep for markdown. The bundle ID does not contain that word, so grep -i markdown can return no results even when Marked Quick Look is installed and enabled.

If Marked Quick Look is missing entirely, reinstall from the App Store, launch the app once, then repeat Step 3.

macOS allows multiple apps to register Markdown Quick Look handlers. Only one extension handles each preview. Another app may be taking precedence over Marked Quick Look.

List all registered preview extensions (look for bundle IDs from the table below):

pluginkit -m -D -p com.apple.quicklook.preview -A -v

Common conflicting apps

Important: Marked Quick Look can show as enabled (+) while another Markdown QL extension still wins the preview. Preferring Marked alone (pluginkit -e use) is not always enough — some peers (notably Nova) keep serving Markdown until they are ignored.

Note: Apps can also break Markdown preview by claiming a fallback UTI as an Editor (not just via a Quick Look extension) — see Step 8 for TeXShop / com.unknown.md.

Test for a conflict

Temporarily ignore suspect extensions (Folder Quick Look and/or Nova), prefer Marked Quick Look, then refresh Quick Look:

# Folder Quick Look:
pluginkit -e ignore -i studio.appahead.AA7.Markdown-Quick-Look-Extension
# Nova:
pluginkit -e ignore -i com.panic.Nova.NovaQuickLookPreview

pluginkit -e use -i com.brettterpstra.MarkedQuickLook.preview
killall quicklookd QuickLookUIService
qlmanage -r cache

Preview a .md file. If Marked Quick Look now works, you have confirmed a conflict — re-enable only the extensions you still want (or leave the conflicting one ignored).

Restore when done testing:

pluginkit -e default -i studio.appahead.AA7.Markdown-Quick-Look-Extension
pluginkit -e default -i com.panic.Nova.NovaQuickLookPreview

This bypasses Finder and shows whether the extension works at all:

qlmanage -r cache
qlmanage -p ~/Desktop/your-file.md

Replace the path with any real .md file.

• Works in Terminal but not Finder: registration or conflict issue (repeat Steps 3–5).
• Still monospace in Terminal: the extension is not being selected for that file's UTI (see Step 8).
• Fails in both: extension crash or install problem (see Steps 7–8).

If you see unstyled monospace source, macOS is likely falling back to the built-in Text.qlgenerator because the preview extension failed to load.

1. Open Console.app (Applications → Utilities → Console)
2. In the search field, type: MarkedQuickLookPreview
3. Press Spacebar on a .md file in Finder
4. Look for crash reports, sandbox violations, or "extension failed to initialize" messages

If you see errors, note them for a support request (see Step 9).

This step checks your specific file, not whether a Markdown UTI exists somewhere in macOS. Quick Look only matches UTIs — not filename wildcards — so the type Launch Services assigns to the file determines which preview extension runs.

Check a file's content type and type hierarchy:

mdls -name kMDItemContentType -name kMDItemContentTypeTree /path/to/file.md

Marked Quick Look handles files whose UTI conforms to one of:

• net.daringfireball.markdown
• net.ia.markdown (iA Writer; requires 1.0.2+)
• public.markdown / public.utf8-plain-text (Apple Markdown types on newer macOS)
• io.typora.markdown (Typora; requires 1.0.3+)
• com.unknown.md (TeXShop and other apps that retag .md; requires 1.0.3+)
• public.plain-text (older systems and legacy type assignments)
• org.quarto.qmd / org.rstudio.qmd (Quarto; requires 1.0.3+)

If you see something unexpected (e.g. public.data), macOS may not route the file to any Markdown Quick Look extension.

/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -dump | grep -B5 -A20 'com.unknown.md'

If a Launch Services reset “doesn’t stick”

Launch Services can keep stale registrations from copies in Trash, backups, or old download folders even after you fix or remove the live app. Unregister those paths explicitly, then rebuild Quick Look:

# Replace with every leftover path lsregister -dump still shows for the app:
/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -u "/path/to/old/TeXShop.app"
/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -u "$HOME/.Trash/TeXShop.app"

qlmanage -r
qlmanage -r cache
killall quicklookd QuickLookUIService Finder 2>/dev/null

If your file has a different unexpected UTI, another app may have claimed the .md extension. Full Launch Services rebuild:

/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -kill -r -domain local -domain system -domain user
qlmanage -r
qlmanage -r cache
killall quicklookd QuickLookUIService Finder 2>/dev/null

Reboot if the UTI still looks wrong.

qlmanage -r cache
qlmanage -r
killall quicklookd QuickLookUIService Finder 2>/dev/null
open -a "Marked Quick Look"

Wait for the app to open, then run:

pluginkit -a "/Applications/Marked Quick Look.app/Contents/PlugIns/MarkedQuickLookPreview.appex"
pluginkit -e use -i com.brettterpstra.MarkedQuickLook.preview

If Quick Look still does not work:

1. Delete Marked Quick Look from /Applications
2. Restart your Mac
3. Reinstall from the Mac App Store
4. Launch the app once
5. Repeat the registration commands above

If you still need help, copy this template, fill it in, and email marked@brettterpstra.com:

macOS version:
(sw_vers output)

Marked Quick Look installed in /Applications:
(yes/no)

Launched Marked Quick Look after install:
(yes/no)

What happens when you press Spacebar:
(no panel / plain text / styled preview from another app)

Other Markdown or Quick Look apps installed:
(list any from the conflict table above)

Output of:
pluginkit -m -D -p com.apple.quicklook.preview -A -v | grep -i MarkedQuickLook
mdls -name kMDItemContentType -name kMDItemContentTypeTree /path/to/failing/file.md

Console errors (if any):
(paste from Console.app while previewing)

Most first-day issues are resolved by launching the app once and re-registering the extension:

open -a "Marked Quick Look"
pluginkit -a "/Applications/Marked Quick Look.app/Contents/PlugIns/MarkedQuickLookPreview.appex"
pluginkit -e use -i com.brettterpstra.MarkedQuickLook.preview
killall quicklookd QuickLookUIService 2>/dev/null
qlmanage -r cache

Then press Spacebar on a .md file in Finder.