Firefox Bookmarks Backup to HTML Converter

A fast, dependency-free tool that converts Firefox bookmark backup files directly to HTML format.

🚀 Features

• Direct conversion: Convert Firefox .jsonlz4 backup files directly to HTML without intermediate steps
• JSON support: Also supports regular .json bookmark files
• Automatic file detection: Automatically detects the input file format
• Preserves metadata: Maintains bookmark timestamps and descriptions
• Standard format: Outputs HTML in the standard Netscape bookmark format
• Zero dependencies: Single binary, no runtime requirements
• Cross-platform: Builds for Windows, macOS, and Linux

📥 Installation

Pre-built Binaries (Recommended)

Download the latest pre-built binary for your platform from the releases page.

Linux/macOS

# Download and install (replace $VERSION with the latest version)
curl -L -o firefox-bookmarks "https://github.com/panz3r/firefox-bookmarks/releases/download/v$VERSION/firefox-bookmarks-linux-amd64"

# Make executable
chmod +x firefox-bookmarks

# Move to PATH (optional)
sudo mv firefox-bookmarks /usr/local/bin/

Windows

1. Download firefox-bookmarks-windows-amd64.exe from the releases page
2. Rename to firefox-bookmarks.exe (optional)
3. Place in a directory in your PATH, or run directly

Platform-specific downloads:

• Linux AMD64: firefox-bookmarks-linux-amd64
• Linux ARM64: firefox-bookmarks-linux-arm64
• macOS AMD64: firefox-bookmarks-darwin-amd64
• macOS ARM64: firefox-bookmarks-darwin-arm64 (Apple Silicon)
• Windows AMD64: firefox-bookmarks-windows-amd64.exe
• Windows ARM64: firefox-bookmarks-windows-arm64.exe

Build from Source

# Clone and build
git clone git@github.com:panz3r/firefox-bookmarks.git

cd firefox-bookmarks

# Build for current platform
make build

# Or build for all platforms
make build-all

Available Make Commands

# See all available commands
make help

# Development workflow
make dev          # Full development setup (deps + build + test)
make quick        # Quick build and test

# Building
make build        # Build for current platform
make build-all    # Build for all platforms

# Testing
make test         # Run all tests
make test-cover   # Run tests with coverage
make benchmark    # Performance comparison vs Python version

# Examples
make example      # Run example demonstration
make run-example  # Quick test with sample file

# Utilities
make clean        # Clean build artifacts
make format       # Format code
make info         # Show project information

🚀 Usage

Basic Usage

# Show help
./firefox-bookmarks -help

# Convert with auto-generated output filename
./firefox-bookmarks backup.jsonlz4

# Convert with custom output filename
./firefox-bookmarks -o my_bookmarks.html backup.jsonlz4

# Convert JSON bookmark file
./firefox-bookmarks -o bookmarks.html bookmarks.json

Note: Flags must come before the input file.

📁 Input File Formats

Firefox .jsonlz4 backup files

Location

• Linux/macOS: ~/.mozilla/firefox/[profile]/bookmarkbackups/
• Windows: %APPDATA%\Mozilla\Firefox\Profiles\[profile]\bookmarkbackups\

Format

• Filename: bookmarks-YYYY-MM-DD_HHMMSS_randomhash.jsonlz4
• These are compressed backup files created automatically by Firefox

JSON bookmark files

• Regular JSON files containing Firefox bookmark data
• Can be created by manually exporting bookmarks

📄 Output Format

Generates HTML files in the standard Netscape bookmark format, compatible with:

• Firefox, Chrome, Safari, Edge, Opera
• Most bookmark management tools
• Other bookmark converters

🧠 How it works

1. File Detection: The tool automatically detects whether the input is a compressed .jsonlz4 file or a regular JSON file
2. Decompression (if needed): For .jsonlz4 files, it removes the Mozilla LZ4 header and decompresses the content
3. JSON Parsing: Parses the bookmark data structure
4. HTML Generation: Recursively converts the bookmark tree to HTML format, preserving:
   • Folder hierarchy
   • Bookmark URLs and titles
   • Creation and modification timestamps
   • Bookmark descriptions (if present)

🧪 Example

Run the included demonstration:

make example

This will:

• Build the binary if needed
• Show usage examples
• Run a test conversion
• Display performance metrics

🚀 Performance

• Execution time: ~5-10ms startup + processing
• Memory usage: ~8-12MB peak
• Binary size: ~2-3MB (no runtime dependencies)
• Cross-platform: Native binaries for all major platforms

🔧 Troubleshooting

Binary not found or won't run

• Download the correct binary for your platform from builds/
• Make sure the binary has execute permissions: chmod +x firefox-bookmarks
• Build from source if needed: make build

"not a valid Firefox bookmark backup file"

Ensure you're using a valid Firefox bookmark backup file from:

• Linux: ~/.mozilla/firefox/[profile]/bookmarkbackups/
• Windows: %APPDATA%\Mozilla\Firefox\Profiles\[profile]\bookmarkbackups\
• macOS: ~/Library/Application Support/Firefox/Profiles/[profile]/bookmarkbackups/

File permission errors

Ensure you have read permissions for the input file and write permissions for the output directory.

🐍 Legacy Python Version

The original Python implementation is still available in the python/ directory. See Python README for details. The Python version requires Python 3.6+ and the lz4 library, but produces identical output to the Go version.

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

This project builds upon excellent work from:

• json2html-bookmarks by Andrea Bonomi
• jsonlz4_to_json by Robotvasya