147 lines
4.4 KiB
Markdown
147 lines
4.4 KiB
Markdown
# 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 |