MarkPane — 用户指南

MarkPane 是面向本地 Mac 文件的原生 Markdown 查看器。它可以打开 Markdown 文件、纯文本文件， 或包含相关 Markdown 文件的文件夹；创建新的 Markdown 文件和文件夹；在清爽的阅读表面中进行渲染； 并将常用审阅操作放在触手可及的位置：文件夹浏览、文件和文件夹创建、文件和文件夹重命名、 移至废纸篓删除、链接的 Markdown 标签页、搜索、源码编辑、任务复选框更新、本地图片访问、 图表渲染、数学公式渲染、排版控制和打印。

1. 打开 MarkPane。
2. 将 Markdown 文件或文件夹拖入查看器窗口，或选择 文件 > 打开 Markdown 或文件夹...（Command-O）。
3. 要开始新文档，请在空查看器中点击 新建 Markdown，选择目标位置， MarkPane 会在源码编辑器中打开新文件。
4. 如果你打开的是文件夹，点击 Markdown 文件可在当前标签页中打开，Option-点击可在新标签页中打开。 使用文件夹操作菜单或上下文菜单可以创建 Markdown 文件和文件夹、重命名文件夹项目，或将选中的文件或文件夹移至废纸篓。
5. 阅读渲染后的文档。你可以直接在查看器中使用链接、details 区段、脚注、任务复选框、表格、图表和数学公式。
6. 按 Command-F 搜索渲染内容。
7. 按 Command-E 为当前文件打开源码编辑器。更改会自动保存回文件。
8. 按 Command-P 从当前活动的查看器或编辑器窗口打印。
9. 将指针悬停在已渲染的图片、表格或 Mermaid 图表上，然后点击 Open in New Window， 可在可调整大小的独立窗口中查看。

上方截图展示了核心的 Markdown 渲染布局，包括主文档表面和常用审阅控件。

查看器窗口

查看器窗口会显示渲染后的文档。未打开文件时，窗口会显示 Markdown 文件和文件夹的拖放目标， 以及用于创建新 Markdown 文件的按钮。

文件夹浏览器

选择或拖放文件夹后，文件夹浏览器会在单独窗口中打开。它会显示目录和受支持的 Markdown 文件， 高亮最前端的文件，标记已在标签页中打开的文件，保持空文件夹可见以便整理，并提供创建 Markdown 文件和文件夹、 重命名项目以及将选中文件或文件夹移至废纸篓的文件夹操作。

搜索栏

当你选择 编辑 > 在 Markdown 中查找 时，搜索栏会显示在文档上方。 它会显示当前匹配数量，并提供上一个/下一个控件。

源码编辑器

源码编辑器会在单独窗口中为当前文件打开。它适合在保留渲染视图可用的同时快速修正和更新内容。 按 Return 会续写常见 Markdown 结构，例如项目符号列表、有序列表、任务列表和引用； Tab 和 Shift-Tab 可缩进或减少选中行的缩进。

MarkPane 可以打开可读的本地文本文件，包括：

• .md
• .markdown
• .mdown
• .mkd
• .txt

你可以通过以下方式打开文件：

• 将文件或文件夹拖放到查看器窗口中。
• 选择 文件 > 打开 Markdown 或文件夹...（Command-O）。
• 在 Finder 中使用 MarkPane 打开受支持的文件。

你可以在空查看器中点击 新建 Markdown 来创建新的 Markdown 文件。 保存面板会建议 Untitled.md 或下一个可用的编号名称；创建后，MarkPane 会在源码编辑器中打开新的空文件。

当你选择文件夹时，MarkPane 会打开文件夹浏览器，而不是立即替换当前文档。

如果文件不是可读文本，MarkPane 会显示错误，而不是渲染该文件。

请将文件夹浏览用于项目笔记、文档文件夹以及相关 Markdown 文件集合。 文件夹浏览器会在你于文档之间切换时保持所选文件夹可用。

• 点击 Markdown 文件可在当前查看器标签页中打开。
• Option-点击 Markdown 文件可在新标签页中打开。
• 使用标题栏中的 文件夹操作 菜单，可在根文件夹中创建 Markdown 文件或文件夹。
• 右键点击文件夹并选择 新建 Markdown，可在该文件夹内创建文件。
• 右键点击文件夹并选择 新建文件夹，可在该文件夹内创建子文件夹。
• 右键点击文件或文件夹并选择 重命名，可进行行内重命名。按 Return 提交，或按 Escape 取消。
• 右键点击文件或文件夹并选择 删除，确认后会将其移至 macOS 废纸篓。
• 磁盘上的文件发生变化后，文件夹树会自动刷新。
• 当前最前端的文件会被高亮，已在标签页组中打开的文件会被标记。
• 文件夹和受支持的 Markdown 文件会用于导航显示；其他文件可能会以灰色显示以提供上下文。

从文件夹浏览器创建 Markdown 时，MarkPane 会插入一个空文件，开始行内重命名；提交名称后， 新文件会在标签页中打开，并同时打开源码编辑器。创建文件夹时，MarkPane 会建议 Untitled Folder 或下一个可用的编号名称，开始行内重命名，并展开父文件夹，让新文件夹立即可见。

隐藏文件和包内容会在文件夹树中跳过。即使空文件夹尚未包含 Markdown 文件，也会显示并可展开。 创建、重命名和删除操作仅限于你授予访问权限范围内的可写项目；名称不能为空，也不能包含 /。删除会将选中项目移至废纸篓，而不是永久抹除。

• 新建窗口：选择 文件 > 新建窗口 （Command-N）可打开独立的查看器窗口。
• 新建标签页：选择 文件 > 新建标签页 （Command-T）可向当前窗口组添加查看器标签页。
• 链接的 Markdown 文件：点击渲染文档中的本地 Markdown 链接，可在 MarkPane 标签页中打开链接文件。 如果 macOS 需要链接文件所在文件夹的权限，MarkPane 会要求你选择该文件夹。
• 文档恢复：MarkPane 可以使用本地 macOS 文档书签记住上次打开的文档，供返回的窗口恢复。

MarkPane 使用原生 Swift 视图渲染 Markdown。受支持的内容包括：

• 标题、段落、强调、链接、引用、有序列表、无序列表和嵌套列表。
• 表格、代码块、行内代码、图片、脚注和 details 区段。
• 来自以尾随空格结尾的 Markdown 行的硬换行。
• GitHub 风格提醒：note、tip、important、warning 和 caution。
• 交互式任务列表复选框。
• 用于 flowchart、state、sequence、class、ER 和 XY chart 图表的 Mermaid 围栏代码块。
• 由 MathJaxSwift 支持的显示数学公式，适用于 $$...$$、\[...\] 和围栏 math 代码块。
• 已渲染的图片、表格和 Mermaid 图表可通过悬停时出现的控件，在可调整大小的独立窗口中打开。

原始 HTML 不会被执行。受支持的原生等效内容（例如 <details>）会直接渲染， 其他 HTML 块会以源码形式显示。

本地图片

如果 Markdown 文件引用了与文档存放在一起的图片，macOS 沙盒可能需要文件夹权限。 请使用行内的 允许本地图片 操作，并选择该 Markdown 文件所在的文件夹。 MarkPane 会使用该权限加载你选择公开给应用的图片。

链接

指向其他本地 Markdown 文件的链接会尽可能在 MarkPane 标签页中打开。 如果链接的 Markdown 文件位于 MarkPane 已有文件夹访问权限之外，macOS 可能会要求你选择该链接文件所在的文件夹。 https:// 等网页链接可能会在你的默认浏览器中打开。

1. 打开 Markdown 文件，或从空查看器或文件夹浏览器创建新的 Markdown 文件。
2. 选择 文件 > 编辑当前 Markdown（Command-E）。
3. 在编辑器窗口中编辑源码。
4. 在常见 Markdown 列表和引用中使用 Return，可继续当前结构。
5. 在空列表项上按 Return 可退出列表，或使用 Tab 和 Shift-Tab 缩进和减少选中行的缩进。
6. MarkPane 会自动将编辑保存回文件，并更新渲染后的文档。

Markdown 感知编辑支持项目符号、有序列表、任务列表、引用和选中行缩进。 在围栏代码块内，Return 会保持普通代码编辑行为，而不会添加 Markdown 列表标记。

只有当前查看器已打开有文件支持的文档时，才能使用“编辑当前 Markdown”。

点击已渲染的任务列表复选框，可更新 Markdown 文件中匹配的源码标记。MarkPane 会直接在磁盘上更改 [ ] 和 [x] 等标记。

如果文件无法写入，或复选框无法匹配到 Markdown 任务标记，MarkPane 会显示错误。

• 选择 编辑 > 在 Markdown 中查找（Command-F）。
• 输入搜索词。匹配项会在渲染文档中高亮显示。
• 使用 查找下一个（Command-G）和 查找上一个 （Shift-Command-G）在匹配项之间移动。
• 按 Escape 或关闭按钮可关闭搜索。

搜索作用于渲染内容，包括标题、表格、代码、数学公式回退文本、details 和脚注。

• 选择字体：选择 视图 > 选择字体... 可使用不同的渲染文档字体。
• 增大字体大小：Command-+
• 减小字体大小：Command--
• 增加行高：Shift-Command-+
• 减小行高：Shift-Command--
• 重置排版：从“视图”菜单恢复默认字体、字号和行高。
• 窗口透明度：从“视图”菜单选择百分比。
• 使用玻璃文档表面：从“视图”菜单切换文档表面样式，或使用 Option-Command-G。

选择 文件 > 打印...（Command-P），可从当前活动的查看器或编辑器窗口打印渲染后的文档。 MarkPane 会先为打印页面布局准备文档，然后显示标准 macOS 打印面板。

在 MarkPane 中选择 帮助 > 快速帮助（Shift-Command-/）， 可打开内置快捷键参考。

文件可以打开，但图片缺失

使用行内的 允许本地图片 操作，授予对该 Markdown 文件所在文件夹的访问权限。

无法编辑

请先打开一个有文件支持的 Markdown 文档。空查看器不会显示编辑器。

创建 Markdown 文件失败

请选择可写的本地文件夹，并使用受支持的扩展名，例如 .md、 .markdown、.mdown、.mkd 或 .txt。 MarkPane 不会覆盖同名的现有项目。

创建文件夹失败

请在可写文件夹内，通过文件夹操作菜单或文件夹上下文菜单创建文件夹。MarkPane 会建议 Untitled Folder，且不会覆盖同名的现有项目。如果文件夹为只读、位于你授予的文件夹访问范围之外， 或被 macOS 权限阻止，请将项目移至可写的本地文件夹后再试。

重命名文件夹项目失败

请从文件夹访问窗口的上下文菜单执行重命名。新名称不能为空、不能包含 /，也不能与同一位置的其他文件或文件夹同名。如果该项目为只读，请将其移至可写的本地文件夹后再试。

删除文件夹项目失败

请从文件夹访问窗口的上下文菜单执行删除。MarkPane 会在确认后将选中的文件或文件夹移至 macOS 废纸篓。如果该项目为只读、位于你授予的文件夹访问范围之外，或被 macOS 权限阻止， 请将其移至可写的本地文件夹后再试。

Markdown 列表续写没有在代码块中出现

在围栏代码块内，Return 会保持普通代码编辑行为，因此代码示例不会自动添加 Markdown 列表标记。

文件夹可以打开，但缺少预期文件

MarkPane 会跳过隐藏文件和包内容，并打开受支持的 Markdown 或文本文件。空文件夹会保持可见且可展开； 在磁盘上添加或重命名文件后，文件夹树会自动刷新。

链接的 Markdown 文件要求文件夹访问权限

请选择包含该链接文件的文件夹。MarkPane 会使用该 macOS 权限，在标签页中打开链接的 Markdown 文档。

Mermaid 或数学公式无法渲染

请检查围栏标签和语法。不受支持的 Mermaid 图表类型或无效 TeX 可能会显示为回退内容。

查找没有显示结果

查找会搜索渲染后的文档。请尝试输入可见渲染输出中出现的词，或在源码编辑器中检查原始 Markdown 语法。