bookmark-manager

# bookmark-manager

Self-hosted bookmark manager with tags, screenshots, and full-text search.

## When to use

- Saving URLs to read or reference later
- Organizing links into collections by topic
- Searching across all saved bookmarks by content
- Importing browser bookmarks from Chrome/Firefox/Safari
- Sharing a curated collection of links publicly

## Prerequisites

1. A running bookmark-manager instance (self-hosted or Docker)
2. Access to the web UI at the configured BASE_URL
3. Password set during first-run setup

## Quick Start

```bash
# Run with Docker
docker compose up -d
# Open http://localhost:3000
# Set your password on the first-run screen
# Start saving bookmarks
```

## Key Operations

### Save a bookmark

POST to the API or use the web UI form:

```bash
curl -X POST http://localhost:3000/api/bookmarks \
  -H "Cookie: session=your-session-token" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","tags":["dev","reference"]}'
```

Response: `{"id":42,"url":"...","title":"Example","screenshot_status":"pending"}`

### Search bookmarks

```bash
curl "http://localhost:3000/api/search?q=javascript+promises&page=1" \
  -H "Cookie: session=your-session-token"
```

Returns paginated results with FTS5 `<mark>` snippets.

### Import from browser

```bash
curl -X POST http://localhost:3000/api/import \
  -H "Cookie: session=your-session-token" \
  -F "file=@bookmarks.html"
```

Returns: `{"imported":312,"skipped":28,"errors":2}`

### Export all bookmarks

```bash
curl http://localhost:3000/api/export \
  -H "Cookie: session=your-session-token" \
  > my-bookmarks.html
```

### Share a collection

```bash
curl -X POST http://localhost:3000/api/collections/3/share \
  -H "Cookie: session=your-session-token"
```

Returns: `{"shareUrl":"https://bookmarks.example.com/s/abc123..."}`

## API Reference

| Method | Endpoint | Description |
|---|---|---|
| POST | `/api/auth/login` | Login with password |
| POST | `/api/auth/logout` | End session |
| GET | `/api/bookmarks` | List bookmarks (paginated) |
| POST | `/api/bookmarks` | Create bookmark |
| GET | `/api/bookmarks/:id` | Get single bookmark |
| PUT | `/api/bookmarks/:id` | Update bookmark |
| DELETE | `/api/bookmarks/:id` | Delete bookmark |
| POST | `/api/bookmarks/bulk` | Bulk tag/delete |
| GET | `/api/search` | Full-text search |
| GET | `/api/collections` | List collections |
| POST | `/api/collections` | Create collection |
| POST | `/api/collections/:id/share` | Share/unshare collection |
| GET | `/api/tags` | List tags with counts |
| POST | `/api/import` | Import Netscape HTML |
| GET | `/api/export` | Export Netscape HTML |
| GET | `/api/share/:token` | Public collection (no auth) |
| GET | `/api/screenshot/queue` | Screenshot queue status |

## Query Parameters

| Param | Description |
|---|---|
| `q` | Search query (FTS5) |
| `tag` | Filter by tag name |
| `collection` | Filter by collection ID |
| `pinned=1` | Only pinned bookmarks |
| `page` | Page number (1-indexed) |
| `per_page` | Results per page (default 24, max 100) |

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `PORT` | `3000` | HTTP port |
| `DATA_DIR` | `./data` | SQLite DB and screenshots directory |
| `SESSION_SECRET` | (required) | Session signing secret |
| `SCREENSHOT_ENABLED` | `1` | Enable Puppeteer screenshots (0/1) |
| `SCREENSHOT_CONCURRENCY` | `2` | Parallel Puppeteer workers |
| `SCREENSHOT_TIMEOUT_MS` | `15000` | Per-page capture timeout |
| `SHARE_ENABLED` | `1` | Allow public share links (0/1) |
| `BASE_URL` | `http://localhost:3000` | Public URL for share links |

## Troubleshooting

### Screenshots not capturing

Check `SCREENSHOT_ENABLED=1` and that Chromium is installed. View the queue at `/screenshot-queue` to see errors.

### Import shows 0 imported

The HTML file may not be in Netscape bookmark format. Export from Chrome: Bookmark Manager > three-dot menu > Export bookmarks.

### "Unauthorized" on all API calls

Session cookie expired or not sent. POST to `/api/auth/login` to get a new session cookie.

### Search returns no results

FTS5 index may be out of sync. Rebuilding is triggered automatically on startup. Check that the query does not contain unbalanced quotes.