david/myworkspace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ad0b12b452cec94b24d2b01fdea5b754a16c6a17
myworkspace/Linkding Browser Extension/LinkdingSync/docs/design.md

7.9 KiB
Raw Blame History

LinkdingSync Extension - Design Document

Overview

linkdingsync is a Firefox browser extension that synchronizes bookmarks with a self-hosted Linkding instance. It supports folder hierarchy, bi-directional sync, configurable sync modes, and tag-based bundle management.

Project Location

Linkding Browser Extension/LinkdingSync/

Extension Name

linkdingsync - Firefox extension name (manifest.json)

1. Data Storage Structure

Configuration (stored in browser.storage.local)

{
  "serverUrl": "https://links.blabber1565.com",
  "apiKey": "your-api-token-here",
  "bundleTag": "bundle_personal_firefox_1",
  "syncMode": "bi-directional",
  "autoGenerateTags": false,
  "lastSyncTimestamp": 1715012345678
}

Storage Areas

  • browser.storage.local - Persistent data per browser profile
  • browser.storage.session - Temporary session data

Supported Values

Value Description
bi-directional Replicate both directions; keep both versions
write-only Browser is authoritative source; update Linkding only
read-only Linkding is authoritative source; download only

Default: bi-directional

2. Bookmark Notes Structure

The notes field uses a JSON-compatible structure with versioning for forward compatibility:

{
  "version": 1.0,
  "path": "Work/Resources/Development",
  "userNotes": "Development resources and references",
  "autoTags": [
    {"name": "Work"},
    {"name": "Resources"},
    {"name": "Development"}
  ],
  "bundleTag": "bundle_personal_firefox_1"
}

Display Format

  • Only show userNotes in the UI
  • path and autoTags are hidden from regular users

Version Handling

  • version 1.0: Basic structured format with path, userNotes, autoTags
  • version 2.0: Adds bundleTag field for tag-based bundle identification
  • Extension version tracking: Uses extension version number for notes version
  • Backward compatibility:
    • Old bookmarks without structured notes are detected
    • Non-JSON notes are migrated to structured format
    • Old notes get version: 1.0 and existing text in userNotes
    • Future fields are ignored by older versions

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/Tag Configuration

Instead of creating actual Linkding bundles, we use Linkding's "required tags" feature:

Bundle Tag Convention

All bookmarks in a bundle must have the bundle tag. The bundle tag name follows this pattern:

bundle_{BUNDLE_NAME}_{BROWSER}

Examples:

  • bundle_personal_firefox_1
  • bundle_work_chrome_1
  • bundle_personal_edge_1

Linkding Query Parameters

In Linkding, create a bundle with these parameters:

  • Search: (empty)
  • Required tags: {bundleTag}
  • Any tags: (empty)
  • All tags: (empty)
  • Excluded tags: (empty)

This means all bookmarks with the bundle tag appear in this bundle.

Updating Extension Version

The extension version is used as the notes version:

  • Extension v1.0.x → notes version 1.0
  • Extension v2.0.x → notes version 2.0
  • Extension v1.0.1 → notes version 1.0 (patch versions don't change notes version)

4. Extension File Structure

LinkdingSync/
├── 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
├── README.md                  # User documentation
├── docs/
│   ├── design.md              # Design document
│   └── TODOs.txt             # Version compatibility notes
└── icons/
    ├── icon-48.svg            # 48x48 icon
    └── 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 (with validation)
  • API key input (with "Get from Linkding Settings" guidance)
  • Bundle tag input (e.g., "bundle_personal_firefox_1")
  • Sync mode selector (bi-directional | write-only | read-only)
  • Auto-generate tags toggle
  • Last sync timestamp (human-readable with timezone)
  • Test connection button
  • Save Settings 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
  • Apply bundle tag to all new bookmarks
  • Migrate old notes to structured format

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 new bookmarks:
   - Add bundleTag to notes
   - Check if URL already in Linkding
   - If no → create new bookmark with bundle tag
   - If yes + different URL → create new bookmark
   - If yes + same URL → update notes (keep title/description)
   ↓
4. For updates (same URL, different folder):
   - Update path in notes
   - Merge with existing notes
   - Apply sync mode rules
   ↓
5. For deletions:
   - write-only → delete from Linkding
   - read-only → ignore (keep Linkding version)
   - bi-directional → delete from Linkding
   ↓
6. Migrate old notes:
   - If notes not JSON or lacks version field → treat as old notes
   - Convert to structured format with version 1.0
   - Preserve existing content in userNotes

7. Notes Migration

Old Notes Detection

Old notes are detected if:

  • notes is not valid JSON, OR
  • notes doesn't contain a version field

Migration Process

  1. Parse existing notes
  2. If invalid/non-JSON → create structured notes with: 
    {
  "version": 1.0,
  "path": "",
  "userNotes": "<existing text here>",
  "autoTags": [],
  "bundleTag": "<from config>"
}
  3. If valid but old version → update version field
  4. If same or newer version → keep as-is

Forward Compatibility

When new fields are added to notes structure:

  • Older extension versions ignore unknown fields
  • Newer extension versions add new fields
  • This allows gradual feature rollouts

8. API Endpoints Used

Authentication

Authorization: Token <Token>

Bookmarks

  • GET /api/bookmarks/ - List bookmarks
  • GET /api/bookmarks/check/?url=... - Check if URL is already bookmarked
  • POST /api/bookmarks/ - Create bookmark
  • PUT/PATCH /api/bookmarks/<id>/ - Update bookmark
  • DELETE /api/bookmarks/<id>/ - Delete bookmark

9. Implementation Status

Phase 1: Core Setup

  • Create manifest.json with options_ui
  • Create popup HTML/CSS/JS
  • Create background service worker
  • Implement storage helpers

Phase 2: Sync Logic

  • Implement bookmark manipulation
  • Implement notes parser with versioning
  • Implement sync logic
  • Implement conflict resolution

Phase 3: Configuration UI

  • Create config page
  • Implement config form logic
  • Add API key guidance

Phase 4: Polish

  • Add icons
  • Add error handling
  • Add notifications
  • Implement notes migration
  • Implement tag-based bundle approach

10. Version History

Version Date Changes
0.1.0 2026-05-06 Initial design document
1.0.0 2026-05-06 Initial implementation
1.0.1 TBD Tag-based bundle support
1.0.2 TBD Notes version migration

11. Notes

This document should be referenced during implementation to ensure all requirements are met. Any deviations from this design should be documented here.

Last Updated: 2026-05-06

Reference in New Issue View Git Blame Copy Permalink