FluxMarkdown

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

中文文档 • Install • Troubleshooting

---

✨ 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

Manual (DMG)

1. Download the latest FluxMarkdown.dmg from Releases
2. Open the DMG
3. 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, .mkd, .mkdn, .mkdown

---

⚙️ 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

1. Check if the app is in /Applications/
2. Try restarting Finder: killall Finder
3. 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}