obsidian-to-NotionNext/docs/en/04-sync.md

title, description

title	description
Syncing Notes	How to sync your Obsidian notes to Notion using the NotionNext plugin

Syncing Notes

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.

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)

Prepare the Frontmatter

Auto sync reads the database list from the frontmatter key you configured in Settings → Auto Sync Frontmatter Key (default: autosync-database). To make sure your notes can sync automatically:

• Add the configured key to your note's frontmatter
• List one or more database abbreviations that you defined in the plugin settings
• Keep the list updated if you change the databases a note should sync to

Example with the default key:

---
title: My Article
autosync-database: [blog, portfolio]
---

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
• 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-1: New File Missing Auto Sync Entry

---
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

---
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)

---
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

---
title: My Article
NotionID-blog: abc123
autosync-database: [blog]
---

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 D: Synced to Multiple Databases

---
title: My Article  
NotionID-blog: abc123
NotionID-portfolio: def456
NotionID-notes: ghi789
autosync-database: [blog, portfolio, notes]
---

Behavior:

• ✅ 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
• 📝 No Action Required: Changes are automatically synced to all linked databases

Scenario E: Custom Frontmatter Key

---
title: My Article
NotionID-blog: abc123
NotionID-portfolio: def456
🚀-sync-targets: [blog, portfolio]
---

Behavior:

• ✅ Uses your custom key (for example 🚀-sync-targets) configured in settings
• ✅ Syncs to the listed databases when NotionIDs are present
• 📝 Remember: Update both the setting and your frontmatter if you rename the key

Auto Sync Best Practices

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

Troubleshooting

Having issues with auto sync? Check the Troubleshooting Guide for detailed solutions to common problems.