Obsidian plugins

# ⌨️ Obsidian Plugin

MrDoc provides an Obsidian plugin — "Obsidian Mrdoc Plugin" — to synchronize documents between Obsidian and MrDoc.

- Provides Obsidian users with a new solution for remote synchronization of local documents;
- Provides a new solution for online web browsing of Obsidian local documents;
- Provides MrDoc users with a new solution for offline writing, saving, and synchronizing documents;

## System Requirements

- MrDoc Pro edition `v1.3.6+`, MrDoc open source edition `v0.9.2+`
- Obsidian `v1.4.16`

## Correspondence of Basic Concepts

- Obsidian's "Vault" corresponds to MrDoc's "project";
- "Markdown files" within an Obsidian vault correspond to "documents" in MrDoc;
- "Folders" within an Obsidian vault correspond to "documents" in MrDoc that contain sub-documents;

## Plugin Rules

### Vault

In Obsidian, you need to select the target project in MrDoc on the plugin's settings page.
> If you want documents to be synchronized to a new MrDoc project, you can click the "New" button to create a project and then select it.

### Pull Remote Documents

The plugin adds a function icon button to the left toolbar, used to pull all documents within a project from MrDoc to the local Obsidian. After clicking the pull operation, the plugin retrieves information for all documents within the specified project and prepares to write them to the local Obsidian.

- If a file/folder with the same name does not exist locally, a new file/folder is created;
- If a file with the same name already exists locally, it determines whether a mapping relationship exists between the local file and the remote document:
	- If a mapping relationship exists, it compares the last modification time of the local file and the remote document:
		- If the local file's last modification time is newer than the remote document, skip;
		- If the local file's last modification time is older than the remote document, overwrite the local file with the remote document's content.
	- If no mapping relationship exists, skip.
- If a folder with the same name already exists locally, skip.

### Create New File/Folder

When you create a new file/folder locally in Obsidian, a document is automatically created in the specified project in MrDoc, and a mapping relationship between the local document and the remote document is maintained within the plugin;

### Rename File/Folder

When you rename a file/folder locally in Obsidian, the corresponding document title in MrDoc is automatically modified.

### Move File Hierarchy

When you move a file to a different folder locally in Obsidian, the corresponding document's parent in MrDoc is automatically modified.

### Modify File

After modifying the file content, you can click the "Sync to MrDoc" menu in the "More options" at the top right of the editor to push the document's updates to MrDoc.

You can also hover the mouse over the specified document in the file list on the left side of the Obsidian software, right-click to bring up the context menu, and then click the "Sync to MrDoc" menu to push the document's updates to MrDoc.

In addition, the plugin provides a **real-time push** option. You can enable "Real-time document content update" on the plugin's settings page. Then, when you modify the file content in Obsidian, the plugin will update the latest file content to MrDoc in real time.

### Delete File/Folder

If a mapping relationship has been established between a local file/folder in Obsidian and MrDoc, then when you delete the file/folder locally, the plugin will also synchronously delete the document in MrDoc (soft delete, the document enters the recycle bin).

### Image Handling

For image handling, the plugin provides two options:

- Save local images
- Save images from the clipboard

**1. Save local images**

When you paste or drag a local image into the Obsidian editor, the plugin uploads the image to MrDoc, then returns the image link address from MrDoc and fills it into the Obsidian editor.

**2. Save images from the clipboard**

When you copy text from elsewhere to paste into the Obsidian editor, the plugin extracts the image links within it, uploads them to MrDoc, then returns the image link addresses from MrDoc to replace the original image links in the text.

### Reset Mapping Relationship

After a mapping relationship has been established between a local file in Obsidian and a document in MrDoc, if you need to remove its bound mapping relationship, you can click "Reset document mapping" on the plugin's settings page. Then, operations on the local file in Obsidian will not be synchronized to MrDoc.

## Usage Tutorial

### Installation

1. Official installation (the plugin has been submitted for official review)

2. Installation via BRAT (recommended)

Open Settings - Third-party plugins - Browse - search for brat, download, install, and enable it.

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

Open BRAT settings

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

Click Add Beta plugin, a popup will appear, fill in the following 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
```

Click the `Add Plugin` button and wait for the installation. The following message indicates successful installation:

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

Before using this plugin, you need to perform some configuration.

### Configure Connection Information

Go to the "MrDoc" plugin configuration page, fill in "MrDoc URL" and "User Token" (obtained at: Personal Center -> Personal Management -> Token Management), and click the "Check" button to test whether the connection is successful.

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

### Specify Target Project

After successfully configuring the connection information, you need to specify a target project in MrDoc to bind with the Obsidian vault.

Click the "Refresh" button to obtain your project list, and then you can select a project from it.

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

You can also click the "New" button to create a blank project, and then select it from the project list as the binding for the Obsidian vault.

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

After completing the above two operations, creating, renaming, and moving documents within the Obsidian vault will be synchronized to MrDoc.

### Pull Documents

If you have specified a MrDoc project but the local Obsidian vault is empty, you can pull the documents within the MrDoc project into the Obsidian vault.

Click the button on the left sidebar of the Obsidian main interface, as shown in the figure:

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

Click the "Confirm" button in the popup modal, and the plugin will pull the documents in the specified project from MrDoc to Obsidian.

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

After the pull is complete, all newly created folders and documents will be displayed.

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

### Synchronize Documents

After you modify a document in Obsidian, you can synchronize the document's content by clicking the "Sync to MrDoc" menu in the document menu.

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

You can also right-click the specified file in the vault file list on the left to bring up the file's right-click menu, and click the "Sync to MrDoc" menu to synchronize the document's content.

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

If you have enabled the "Real-time document content update" switch on the plugin's configuration page, then after you modify the document content, no manual operation is required; the plugin will automatically synchronize your updates to 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)

### Save Local Images

If your text content contains images, it is recommended that you enable the "Save local images" switch in the plugin configuration. This will save images that you copy or drag from local into the document editor to MrDoc, and the image links within the document will be updated to MrDoc's image links. In this way, whether you browse the document locally or online, the images within it will display correctly.

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

### Save Images from Clipboard Data

If you frequently copy content from elsewhere into documents in the Obsidian vault, it is recommended that you enable the "Save images from clipboard data" switch in the plugin configuration.

After enabling this switch, the plugin will extract the image links from the clipboard text content, upload them to MrDoc, and then replace them with MrDoc's image links.

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