readme.md

Bookmark Sync for GitHub

Synchronize browser bookmarks from a GitHub repository.

🚀 Why Use This Extension?

Have you ever wished to share a common set of bookmarks across a team or organization without needing everyone to manually update their bookmarks?

This extension allows for just that.

Store bookmarks in a simple JSON structure in your organization's GitHub repository, and let everyone have the latest bookmarks at their fingertips.

🚀 Features

• ⏱️ Automatic Synchronization: Sync bookmarks every hour and shortly after the browser starts.
• ✋ Manual Sync: Need the latest bookmarks immediately? Trigger a sync manually.
• 🎯 Selective Sync: Syncs only the folders contained in the remote bookmark files without touching others you might have.
• 🔄 Multi-Source Synchronization: Seamlessly integrate bookmarks from two separate sources, such as personal and work repositories.
• 📁 Multi-File Support: Organize your organizations bookmarks into separate JSON files, for example by project.
• 🔔 Notifications: Stay informed about successful syncs or if any issues arise.
• 🔒 Secure: Uses GitHub's Personal Access Token (PAT) for authentication, ensuring secure access.
• 🌐 GitHub Enterprise Support: Synchronize bookmarks from GitHub or GitHub Enterprise Server (GHES).

🛠 Installation

also compatible with Orion

📖 Usage

1. Install the extension using the above steps.
2. Configure your GitHub Personal Access Token, the Git repository and the path to your bookmark JSON file(s).
3. The extension will automatically synchronize the bookmarks from the JSON file(s) into your bookmark bar.

⚙ Configuration

Access the extension's options and provide:

1. GitHub Personal Access Token: Ensure this token has access to the repository. Your token is stored securely and used only for fetching the files. Use a fine-grained token restricted to the repository.
2. Organization: The account owner of the repository. The name is not case sensitive.
3. Repository: The name of the repository without the .git extension. The name is not case sensitive.
4. Source Path: The path within the repository to either a single JSON file or a directory containing multiple JSON bookmark files. For a single file, provide the path e.g., path/to/bookmarks.json. For a directory, just specify the folder path e.g., bookmarks.

You can also synchronize bookmarks from a GitHub Enterprise Server (GHES) by specifying the GitHub API URL (which ends with /api/v3).

Then make your bookmarks available at the source path in your repository to watch the magic happen.

Use the Check Connection to test the configuration.

📄 Bookmark Collection JSON Format

Structure your JSON file for bookmarks as per the schema defined at https://frederikb.github.io/bookmarksync/schemas/bookmarks.1-0-0.schema.json.

Top-Level Structure

Field	Type	Required	Description
$schema	URI	No	Schema identifier.
name	String	Yes	Name of the bookmark collection.
bookmarks	Array	Yes	Array of bookmark items.

Bookmark Item Types

Bookmark

Field	Type	Required	Description
title	String	Yes	Title of the bookmark.
url	URI	Yes	URL of the bookmark.
type	String	No	Set to "bookmark".

Folder

Field	Type	Required	Description
title	String	Yes	Title of the folder.
children	Array	Yes	Array of nested bookmark items.
type	String	No	Set to "folder".

Separator

Field	Type	Required	Description
type	String	Yes	Set to "separator".

Example

Example Bookmark JSON (Click to expand)

{
  "$schema": "https://frederikb.github.io/bookmarksync/schemas/bookmarks.1-0-0.schema.json",
  "name": "Bookmarks 1",
  "bookmarks": [
    {
      "title": "Work",
      "children": [
        {
          "title": "Email",
          "url": "https://mail.example.com"
        },
        {
          "title": "Docs",
          "children": [
            {
              "title": "Specs",
              "url": "https://specs.example.com"
            },
            {
                "type": "separator"
            },
            {
              "title": "Reports",
              "url": "https://reports.example.com"
            }
          ]
        }
      ]
    }
  ]
}

📸 Screenshots

Options Page - Configure your GitHub Personal Access Token and repository details.

Popup Screen - Manually trigger a sync.

🛑 Known Limitations

• 🚧 Manual Cleanup: If a folder or bookmark that was added to the Bookmarks Bar via the sync is no longer present in any of the synced bookmark JSON files, it will not be automatically removed. Such entries need to be manually cleaned up by the user.

🤝 Contributing

Contributions make the open source community an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the label "enhancement".

📜 License

Distributed under the MIT License. See LICENSE for more information.

📣 Acknowledgements

• Octokit: Seamless GitHub API integration.
• Hyperjump - JSON Schema: JSON Schema tooling.
• This project was bootstrapped with Web Extension Toolkit (wxt.dev).