Project Awesome project awesome
♥

FluxMarkdown

Quick Look extension for Markdown previews with Mermaid, KaTeX, GFM, TOC, and charts.

Package 725 stars GitHub

FluxMarkdown

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

GitHub stars Latest release Downloads License

中文文档 • 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

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, .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
  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

Back to Apps