⌨️Obsidian 插件

觅思文档提供了一个 Obsidian 的插件——「Obsidian Mrdoc Plugin」，以实现 Obsidian 文档与觅思文档之间的同步。

- 为 Obsidian 用户提供了一个本地文档远程同步的新方案；
- 为 Obsidian 本地文档提供了一个 Web 在线浏览文档的新方案；
- 为觅思文档用户提供了一个离线编写、保存和同步文档的新方案；

## 系统要求

- 觅思文档专业版`v1.3.6+`、觅思文档开源版`v0.9.2+`
- Obsidian`v1.4.16`

## 基本概念的对应关系

- Obsidian 的「仓库（Vault）」，对应于觅思文档的「文集」；
- Obsidian 仓库内的「Markdown 文件」，对应于觅思文档中的「文档」；
- Obsidian 仓库内的「文件夹」对应于觅思文档中包含下级文档的「文档」；

## 插件规则

### 仓库（Vault）

Obsidian 需要在插件的设置页面选择对应觅思文档的目标文集。
> 如果希望文档同步到一个新的觅思文档文集，可点击「新建」按钮新建一个文集后选择。

### 拉取远程文档

插件在左侧工具栏上添加了一个功能图标按钮，用于从觅思文档上拉取文集内所有文档到 Obsidian 本地。点击拉取操作后，插件会获取已指定文集内所有文档的信息并准备写入到 Obsidian 本地。

- 如果本地不存在同名的文件/文件夹，则新建文件/文件夹；
- 如果本地已存在同名的文件，判断本地文件是否与远程文档存在映射关系：
	- 如果存在映射关系，比对本地文件和远程文档的最后修改时间：
		- 如果本地文件最后修改时间新于远程文档，跳过；
		- 如果本地文件最后修改时间旧于远程文档，将远程文档的内容覆盖写入本地文件。
	- 如果不存在映射关系，跳过。
- 如果本地已存在同名文件夹，跳过。

### 新建文件/文件夹

Obsidian 本地新建文件/文件夹，会自动在觅思文档指定的文集中创建一个文档，并在插件内维护一个本地文档与远程文档的映射关系；

### 重命名文件/文件夹

在 Obsidian 本地对文件/文件夹进行重命名，会自动修改觅思文档上对应的文档标题。

### 移动文件层级

在 Obsidian 本地对文件移动到不同的文件夹，会自动修改觅思文档上对应的文档上级。

### 修改文件

修改文件内容后，你可以在编辑器右上角的「更多选项」中点击「同步至 MrDoc」菜单将文档的更新推送到觅思文档。

你也可以在 Obsidian 软件的左侧文件列表中，鼠标停留在指定的文档上，点击鼠标右键，唤出上下文菜单后，点击「同步至 MrDoc」菜单将文档的更新推送到觅思文档。

除此之外，插件提供了一个**实时推送**的选项，你可以在插件的设置页面开启「实时更新文档内容」，这样，当你在 Obsidian 中修改了文件内容，插件会实时将最新的文件内容更新到觅思文档上。

### 删除文件/文件夹

如果 Obsidian 本地的文件/文件夹与觅思文档建立了映射关系，那么在本地删除文件/文件夹，插件也会同步将觅思文档内的文档进行删除（软删除，文档进入回收站）。

### 图片处理

对于图片的处理，插件提供了两个选项：

- 转存本地图片
- 转存粘贴板中的图片

**1、转存本地图片**

当你粘贴或拖拽本地图片到 Obsidian 编辑器内时，插件会将图片上传至觅思文档，然后返回觅思文档的图片链接地址并填入 Obsidian 编辑器。

**2、转存粘贴板中的图片**

当你在别处复制了文本要粘贴到 Obsidian 编辑器内时，插件会提取其中的图片链接，并将其上传至觅思文档，然后返回觅思文档的图片链接地址替换掉原文本中的图片链接。

### 重置映射关系

在 Obsidian 本地文件于觅思文档的文档建立了映射关系后，如果你需要接触其绑定的映射关系，可以在插件的设置页面点击「重置文档映射」，这样，对 Obsidian 本地文件的操作将不会同步至觅思文档。

## 使用教程

### 安装

1、官方安装（插件已提交官方审核）

2、通过 BRAT 安装（推荐）

打开设置 - 第三方插件 - 浏览 - 搜索 brat，下载安装并启用。

![](http://file.mrdoc.pro/mrdoc-oss/img/2024/01/13/2024-01-13_141843_4327490.5202977066532346.png)

打开 BRAT 设置

![](http://file.mrdoc.pro/mrdoc-oss/img/2024/01/13/2024-01-13_142242_5674970.06758126640853157.png)

点击 Add Beta plugin，会出现弹窗，填写下面的URL：

![](http://file.mrdoc.pro/mrdoc-oss/img/2024/01/13/2024-01-13_142421_9090860.15771273748072345.png)

```text
https://github.com/zmister2016/obsidian-mrdoc
```

点击 `Add Plugin`按钮，等待安装。出现如下信息，说明安装成功：

![](http://file.mrdoc.pro/mrdoc-oss/img/2024/01/13/2024-01-13_142630_4095570.6298625211202187.png)

在使用本插件之前，你需要进行一些配置。

### 配置连接信息

进入「MrDoc」插件配置页面，填写「MrDoc URL」和「用户 Token」（获取地址为：个人中心 -> 个人管理 -> Token 管理），点击「检查」按钮，测试连接是否成功。

![](http://file.mrdoc.pro/mrdoc-oss/img/2024/01/13/2024-01-13_143207_3133480.31309160613727405.png)

### 指定目标文集

配置连接信息成功后，你需要指定一个 MrDoc 的目标文集来与 Obsidian 仓库进行绑定。

点击「刷新」按钮，你可以获取到你的文集列表，随后可以从中选择一个文集。

![](http://file.mrdoc.pro/mrdoc-oss/img/2024/01/13/2024-01-13_143501_2242810.7894091310554345.png)

也可以点击「新建」按钮，新建一个空白的文集，然后从文集列表中选择它，作为 Obsidian 仓库的绑定。

![](http://file.mrdoc.pro/mrdoc-oss/img/2024/01/13/2024-01-13_143605_3274880.38229838785703185.png)

完成上述两个操作后，你在 Obsidian 仓库内新建、重命名、移动文档会同步创建到觅思文档。

### 拉取文档

如果你指定了一个 MrDoc 文集，但是 Obsidian 本地仓库内是空的，那么你可以将 MrDoc 文集内的文档拉取到 Obsidian 仓库内。

点击 Obsidian 主界面左侧栏的按钮，如图所示：

![](http://file.mrdoc.pro/mrdoc-oss/img/2024/01/13/2024-01-13_145450_6953330.026724187946916445.png)

在弹出的模态框中点击「确认」按钮，插件将从 MrDoc 中将指定文集中的文档拉取到 Obsidian。

![](http://file.mrdoc.pro/mrdoc-oss/img/2024/01/13/2024-01-13_145624_6138930.8678963723754145.png)

拉取完成后，会显示所有新建的文件夹和文档。

![](http://file.mrdoc.pro/mrdoc-oss/img/2024/01/13/2024-01-13_145720_0889870.6082584868290078.png)

### 同步文档

你在 Obsidian 文档内修改了文档后，可以通过点击文档菜单中的「同步至MrDoc」菜单，对文档的内容进行同步。

![](http://file.mrdoc.pro/mrdoc-oss/img/2024/01/13/2024-01-13_174023_7558060.1447546826138224.png)

也可以在左侧的仓库文件列表中，鼠标右键指定文件，唤出文件的右键菜单，点击「同步至MrDoc」菜单，对文档的内容进行同步。

![](http://file.mrdoc.pro/mrdoc-oss/img/2024/01/13/2024-01-13_174152_8607290.01594941520976112.png)

如果你在插件的配置页面中开启了「实时更新文档内容」开关，那么你在修改了文档内容之后，无需手动操作，插件会自动同步你的更新至MrDoc。

![](http://file.mrdoc.pro/mrdoc-oss/img/2024/01/13/2024-01-13_174342_0886190.24705776965750292.png)

![](http://file.mrdoc.pro/mrdoc-oss/img/2024/01/13/2024-01-13_175034_7994990.9571830904752416.png)

### 转存本地图片

如果你的文本内容中包含图片，那么建议你在插件配置中开启「转存本地图片」开关，这会将你从本地复制或拖拽到文档编辑器中的图片转存至 MrDoc，并且文档内的图片链接更新为 MrDoc 的图片链接。这样，无论你在本地还是网络上浏览文档，里面的图片都能够正确显示。

![](http://file.mrdoc.pro/mrdoc-oss/img/2024/01/13/2024-01-13_174945_6869210.3739490082968101.png)

### 转存剪贴板数据中的图片

如果你经常中别处复制内容到 Obsidian 仓库的文档中，那么建议你在插件配置中开启「转存剪贴板数据中的图片」开关。

开启此开关后，插件会提取剪切板文本内容中的图片链接，并将其上传至 MrDoc，然后替换为 MrDoc 的图片链接。

![](http://file.mrdoc.pro/mrdoc-oss/img/2024/01/13/2024-01-13_174928_9329810.12138738551333095.png)