[![English](https://img.shields.io/badge/Language-English-blue)](README.md)
[![简体中文](https://img.shields.io/badge/Language-简体中文-red)](README.zh-CN.md)


# Side Comments origin

一款适用于 Obsidian 的本地、非侵入式侧栏批注插件。选中 Markdown 笔记中的文字后，
可以添加视觉标记和独立的 Markdown 批注，无需向原笔记插入额外语法。

- **官方网站：** [peyote.info](https://peyote.info/)
- **当前版本：** [v1.0.10](https://github.com/jepicaju862-lab/Side-Comments-origin/releases/tag/1.0.10)


## 🌟 功能

### ✍️ 文字批注与视觉标记

- 选中 Markdown 笔记中的文字并添加独立批注。
- 支持四种视觉样式：**高亮、下划线、删除线、加粗**。
- 每条批注可使用五种预设色之一，也可以选择自定义颜色。
- 精确选中已有批注时识别并编辑原批注，避免重复创建。
- 编辑视图和阅读视图都会显示视觉标记。

四种样式仅用于视觉表达。v1.0.4 不增加笔记、疑问、待办、警告等语义类型，也不增加
“已解决”状态。

### 🛠️ 选区工具栏

- 在编辑视图中选择文字后自动显示浮动工具栏。
- 直接选择视觉样式、颜色，或打开批注编辑窗口。
- 重新选择已有批注时回显原样式和颜色。
- 可以在设置中关闭选区工具栏。

也可以通过右键菜单、命令面板或自定义快捷键创建批注。

### 👁️ 编辑视图与阅读视图

| 操作 | 编辑视图 | 阅读视图 |
| :--- | :--- | :--- |
| 单击标记 | 定位对应的侧栏卡片 | 定位对应的侧栏卡片 |
| 双击标记 | 打开批注编辑窗口 | 打开批注编辑窗口 |
| 悬停标记 | 显示简洁提示 | 预览批注内容和快捷操作 |
| 修饰键点击链接 | 保留编辑器原有行为 | 保留链接正常打开行为 |

无论从哪个入口打开批注，都会复用同一个编辑窗口。v1.0.4 已修复双击一条批注时可能
同时打开多个批注窗口的问题。

### 💬 悬浮预览

- 在阅读视图中悬停标记，预览渲染后的批注内容。
- 支持 Markdown、链接和嵌入图片。
- 快捷操作可以打开侧栏或编辑批注。

### 📑 侧栏批注管理

专用的 **Side Comments View** 会跟随当前 Markdown 笔记。

- 以卡片形式查看批注并跳转到原文。
- 搜索当前笔记中的引用文本与批注正文。
- 按正文位置或创建时间排序。
- 一键折叠或展开全部批注正文。
- 编辑、复制精确回链、在库中搜索或删除批注。
- 删除后七秒内撤销。
- 通过样式图标和颜色边线快速识别批注。

### 🖼️ Markdown 与图片

- 批注正文支持 Markdown。
- 可以把图片直接粘贴到批注编辑窗口。
- 图片保存在 vault 内可配置的附件文件夹。
- 编辑窗口支持拖动、文本框自动增高和关闭后的焦点恢复。

### 📤 导出与备份

- 把当前笔记的全部批注导出为 Markdown 摘要。
- 复制包含引用、批注正文和 `obsidian://sidenote` 跳转地址的精确 Obsidian Callout 回链。
- 把当前 Markdown 笔记导出为 `.docx`，将仍可定位的批注保留为 Word 原生批注。
- 创建独立 Markdown 备份，便于长期保存与同步。

### 🧭 文本跟踪与孤立批注

插件综合使用正文位置、绝对偏移量、选中文本及其 SHA-256 哈希、标题路径、重复文本序号
与上下文重新定位批注。

- 原文移动后尽可能重新匹配并更新坐标。
- 只有无法可靠找到原文时，批注才会变为孤立批注。
- 设置页会显示孤立批注数量并提供批量清理。

### ⌨️ 无障碍与移动端

- 侧栏卡片与菜单支持键盘操作。
- 移动端编辑窗口始终限制在可视区域内。
- 样式、颜色与菜单按钮采用触控友好尺寸。
- 窄屏下选区工具栏可以横向滚动。
- 支持长按选择文字后的命令与选区工具栏流程。

---

## 📥 安装

### 方式一：社区插件

插件进入官方社区插件目录后：

1. 打开 Obsidian“**设置 → 第三方插件**”。
2. 点击“**浏览**”并搜索 **Side Comments origin**。
3. 点击“**安装**”，然后启用插件。

### 方式二：手动安装

1. 从 [GitHub Releases 页面](https://github.com/jepicaju862-lab/Side-Comments-origin/releases)
   下载最新版本。
2. 把以下文件复制到插件目录：
   - `main.js`
   - `manifest.json`
   - `styles.css`
3. 最终目录应为：

```text
<vault>/.obsidian/plugins/side-comments-origin/
```

4. 重新加载 Obsidian。
5. 在“**设置 → 第三方插件**”中启用 **Side Comments origin**。

---

## 🖊️ 使用

### 添加批注

1. 在 Markdown 编辑视图中选中一段文字。
2. 在选区工具栏选择视觉样式和颜色。
3. 需要填写 Markdown 内容时打开批注编辑窗口。
4. 点击“添加”，或按 `Ctrl/Cmd + Enter` 保存。

### 打开批注侧栏

在命令面板中执行以下任一命令：

- **在侧边栏打开批注视图**
- **在分屏中打开批注视图**

在侧栏中，单击卡片定位对应原文，双击卡片编辑批注。其他操作位于卡片菜单中。

### 粘贴图片

批注编辑窗口获得焦点时，使用 `Ctrl+V` / `Cmd+V` 粘贴截图或图片。图片会保存到
配置的附件文件夹，并通过 Markdown 语法链接。

### 导出批注

使用侧栏中的导出操作生成 Markdown 摘要，其中包含原始引用、批注正文和结构化 Callout。

---

## ⌨️ 键盘快捷键

### 批注编辑窗口

| 按键 | 操作 |
| :--- | :--- |
| `Ctrl/Cmd + Enter` | 保存批注 |
| `Esc` | 关闭窗口 |
| `←` / `→` | 切换视觉样式 |
| `Home` / `End` | 跳到第一个或最后一个样式 |

### 侧栏

| 按键 | 操作 |
| :--- | :--- |
| `Tab` | 聚焦批注卡片或操作按钮 |
| `Enter` / `Space` | 定位当前批注对应的正文 |
| `F2` | 编辑当前批注 |
| `↑` / `↓` | 在批注操作菜单中移动 |
| `Home` / `End` | 跳到菜单首项或末项 |
| `Esc` | 关闭菜单并返回触发按钮 |

---

## ⚙️ 设置

| 设置 | 说明 |
| :--- | :--- |
| **批注排序** | 按正文位置或创建时间排列侧栏批注 |
| **显示批注标记** | 同时控制编辑视图和阅读视图中的视觉标记 |
| **启用选区工具栏** | 控制选择文字后是否显示快速工具栏 |
| **新批注默认颜色** | 仅影响之后创建的批注 |
| **标记透明度** | 调整视觉标记透明度 |
| **Markdown 批注备份文件夹** | 默认 `side-note-comments` |
| **批注附件文件夹** | 默认 `side-note-attachments` |
| **批注数据文件夹** | 默认 `side-note-data`，修改后需要重新加载插件 |
| **创建 Markdown 备份** | 手动生成批注备份文件 |
| **孤立批注** | 查看并批量删除无法定位的批注 |

---

## 🔒 数据与隐私

- 批注默认按笔记保存为 `side-note-data` 中的 JSON 文件。
- 插件设置和旧版迁移状态保存在 `data.json`。
- 粘贴的图片默认保存在 `side-note-attachments`。
- 手动创建的 Markdown 备份默认保存在 `side-note-comments`。
- 仅在你主动粘贴图片或复制批注回链时访问剪贴板；插件不会在后台监控剪贴板。
- 所有文件夹都位于 vault 内，并可以在设置中修改。
- 笔记重命名时会同步更新批注引用。
- 插件代码不会发起网络请求。

### 向后兼容

- 旧批注没有 `markType` 时按高亮显示。
- 旧批注没有独立颜色时使用插件默认颜色。
- 旧版 `data.json` 中的批注会迁移到按笔记保存的 JSON 文件。
- v1.0.4 不改变现有批注含义。

重大升级前，建议备份整个 vault，或至少备份批注数据文件夹。

---

## ❓ 常见问题

### 阅读视图可以显示和编辑批注吗？

可以。阅读视图会渲染视觉标记。单击标记定位侧栏卡片，双击进入编辑，悬停则预览
批注内容和快捷操作。

### 可以修改已有批注的样式和颜色吗？

可以。从正文标记或侧栏卡片打开编辑窗口，然后选择其他视觉样式、预设颜色或自定义颜色。

### 为什么删除原文后批注仍然存在？

批注数据与 Markdown 独立保存。无法再找到原文时，批注会变为孤立批注，可以在设置中清理。

### 为什么双击一条批注会打开很多编辑窗口？

这是重复事件处理引起的问题，已在 v1.0.4 修复。现在同一时间只会保留一个批注编辑窗口。

### 批注数据保存在哪里？

默认按笔记保存为 vault 内 `side-note-data` 文件夹中的 JSON 文件，可以在设置中修改目录。

---

## 🧑‍💻 开发

```bash
npm install
npm run build
```

生产构建会先运行 TypeScript 检查，再把 `main.js` 写入仓库根目录。

## 📋 版本说明

v1.0.4 增加阅读视图交互、四种视觉标记、每条批注独立颜色、选区工具栏、统一编辑窗口、
侧栏工作流增强、Word 导出、Markdown 备份、附件、精确回链、移动端与无障碍修复，并修复
多批注窗口问题。

完整变更请参阅 [RELEASE_NOTES.zh-CN.md](RELEASE_NOTES.zh-CN.md)。

---

## 🤝 支持与反馈

- **Bug 反馈——[本仓库的 issue][issues]。** 请尽量附上 Obsidian 版本、操作系统、
  一个可复现问题的最小 Markdown 笔记，以及 `side-note-data` 中对应的批注 JSON。
- **使用问题与交流——QQ 群 `1094620986`。** 群内使用简体中文交流。
- **邮件——<jepicaju862@gmail.com>。** 不方便公开的复现文件或其他内容可以通过邮件发送。
- **官方网站——[peyote.info](https://peyote.info/)。**

[issues]: ../../issues

---

## 📄 许可证

[GNU 通用公共许可证 v3.0](LICENSE)

---

## 🙏 致谢

本项目参考并吸收了多个优秀开源批注插件的设计思路：

- [HiNote](https://github.com/catmuse/HiNote)——行内批注交互、文档高亮流程和阅读笔记体验。
- [SideNote](https://github.com/mofukuru/SideNote)——侧栏批注管理、批注组织方式和交互设计。

感谢开源社区及所有贡献者分享的思路、实现与用户体验探索。

---

## 📬 联系方式

- **QQ 群：** `1094620986`
- **邮箱：** <jepicaju862@gmail.com>
- **官网：** [peyote.info](https://peyote.info/)