Bookmarks Converter

BookmarksConverter is a package that converts browser bookmark files, usable as a module or as a CLI.

BookmarksConverter supports the converters below:

• Bookmarkie (custom formats)
• Chrome/Chromium
• Firefox

The converters can import and export bookmarks from and to the formats listed below:

• Bookmarkie: DB, HTML, JSON
• Chrome/Chromium: HTML, JSON
• Firefox: HTML, JSON

Notes:

• Supports Netscape-Bookmark format for HTML files
• The exported HTML files are compatible with all browsers.
• Custom DB files are powered by SQLAlchemy ORM (see models.py).
• Chrome/Chromium JSON files cannot be directly imported but can be placed in the appropriate location (see bookmarks_file_structure.md - Chrome/Chromium - b. JSON).
• For examples of supported DB, HTML, or JSON structures and formats, refer to the test resources or bookmarks_file_structure.md.
• Custom DB and JSON formats by BookmarksConverter are not browser-importable.

Table of Contents

• Table of Contents
  • Python and OS Support
  • Dependencies
  • Install
  • Test
  • Usage as Module
  • Usage as CLI
  • License

Python and OS Support

The package has been tested on GitHub Actions with the following OSs and Python versions:

Dependencies

The package relies on the following libraries:

• BeautifulSoup4: used to parse the HTML files.
• SQLAlchemy: used to create and manager the database files.

Install

Bookmarks Converter is available on PYPI

python -m pip install bookmarks-converter

Test

To test the package you will need to clone the git repository.

# Cloning with HTTPS
git clone https://github.com/radam9/bookmarks-converter.git

# Cloning with SSH
git clone git@github.com:radam9/bookmarks-converter.git

then you create and install the dependencies using uv.

# navigate to repo's folder
cd bookmarks-converter
# install the dependencies
uv sync --group dev
# run the tests
uv run pytest

Usage as Module

from pathlib import Path
from bookmarks_converter import Chrome, Firefox
from bookmarks_converter.formats import save_json

# initialize the converter
firefox = Firefox()
chrome = Chrome()

# import the bookmarks
input_file = Path("/path/to/input.html")
content = firefox.from_html(input_file)

# convert to desired format
output_file = Path("/path/to/output.json")
bookmarks = chrome.as_json(content)

# finally save the bookmarks
# there are some helper files that could be useful for saving to files
save_json(bookmarks, output_file)

Usage as CLI

bookmarks-converter cli can be installed inside a virtual environment or using pipx.

# bookmarks-converter usages:
# example 1
bookmarks-converter -i ./input_bookmarks.db --input-format 'bookmarkie/db' --output-format 'chrome/html'

# example 2
bookmarks-converter -i ./some_bookmarks.html -I 'chrome/html' -o ./output_bookmarks.json -O 'firefox/json'

The help message:

# use -h for to show the help message (shown in the code block below)
$ bookmarks-converter --help

usage: bookmarks-converter [-h] [-V] -i INPUT -I INPUT_FORMAT [-o OUTPUT] -O OUTPUT_FORMAT

Convert your browser bookmarks file.

The bookmark format is composed of two parts separated by a slash: [CONVERTER]/[FORMAT], ex. 'firefox/html'
With the converter being one of the available converters: ('bookmarkie', 'chrome', 'firefox')
And the format being one of the available formats: ('db', 'html', 'json')

Example Usage:
    bookmarks-converter -i ./input_bookmarks.db --input-format 'bookmarkie/db' --output-format 'chrome/html'
    bookmarks-converter -i ./some_bookmarks.html -I 'chrome/html' -o ./output_bookmarks.json -O 'firefox/json'
    

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -i INPUT, --input INPUT
                        Input bookmarks file
  -I INPUT_FORMAT, --input-format INPUT_FORMAT
                        The bookmark format of the input bookmarks file
  -o OUTPUT, --output OUTPUT
                        Output bookmarks file
  -O OUTPUT_FORMAT, --output-format OUTPUT_FORMAT
                        The bookmark format of the output bookmarks file

License

MIT License