bookmark manager

A few scripts & a local bookmark manager to make life a little easier & give you a bit more control.

• Clean & convert your exported Brave/Chrome bookmarks to JSON
• Extract your X bookmarks & organize them into JSON
• Display them locally & securely
• Add or edit categories, delete the worst of them
• Auto-adds corresponding Nitter URL in case you get suspended

---

features

• Local-first: your data stays on your machine
• Search across titles, URLs, categories, and tweet content
• Filter by category with toggle buttons
• Edit categories through the UI
• Nitter mirror URLs for every X bookmark (privacy + backup if account suspended)
• Terminal aesthetic (black/amber monospace)
• Portable JSON storage

---

setup

requirements

• Python 3
• uv (recommended for Python environment management)
• beautifulsoup4 (for browser bookmark parsing)

# with uv (recommended)
uv pip install beautifulsoup4

# or with pip
pip install beautifulsoup4

---

usage

importing browser bookmarks

1. Export bookmarks from Brave/Chrome as HTML
2. Save as bookmarks.html in the project directory
3. Run the parser:

uv run bookmarks_to_json.py
# or: python3 bookmarks_to_json.py

This creates bookmarks.json with your bookmark folder structure as categories.

---

importing X/Twitter bookmarks

1. Go to https://x.com/i/bookmarks in your browser
2. Open browser console (F12)
3. Paste and run bmark_extract.js
4. Script scrolls through bookmarks and downloads JSON
5. Move the downloaded file to project directory
6. Edit book_clean_add_cat.py line 9 to match your filename
7. Run the cleaner:

uv run book_clean_add_cat.py
# or: python3 book_clean_add_cat.py

This creates x_bookmarks.json with:

• Formatted dates
• Nitter mirror URLs (default: nitter.net)
• Empty category fields ready for sorting

Nitter instance: Change NITTER_PREFIX in book_clean_add_cat.py (line 9) if you prefer a different Nitter instance.

---

running the manager

uv run server.py
# or: python3 server.py

Opens http://localhost:8000 in your browser.

Two views:

• index.html - browser bookmarks
• x_books_index.html - X bookmarks

Navigate between them using the top-right links.

---

adding bookmarks via CLI

Run add_bookmark.py to add browser bookmarks from terminal:

uv run add_bookmark.py
# or: python3 add_bookmark.py

Prompts for title, URL, and category. Validates input and sorts automatically.

---

categorization

Browser bookmarks: Import with existing folder structure as categories. Edit through UI if needed.

X bookmarks: Start with empty categories. Organize through the UI manually, or use AI for bulk categorization if you want (local AI for private bookmarks, any AI for non-sensitive).

The manager is built for category editing - that's the point. Search, filter, and organize at your own pace.

---

backup

No built-in backup system. Your data lives in:

• bookmarks.json
• x_bookmarks.json

Copy these files to external storage/USB/your own setup periodically. They're plain JSON - portable and future-proof.

---

optional: shell aliases (Linux)

Add to .bashrc or .zshrc:

alias addbook='uv run ~/path/to/bookmarks/add_bookmark.py'
alias books='uv run ~/path/to/bookmarks/server.py'
alias cleanx='uv run ~/path/to/bookmarks/book_clean_add_cat.py'
alias parsebooks='uv run ~/path/to/bookmarks/bookmarks_to_json.py'

Then:

books          # launch manager
addbook        # add bookmark via CLI
cleanx         # process X bookmark export
parsebooks     # parse browser bookmark HTML

Change paths to match your installation.

---

file structure

bookmarks/
├── index.html              # browser bookmarks UI
├── x_books_index.html      # X bookmarks UI
├── script.js               # browser bookmarks logic
├── x_script.js             # X bookmarks logic
├── style.css               # shared styles
├── server.py               # local web server
├── add_bookmark.py         # CLI bookmark adder
├── bookmarks_to_json.py    # browser bookmark parser
├── book_clean_add_cat.py   # X bookmark cleaner
├── bmark_extract.js        # X bookmark scraper (run in browser)
├── bookmarks.json          # browser bookmarks data
└── x_bookmarks.json        # X bookmarks data

---

why Nitter mirrors?

Every X bookmark gets a Nitter URL generated automatically. Benefits:

• Privacy-respecting frontend (no tracking)
• Account suspension backup: If you lose X access, you can still read your bookmarked tweets
• Alternative viewing option built into the UI

Click "x" for original tweet, "nitter" for mirror.

---

notes

• Server runs on localhost:8000 (change port in server.py line 78)
• X bookmark scraper pauses 2 seconds between scrolls (change in bmark_extract.js line 10)
• Category editing and deletion save immediately to JSON

---

security notes

For local-only use (default):

• Server binds to localhost only - not accessible from network
• Server only serves .html, .js, .css, and .json files - blocks access to .env, .git, and other sensitive files
• No authentication needed for single-user local setup
• All user data is properly escaped to prevent XSS
• Periodically update Python dependencies: uv pip install --upgrade beautifulsoup4

If exposing beyond localhost:

• Add CSRF protection (server currently has none)
• Implement authentication (currently anyone with access can read/write)
• Use HTTPS (currently HTTP only)
• Add comprehensive logging and monitoring
• Consider using a proper web framework instead of SimpleHTTPRequestHandler
• Implement proper access controls

The code is secure for its intended use case (local bookmark manager), but was not designed for multi-user or network exposure.

---

license

Do whatever you want with this.