From 22f8cb2cd31cee6a82aca0c1f2dc258bc4e0f870 Mon Sep 17 00:00:00 2001 From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com> Date: Wed, 22 Apr 2026 00:24:26 +0530 Subject: [PATCH] feat: enhance obsidian connector doc and add notes for migration from legacy obsidian connector --- .../components/obsidian-config.tsx | 56 +++++++++++++++++-- .../content/docs/connectors/index.mdx | 2 +- .../content/docs/connectors/obsidian.mdx | 31 +++++----- 3 files changed, 70 insertions(+), 19 deletions(-) diff --git a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/components/obsidian-config.tsx b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/components/obsidian-config.tsx index cfe6f0574..33a7110c0 100644 --- a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/components/obsidian-config.tsx +++ b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/components/obsidian-config.tsx @@ -1,11 +1,13 @@ "use client"; -import { Info } from "lucide-react"; +import { AlertTriangle, Info } from "lucide-react"; import { type FC, useEffect, useMemo, useState } from "react"; import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert"; import { connectorsApiService, type ObsidianStats } from "@/lib/apis/connectors-api.service"; import type { ConnectorConfigProps } from "../index"; +const OBSIDIAN_SETUP_DOCS_URL = "/docs/connectors/obsidian"; + function formatTimestamp(value: unknown): string { if (typeof value !== "string" || !value) return "—"; const d = new Date(value); @@ -22,17 +24,61 @@ function formatTimestamp(value: unknown): string { * web UI doesn't expose a Name input or a Save button for Obsidian (the * latter is suppressed in `connector-edit-view.tsx`). * - * Renders plugin stats when connector metadata comes from the plugin. - * If metadata is missing or malformed, we show a recovery hint. + * Renders one of three modes depending on the connector's `config`: + * + * 1. **Plugin connector** (`config.source === "plugin"`) — read-only stats + * panel showing what the plugin most recently reported. + * 2. **Legacy server-path connector** (`config.legacy === true`, set by the + * migration) — migration warning + docs link + explicit disconnect data-loss + * warning so users move to the plugin flow safely. + * 3. **Unknown** — fallback for rows that escaped migration; suggests a + * clean re-install. */ export const ObsidianConfig: FC = ({ connector }) => { const config = (connector.config ?? {}) as Record; + const isLegacy = config.legacy === true; const isPlugin = config.source === "plugin"; + if (isLegacy) return ; if (isPlugin) return ; return ; }; +const LegacyBanner: FC = () => { + return ( +
+ + + + Sync stopped, install the plugin to migrate + + + This Obsidian connector used the legacy server-path scanner, which has been removed. The + notes already indexed remain searchable, but they no longer reflect changes made in your + vault. + + + +
+

Migration required

+

+ Follow the{" "} + + Obsidian setup guide + {" "} + to reconnect this vault through the plugin. +

+

+ Heads up: Disconnect also deletes every document this connector previously indexed. +

+
+
+ ); +}; + const PluginStats: FC<{ config: Record }> = ({ config }) => { const vaultId = typeof config.vault_id === "string" ? config.vault_id : null; const [stats, setStats] = useState(null); @@ -114,8 +160,8 @@ const UnknownConnectorState: FC = () => ( Unrecognized config - This connector is missing plugin metadata. Delete it, then reconnect your vault from the - SurfSense Obsidian plugin so sync can resume. + This connector has neither plugin metadata nor a legacy marker. It may predate migration — + you can safely delete it and re-install the SurfSense Obsidian plugin to resume syncing. ); diff --git a/surfsense_web/content/docs/connectors/index.mdx b/surfsense_web/content/docs/connectors/index.mdx index e3d06aa3c..ef8d214ef 100644 --- a/surfsense_web/content/docs/connectors/index.mdx +++ b/surfsense_web/content/docs/connectors/index.mdx @@ -105,7 +105,7 @@ Connect SurfSense to your favorite tools and services. Browse the available inte /> ** in SurfSense. +4. Paste your SurfSense API token from the user settings section. +5. Paste your Server URL in the plugin setting: either your SurfSense main domain (if `/api/v1` rewrites are enabled) or your direct backend URL. +6. Choose the Search Space in the plugin, then the first sync should run automatically. +7. Confirm the connector appears as **Obsidian — <vault>** in SurfSense. - - You do not create or configure a vault path in the web UI. The connector row is created automatically when the plugin calls `/api/v1/obsidian/connect`. +## Migrating from the legacy connector + +If you previously used the legacy Obsidian connector architecture, migrate to the plugin flow: + +1. Delete the old legacy Obsidian connector from SurfSense. +2. Install and configure the SurfSense Obsidian plugin using the quick start above. +3. Run the first plugin sync and verify the new **Obsidian — <vault>** connector is active. + + + Deleting the legacy connector also deletes all documents that were indexed by that connector. Always finish and verify plugin sync before deleting the old connector. -## Self-hosted notes - -- Use your public or LAN backend URL that your Obsidian device can reach. -- No Docker bind mount for the vault is required. -- If your instance is behind TLS, ensure the URL/certificate is valid for the device running Obsidian. - ## Troubleshooting **Plugin connects but no files appear** @@ -50,6 +51,10 @@ This works for cloud and self-hosted deployments, including desktop and mobile c - Trigger a manual sync from the plugin settings. - Confirm your API token is valid and not expired. +**Self-hosted URL issues** +- Use a public or LAN backend URL that your Obsidian device can reach. +- If your instance is behind TLS, ensure the URL/certificate is valid for the device running Obsidian. + **Unauthorized / 401 errors** - Regenerate and paste a fresh API token from SurfSense. - Ensure the token belongs to the same account and workspace you are syncing into.