README file from
GithubA outline
简介
A outline 是一个 Obsidian 插件。它把块引用渲染成行内文本，并让光标在列表里的移动更符合直觉。
插件提供四类能力：
- 行内块引用：引用与前后文字同行显示，源块修改后自动刷新。
- 块搜索：输入
@加关键词，从整个库里找到块，并插入块链接。 - 块 id 保护：隐藏行尾的
^id，并防止回车、退格键弄丢它。 - 光标与位置：Roam 式的光标移动，重新打开文件时回到上次的位置。
插件不联网，不收集数据。桌面端和移动端都可以使用。
快速上手
- 安装并启用插件，步骤见“安装”。
- 在任意笔记里输入
@和关键词，选中一个块，按Enter。 - 插件插入块链接，例如
[[笔记名#^abc123]]。它还会把这个 id 写入原块所在的笔记。 - 链接显示为行内引用。按住
Shift点击它，右侧分栏会打开原块。
基础
前置条件
- Obsidian 1.8.7 或更高版本。插件在 Obsidian 1.13.7 上测试过。
安装
从社区插件市场安装（上架后可用）：
- 打开“设置 → 第三方插件”，关闭安全模式。
- 点击“浏览”，搜索“A outline”。
- 点击“安装”，再点击“启用”。
手动安装：
- 从本仓库的 Releases 页面下载三个文件：
main.js、manifest.json和styles.css。 - 在库里创建目录
.obsidian/plugins/a-outline/。把这三个文件放进去。 - 重启 Obsidian，在“第三方插件”里启用“A outline”。
配置
下表列出每个设置项的默认状态。
| 设置项 | 默认 | 作用 |
|---|---|---|
| 行内块引用 | 开 | 把 [[笔记#^块]] 渲染为行内文本 |
| 引用带待办状态（实验） | 关 | 引用任务行时显示复选框，点击直接修改原任务行 |
| Shift+点击跳转原文 | 开 | 按住 Shift 点击引用，打开原块 |
| 打开文件时预热扫描（实验） | 关 | 先测量全文行高，减少长文件的滚动跳动 |
| @ 唤起全库块搜索 | 开 | 输入 @ 搜索块并插入块链接 |
| 隐藏块 id | 开 | 隐藏行尾的 ^id，并启用块 id 保护 |
| Roam 式光标 | 开 | 上下移动和回车时，光标停在内容起点或行尾 |
| 块引用计数 | 关 | 在块的右侧显示被引用的次数 |
| 右键菜单：复制块链接/嵌入 | 开 | 在编辑器右键菜单里加入两个复制项 |
| 记住光标与滚动位置 | 开 | 重新打开文件时回到上次的位置 |
引用的外观可以用 CSS 片段微调。插件提供两个变量：
| 变量 | 作用 |
|---|---|
--oo-ref-color |
引用文字的颜色 |
--oo-ref-bg-alpha |
引用底色的透明度 |
使用
行内块引用
块链接 [[笔记#^块id]] 和块嵌入 ![[笔记#^块id]] 都渲染成行内文本。引用与前后文字同行，自然折行，行高不变。阅读视图和实时预览都生效。
引用的显示规则如下：
- 引用列表项时，只显示这一行，不含子项。
- 引用带 id 的标题时，只显示标题文字。
- 源块修改后，引用自动刷新。
- 目标不存在时，引用显示为灰色虚线，不能跳转。
- 嵌套引用最多显示 2 层。
引用的操作方式如下：
- 单击引用：光标进入链接代码，可以直接修改链接。
Shift+ 单击：在右侧分栏打开原块（仅桌面端）。Shift+Cmd或Ctrl+ 单击：在新标签页打开原块。
块搜索和块链接
在任意位置输入 @，再输入关键词，就能搜索整个库的块。@ 可以紧接在文字后面。为了不干扰邮箱地址，有一种情况不弹窗：@ 前是字母、数字或邮箱符号，且 @ 后已出现英文句点。
关键词最长 40 个字符，不能含空格。候选列表显示块的文本、文件路径和行号。按 Enter 插入块链接。
目标块没有 id 时，插件会生成一个 id，写入目标笔记。
只输入 @ 不加关键词时，列表显示被引用次数最多的块。还没有块被引用过时，列表显示最近修改的文件里的块。没有匹配的块时，弹窗显示“没有匹配的块”。
三个命令可以绑定快捷键：
- “复制当前块的块链接（无 id 自动生成）”。
- “复制当前块的块嵌入（无 id 自动生成）”。
- “插入 @ 块搜索”，方便加入移动端工具栏。
编辑器右键菜单也提供前两项。
块 id 保护
Obsidian 只认段落最后一行行末的 id。隐藏 id 之后，光标可能停在它之前或之后。一次回车或退格，就会让它露出、丢失或失效。
开启“隐藏块 id”后，插件处理三种按键：
Enter：把 id 留在原段落，新内容另起一段。Backspace和Delete：删除或合并两行时，把 id 移到合并后段落的末行。- 两行都带 id 时：阻止合并，并弹出提示。
输入法组合中、有选区、在代码块或公式里，插件不介入。
光标与位置
Roam 式光标的规则如下：
- 光标在内容起点时，上下键把光标移到相邻行的内容起点。内容起点指列表符号或待办框之后。
- 光标在行尾时，上下键把光标移到相邻行的行尾。行尾有隐藏 id 时，停在 id 之前。
- 在内容起点按
Enter，光标进入新空出的一行。
“记住光标与滚动位置”在关闭或切换文件时记录位置，重新打开文件时恢复。重启 Obsidian 后，已打开的标签页同样恢复。位置保存在本机，不随同步走。通过前进后退、标题链接、块链接或搜索结果打开的文件，不受影响。
常见问题
块 id 看不见，怎么查看？
关闭设置“隐藏块 id”。
引用显示为灰色虚线，是什么原因？
目标笔记或目标块不存在，或者块 id 被改动过。
输入 @ 后没有弹窗，怎么办？
检查三点：设置“@ 唤起全库块搜索”已开启；当前在编辑模式，阅读视图不响应；@ 后面没有输入英文句点，也不是连续的两个 @。
和其他插件冲突怎么办？
另一个插件可能也接管块嵌入的渲染，或者改写列表里的回车键。这时两者的行为会叠加。请在其中一个插件里关闭对应功能。
插件会联网吗？
不会。插件不发送任何网络请求，也不收集数据。
插件会修改我的笔记吗？
只在三种情况下修改：
- 用
@搜索或复制块链接时，给没有 id 的目标块补上 id。 - 开启“引用带待办状态”后，点击引用里的复选框，修改原任务行。
- 块 id 保护合并两行时，移动 id 的位置。
设置和位置记录保存在哪里？
设置保存在插件目录的 data.json。光标和滚动位置保存在本机的 localStorage。
附录
已知限制
- 界面文字目前只有中文。
- 嵌套引用最多显示 2 层，循环引用显示为省略号。
- 记住位置按行号记录。文件在别处被修改后，位置可能偏移。
- 插件为编辑器打开文件的流程打了补丁。它还调用了 Obsidian 的全局搜索内部接口。Obsidian 大版本更新后，这些功能可能失效。
更新日志
1.0.2：只保留块引用与光标相关功能。移除大纲外观、缩进参考线、标题徽标、文件树参考线、日记流以及其他主题选项。
1.0.1：@ 块搜索可以直接接在文字后面，并对邮箱地址做了防误触。
1.0.0：首个公开版本。
反馈
请在本仓库的 Issues 页面提交问题。请附上 Obsidian 版本、操作系统和复现步骤。
许可证
MIT，详见 LICENSE 文件。