Documentation

Getting Started

Open Markdown is a native macOS app for reading Markdown files. Open any .md file and it renders instantly with GitHub-style formatting.

There are several ways to open a file:

• Use File → Open or press Cmd+O
• Drag & drop a file onto the app window or the Dock icon
• Double-click a Markdown file in Finder (once file associations are set up)
• Open from the terminal: open -a "Open Markdown" README.md

Live Reload

When a file is open, Open Markdown watches it for changes. Edit the file in any text editor and the preview updates automatically — no manual refresh needed.

Changed sections are briefly highlighted so you can see exactly what was modified.

Multi-Window

Press Cmd+N to open a new window and view multiple files side by side. Each window independently tracks and live-reloads its own file.

Edit Mode

Press Cmd+E (or the Edit button in the toolbar) to toggle edit mode. The rendered document becomes editable in place — no separate textarea, no syntax view.

Each block (paragraph, heading, list, quote, code block) shows a handle on hover. Click the handle to open a menu that lets you convert the block to a different type, duplicate it, move it up or down, or delete it.

Formatting — with text selected:

Navigation and structure:

• Enter splits the current block at the caret — the new block below gets focus
• Shift+Enter inserts a line break inside the current block
• ArrowUp / ArrowDown at the top or bottom of a block moves the caret to the adjacent block
• Esc commits the edit and exits the block

Toggles:

• Cmd+/ drops the active block into a raw-markdown editor — useful for content the WYSIWYG editor can't represent (e.g. images, footnotes). The next click on the block returns to WYSIWYG.
• Cmd+Shift+F toggles a small floating toolbar with buttons for the formatting actions above. Starts hidden each session.

Blocks containing inline content the editor can't faithfully round-trip (raw HTML, inline images, superscript, etc.) open in the raw-markdown editor automatically so the source is never silently changed.

Images

Inline images load directly in the rendered document:

• Local paths — relative (![](images/photo.png)) or absolute (![](/Users/you/Pictures/photo.png)) filesystem paths, served via a dedicated om-asset: protocol restricted to image file types
• Remote URLs — https:// URLs are loaded by the renderer

Supported image formats: PNG, JPEG, GIF, SVG, WebP, AVIF, ICO, BMP.

Links

Links in rendered documents work the way you'd expect:

• Hover a link to see its target URL in the status bar
• Click an HTTP/HTTPS link to open it in your default browser
• Right-click for a menu with options to copy the URL or open it explicitly

External Editor

If you'd rather make heavier edits in your usual editor, configure an external editor command in Preferences → External Editor (for example, code for VS Code, cursor for Cursor, subl for Sublime). A button in the toolbar then opens the current file in that editor with one click.

Live reload picks up the changes as soon as you save in the external editor.

Window State

The app remembers each window's size, position, and fullscreen state. When you reopen Open Markdown, your windows come back exactly where they were.

Keyboard Shortcuts

Global

In edit mode (with text selected, unless noted)

Supported Formats

Open Markdown recognises files with the following extensions:

• .md
• .markdown
• .mdown
• .mkdn
• .mkd

File Associations

To double-click a Markdown file and have it open in Open Markdown, you need to set it as the default app:

Via System Settings (macOS 14+):

1. Open System Settings → Default Apps
2. Set Open Markdown as the default for Markdown files

Via Finder:

1. Right-click any .md file in Finder
2. Select Get Info
3. Under Open with, choose Open Markdown
4. Click Change All... to apply to all files of this type

Mermaid Diagrams

Fenced code blocks with the mermaid language tag are automatically rendered as diagrams:

Supported diagram types include flowcharts, sequence diagrams, class diagrams, state diagrams, Gantt charts, pie charts, and more. See the Mermaid documentation for the full list.

Syntax Highlighting

Code blocks with a language tag are syntax-highlighted using highlight.js, which supports 190+ languages. The highlighting theme automatically adapts to light and dark mode.

Export & Copy

• Save as image — Export the entire rendered document as a PNG image
• Copy diagram as image — Right-click any Mermaid diagram to copy it to your clipboard
• Copy as rich text — Copy the rendered document as rich text and paste it directly into Google Docs, Jira, Confluence, and other apps with formatting preserved