MarkdownPreviewOverlay

MarkdownPreviewOverlay is an editor-native Markdown preview and reading mode for Sublime Text. It renders formatted Markdown directly inside your active tab—no external browser, no split-pane, and zero context switching.

This overlay concept was originally designed as the chat preview feature for TermMate, and extracted into a standalone package as discussed in the forum topic: Provide markdown preview mode using folded source and phantom. Join the forum and share your feedback in that thread!

Features & Capabilities

Compared to traditional external browsers or split-pane previewers, MarkdownPreviewOverlay renders your Markdown preview directly inside the same editor view while keeping your plain-text workflow intact:

• Zero Context-Switching: Read and edit in the exact same view—never leave Sublime Text or juggle external browser windows.
• No Split-Pane Clutter: Maximizes your entire editor width without dividing the screen into cramped columns or causing premature line wrapping.
• Position Sync & State Preservation: Automatically aligns the preview with your current editing position, and seamlessly restores your exact cursors, selections, viewport offset, and Vim (Vintage) mode when toggling.
• Lightweight: Powered directly by Sublime Text’s built-in minihtml engine (mdpopups), fully offline with zero background servers, minimal memory overhead, and automatic color scheme alignment.
• Rich Markdown & Responsive Table: Renders syntax-highlighted code blocks, blockquotes, nested lists, and viewport-adaptive tables tailored specifically for minihtml.
• Mermaid Diagrams: Asynchronously renders fenced mermaid blocks into responsive inline diagrams via an auto-detected CLI (@mermaid-js/mermaid-cli or merman-cli), with graceful code fallback.

Note: Rendering is delegated directly to the mdpopups Package Control dependency without bundling a separate Markdown parser.

Installation

The easiest way to install is via Package Control:

1. Open the Command Palette: Command+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux).
2. Select Package Control: Install Package.
3. Search for **MarkdownPreviewOverlay** and press Enter.

Usage

MarkdownPreviewOverlay provides seamless ways to enter, navigate, and exit preview mode without leaving your active editor view.

1. Interactive Phantom Button

The package injects lightweight, non-intrusive interactive controls directly into the buffer for saved files (enabled by default, can be hidden via "show_preview_button": false in settings):

• Preview Mode: Click the **▣ Preview** button at the top of the file (displayed as a right-aligned annotation badge, or a compact inline ▣ icon if the line is long) to fold the source text and enter the preview overlay.
• Edit Mode: Click the ✏️Edit source button in the top toolbar to exit preview mode. Your previous cursor selection, scroll position, original read-only status, and manual code folds are fully restored.

2. Command Palette

Press Command+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux) and search for Markdown Overlay (or type mdo):

Note for Unsaved Buffer: To keep scratch view clean, the inline ▣ Preview button is only displayed for saved files on disk. For unsaved or untitled buffers, enter preview mode using the Command Palette or a keyboard shortcut.

Document Behaviors

• Unsaved Buffer: Phantom buttons are hidden on untitled/scratch views to prevent visual clutter; use the Command Palette or keyboard shortcut to switch preview mode.
• Auto-Refresh: If the document is modified or saved, the preview updates automatically with debounced re-rendering.
• Local Images Only: Only local image files are rendered; remote web images are not downloaded; resolving local relative image paths is enabled by default (disable via "resolve_image_paths": false).
• Keyboard Navigation: In preview mode, native navigation keys (Up/Down, PageUp/PageDown, Home/End) as well as Vim mode (j/k, Ctrl+d/Ctrl+u, gg/G) automatically scroll the preview without any custom keybindings.

Markdown Extensions

Mermaid Diagrams

To render fenced mermaid diagrams, install either of the supported CLI tools:

• @mermaid-js/mermaid-cli (executable: mmdc)
• merman-cli (executable: merman-cli)

The plugin automatically detects whichever tool is installed on your PATH.

Configuration

Access settings and key bindings via the menu: Preferences -> Package Settings -> MarkdownPreviewOverlay.

Settings

Settings can be customized via Preferences -> Package Settings -> MarkdownPreviewOverlay -> Settings (or directly in MarkdownPreviewOverlay.sublime-settings):

Key Bindings

MarkdownPreviewOverlay does not register a shortcut to avoid collisions. Key bindings are provided as a keymap example.

To enable keyboard shortcuts, open Preferences -> Package Settings -> MarkdownPreviewOverlay -> Key Bindings (or copy from Example.sublime-keymap into your User keymap):

[
    {
        "keys": ["primary+alt+r"],
        "command": "markdown_preview_overlay_toggle",
        "context": [{ "key": "setting.is_widget", "operand": false }]
    }
]

primary+alt+r automatically maps to Cmd+Option+R on macOS and Ctrl+Alt+R on Windows/Linux in Sublime Text.

Development installation

Clone or link this directory as Packages/MarkdownPreviewOverlay, then run Package Control: Satisfy Dependencies. Package Control installs mdpopups according to dependencies.json.

Sublime Text build 4050 or newer is required. The package selects Sublime's Python 3.8 plugin host through .python-version.

License

This project is licensed under the Apache-2.0 License.