# QLMarkdown

macOS Quick Look 扩展，用于预览格式化的 Markdown，支持可配置主题及 Markdown 转 HTML 工具。

> 这是 OpenNavo 上 QLMarkdown 页面的 Markdown 版本，内容与网页相同： <https://opennavo.com/zh/apps/qlmarkdown>

- **最新版本**: `1.5.7`
- **开发者**: sbarex and contributors
- **主页**: <https://github.com/sbarex/QLMarkdown>
- **分类**: [系统工具](https://opennavo.com/zh/categories/utilities)
- **安装**: `brew install --cask qlmarkdown`
- **近 30 天安装**: 2,783
- **Homebrew**: 可以安装，应用会自行更新
- **下载地址**: <https://github.com/sbarex/QLMarkdown/releases/download/1.5.7/QLMarkdown.zip>
- **SHA-256**: `96cc95553ee63557f7ec58f41a568ff1fe5bca95b6bcd3883709fa8337c685d4`
- **附带命令**: qlmarkdown_cli

SHA-256 只用来核对下载的文件是否完整，不代表安全认证。

## 安装与卸载内容

```json
[
  {
    "declaration": {
      "uninstall": [
        {
          "quit": "org.sbarex.QLMarkdown"
        }
      ]
    },
    "phase": "uninstall",
    "sources": [],
    "type": "uninstall"
  },
  {
    "declaration": {
      "app": [
        "QLMarkdown.app"
      ],
      "target": "/Applications/QLMarkdown.app"
    },
    "phase": "install",
    "sources": [
      "QLMarkdown.app"
    ],
    "target": "/Applications/QLMarkdown.app",
    "type": "app"
  },
  {
    "declaration": {
      "binary": [
        "$APPDIR/QLMarkdown.app/Contents/Resources/qlmarkdown_cli"
      ],
      "target": "$HOMEBREW_PREFIX/bin/qlmarkdown_cli"
    },
    "phase": "install",
    "sources": [
      "$APPDIR/QLMarkdown.app/Contents/Resources/qlmarkdown_cli"
    ],
    "target": "$HOMEBREW_PREFIX/bin/qlmarkdown_cli",
    "type": "binary"
  },
  {
    "declaration": {
      "zap": [
        {
          "trash": [
            "~/Library/Application Scripts/group.org.sbarex.qlmarkdown",
            "~/Library/Application Scripts/org.sbarex.QLMarkdown",
            "~/Library/Application Scripts/org.sbarex.QLMarkdown.QLExtension",
            "~/Library/Application Scripts/org.sbarex.QLMarkdown.Shortcut-Extension",
            "~/Library/Application Support/QLMarkdown",
            "~/Library/Containers/org.sbarex.QLMarkdown",
            "~/Library/Containers/org.sbarex.QLMarkdown.QLExtension",
            "~/Library/Containers/org.sbarex.QLMarkdown.Shortcut-Extension",
            "~/Library/Group Containers/group.org.sbarex.qlmarkdown",
            "~/Library/Group Containers/org.sbarex.QLMarkdown",
            "~/Library/Group Containers/org.sbarex.qlmarkdown",
            "~/Library/Preferences/org.sbarex.QLMarkdown.plist",
            "~/Library/Preferences/org.sbarex.QLMarkdownXPCHelper.plist",
            "~/Library/QuickLook/QLMarkdown.qlgenerator"
          ]
        }
      ]
    },
    "phase": "cleanup",
    "sources": [],
    "type": "zap"
  }
]
```

## 介绍

QLMarkdown 是 sbarex 开发的免费开源 macOS 应用，可安装用于格式化 Markdown 预览的 Quick Look 扩展。它适合希望在 Finder 中查看文档而不必打开完整编辑器的开发者、技术写作者和其他用户。此 Homebrew 软件包属于 sbarex 项目，与名称相似的旧项目不同。

### 功能
- 使用基于 cmark-gfm 的渲染，通过 macOS Quick Look 预览 Markdown。
- 配置浅色和深色主题、字体、源代码渲染及预览选项。
- 启用表格、任务列表、脚注、标题锚点及其他扩展。
- 高亮围栏代码，并可选择渲染 MathJax 公式或 Mermaid 图表。
- 预览受支持的 R Markdown、Quarto、MDX、API Blueprint 和 textbundle 文件。
- 使用内附命令行工具或实验性的快捷指令操作将 Markdown 转换为 HTML。

### 安装并启用扩展
使用 `brew install --cask qlmarkdown` 安装，或解压官方 QLMarkdown.zip，并将 QLMarkdown.app 放入 Applications。至少启动一次应用，以便 macOS 发现扩展，并让应用准备共享支持文件。在主应用中，点击打开 Quick Look 设置面板的按钮，并确认扩展已启用。在当前 macOS 版本中，文档所述路径为“系统设置”>“通用”>“登录项与扩展”>“Quick Look”；较旧系统的扩展设置位置有所不同。

在 Finder 中选中受支持的 Markdown 文件，然后按空格键进行预览。在配置应用中，按 Command-S 或选择“文件”>“保存设置”保存设置，也可启用自动保存。内嵌测试编辑器用于检查格式；开发者并未将此应用定位为独立的 Markdown 编辑器或通用文档查看器。R Markdown 预览不会执行 R 代码，MDX 预览也不会渲染 JSX。

如果其他应用也注册了 Markdown Quick Look 支持，其扩展或文件类型注册可能会优先处理。官方故障排除指南建议逐个测试其他 Quick Look 扩展，以找出冲突。cask本身未声明明确冲突的 cask或额外的 cask 依赖。Homebrew还提供内附的 `qlmarkdown_cli` 工具链接；该工具使用自己的设置，不与应用的 Quick Look 配置共享设置。

### 要求、权限与平台限制
当前 Homebrew cask 要求 macOS 12 Monterey 或更高版本，并注明支持 Intel 和 Apple Silicon。这是一款 macOS Quick Look 应用；目前未确认该项目提供官方 Windows 或 Linux 客户端。上游将预编译版本描述为已签名并经过公证。从源代码构建需要开发依赖项，但这些并非安装打包应用的额外要求。

Quick Look 扩展使用只读权限例外来解析本地预览图像；这并不意味着通常需要授予辅助功能或完全磁盘访问权限。本地图片嵌入和原始 HTML 是独立的渲染选项。原始 HTML 可能允许不安全内容，而默认设置会移除 HTML 标签和不安全链接；对于不可信文档，启用此选项前请先检查上游设置。MathJax 和 Mermaid 可使用网络托管的库或嵌入捆绑代码，因此 CDN 模式需要互联网连接。其他远程资源也取决于网络是否可用。

### 账户、费用与许可证
此应用是免费开源软件，附有 GNU GPL 版本 3 许可证文件。本地预览或 HTML 转换无需账户或订阅；捐赠为自愿选项。官方 1.5.7 ZIP 为 26,322,745 字节，这是下载文件大小，不代表安装后占用空间。未确定通用的内存或安装空间最低要求。

截图是官方带标签 README 中的 Mac Quick Look 预览示例，展示了渲染后的 Markdown，并非全新安装的 1.5.7 截图。

来源：[官方带标签的 README 和故障排除指南](https://github.com/sbarex/QLMarkdown/blob/1.5.7/README.md)、[官方 1.5.7 版本](https://github.com/sbarex/QLMarkdown/releases/tag/1.5.7)、[许可证](https://github.com/sbarex/QLMarkdown/blob/1.5.7/LICENSE.txt)、[Homebrew cask](https://github.com/Homebrew/homebrew-cask/blob/main/Casks/q/qlmarkdown.rb)。

## 系统要求

- macOS 12 起 · 应用版本: 1.5.7 · Intel · <https://github.com/homebrew/homebrew-cask/blob/HEAD/Casks/q/qlmarkdown.rb> · 核查于 2026-11-21
  - <https://github.com/sbarex/QLMarkdown/releases/download/1.5.7/QLMarkdown.zip>
  - SHA-256: `96cc95553ee63557f7ec58f41a568ff1fe5bca95b6bcd3883709fa8337c685d4`
- macOS 12 起 · 应用版本: 1.5.7 · Apple 芯片 · <https://github.com/homebrew/homebrew-cask/blob/HEAD/Casks/q/qlmarkdown.rb> · 核查于 2026-11-21
  - <https://github.com/sbarex/QLMarkdown/releases/download/1.5.7/QLMarkdown.zip>
  - SHA-256: `96cc95553ee63557f7ec58f41a568ff1fe5bca95b6bcd3883709fa8337c685d4`

## QLMarkdown 的安全事实

这里只列可以核验的事实，并注明来源和日期，不是安全认证。要检查你下载的文件，可以用 OpenNavo 在本机扫描。

- <https://github.com/sbarex/QLMarkdown> · 是否开源: 是 — <https://github.com/sbarex/QLMarkdown> · 核查于 2026-11-13

## 卸载

- `brew uninstall --cask qlmarkdown`

普通卸载会删除应用本身，设置和缓存会保留。

### 深度清理（可选）

- `brew uninstall --zap --cask qlmarkdown`

`--zap` 还会删除 Homebrew 定义里列出的设置、缓存等文件，其中可能有其他应用共用的数据，删除后无法恢复；它也不保证没有任何残留。请先备份需要保留的数据；如要保留设置和缓存，请不要加 `--zap`。

普通卸载会删除应用本身，设置和缓存会保留。

- 文件和文件夹: `~/Library/Application Scripts/group.org.sbarex.qlmarkdown` — <https://github.com/homebrew/homebrew-cask/blob/HEAD/Casks/q/qlmarkdown.rb> · 以上条目来自 Homebrew 定义，核查于 2026-11-21；它们只说明定义声明会删除什么，不代表你的 Mac 上都有。
- 文件和文件夹: `~/Library/Application Scripts/org.sbarex.QLMarkdown` — <https://github.com/homebrew/homebrew-cask/blob/HEAD/Casks/q/qlmarkdown.rb> · 以上条目来自 Homebrew 定义，核查于 2026-11-21；它们只说明定义声明会删除什么，不代表你的 Mac 上都有。
- 文件和文件夹: `~/Library/Application Scripts/org.sbarex.QLMarkdown.QLExtension` — <https://github.com/homebrew/homebrew-cask/blob/HEAD/Casks/q/qlmarkdown.rb> · 以上条目来自 Homebrew 定义，核查于 2026-11-21；它们只说明定义声明会删除什么，不代表你的 Mac 上都有。
- 文件和文件夹: `~/Library/Application Scripts/org.sbarex.QLMarkdown.Shortcut-Extension` — <https://github.com/homebrew/homebrew-cask/blob/HEAD/Casks/q/qlmarkdown.rb> · 以上条目来自 Homebrew 定义，核查于 2026-11-21；它们只说明定义声明会删除什么，不代表你的 Mac 上都有。
- 文件和文件夹: `~/Library/Application Support/QLMarkdown` — <https://github.com/homebrew/homebrew-cask/blob/HEAD/Casks/q/qlmarkdown.rb> · 以上条目来自 Homebrew 定义，核查于 2026-11-21；它们只说明定义声明会删除什么，不代表你的 Mac 上都有。
- 文件和文件夹: `~/Library/Containers/org.sbarex.QLMarkdown` — <https://github.com/homebrew/homebrew-cask/blob/HEAD/Casks/q/qlmarkdown.rb> · 以上条目来自 Homebrew 定义，核查于 2026-11-21；它们只说明定义声明会删除什么，不代表你的 Mac 上都有。
- 文件和文件夹: `~/Library/Containers/org.sbarex.QLMarkdown.QLExtension` — <https://github.com/homebrew/homebrew-cask/blob/HEAD/Casks/q/qlmarkdown.rb> · 以上条目来自 Homebrew 定义，核查于 2026-11-21；它们只说明定义声明会删除什么，不代表你的 Mac 上都有。
- 文件和文件夹: `~/Library/Containers/org.sbarex.QLMarkdown.Shortcut-Extension` — <https://github.com/homebrew/homebrew-cask/blob/HEAD/Casks/q/qlmarkdown.rb> · 以上条目来自 Homebrew 定义，核查于 2026-11-21；它们只说明定义声明会删除什么，不代表你的 Mac 上都有。
- 文件和文件夹: `~/Library/Group Containers/group.org.sbarex.qlmarkdown` — <https://github.com/homebrew/homebrew-cask/blob/HEAD/Casks/q/qlmarkdown.rb> · 以上条目来自 Homebrew 定义，核查于 2026-11-21；它们只说明定义声明会删除什么，不代表你的 Mac 上都有。
- 文件和文件夹: `~/Library/Group Containers/org.sbarex.QLMarkdown` — <https://github.com/homebrew/homebrew-cask/blob/HEAD/Casks/q/qlmarkdown.rb> · 以上条目来自 Homebrew 定义，核查于 2026-11-21；它们只说明定义声明会删除什么，不代表你的 Mac 上都有。
- 文件和文件夹: `~/Library/Group Containers/org.sbarex.qlmarkdown` — <https://github.com/homebrew/homebrew-cask/blob/HEAD/Casks/q/qlmarkdown.rb> · 以上条目来自 Homebrew 定义，核查于 2026-11-21；它们只说明定义声明会删除什么，不代表你的 Mac 上都有。
- 文件和文件夹: `~/Library/Preferences/org.sbarex.QLMarkdown.plist` — <https://github.com/homebrew/homebrew-cask/blob/HEAD/Casks/q/qlmarkdown.rb> · 以上条目来自 Homebrew 定义，核查于 2026-11-21；它们只说明定义声明会删除什么，不代表你的 Mac 上都有。
- 文件和文件夹: `~/Library/Preferences/org.sbarex.QLMarkdownXPCHelper.plist` — <https://github.com/homebrew/homebrew-cask/blob/HEAD/Casks/q/qlmarkdown.rb> · 以上条目来自 Homebrew 定义，核查于 2026-11-21；它们只说明定义声明会删除什么，不代表你的 Mac 上都有。
- 文件和文件夹: `~/Library/QuickLook/QLMarkdown.qlgenerator` — <https://github.com/homebrew/homebrew-cask/blob/HEAD/Casks/q/qlmarkdown.rb> · 以上条目来自 Homebrew 定义，核查于 2026-11-21；它们只说明定义声明会删除什么，不代表你的 Mac 上都有。

## 最新版本说明

### 1.5.7 (2026-10-07)

修复脚注上标处理以及表格单元格内的行内格式。

**修复**

- 修复启用上标扩展时的脚注。
- 在表格单元格内渲染下标、上标、高亮和数学公式。

## 资料与来源

- <https://opennavo.com/zh/apps/qlmarkdown>
- <https://opennavo.com/zh/apps/qlmarkdown/versions>
- <https://github.com/homebrew/homebrew-cask/blob/HEAD/Casks/q/qlmarkdown.rb> · 核查于 2026-11-21
- <https://formulae.brew.sh/cask/qlmarkdown>
- <https://github.com/sbarex/QLMarkdown> · 核查于 2026-11-13
