【免费下载链接】swift-markdown-engine
A native AppKit Markdown editor for macOS, built on TextKit 2 and bridged to SwiftUI.
MarkdownEngine 是一款基于 TextKit 2 构建的原生 macOS Markdown 编辑器，通过 SwiftUI 桥接使用，零外部依赖。官方仓库中的 Demo 项目内置了一篇精心设计的样例文档，把核心 Markdown、可选产品、两条"可选缝隙"（Extensions 与 Directives）全部特性按来源分层展示——只要读懂这一篇文档，就等于把整个编辑器过了一遍。
为什么官方 Demo 是最好的学习入口
大多数开源项目的文档是"说明书"，而 Demo/ 目录下的示例工程是"活教材"：
- 样例文档的章节顺序刻意不按功能点排列，而是按"每个构造从哪来"排列，一眼分清哪些是引擎内置、哪些要加依赖、哪些要手动注册；
- 工具栏提供 6 个实时开关，可以在不重新编译的情况下切换引擎模式；
- 源码极简，入口只有 ContentView.swift，全部特性装配逻辑集中在一个
configuration计算属性里，非常适合作为二次开发模板。
如何运行 MarkdownEngine 官方 Demo
git clone https://gitcode.com/gh_mirrors/sw/swift-markdown-engine用 Xcode 打开 MarkdownEngineDemo.xcodeproj 后直接Run。Demo 通过本地路径引用包，任何引擎侧的改动都会在下次运行时自动生效。窗口入口见 MarkdownEngineDemoApp.swift，最小尺寸 640×480。
⚠️ 如果遇到 "missing package product" 报错，通常是过期的包缓存导致，执行File → Packages → Reset Package Caches后重新构建即可（官方 README 中明确提示了这一点）。
样例文档的三段式结构：核心特性分层速览
打开 Demo，样例文档以三条分隔线切成三部分，这也是理解整个项目设计哲学的钥匙：
| 部分 | 内容 | 启用方式 | 关闭后的表现 |
|---|---|---|---|
| Part 1 · Core markdown | 行内样式、引用、列表、任务列表、表格 | 链接MarkdownEngine即得 | 两个工具栏开关都不影响此部分 |
| Part 2 · Optional products | 代码块高亮、LaTeX 公式 | 各多依赖一个 SPM 产品 | Markdown 照常解析，只是回退为朴素外观 |
| Part 3 · Opt-in seams | 高亮/删除线扩展、@指令 | 在配置中注册 | 同一串字符原地退化为纯文本 |
Part 2 与 Part 3 的区别正是项目反复强调的一点：Part 2 只改变"看起来如何"，从不改变"能否解析"；而 Part 3 的构造完全由注册表决定，未注册就是普通文字。
Part 1 核心 Markdown 特性：实时样式一览
链接MarkdownEngine后无需任何额外代码，以下特性开箱即用（样例片段见 ContentView.swift）：
- 行内格式化：
**粗体**、*斜体*、***两者兼得***、反引号行内代码，边输入边变样式； - 引用与列表：引用块保留完整行内样式，引用标记自动隐藏；列表按 Return 自动续行，Tab / Shift-Tab 缩进/反缩进嵌套层级，有序列表编辑时自动重新编号；
- 任务列表（Task Lists）：GitHub 风格
- [x]复选框，点击即可切换勾选状态，图标是 SF Symbols，可通过config.taskCheckbox定制； - GFM 表格：单元格按可用宽度自动换行；列数过多放不下时保持宽度并横向滚动，而不是把单元格挤扁——样例文档里那张 12 列的"小说速查表"就是专门演示这一点的；
- 分隔线、标题缩放：标题字号按基础字号（工具栏可在 10–28pt 间调节）相对缩放。
这些渲染能力由 Sources/MarkdownEngine/Parser/ 下的两阶段 AST 管线（BlockParser → InlineParser）和 Sources/MarkdownEngine/Styling/ 下的样式器实现，增量解析保证每次按键只重解析被编辑的块，长文档也能保持流畅。
Part 2 可选产品：代码高亮与 LaTeX 公式
两个"重"特性因为要引入第三方依赖，被拆成了独立 SPM 产品（见 Package.swift）：
代码块语法高亮开启方法
依赖MarkdownEngineCodeBlocks产品并注入官方桥接：
configuration.services.syntaxHighlighter = HighlighterSwiftBridge()桥接层（HighlighterSwiftBridge.swift）基于 HighlighterSwift，自动跟随系统深浅色切换atom-one-light/atom-one-dark主题，并处理行高、外观监听、布局时机等细节。未链接该产品时，围栏代码块仍被解析、仍占据代码块外观，只是回退为纯等宽字体。
LaTeX 数学公式渲染配置
依赖MarkdownEngineLatex产品并注入 SwiftMathBridge 后，行内$e^{i\pi} + 1 = 0$与块级$$\int …$$都会渲染为数学符号（样例文档里的欧拉恒等式和高斯积分就是演示）。注意$…$语法本身是核心语法——解析器无论如何都会认领它，缺的只是渲染产品，这正是 Part 2 的定义。
Part 3 可选缝隙：Extensions 与 Directives
这是 MarkdownEngine 最有特色的部分：两条"可选缝隙"让你在不改引擎的前提下扩展语法。工具栏的Opt-in seams开关会同时注销两侧，你会看到 Part 3 原地坍缩为纯文本，而 Part 1、Part 2 纹丝不动。
缝隙一：Extensions（分隔符形状）
扩展 =一对定界符 + 中间内容如何着色，例如==高亮==与~~删除线~~并不是核心语法的一部分，而是由HighlightExtension和StrikethroughExtension提供的：
config.extensions = [HighlightExtension(), StrikethroughExtension()]注册后即可与核心语法自由嵌套（==with *italic* inside==），未注册的写法保持为字面文字。核心引擎掌握所有几何、标记隐藏、光标显隐与增量重着色，扩展行为与内置构造完全一致。接口定义在 MarkdownExtension.swift。
缝隙二：Directives（命名指令）
需要"名称 + 类型化参数"而分隔符表达不了的构造，交给指令：
@font(size: 18){eighteen point} @color(red){tinted} @flag(JP) @emoji(rocket) @icon(star.fill, color: yellow) @pagebreak两种形态：容器式（带正文，字体变换可双向组合——@font(size: 20){**bold**}同时放大且加粗，放进标题里仍保持标题字重）与自含式（无正文，原地绘制一个随上下文缩放的图标/文字，源字符只是收缩为零宽度，选区、查找、复制、撤销全部照常）。
- 引擎只内置
FontDirective和ColorDirective两个纯展示参考实现； @icon、@flag、@emoji、@pagebreak则由 Demo 自己在 DemoDirectives.swift 中实现，每个 30–60 行，含参数 schema、字形与补全——这就是"自定义指令"的完整样板，例如 FlagDirective 无需内置数据集即可匹配全部 ISO 国家代码。
指令自动补全：输入 @ 即可体验
引擎负责检测触发符、排序候选并路由 ↑/↓/↵/Esc 按键，你只需要画列表。Demo 的整个补全弹层约 60 行 SwiftUI（ContentView.swift），同时服务指令名和参数值两类补全：输入@列出所有已注册指令；输入@flag(jap会按代码或国家名匹配出JP并预览国旗；输入@emoji(则带表情预览。每个指令通过valueCompletions(for:prefix:)自行声明候选来源，编辑器无需了解国旗、表情或符号的任何细节。
工具栏 6 个实时开关：编辑器模式速查
Demo 工具栏（ContentView.swift）是观察引擎能力最快的方式：
| 开关 | 作用 | 对应配置 |
|---|---|---|
| Focus editor | 让编辑器获得焦点 | isFocused绑定 |
| Read-only | 只读模式：样式文档仍可滚动、选择，编辑关闭 | isEditable |
| Raw source | 原始源码模式：无样式、无语法隐藏 | config.rawSourceMode |
| Reading column | 居中固定宽度阅读栏（620pt），宽表格自动撑满全窗 | config.readingWidth |
| Opt-in seams | 同时注销 Part 3 的全部扩展与指令 | config.extensions/config.directives |
| 字号 ± | 基础字号 10–28pt，标题/代码/公式相对缩放 | fontSize参数 |
另有Header菜单可开启"滚动消失头部"：一个由宿主提供的 SwiftUI 视图托管在文档上方，随文档滚动、可折叠为 40pt 吸顶行——适合放文档元信息或属性表。
源码导读：Demo 其实只做了三件事
想在自己的项目里复刻这套能力，只需关注三个位置：
- 装配配置：ContentView.swift 的
configuration属性——按需注入高亮桥接、公式桥接、扩展与指令，这是全文最重要的 50 行； - 样例文档：同文件 sampleMarkdown 及各分区字符串常量，展示了每一部分"未启用时"的诚实回退文案写法；
- 应用层指令：DemoDirectives.swift——携带业务数据（图标目录、国旗、表情）与文档策略（分页符）的指令应留在应用侧，这正是官方对引擎边界的划法。
更深入的管线细节（两阶段 AST、token 投影、增量解析不变量）可阅读 ARCHITECTURE.md，完整 API 文档以 DocC 形式随包发布，在 Xcode 中Product → Build Documentation（⇧⌃⌘D）即可查看。
常见问题：遇到 "missing package product" 怎么办
这几乎总是过期的包缓存，而非配置错误。执行一次File → Packages → Reset Package Caches后重新构建即可。另外注意：核心MarkdownEngine产品零外部依赖；只有你显式引入MarkdownEngineCodeBlocks或MarkdownEngineLatex时才会带入 HighlighterSwift 与 SwiftMath。
结语：从 Demo 出发，三步上手
📌 一句话总结：
- 链接
MarkdownEngine—— Part 1 全部核心特性立即可用； - 按需加产品—— 代码高亮、LaTeX 各一个依赖，只换外观不破坏解析；
- 注册自己的缝隙—— 一对定界符写扩展，一个名字加参数写指令，30–60 行即可上线。
官方 Demo 就是这三步的活样本，样例文档就是特性清单本身。跑起来、开着 6 个开关来回拨动，MarkdownEngine 的设计边界会自己浮出水面。
【免费下载链接】swift-markdown-engine
A native AppKit Markdown editor for macOS, built on TextKit 2 and bridged to SwiftUI.
相关推荐
Universal-Updater快捷键与快捷方式功能详解：提升使用效率的10个技巧
Universal Updater快捷键与快捷方式功能详解：提升使用效率的10个技巧 Universal Updater是一款专为3DS自制软件设计的安装与更新
包管理器Universal Ctags 项目完全指南：文档体系、构建方式与核心特性详解
Universal Ctags 项目完全指南：文档体系、构建方式与核心特性详解 导读 ：本文以 Universal Ctags Hacking Guide（即
开发工具CLISpring Modulith 入门指南：如何构建模块化 Spring Boot 应用
Spring Modulith 入门指南：如何构建模块化 Spring Boot 应用 Spring Modulith 是一款强大的工具，能帮助开发者轻松构建模
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
