diff --git a/docs/en/04-sync.md b/docs/en/04-sync.md index 36e521f..a7a67a8 100644 --- a/docs/en/04-sync.md +++ b/docs/en/04-sync.md @@ -39,19 +39,21 @@ autosync-database: [blog, portfolio] --- ``` -If you change the key name in the settings, update your frontmatter to match. The plugin will prompt you when the entry is missing. +If you change the key name in the settings, update your frontmatter to match. ### 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 +- 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 - 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 ### Auto Sync Scenarios -#### Scenario A: Missing Auto Sync Entry +#### Scenario A-1: New File Missing Auto Sync Entry ```yaml --- @@ -61,25 +63,42 @@ tags: [blog, tech] ``` **Behavior:** -- ✅ Detects that the configured auto sync key is missing -- ✅ Shows notice: `⚠️ Auto sync skipped: Add a "{key}" entry in the frontmatter to choose databases` -- ✅ No sync operation performed -- 📝 **Action Required:** Add the configured key (default `autosync-database`) to the frontmatter with the database abbreviations +- ✅ 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 B: New Document (Not Yet Synced) +#### Scenario A-2: Synced File Missing Auto Sync Entry ```yaml --- -title: My New Article -aytosync-database: [blog] +title: My Article +NotionID-blog: abc123 --- ``` **Behavior:** -- ✅ Detects no NotionID present -- ✅ Shows notice: "⚠️ Auto sync skipped: This document has not been synced to Notion, please upload manually first" +- ✅ 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:** Manually sync the document first using the command palette +- 📝 **Action Required:** Add `autosync-database: [blog]` to the frontmatter + +#### Scenario B: New Document (First-Time Auto Upload) + +```yaml +--- +title: My New Article +autosync-database: [blog] +--- +``` + +**Behavior:** +- ✅ Detects no NotionID present but `autosync-database` is configured +- ✅ Automatically performs first-time upload to the Blog database +- ✅ Adds `NotionID-blog: xxx` to the frontmatter after successful upload +- ✅ Shows success/failure notification +- 📝 **No Action Required:** The plugin handles the initial upload automatically #### Scenario C: Synced to One Database @@ -105,11 +124,12 @@ title: My Article NotionID-blog: abc123 NotionID-portfolio: def456 NotionID-notes: ghi789 +autosync-database: [blog, portfolio, notes] --- ``` **Behavior:** -- ✅ Detects 3 NotionIDs +- ✅ Detects 3 database targets - ✅ Shows notice: "🔄 Auto sync: Syncing to 3 database(s)..." - ✅ Syncs to all 3 databases sequentially - ✅ Shows individual result notifications for each database @@ -132,7 +152,7 @@ NotionID-portfolio: def456 - 📝 **Remember:** Update both the setting and your frontmatter if you rename the key ### Auto Sync Best Practices -1. **First Sync Manually**: Always perform the first sync manually to establish the NotionID link +1. **Add Frontmatter Key**: Just add `autosync-database: [your-db]` to enable auto sync - no manual upload needed 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 diff --git a/docs/zh/04-sync.md b/docs/zh/04-sync.md index 4f1b0f5..b8f59fc 100644 --- a/docs/zh/04-sync.md +++ b/docs/zh/04-sync.md @@ -22,18 +22,38 @@ description: 如何使用 NotionNext 插件将你的 Obsidian 笔记同步到 No 3. 开启该开关 4. 配置"自动同步延迟时间"(默认:5秒,最小:2秒) +### 准备 Frontmatter + +自动同步会读取你在 **设置 → 自动同步 Frontmatter 键名** 中配置的键名(默认为 `autosync-database`)来确定要同步的数据库。要让你的笔记能够自动同步: + +- 在笔记的 frontmatter 中添加配置的键名 +- 列出一个或多个你在插件设置中定义的数据库简称 +- 如果修改了笔记要同步的数据库,记得更新列表 + +示例(使用默认键名): + +```yaml +--- +title: 我的文章 +autosync-database: [blog, portfolio] +--- +``` + +如果你在设置中修改了键名,记得同时更新你的 frontmatter。 + ### 自动同步工作原理 当自动同步启用后: - 插件会监控 Markdown 文件的变化 - 在你停止编辑达到配置的延迟时间后,自动触发同步 -- 只有已经同步过的文件(frontmatter 中有 NotionID)才会被自动同步 +- **支持首次自动上传**:无需先手动同步,只要添加 frontmatter 键名,插件会自动处理首次上传 - 如果文件关联了多个数据库,会自动同步到所有数据库 +- 首次同步后,会自动在 frontmatter 中添加 `NotionID-{数据库}` 用于后续更新 ### 自动同步场景示例 -#### 场景 A:新文档(未同步) +#### 场景 A-1:新文件缺少自动同步配置 ```yaml --- @@ -44,12 +64,12 @@ tags: [博客, 技术] **行为:** -- ✅ 检测到没有 NotionID -- ✅ 显示提示:"⚠️ 自动同步跳过:此文档未同步到 Notion,请先手动上传" -- ✅ 不执行同步操作 -- 📝 **需要操作:** 先使用命令面板手动同步文档 +- ✅ 检测到缺少自动同步配置键 +- ✅ 检测到没有 NotionID(新文件) +- ✅ 静默跳过,不显示任何提示 +- 📝 **如需启用自动同步:** 在 frontmatter 中添加 `autosync-database: [你的数据库简称]` -#### 场景 B:已同步到一个数据库 +#### 场景 A-2:已同步文件缺少自动同步配置 ```yaml --- @@ -60,12 +80,47 @@ NotionID-blog: abc123 **行为:** +- ✅ 检测到缺少自动同步配置键 +- ✅ 检测到已存在 NotionID(说明之前同步过) +- ✅ 显示提示:"⚠️ 自动同步已跳过:请在 frontmatter 中添加 autosync-database 以指定目标数据库" +- ✅ 不执行同步操作 +- 📝 **需要操作:** 在 frontmatter 中添加 `autosync-database: [blog]` + +#### 场景 B:新文档(首次自动上传) + +```yaml +--- +title: 我的新文章 +autosync-database: [blog] +--- +``` + +**行为:** + +- ✅ 检测到没有 NotionID,但配置了 `autosync-database` +- ✅ 自动执行首次上传到 Blog 数据库 +- ✅ 上传成功后自动添加 `NotionID-blog: xxx` 到 frontmatter +- ✅ 显示成功/失败通知 +- 📝 **无需操作:** 插件会自动处理首次上传 + +#### 场景 C:已同步到一个数据库(更新) + +```yaml +--- +title: 我的文章 +NotionID-blog: abc123 +autosync-database: [blog] +--- +``` + +**行为:** + - ✅ 检测到 1 个 NotionID -- ✅ 自动同步到 Blog 数据库 +- ✅ 自动同步更新到 Blog 数据库 - ✅ 显示上传命令返回的成功/失败通知 - 📝 **无需操作:** 变更会自动同步 -#### 场景 C:同步到多个数据库 +#### 场景 D:同步到多个数据库 ```yaml --- @@ -73,12 +128,13 @@ title: 我的文章 NotionID-blog: abc123 NotionID-portfolio: def456 NotionID-notes: ghi789 +autosync-database: [blog, portfolio, notes] --- ``` **行为:** -- ✅ 检测到 3 个 NotionID +- ✅ 检测到 3 个数据库目标 - ✅ 显示提示:"🔄 自动同步:正在同步到 3 个数据库..." - ✅ 依次同步到所有 3 个数据库 - ✅ 为每个数据库显示独立的结果通知 @@ -86,7 +142,7 @@ NotionID-notes: ghi789 ### 自动同步最佳实践 -1. **首次手动同步**:始终先手动执行第一次同步以建立 NotionID 链接 +1. **添加 Frontmatter 配置**:只需添加 `autosync-database: [你的数据库]` 即可启用自动同步,无需手动上传 2. **合理配置延迟**:如果你经常编辑,设置较长的延迟时间(5-10 秒) 3. **监控同步状态**:注意查看通知以确保同步成功完成 4. **查看日志**:打开开发者控制台(Ctrl+Shift+I / Cmd+Option+I)查看详细的同步日志 diff --git a/src/main.ts b/src/main.ts index 32ae6ea..4b01978 100644 --- a/src/main.ts +++ b/src/main.ts @@ -18,7 +18,7 @@ export default class ObsidianSyncNotionPlugin extends Plugin { private syncingFiles: Set = new Set(); private lastFrontmatterCache: Map = new Map(); private lastContentHashCache: Map = new Map(); - private missingAutoSyncNoticeShown: Set = new Set(); + async onload() { await this.loadSettings(); @@ -69,7 +69,7 @@ export default class ObsidianSyncNotionPlugin extends Plugin { } this.lastFrontmatterCache.clear(); this.lastContentHashCache.clear(); - this.missingAutoSyncNoticeShown.clear(); + } async loadSettings() { @@ -170,9 +170,7 @@ export default class ObsidianSyncNotionPlugin extends Plugin { } } - resetAutoSyncNoticeCache() { - this.missingAutoSyncNoticeShown.clear(); - } + getAutoSyncFrontmatterKey(): string { return resolveAutoSyncKey(this.settings.autoSyncFrontmatterKey); @@ -353,17 +351,24 @@ export default class ObsidianSyncNotionPlugin extends Plugin { const autoSyncKey = this.getAutoSyncFrontmatterKey(); const autoSyncTargets = parseAutoSyncDatabaseList(frontMatter[autoSyncKey]); + // If no autosync-database field specified if (autoSyncTargets.length === 0) { - if (!this.missingAutoSyncNoticeShown.has(file.path)) { + // Check if file has any existing NotionID (meaning it was synced before) + const hasExistingNotionID = Object.keys(frontMatter).some(key => + key.startsWith('NotionID-') || key === 'NotionID' + ); + + if (hasExistingNotionID) { + // User likely forgot to add autosync-database - show a notice const message = i18nConfig.AutoSyncMissingDatabaseList.replace('{key}', autoSyncKey); - new Notice(message, 10000); - this.missingAutoSyncNoticeShown.add(file.path); + new Notice(message, 8000); + console.log(`[AutoSync] File ${file.path} has NotionID but missing autosync-database - showing notice`); } - console.log(`[AutoSync] No auto sync database list found in ${file.path} using key "${autoSyncKey}"`); + // Silently skip files without NotionID (new files that don't need auto-sync) return; } - this.missingAutoSyncNoticeShown.delete(file.path); + const dbByShortName = new Map(); for (const key in this.settings.databaseDetails) {