我做了一个 macOS QuickLook Markdown 预览工具，支持 Mermaid / Vega / KaTeX / 导出 PDF

起因

自从 AI 工具普及之后，我发现自己硬盘里的 .md 文件越来越多

Claude / ChatGPT 输出的技术分析、Cursor 帮我生成的架构设计文档、AI 写的项目 README 、还有各种 AGENTS.md、开发规范……几乎全是 Markdown 格式。

这些文档里经常有 Mermaid 架构图、数学公式、代码片段。但 macOS 自带的空格预览只能看到一堆 # 和 ---，完全没法读。

于是我做了 FluxMarkdown：一个 macOS QuickLook 扩展，选中 .md 文件按空格，立即看到完整渲染结果。

支持的功能

图表渲染

• Mermaid：架构图、流程图、时序图、类图、甘特图、Git 分支图
• Vega / Vega-Lite：交互式数据可视化图表
• Graphviz / DOT：关系图、依赖图

文档格式

• KaTeX 数学公式：行内 $...$ 和块级 $$...$$
• GitHub Flavored Markdown：表格、任务列表、删除线、GitHub Alerts （> [!NOTE]）
• YAML Frontmatter：自动解析文档头部元数据，以表格形式展示
• **脚注 / 上标 / 下标 / ==高亮==**：学术和技术文档常用语法
• 代码高亮：40+ 编程语言

体验细节

• 交互式 TOC：自动生成目录面板，点击跳转，当前章节高亮
• 导出：Cmd+Shift+P 导出 PDF ，Cmd+Shift+E 导出 HTML
• 源码切换：点击右上角 </> 按钮，在渲染视图和原始源码之间切换
• 主题：亮色 / 暗色 / 跟随系统，自动切换
• Settings 界面：Cmd+, 打开，可调字体、主题、渲染开关
• 滚动位置记忆：每个文件独立记忆，关了再开回到原位
• 文件格式：.md .mdx .rmd .qmd .mdoc .mkd 等均支持

性能

最近做了一轮大重构（ v1.15 ），有实测数据：

• 渲染包体积：index.html 从 5.5 MB → 1.84 KB（-99.97%），改用多文件加载
• KaTeX 懒加载：index.js 从 554 KB → 317 KB（-43%），仅含公式时才加载
• Mermaid 热渲染：从 ~380ms → ~20ms（预热缓存后，同会话二次打开）
• Mermaid 单次渲染：从 ~186ms → ~46ms（-75%，单例化后）

一键安装

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

或从 GitHub Releases 下载 DMG 手动安装。

开源协议

• 个人 / 教育 / 开源项目：GPL-3.0 ，完全免费
• 商业闭源产品：需购买商业许可证（联系 [email protected] ）

项目地址： https://github.com/xykong/flux-markdown

常见问题

Q: "应用已损坏" / "无法验证开发者"？ A: 运行 xattr -cr "/Applications/FluxMarkdown.app"

Q: QuickLook 不刷新 / 没反应？ A: 运行 qlmanage -r，如仍无效，重启 Finder：killall Finder

Q: 和 QLMarkdown 有什么区别？ A: 功能侧重不同。FluxMarkdown 额外支持 Vega/Graphviz 图表、PDF/HTML 导出、Settings 界面、YAML Frontmatter 渲染、源码切换、更丰富的扩展语法。

求反馈

用 AI 工具的同学应该会有感触：现在打开项目文件夹，.md 文件越来越多了。欢迎试用，有什么不顺手的地方直接提 Issue 或在这里说。

如果觉得有用，欢迎给个 Star： https://github.com/xykong/flux-markdown