这份手册对应墨岛笔记 NoteHarbor 0.4.1。软件当前以本地文件为中心：笔记和文档保存在你选择的资料库中，预览、搜索和附件管理均在本机完成。
在 macOS 上打开 DMG，把“墨岛笔记”拖到“应用程序”。当前安装包没有 Apple 公证；如果系统拦截首次启动，请在访达中右键应用并选择“打开”。
首次进入会显示七步新手引导。以后可以点击窗口右上角的问号或按 F1 打开“使用帮助”，搜索具体功能或重新查看引导。鼠标停留在主要图标按钮上也会显示简短说明和快捷键。
资料库就是一个普通的本地文件夹，不是墨岛笔记专用格式。
- 点击侧栏“资料库”标题旁的
+，选择“新建或添加资料库”。也可以在侧栏空白处右键打开这个菜单。 - 选择一个已有文件夹，或者直接在系统窗口中新建文件夹。
- 等待首次扫描完成；扫描期间仍然可以开始编辑。
添加资料库不会复制文件。文件夹中已有的 Markdown、TXT、PDF 和 Word 文档会自动扫描并显示。需要把资料库外的文件复制进当前资料库时，再从同一个 + 菜单选择“导入文件到当前资料库”。资料库中的文件夹最多显示和新建两层；更深的既有目录内容会归入第二层显示。
可以同时登记多个资料库。侧栏中当前选中的资料库是“活动资料库”，新笔记、每日笔记和导入文件会优先进入这里。全局搜索可以跨全部资料库，普通相对链接和 [[笔记链接]] 只在当前资料库内解析。
移除资料库只会取消登记，不会删除文件夹或其中内容。把一个文件夹从访达或 Windows 文件资源管理器拖进墨岛笔记，也可以在确认后直接登记为资料库；文件夹本身不会被复制或移动。
点击侧栏底部“新建笔记”会创建标准 .md 文件。Markdown 新笔记带有稳定 ID、创建时间、更新时间和标签信息，便于历史管理及未来同步。
- 点击编辑区顶部、“已保存”前面的笔记名，可以直接重命名。
- 输入新名称时不需要写
.md或.txt，软件会保留原扩展名。 - 改名或移动后，同一资料库内受影响的笔记链接和相对链接会自动更新。
- 输入停止约 500 毫秒后自动保存；内容稳定约 30 秒后创建历史快照。
- 如果文件被其他软件修改，墨岛笔记会停止覆盖，并让你选择载入外部版本、保留当前内容或另存副本。
编辑器提供三种模式，它们始终使用同一份文件内容：
- “Markdown”：完整显示 Markdown 原文和格式符号。
- “即时渲染”：在可编辑内容中显示标题、强调、图片等效果。
- “分栏”：左侧编辑、右侧预览，并同步滚动。
.txt 是一等文本笔记，不作为普通附件处理。它支持三种编辑模式、全文搜索、最近、收藏、置顶、自动保存、冲突保护、历史、大纲、普通链接、笔记链接和附件。
TXT 会一直保留 .txt 扩展名，不写 YAML，也不解析或写入标签。即时渲染会把 TXT 内容按 Markdown 兼容语法显示，但磁盘上仍然只是普通 UTF-8 文本，其他软件可以照常打开。
可以直接从 macOS 访达或 Windows 文件资源管理器拖入文件。拖动时，界面覆盖层会显示真实资料库和目标文件夹；松手前请确认落点。
| 拖放位置 | 处理结果 |
|---|---|
| 资料库行 | 导入资料库根目录，显示为正式文件 |
| 侧栏文件夹 | 导入该文件夹，显示为正式文件 |
| 普通工作区 | 导入当前活动资料库根目录 |
| Markdown/TXT 编辑器 | 图片、PDF、Word 和普通文件作为附件，并插入相对链接 |
| Markdown/TXT 编辑器 | .md、.txt 直接把其中的 UTF-8 文字插入当前笔记 |
| 任意可接收区域中的文件夹 | 确认后登记为新资料库，不复制或移动 |
文件和文件夹混合拖入时不会执行，请分开拖入。一次也只能登记一个资料库文件夹。
来源位置会影响附件处理：
- 文件位于当前资料库外：复制到当前资料库的
assets/。 - 文件已经位于当前资料库内：保留原位置，直接插入相对链接，不重复复制。
- 文件位于另一个资料库：复制到当前笔记所属资料库的
assets/。 - 文件重名：自动生成“名称 (2).扩展名”等不冲突名称。
墨岛笔记不会把系统绝对路径写进笔记。危险脚本、可执行文件、安装包、非 UTF-8 的 Markdown/TXT 和超过限制的文件会被拒绝导入。
“附件”和“资料库文件”是软件中的角色，不由磁盘位置决定：
- 附件：默认不出现在文件树、最近和全局搜索中，但可以从引用它的笔记中预览或打开。
- 资料库文件：显示在文件树，可以参与最近、收藏、置顶和文件名搜索。
assets/ 只是外部附件的默认存放位置。位于 assets/ 中的文件也可以被提升为正式资料库文件。
打开 Markdown 或 TXT 后，展开右侧信息面板并选择“附件”，可以查看：
- 当前笔记引用了哪些本地文件。
- 文件在资料库中的实际位置和角色。
- 有多少篇笔记正在引用这个文件。
- 预览或打开、在访达/文件资源管理器中显示。
- 转为资料库文件、移动到其他目录、复制相对路径。
- 移除当前引用或删除实际文件。
“转为资料库文件”只改变角色，不移动磁盘文件，因此所有链接保持不变。“移动到……”才会真正改变路径；执行前会为受影响笔记创建快照，并重新计算所有相对链接。如果任一步失败，文件和笔记会回滚到原状态。
“移除当前引用”只删除当前笔记中的链接，不删除文件。删除实际文件前会显示引用数量；存在引用时必须再次确认。
PDF 使用本地打包的 PDF.js 预览，不会上传文件，也不会使用网络 CDN。
- PDF 拖到侧栏：作为正式资料库文件，在普通标签页和主区域打开。
- PDF 拖到编辑器：作为附件，可从右侧“附件”页打开临时预览标签。
- 支持连续分页、50%–200% 缩放、页码跳转、文字选择和文内查找。
- 点击“默认软件打开”，可以使用系统 PDF 软件进行打印、表单填写或其他操作。
内置预览限制为 50MB。超过限制、文件损坏或受密码保护时，墨岛笔记会保留文件信息，并引导使用默认软件打开。首版暂不提供缩略图、PDF 目录树、打印、表单填写或批注编辑。
墨岛笔记支持 .docx 和旧式 .doc。导入后，软件会把原文件完整复制到当前资料库的 documents/，不转换、不改写外部原文件。
我的资料库/
├── 工作记录.md
├── 说明.txt
├── assets/
│ ├── 20260721-a3f82c.png
│ └── 参考资料.pdf
└── documents/
├── 项目方案.docx
└── 旧版会议记录.doc
- 点击侧栏“资料库”标题旁的
+，选择“导入文件到当前资料库”，再选择一个或多个 Word 文档。 - 如果资料库文件夹里原本就有 Word 文档，添加资料库后会自动扫描显示，不需要重复导入。
.docx可以在软件内本地预览，尽量保留图片、表格、分页、页眉和页脚，但不保证与 Word 像素级一致。.doc暂不支持内置预览，需要使用本地默认软件打开。- 导入时的外部源文件是主版本。检测到源文件变化后，软件会单向同步到
documents/副本。 - 外部源存在时，“默认软件打开”优先打开源文件；源文件不可用或没有关联时，打开资料库副本。
- 源文件移动或删除后，资料库副本仍然保留；选择“重新关联”可以继续同步。
- 删除资料库副本永远不会删除外部源文件。
Word 文件当前只按文件名和路径参与搜索，不索引正文，也不参与 Markdown 标签、大纲或反向链接解析。
在侧栏文件或文件夹上点击右键，会出现墨岛笔记自己的菜单，不再显示 WebView 的 Reload。
文件夹菜单包括：
- 新建笔记。
- 新建子文件夹。
- 导入文件。
- 排序方式：名称 A–Z、名称 Z–A、修改时间新–旧或旧–新。
- 重命名。
- 复制相对路径。
- 在访达或 Windows 文件资源管理器中显示。
- 确认后移到系统废纸篓或回收站。
资料库根目录不能重命名或删除。assets/ 和 documents/ 本身受到保护，但其中的自建子文件夹仍可正常整理。删除文件夹前会显示其中子项和受影响引用数量。
排序设置只作用于右键点击的那个文件夹，并会在本机记住；不同资料库、不同层级可以使用不同规则。文件夹始终显示在文件前面。选择“修改时间”时，子文件夹按照其内部最近一次修改时间参与排序；时间相同时按名称升序。没有手动选择时，默认按照中文名称升序排列。
文件菜单可以根据类型提供重命名、复制笔记链接、复制相对路径、置顶、收藏、打开、同步、在系统文件管理器中显示和移到废纸篓/回收站等操作。
Markdown 和 TXT 支持普通相对链接，以及：
[[目标笔记]]
[[目标笔记|显示名称]]在侧栏右键笔记并选择“复制笔记链接”，再粘贴到另一篇笔记即可建立关联。右侧“反向链接”会显示哪些笔记链接到了当前笔记。
⌘K（Windows 为Ctrl+K）打开全局搜索。- Markdown/TXT 可以搜索正文；PDF、Word 和普通资料库文件首版按文件名和路径搜索。
- “最近、置顶、收藏”用于快速过滤内容。
- Markdown 支持标签；TXT 不写入或解析标签。
- 右侧面板还提供大纲、附件、反向链接和历史版本。
点击窗口右上角的调色盘，可以选择“现代克制”“温暖纸张”或“通透玻璃”，并设置跟随系统、明亮或深色模式。点击面板外部、按 Esc 或切换到其他窗口，面板会自动收起。
“通透玻璃”在 macOS 使用原生通透材质，在 Windows 11 使用 Mica。透明关系发生在应用窗口和桌面/其他窗口之间；右键菜单、外观面板等软件内部浮层保持不透明，避免底层文字穿透。系统开启“减少透明度”时会自动使用不透明回退，保证正文可读性。
Markdown/TXT 的 .md/.txt 文件是内容的唯一真实来源。PDF、普通文件和 Word 副本也都保存在资料库中。搜索索引、附件角色、偏好设置和历史快照保存在系统应用数据目录，不会向资料库写入私有数据库。
文件删除会进入系统废纸篓或回收站；移除资料库只取消登记。Word 外部源文件始终不会被墨岛笔记移动、改写或删除。
建议使用 Time Machine、Git 或其他备份工具定期备份整个资料库。历史快照适合恢复误改，但不替代完整备份。当前的 Word 单向同步也不是云同步。
⌘K/Ctrl+K：全局搜索。⌘N/Ctrl+N：在当前资料库新建笔记。⌘\/Ctrl+\：显示或隐藏侧栏。F1：打开可搜索的使用帮助。Esc：关闭当前菜单或弹窗。
如果不确定某个按钮的作用，可以先把鼠标停在按钮上查看说明；需要完整步骤时按 F1，也可以从帮助中心重新开始七步新手引导。