2026/9/14 17:12:04
FEATURED · 精选文章 
Tolaria 富文本编辑器实战指南块级编辑、折叠、Callout 与 Markdown 无损往返【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolariaTolaria 的富文本编辑器Rich Editor以块block为核心组织内容同时保证每条笔记底层始终是可移植的 Markdown 文件。本指南将完整讲解斜杠菜单插入、整块选择与移动、标题折叠、代码块、Callout、高亮与 Raw 模式等日常高频工作流并结合仓库源码解析其Markdown → 块 → Markdown无损往返的实现原理帮助你既写得快又随时保有对底层文件的完全控制。一、块级编辑与可移植 Markdown两种模式写同一个文件Tolaria 的编辑器设计遵循 ADR-0022以 BlockNote 作为富文本编辑器日常写作使用 BlockNote 驱动的富文本模式需要精确控制时切换到 CodeMirror 6 驱动的 Raw 模式。两种模式读写的是同一个 Markdown 文件不存在编辑器私有格式——这与 editor 概念文档 中Both modes write back to the same Markdown file的定位一致。由此带来两个关键特性块结构仅在编辑体验中存在标题折叠、整块移动等操作只改变编辑器的呈现不会向文件里写入私有折叠语法见下文折叠长章节。Markdown 是唯一事实源任何时刻切换到 Raw 模式看到的都是真正落盘的内容可被 git、其他工具或 AI 直接读取。从源码看整个编辑器的块模型在 src/components/editorSchema.tsx 中定义自定义的 wikilink 内联内容、Callout 块、代码块、高亮样式等均通过 BlockNote 的createReactBlockSpec/createReactInlineContentSpec注册这就是块与 Markdown 语法一一对应的基础。二、插入常用块斜杠菜单与 Todo 快捷键在空行输入/即可打开斜杠菜单Slash Menu。常用命令包括标题heading、列表bullet / numbered list、引用quote、分隔线divider待办块todo / check list代码块code block表格table当前日期date当前时间time斜杠菜单的实际实现位于 src/components/tolariaEditorFormattingConfig.ts其中日期与时间命令DATE_TIME_SLASH_COMMANDS的格式化逻辑值得注意日期输出YYYY-MM-DD时间输出HH:MM补零到两位而日期时间命令则输出YYYY-MM-DD HH:MM见formatLocalDateTime。菜单项还支持别名例如today、clock、timestamp等便于快速检索。快捷键macOS / Windows·Linux作用CmdT/CtrlT在当前块段落 ↔ 待办之间切换/空行打开斜杠菜单三、选择与移动整块块级结构操作的快捷键体系编辑状态下按Esc即可选中当前块进入块选择模式。该模式下Up/Down移动选中光标在块之间跳转ShiftUp/ShiftDown扩展选中范围多块Enter退出块选择回到文本编辑CmdShiftUp/CmdShiftDownmacOS或CtrlShiftUp/CtrlShiftDownWindows/Linux移动选中的块复制、剪切、粘贴、删除均作用于被选中的整块。特别地折叠状态下标题下的隐藏内容会随标题一起复制、剪切、删除或移动——这意味着你可以在大纲级别重组文档而不必先展开再手动调整每一行。整套快捷键与 keyboard-shortcuts.md 参考文档 中Rich Editor Shortcuts一节一一对应跨平台差异源于 macOS、Linux、Windows 对键位组合的保留策略不同因此 Tolaria 刻意按平台提供不同绑定并使用命令面板CmdK/CtrlK作为当前命令集的权威来源。四、折叠长章节纯展示层操作不改写文件标题可以隐藏其下方直到同级或更高级标题之前的所有内容。两种触发方式点击标题旁的展开/收起控件disclosure control选中标题块后按CmdEnter/CtrlEnter。关键设计折叠只是编辑器的展示状态Tolaria 不会向 Markdown 文件中写入任何私有折叠语法。因此折叠/展开不会污染文件内容也不会影响 git diff 的整洁度而折叠时标题下隐藏的内容在块选择操作复制/剪切/删除/移动中仍会作为一个整体被携带两者配合可用于快速重组长文档。五、编写代码块围栏语法与语言高亮创建代码块有三种方式从斜杠菜单选择代码块直接输入三反引号围栏后按Enter使用快捷键CmdShiftBacktickmacOS/CtrlShiftBacktickWindows/Linux将当前块转换为代码块。创建后可通过代码块控件选择语言以启用语法高亮。行号仅为展示层信息不会写入笔记文件。关于语法高亮的具体实现可参考 ADR-0134直接注册 Shiki 语言 与编辑器源码中的代码块选项配置src/components/codeBlockOptions.ts。代码块相关的复制控件与语言选择控件分别位于 src/components/codeBlockCopyControls.tsx 和 src/components/codeBlockLanguageControls.tsx仓库还为此维护了 blocknote/code-block 补丁。六、CalloutObsidian 风格与 GitHub Alert 双语法兼容Tolaria 将 Obsidian 风格 Callout 和 GitHub Alert 语法渲染为可编辑块同时保留底层 Markdown 原样。基础写法 [!NOTE] Local-first This note stays readable outside Tolaria.Callout 类型后加或-可控制初始折叠状态 [!TIP]- Optional details This callout starts collapsed.Callout 正文在富文本模式下可直接编辑而类型、标题或初始折叠标记的修改则需要切到 Raw 模式进行。从源码看Callout 的实现非常完整解析逻辑在 src/utils/calloutMarkdown.ts标记正则CALLOUT_MARKER为/^\[!([a-z][a-z0-9_-]*)\](?![-])[ \t]*(.*)$/iu——它捕获[!type]后的可选标题并明确排除紧跟/-的折叠标记折叠状态由另一路径单独处理块渲染在 src/components/CalloutBlock.tsxpropSchema中calloutType默认值为notetitle默认为空渲染为aside classtolaria-callout ...按类型家族着色并附图标图标映射见 src/components/calloutIcons.ts斜杠菜单中提供完整的 Callout 类型集note、tip、warning、danger、info、question、success、abstract、example、failure、bug、quote、todo本地化标题通过 i18n 注入见 src/components/singleEditorSuggestionItems.tsx 的useSlashMenuItems。若未指定标题Callout 头部会按类型自动生成可读标题calloutHeadingnote显示默认标题my-type会变成My Type保证任何类型都有清晰的可视化呈现。七、高亮文本以记号持久化选中文本后使用格式化工具栏或按CmdShiftMmacOS/CtrlShiftMWindows/Linux即可应用/取消高亮。Tolaria 将高亮保存为标准的highlighted textMarkdown 记号因此高亮在文件层是普通 Markdown可在任意编辑器中保留语义。值得补充的是Tolaria 的高亮还支持多种颜色见 src/utils/markdownHighlightMarkdown.ts 中的MARKDOWN_HIGHLIGHT_COLOR_OPTIONS——默认黄色text另有绿色、红色、蓝色、紫色变体分别以、、、等字符作为 Markdown 前缀标记从而在不破坏纯 Markdown 可移植性的前提下实现彩色高亮。八、检查 MarkdownRaw 模式与前端 YAML 修复按Cmd\macOS/Ctrl\Windows/Linux可在富文本与 Raw 模式间切换。Raw 模式适合查看 Markdown 的确切表示验证块结构与实际落盘内容一致编辑 YAML frontmatter修改 Callout 的标记类型、标题、折叠标记修复异常粘贴产生的脏内容。Raw 模式的核心价值之一是无效 YAML frontmatter 会被高亮显示你可以直接定位结构性问题所在而无需猜测解析在哪一行失败。从编辑器结构看Raw 模式与富文本模式共享同一份文件状态切换入口也出现在面包屑栏BreadcrumbBar的 Raw editor / Back to editor 按钮上见 src/components/BreadcrumbBar.tsx 及其测试命令面板同样提供该命令src/App.tsx 中的toggleRawEditorCommand。frontmatter 的字段规范可参考 frontmatter-fields.md 与 file-layout.md。另外注意H1 是编辑器中唯一的标题表面ADR-0068正文标题即笔记的显示标题untitled 笔记是否在保存时按首个 H1 自动重命名由安装级设置initial_h1_auto_rename_enabled控制默认启用。九、深入Markdown ↔ 块的无损往返管线富文本编辑器的地基是 ADR-0022 记录的 Markdown 往返管线理解它有助于判断什么时候该放心用富文本、什么时候该切 Raw 模式Markdown → 块splitFrontmatter()→preProcessWikilinks()→tryParseMarkdownToBlocks()→injectWikilinks()块 → MarkdownblocksToMarkdownLossy()→postProcessWikilinks()→ 重新拼接 frontmatter。由于 wikilink[[...]]并非标准 Markdown往返过程中使用占位 token‹/›U2039 / U203A避免与 Markdown 语法冲突。正是因为存在这条串行化再解析的管线编辑器才能保证无论你在富文本里插入日期、表格、Callout、代码块还是高亮切到 Raw 模式看到的永远是规整、可移植的 Markdown同理外部编辑、git 同步后的文件也能在打开时被可靠地还原成块结构。仓库还为此维护了 BlockNote core/react 补丁 与 prosemirror-tables 补丁以修正第三方依赖在表格与块序列化上的边界问题。十、继续深入富文本编辑器支持的完整能力集wikilink、表格、Mermaid 图、LaTeX 数学、沙箱 HTML 块、白板等见 editor 概念文档全部快捷键清单见 keyboard-shortcuts.md网页捕获与媒体预览见 Use Media Previews长文档导航见 Use The Table Of Contents想在真实笔记中验证 Callout、折叠、高亮等语法可直接查看仓库自带的示例 vaultdemo-vault-v2含各类带 frontmatter 的 Markdown 笔记。实践建议把折叠 块选择 Raw 模式组合起来使用——日常写作在富文本模式下快速录入与重组保存前切一次 Raw 模式检查 frontmatter 与 Markdown 表示即可同时获得块编辑的效率和 Markdown 的持久性与可移植性。【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Tolaria 富文本编辑器实战指南：块级编辑、折叠、Callout 与 Markdown 无损往返
Tolaria 富文本编辑器实战指南块级编辑、折叠、Callout 与 Markdown 无损往返【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolariaTolaria 的富文本编辑器Rich Editor以块block为核心组织内容同时保证每条笔记底层始终是可移植的 Markdown 文件。本指南将完整讲解斜杠菜单插入、整块选择与移动、标题折叠、代码块、Callout、高亮与 Raw 模式等日常高频工作流并结合仓库源码解析其Markdown → 块 → Markdown无损往返的实现原理帮助你既写得快又随时保有对底层文件的完全控制。一、块级编辑与可移植 Markdown两种模式写同一个文件Tolaria 的编辑器设计遵循 ADR-0022以 BlockNote 作为富文本编辑器日常写作使用 BlockNote 驱动的富文本模式需要精确控制时切换到 CodeMirror 6 驱动的 Raw 模式。两种模式读写的是同一个 Markdown 文件不存在编辑器私有格式——这与 editor 概念文档 中Both modes write back to the same Markdown file的定位一致。由此带来两个关键特性块结构仅在编辑体验中存在标题折叠、整块移动等操作只改变编辑器的呈现不会向文件里写入私有折叠语法见下文折叠长章节。Markdown 是唯一事实源任何时刻切换到 Raw 模式看到的都是真正落盘的内容可被 git、其他工具或 AI 直接读取。从源码看整个编辑器的块模型在 src/components/editorSchema.tsx 中定义自定义的 wikilink 内联内容、Callout 块、代码块、高亮样式等均通过 BlockNote 的createReactBlockSpec/createReactInlineContentSpec注册这就是块与 Markdown 语法一一对应的基础。二、插入常用块斜杠菜单与 Todo 快捷键在空行输入/即可打开斜杠菜单Slash Menu。常用命令包括标题heading、列表bullet / numbered list、引用quote、分隔线divider待办块todo / check list代码块code block表格table当前日期date当前时间time斜杠菜单的实际实现位于 src/components/tolariaEditorFormattingConfig.ts其中日期与时间命令DATE_TIME_SLASH_COMMANDS的格式化逻辑值得注意日期输出YYYY-MM-DD时间输出HH:MM补零到两位而日期时间命令则输出YYYY-MM-DD HH:MM见formatLocalDateTime。菜单项还支持别名例如today、clock、timestamp等便于快速检索。快捷键macOS / Windows·Linux作用CmdT/CtrlT在当前块段落 ↔ 待办之间切换/空行打开斜杠菜单三、选择与移动整块块级结构操作的快捷键体系编辑状态下按Esc即可选中当前块进入块选择模式。该模式下Up/Down移动选中光标在块之间跳转ShiftUp/ShiftDown扩展选中范围多块Enter退出块选择回到文本编辑CmdShiftUp/CmdShiftDownmacOS或CtrlShiftUp/CtrlShiftDownWindows/Linux移动选中的块复制、剪切、粘贴、删除均作用于被选中的整块。特别地折叠状态下标题下的隐藏内容会随标题一起复制、剪切、删除或移动——这意味着你可以在大纲级别重组文档而不必先展开再手动调整每一行。整套快捷键与 keyboard-shortcuts.md 参考文档 中Rich Editor Shortcuts一节一一对应跨平台差异源于 macOS、Linux、Windows 对键位组合的保留策略不同因此 Tolaria 刻意按平台提供不同绑定并使用命令面板CmdK/CtrlK作为当前命令集的权威来源。四、折叠长章节纯展示层操作不改写文件标题可以隐藏其下方直到同级或更高级标题之前的所有内容。两种触发方式点击标题旁的展开/收起控件disclosure control选中标题块后按CmdEnter/CtrlEnter。关键设计折叠只是编辑器的展示状态Tolaria 不会向 Markdown 文件中写入任何私有折叠语法。因此折叠/展开不会污染文件内容也不会影响 git diff 的整洁度而折叠时标题下隐藏的内容在块选择操作复制/剪切/删除/移动中仍会作为一个整体被携带两者配合可用于快速重组长文档。五、编写代码块围栏语法与语言高亮创建代码块有三种方式从斜杠菜单选择代码块直接输入三反引号围栏后按Enter使用快捷键CmdShiftBacktickmacOS/CtrlShiftBacktickWindows/Linux将当前块转换为代码块。创建后可通过代码块控件选择语言以启用语法高亮。行号仅为展示层信息不会写入笔记文件。关于语法高亮的具体实现可参考 ADR-0134直接注册 Shiki 语言 与编辑器源码中的代码块选项配置src/components/codeBlockOptions.ts。代码块相关的复制控件与语言选择控件分别位于 src/components/codeBlockCopyControls.tsx 和 src/components/codeBlockLanguageControls.tsx仓库还为此维护了 blocknote/code-block 补丁。六、CalloutObsidian 风格与 GitHub Alert 双语法兼容Tolaria 将 Obsidian 风格 Callout 和 GitHub Alert 语法渲染为可编辑块同时保留底层 Markdown 原样。基础写法 [!NOTE] Local-first This note stays readable outside Tolaria.Callout 类型后加或-可控制初始折叠状态 [!TIP]- Optional details This callout starts collapsed.Callout 正文在富文本模式下可直接编辑而类型、标题或初始折叠标记的修改则需要切到 Raw 模式进行。从源码看Callout 的实现非常完整解析逻辑在 src/utils/calloutMarkdown.ts标记正则CALLOUT_MARKER为/^\[!([a-z][a-z0-9_-]*)\](?![-])[ \t]*(.*)$/iu——它捕获[!type]后的可选标题并明确排除紧跟/-的折叠标记折叠状态由另一路径单独处理块渲染在 src/components/CalloutBlock.tsxpropSchema中calloutType默认值为notetitle默认为空渲染为aside classtolaria-callout ...按类型家族着色并附图标图标映射见 src/components/calloutIcons.ts斜杠菜单中提供完整的 Callout 类型集note、tip、warning、danger、info、question、success、abstract、example、failure、bug、quote、todo本地化标题通过 i18n 注入见 src/components/singleEditorSuggestionItems.tsx 的useSlashMenuItems。若未指定标题Callout 头部会按类型自动生成可读标题calloutHeadingnote显示默认标题my-type会变成My Type保证任何类型都有清晰的可视化呈现。七、高亮文本以记号持久化选中文本后使用格式化工具栏或按CmdShiftMmacOS/CtrlShiftMWindows/Linux即可应用/取消高亮。Tolaria 将高亮保存为标准的highlighted textMarkdown 记号因此高亮在文件层是普通 Markdown可在任意编辑器中保留语义。值得补充的是Tolaria 的高亮还支持多种颜色见 src/utils/markdownHighlightMarkdown.ts 中的MARKDOWN_HIGHLIGHT_COLOR_OPTIONS——默认黄色text另有绿色、红色、蓝色、紫色变体分别以、、、等字符作为 Markdown 前缀标记从而在不破坏纯 Markdown 可移植性的前提下实现彩色高亮。八、检查 MarkdownRaw 模式与前端 YAML 修复按Cmd\macOS/Ctrl\Windows/Linux可在富文本与 Raw 模式间切换。Raw 模式适合查看 Markdown 的确切表示验证块结构与实际落盘内容一致编辑 YAML frontmatter修改 Callout 的标记类型、标题、折叠标记修复异常粘贴产生的脏内容。Raw 模式的核心价值之一是无效 YAML frontmatter 会被高亮显示你可以直接定位结构性问题所在而无需猜测解析在哪一行失败。从编辑器结构看Raw 模式与富文本模式共享同一份文件状态切换入口也出现在面包屑栏BreadcrumbBar的 Raw editor / Back to editor 按钮上见 src/components/BreadcrumbBar.tsx 及其测试命令面板同样提供该命令src/App.tsx 中的toggleRawEditorCommand。frontmatter 的字段规范可参考 frontmatter-fields.md 与 file-layout.md。另外注意H1 是编辑器中唯一的标题表面ADR-0068正文标题即笔记的显示标题untitled 笔记是否在保存时按首个 H1 自动重命名由安装级设置initial_h1_auto_rename_enabled控制默认启用。九、深入Markdown ↔ 块的无损往返管线富文本编辑器的地基是 ADR-0022 记录的 Markdown 往返管线理解它有助于判断什么时候该放心用富文本、什么时候该切 Raw 模式Markdown → 块splitFrontmatter()→preProcessWikilinks()→tryParseMarkdownToBlocks()→injectWikilinks()块 → MarkdownblocksToMarkdownLossy()→postProcessWikilinks()→ 重新拼接 frontmatter。由于 wikilink[[...]]并非标准 Markdown往返过程中使用占位 token‹/›U2039 / U203A避免与 Markdown 语法冲突。正是因为存在这条串行化再解析的管线编辑器才能保证无论你在富文本里插入日期、表格、Callout、代码块还是高亮切到 Raw 模式看到的永远是规整、可移植的 Markdown同理外部编辑、git 同步后的文件也能在打开时被可靠地还原成块结构。仓库还为此维护了 BlockNote core/react 补丁 与 prosemirror-tables 补丁以修正第三方依赖在表格与块序列化上的边界问题。十、继续深入富文本编辑器支持的完整能力集wikilink、表格、Mermaid 图、LaTeX 数学、沙箱 HTML 块、白板等见 editor 概念文档全部快捷键清单见 keyboard-shortcuts.md网页捕获与媒体预览见 Use Media Previews长文档导航见 Use The Table Of Contents想在真实笔记中验证 Callout、折叠、高亮等语法可直接查看仓库自带的示例 vaultdemo-vault-v2含各类带 frontmatter 的 Markdown 笔记。实践建议把折叠 块选择 Raw 模式组合起来使用——日常写作在富文本模式下快速录入与重组保存前切一次 Raw 模式检查 frontmatter 与 Markdown 表示即可同时获得块编辑的效率和 Markdown 的持久性与可移植性。【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
