Quick Look shows raw text
Press Space on a .md file and macOS dumps the raw source — hashes, asterisks, dashes and all. Unreadable.
Markdown was never meant
to be previewed plain text.
The most readable way to preview any .md file on macOS.
Open source, free
Agent instructions
This file configures how the AI agent behaves in this repo. Read carefully before running any automated task or deploying to production.
Commands
$ npm run build · npm test · npm run lint
---
title: Agent instructions
tags: [agent, config, v2]
version: 2.1
---
# Agent instructions
This file configures how the AI agent
behaves in this repo. Read carefully
before running any automated task.
## Commands
$ npm run build · npm test · npm run lint
The problem with .md files on macOS #
AI files are a mess to read
AGENTS.md, CLAUDE.md, .cursorrules — full of XML tags, alerts, and structured prompts. Every viewer renders them as garbled angle brackets.
Diagrams and math render as code
Mermaid flowcharts and LaTeX equations are just raw text in every other previewer. You have to open a browser to see what they actually look like.
AI writes in markdown.
The least you can do is render it.
unique to showmd
Built for how
markdown is actually used today.
YAML frontmatter parsed into a collapsible metadata table — collapsed by default, one click to expand. No other viewer does this.
Agentic AI XML tags — <example>, <instructions>, <thinking>, and 17 more — rendered as labeled, bordered blocks instead of raw angle brackets.
raw file
--- title: Agent instructions tags: [agent, config, v2] --- <instructions> Follow these rules carefully. </instructions> <example> Run: npm test </example>
→
showmd renders
▶
METADATA (2) — YAML FRONTMATTER
| title | Agent instructions |
|---|---|
| tags | agent, config, v2 |
<instructions>
Follow these rules carefully.
<example>
Run: npm test
what it does #
Instant open
Set as default for .md files. Spacebar to preview in Finder. Zero friction.
macOS native
Feels like it belongs. Respects system fonts, dark mode, and your keyboard.
Full GitHub Flavored Markdown
Tables, task lists, strikethrough, autolinks, footnotes, and more. Powered by Apple's swift-markdown parser.
Frontmatter rendering
YAML metadata rendered as a collapsible table. Collapsed by default, one click to expand. Unique to showmd.
No bloat
Not an editor. Not a note app. Just a viewer. Opens in under a second.
Rendered & source
Switch between rendered and raw markdown with a single click. Copy as HTML anytime.
Private by default
No cloud. No uploads. No telemetry. Your files never leave your machine.
Syntax highlighting
Code blocks rendered with language-aware highlighting. Supports 190+ languages out of the box.
LaTeX math
Inline $x^2$ and block $$...$$ expressions rendered beautifully via KaTeX.
Mermaid diagrams
Flowcharts, sequence diagrams, state machines, and more — rendered inline from code blocks.
All markdown flavors
.md, .markdown, .mdx, .mdc, .rmd, .qmd, .mdown, .mkd, .mkdn — every markdown extension, one previewer.
Emoji, footnotes & more
Emoji shortcodes, footnotes, ==highlight==, ^super^script, ~sub~script, smart quotes, and autolinked URLs — all built in.
Inline images
Relative image paths resolve correctly in Quick Look. Your local screenshots and diagrams just work.
GitHub-style alerts
NOTE, TIP, IMPORTANT, WARNING, and CAUTION callouts — rendered with colored borders and icons, just like on GitHub.
Agentic AI tags
Custom XML tags used in AI prompts — <example>, <instructions>, <thinking>, and more — rendered as labeled, bordered blocks.
get it #
-
01
Download & open
The extension registers automatically. No config needed.
-
02
Enable in System Settings
Privacy & Security → Extensions → Quick Look. One toggle.
-
03
Press Space in Finder
Rendered markdown, frontmatter, source toggle. Done.
Do you like it? Buy me a pasta 🍝
FAQ #
- Download showmd, open it once, then go to System Settings → Privacy & Security → Extensions → Quick Look. Enable showmd there. After that, pressing Space on any .md file in Finder will use showmd automatically.
- showmd parses the
---block and renders it as a collapsible metadata table — collapsed by default so it never gets in the way. Supports plain values, quoted strings, arrays, and multi-line folded blocks. - Yes. showmd has a Rendered / Source toggle at the top of every preview. Click Source to see the original Markdown, Rendered to go back. You can also copy the file as HTML from the Rendered view.
- Yes — showmd follows your macOS appearance setting automatically. You can also override it in showmd's settings: choose Light, Dark, or Auto.
- Full GitHub Flavored Markdown (GFM) — tables, task lists, strikethrough, fenced code blocks. Plus syntax highlighting for 190+ languages, math rendering (LaTeX via KaTeX), emoji shortcodes, footnotes, highlight/superscript/subscript syntax, smart quotes, optional Mermaid diagrams, GitHub-style alerts (NOTE, TIP, WARNING, etc.), and styled agentic AI XML tags. Everything renders offline with no internet needed.
.md,.markdown,.mdx,.mdc,.rmd,.qmd,.mdown,.mkd,.mkdn,.mdtext, and.mdtxt. All recognized automatically in Finder Quick Look.- The closest alternatives are other macOS Quick Look extensions for Markdown. Markdown Preview by Anybox ($2.99 on the App Store) is the most direct competitor. QLMarkdown is free and open source but doesn't include a standalone settings app. showmd sets itself apart by being free, open source, hassle-free to install (one command via Homebrew), and feature-complete — YAML frontmatter, syntax highlighting, math, Mermaid diagrams, and a settings app — all in one package.
- No. showmd is a viewer only — a Quick Look extension. It opens files read-only. Its job is to render your markdown and get out of the way.
- Yes — completely free and open source under the MIT license. Source on GitHub. If it saves you a trip to VS Code, you can optionally buy the developer a pasta.
