Support

Double-click any .md or .markdown file in Finder, or drag it onto the Markdown Lens icon in your Dock. You can also use File → Open from within the app, or right-click a file and choose "Open With" → Markdown Lens.

Markdown Lens needs permission to access folders containing your images. When you open a document with local images, you'll be prompted to grant folder access. Click "Grant Access" to allow the app to display your images.

Note: Images using http:// URLs (not https://) won't display due to macOS security requirements. Use https:// URLs for remote images, or reference local images with relative paths.

Math rendering (KaTeX) and diagrams (Mermaid) are enabled by default. If you need to toggle them:

Open Preferences (⌘,) → Extensions tab → Toggle the features you want.

Use File → Export As → PDF... or press ⇧⌘E.

You can customize paper size, margins, and code wrapping in Preferences → PDF.

Use File → Export As → HTML...

The exported HTML is self-contained with all images embedded, making it easy to share.

Markdown Lens is completely free with all features included. The optional $1.99 "Support Development" purchase removes periodic reminder messages and helps fund continued development.

This is entirely optional—all features work identically whether you purchase or not.

No. Markdown Lens processes everything locally on your Mac. There are no analytics, no tracking, and no cloud sync. Your files never leave your device.

The only network access is for loading remote images (https:// URLs in your documents) and App Store purchases.

Make sure you're running the latest version from the Mac App Store — several stability and crash fixes have shipped in recent updates, especially for macOS 12 Monterey.

If you're still experiencing issues, try these troubleshooting steps:

• Make sure the file is a valid .md or .markdown file
• Check if the file is extremely large (>10MB may be slow to render)
• Restart the app
• Check if the file contains unusual characters or encoding issues

If issues persist, use Help → Get Support... to send us your system information and a description of the problem.

Markdown Lens is a preview-only application—it doesn't include editing features. This is intentional: we believe in doing one thing well.

Use your favorite text editor (VS Code, Vim, BBEdit, TextEdit, etc.) to edit, and Markdown Lens will automatically refresh when you save.

Markdown Lens requires macOS 12 (Monterey) or later. It runs natively on both Intel and Apple Silicon Macs.

For the best experience with all features, macOS 14 Sonoma or later is recommended. Some export and rendering features have minor limitations on older macOS versions due to WebKit differences.

Note: Version 2.20 is the final release supporting macOS 12 Monterey. Future updates will require macOS 13 Ventura or later. macOS 11 Big Sur has not been supported since version 2.10.

Use File → Export As → Word Document... or press ⌥⌘E.

The exported .docx file includes tables, images, code blocks, math equations, Mermaid diagrams, footnotes, GFM alerts, and all formatting. No external tools or dependencies required.

Document Health is a sidebar (toggle with ⇧⌘D) that analyzes your markdown and gives you an at-a-glance quality score from 0 to 100. It includes:

• Spell check — Powered by Harper with a built-in technical jargon dictionary of 670+ programming terms
• Structural linting — Catches common markdown issues like inconsistent headings and missing blank lines, with one-click auto-fix for many rules
• Platform compatibility — Detects features that may not render on GitHub, BitBucket, or other target platforms

Click any issue to navigate directly to it in your document. You can configure all options in Preferences → Document Health.

When opening a document, Markdown Lens performs security checks to prepare for local images and file links that may be embedded in your content. This typically takes 2–4 seconds and is more noticeable on older Macs.

The delay occurs once per document. Subsequent operations like scrolling, zooming, and exporting are fast.

When the search bar is open (⌘F), the Edit menu's Copy command doesn't work for search-highlighted text. This is a focus management limitation—the search field has keyboard focus, so the Edit menu doesn't see the WebView's selection.

Workaround: Right-click on the highlighted match and use "Copy" from the context menu. This works reliably.

On slower Macs, accessing files immediately after granting folder permission may fail with a "permission denied" error. This is a macOS timing issue—the system needs a moment to propagate the new permission.

Fix: Wait a few seconds and try again. If the issue persists, quit and relaunch Markdown Lens. The permission only needs to be granted once per folder—subsequent access will work normally.

In Microsoft Word for Mac, some images may appear invisible until you click on them. This is a known Word for Mac rendering bug—the images are present in the document and will display correctly when printed, exported to PDF, or opened in Word on Windows or LibreOffice.

Clicking the invisible area where the image should be will make it appear.

On macOS 12 Monterey, some SVG images may not appear in Word exports due to a WebKit rendering limitation. On macOS 13 Ventura, SVG images export but text labels may be slightly mispositioned.

These issues are resolved on macOS 14 Sonoma and later. PNG and JPEG images are unaffected on all macOS versions.

If a math formula containing the | (pipe) character is inside a table cell, the pipe is interpreted as a column separator, breaking the table layout.

Fix: Use \mid instead of | in math formulas inside table cells. For example, use $P(A \mid B)$ instead of $P(A|B)$. This works correctly on all platforms and is the standard LaTeX notation for conditional probability.

On macOS 12 Monterey, macOS 13 Ventura, and macOS 14 Sonoma, the very first click on the Document Health icon in the status bar of a newly opened document window may not register. Subsequent clicks work normally, as does the menu shortcut.

Workarounds:

• Use View → Document Health (or ⇧⌘D) to toggle the sidebar — this always works on the first try
• Click the status bar icon a second time

This is a SwiftUI focus-handling issue that Apple resolved in macOS 15 Sequoia.

On macOS 12 Monterey through macOS 14 Sonoma, when the Document Health sidebar is hidden, the main content scrollbar may not respond to mouse clicks (thumb drag, page up/down). Trackpad scrolling works normally.

Workarounds:

• Use trackpad gestures to scroll (these work normally)
• Show the Document Health sidebar (⇧⌘D) to restore scrollbar functionality

This is an AppKit limitation that Apple resolved in macOS 15 Sequoia.