Clearly架构解析：一个ClearlyCore包如何同时驱动Mac与iOS的Markdown渲染

【免费下载链接】clearlyMarkdown editor for Mac, iOS and iPadOS项目地址https://gitcode.com/gh_mirrors/cle/clearly点击查看免费下载Clearly 是一款原生 Markdown 编辑器面向 Mac、iOS 与 iPadOS。很多人好奇同一个 Markdown 文件为什么它在 Mac 的预览窗、Finder 的 QuickLook、甚至 iPhone 的预览里长得一模一样秘密就在一个名为 ClearlyCore 的本地 Swift 包中——它把 Markdown 渲染、语法高亮、主题配色与文档状态等所有平台无关逻辑收进同一个包让 Mac 与 iOS 两份 App 共用同一套大脑。这篇文章带你拆解这个包的结构从跨平台抽象层、cmark-gfm 渲染管线到一个包驱动五个构建目标的工程配置看完你会收获一套可直接套用的跨平台 Swift 架构思路 一、认识 ClearlyCore五大模块各司其职ClearlyCore 是一个本地 Swift Package位于 Packages/ClearlyCore/在 Package.swift 中声明支持macOS 15与iOS 17双平台。包内目录即职责划分目录职责代表文件Rendering/Markdown → HTML 渲染管线与主题MarkdownRenderer.swift、PreviewCSS.swiftState/大纲、查找替换、状态栏等文档级状态OutlineState.swift、FindState.swiftPlatform/抹平 AppKit 与 UIKit 差异的抽象层Platform.swiftDiagnostics/日志与 Bug 上报 URL 生成DiagnosticLog.swiftStats/字数统计MarkdownStats.swift包外还有一个隐藏功臣Shared/Resources/ 目录里的 KaTeX、Mermaid、highlight.js 等前端资源由 project.yml 统一打包进各个构建目标保证渲染依赖同源同版本。二、跨平台第一招一套类型别名抹平 AppKit 与 UIKitmacOS 用 AppKit 的NSFont、NSColoriOS 用 UIKit 的UIFont、UIColor——核心代码若直接引用这些类型就得写两遍。Platform.swift 用编译期#if给每对类型起了统一别名#if os(macOS) public typealias PlatformFont NSFont public typealias PlatformColor NSColor #else public typealias PlatformFont UIFont public typealias PlatformColor UIColor #endif于是 Theme.swift 之类的文件只面向PlatformFont/PlatformColor编程颜色统一从 Colors.xcassets 读取自动适配明暗模式字体默认值再按平台微调——Mac 用 12pt 适合桌面密排iOS 用 17pt 贴合系统正文习惯。同一份代码两种手感这是跨平台渲染一致性的低成本起点。三、渲染管线cmark-gfm 打底 多步后置加工把 Markdown 变成 HTML 的核心在 MarkdownRenderer.swift 的renderHTML()先抽离 frontmatter避免 YAML 头干扰解析调用 cmark-gfm 库GFM表格、任务列表、删除线、自动链接把正文转成 HTML依次执行后置加工数学公式$...$→ KaTeX span、高亮、上下标、:emoji:短码、Callout 提示块、[[toc]]目录、表格标题、代码块文件名标签全程用protectCodeRegions()保护pre/code区域防止代码块内容被误改写。这条管线还有个巧思每个 HTML 节点都带data-sourcepos源码行号渲染结果与源文件行号精确对齐——双击预览跳回源码这类交互就靠它。完整管线细节可参考官方文档 docs/markdown-rendering-architecture.md。四、一个包驱动五个构建目标XcodeGen SwiftPMproject.yml 用 XcodeGen 声明了五个 target全部依赖同一个 ClearlyCore 包构建目标平台形态ClearlymacOS主 AppAppKit 编辑器 WKWebView 预览Clearly-iOSiOS 17iPhone/iPad 主 AppUIKit 编辑器 WKWebView 预览ClearlyQuickLookmacOSFinder QuickLook 预览扩展ClearlyPreview-iOSiOS文件 App 预览扩展ClearlyThumbnail-iOSiOS文件列表缩略图扩展SwiftPM 会为每个目标平台自动编译对应版本五个 target 共享同一份源码与同一套资源天然保证Mac 上看到的预览和 iPhone 上看到的预览像素级一致。iOS 端的差异其实很小把 Mac 的NSViewRepresentable换成UIViewRepresentable如 EditorView_iOS.swift、PreviewView_iOS.swift渲染器、CSS、语法高亮、大纲、查找则全部直接复用 ClearlyCore。五、架构小结一份核心多端薄壳这套架构最值得借鉴的三点逻辑归包、UI 归壳平台无关逻辑全部进 ClearlyCoreClearly/与Clearly/iOS/只保留视图桥接类型别名抽象用Platform*别名替代满屏#if跨平台代码可读性拉满声明式多目标XcodeGen SwiftPM 让五个构建目标共用一份依赖声明升级 cmark-gfm 或前端资源只需改一处。对于需要同时支持多平台、且要求渲染/行为严格一致的 Swift 项目单一核心包 多端薄壳是绕不开的参考范式 赞分享【免费下载链接】clearlyMarkdown editor for Mac, iOS and iPadOS项目地址https://gitcode.com/gh_mirrors/cle/clearly点击查看免费下载相关推荐libwebsockets lws-md 流式 Markdown 渲染器结构化事件驱动的安全渲染架构解析libwebsockets lws md 流式 Markdown 渲染器结构化事件驱动的安全渲染架构解析 lws md 是 libwebsockets 库中一后端网络通信OpenChamber 1.2.2 解析Agent Task 实时进度渲染与统一 Markdown 渲染OpenChamber 1.2.2 解析Agent Task 实时进度渲染与统一 Markdown 渲染 本篇围绕 OpenChamber 1.2.2202技术博客如何使用Swift Markdown UI在iOS应用中优雅渲染Markdown内容如何使用Swift Markdown UI在iOS应用中优雅渲染Markdown内容 Swift Markdown UI是一款专为SwiftUI打造的原生MarUI组件富文本创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考