1# obsidian plugin
2
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/) 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
9
10## xattrs
11
12FileProvider writes these on every synced file (all implemented and working):
13- `com.sublimated.version#PS` — version number (integer)
14- `com.sublimated.commit#PS` — last commit hash
15- `com.sublimated.url#PS` — web link (sublimated.com/anton/blog/readme_md)
16- `com.sublimated.content-hash#PS` — BLAKE3 hash
17- `com.sublimated.id#PS` — item ID (stable across renames)
18- `com.sublimated.created-by#PS` — original author name
19- `com.sublimated.modified-by#PS` — last author name
20- `com.sublimated.modified-by-type#PS` — person/ai_agent/bot
21- `com.sublimated.sync-status#PS` — synced/uploading/downloading/error
22- `com.sublimated.space#PS` — space slug
23- `com.sublimated.branch#PS` — current branch name
24- `com.sublimated.modified-at#PS` — server-side timestamp of last change
25
26plugin reads these directly from filesystem. no API calls, no token, no signup for core features.
27
28## official Obsidian APIs only
29
30this plugin only uses official, stable Obsidian APIs:
31- `addStatusBarItem()` — status bar text at the bottom
32- `addRibbonIcon()` — ribbon icon in the left sidebar
33- `registerView()` — custom sidebar panel (version history)
34- `addCommand()` — command palette entries
35- `registerObsidianProtocolHandler()` — URI handler
36- `addSettingTab()` — settings page
37
38Obsidian has no official API for file explorer badges, editor hover tooltips, or inline decorations. VS Code has `FileDecorationProvider`, `HoverProvider`, `CodeLens` etc — Obsidian doesn't. plugins that add file tree badges do it via DOM manipulation (finding internal `fileItems`, appending `<span>` elements, watching with MutationObserver). this is fragile — Obsidian can change its internal DOM structure in any update and badges break silently. not worth the maintenance cost.
39
40we deliberately skip these VS Code features that have no stable Obsidian equivalent:
41- file explorer sync badges (requires DOM hacking)
42- hover tooltips on wikilinks (no HoverProvider API)
43- CodeLens-style section attribution above headings (no CodeLens API)
44- inline editor decorations (no stable decoration API)
45
46## done
47
48- status bar: compact format `✓ synced v21 by anton` (sync icon + version + author + optional branch/visibility). click to open on web. hidden for non-sublimated files. updates on file change
49- version history sidebar: newest-first, grouped by day (Today / Yesterday / N days ago), with author, timestamp, commit message, per-version "view on web" link (`/~versions/v{number}`)
50- anonymous version history: public files fetch history without an API token. private files show a friendly "add token in settings" message on 401/403
51- ribbon icon: history button opens version sidebar
52- view on web: command palette + status bar click opens sublimated.com URL from xattr
53- copy web link: command to copy sublimated.com URL to clipboard
54- open in Obsidian: URI handler (`obsidian://sublimated?action=open&file=path`), OAuth token flow stub (`action=auth`)
55- welcome modal: first-run with setup steps, docs + source links, hasSeenWelcome flag
56- settings page: API token input, test connection, xattr-based workspace detection, links
57- xattr-based workspace detection: per-file, works for subfolder vaults and mixed vaults, no `.sbl/` folder required
58- all 13 xattr fields read: version, commit, url, contentHash, id, createdBy, modifiedBy, modifiedByType, syncStatus, space, branch, modifiedAt, visibility
59
60## todo
61
62### cache layer
63
64Obsidian re-reads all xattrs on every file switch (shells out `xattr` 13 times per tab switch).
65- add TTL-based in-memory cache for xattr reads
66- cache API responses (folder context, file context)
67- invalidate on file save events
68
69### workspace detection
70
71done: per-file xattr-based detection. any file with `com.sublimated.space#PS` identifies the workspace. works for subfolder vaults, works without `.sbl/`, works for mixed vaults.
72
73possible future additions:
74- CloudStorage mount path detection as a fallback for empty vaults: `~/Library/CloudStorage/Sublimated-{space}/` (prod) and `~/Library/CloudStorage/sublimated-dev-{space}/` (dev)
75- cache detected space slug across sessions so settings page shows it before any file is opened
76
77### version history improvements
78
79phase 1 (done):
80- [x] group versions by day: "Today", "Yesterday", "3 days ago", "Mon DD"
81- [x] commit messages render with improved visual layout
82- [x] "view on web" link per version using `/:path/~versions/v{number}` URL pattern
83- [x] newest version first (reverse server order)
84- [x] anonymous fetch for public files (no token needed)
85
86phase 2 (diff viewer, needs API):
87- click version to see content at that point (read-only tab)
88- API: `GET /v1/spaces/:slug/items/:id/diff?v1=X&v2=Y` already exists
89- API: `GET /v1/spaces/:slug/content/:hash` for fetching old version content
90- Obsidian Sync does NOT show diffs natively. community plugin (obsidian-version-history-diff) does but uses private APIs
91- our approach: open old version content in a read-only leaf, let user compare visually. no private APIs
92
93phase 3 (restore):
94- "restore this version" button per version
95- API: `POST /v1/spaces/:slug/items/:id/restore` with `{ from_version: number }` already exists
96
97### OAuth sign-in
98
99add one-click sign-in instead of pasting API tokens:
1001. user clicks "Sign in with sublimated" in settings
1012. browser opens `id.sublimated.com/auth/obsidian`
1023. user signs in, server redirects to `obsidian://sublimated?action=auth&token={token}`
1034. plugin stores token, API calls use `Authorization: Bearer {token}`
104
105plugin-side: `main.ts` already handles the URI. settings.ts needs a "Sign in" button.
106server-side: add GET `/auth/obsidian` route to id.sublimated.com. bearer plugin already set up.
107keep manual API token input as fallback. token should be long-lived.
108
109### comments sidebar
110
111VS Code has full CommentController (513 lines) with gutter "+", threading, resolve, reactions. Obsidian has no comment API — use a sidebar view (official `registerView()` API).
112
113- sidebar view: list comments anchored to specific text
114- author, timestamp, quoted text, resolved/unresolved status
115- threaded replies
116- clicking a comment scrolls to anchored text
117- "resolve" button (API call)
118- new comment creation on sublimated.com (link to web UI)
119- needs new API endpoint — comments are not currently exposed over HTTP
120
121## API endpoints
122
123plugin currently uses:
124- GET /v1/spaces/:slug/items/:id/versions — list version history (anonymous for public items, token required for private)
125
126public items work without an API token. the middleware in `src/shared/auth/authorize.ts` grants anonymous callers `{ read: true }` when folder visibility is public.
127
128## submission
129
130- source of truth: https://sublimated.com/sublimated/code/obsidian
131- GitHub live mirror: https://github.com/sublimates/obsidian — live-synced from sublimated.com
132- todo: PR to obsidianmd/obsidian-releases adding entry to community-plugins.json
133- todo: GitHub release workflow for plugin submission (main.js, manifest.json, styles.css as release assets)
134- todo: README with screenshots, description, setup instructions
135- automated validation + manual review by Obsidian team
136
137## promotion
138
139- r/ObsidianMD
140- Obsidian Forum "Share & showcase"
141- Obsidian Discord #updates
142- twitter #ObsidianMD
143- blog post: "how to use Obsidian with sublimated"