【免费下载链接】clearlyMarkdown editor for Mac, iOS and iPadOS项目地址https://gitcode.com/gh_mirrors/cle/clearly点击查看免费下载Clearly 是一款面向 Mac、iOS 与 iPadOS 的原生 Markdown 编辑器。它的亮点之一是随主应用附带的QuickLook 扩展在 Finder 中选中任意.md文件按下空格就能看到代码高亮、数学公式、Mermaid 图表一应俱全的精美预览而不是干巴巴的原始文本。这篇文章拆解 Clearly 的 QuickLook 扩展是怎么做出来的并附上项目团队踩过的3 个 LaunchServices 陷阱——它们会让你的 Markdown 预览静默退化回纯文本且不报任何错。 QuickLook 能带来什么空格一键预览QuickLook 是 macOS/iOS 系统级的文件预览机制。装好 Clearly 后你获得两个体验升级Finder 空格预览选中.md文件按空格全屏浮层直接展示渲染后的 Markdown分栏视图预览Finder 列式视图中浏览笔记目录时右侧预览栏同步显示排版内容且自动切换更小的字体以适配窄栏。预览效果与 Clearly 应用内的预览面板完全同源——同一套渲染管线多端一致️ 架构一览一个 app-extension 目标 共享渲染核心在 project.ymlxcodegen 配置中QuickLook 扩展是一个独立的app-extension构建目标ClearlyQuickLook其配置见 project.yml扩展 Bundle IDcom.sabotage.clearly.quicklook随主应用以embed: true方式打包进 app资源上复用主应用的Shared/Resources/KaTeX、Mermaid、highlight.js 及字体保证离线可用核心渲染逻辑不复制、不重写而是依赖本地 Swift 包ClearlyCore。这正是 Clearly 多端架构的关键决策MarkdownRenderer和PreviewCSS放在ClearlyCore中同时编译进 Mac 主应用、iOS 应用和 QuickLook 扩展三个目标。应用内预览改一个样式Finder 预览自动同步完整的渲染上下文应用内预览 / QuickLook / PDF 导出说明见 docs/markdown-rendering-architecture.md。 核心实现不到 50 行的 PreviewProviderQuickLook 预览扩展的入口是 ClearlyQuickLook/PreviewProvider.swift整个文件只有 40 多行。核心逻辑是标准四步实现QLPreviewingController协议系统把待预览文件 URL 交给preparePreviewOfFile(at:completionHandler:)以 UTF-8 读取 Markdown 文本调用 MarkdownRenderer.renderHTML底层是 cmark-gfm支持表格、删除线、任务列表等 GFM 语法转成 HTML拼上 PreviewCSS.swift 生成的样式表以及数学公式KaTeX、表格、Mermaid、代码高亮的注入脚本交给一个WKWebView加载webView.loadHTMLString(html, baseURL: MermaidSupport.resourceBaseURL) handler(nil)注意这里的轻量级QuickLook 扩展本身几乎不写业务代码全部复用主应用已有的渲染栈。扩展真正的差异化配置集中在 ClearlyQuickLook/Info.plistNSExtensionPointIdentifier声明为com.apple.quicklook.previewQLSupportedContentTypes列出支持的 UTI内容类型标识开启QLSupportsSearchableItems让 Finder 快速预览中支持文字查找。沙盒权限则非常克制见 ClearlyQuickLook/ClearlyQuickLook.entitlements——只开了app-sandbox和network.clientQuickLook 进程以 XPC 形式运行不能碰主应用之外的东西。⚠️ 3 个 LaunchServices 陷阱为什么你的预览只是原始文本这是全文最值钱的部分。.md的 QuickLook 预览、Finder 分栏预览、.md 的默认打开方式三者共享同一套 LaunchServices 路由任何一环配置错误系统都静默回退到原生纯文本预览器Text.qlgenerator日志里几乎找不到报错。以下是 Clearly 团队记录在 CLAUDE.md 中的三个必须同时满足的不变量陷阱 1必须用UTExportedTypeDeclarations而不是UTImportedTypeDeclarationsClearly 在 Clearly/Info.plist 中用导出Exported声明来认领net.daringfireball.markdown这个内容类型并声明md、markdown等扩展名属于它。如果你用UTImportedTypeDeclarations很多教程示例都这么写当系统上没有其他应用权威导出该类型时LaunchServices 会把这个导入声明标记为inactive imported untrusted结果quicklookd直接放弃你的扩展回退到纯文本预览。导出声明则意味着这个类型由我说了算。陷阱 2LSHandlerRank必须是Owner同一份 Clearly/Info.plist 的CFBundleDocumentTypes里.md文档类型的LSHandlerRank写的是Owner。原因如果用默认的Default其他以Owner级别认领 Markdown 的应用某些代码编辑器、写作工具就会在默认打开程序的竞争中获胜——哪怕它们的内容类型声明更弱。这会导致 Finder 双击.md打开的不是你的编辑器。陷阱 3QLSupportedContentTypes必须同时包含两个 Markdown UTI这是最隐蔽的一个。macOS Spotlight 在文件首次被索引时会粘性地给它定型当时系统上哪个 Markdown UTI 是权威的文件就被标成那个类型。结果就是曾经装过 iA Writer或任何导出net.ia.markdown的应用的用户磁盘上约一半的.md文件会被定型为net.ia.markdown——即使那个应用早已卸载。而 QuickLook 系统只调用QLSupportedContentTypes里列出的 UTI 对应的扩展。所以 ClearlyQuickLook/Info.plist 里老老实实写了两行keyQLSupportedContentTypes/key array stringnet.daringfireball.markdown/string stringnet.ia.markdown/string /array少写任何一个另一批用户的文件就会永久停留在原始文本预览。️ 附赠验证环节的隐藏深坑修好配置只是开始怎么验证本身还有坑同样记录在 CLAUDE.mdqlmanage命令行不可信在 macOS 26 上它对.appex预览扩展会直接崩溃qlmanage -m plugins也只列出旧式.qlgenerator插件空结果属于正常现象。唯一的可靠测试方式是Finder 里按空格未公证的扩展不被quicklookd调用新系统要求父应用完成公证notarization staple 后扩展才会生效。所以本地验证发布产物时要走完整的公证 →staple→qlmanage -r刷缓存流程旧注册会污染本机 LaunchServices大量 DerivedData / 并行工作目录里的开发版应用会留下成百上千条陈旧注册且新版 macOS 已移除lsregister -kill只能按路径逐条lsregister -u清理。 iOS 侧预览扩展 自定义缩略图Mac 之外Clearly 在 iOS/iPadOS 上还做了两件事配置思路完全一致1. QuickLook 预览扩展Clearly/iOS/PreviewExtension/PreviewViewController.swift逻辑与 Mac 版几乎相同但多了一步——注册了LocalImageSchemeHandler处理本地图片并把baseURL设为文件所在目录让相对路径图片能在预览中正常显示。2. 自定义缩略图扩展Clearly/iOS/ThumbnailExtension/ThumbnailProvider.swift在文件App 列表视图里给.md文件画出标题 前几行正文的定制缩略图。它的做法很聪明——只读文件前 4096 字节readSample提取第一个#标题和最多 12 行正文来绘制缩略图生成快且不拖慢文件系统列表宽度小于 64pt 时干脆画空白让系统自己贴文档角标。 细节深色模式一行都不用改因为样式全部来自共享的PreviewCSS它内部用media (prefers-color-scheme: dark)自动适配深色模式。QuickLook 预览跟着系统外观切换主应用零成本获得同样的体验 总结你的 QuickLook 扩展检查清单从 Clearly 的实现中可以提炼出这份可复用的检查清单#检查项Clearly 对应文件1扩展目标独立、随主应用内嵌Bundle ID 用独立后缀project.yml2渲染逻辑放共享包扩展只做胶水MarkdownRenderer.swift3用UTExportedTypeDeclarations声明内容类型Clearly/Info.plist4LSHandlerRank设为OwnerClearly/Info.plist5QLSupportedContentTypes覆盖所有历史UTIClearlyQuickLook/Info.plist6验证用 Finder 空格别信qlmanageCLAUDE.mdQuickLook 扩展的代码量小得惊人——难点全在配置与系统路由。照着这份清单走你的 Markdown 文件在 Finder 里按下空格的那一刻就该是一篇排版精美的文章。赞分享【免费下载链接】clearlyMarkdown editor for Mac, iOS and iPadOS项目地址https://gitcode.com/gh_mirrors/cle/clearly点击查看免费下载相关推荐Go-Chassis 服务发现与注册集成 ServiceComb 与 Kubernetes 完整指南Go Chassis 服务发现与注册集成 ServiceComb 与 Kubernetes 完整指南 Go Chassis 是一款云原生应用框架专为 GoQuickLook5个超实用技巧让你3分钟精通Windows文件预览神器QuickLook5个超实用技巧让你3分钟精通Windows文件预览神器 你是否曾在整理项目文件时为了查看一个图片内容而不得不启动Photoshop或者在桌面应用插件系统如何免费使用 Markdown Viewer浏览器扩展完全指南让 Markdown 预览更高效 如何免费使用 Markdown Viewer浏览器扩展完全指南让 Markdown 预览更高效 Markdown Viewer 是一款强大的浏览器扩展前端文档创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 QuickLook扩展开发实战：Clearly如何让Finder精美预览Markdown（附3个LaunchServices陷阱）
【免费下载链接】clearlyMarkdown editor for Mac, iOS and iPadOS项目地址https://gitcode.com/gh_mirrors/cle/clearly点击查看免费下载Clearly 是一款面向 Mac、iOS 与 iPadOS 的原生 Markdown 编辑器。它的亮点之一是随主应用附带的QuickLook 扩展在 Finder 中选中任意.md文件按下空格就能看到代码高亮、数学公式、Mermaid 图表一应俱全的精美预览而不是干巴巴的原始文本。这篇文章拆解 Clearly 的 QuickLook 扩展是怎么做出来的并附上项目团队踩过的3 个 LaunchServices 陷阱——它们会让你的 Markdown 预览静默退化回纯文本且不报任何错。 QuickLook 能带来什么空格一键预览QuickLook 是 macOS/iOS 系统级的文件预览机制。装好 Clearly 后你获得两个体验升级Finder 空格预览选中.md文件按空格全屏浮层直接展示渲染后的 Markdown分栏视图预览Finder 列式视图中浏览笔记目录时右侧预览栏同步显示排版内容且自动切换更小的字体以适配窄栏。预览效果与 Clearly 应用内的预览面板完全同源——同一套渲染管线多端一致️ 架构一览一个 app-extension 目标 共享渲染核心在 project.ymlxcodegen 配置中QuickLook 扩展是一个独立的app-extension构建目标ClearlyQuickLook其配置见 project.yml扩展 Bundle IDcom.sabotage.clearly.quicklook随主应用以embed: true方式打包进 app资源上复用主应用的Shared/Resources/KaTeX、Mermaid、highlight.js 及字体保证离线可用核心渲染逻辑不复制、不重写而是依赖本地 Swift 包ClearlyCore。这正是 Clearly 多端架构的关键决策MarkdownRenderer和PreviewCSS放在ClearlyCore中同时编译进 Mac 主应用、iOS 应用和 QuickLook 扩展三个目标。应用内预览改一个样式Finder 预览自动同步完整的渲染上下文应用内预览 / QuickLook / PDF 导出说明见 docs/markdown-rendering-architecture.md。 核心实现不到 50 行的 PreviewProviderQuickLook 预览扩展的入口是 ClearlyQuickLook/PreviewProvider.swift整个文件只有 40 多行。核心逻辑是标准四步实现QLPreviewingController协议系统把待预览文件 URL 交给preparePreviewOfFile(at:completionHandler:)以 UTF-8 读取 Markdown 文本调用 MarkdownRenderer.renderHTML底层是 cmark-gfm支持表格、删除线、任务列表等 GFM 语法转成 HTML拼上 PreviewCSS.swift 生成的样式表以及数学公式KaTeX、表格、Mermaid、代码高亮的注入脚本交给一个WKWebView加载webView.loadHTMLString(html, baseURL: MermaidSupport.resourceBaseURL) handler(nil)注意这里的轻量级QuickLook 扩展本身几乎不写业务代码全部复用主应用已有的渲染栈。扩展真正的差异化配置集中在 ClearlyQuickLook/Info.plistNSExtensionPointIdentifier声明为com.apple.quicklook.previewQLSupportedContentTypes列出支持的 UTI内容类型标识开启QLSupportsSearchableItems让 Finder 快速预览中支持文字查找。沙盒权限则非常克制见 ClearlyQuickLook/ClearlyQuickLook.entitlements——只开了app-sandbox和network.clientQuickLook 进程以 XPC 形式运行不能碰主应用之外的东西。⚠️ 3 个 LaunchServices 陷阱为什么你的预览只是原始文本这是全文最值钱的部分。.md的 QuickLook 预览、Finder 分栏预览、.md 的默认打开方式三者共享同一套 LaunchServices 路由任何一环配置错误系统都静默回退到原生纯文本预览器Text.qlgenerator日志里几乎找不到报错。以下是 Clearly 团队记录在 CLAUDE.md 中的三个必须同时满足的不变量陷阱 1必须用UTExportedTypeDeclarations而不是UTImportedTypeDeclarationsClearly 在 Clearly/Info.plist 中用导出Exported声明来认领net.daringfireball.markdown这个内容类型并声明md、markdown等扩展名属于它。如果你用UTImportedTypeDeclarations很多教程示例都这么写当系统上没有其他应用权威导出该类型时LaunchServices 会把这个导入声明标记为inactive imported untrusted结果quicklookd直接放弃你的扩展回退到纯文本预览。导出声明则意味着这个类型由我说了算。陷阱 2LSHandlerRank必须是Owner同一份 Clearly/Info.plist 的CFBundleDocumentTypes里.md文档类型的LSHandlerRank写的是Owner。原因如果用默认的Default其他以Owner级别认领 Markdown 的应用某些代码编辑器、写作工具就会在默认打开程序的竞争中获胜——哪怕它们的内容类型声明更弱。这会导致 Finder 双击.md打开的不是你的编辑器。陷阱 3QLSupportedContentTypes必须同时包含两个 Markdown UTI这是最隐蔽的一个。macOS Spotlight 在文件首次被索引时会粘性地给它定型当时系统上哪个 Markdown UTI 是权威的文件就被标成那个类型。结果就是曾经装过 iA Writer或任何导出net.ia.markdown的应用的用户磁盘上约一半的.md文件会被定型为net.ia.markdown——即使那个应用早已卸载。而 QuickLook 系统只调用QLSupportedContentTypes里列出的 UTI 对应的扩展。所以 ClearlyQuickLook/Info.plist 里老老实实写了两行keyQLSupportedContentTypes/key array stringnet.daringfireball.markdown/string stringnet.ia.markdown/string /array少写任何一个另一批用户的文件就会永久停留在原始文本预览。️ 附赠验证环节的隐藏深坑修好配置只是开始怎么验证本身还有坑同样记录在 CLAUDE.mdqlmanage命令行不可信在 macOS 26 上它对.appex预览扩展会直接崩溃qlmanage -m plugins也只列出旧式.qlgenerator插件空结果属于正常现象。唯一的可靠测试方式是Finder 里按空格未公证的扩展不被quicklookd调用新系统要求父应用完成公证notarization staple 后扩展才会生效。所以本地验证发布产物时要走完整的公证 →staple→qlmanage -r刷缓存流程旧注册会污染本机 LaunchServices大量 DerivedData / 并行工作目录里的开发版应用会留下成百上千条陈旧注册且新版 macOS 已移除lsregister -kill只能按路径逐条lsregister -u清理。 iOS 侧预览扩展 自定义缩略图Mac 之外Clearly 在 iOS/iPadOS 上还做了两件事配置思路完全一致1. QuickLook 预览扩展Clearly/iOS/PreviewExtension/PreviewViewController.swift逻辑与 Mac 版几乎相同但多了一步——注册了LocalImageSchemeHandler处理本地图片并把baseURL设为文件所在目录让相对路径图片能在预览中正常显示。2. 自定义缩略图扩展Clearly/iOS/ThumbnailExtension/ThumbnailProvider.swift在文件App 列表视图里给.md文件画出标题 前几行正文的定制缩略图。它的做法很聪明——只读文件前 4096 字节readSample提取第一个#标题和最多 12 行正文来绘制缩略图生成快且不拖慢文件系统列表宽度小于 64pt 时干脆画空白让系统自己贴文档角标。 细节深色模式一行都不用改因为样式全部来自共享的PreviewCSS它内部用media (prefers-color-scheme: dark)自动适配深色模式。QuickLook 预览跟着系统外观切换主应用零成本获得同样的体验 总结你的 QuickLook 扩展检查清单从 Clearly 的实现中可以提炼出这份可复用的检查清单#检查项Clearly 对应文件1扩展目标独立、随主应用内嵌Bundle ID 用独立后缀project.yml2渲染逻辑放共享包扩展只做胶水MarkdownRenderer.swift3用UTExportedTypeDeclarations声明内容类型Clearly/Info.plist4LSHandlerRank设为OwnerClearly/Info.plist5QLSupportedContentTypes覆盖所有历史UTIClearlyQuickLook/Info.plist6验证用 Finder 空格别信qlmanageCLAUDE.mdQuickLook 扩展的代码量小得惊人——难点全在配置与系统路由。照着这份清单走你的 Markdown 文件在 Finder 里按下空格的那一刻就该是一篇排版精美的文章。赞分享【免费下载链接】clearlyMarkdown editor for Mac, iOS and iPadOS项目地址https://gitcode.com/gh_mirrors/cle/clearly点击查看免费下载相关推荐Go-Chassis 服务发现与注册集成 ServiceComb 与 Kubernetes 完整指南Go Chassis 服务发现与注册集成 ServiceComb 与 Kubernetes 完整指南 Go Chassis 是一款云原生应用框架专为 GoQuickLook5个超实用技巧让你3分钟精通Windows文件预览神器QuickLook5个超实用技巧让你3分钟精通Windows文件预览神器 你是否曾在整理项目文件时为了查看一个图片内容而不得不启动Photoshop或者在桌面应用插件系统如何免费使用 Markdown Viewer浏览器扩展完全指南让 Markdown 预览更高效 如何免费使用 Markdown Viewer浏览器扩展完全指南让 Markdown 预览更高效 Markdown Viewer 是一款强大的浏览器扩展前端文档创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考