Peekdown
Website & demo · Download the latest release
A native macOS Quick Look extension that renders Markdown (.md, .markdown, .mdown, .mkd, .mkdn) as formatted documents when you press Space in Finder — headings, lists, tables, code, and more — and syntax-highlights standalone YAML (.yaml, .yml). Markdown files also get a styled thumbnail in the Finder preview pane.
Markdown is parsed to an NSAttributedString in Swift and drawn with AppKit. No WebKit, no JavaScript, no HTML importer — so it works inside the Quick Look sandbox.
Release status
v1.1.1 includes manual update checks, standalone YAML, appearance settings, static MDX, and
experimental native Mermaid/math. Diagram and equation rendering are off by
default; enable them in Peekdown. See the support docs for supported syntax.
Features
- Manual update checks (v1.1.1) — check for stable GitHub releases from the app menu or window, then open the release page to download. No background checks or automatic installation. See update checks and network behavior.
- Quick Look preview — select a
.md file and press Space for a rendered document.
- YAML preview — select a
.yaml or .yml file and press Space for a syntax-colored code panel. Oversized or invalid YAML stays plain monospaced text. See YAML previews.
- Appearance preferences — open Peekdown to adjust text size (80–160%), compact paragraph spacing, and code line spacing. Reopen Quick Look to apply changes.
- Experimental Mermaid (experimental, off by default) — native flowcharts and sequence diagrams in
mermaid fences. Unsupported input remains source.
- Experimental display math (experimental, off by default) — native equations between standalone
$$ or \[ / \] delimiter lines. Inline math is not enabled.
- Static MDX —
.mdx previews render ordinary Markdown; imports, JSX, and expressions remain literal source and never execute. This is not full MDX component rendering.
- Finder thumbnails — a styled card with the first heading and a text snippet for Markdown files.
- Renders CommonMark-ish Markdown natively:
- ATX and setext headings
- bold, italic, strikethrough, inline code
- fenced and indented code blocks
- language-aware fenced-code colors for Swift, shell, JSON, YAML, Python, JavaScript, and TypeScript (available in v1.0.4)
- ordered, unordered, and nested lists
- GFM task lists (
- [x] / - [ ] → ☑ / ☐)
- tables (box-drawn, width-capped and word-wrapped)
- links, images (alt text), blockquotes, horizontal rules
- URL/email recognition with a Copy link fallback, numbered footnotes, and GitHub-style alerts (available in v1.0.3)
- YAML front-matter stripping
- Light and dark mode (system label colors).
- The host app imports the
net.daringfireball.markdown UTI so Finder routes .md files to this extension.
- Standalone YAML uses the system
public.yaml type (.yaml and .yml). The host app declares that type with document role and handler rank None, so Peekdown does not become the default editor.
See native Markdown support for syntax examples and
limitations. See experimental previews and settings for examples and limits. Quick Look
may block opening external links; copying a recognized destination is supported.
The host app registers Markdown types for previews without claiming to be a
document editor or viewer.
Installation
Homebrew (recommended)
brew install --cask h0ck3ystyx/tap/peekdown
Manual installation
Download the latest release from the releases page.
- Installer package: Download and run
Peekdown-VERSION.pkg
- ZIP archive: Download
Peekdown-VERSION.zip, extract, and move Peekdown.app to ~/Applications
After installation, launch Peekdown.app once, then select a Markdown file in Finder
and press Space. Version 1.1.0 also accepts .yaml, .yml, and .mdx.
Distribution releases
Signed and notarized releases are built automatically via GitHub Actions when a v*
tag is pushed. See RELEASE.md for release automation setup and local
release instructions. The release build supports Intel and Apple Silicon.
Development signing and ad-hoc builds below are for local use.
The installer .pkg offers Install for me only (~/Applications, no admin password)
and Install for all users of this computer (/Applications, administrator
authorization). Use Change Install Location… if Installer skips the
destination screen.
Peekdown was previously named MarkdownPreview. After installing Peekdown, remove
the old MarkdownPreview.app copy to avoid duplicate extension registrations.
The bundle identifiers retain com.markdownpreview for signing continuity.
Requirements
- macOS 12.0+
- Xcode (full Xcode, not just Command Line Tools) — the preview extension needs a real code-signing identity
- An Apple ID signed into Xcode with a (free) Personal Team
- XcodeGen (
brew install xcodegen)
Why a real identity? On macOS 13+, Quick Look preview extensions are discovered by ExtensionKit, which does not launch ad-hoc-signed preview extensions (symptom: raw text, or a key cannot be nil crash). Thumbnail extensions work ad-hoc via a separate daemon. The free Personal Team is sufficient.
Build & install
1. Configure signing
Set your development team when building (or edit DEVELOPMENT_TEAM in
project.yml). Find your team ID with:
defaults read com.apple.dt.Xcode | grep -A4 IDEProvisioningTeamByIdentifier
This is the beginning of the README. Read the rest at the original. Read the full README ↗
