jxpeng98/obsidian-to-NotionNext
1
0
Fork 0
mirror of https://github.com/jxpeng98/obsidian-to-NotionNext synced 2026-07-29 08:08:34 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: Enhance attachment upload documentation with supported formats and auto sync details

Browse Source
This commit is contained in:
Jiaxin Peng
2026-01-04 19:10:59 +00:00
parent ccfe40c1f0
commit 876b6233cb
2 changed files with 147 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

110
docs/en/04-sync.md
View File

@@ -11,6 +11,73 @@ After configuring your Notion database in the plugin settings, you can start syn
To sync a note, open the note you want to sync and use the "Share to NotionNext" command from the command palette or the note context menu. This will create a new page in your Notion database with the content of your Obsidian note. To sync a note, open the note you want to sync and use the "Share to NotionNext" command from the command palette or the note context menu. This will create a new page in your Notion database with the content of your Obsidian note.
## Attachment Upload
The plugin automatically detects and uploads local attachments (images, PDFs, etc.) from your notes to Notion.
### Supported Attachment Formats
**Image formats:**
- PNG, JPG, JPEG, GIF, WebP, SVG, HEIC, TIF, TIFF, BMP
**Other formats:**
- PDF
### Supported Link Formats
Currently supported:
#### Wikilink Format (Recommended)
```markdown
![[image.png]]
![[folder/image.png]]
![[image.png|alt text]]
[[document.pdf]]
[[folder/document.pdf]]
```
#### Standard Markdown Format
```markdown
![alt text](image.png)
![alt text](folder/image.png)
![](./relative/path/image.png)
[document.pdf](document.pdf)
[document.pdf](folder/document.pdf)
```
#### TODO
- [ ] Obsidian URL Format
```markdown
![](obsidian://open?vault=MyVault&file=path/to/image.png)
```
- [ ] App URL Format
```markdown
![](app://local/path/to/image.png)
```
### How Attachment Upload Works
1. **Auto Detection**: During sync, the plugin scans your note content and identifies all local attachment references
2. **Upload to Notion**: Detected attachments are uploaded via the Notion File Upload API
3. **Link Replacement**: After successful upload, local links are replaced with Notion file references
4. **Image Display**: Images are displayed as Notion image blocks
5. **File Embedding**: Non-image files like PDFs are embedded as file blocks
### Notes
- Attachment references inside code blocks are not processed
- External URLs (`http://` or `https://`) are not processed
- Single file size limit is 5MB
- Ensure attachment files exist in your Vault
## Auto Sync ## Auto Sync
The plugin supports automatic syncing that monitors your notes for changes and automatically syncs them to Notion. The plugin supports automatic syncing that monitors your notes for changes and automatically syncs them to Notion.
@@ -45,46 +112,17 @@ If you change the key name in the settings, update your frontmatter to match.
When auto sync is enabled: When auto sync is enabled:
- The plugin monitors markdown files for changes - The plugin monitors markdown files for changes
- **Only files with the auto sync key in frontmatter will be processed**
- Files without the auto sync key are silently skipped - no sync operations or notices
- Files containing internal attachments (local images/PDFs) are skipped - sync them manually
- After you stop editing for the configured delay period, auto sync is triggered - After you stop editing for the configured delay period, auto sync is triggered
- Files with the `autosync-database` key in frontmatter will be automatically synced
- **First-time upload is supported**: No need to manually sync first - just add the frontmatter key and the plugin will handle the initial upload - **First-time upload is supported**: No need to manually sync first - just add the frontmatter key and the plugin will handle the initial upload
- If a file is linked to multiple databases, it will sync to all of them automatically - If a file is linked to multiple databases, it will sync to all of them automatically
- After the first sync, a `NotionID-{database}` will be added to the frontmatter for future updates - After the first sync, a `NotionID-{database}` will be added to the frontmatter for future updates
### Auto Sync Scenarios ### Auto Sync Scenarios
#### Scenario A-1: New File Missing Auto Sync Entry #### Scenario A: New Document (First-Time Auto Upload)
```yaml
---
title: My New Article
tags: [blog, tech]
---
```
**Behavior:**
- ✅ Detects that the auto sync key is missing
- ✅ Detects no NotionID present (new file)
- ✅ Silently skips - no notice shown
- 📝 **To enable auto sync:** Add `autosync-database: [your-db-abbreviation]` to the frontmatter
#### Scenario A-2: Synced File Missing Auto Sync Entry
```yaml
---
title: My Article
NotionID-blog: abc123
---
```
**Behavior:**
- ✅ Detects that the auto sync key is missing
- ✅ Detects existing NotionID (file was synced before)
- ✅ Shows notice: "⚠️ Auto-sync skipped: Add autosync-database to your frontmatter to specify target databases"
- ✅ No sync operation performed
- 📝 **Action Required:** Add `autosync-database: [blog]` to the frontmatter
#### Scenario B: New Document (First-Time Auto Upload)
```yaml ```yaml
--- ---
@@ -100,7 +138,7 @@ autosync-database: [blog]
- ✅ Shows success/failure notification - ✅ Shows success/failure notification
- 📝 **No Action Required:** The plugin handles the initial upload automatically - 📝 **No Action Required:** The plugin handles the initial upload automatically
#### Scenario C: Synced to One Database #### Scenario B: Synced to One Database
```yaml ```yaml
--- ---
@@ -116,7 +154,7 @@ autosync-database: [blog]
- ✅ Shows success/failure notification from the upload command - ✅ Shows success/failure notification from the upload command
- 📝 **No Action Required:** Changes are automatically synced - 📝 **No Action Required:** Changes are automatically synced
#### Scenario D: Synced to Multiple Databases #### Scenario C: Synced to Multiple Databases
```yaml ```yaml
--- ---
@@ -135,7 +173,7 @@ autosync-database: [blog, portfolio, notes]
- ✅ Shows individual result notifications for each database - ✅ Shows individual result notifications for each database
- 📝 **No Action Required:** Changes are automatically synced to all linked databases - 📝 **No Action Required:** Changes are automatically synced to all linked databases
#### Scenario E: Custom Frontmatter Key #### Scenario D: Custom Frontmatter Key
```yaml ```yaml
--- ---

109
docs/zh/04-sync.md
View File

@@ -11,6 +11,73 @@ description: 如何使用 NotionNext 插件将你的 Obsidian 笔记同步到 No
要同步一篇笔记，只需打开你想要同步的笔记，然后从命令面板（`Ctrl/Cmd + P`）或笔记的右键菜单中选择 "Share to NotionNext" 命令。这会在你的 Notion 数据库中创建一个新页面，内容与你的 Obsidian 笔记完全一致。 要同步一篇笔记，只需打开你想要同步的笔记，然后从命令面板（`Ctrl/Cmd + P`）或笔记的右键菜单中选择 "Share to NotionNext" 命令。这会在你的 Notion 数据库中创建一个新页面，内容与你的 Obsidian 笔记完全一致。
## 附件上传
插件支持自动检测并上传笔记中的本地附件（图片、PDF 等）到 Notion。
### 支持的附件格式
**图片格式：**
- PNG, JPG, JPEG, GIF, WebP, SVG, HEIC, TIF, TIFF, BMP
**其他格式：**
- PDF
### 支持的链接格式
当前支持：
#### Wikilink 格式（推荐）
```markdown
![[image.png]]
![[folder/image.png]]
![[image.png|alt text]]
[[document.pdf]]
[[folder/document.pdf]]
```
#### 标准 Markdown 格式
```markdown
![alt text](image.png)
![alt text](folder/image.png)
![](./relative/path/image.png)
[document.pdf](document.pdf)
[document.pdf](folder/document.pdf)
```
#### TODO
- [ ] Obsidian URL 格式
```markdown
![](obsidian://open?vault=MyVault&file=path/to/image.png)
```
- [ ] App URL 格式
```markdown
![](app://local/path/to/image.png)
```
### 附件上传工作原理
1. **自动检测**：同步时，插件会自动扫描笔记内容，识别所有本地附件引用
2. **上传到 Notion**：检测到的附件会通过 Notion File Upload API 上传
3. **链接替换**：上传成功后，笔记中的本地链接会被替换为 Notion 的文件引用
4. **图片显示**：图片会作为 Notion 的图片块显示
5. **文件嵌入**：PDF 等非图片文件会作为文件块嵌入
### 注意事项
- 代码块中的附件引用不会被处理
- 外部 URL（`http://` 或 `https://`）不会被处理
- 单个文件大小限制为 5MB
- 确保附件文件存在于 Vault 中
## 自动同步 ## 自动同步
插件支持自动同步功能，可以监控你的笔记变化并自动同步到 Notion。 插件支持自动同步功能，可以监控你的笔记变化并自动同步到 Notion。
@@ -46,6 +113,9 @@ autosync-database: [blog, portfolio]
当自动同步启用后： 当自动同步启用后：
- 插件会监控 Markdown 文件的变化 - 插件会监控 Markdown 文件的变化
- **只有 frontmatter 中包含自动同步配置键的文件才会被处理**
- 没有配置自动同步键的文件会被静默跳过，不会触发任何同步操作或提示
- 含有本地附件（图片/PDF）的文件会跳过自动同步，请手动同步
- 在你停止编辑达到配置的延迟时间后，自动触发同步 - 在你停止编辑达到配置的延迟时间后，自动触发同步
- **支持首次自动上传**：无需先手动同步，只要添加 frontmatter 键名，插件会自动处理首次上传 - **支持首次自动上传**：无需先手动同步，只要添加 frontmatter 键名，插件会自动处理首次上传
- 如果文件关联了多个数据库，会自动同步到所有数据库 - 如果文件关联了多个数据库，会自动同步到所有数据库
@@ -53,40 +123,7 @@ autosync-database: [blog, portfolio]
### 自动同步场景示例 ### 自动同步场景示例
#### 场景 A-1：新文件缺少自动同步配置 #### 场景 A：新文档（首次自动上传）
```yaml
---
title: 我的新文章
tags: [博客, 技术]
---
```
**行为：**
- ✅ 检测到缺少自动同步配置键
- ✅ 检测到没有 NotionID（新文件）
- ✅ 静默跳过，不显示任何提示
- 📝 **如需启用自动同步：** 在 frontmatter 中添加 `autosync-database: [你的数据库简称]`
#### 场景 A-2：已同步文件缺少自动同步配置
```yaml
---
title: 我的文章
NotionID-blog: abc123
---
```
**行为：**
- ✅ 检测到缺少自动同步配置键
- ✅ 检测到已存在 NotionID（说明之前同步过）
- ✅ 显示提示："⚠️ 自动同步已跳过：请在 frontmatter 中添加 autosync-database 以指定目标数据库"
- ✅ 不执行同步操作
- 📝 **需要操作：** 在 frontmatter 中添加 `autosync-database: [blog]`
#### 场景 B：新文档（首次自动上传）
```yaml ```yaml
--- ---
@@ -103,7 +140,7 @@ autosync-database: [blog]
- ✅ 显示成功/失败通知 - ✅ 显示成功/失败通知
- 📝 **无需操作：** 插件会自动处理首次上传 - 📝 **无需操作：** 插件会自动处理首次上传
#### 场景 C：已同步到一个数据库（更新） #### 场景 B：已同步到一个数据库（更新）
```yaml ```yaml
--- ---
@@ -120,7 +157,7 @@ autosync-database: [blog]
- ✅ 显示上传命令返回的成功/失败通知 - ✅ 显示上传命令返回的成功/失败通知
- 📝 **无需操作：** 变更会自动同步 - 📝 **无需操作：** 变更会自动同步
#### 场景 D：同步到多个数据库 #### 场景 C：同步到多个数据库
```yaml ```yaml
--- ---