255 lines
6.7 KiB
Markdown
255 lines
6.7 KiB
Markdown
---
|
|
title: "LinkdingSync - Design Document"
|
|
---
|
|
|
|
# LinkdingSync Extension Design Document
|
|
|
|
## Overview
|
|
|
|
`linkdingsync` is a Firefox browser extension that synchronizes bookmarks with a self-hosted Linkding instance. It supports folder hierarchy, bidirectional sync, and configurable sync modes for different use cases (personal, work, shared bundles).
|
|
|
|
## Project Location
|
|
|
|
```
|
|
MyWorkspace/Linkding Browser Extension/bookmark-sync/
|
|
```
|
|
|
|
## Extension Name
|
|
|
|
**`linkdingsync`** - Firefox extension name (manifest.json)
|
|
|
|
---
|
|
|
|
## 1. Data Storage Structure
|
|
|
|
### `config.json` (stored in web storage)
|
|
|
|
```json
|
|
{
|
|
"serverUrl": "https://links.blabber1565.com/api",
|
|
"apiKey": "your-api-token-here",
|
|
"bundleId": null,
|
|
"bundleName": null,
|
|
"syncMode": "bi-directional",
|
|
"autoGenerateTags": false,
|
|
"syncTimestamp": "2026-05-06T04:38:26-05:00"
|
|
}
|
|
```
|
|
|
|
### Storage Areas
|
|
|
|
- **`window.storage.local`** - Persistent data per browser profile
|
|
- **`window.storage.session`** - Temporary session data
|
|
|
|
### Stored Data Structure
|
|
|
|
```json
|
|
{
|
|
"serverUrl": "https://links.blabber1565.com/api",
|
|
"apiKey": "your-api-token-here",
|
|
"bundleId": 5,
|
|
"bundleName": "My Browser Bundle",
|
|
"syncMode": "bi-directional",
|
|
"autoGenerateTags": false,
|
|
"lastSyncTimestamp": 1715012345678,
|
|
"bookmarksVersion": 1234567890
|
|
}
|
|
```
|
|
|
|
### Sync Mode Values
|
|
|
|
| Value | Description | Conflict Resolution |
|
|
|-------|-------------|---------------------|
|
|
| `bi-directional` | Replicate both directions; keep both versions | Keep both versions |
|
|
| `write-only` | Browser is authoritative source | Update Linkding from browser |
|
|
| `read-only` | Linkding is authoritative source | Download from Linkding, never upload |
|
|
|
|
**Default:** `bi-directional`
|
|
|
|
---
|
|
|
|
## 2. Bookmark Notes Structure
|
|
|
|
The `notes` field uses a JSON-compatible structure that remains human-readable:
|
|
|
|
```json
|
|
{
|
|
"path": "Work/Resources/Development",
|
|
"userNotes": "Development resources and references",
|
|
"autoTags": [
|
|
{"name": "Work"},
|
|
{"name": "Resources"},
|
|
{"name": "Development"}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Display Format
|
|
- Only show `userNotes` in the UI
|
|
- `path` and `autoTags` are hidden from regular users
|
|
|
|
### Auto-generate Tags Setting
|
|
- **Default:** `false` (disabled)
|
|
- When `true`, extracts folder names from `path` as tag suggestions
|
|
- User must organize folders intentionally for tag auto-generation to work correctly
|
|
|
|
---
|
|
|
|
## 3. Bundle Naming
|
|
|
|
- User-defined bundle names via config UI
|
|
- Examples: "My Personal Bookmarks", "Work Resources", "Project Collection"
|
|
- Extension prompts for missing config (server URL, API key, bundle selection) on first run
|
|
|
|
---
|
|
|
|
## 4. Extension File Structure
|
|
|
|
```
|
|
bookmark-sync/
|
|
├── manifest.json # Firefox manifest v2
|
|
├── popup.html # Main extension popup
|
|
├── popup.css # Popup styling
|
|
├── popup.js # Popup UI logic
|
|
├── background.html # Settings/config page
|
|
├── background.js # Service worker
|
|
├── storage.js # Web storage helpers
|
|
├── utils/
|
|
│ ├── bookmark.js # Bookmark manipulation
|
|
│ ├── notes-parser.js # Parse/write notes structure
|
|
│ ├── sync.js # Sync logic (add, delete, update)
|
|
│ └── conflict-resolver.js # Handle sync conflicts
|
|
└── icons/
|
|
├── 48.svg # 48x48 icon
|
|
└── 96.svg # 96x96 icon
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Key Features
|
|
|
|
### Popup UI
|
|
- Quick bookmark add with optional notes
|
|
- Sync status indicator
|
|
- Settings button → opens config page
|
|
|
|
### Config Page (`background.html`)
|
|
- Server URL input (default: `links.blabber1565.com`)
|
|
- API key input (with "Get from Linkding Settings" guidance)
|
|
- Bundle selection dropdown (with "Create new bundle" button)
|
|
- Sync mode selector (`bi-directional` | `write-only` | `read-only`)
|
|
- Auto-generate tags toggle
|
|
- Sync last timestamp (human-readable with timezone)
|
|
- Manual sync button
|
|
- Reset config button
|
|
|
|
### Background Service
|
|
- Monitor bookmark events (add, remove, modify)
|
|
- Perform sync operations with Linkding API
|
|
- Cache recent API responses
|
|
- Handle errors and show notifications
|
|
|
|
---
|
|
|
|
## 6. Sync Logic Flow
|
|
|
|
```
|
|
1. Browser bookmark change detected
|
|
↓
|
|
2. Check syncMode:
|
|
- read-only: download from Linkding only
|
|
- write-only: sync to Linkding only
|
|
- bi-directional: sync both directions
|
|
↓
|
|
3. For updates (same URL, different folder):
|
|
- Store both versions with different notes
|
|
- User must manually de-dupe later
|
|
↓
|
|
4. For new bookmarks:
|
|
- Check if URL already in Linkding
|
|
- If no → create new bookmark
|
|
- If yes + different URL → create new bookmark
|
|
- If yes + same URL → update title, description, notes
|
|
↓
|
|
5. For deletions:
|
|
- write-only → delete from Linkding
|
|
- read-only → ignore (keep Linkding version)
|
|
- bi-directional → delete from Linkding
|
|
```
|
|
|
|
---
|
|
|
|
## 7. API Endpoints Used
|
|
|
|
### Authentication
|
|
```
|
|
Authorization: Token <Token>
|
|
```
|
|
|
|
### Bookmarks
|
|
- `GET /api/bookmarks/` - List bookmarks
|
|
- `POST /api/bookmarks/` - Create bookmark
|
|
- `PUT/PATCH /api/bookmarks/<id>/` - Update bookmark
|
|
- `DELETE /api/bookmarks/<id>/` - Delete bookmark
|
|
- `GET /api/bookmarks/check/?url=...` - Check if URL is already bookmarked
|
|
|
|
### Bundles
|
|
- `GET /api/bundles/` - List bundles
|
|
- `POST /api/bundles/` - Create bundle
|
|
- `PUT/PATCH /api/bundles/<id>/` - Update bundle
|
|
- `DELETE /api/bundles/<id>/` - Delete bundle
|
|
|
|
---
|
|
|
|
## 8. Implementation Plan
|
|
|
|
### Phase 1: Core Setup
|
|
- [ ] Create manifest.json
|
|
- [ ] Create popup HTML/CSS/JS
|
|
- [ ] Create background service worker
|
|
- [ ] Implement storage.js helpers
|
|
|
|
### Phase 2: Sync Logic
|
|
- [ ] Implement bookmark manipulation (bookmark.js)
|
|
- [ ] Implement notes parser (notes-parser.js)
|
|
- [ ] Implement sync logic (sync.js)
|
|
- [ ] Implement conflict resolution (conflict-resolver.js)
|
|
|
|
### Phase 3: Configuration UI
|
|
- [ ] Create config page (background.html)
|
|
- [ ] Implement config form logic
|
|
- [ ] Add API key guidance
|
|
|
|
### Phase 4: Polish
|
|
- [ ] Add icons
|
|
- [ ] Add error handling
|
|
- [ ] Add notifications
|
|
- [ ] Test sync scenarios
|
|
|
|
---
|
|
|
|
## 9. Resource Storage Location
|
|
|
|
All downloaded resources should be stored in `MyWorkspace` folder to avoid permission prompts:
|
|
|
|
```
|
|
MyWorkspace/Linkding Browser Extension/
|
|
├── bookmark-sync/ # Main extension directory
|
|
├── linkding/ # Cloned repo (if needed)
|
|
├── linkding-extension/ # Existing extension (if needed)
|
|
└── assets/ # Cached icons, screenshots
|
|
```
|
|
|
|
---
|
|
|
|
## 10. Version History
|
|
|
|
| Version | Date | Changes |
|
|
|---------|------|---------|
|
|
| 0.1.0 | 2026-05-06 | Initial design document |
|
|
|
|
---
|
|
|
|
## 11. Notes
|
|
|
|
This document should be referenced during implementation to ensure all requirements are met. Any deviations from this design should be documented here. |