1# obsidian plugin
2
3build an Obsidian community plugin as a marketing/distribution channel. no signup required — plugin reads file metadata directly from xattrs set by FileProvider.
3Obsidian community plugin for sublimated. reads file metadata directly from xattrs set by FileProvider. no signup required for core features.
4
5consistency rule: VS Code plugin (src/vscode-sublimated/, v0.3.5, 2,951 LOC) is the reference implementation. both plugins must show the same information in the same format, adapted to each platform's UI. when adding features to either plugin, check the other for parity.
5consistency rule: VS Code plugin (src/vscode-sublimated/) is the reference implementation. both plugins must show the same information in the same format, adapted to each platform's UI.
6
7macOS only for now. iOS later. no Windows/Linux — sublimated itself is macOS/iOS only.
8
9related docs (in main sublimated repo):
8- https://sublimated.com/sublimated/docs/MARKETING/OBSIDIAN — plugin ideas, submission requirements, promotion channels, competitive research
9- https://sublimated.com/sublimated/docs/MARKETING/ZED_LANGUAGE_SERVER — language server design (shared API endpoints, feature set, comment anchoring)
10- https://sublimated.com/sublimated/docs/SDK/FILEPROVIDER_DATA_MODEL — FileProvider data model and sync status
10- https://sublimated.com/sublimated/docs/MARKETING/OBSIDIAN — plugin ideas, submission, promotion, competitive research
11- https://sublimated.com/sublimated/docs/MARKETING/ZED_LANGUAGE_SERVER — shared API endpoints, feature set
12- https://sublimated.com/sublimated/docs/SDK/FILEPROVIDER_DATA_MODEL — FileProvider data model
13- https://sublimated.com/sublimated/docs/DEV/OPEN_IN — "open in" deeplink design
12- https://sublimated.com/sublimated/docs/KNOWLEDGE_BASE/OBSIDIAN — integration strategy, pain points, features
14- https://sublimated.com/sublimated/docs/KNOWLEDGE_BASE/OBSIDIAN — integration strategy, pain points
15
16## xattrs
17
18FileProvider writes these on every synced file (all implemented and working):
11 unmodified lines
30- `com.sublimated.modified-at#PS` — server-side timestamp of last change
31
32plugin reads these directly from filesystem. no API calls, no token, no signup for core features.
33
32## URI scheme — DONE
34## done
35
34`sublimated://open-in?tool=obsidian&type=file&path=blog/post.md` — implemented in URLHandler.swift. Obsidian added to OPEN IN section in SharePopup.astro. open on web (local -> web) reads `com.sublimated.url` xattr and opens browser.
36- status bar (basic): text showing version, sync status, author. click to open on web. updates on file change
37- version history sidebar: version list with number/author/timestamp, "view on web" link
38- view on web: command palette + status bar click opens sublimated.com URL from xattr
39- copy web link: command to copy sublimated.com URL to clipboard
40- open in Obsidian: URI handler (`obsidian://sublimated?action=open&file=path`), OAuth token flow (`action=auth`), URLHandler.swift, SharePopup.astro OPEN IN section
41- welcome modal: first-run with setup steps, links, hasSeenWelcome flag
42- settings page: API token input, test connection, workspace detection (.sbl/ folder), links
43
36## v1 scope
44## todo: immediate (VS Code parity)
45
38### 1. sync status bar — DONE (basic), needs update
46### status bar update
47
40done: basic text status bar, click to open on web, updates on file change
41missing (VS Code has these):
42- sync status icons: checkmark synced, up-arrow uploading, down-arrow downloading, ! error, warning conflict
43- visibility indicator: globe public, people shared, lock private
44- branch display (hide when `main`)
45- AI agent prefix: `by AI: name` when `modifiedByType === "ai_agent"` (vs plain `by name`)
46- `visibility` field missing from Obsidian's FileMetadata type (VS Code has 13 fields, Obsidian has 12)
47- target format: `sublimated: v12 · checkmark synced · by anton · feature-x · globe` (matches VS Code)
48current: `sublimated: v12 · synced · by anton`
49target: `sublimated: v12 · ✓ synced · by anton · feature-x · 🌐` (matches VS Code)
50
49### 2. version history — DONE (basic), needs update
51- add sync status icons: ✓ synced, ↑ uploading, ↓ downloading, ! error, ⚠ conflict
52- add visibility indicator: 🌐 public, 👥 shared, 🔒 private
53- add branch display (hide when `main`)
54- add AI agent prefix: `by AI: name` when `modifiedByType === "ai_agent"`
55- add `visibility` field to FileMetadata in xattr.ts (VS Code has it, Obsidian doesn't yet)
56
51done: sidebar view, version list with number/author/timestamp, "view on web" link
52missing (VS Code has these):
53- group versions by day: "Today", "Yesterday", "X days ago", "Mon DD"
54- show commit message per version
55- diff viewer (click version to see diff against current)
57### cache layer
58
57### 3. view on web — DONE
59VS Code has `cache.ts` with in-memory cache. Obsidian re-reads all xattrs on every file switch.
60- add TTL-based cache for xattr reads (avoid shelling out `xattr` 12 times per tab switch)
61- cache API responses (folder context, file context)
62- invalidate on file save events
63
59done: command palette + status bar click opens sublimated.com URL from xattr
64### workspace detection
65
61### 4. open in Obsidian (from sublimated.com) — DONE (plugin side)
66done: checks for `.sbl/` folder
67missing:
68- CloudStorage mount path detection: `~/Library/CloudStorage/Sublimated-{space}/` (prod) and `~/Library/CloudStorage/sublimated-dev-{space}/` (dev)
69- `.sbl/config` or `.sbl/config.yml` parsing for space slug
70- detection result: space slug, folder path, root path, detection mode
71
63done: URI handler for `obsidian://sublimated?action=open&file=path` + OAuth token `action=auth`
64not done: web UI changes (add Obsidian to SharePopup.astro OPEN IN section), macOS app URLHandler.swift
72### file explorer decorations
73
66### 5. welcome modal — DONE
74VS Code shows sync status badges on files in the explorer tree. Obsidian equivalent:
75- use FileExplorerPlugin API or CSS-based decorations on file tree items
76- read sync-status xattr per file, show badge/icon next to filename
77- ✓ synced, ↑ uploading, ↓ downloading, ! error, ⚠ conflict
78
68done: first-run modal with setup steps, links, hasSeenWelcome flag
79### version history improvements
80
70### 6. settings page — DONE (basic)
81- group versions by day: "Today", "Yesterday", "X days ago", "Mon DD"
82- show commit message per version
83- diff viewer (click version to see diff against current)
84
72done: API token input, test connection, workspace detection (.sbl/ folder), links
73missing: OAuth sign-in button (see oauth-signin section below)
85### OAuth sign-in
86
75### 7. file explorer decorations — NEW (VS Code has this)
87add one-click sign-in instead of pasting API tokens:
881. user clicks "Sign in with sublimated" in settings
892. browser opens `id.sublimated.com/auth/obsidian`
903. user signs in, server redirects to `obsidian://sublimated?action=auth&token={token}`
914. plugin stores token, API calls use `Authorization: Bearer {token}`
92
77VS Code shows sync status badges on files in the explorer tree:
78- checkmark synced (no color), up-arrow uploading (blue), down-arrow downloading (blue), ! error (red), warning conflict (red)
79- Obsidian equivalent: FileExplorerPlugin API or CSS-based decorations on file tree items
80- read sync-status xattr per file, show badge/icon next to filename
93plugin-side: `main.ts` already handles the URI. settings.ts needs a "Sign in" button.
94server-side: add GET `/auth/obsidian` route to id.sublimated.com. bearer plugin already set up.
95keep manual API token input as fallback. token should be long-lived.
96
82### 8. cache layer — NEW (VS Code has this)
97## todo: later
98
84VS Code has `cache.ts` (85 lines) with in-memory cache for xattr reads and API responses. Obsidian plugin currently re-reads all xattrs on every file switch with no caching.
85- add TTL-based cache for xattr reads (avoid shelling out `xattr` 13 times on every tab switch)
86- cache API responses (folder context, file context)
87- invalidate on file save events
99### comments and threads
100
89### 9. workspace detection — needs update
101VS Code has full CommentController (513 lines) with gutter "+", threading, resolve, reactions.
102
91done: checks for `.sbl/` folder in vault root
92missing (VS Code has these):
93- CloudStorage mount path detection: `~/Library/CloudStorage/Sublimated-{space}/` (prod) and `~/Library/CloudStorage/sublimated-dev-{space}/` (dev)
94- `.sbl/config` or `.sbl/config.yml` parsing for space slug (VS Code reads plain text `space=...` or YAML `space: ...`)
95- detection result should include: space slug, folder path, root path, detection mode (cloud-storage vs sbl-config vs sbl-folder)
96
97### 10. comments and threads (VS Code has full implementation)
98
99VS Code: `comments/controller.ts` (513 lines) — native CommentController with gutter "+", threading, resolve/reopen, reactions, anchor resolution (text search -> line number -> top of file).
100
103Obsidian equivalent:
102- sidebar view: list all comments on the active file (anchored to specific text)
103- each comment shows: author, timestamp, quoted text, resolved/unresolved status
104- threaded replies shown inline under parent comment
105- clicking a comment scrolls to the anchored text in the editor
106- anchor resolution: same cascade as LSP — Loro cursors -> PM JSON blockId -> text search (quote+prefix+suffix) -> blockIndex -> orphaned
107- unresolved comments shown as notices/callouts or gutter markers
108- "resolve" button on each comment (API call, just a toggle)
109- "reply on sublimated.com" button opens browser at the thread
110- new comment creation happens on sublimated.com (no input forms in plugin)
111- API endpoint: GET /v1/spaces/{slug}/items/{id}/context (returns comments with FileAnchor)
104- sidebar view: list comments anchored to specific text
105- author, timestamp, quoted text, resolved/unresolved status
106- threaded replies inline
107- clicking a comment scrolls to anchored text
108- anchor resolution: text search (quote+prefix+suffix) -> blockIndex -> orphaned
109- "resolve" button (API call)
110- new comment creation on sublimated.com (no input forms in plugin)
111- API: GET /v1/spaces/{slug}/items/{id}/context
112
113### 11. reactions
113### reactions
114
115- show reactions on file or section level in sidebar or status bar
116- hover or click to see who reacted
117- adding reactions happens on sublimated.com — plugin links to web UI
118- reactions are anchored to text via FileAnchor (same as comments)
116- hover/click to see who reacted
117- adding reactions on sublimated.com — plugin links to web UI
118
120### 12. section-level history (VS Code has CodeLens equivalent)
119### section-level history
120
122VS Code: `codelens.ts` (157 lines) — CodeLens above headings showing "last: {author}, {timeAgo}" and version/comment counts. Obsidian has no CodeLens, so use different UI.
123
121VS Code has CodeLens above headings. Obsidian has no CodeLens.
122- command palette: "sublimated: show section history"
125- for each heading in the current file, show: last author, edit count, actor count
126- sections derived from AST (heading boundaries)
127- useful for long docs — see which sections changed recently and by whom
128- API provides this via file context endpoint (sections array with lastAuthor, editCount, actorCount)
123- per heading: last author, edit count, actor count
124- API: file context endpoint (sections array)
125
130### 13. hover and diagnostics (VS Code has these, Obsidian needs equivalents)
126### hover and diagnostics
127
132VS Code: `hover.ts` (163 lines) — wikilink hovers showing file info (versions, comments, backlinks). `diagnostics.ts` (104 lines) — broken link warnings, unresolved comment indicators.
133
128VS Code: wikilink hovers (versions, comments, backlinks), broken link warnings, unresolved comment indicators.
129Obsidian equivalent:
135- reading view: render broken `[[links]]` with visual indicator (strikethrough, red text)
136- sidebar or notice: list unresolved comments with context
137- hover on wikilinks (if Obsidian API supports it): show version count, last author, comment count
130- render broken `[[links]]` with visual indicator
131- list unresolved comments in sidebar
132- hover on wikilinks if Obsidian API supports it
133
139### 14. block attribution (PM JSON)
134### block attribution (PM JSON)
135
141- sidebar or hover: per-paragraph attribution
142- each block (PM JSON blockId) shows: original author, creation date, edit count, last editor
136- per-paragraph attribution: original author, creation date, edit count, last editor
137- requires PM JSON representation (block IDs stable across edits)
138
145### 15. character-level attribution (Loro)
139### character-level attribution (Loro)
140
147- deeper attribution: percentage breakdown of who wrote what in a paragraph
148- distinguishes human vs AI edits
149- Loro CRDT tracks character-level authorship
150- could render as colored highlights in reading view (different color per author)
141- percentage breakdown of who wrote what
142- human vs AI edits
143- colored highlights in reading view per author
144
152### 16. @mention rendering
145### @mention rendering
146
154- render `@username` as styled inline elements (colored, linked)
155- clicking @mention opens that user's profile on sublimated.com
156- in editing mode: autocomplete dropdown when typing `@` (users with access to the space)
147- render `@username` as styled inline elements
148- autocomplete when typing `@`
149- API provides user list via folder context endpoint
150
159### 17. stale content detection
151### stale content detection
152
161- embedded files (`![[data.csv]]`, `![[report.md]]`) checked for staleness
162- if referenced file changed since current file was last edited, show notice
163- uses content-hash xattr on referenced file vs stored hash at embed time
153- check embedded files (`![[data.csv]]`) for staleness via content-hash xattr
154- show notice if referenced file changed since current file was last edited
155
165### 18. activity tracking
156### activity tracking
157
167- plugin sends editor events to API as they happen (same as LSP):
168  - file opened, content changed (with position info), file saved, file closed
169- API endpoint: POST /v1/spaces/{slug}/items/{id}/events
170- server computes section-level focus data from change positions
171- powers writing analytics: time spent editing vs reading per section
158- send editor events to API: file opened, changed, saved, closed
159- API: POST /v1/spaces/{slug}/items/{id}/events
160- powers writing analytics and session tracking
161
173### 19. backlinks
162### backlinks
163
175- sidebar view: list all files that link to the current file via `[[wikilinks]]`
176- each backlink shows: file path, link context (surrounding text), version count, last author
177- clicking a backlink opens that file
178- data from item_dependencies table (dep_type = 'links_to')
179- Obsidian has native backlinks but sublimated adds: version count, author info, comment count per linking file
164- sidebar: files linking to current file via `[[wikilinks]]`
165- sublimated adds over native Obsidian backlinks: version count, author info, comment count
166
181### 20. broken link detection
167### broken link detection
168
183- `[[links]]` pointing to nonexistent files flagged in reading view or sidebar
184- offer to create the missing file
185- also detects broken content embeds (`![[missing.png]]`)
186- uses folder context items list to check existence
169- flag `[[links]]` to nonexistent files
170- offer to create missing file
171- detect broken embeds (`![[missing.png]]`)
172
188## implementation work
173## API endpoints
174
190### plugin — exists, needs updates
175plugin uses these (shared with VS Code extension and language server):
176- GET /v1/spaces/:slug/items/:folderId/context — folder context (items, links, users)
177- GET /v1/spaces/:slug/items/:id/context — file context (comments, versions, sections, blocks, attribution, reactions)
178- POST /v1/spaces/:slug/items/:id/events — editor events
179- POST /v1/spaces/:slug/messages — comment resolve
180
192existing: TypeScript + esbuild, main.ts + manifest.json + styles.css, plugin ID `sublimated`
193existing: xattr.ts (reads 12 attrs), api.ts (versions + test connection), settings.ts, version-view.ts, welcome-modal.ts
194
195immediate work (VS Code parity for status bar):
196- add `visibility` to FileMetadata in xattr.ts (13th field, matching VS Code)
197- update status bar format to match VS Code: icons, visibility, branch, AI prefix
198- add cache layer (new cache.ts) for xattr reads and API responses
199- update workspace detection: CloudStorage mount path, `.sbl/config` parsing
200- add file explorer decorations (sync badges)
201
202later work:
203- comments sidebar (equivalent of VS Code's CommentController)
204- section-level info (equivalent of VS Code's CodeLens)
205- hover/diagnostics (equivalent of VS Code's hover + diagnostics providers)
206- API client: expand to match VS Code's api.ts (folder context, file context, editor events, comments)
207
208### FileProvider changes (sdk/swift/)
209- add 4 new xattrs: sync-status, space, branch, modified-at
210- add visibility xattr (already in VS Code constants.ts but needs FileProvider to set it)
211- set sync-status during upload/download/error operations in SublimatedFileProviderExtension.swift
212
213### web UI changes (sublimated.com worker)
214- add Obsidian to OPEN IN tools in SharePopup.astro (with Obsidian icon)
215- detect `.obsidian/` folder presence to show/hide the button
216
217### macOS app changes
218- add `obsidian` case to URLHandler.swift tool router
219- resolve path -> `obsidian://open?vault={vault}&file={path}`
220
221### API (api.sublimated.com)
222- same endpoints as language server:
223  - GET /v1/spaces/:slug/items/:folderId/context — folder context (items, links, users)
224  - GET /v1/spaces/:slug/items/:id/context — file context (comments, versions, sections, blocks, attribution, reactions, session)
225  - POST /v1/spaces/:slug/items/:id/events — editor events (open, change, save, close)
226  - POST /v1/spaces/:slug/messages — comment resolve
227- plugin uses folder context on vault open, file context on note open
228- editor events sent as user interacts (same as LSP)
229
230## OAuth sign-in
231
232add OAuth redirect flow so users can sign in with one click instead of pasting API tokens.
233
234how it works:
2351. user clicks "Sign in with sublimated" in plugin settings
2362. plugin opens browser to `id.sublimated.com/auth/obsidian`
2373. user signs in (GitHub, Apple, email — whatever id.sublimated.com supports)
2384. after sign-in, server redirects to `obsidian://sublimated?action=auth&token={sessionToken}`
2395. plugin URI handler catches the redirect, stores the token
2406. API calls use `Authorization: Bearer {token}` — same as the macOS app
241
242server-side: add GET `/auth/obsidian` route to id.sublimated.com. bearer plugin already set up.
243plugin-side: `main.ts` already handles `obsidian://sublimated?action=auth&token=...` in handleUri(). settings.ts needs a "Sign in" button that opens the browser URL.
244
245notes:
246- keep manual API token input as fallback
247- token should be long-lived (months/never) since there's no session refresh in Obsidian
248- consider scoped access token (read-only, specific space) vs full session
249
181## submission
182
252- source of truth: https://sublimated.com/sublimated/code/obsidian (dogfooded on our own platform)
253- GitHub mirror for submission: https://github.com/sublimates/obsidian — Obsidian community plugins require a GitHub repo URL in community-plugins.json. keep sublimated.com as primary, push to GitHub for releases
183- source of truth: https://sublimated.com/sublimated/code/obsidian
184- GitHub mirror for submission: https://github.com/sublimates/obsidian — required for Obsidian community plugins. keep sublimated.com as primary, push to GitHub for releases
185- PR to obsidianmd/obsidian-releases adding entry to community-plugins.json
255- macOS only for now (iOS later). no Windows/Linux support planned
186- automated validation + manual review
187- README with screenshots, description, setup instructions
258- stale PR policy: 30 days warning, 45 days auto-close
188
260## platform support
261
262- macOS only for now. sublimated's FileProvider and xattrs are macOS-specific
263- iOS later (Obsidian has an iOS app, FileProvider works on iOS too)
264- no Windows/Linux support planned — sublimated itself is macOS/iOS only
265
189## open questions
190
191### git-only users (no FileProvider)
192
270what if someone clones via `git clone https://sublimated.com/slug.git` and opens the clone as an Obsidian vault? no FileProvider means no xattrs, no sync status, no `.sbl/` detection. options:
271- plugin detects `.git/` with sublimated remote URL instead of `.sbl/` folder
272- shell out to `git log`, `git status`, `git diff` to show version/sync info
273- show unsynced changes by running `git status` — dirty files = unsynced
274- push/pull via git commands from within the plugin
275- this is a separate mode from FileProvider mode — need to detect which one we're in
193what if someone clones via `git clone https://sublimated.com/slug.git` and opens as vault? no xattrs, no `.sbl/`. options:
194- detect `.git/` with sublimated remote URL
195- shell out to `git log`, `git status`, `git diff` for version/sync info
196- auto-push on save (opt-in, with interval, debounce)
197- separate mode from FileProvider mode
198
277### auto-push
199### sessions, checkpoints, focus mode
200
279should the plugin offer auto-push in settings? when user saves a file:
280- run `git add . && git commit -m "auto" && git push` in background
281- or debounce: push every N minutes if there are uncommitted changes
282- risk: merge conflicts if someone else pushes. how to handle?
283- could be opt-in toggle in settings: "auto-sync" on/off, with interval selector
284- only makes sense for git-clone mode — FileProvider already syncs automatically
201macOS app tracks editing sessions with checkpoints and attribution. Obsidian surface:
202- session sidebar: elapsed time, word count delta, checkpoint list
203- checkpoints: auto-snapshot at intervals or on save, "restore checkpoint" command
204- focus mode: start/stop from command palette, track uninterrupted writing time
205- differentiator vs plain Obsidian
206
286### sessions, checkpoints, and focus mode
287
288the macOS app tracks editing sessions with checkpoints, focus mode, and attribution (human vs AI edits). how does this surface in Obsidian?
289- session sidebar: show active session with elapsed time, word count delta, checkpoint list
290- checkpoints: auto-snapshot at intervals or on save. "restore checkpoint" command to revert to a point-in-time
291- focus mode: start/stop focus session from command palette. track uninterrupted writing time, words written
292- attribution: show which parts were edited by human vs AI agent (inline highlights or gutter marks)
293- this is a differentiator vs plain Obsidian — writing analytics and session tracking built into the sync layer
294
207### sharing and access visibility
208
297shared/public folders and files should be visible in Obsidian:
209- status bar: show sharing status alongside sync info
299- file explorer decorations: small icon (people, globe) next to shared/public files and folders
300- command: "sublimated: show access" — opens panel showing who has access, roles, visibility
301- needs: `com.sublimated.visibility#PS` xattr (private/shared/public) and optionally `com.sublimated.shared-with#PS`
302- API endpoint: `GET /v1/items/{id}/access` for detailed access panel
210- file explorer: icons next to shared/public files
211- command: "sublimated: show access" — who has access, roles, visibility
212- needs: `com.sublimated.visibility#PS` xattr, `GET /v1/items/{id}/access` endpoint
213
214## promotion
215
306- r/ObsidianMD (https://www.reddit.com/r/ObsidianMD/)
216- r/ObsidianMD
217- Obsidian Forum "Share & showcase"
218- Obsidian Discord #updates
219- twitter #ObsidianMD
220- blog post: "how to use Obsidian with sublimated"