A fast, lightweight native Markdown viewer for macOS

Render GitHub-flavored and Obsidian-style Markdown as beautiful HTML in a native window — with instant load time and a tiny binary footprint.

Features · Installation · Usage · Development · Contributing · Colophon

Features

Metadata Bar

Frontmatter is rendered as a structured metadata bar above your content — title as heading, description as subtitle, tags and status as color-coded badges.

Properties Box

A collapsible panel below content showing all frontmatter properties with icons, pill badges, and boolean toggles (✅/❌).

Callout Types

NOTE · TIP · WARNING · CAUTION · IMPORTANT — with foldable support (> [!TIP]+)

Wikilinks

• [[My Document]] → links to my-document.html
• [[#Heading]] → anchors within the page
• [[path\|label]] → custom display text

Installation

Option 1: Download (macOS)

1. Go to the Releases page
2. Download the latest .dmg (Apple Silicon)
3. Open the .dmg and drag Markdown Viewer to Applications

Updating to a new version:

# Check for updates
make update --check

# Install the latest version
make update

This downloads the latest release .dmg, mounts it, copies the app to ~/Applications/, removes quarantine, and re-signs — all in one command. Requires jq (brew install jq).

First launch: macOS may show "app is damaged" due to quarantine. Run:

xattr -cr /Applications/Markdown\ Viewer.app

Tested on: macOS 26.4 (25E246) on Apple Silicon (M-series).

Option 2: Build from Source

Prerequisites:

• Rust 1.94+ stable (rustup)
• Node.js 18+ (for Tauri CLI)
• Xcode Command Line Tools

# Clone the repo
git clone https://github.com/rajatarya/mdviewer.git
cd mdviewer

# Install Tauri CLI
npm install -g @tauri-apps/cli

# Build and install (copies .app to ~/Applications, creates ~/.local/bin/mdviewer wrapper)
make install

Or install without rebuilding (after a fresh bundle):

make install-fast

The wrapper script at ~/.local/bin/mdviewer launches the .app with open -a and passes through any arguments. It also handles --help inline (no app launch needed).

Usage

CLI

# Open a single file
mdviewer document.md

# Open multiple files
mdviewer doc1.md doc2.md notes.txt

# Show help
mdviewer --help

# Pipe from stdin
cat document.md | mdviewer -

GUI

1. Launch Markdown Viewer from Applications
2. Open a file via File → Open or drag-and-drop onto the app icon
3. Navigate between files using the sidebar

Double-clicking a .md, .markdown, or .txt file in Finder will also open it in Markdown Viewer (file association registered during install).

Development

# Run in development mode (hot-reload enabled)
cargo tauri dev

# Format and lint
cargo fmt
cargo clippy -- -D warnings

# Run tests
cargo test --lib

# Full check before committing
make all

Architecture

Tauri 2.x (Rust backend)
  ├─ pulldown-cmark  → Markdown parsing
  ├─ ammonia         → HTML sanitization
  ├─ regex           → Text preprocessing
  └─ Webview (HTML/CSS/JS)
      ├─ KaTeX       → Math rendering
      └─ Mermaid.js  → Diagram rendering

See DESIGN.md for the full architecture and rendering pipeline.

Contributing

Forks and issues are welcome — see CONTRIBUTING.md for details. We encourage personal forks and bug reports, and discourage blind AI-generated PRs.

Colophon

This app was designed and implemented entirely by AI coding agents.

The initial implementation — every line of Rust, every CSS rule, every JavaScript function — was written by pi.dev using the Qwen3.6-35B-A3B-GGUF:BF16 model by Unsloth (🤗 Hugging Face), hosted locally via llama.cpp on an M5 MacBook Pro (128 GB RAM).

Subsequent fixes and architectural work — including the Tauri 2.x migration cleanup, the v1.4.0 macOS file-open deadlock investigation, and the frontmatter rendering redesign — were done by Claude (Anthropic), accessed through Claude Code.

The result: a complete, tested, production-ready native macOS app — from zero to shipped — without a single human typing code.

Stack: Tauri 2 · Rust · pulldown-cmark · ammonia · KaTeX · Mermaid.js

Release Process

Automated since v1.6.0 — see .github/workflows/release.yml.

To cut a release:

# 1. Ensure everything passes
make all

# 2. Bump version in both files
sed -i '' 's/version = ".*"/version = "1.7.0"/' src-tauri/Cargo.toml
sed -i '' 's/"version": ".*"/"version": "1.7.0"/' src-tauri/tauri.conf.json

# 3. Commit and tag
git add -A && git commit -m "chore(release): bump version to 1.7.0"
git tag v1.7.0 && git push origin main --tags

# 4. GitHub Actions builds the .dmg and publishes the release automatically

License

MIT · © 2026 Rajat Arya