Beautiful Markdown previews in macOS Finder QuickLook
Mermaid • KaTeX • GFM • TOC • Charts • Export
English • Español • 中文文档 • Install • Troubleshooting
Markdown rendering uses bundled local assets. The app also checks for updates and, by default, sends pseudonymous usage statistics. You can turn off Share Usage Statistics in Settings (for both the app and Quick Look). Statistics do not include document names, paths or contents. See the privacy notice for the collected fields, IP-based location processing, retention and opt-out behavior.
Press Space in Finder → Instant preview with diagrams, math, and more.
👋 If FluxMarkdown helps you, consider giving it a ⭐ star on GitHub!
brew install --cask xykong/tap/flux-markdownIf 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-markdownSee Tap Trust for Homebrew's security model.
- Download the latest
FluxMarkdown.dmgfrom Releases - Open the DMG
- Drag FluxMarkdown.app to Applications
| 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, and read-only .tsv table previews |
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.).
| 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 |
"App is damaged" / "Unidentified developer"
Run this in Terminal:
xattr -cr "/Applications/FluxMarkdown.app"QuickLook not showing updates
Reset QuickLook cache:
qlmanage -rPreview not working at all
- Check if the app is in
/Applications/ - Try restarting Finder:
killall Finder - Check
pluginkit -m -vfor active QuickLook extensions
📚 More help: See docs/user/TROUBLESHOOTING.md and docs/user/AUTO_UPDATE.md
📖 Documentation index: docs/README.md
| 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".
git clone https://github.com/xykong/flux-markdown.git
cd flux-markdown
make installFluxMarkdown is dual-licensed:
- ✅ Free for personal, educational, and open-source use
- ✅ Any modifications must also be open-sourced under GPL-3.0
- 📜 See
LICENSEfor full terms
- 💼 Required for closed-source or proprietary products
- 💼 Allows distribution without open-sourcing your modifications
- 📧 Contact: xy.kong@gmail.com for licensing inquiries
- 📜 See
LICENSE.COMMERCIALfor 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
Error notices offer a recovery action and Report This Problem. Reporting opens GitHub with the selected error and available system information already filled in; you review and publish the issue there. A GitHub account is required. Use Review Feedback… to add optional details or turn off diagnostics before continuing.
Reports exclude document text, file paths and raw system logs by default. If the browser cannot open, the report remains available to copy or save. Help → Review Last Error… reopens the latest failure, and Help → Clear Error History clears locally retained error records without changing your settings. Errors controlled by macOS itself, or failures where the extension never starts, may require the existing Help → Report an Issue entry.
Open .tsv in FluxMarkdown or preview it with Finder Quick Look. UTF-8 (including BOM) and LF/CRLF/CR records are supported. Tabs separate columns; quotes, HTML, Markdown and formulas remain literal text. The first record is data, with generated column numbers above it.
Previews show up to 500 KiB, 1,000 rows, 100 columns and 20,000 cells. Truncation is marked in the table, source view and exports. Empty fields and uneven rows are preserved. This is a read-only viewer, not a spreadsheet editor; quoted multiline fields and non-UTF-8 encodings are not supported. On initial host-app opening, macOS supplies a full FileDocument buffer before the app decodes its bounded prefix; very large initial opens can still use significant memory.