showmd

showmd：重定义 macOS 上的 Markdown 预览体验

在 macOS 系统中，按下空格键使用 Quick Look 预览文件是一项非常高效的功能。然而，对于开发者、作家和 AI 工程师而言，原生预览功能在处理 Markdown 文件（.md）时表现得并不理想：它往往只显示充满井号、星号和代码块的纯文本，极其难以阅读。showmd 的出现正是为了解决这一痛点，它认为 Markdown 绝不应该仅以纯文本形式被预览。

什么是 showmd？

showmd 是一款专为 macOS 打造的开源、免费的 Markdown 预览扩展工具。它旨在提供一种最易读的方式来预览 macOS 上的任何 .md 文件。作为一款轻量级的查看器，showmd 并非编辑器或笔记软件，它的核心使命是为您提供极致的渲染效果，让原本杂乱的原始代码瞬间变成排版精美的文档。

"Markdown was never meant to be previewed plain text."

showmd 的核心特性 (Features)

showmd 不仅仅是一个简单的渲染器，它针对现代 Markdown 的使用场景（尤其是 AI 驱动的文档）进行了深度优化：

1. 强大的 GitHub 风格支持 (GFM)

showmd 完整支持 GitHub Flavored Markdown (GFM)，包括表格、任务列表、删除线、自动链接和脚注等。依托 Apple 的 swift-markdown 解析器，渲染效果精准可靠。

2. 独特的 AI Agent 标签渲染

这是 showmd 区别于其他工具的一大亮点。针对现代 AI 写入的 Markdown 文件（如 AGENTS.md 或 .cursorrules），它可以将自定义的 XML 标签（如 <instructions>、<example>、<thinking> 等）渲染为带有标签和边框的样式块，而非凌乱的角括号。

3. 智能 YAML 前置数据 (Frontmatter) 处理

它能自动解析 Markdown 文件顶部的 YAML 元数据块，并将其转化为一个可折叠的元数据表格。默认情况下它是折叠的，以保持界面整洁，点击即可展开查看详细的 title、tags 等信息。

4. 专业级数学公式与图表

• LaTeX 数学公式：通过 KaTeX 完美渲染行内 $x^2$ 和块级 $$...$$ 表达式。
• Mermaid 流程图：支持直接在预览中查看流程图、时序图和状态机，无需打开浏览器。

5. 极致的系统集成与性能

• 原生体验：遵循 macOS 系统字体，支持自动切换暗黑模式。
• 无感开启：作为 Quick Look 扩展运行，按下空格键即可瞬时开启，耗时不到一秒。
• 源码切换：内置“Rendered（渲染）”与“Source（源码）”切换开关，支持随时复制为 HTML。
• 隐私安全：完全离线运行，无云端上传，无遥测数据，确保您的文件隐私。

6. 多种文件扩展名支持

除了标准的 .md，它还支持 .markdown、.mdx、.mdc、.rmd、.qmd、.mdown、.mkd、.mkdn、.mdtext 及 .mdtxt 等几乎所有 Markdown 变体。

使用场景 (Use Case)

• 开发者文档查阅：快速浏览 README.md 或 CHANGELOG.md 中的代码示例与更新日志。
• AI 提示词管理：清晰地阅读包含大量结构化 XML 标签的 AI Agent 指令文件。
• 学术与数据科学：在 Finder 中直接预览包含 LaTeX 公式和复杂图表的调研报告。
• 本地图片预览：showmd 可以正确解析相对路径，让文档中的本地截图和示意图正常显示。

如何安装与使用 (How to Use)

安装 showmd 非常简单，只需三个步骤：

1. 下载与开启：
   • 您可以通过 GitHub 下载最新的 .dmg 安装包（v1.0.1 已签名并经过公证）。
   • 或者使用 Homebrew 一键安装： brew install --cask johannesnagl/tap/showmd
2. 在系统设置中启用：
   • 打开“系统设置” -> “隐私与安全性” -> “扩展” -> “快速查看 (Quick Look)”。
   • 勾选 showmd。初次启动时，macOS 可能会询问是否允许访问其他应用的数据，请点击“允许”以同步设置。
3. 开始预览：
   • 在 Finder 中选中任何 Markdown 文件，按下空格键。此时，您将看到排版完美的渲染效果，包括前置数据表格和源码切换按钮。

常见问题 (FAQ)

Q: showmd 是收费软件吗？ A: 不是。showmd 是完全免费且开源的（基于 MIT 协议）。如果您觉得好用，可以通过“请开发者吃份意面 (Buy me a pasta)”的方式表示支持。

Q: 它支持暗黑模式吗？ A: 支持。它会自动遵循系统的外观设置，您也可以在 app 的设置界面手动指定浅色或深色模式。

Q: 我可以在预览中查看代码高亮吗？ A: 可以。showmd 开箱即用支持超过 190 种编程语言的语法高亮。

Q: 与同类工具相比，showmd 有什么优势？ A: 相比于收费的工具或配置复杂的开源项目，showmd 更加简单易用且功能全面。它特有的 YAML 前置数据折叠渲染和 AI 标签支持，使其成为目前最符合现代工作流的 Markdown 预览工具。

Q: 它是编辑器吗？ A: 不，它仅是一个查看器。它的任务是渲染您的 Markdown 并迅速退出，不提供编辑功能。