myworkspace/Linkding Browser Extension/LinkdingSync/README.md

linkdingsync

A Firefox browser extension that synchronizes bookmarks with your self-hosted Linkding instance.

Features

• 🔄 Bi-directional Sync - Keeps bookmarks in sync between browser and Linkding
• 📁 Folder Structure - Preserves browser bookmark folder hierarchy in Linkding notes
• ⚙️ Multiple Sync Modes
  • Bi-directional: Keep both versions, replicate changes both ways
  • Write-only: Browser is authoritative, push changes to Linkding
  • Read-only: Linkding is authoritative, download from Linkding only
• 🎯 Bundle Management - Works with Linkding bundles for organized collections
• 🏷️ Auto-tag Generation - Optional auto-generation of tags from folder names

Installation

1. Open Firefox and navigate to about:addons
2. Click the "Gear" icon → "Debug Add-ons" -> Load Temporary Add-on...
3. Navigate to the "linkdingsync" folder and select the manifest.json file, or upload the extension zip (not created yet).

Usage

First-time Setup

1. Click the extension icon
2. Click "Settings" button
3. Configure:
   • Linkding Server URL (default: https://links.blabber1565.com)
   • API Token (get from Linkding Settings → Advanced → API Token)
   • Bundle Name
   • Sync Mode (default: Bi-directional)
4. Click "Save Settings"

Adding Bookmarks

Click the extension icon and fill in:

• URL - The bookmark URL (auto-filled with current page)
• Notes - Optional notes for this bookmark
• Folder - Browser folder classification
• Click "Add Bookmark"

Configuration

Sync Mode Options

Mode	Description
Bi-directional	Keep both versions; additions/updates replicate both ways. Both versions kept on conflict.
Write-only	Browser is authoritative; updates push to Linkding only.
Read-only	Linkding is authoritative; download from Linkding only.

Auto-generate Tags

When enabled, extracts folder names from bookmark path as tag suggestions. Disabled by default to avoid unwanted tags.

Folder Structure

bookmark-sync/
├── manifest.json              # Extension manifest
├── popup.html                 # Extension popup
├── popup.css                  # Popup styling
├── popup.js                   # Popup logic
├── background.html            # Settings page
├── background.js              # Service worker
├── README.md                  # This file
├── utils/
│   ├── bookmark.js            # Bookmark manipulation
│   ├── notes-parser.js        # Notes parsing utilities
│   ├── sync.js                # Sync logic
│   └── conflict-resolver.js   # Conflict handling
└── icons/
    ├── icon-48.svg            # 48x48 icon
    └── icon-96.svg            # 96x96 icon

API

The extension uses Linkding's REST API:

• GET /api/bookmarks/ - List bookmarks
• POST /api/bookmarks/ - Create bookmark
• PUT /api/bookmarks/<id>/ - Update bookmark
• DELETE /api/bookmarks/<id>/ - Delete bookmark
• GET /api/bundles/ - List bundles
• POST /api/bundles/ - Create bundle
• Authorization: Token <your-api-token>

Notes Structure

Bookmarks stored in Linkding use this notes format:

{
  "path": "Work/Resources/Development",
  "userNotes": "Development resources folder",
  "autoTags": [
    {"name": "Work"},
    {"name": "Resources"},
    {"name": "Development"}
  ]
}

• path - Browser folder path (machine-readable)
• userNotes - Human-readable notes
• autoTags - Auto-generated tags from folders

Security

• API tokens stored in browser storage (client-side only)
• Never expose tokens in client-side code
• Validate all API responses
• Handle authentication errors gracefully

Troubleshooting

Extension not loading

• Check browser console for errors
• Verify manifest.json is valid JSON
• Ensure all files are present

Cannot connect to Linkding

• Verify server URL is correct
• Check API token is valid
• Ensure Linkding is accessible

Bookmarks not syncing

• Check sync mode is not "read-only"
• Verify bundle exists in Linkding
• Check browser console for errors

License

This extension is provided as-is. Linkding is © sissbruecker and licensed under Apache License 2.0.

Support

For issues and questions, please open an issue on the Linkding GitHub repository: https://github.com/sissbruecker/linkding

---

Version: 1.0.0
Last Updated: 2026-05-06