# A outline

[English](README.en.md)

## 简介

A outline 是一个 Obsidian 插件。它把块引用渲染成行内文本，并让光标在列表里的移动更符合直觉。

插件提供四类能力：

- 行内块引用：引用与前后文字同行显示，源块修改后自动刷新。
- 块搜索：输入 `@` 加关键词，从整个库里找到块，并插入块链接。
- 块 id 保护：隐藏行尾的 `^id`，并防止回车、退格键弄丢它。
- 光标与位置：Roam 式的光标移动，重新打开文件时回到上次的位置。

插件不联网，不收集数据。桌面端和移动端都可以使用。

## 快速上手

1. 安装并启用插件，步骤见“安装”。
2. 在任意笔记里输入 `@` 和关键词，选中一个块，按 `Enter`。
3. 插件插入块链接，例如 `[[笔记名#^abc123]]`。它还会把这个 id 写入原块所在的笔记。
4. 链接显示为行内引用。按住 `Shift` 点击它，右侧分栏会打开原块。

## 基础

### 前置条件

- Obsidian 1.8.7 或更高版本。插件在 Obsidian 1.13.7 上测试过。

### 安装

从社区插件市场安装（上架后可用）：

1. 打开“设置 → 第三方插件”，关闭安全模式。
2. 点击“浏览”，搜索“A outline”。
3. 点击“安装”，再点击“启用”。

手动安装：

1. 从本仓库的 Releases 页面下载三个文件：`main.js`、`manifest.json` 和 `styles.css`。
2. 在库里创建目录 `.obsidian/plugins/a-outline/`。把这三个文件放进去。
3. 重启 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` 文件。