xykong/flux-markdown

Markdown Preview Enhanced for macOS QuickLook

Swift

1,251

476 commits

updated Aug 14, 2026

See the code

README

FluxMarkdown

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}

Contributors

469 commits

5 commits

1 commits

1 commits

Similar repos

pluk-inc/markdown-preview

A simple Markdown viewer for reading .md files

2,379

sbarex/QLMarkdown

macOS Quick Look extension for Markdown files.

3,597

schuyler/macdown3000

A modern, lightweight Markdown editor for macOS.

476

sindresorhus/quick-look-plugins

List of useful Quick Look plugins for developers

18,767

temir-dev/tims-markdown-reader

QL-Win/QuickLook

Bring macOS “Quick Look” feature to Windows

24,954

RivoLink/leaf

Terminal Markdown previewer — GUI-like experience.

2,055

marktext/marktext

📝A simple and elegant markdown editor, available for Linux, macOS and Windows.

61,856

Languages

Swift

51.7%

TypeScript

30.3%

Shell

9.2%

CSS

5.7%

JavaScript

2.0%

xykong/flux-markdown

Markdown Preview Enhanced for macOS QuickLook

Swift

1,251

476 commits

updated Aug 14, 2026

See the code

README

FluxMarkdown

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}

Similar repos

pluk-inc/markdown-preview

A simple Markdown viewer for reading .md files

2,379

sbarex/QLMarkdown

macOS Quick Look extension for Markdown files.

3,597

schuyler/macdown3000

A modern, lightweight Markdown editor for macOS.

476

sindresorhus/quick-look-plugins

List of useful Quick Look plugins for developers

18,767

temir-dev/tims-markdown-reader

QL-Win/QuickLook

Bring macOS “Quick Look” feature to Windows

24,954

RivoLink/leaf

Terminal Markdown previewer — GUI-like experience.

2,055

marktext/marktext

📝A simple and elegant markdown editor, available for Linux, macOS and Windows.

61,856

Contributors

469 commits

5 commits

1 commits

1 commits

Languages

Swift

51.7%

TypeScript

30.3%

Shell

9.2%

CSS

5.7%

JavaScript

2.0%