MDViewer

A minimal macOS Markdown viewer. No editor, no bloat — just clean rendering with automatic Dark Mode support.

Features

• GitHub-flavored rendering via marked.js
• Syntax highlighting — code blocks auto-detected and highlighted via highlight.js
• Local images & video — ![alt](path) and <img> tags resolve relative to the markdown file; <video> tags work too
• Mermaid diagrams — fenced ```mermaid blocks render natively as SVG with zoom, pan, and keyboard controls
• Diagram export — save any Mermaid diagram as SVG or PNG (File → Export Mermaid Diagram)
• Dark Mode — automatic (system), light, or dark via View > Appearance
• Zoom — Cmd + / Cmd - with persistent zoom level
• Reload — Cmd R to refresh after external edits
• Sidebar — browse all .md files in the current directory with Cmd Shift S or Cmd B
• File navigation — Cmd ← / Cmd → cycles through all .md files in the same directory, alphabetically (or by date modified — change in Sort By menu)
• Internal links — click links between .md files to navigate within MDViewer
• Footnotes — GitHub-style footnotes rendered and linked automatically
• In-document search — Cmd F find bar with next/previous match and match count
• Quick open — Cmd K floating file picker: type a path, Tab to complete directories, ../ to navigate up, results filtered to .md files only
• Native file handling — Open, Recent Files, drag & drop
• No Electron, no runtime — native macOS app

Performance

Metric	Value
App size	~ 4.5 MB
Download (zip)	~ 1.3 MB
Cold start	< 50 ms
Memory	< 100 MB

Install

Homebrew (recommended)

brew tap sdkks/tap
brew install --cask mdviewer

Gatekeeper is handled automatically — no extra steps needed.

Manual

Download the latest .app from Releases, unzip, and drag to /Applications.

On first launch macOS will block the app because it is unsigned. Right-click > Open works, or run this once in Terminal:

xattr -dr com.apple.quarantine /Applications/MDViewer.app

Keyboard Shortcuts

Action	Shortcut
Previous file in directory	Cmd ←
Next file in directory	Cmd →
Toggle sidebar	Cmd Shift S
Toggle sidebar (alt)	Cmd B
Find in document	Cmd F
Find next match	Cmd G
Find previous match	Cmd Shift G
Quick open file	Cmd K
Reload	Cmd R
Zoom In	Cmd +
Zoom Out	Cmd -
Actual Size	Cmd 0
System Appearance	Cmd Shift 0
Light Mode	Cmd Shift 1
Dark Mode	Cmd Shift 2

Quick Open (Cmd K)

The file picker lets you jump to any .md file on your filesystem without leaving the keyboard:

• Type a partial path or filename — results update as you type (substring match)
• Tab — completes the current directory segment; appends / to drill in
• ../ — navigates to the parent directory, just like a shell
• ../../ — chains upward arbitrarily
• ↑ / ↓ — move through the candidate list
• Return — opens the selected file in a new window
• Escape — closes the picker without navigating

The picker anchors to the directory of the currently open file, or your home directory if no file is open.

Sidebar

The sidebar (Cmd Shift S or Cmd B) shows every Markdown file in the same directory as the current document. Click any file to open it instantly.

• Sort order — alphabetical (default) or by date modified, via View → Sort By
• Live sync — changes made in other apps (new files, renames, deletes) appear automatically
• Selection follows — the currently open file is always highlighted
• Persistence — sidebar visibility is remembered across launches (toggle in Preferences)

Mermaid Diagrams

Fenced ```mermaid blocks render as interactive SVG diagrams:

• Zoom & pan — click and drag to pan; hold Cmd (or Ctrl) and scroll to zoom
• Keyboard controls — focus a diagram (click or Tab) and use:
  • + / - — zoom in/out
  • Arrow keys — pan
  • 0 — fit to view
  • Escape — reset zoom and pan
• Fit to view — diagrams scale to the window width automatically (toggle in View → Fit Diagrams to View)
• Export — File → Export Mermaid Diagram → SVG or PNG saves all diagrams in the current document
• Error diagnostics — syntax errors show an inline error message with the problematic source line highlighted

Building from Source

Prerequisites: Xcode 16+, Command Line Tools, XcodeGen

brew install xcodegen
git clone https://github.com/sdkks/mdviewer
cd mdviewer
make build

make build runs xcodegen generate then builds a Release .app in Xcode's DerivedData.

Releasing

1. Make a commit with a versioned prefix

The version bump script reads the most recent commit message to decide which component to increment:

Commit prefix	Version bump
Breaking:	major (1.0.0 → 2.0.0)
Feature:	minor (1.0.0 → 1.1.0)
Core:	minor (1.0.0 → 1.1.0)
Fix:	patch (1.0.0 → 1.0.1)

Example:

git commit -m "Feature: add table of contents sidebar"

2. Bump the version

make version-bump

This reads the last commit message, increments MARKETING_VERSION and CURRENT_PROJECT_VERSION in project.yml, regenerates the Xcode project, commits the change, and creates an annotated git tag (e.g. v1.1.0).

3. Ship it

Prerequisites: gh CLI installed and authenticated, GH_TOKEN env var set with a fine-grained token scoped to sdkks/mdviewer with Contents: read & write.

make release

This pushes all commits and tags, builds a Release archive, ad-hoc signs MDViewer.app, zips it, creates a GitHub Release for the current tag, uploads the zip as a release asset, and updates the Homebrew cask in sdkks/homebrew-tap automatically.

Prerequisites for tap push: the tap repo must be checked out at ../homebrew-tap relative to this repo.

Dependencies

Library	Version	License	Purpose
marked	15.0.7	MIT	Markdown → HTML parsing
mermaid	~11.5	MIT	Diagram rendering (SVG)
highlight.js	~11.9	BSD-3	Syntax highlighting
svg-pan-zoom	~3.6	BSD-2	Diagram zoom & pan
marked-footnote	—	MIT	Footnote support

No Swift package dependencies. No external frameworks.

License

MIT