MarkdownViewer

A native macOS Markdown viewer built with Tauri v2. Browse folders, read .md files with a clean rendered view, navigate between documents, and enjoy a native experience with dark mode support.

Documentation

Features

Core

• Folder browsing — Open any folder and navigate its directory tree via the sidebar
• Outline panel — Auto-generated table of contents (h2/h3) with scroll tracking
• Relative link navigation — Click .md links to navigate between documents
• Dark mode — Follows macOS system appearance, toggleable manually
• Session persistence — Remembers your last opened folder across launches
• Open single files — Open .md files directly via CLI, Finder "Open With", or drag & drop
• PDF export — Export the current document as PDF with native rendering
• CLI support — Open a folder or file directly: mdv ~/docs or mdv ~/docs/README.md
• Native menu — Cmd+O to open a folder, standard macOS app menu

Markdown Rendering

• GitHub-Flavored Markdown — Headings, tables, code blocks, blockquotes, task lists, strikethrough
• Syntax highlighting — Code blocks with language detection via highlight.js
• Math (KaTeX) — Inline $...$ and display $$...$$ math expressions
• Mermaid diagrams — Rendered diagrams with fullscreen view
• GitHub Alerts — [!NOTE], [!TIP], [!WARNING], [!IMPORTANT], [!CAUTION]
• Footnotes — Reference-style footnotes with backlinks
• Smart typography — Curly quotes, em/en dashes, ellipses
• Emoji shortcodes — :rocket:, :heart:, :fire: and 80+ more
• Extended tables — Colspan via || syntax
• Copy button — One-click code block copying
• Image lightbox — Click any image to view fullscreen
• Task list checkboxes — - [x] and - [ ] rendered as checkboxes

Security

All rendered HTML is sanitized through DOMPurify before being displayed. This protects against:

• Script injection — <script> tags are stripped
• Event handler XSS — onerror, onclick, onload, ontoggle attributes are removed
• JavaScript URIs — href="javascript:..." links are neutralized
• Iframe injection — <iframe> elements are stripped

Safe content like KaTeX math output, MathML, checkboxes, and footnote attributes are preserved through a configured allowlist.

Examples

The app includes a built-in View examples button on the welcome screen that loads sample documents showcasing all supported features. These examples are also available in the examples/ directory.

Download

Download the latest .dmg from the Releases page. The app is signed and notarized by Apple.

Build from Source

Prerequisites

• Node.js >= 18
• Rust (stable)
• macOS with Xcode Command Line Tools

Steps

# Clone the repo
git clone git@github.com:ekino/MarkdownViewer.git
cd MarkdownViewer

# Install dependencies
npm install

# Run in development mode
npm run tauri dev

# Build for production (.app + .dmg)
npm run tauri build

The built app will be at src-tauri/target/release/bundle/macos/Markdown Viewer.app.

Usage

GUI

1. Launch the app
2. Click Open folder or press Cmd+O
3. Select a folder containing .md files
4. Browse and read your documentation

CLI

# Open a specific folder
mdv ~/my-docs

# Open a single file (loads its parent directory in the sidebar)
mdv ~/my-docs/README.md

Tech Stack

• Tauri v2 — Native app shell with Rust backend
• Vite — Frontend build tool
• TypeScript — Type-safe frontend logic
• marked — Markdown parser with extensions:
  • marked-alert — GitHub-style alerts
  • marked-footnote — Footnotes
  • marked-highlight — Syntax highlighting
  • marked-katex-extension — KaTeX math
  • marked-smartypants — Smart typography
  • marked-extended-tables — Extended tables
  • marked-emoji — Emoji shortcodes
• Mermaid — Diagram rendering
• highlight.js — Code syntax highlighting
• DOMPurify — HTML sanitization
• Tauri plugins — fs (file access), dialog (folder picker), store (persistence)

License

MIT

---