MarkdownFlow

A beautiful, offline macOS Markdown reader with full diagram rendering — plus an Xcode Source Editor Extension that previews the .md file you're editing.

Features

• Welcome window — launching the app shows an Xcode-style welcome page: create a new document, open a file, or pick from recent files (⇧⌘1 brings it back any time)
• Standalone reader — open any .md file via Finder ("Open With"), drag onto the Dock, or ⌘O. Document windows with:
  • Outline sidebar (table of contents) — click to jump, highlights follow your scroll position
  • GitHub-style typography, light / dark / auto theme
  • Zoom (⌘+ / ⌘- / ⌘0), click any Mermaid diagram to zoom & pan it
• Editing — toggle the editor pane (toolbar pencil) for side-by-side source editing with live preview; ⌘S saves, ⌘N starts a new document
• Diagrams — Mermaid 10: flowchart, sequence, gantt, class, state, ER, pie, mindmap, timeline, git graph. Parse errors show inline without breaking the rest of the document.
• Code highlighting — highlight.js with GitHub light/dark themes
• GFM — tables, task lists, strikethrough (marked.js)
• Fully offline — all JS libraries bundled, nothing fetched at runtime
• Xcode follow mode — a floating panel automatically previews the .md file currently open in Xcode (toggle via the Xcode menu in the app, or the Editor → Toggle Markdown Preview source editor command)

Requirements

• macOS 15+
• Xcode 15+ (to build; only needed at runtime for the Xcode follow mode)

Build

brew install xcodegen   # if needed
xcodegen generate
xcodebuild -scheme MarkdownFlow -configuration Release build

Or open MarkdownFlow.xcodeproj and run the MarkdownFlow scheme.

Enable the Xcode extension

1. Run MarkdownFlow once (so macOS registers the extension)
2. System Settings → General → Login Items & Extensions, scroll down to the Extensions section, click ⓘ next to Xcode Source Editor, and enable MarkdownFlow (on macOS 13/14 this was under Privacy & Security → Extensions)
3. Restart Xcode; the command appears under Editor → MarkdownFlowExtension → Toggle Markdown Preview

If the extension doesn't show up, check it is registered with pluginkit -m | grep -i markdown — it should list com.fanyu.MarkdownFlow.Extension.

The first time follow mode activates, macOS asks for permission to automate Xcode (Apple Events) — required to detect which file is open.

Architecture

Two targets generated by XcodeGen from project.yml:

• MarkdownFlow — SwiftUI document app (DocumentGroup) with an AppKit welcome window, WKWebView rendering via a bundled preview.html (marked + mermaid + highlight.js), debounced live re-render while editing, AppleScript-based Xcode polling, floating NSPanel with FSEvents reload
• MarkdownFlowExtension — sandboxed source editor extension that posts a distributed notification to toggle the panel

See docs/2026-06-11-standalone-reader-design.md.