docs: enhance auto sync documentation with detailed setup, scenarios, and troubleshooting guidance

docs/en/04-sync.md

@@ -7,6 +7,86 @@ description: How to sync your Obsidian notes to Notion using the NotionNext plug
 
 After configuring your Notion database in the plugin settings, you can start syncing your Obsidian notes to Notion.
 
+## Manual Sync
+
 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.
 
-You can also set up automatic syncing for specific notes or folders by configuring the plugin settings. This way, any changes you make to your Obsidian notes will be automatically reflected in Notion.
+## Auto Sync
+
+The plugin supports automatic syncing that monitors your notes for changes and automatically syncs them to Notion.
+
+### Enabling Auto Sync
+
+1. Open the plugin settings
+2. Find the "Auto Sync" toggle under General Settings
+3. Enable the toggle
+4. Configure the "Auto Sync Delay" (default: 5 seconds, minimum: 2 seconds)
+
+### How Auto Sync Works
+
+When auto sync is enabled:
+- The plugin monitors markdown files for changes
+- After you stop editing for the configured delay period, auto sync is triggered
+- Only files that have already been synced to Notion (have a NotionID in frontmatter) will be auto-synced
+- If a file is linked to multiple databases, it will sync to all of them automatically
+
+### Auto Sync Scenarios
+
+#### Scenario A: New Document (Not Yet Synced)
+
+```yaml
+---
+title: My New Article
+tags: [blog, tech]
+---
+```
+
+**Behavior:**
+- ✅ Detects no NotionID present
+- ✅ Shows notice: "⚠️ Auto sync skipped: This document has not been synced to Notion, please upload manually first"
+- ✅ No sync operation performed
+- 📝 **Action Required:** Manually sync the document first using the command palette
+
+#### Scenario B: Synced to One Database
+
+```yaml
+---
+title: My Article
+NotionID-blog: abc123
+---
+```
+
+**Behavior:**
+- ✅ Detects 1 NotionID
+- ✅ Automatically syncs to the Blog database
+- ✅ Shows success/failure notification from the upload command
+- 📝 **No Action Required:** Changes are automatically synced
+
+#### Scenario C: Synced to Multiple Databases
+
+```yaml
+---
+title: My Article  
+NotionID-blog: abc123
+NotionID-portfolio: def456
+NotionID-notes: ghi789
+---
+```
+
+**Behavior:**
+- ✅ Detects 3 NotionIDs
+- ✅ Shows notice: "🔄 Auto sync: Syncing to 3 database(s)..."
+- ✅ Syncs to all 3 databases sequentially
+- ✅ Shows individual result notifications for each database
+- 📝 **No Action Required:** Changes are automatically synced to all linked databases
+
+### Auto Sync Best Practices
+
+1. **First Sync Manually**: Always perform the first sync manually to establish the NotionID link
+2. **Configure Delay Appropriately**: Set a longer delay (5-10 seconds) if you make frequent edits
+3. **Monitor Sync Status**: Check the notifications to ensure syncs complete successfully
+4. **Check Logs**: Open the developer console (Ctrl+Shift+I / Cmd+Option+I) to view detailed sync logs
+
+### Troubleshooting
+
+Having issues with auto sync? Check the [Troubleshooting Guide](05-troubleshooting.md) for detailed solutions to common problems.

docs/en/05-troubleshooting.md

@@ -5,6 +5,70 @@ description: Common issues and solutions for the Obsidian to NotionNext plugin
 
 # Troubleshooting
 
+## Auto Sync Issues
+
+### Auto sync not working?
+
+**Possible causes and solutions:**
+
+- **Auto sync not enabled**: Ensure auto sync is enabled in plugin settings under General Settings
+- **No NotionID in frontmatter**: Verify the document has a NotionID field (e.g., `NotionID-blog: abc123`) in its frontmatter. Auto sync only works for documents that have been manually synced at least once
+- **Invalid database configuration**: Check that your database configuration is valid and the API credentials are correct
+- **Console errors**: Look for errors in the developer console (`Ctrl+Shift+I` / `Cmd+Option+I`)
+
+### Sync too frequent?
+
+If auto sync is triggering too often while you're editing:
+
+- **Increase the delay**: Go to plugin settings and increase the "Auto Sync Delay" value (default is 5 seconds)
+- **Understanding the delay**: The delay timer resets each time you make an edit, so sync only triggers after you stop editing for the configured duration
+
+### Missing notifications?
+
+If you're not seeing sync notifications:
+
+- **Notification duration**: Notifications appear for 3-6 seconds and then automatically disappear
+- **Check console logs**: Open the developer console (`Ctrl+Shift+I` / `Cmd+Option+I`) to view detailed sync information
+- **Multiple syncs**: When syncing to multiple databases, you'll see a notification for the multi-database sync plus individual result notifications
+
+### Auto sync skipped for new documents
+
+If you see the message "⚠️ Auto sync skipped: This document has not been synced to Notion, please upload manually first":
+
+- **First sync required**: This is expected behavior. Auto sync only works for documents that already have a NotionID
+- **Solution**: Use the command palette (`Ctrl/Cmd + P`) and select "Share to NotionNext" to perform the first manual sync
+- **After manual sync**: Once the document has a NotionID in its frontmatter, auto sync will work automatically
+
+## General Sync Issues
+
+### Sync failed with error message
+
+If you see error messages during sync:
+
+1. **Check API credentials**: Verify your Notion API token and Database ID are correct
+2. **Check permissions**: Ensure the integration has access to the target database
+3. **Network issues**: Check your internet connection
+4. **Rate limiting**: Notion has API rate limits; wait a moment and try again
+5. **Check console**: Open developer tools to see detailed error information
+
+### Multiple database sync issues
+
+When syncing to multiple databases:
+
+- **Partial failures**: If one database fails, others will still continue syncing
+- **Individual notifications**: Each database sync shows its own result notification
+- **Check frontmatter**: Verify all NotionID fields are present and correct (e.g., `NotionID-blog`, `NotionID-portfolio`)
+
+## Getting Help
+
 If the problem persists, you can [open an issue on GitHub](https://github.com/jxpeng98/obsidian-to-NotionNext/issues) with detailed error information and the steps you took.
 
 You can find the error logs in Obsidian by going to developer tools (`Ctrl+Shift+I` or `Cmd+Option+I`) and checking the console for any error messages related to the NotionNext plugin.
+
+### What to include in bug reports:
+
+1. **Error messages**: Copy the exact error message from notifications or console
+2. **Console logs**: Include relevant logs from the developer console (look for `[AutoSync]`, `[Settings]`, or `[Plugin]` prefixes)
+3. **Steps to reproduce**: Describe what you were doing when the issue occurred
+4. **Configuration**: Mention which database format you're using (NotionNext, General, or Custom)
+5. **Settings**: Note if auto sync is enabled and what delay is configured

docs/zh/04-sync.md

@@ -7,6 +7,90 @@ description: 如何使用 NotionNext 插件将你的 Obsidian 笔记同步到 No
 
 在插件设置中配置好你的 Notion 数据库后，你就可以开始将 Obsidian 笔记同步到 Notion 了。
 
-要同步一篇笔记，只需打开你想要同步的笔记，然后从命令面板（`Ctrl/Cmd + P`）或笔记的右键菜单中选择 “Share to NotionNext” 命令。这会在你的 Notion 数据库中创建一个新页面，内容与你的 Obsidian 笔记完全一致。
+## 手动同步
 
-你还可以为特定的笔记或文件夹设置自动同步。这样，你在 Obsidian 中对这些笔记所做的任何更改，都会自动反映到 Notion 中，非常方便。
+要同步一篇笔记，只需打开你想要同步的笔记，然后从命令面板（`Ctrl/Cmd + P`）或笔记的右键菜单中选择 "Share to NotionNext" 命令。这会在你的 Notion 数据库中创建一个新页面，内容与你的 Obsidian 笔记完全一致。
+
+## 自动同步
+
+插件支持自动同步功能，可以监控你的笔记变化并自动同步到 Notion。
+
+### 启用自动同步
+
+1. 打开插件设置
+2. 在通用设置下找到"自动同步"开关
+3. 开启该开关
+4. 配置"自动同步延迟时间"（默认：5秒，最小：2秒）
+
+### 自动同步工作原理
+
+当自动同步启用后：
+
+- 插件会监控 Markdown 文件的变化
+- 在你停止编辑达到配置的延迟时间后，自动触发同步
+- 只有已经同步过的文件（frontmatter 中有 NotionID）才会被自动同步
+- 如果文件关联了多个数据库，会自动同步到所有数据库
+
+### 自动同步场景示例
+
+#### 场景 A：新文档（未同步）
+
+```yaml
+---
+title: 我的新文章
+tags: [博客, 技术]
+---
+```
+
+**行为：**
+
+- ✅ 检测到没有 NotionID
+- ✅ 显示提示："⚠️ 自动同步跳过：此文档未同步到 Notion，请先手动上传"
+- ✅ 不执行同步操作
+- 📝 **需要操作：** 先使用命令面板手动同步文档
+
+#### 场景 B：已同步到一个数据库
+
+```yaml
+---
+title: 我的文章
+NotionID-blog: abc123
+---
+```
+
+**行为：**
+
+- ✅ 检测到 1 个 NotionID
+- ✅ 自动同步到 Blog 数据库
+- ✅ 显示上传命令返回的成功/失败通知
+- 📝 **无需操作：** 变更会自动同步
+
+#### 场景 C：同步到多个数据库
+
+```yaml
+---
+title: 我的文章  
+NotionID-blog: abc123
+NotionID-portfolio: def456
+NotionID-notes: ghi789
+---
+```
+
+**行为：**
+
+- ✅ 检测到 3 个 NotionID
+- ✅ 显示提示："🔄 自动同步：正在同步到 3 个数据库..."
+- ✅ 依次同步到所有 3 个数据库
+- ✅ 为每个数据库显示独立的结果通知
+- 📝 **无需操作：** 变更会自动同步到所有关联的数据库
+
+### 自动同步最佳实践
+
+1. **首次手动同步**：始终先手动执行第一次同步以建立 NotionID 链接
+2. **合理配置延迟**：如果你经常编辑，设置较长的延迟时间（5-10 秒）
+3. **监控同步状态**：注意查看通知以确保同步成功完成
+4. **查看日志**：打开开发者控制台（Ctrl+Shift+I / Cmd+Option+I）查看详细的同步日志
+
+### 故障排除
+
+遇到自动同步问题？请查看[问题排查指南](05-troubleshooting.md)获取常见问题的详细解决方案。

docs/zh/05-troubleshooting.md

@@ -5,6 +5,70 @@ description: Obsidian to NotionNext 插件的常见问题与解决方案
 
 # 问题排查
 
+## 自动同步问题
+
+### 自动同步不工作？
+
+**可能的原因及解决方案：**
+
+- **未启用自动同步**：确保在插件设置的通用设置中启用了自动同步功能
+- **frontmatter 中没有 NotionID**：验证文档的 frontmatter 中有 NotionID 字段（如 `NotionID-blog: abc123`）。自动同步仅适用于至少手动同步过一次的文档
+- **数据库配置无效**：检查数据库配置是否有效，API 凭证是否正确
+- **控制台错误**：查看开发者控制台（`Ctrl+Shift+I` / `Cmd+Option+I`）中的错误信息
+
+### 同步太频繁？
+
+如果在编辑时自动同步触发太频繁：
+
+- **增加延迟时间**：前往插件设置，增加"自动同步延迟时间"的值（默认为 5 秒）
+- **理解延迟机制**：每次编辑都会重置延迟计时器，只有在停止编辑达到配置的时长后才会触发同步
+
+### 看不到通知？
+
+如果没有看到同步通知：
+
+- **通知显示时长**：通知会显示 3-6 秒然后自动消失
+- **查看控制台日志**：打开开发者控制台（`Ctrl+Shift+I` / `Cmd+Option+I`）查看详细的同步信息
+- **多数据库同步**：同步到多个数据库时，你会看到一个多数据库同步通知以及各个数据库的结果通知
+
+### 新文档跳过自动同步
+
+如果看到消息"⚠️ 自动同步跳过：此文档未同步到 Notion，请先手动上传"：
+
+- **需要首次同步**：这是预期行为。自动同步仅适用于已有 NotionID 的文档
+- **解决方案**：使用命令面板（`Ctrl/Cmd + P`）选择"Share to NotionNext"执行首次手动同步
+- **手动同步后**：一旦文档的 frontmatter 中有了 NotionID，自动同步就会自动工作
+
+## 常规同步问题
+
+### 同步失败并显示错误消息
+
+如果在同步时看到错误消息：
+
+1. **检查 API 凭证**：验证 Notion API 令牌和数据库 ID 是否正确
+2. **检查权限**：确保集成有权限访问目标数据库
+3. **网络问题**：检查网络连接
+4. **速率限制**：Notion 有 API 速率限制，等待片刻后重试
+5. **查看控制台**：打开开发者工具查看详细的错误信息
+
+### 多数据库同步问题
+
+同步到多个数据库时：
+
+- **部分失败**：如果一个数据库失败，其他数据库仍会继续同步
+- **独立通知**：每个数据库同步都会显示自己的结果通知
+- **检查 frontmatter**：验证所有 NotionID 字段都存在且正确（如 `NotionID-blog`、`NotionID-portfolio`）
+
+## 获取帮助
+
 如果问题依然存在，你可以在 GitHub 上[提交一个 Issue](https://github.com/jxpeng98/obsidian-to-NotionNext/issues)，并附上详细的错误信息和你的操作步骤，我会尽快帮助你。
 
 你也可以通过 `Ctrl+Shift+I` (Windows/Linux) 或 `Cmd+Option+I` (Mac) 打开 Obsidian 的开发者工具，在控制台（Console）中查看是否有与 NotionNext 插件相关的错误日志，这对于定位问题非常有帮助。
+
+### 提交 Bug 报告时应包含的信息
+
+1. **错误消息**：复制通知或控制台中的确切错误消息
+2. **控制台日志**：包含开发者控制台中的相关日志（查找 `[AutoSync]`、`[Settings]` 或 `[Plugin]` 前缀）
+3. **重现步骤**：描述问题发生时你正在做什么
+4. **配置信息**：说明你使用的数据库格式（NotionNext、普通或自定义）
+5. **设置信息**：注明是否启用了自动同步以及配置的延迟时间