Open Markdown

A fast, native macOS/Windows/Linux desktop app for viewing Markdown files with live preview, syntax highlighting, and Mermaid diagram support.

Features

• GitHub-flavored Markdown - Tables, task lists, strikethrough, and more
• Syntax Highlighting - Code blocks with language detection and theme-aware colors
• Mermaid Diagrams - Flowcharts, sequence diagrams, ERDs, and more
• Live Reload - Automatically updates when the file changes, with change highlighting
• Multi-Window - Open multiple files side by side (Cmd+N)
• Dark/Light Theme - Follows system preference or manual toggle
• Drag & Drop - Drop markdown files directly into the app
• Find in Page - Search within rendered content (Cmd+F)
• Folder Sidebar - Open a folder (Cmd+Alt+O, or drop it on the window) and browse its markdown files as a tree that follows the open document, filters by name and updates as files change (Cmd+Shift+E to focus)
• Document Outline - Sidebar of headings that follows your scroll position and jumps to any section (Cmd+Shift+O)
• Open Documents Browser - Grid of thumbnails of every open document plus recent files, filtered by name or content (Cmd+Shift+D)
• Open by Path - Paste a full path, or a path relative to the current document, and press Enter (Cmd+P)
• Clickable Task Lists - Tick a checkbox in the rendered document and the - [ ] in the file follows
• Copy Code - Hover a code block for a copy button, or press Cmd+Shift+C
• Copy as Rich Text - Paste the document, a selection or a section into Slack, mail, Notion or Google Docs with formatting intact
• Front Matter - YAML metadata at the top of a file shows as a collapsible table
• Alerts - > [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] and [!CAUTION] render as GitHub does
• Math - $…$, $$…$$, \(…\) and \[…\] rendered with KaTeX, offline
• File References - src/app.ts:42 opens the file in your editor at that line; docs/plan.md opens in the viewer
• Code Block Titles & Line Highlights - ```ts title="app.ts" {2-3} draws a title bar and calls out lines; diff blocks colour whole lines
• Footnotes - [^1] references with back links
• Table Editor - In edit mode a table is edited cell by cell in place: Tab and Enter move between cells, handles insert, move, align and delete rows and columns, and the file gets an aligned pipe table back
• Print & Export - Print (Cmd+Shift+P), or export a self-contained HTML file or a PDF with vector diagrams (File → Export)
• Navigation - Links between markdown files open in place (Cmd-click for a new window), with Back/Forward (Cmd+[, Cmd+]) and a quick switcher (Cmd+T)
• Lightbox & Diagram Zoom - Click an image to see it large; zoom and pan diagrams in place
• Native Performance - Built with Electron for a smooth experience

Installation

Mac App Store (recommended for macOS):

Or download the latest release from the Releases page:

• macOS: .dmg or .zip
• Windows: .exe installer
• Linux: .deb or .rpm

Builds from the Releases page check for new versions on launch and every few hours (Preferences → Updates to turn that off or follow pre-releases). macOS and Windows download the update in the background and offer a restart; Linux shows where to download it. The Mac App Store build is updated by the App Store.

Usage

1. Open a file: Click the "Open" button or use Cmd+O (macOS) / Ctrl+O (Windows/Linux)
2. Drag & Drop: Drag a .md file, or a whole folder, directly into the app window
3. Open a folder: File → Open Folder… (Cmd+Alt+O), or open-markdown ./docs from a terminal; the sidebar lists its markdown files, opens its README and remembers the folder for next time
4. New window: Cmd+N to open additional windows for side-by-side viewing
5. Toggle theme: Click the theme button in the toolbar to switch between light and dark mode

The app will automatically reload when the file is modified externally.

Development

Prerequisites

• Node.js 20+
• pnpm 10+

Setup

# Clone the repository
git clone https://github.com/ptheofan/open-markdown.git
cd markdown-viewer

# Install dependencies
pnpm install

Running Locally

# Start the app in development mode with hot reload
pnpm start

Scripts

Command	Description
pnpm start	Start app in development mode
pnpm test	Run unit tests
pnpm test:e2e	Run end-to-end tests
pnpm lint	Run ESLint
pnpm typecheck	Run TypeScript type checking
pnpm package	Package the app (no installer)
pnpm make	Build distributable installers

Building

# Package for current platform
pnpm package

# Create distributable installers (DMG, EXE, DEB, RPM)
pnpm make

Build artifacts are output to the out/ directory.

Releasing

Tag a version and push the tag; the Release workflow builds the installers on macOS, Windows and Linux and uploads them to a draft GitHub Release. Publish the draft and the in-app updater (via update.electronjs.org) starts serving it.

# bump "version" in package.json, update CHANGELOG.md, commit, then
git tag v1.6.0 && git push origin v1.6.0

• Squirrel.Mac only installs updates that are signed with a Developer ID and notarized. The workflow signs and notarizes when the MACOS_DEVELOPER_ID_CERTIFICATE, MACOS_DEVELOPER_ID_CERTIFICATE_PWD, MACOS_KEYCHAIN_PWD, APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD and APPLE_TEAM_ID secrets are set; without them the macOS build is ad-hoc signed and can only be installed by hand.
• Windows installs come from Squirrel.Windows (RELEASES + .nupkg are uploaded alongside the installer). Sign the installer for SmartScreen when a certificate is available.
• A pre-release (tick "pre-release" on the draft) is announced to users on the Beta channel but never installed automatically.
• The Mac App Store build (release-mas.yml) contains no updater path: process.mas turns it off.

Tech Stack

• Framework: Electron with Electron Forge
• Language: TypeScript (strict mode)
• Bundler: Vite
• Markdown: markdown-it
• Syntax Highlighting: highlight.js
• Diagrams: Mermaid
• File Watching: chokidar
• Testing: Vitest + Playwright

Project Structure

src/
├── main/           # Main process (Node.js)
│   ├── window/     # BrowserWindow management
│   ├── ipc/        # IPC handlers
│   └── services/   # File, theme, and watcher services
├── preload/        # Preload scripts (secure bridge)
├── renderer/       # Renderer process (UI)
│   └── components/ # UI components
├── plugins/        # Markdown plugin system
│   ├── core/       # Plugin manager and renderer
│   └── builtin/    # GFM, syntax highlight, Mermaid
└── shared/         # Shared types, constants, errors

License

GPL-3.0