FluxMarkdown

June 28, 2026 · View on GitHub

Beautiful Markdown previews in macOS Finder QuickLook
Mermaid • KaTeX • GFM • TOC • Charts • Export

English • Español • 中文文档 • Install • Troubleshooting

✨ Demo

FluxMarkdown Demo

Press Space in Finder → Instant preview with diagrams, math, and more.

👋 If FluxMarkdown helps you, consider giving it a ⭐ star on GitHub!

🚀 Quick Install (30 seconds)

Homebrew (Recommended)

brew install --cask xykong/tap/flux-markdown

If Homebrew reports that xykong/tap is not trusted, this is Homebrew's third-party tap trust warning, not a FluxMarkdown install failure. Prefer trusting only this cask:

brew trust --cask xykong/tap/flux-markdown
brew install --cask xykong/tap/flux-markdown

See Tap Trust for Homebrew's security model.

Manual (DMG)

Download the latest FluxMarkdown.dmg from Releases
Open the DMG
Drag FluxMarkdown.app to Applications

💡 Why FluxMarkdown?

Feature	Description
📊 Mermaid Diagrams	Architecture diagrams, flowcharts, sequence diagrams
🧮 KaTeX Math	Inline and block mathematical expressions
📝 GFM Support	Tables, task lists, strikethrough, and GitHub Alerts
🎨 Code Highlighting	Syntax highlighting for 40+ languages
📊 Charts & Graphs	Vega, Vega-Lite, and Graphviz (DOT) support
📑 TOC Panel	Interactive table of contents with section tracking
📄 YAML Metadata	Auto-parses frontmatter into a clean table
📤 Export	PDF (Cmd+Shift+P) / HTML (Cmd+Shift+E) — V2EX 用户求的功能！
🔍 Zoom & Pan	Cmd +/-/0, Cmd+scroll, pinch gestures
💾 Position Memory	Remembers scroll position and last-viewed file
🌓 Themes	Light, Dark, and System-synchronized modes
📂 File Formats	Supports .md, .mdx, .rmd, .qmd, .mdoc, .mdc, .mmd, .livemd, .mkd, .mkdn, .mkdown, .mdwn, .mdown, .markdown

⚙️ Settings (Cmd+,)

FluxMarkdown includes a dedicated Settings window to customize your experience:

Appearance: Switch between Light, Dark, or System themes.
Rendering: Toggle Mermaid, KaTeX, or Emoji support.
Editor: Adjust base font size and choose code highlighting themes (GitHub, Monokai, Atom One Dark, etc.).

⌨️ Keyboard Shortcuts

Shortcut	Action
`Space`	Open QuickLook preview (Finder)
`Cmd` + `+` / `-` / `0`	Zoom in / out / reset
`Cmd` + `Shift` + `E`	Export as HTML
`Cmd` + `Shift` + `P`	Export as PDF
`Cmd` + `,`	Open Settings

🛠️ Troubleshooting

"App is damaged" / "Unidentified developer"

Run this in Terminal:

xattr -cr "/Applications/FluxMarkdown.app"

QuickLook not showing updates

Reset QuickLook cache:

qlmanage -r

Preview not working at all

Check if the app is in /Applications/
Try restarting Finder: killall Finder
Check pluginkit -m -v for active QuickLook extensions

📚 More help: See docs/user/TROUBLESHOOTING.md and docs/user/AUTO_UPDATE.md

📖 Documentation index: docs/README.md

Comparison (QuickLook Markdown plugins)

Feature	FluxMarkdown	QLMarkdown	qlmarkdown	PreviewMarkdown
Install	brew cask / DMG	brew cask / DMG	manual	App Store / DMG
Mermaid	Yes	Yes (ref)	Not mentioned	Not mentioned
KaTeX / Math	Yes	Yes (ref)	Not mentioned	Not mentioned
GFM / Alerts	Yes	Yes (cmark-gfm; ref)	Partial (Discount; ref)	Not mentioned
TOC panel	Yes	Not mentioned	No	Not mentioned
Charts (Vega/DOT)	Yes	Not mentioned	No	No
Export (PDF/HTML)	Yes	No	No	No
YAML Frontmatter	Yes	Yes	No	No
Themes	Light/Dark/System	CSS-based (ref)	Not mentioned	Basic controls (ref)
Zoom	Yes	Not mentioned	No	Not mentioned
Scroll restore	Yes	Not mentioned	No	Not mentioned

Notes:

Entries are based on public README/release notes at the cited links.

If a feature isn't mentioned in sources, we mark it as "Not mentioned".

Build from source

git clone https://github.com/xykong/flux-markdown.git
cd flux-markdown
make install

📄 License

FluxMarkdown is dual-licensed:

Open Source License: GPL-3.0

✅ Free for personal, educational, and open-source use
✅ Any modifications must also be open-sourced under GPL-3.0
📜 See LICENSE for full terms

Commercial License

💼 Required for closed-source or proprietary products
💼 Allows distribution without open-sourcing your modifications
📧 Contact: xy.kong@gmail.com for licensing inquiries
📜 See LICENSE.COMMERCIAL for details

Why dual licensing? This ensures FluxMarkdown remains free and open for the community while allowing commercial use without GPL obligations for those who need it.

_{Inspired by and partially based on markdown-preview-enhanced}