Tolaria 富文本编辑器详解：块级编辑、斜杠菜单、Callout 块与原始 Markdown 校验

Tolaria 富文本编辑器详解：块级编辑、斜杠菜单、Callout 块与原始 Markdown 校验

【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria

Tolaria 的富文本编辑器基于 BlockNote 实现块级（block-based）编辑，同时保证笔记始终是可移植的 Markdown 文件——所见即所得的操作不会污染底层文件。本文以官方指南 Use The Rich Editor 为核心骨架，逐条展开斜杠菜单、块选择与移动、章节折叠、代码块、Callout、高亮与原始模式这七类工作流，并结合仓库源码说明每个功能在实现层是如何落地的，读完即可熟练使用该编辑器的全部交互并理解其“富文本操作不落私货”的设计边界。

编辑器的定位：块级编辑，Markdown 为唯一事实

Tolaria 的富文本编辑器让你在 BlockNote 的块模型上编辑，但保存下来的文件依旧是标准 Markdown。这一分工由架构决策记录 0022-blocknote-rich-text-editor.md 确立，并在指南中反复体现：折叠章节只改变编辑器展示而不写入私有折叠语法、代码行号只用于呈现而不落盘、高亮以标准双等号语法保存。换言之，所有“富交互”都被设计为表现层状态，离开 Tolaria 后文件仍然可读、可迁移。

用斜杠菜单快速插入常用块

在空行输入/打开斜杠菜单，可插入：

• 标题、列表、引用、分隔线
• Todo 块
• 代码块
• 表格
• 当前日期
• 当前时间

斜杠菜单不是简单的列表渲染。从 TolariaSlashMenu.tsx 的源码可以看到它支持两级子菜单：带submenuItems的条目会在右侧以 Portal 浮层展开（见 TolariaSlashMenu.tsx#L197-L241），并且菜单项按group字段分组显示标签。菜单还支持完整的纯键盘导航：ArrowRight打开子菜单、ArrowLeft/Esc关闭、ArrowUp/ArrowDown在子菜单内循环移动、Enter选中当前项，相关分派逻辑集中在 submenuKeyboardAction 函数。这意味着你从输入/到插入块可以全程不碰鼠标。

此外，指南还提供了一个不走菜单的快捷方式：在 macOS 上使用Cmd+T、在 Windows/Linux 上使用Ctrl+T，可将当前块在段落与 Todo 之间切换（快捷键全集见 Rich Editor Shortcuts）。

选择并移动整个块

编辑状态下按Esc选中当前块；选中态激活时：

• Up/Down：移动选区到相邻块
• Shift+Up/Shift+Down：扩展选区
• Enter：返回文本编辑
• Cmd+Shift+Up/Cmd+Shift+Down（macOS）或Ctrl+Shift+Up/Ctrl+Shift+Down（Windows/Linux）：上下移动已选块
• 复制、剪切、粘贴、删除均作用于所选块

一个值得注意的细节：标题下已折叠的内容在复制、剪切、删除或移动时会跟随标题一起迁移，不会出现“搬走了标题却把正文丢在原处”的孤儿内容。

除键盘外，块也可以通过拖拽移动。这里有一段工程背景：BlockNote 默认的块拖拽依赖 HTML5 拖拽事件与DataTransfer，在 Tauri 的 macOS webview 里会与原生文件/图片拖放冲突。因此 ADR 0107 决定由 Tolaria 自己用指针手势实现块重排——拖拽侧边菜单负责解析当前块、计算指针命中位置、渲染移动中的块预览与插入分隔线，而DataTransfer通道完全留给文件、图片和 wikilink 的外部拖放。从源码结构看，这也是为什么移动块时有独立的预览效果和插入指示线：它们是由 Tolaria 自绘的拖拽辅助，而非浏览器默认行为。

折叠长章节

标题可以隐藏其下方内容，直到下一个同级或更高级别的标题。两种触发方式：

1. 点击标题旁的折叠控件（disclosure control）；
2. 选中标题块后按Cmd+Enter（macOS）或Ctrl+Enter（Windows/Linux）。

快捷键参考页对该条目的完整表述是“折叠或展开所选标题或列表的章节”（见 keyboard-shortcuts.md），即列表章节同样支持折叠。关键保证是：折叠只改变编辑器内的呈现，Tolaria 不会向 Markdown 文件写入任何私有折叠标记——展开状态属于编辑器会话，而不是文件内容。

编写代码块

创建代码块有三种等价方式：

• 斜杠菜单选择代码块；
• 直接输入三反引号围栏（```）后按Enter；
• 快捷键Cmd+Shift+反引号（macOS）/Ctrl+Shift+反引号（Windows/Linux）。

创建后，通过代码块左上角的语言选择控件挑选语言以启用语法高亮；行号仅用于呈现，不会写入笔记。

实现上，CodeBlockLanguageControls 用MutationObserver监听编辑器 DOM，找到每个原生代码块语言下拉框后，在 document.body 上以 Portal 覆盖层 渲染自绘的 Shadcn 风格下拉菜单（选项来自createTolariaCodeBlockOptions().supportedLanguages）。选择语言时调用 updateCodeBlockLanguage：

editor.updateBlock(blockId, { props: { language } })

语言被更新为 BlockNote 块的一个 prop，序列化时即对应围栏后的语言标识（```ts），因此高亮语言选择最终仍然落回标准 Markdown 语法。

添加 Callout

Tolaria 将 Obsidian 风格 callout 和 GitHub 告警语法渲染为可编辑块，同时完整保留 Markdown。基础形式：

> [!NOTE] Local-first > This note stays readable outside Tolaria.

在 callout 类型后追加+或-可指定初始折叠状态：

> [!TIP]- Optional details > This callout starts collapsed.

其中-表示初始折叠。callout 正文在富文本模式下可直接编辑；若要修改 callout 类型、标题或初始折叠标记，则切到原始模式编辑。

源码侧，callout 是一个注册到 BlockNote 的自定义块，定义见 CalloutBlock.tsx#L12-L19：

const CALLOUT_BLOCK_CONFIG = { type: CALLOUT_BLOCK_TYPE, propSchema: { calloutType: { default: 'note' }, title: { default: '' }, }, content: 'inline', } as const

即calloutType与title是块属性（未指定时类型默认note、标题为空），内容由resolveCalloutDefinition解析出配色家族，最终渲染为带图标与标题栏的<aside>（见 CalloutBlockView）。这解释了为什么 callout 既能像普通块一样选中、拖动、折叠，又能在保存时逐字还原为> [!TYPE] Title的引用块语法。

高亮文本

选中文字后使用浮动格式化工具栏，或按Cmd+Shift+M（macOS）/Ctrl+Shift+M（Windows/Linux）。Tolaria 将高亮保存为==highlighted text==——这是写在源码里的持久化约定：格式化工具栏中高亮按钮的次要提示文本就是==highlight==（见 basicTextStyleCopy）。

顺带说明工具栏的完整能力：TolariaFormattingToolbar 在 BlockNote 默认工具栏基础上做了定制——加粗、斜体、删除线、行内代码四个基础样式按钮均标注“persists in markdown”，并额外插入行内代码与高亮两个按钮（insertExtraTextStyleButtons），还把块类型下拉换成自绘的TolariaBlockTypeSelect，可直接把选中块转换为其他类型。工具栏还有 160ms 的关闭宽限期与视口钳制中间件，避免鼠标移向工具栏途中它提前消失或溢出屏幕。

用原始模式核对 Markdown

按Cmd+\（macOS）或Ctrl+\（Windows/Linux）切换原始模式（raw mode）。原始模式适合：

• 核对确切的 Markdown 表示；
• 编辑 YAML frontmatter；
• 修改 callout 标记；
• 修复粘贴进来的异常内容。

指南强调：无效的 YAML frontmatter 会被高亮标出，让你不用靠猜就能定位解析失败的位置。这一点由 frontmatterHighlight.ts 落实——它是一个 CodeMirrorViewPlugin，先通过首尾---界定 frontmatter 范围，再为分隔符、键、值分别施加装饰，最后调用decorateYamlErrors把语法错误行标记为cm-frontmatter-error装饰（见 frontmatterHighlight.ts#L5-L33）。也就是说错误定位是逐行、确定性的，而不是整段泛红。

快捷键速查（富文本编辑器）

以下汇总指南与 快捷键参考页 中“富文本编辑器拥有焦点时”生效的条目：

由于 macOS、Linux、Windows 各自保留了不同的按键组合，具体按键以 keyboard-shortcuts.md 的对照表为准。

延伸阅读

• 原始指南：Use The Rich Editor
• 完整快捷键表：Keyboard Shortcuts
• 网页抓取与文件预览：Use Media Previews
• 长笔记导航：Use The Table Of Contents
• 块重排的实现决策：ADR 0107 Pointer-owned editor block reordering

【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria