# 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:

```json
{
  "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