diff --git a/apps/website/app/(docs)/docs/obsidian/pages/sync-and-import.md b/apps/website/app/(docs)/docs/obsidian/pages/sync-and-import.md new file mode 100644 index 000000000..7ab91ab5d --- /dev/null +++ b/apps/website/app/(docs)/docs/obsidian/pages/sync-and-import.md @@ -0,0 +1,136 @@ +--- +title: "Sync and Import" +date: "2026-02-16" +author: "" +published: true +--- + +The Sync and Import feature allows you to synchronize your discourse nodes with the Discourse Graph database and share them with collaborators. Once enabled, you can publish nodes to a shared group space and import nodes published by others. + +> **Note:** This feature is currently in **beta**. The sync functionality requires an active connection to the Discourse Graph database. + +> **Warning:** When using sync and import: +> - Don't edit the things you imported +> - Don't click to create new files (from imported nodes) +> - Don't delete imported node types + +## Enabling sync mode + +### Step 1: Open settings + +Open the Discourse Graph plugin settings: + +1. Open **Obsidian settings** (click the gear icon in the bottom-left corner, or press `Cmd/Ctrl + ,`) +2. Scroll down in the left sidebar to **community plugins** +3. Find **Discourse Graph** + +### Step 2: Reveal the admin panel + +The sync feature is located in a hidden **admin panel** tab that is not visible by default. + +1. While on the Discourse Graph settings page, press `Cmd + Shift + A` (Mac) or `Ctrl + Shift + A` (Windows/Linux) +2. A new **admin panel** tab will appear in the settings tab bar + +![Admin panel tab revealed](/docs/obsidian/sync-setting.png) + +### Step 3: Enable sync mode + +1. In the **admin panel** tab, find the **(BETA) Sync mode enable** toggle +2. Click the toggle to enable sync mode +3. Click **Save changes** +4. A confirmation notice will appear: "Admin panel settings saved" +5. The sync mode will initialize automatically, and you will see a notice: "Sync mode initialized successfully" + +Once enabled, your discourse nodes will begin syncing automatically to the Discourse Graph database. The plugin monitors file changes in your vault (with a short delay) and syncs them in the background. + +--- + +## Publishing a discourse node + +Publishing makes a synced discourse node available to other members of your group. This is how you share your work with collaborators. + +### Prerequisites + +Before publishing, make sure: + +- **Sync mode is enabled** (see above) +- **You are a member of a group.** Group membership is managed by your team administrator. The Discourse Graph team will ensure you are added to the appropriate group before you can publish. +- The discourse node you want to publish has a `nodeTypeId` in its frontmatter +- The discourse node has been **synced at least once** (it must have a `nodeInstanceId` in its frontmatter — this is assigned automatically after the first sync) + +### Steps to publish + +1. **Open the discourse node** you want to publish in the editor + +2. **Open the command palette** by pressing `Cmd/Ctrl + P` + +3. **Search for the publish command** by typing "Publish" and select **"Discourse Graph: Publish current node to lab space"** +![Publish command in palette](/docs/obsidian/publish-command.png) + +4. The plugin will: + - Publish the node to your group + - Sync any embedded assets (images, attachments) to the shared storage + - Update the node's frontmatter with a `publishedToGroups` field + +5. A confirmation notice will appear: **"Published"** +![Node published successfully](/docs/obsidian/publish-success.png) + +> **Tip:** If you see the message "Please sync the node first", wait a moment for the automatic sync to complete, or manually trigger a sync via the command palette using **"Discourse Graph: Sync discourse nodes to Supabase"**. +![Sync command](/docs/obsidian/sync-command.png) +--- + +## Importing discourse nodes from another space + +Importing allows you to bring published discourse nodes from other group members into your vault. + +### Steps to import + +1. **Open the command palette** by pressing `Cmd/Ctrl + P` + +2. **Search for the import command** by typing "Import" and select **"Discourse Graph: Import nodes from another space"** + +![Import command in palette](/docs/obsidian/import-command.png) + +3. The **import nodes** modal will open and begin loading available nodes from your groups. Once loaded, you will see a list of importable nodes **grouped by space**. Each space section shows the space name and available nodes. + +![Selecting nodes to import](/docs/obsidian/import-modal.png) + +4. The plugin will import each selected node and display a progress bar. Once complete, a confirmation notice will appear showing how many nodes were imported successfully. + +Imported nodes are saved in an `import/{spaceName}/` folder in your vault, preserving the original space organization. + +![Import location](/docs/obsidian/import-location.png) + +--- + +## Refreshing imported nodes + +After importing, you can fetch the latest content from the original sources to keep your imported nodes up to date. + +1. **Open the command palette** by pressing `Cmd/Ctrl + P` +2. Search for "Fetch" and select **"Discourse Graph: Fetch latest content from imported nodes"** +3. The plugin will check each imported node for updates and refresh any that have changed + +![Refreshing imported nodes](/docs/obsidian/refresh-imported.png) + +Alternatively, you can click the "Refresh" button in the Discourse Context panel. + +![Refresh button](/docs/obsidian/refresh-button.png) +--- + +## Summary of commands + +- **Sync discourse nodes to Supabase**: Manually sync all discourse nodes to the database +- **Publish current node to lab space**: Publish the active discourse node to your group +- **Import nodes from another space**: Open the import modal to browse and import shared nodes +- **Fetch latest content from imported nodes**: Refresh all imported nodes with the latest content + + +## Troubleshooting + +- **"Sync mode is not enabled"** — You need to enable sync mode in the admin panel first (see [Enabling sync mode](#enabling-sync-mode) above) +- **"Please sync the node first"** — The node hasn't been synced yet. Wait for automatic sync or trigger a manual sync +- **"You are not a member of any groups"** — You need to be added to a group before you can import nodes. Contact your team administrator +- **No importable nodes found** — Either no nodes have been published to your groups, or you have already imported all available nodes +- If you want to see more information about imported nodes, you can unhide frontmatter information in the setting panel +![Show frontmatter](/docs/obsidian/show-frontmatter.png) \ No newline at end of file diff --git a/apps/website/public/docs/obsidian/import-command.png b/apps/website/public/docs/obsidian/import-command.png new file mode 100644 index 000000000..78852ebeb Binary files /dev/null and b/apps/website/public/docs/obsidian/import-command.png differ diff --git a/apps/website/public/docs/obsidian/import-location.png b/apps/website/public/docs/obsidian/import-location.png new file mode 100644 index 000000000..4d960e7b2 Binary files /dev/null and b/apps/website/public/docs/obsidian/import-location.png differ diff --git a/apps/website/public/docs/obsidian/import-modal.png b/apps/website/public/docs/obsidian/import-modal.png new file mode 100644 index 000000000..d8bda94a3 Binary files /dev/null and b/apps/website/public/docs/obsidian/import-modal.png differ diff --git a/apps/website/public/docs/obsidian/publish-command.png b/apps/website/public/docs/obsidian/publish-command.png new file mode 100644 index 000000000..b411e9f91 Binary files /dev/null and b/apps/website/public/docs/obsidian/publish-command.png differ diff --git a/apps/website/public/docs/obsidian/publish-success.png b/apps/website/public/docs/obsidian/publish-success.png new file mode 100644 index 000000000..1ece5c52b Binary files /dev/null and b/apps/website/public/docs/obsidian/publish-success.png differ diff --git a/apps/website/public/docs/obsidian/refresh-button.png b/apps/website/public/docs/obsidian/refresh-button.png new file mode 100644 index 000000000..52b3f15c4 Binary files /dev/null and b/apps/website/public/docs/obsidian/refresh-button.png differ diff --git a/apps/website/public/docs/obsidian/refresh-imported.png b/apps/website/public/docs/obsidian/refresh-imported.png new file mode 100644 index 000000000..6e0a2acc0 Binary files /dev/null and b/apps/website/public/docs/obsidian/refresh-imported.png differ diff --git a/apps/website/public/docs/obsidian/show-frontmatter.png b/apps/website/public/docs/obsidian/show-frontmatter.png new file mode 100644 index 000000000..7c67b42cf Binary files /dev/null and b/apps/website/public/docs/obsidian/show-frontmatter.png differ diff --git a/apps/website/public/docs/obsidian/sync-command.png b/apps/website/public/docs/obsidian/sync-command.png new file mode 100644 index 000000000..bb00feb41 Binary files /dev/null and b/apps/website/public/docs/obsidian/sync-command.png differ diff --git a/apps/website/public/docs/obsidian/sync-setting.png b/apps/website/public/docs/obsidian/sync-setting.png new file mode 100644 index 000000000..013302d56 Binary files /dev/null and b/apps/website/public/docs/obsidian/sync-setting.png differ