Tolaria 文件与媒体处理指南Markdown 可持久化的图表、附件、预览、HTML 与白板【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolariaTolaria 是一个以 Markdown 笔记为核心的桌面知识库管理应用但一个 Vault笔记库绝不止于.md文件——它还可以承载图片、PDF、音视频、独立 HTML 文件、白板以及其他本地文件。本篇指南围绕 Tolaria 的文件与媒体子系统展开你将掌握 Mermaid 图如何以纯文本形式持久化在笔记中、粘贴的远程图片如何被安全导入本地、图片/PDF/媒体的应用内预览与回退策略、独立 HTML 文件的沙箱化预览边界、tldraw 白板的 Markdown 存储格式以及被 Git 忽略的内容如何在 Vault 中按边界过滤。文中所有机制均有仓库源码与 ADR 决策记录作为依据可直接用于日常使用与二次开发排查。从笔记到文件Tolaria 的 Vault 文件模型Tolaria 的核心文件模型以「文件系统为事实来源」为第一原则参见 ADR-0002笔记是普通的 Markdown 文件图片、PDF、音视频、白板与 HTML 同样是 Vault 中真实存在的文件。Vault 扫描器会为每个文件标记fileKind如markdown、text、binary见 ADR-0041而文件的预览能力不是持久化的 schema 字段而是由渲染层根据文件扩展名推断出来的——这一约束在多个 ADR 中被反复强调保证了新增媒体类型时无需迁移缓存结构。在这个模型下Markdown 笔记内可以引用或嵌入其他文件二进制文件保持「普通 Vault 条目」的身份不引入专有文档类型所有资源路径遵循便携的attachments/...相对路径约定由 src/utils/vaultAttachments.ts 统一解析。Mermaid 图Markdown 可持久化的图表当笔记需要一张「应当保持纯文本、可被 Git 版本化」的示意图时Tolaria 使用 Mermaid 代码块。在笔记中写入如下 Markdown 即可Tolaria 会在富文本编辑器中渲染 Mermaid 图表同时让源码始终以 Markdown 形式存在——复制、关闭重开、进入 raw 模式都不会丢失原始围栏源码。实现原理Markdown 占位符往返round-trip根据 ADR-0088Tolaria 采用「编辑器管线自有的 Markdown 占位符往返」方案与 wikilink、数学公式共享同一套架构。其核心链路为在 BlockNote 解析 Markdown 之前先将围栏mermaid块转换为临时占位符token 前缀为TOLARIA_MERMAID_BLOCK:占位符被替换为mermaidBlock架构块其中同时保存原始围栏源码source与图表正文diagram富文本编辑器通过mermaid包渲染该块保存、进入 raw 模式、以及编辑器位置快照前mermaidBlock节点被序列化回其存储的围栏 Markdown当 Mermaid 无法渲染某段非法图表源码时直接以内联形式显示原始源码而不是破坏编辑器表面。这段解析/序列化桥接逻辑集中在 src/utils/mermaidMarkdown.ts它导出一个mermaidMarkdownCodecDurableBlockCodec实现。源码还揭示了一个细节looksLikeMermaidDiagram会识别常见的 Mermaid 图表类型关键词因此未标注mermaid语言、或语言为text/plain/plaintext的代码块只要首条有效语句匹配也会被自动注入为 Mermaid 块。识别到的图表类型包括flowchart、graph、sequenceDiagram、classDiagram、stateDiagram/stateDiagram-v2、erDiagram、journey、gantt、pie、mindmap、timeline、quadrantChart、requirementDiagram、gitGraph、C4Context、C4Container、C4Component、C4Dynamic、sankey-beta、xychart-beta。渲染组件位于 src/components/MermaidDiagram.tsx并有对应测试 MermaidDiagram.test.tsx 覆盖渲染与回退行为。附件粘贴即本地化远程图片后台导入Tolaria 的附件模型遵循「粘贴即落盘」的设计粘贴到编辑器中的图片会作为普通文件保存进 Vault保持可移植性任何其他工具都能直接打开。粘贴网页内容时的远程图片导入当粘贴的网页内容包含符合资格的远程图片时Tolaria 会在后台将这些图片导入attachments/目录并把粘贴引用改写为本地路径——文本内容立即呈现如果某张图片无法安全导入其原始远程引用保持可编辑状态而不是阻塞整个粘贴操作。这是 ADR-0162 确立的「先粘贴、后导入」模型富文本模式与 raw 模式共用同一套远程图片提取/导入逻辑但各自保留原生粘贴行为。从 ADR 可以了解到 Rust 边界上的安全校验非常严格将每个下载目标解析为公网地址并将 HTTP 客户端固定到该地址拒绝本地/私有/链路本地目标地址、URL 凭据、不支持的协议、不安全的跳转、非图片或不支持的 MIME 类型拒绝超过15 MiB的响应以及超出有界连接/总超时的请求跳转redirect会重复同样的校验字节在附件文件创建前先缓冲文件名取自最终 URL 的文件名主干加上校验后的 MIME 扩展名。同时私有网络图片与 SVG 明确不会被网页粘贴路径导入。成功保存的引用使用可移植的attachments/...表示并复用现有的唯一附件路径所有权逻辑。下载失败时只会产生一条本地化的非阻塞消息正文与已成功的图片不受影响。便携附件路径解析src/utils/vaultAttachments.ts 是附件路径解析的核心它定义了三种可识别的便携路径前缀attachments/相对前缀./attachments/带点相对前缀/attachments/根相对前缀vaultAttachmentPath根据 Vault 所在平台选择/或\分隔符resolveVaultAttachmentPath依次尝试相对附件路径、Tauri 资源 URL 与原始路径最终必须验证目标路径位于活动 Vault 之内才返回结果并拒绝含..不安全段落的路径。attachmentAssetUrlFromPath通过 Tauri 的convertFileSrc生成资源访问 URL。相关测试见 vaultAttachments.test.ts 与 remoteImagePaste.test.ts。预览图片、PDF 与媒体文件Tolaria 可以在应用内预览常见的图片文件、PDF 与受支持的媒体文件没有应用内预览的文件仍然可以通过系统默认应用打开。预览体系的关键设计源自 ADR-0086 与 ADR-0110单一渲染面FilePreviewsrc/components/FilePreview.tsx是唯一负责二进制文件预览的渲染层组件扩展名推断预览能力由 src/utils/filePreview.ts 依据安全的扩展名白名单推断而不是持久化的 schema 字段作用域资源访问图片通过img、PDF 通过 webview 的 PDF 渲染器、音视频通过原生 HTML 媒体控件展示全部经由 Tauri 作用域资源协议convertFileSrc生成的asset://类 URL不开放宽泛的文件系统读取外部打开走命令边界委托操作系统打开文件前必须先重新进入活动 Vault 的命令边界校验。一个值得注意的平台差异来自 ADR-0121由于 Linux AppImage 构建下的 WebKitGTK 音频/视频播放运行时不够稳定AppImage 版本对音频/视频默认回退为「外部打开」控件而图片与 PDF 预览在所有平台保持应用内。预览策略是运行时拥有的——渲染层先询问原生运行时是否需要外部媒体回退再决定是否渲染音视频元素因此编辑器内嵌的音视频块与文件预览遵循同一运行时门控行为保持一致。设置控制列表可见性设置项控制 PDF、图片以及不受支持的文件是否出现在「所有笔记」All Notes列表中文件夹浏览Folder视图始终按文件夹展示实际存在的文件。这意味着 All Notes 可以聚焦于笔记类内容而文件夹视图保留文件系统的真实全貌。HTML 文件沙箱化的应用内预览独立的.html与.htm文件可以在应用内以净化后的预览形式打开。本地图片、样式、字体与媒体文件只要其路径保持在 Vault 内部即可正常工作。预览模式会移除脚本、表单、嵌套 frame 与远程资源如果需要编辑源码切换到 raw 模式当文件需要交互式浏览器行为时则在默认浏览器中打开。这一设计来自 ADR-0168HTML 文件在编辑器窗格中通过净化过的、不透明源opaque-origin的 iframe 预览渲染iframe 以srcdoc方式注入内容渲染器在设置srcdoc前移除脚本、事件处理器、表单、嵌套 frame、嵌入对象等活跃控件添加限制性的 Content Security Policy禁用脚本、网络连接、workers、表单、嵌套 frame、对象与 base URL 变更iframe不授予allow-scripts与allow-same-origin因此预览内容无法接触 Tolaria 的文档、存储或 Tauri IPC本地被动资源图片、样式表相对于 HTML 文件解析仅当其归一化路径仍在活动 Vault 内时才接受并转换为既有的作用域 Tauri 资源 URL远程被动加载会被移除链接可在独立的带noopener/noreferrer的外部浏览上下文打开既有的「默认应用打开」命令仍然可用。预览占据与富文本编辑器相同的表面面包屑的源码按钮或Cmd/Ctrl\可将 HTML 文件切换到既有的 CodeMirror raw 编辑器RawEditorView.tsx正常保存行为适用再次切换则基于当前标签页内容重建预览。渲染实现位于 src/components/HtmlFilePreview.tsx。此外如果你想在笔记内部嵌入一段静态 HTML而不是打开整个 HTML 文件Tolaria 的围栏html块走的是同一套沙箱思路Markdown 可持久化的htmlBlock节点在净化后的沙箱 iframe 中渲染可携带可选的height元数据见 ADR-0154 与 HtmlBlock.tsx。白板tldraw 画布Markdown 存储白板使用 tldraw 作为编辑器中的交互画布但其持久化表示始终保持在 Markdown 中——这保证了白板与其余笔记一起留在 Vault 内、被 Git 版本化。根据 ADR-0107其实现路径为在 BlockNote 解析 Markdown 前将围栏tldraw块转换为临时占位符占位符被替换为tldrawBlock架构块存储稳定的白板 id与tldraw 文档快照 JSON富文本编辑器中用tldraw包渲染每个块tldraw 文档变更被防抖debounce写入 BlockNote 块属性从而由 Tolaria 常规的自动保存机制把快照写回.md文件保存、raw 模式与编辑器位置快照前tldrawBlock节点序列化回围栏 Markdown提供/whiteboard斜杠命令插入同样的块格式。会话状态如相机位置、选中形状、选中工具不会被持久化进笔记预览图在初始设计中也被有意排除。解析/序列化桥接位于 src/utils/tldrawMarkdown.tstldraw 运行时集成位于 src/components/TldrawWhiteboard.tsx测试见 TldrawWhiteboard.test.tsx。raw 模式仍然是对围栏 JSON 的直接源码编辑器。Git 边界被 Git 忽略内容的可见性过滤如果某些生成文件或仅本地文件被 Git 忽略Tolaria 可以把它们从笔记、搜索、快速打开与文件夹中隐藏——适用于构建产物或私有本地文件不应表现得像 Vault 内容时的场景。该功能由 ADR-0094 定义关键设计是「扫描与缓存保持完整过滤发生在命令边界」hide_gitignored_files是一个安装本地的应用设置默认值为true见 src/lib/gitignoredVisibility.ts 中的DEFAULT_HIDE_GITIGNORED_FILES以及 src/types.ts 中的设置类型定义可见性检查使用批量git check-ignore --no-index --stdin尽可能贴近 Git 常规的忽略与否定negation语义list_vault、reload_vault、list_vault_folders与关键词搜索在设置开启时应用同一过滤切换该设置会重载当前 Vault 的各个表面而不是重建另一种缓存格式如果 Vault 没有.gitignore或该设置被关闭Tolaria 显示完整扫描结果。这种「完整扫描 边界过滤」的取舍在于把 Gitignored 可见性做成每台安装的舒适偏好而非 Vault 共享元数据搜索、文件夹列表与笔记重载始终一致地咨询同一过滤边界缓存也能在不做数据迁移的情况下支持未来的可见性变化——用户关闭设置即可立即重新看到被忽略的内容。设置界面见 SettingsPanel.tsx相关测试见 gitignoredVisibility 相关的 lib 与 hooks 测试。延伸阅读文件模型与资源作用域ADR-0041 全文件扫描、ADR-0099 累积 Vault 资产作用域粘贴与导入ADR-0162 远程粘贴图片的安全本地导入预览体系ADR-0086 图片预览、ADR-0110 媒体与 PDF 预览、ADR-0121 AppImage 外部回退HTML 沙箱ADR-0168 独立 HTML 文件预览、ADR-0154 围栏 HTML 块图与白板ADR-0088 Mermaid 图、ADR-0107 tldraw 白板Git 边界ADR-0094 Gitignored 内容可见性【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考