showmd

The most readable way to preview any .md file on macOS.
A free, native Quick Look extension that renders Markdown beautifully — press Space in Finder and go.

Website · Install · Features · Build from Source

---

Install

Requires macOS 26 (Tahoe) or later.

brew install --cask johannesnagl/tap/showmd

Then open showmd once, go to System Settings → Privacy & Security → Extensions → Quick Look, and enable it. After that, pressing Space on any Markdown file in Finder will use showmd automatically.

Note: On first launch, macOS will ask showmd to "access data from other apps." This is required so the host app and the Quick Look extension can share your settings (theme, font size, etc.) via App Groups. Click Allow — it only happens once.

Features

• Full GitHub Flavored Markdown — tables, task lists, strikethrough, fenced code blocks
• Syntax highlighting for 190+ languages (highlight.js, bundled offline)
• Math rendering — LaTeX via KaTeX, inline $...$ and block $$...$$
• Mermaid diagrams — optional, toggle in settings
• YAML frontmatter — parsed and rendered as a collapsible metadata table
• Emoji shortcodes — :rocket: → 🚀
• GitHub-style alerts — > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], > [!CAUTION]
• Agentic AI XML tags — <example>, <instructions>, <thinking>, <context>, and more rendered as labeled blocks
• Footnotes, highlight, superscript, subscript, smart quotes
• Rendered / Source toggle — switch between rendered HTML and raw Markdown
• Copy as HTML — one click to copy the rendered output
• Dark mode — follows macOS appearance, or override in settings (Light / Dark / Auto)
• Adjustable font size — Small, Medium, or Large
• Menu bar mode — optionally hide the Dock icon and keep showmd in the menu bar instead
• Fully offline — all JS/CSS dependencies are bundled, no network needed
• XSS-hardened — all user content is escaped and raw HTML is sanitized

Supported file extensions

.md, .markdown, .mdx, .mdc, .rmd, .qmd, .mdown, .mkd, .mkdn, .mdtext, .mdtxt

Build from Source

Prerequisites

• macOS 26 or later
• Xcode 16 or later
• XcodeGen — brew install xcodegen

Steps

# Clone the repo
git clone https://github.com/johannesnagl/showmd.git
cd show.md

# Generate the Xcode project
xcodegen generate

# Open in Xcode
open show.md.xcodeproj

In Xcode:

1. Set your Development Team in Signing & Capabilities for both the ShowMd and ShowMdExtension targets
2. Build and run the ShowMd scheme

The .xcodeproj is generated from project.yml and excluded from git. Always regenerate it after pulling changes.

Run tests

cd MarkdownRenderer
swift test

Architecture

show.md/
├── ShowMd/                  # Host app (SwiftUI settings window)
├── ShowMdExtension/         # Quick Look preview extension
├── MarkdownRenderer/        # Swift package (shared between both targets)
│   ├── Sources/
│   │   └── MarkdownRenderer/
│   │       ├── HTMLVisitor.swift       # Markdown → HTML conversion
│   │       ├── HTMLTemplate.swift      # HTML page wrapper + theme
│   │       ├── HTMLPostProcessor.swift # Emoji, footnotes, autolinks, etc.
│   │       ├── HTMLEscape.swift        # XSS prevention
│   │       ├── FrontmatterParser.swift # YAML frontmatter extraction
│   │       ├── ResourceLoader.swift    # Bundled JS/CSS loader
│   │       ├── Settings.swift          # UserDefaults via App Groups
│   │       └── Resources/             # highlight.js, KaTeX, Mermaid (offline)
│   └── Tests/
├── docs/                    # Marketing website (showmd)
└── project.yml              # XcodeGen project definition

Settings are shared between the host app and the Quick Look extension via App Groups (group.one.yetanother.showmd).

Dependencies

Dependency	Purpose
apple/swift-markdown	Markdown parsing (GFM)
highlight.js	Syntax highlighting (bundled)
KaTeX	Math rendering (bundled)
Mermaid	Diagram rendering (bundled)

Contributors

Thanks to everyone who has contributed to showmd:

• @oschrenk — Homebrew cask fix
• @boxpositron (David Ibia) — Menu bar mode
• @gsamat — Surfacing macOS version requirement
• @arhtwk — Reporting Quarto callout and hyperlink issues
• @TokkeDev — Reporting sandbox-blocked link opening

License

MIT

Author

Johannes Nagl — showmd

Concept, growth, and everything except coding — coded with Claude.