Research Pocket 🔖

A self-hostable save-it-later tool that integrates with getpocket.com (and others soon). works on the web and terminal

[!TIP] Find the guide to creating your own static site on GitHub pages here ResearchPocket/my-list 📚

How it works

Installation

• Get the latest release binary for your desktop through the releases page

• Using Cargo

  $ cargo install research
  

Generate your site

This requires that you have tailwindcss installed and available in your $PATH

# Initialize the database
$ research init

# Authenticate with Pocket
$ research pocket auth

# Fetch your articles
$ research fetch

# Generate your site
# add --download-tailwind if you don't have tailwindcss installed in your $PATH
$ research --db ./research.sqlite generate .

URL Handler

Research Pocket includes a custom URL handler for the research:// protocol. This allows you to save web pages directly from your browser using a bookmarklet.

Registering the URL Handler

To register the URL handler on your system, use the following command:

$ research register

This will set up the necessary configurations for your operating system to recognize and handle research:// URLs.

Unregistering the URL Handler

If you want to remove the URL handler, use:

$ research unregister

Bookmarklet

You can use the following bookmarklet to quickly save web pages to Research Pocket:

javascript: (function () {
  var currentUrl = encodeURIComponent(window.location.href);
  var tags = prompt("Enter tags (comma-separated):", "");
  var dbPath = "/path/to/research.sqlite";
  if (tags !== null && dbPath !== null) {
    var encodedTags = encodeURIComponent(tags);
    var encodedDbPath = encodeURIComponent(dbPath);
    var researchUrl =
      `research://save?url=${currentUrl}&provider=local&tags=${encodedTags}&db_path=${encodedDbPath}`;
    window.location.href = researchUrl;
  }
})();

To use this bookmarklet:

1. Create a new bookmark in your browser.
2. Set the name to something like "Save to Research Pocket".
3. In the URL or location field, paste the above JavaScript code.
4. Replace /path/to/research.sqlite with the actual path to your Research Pocket database.

Now, when you click this bookmarklet on any web page, it will prompt you for tags and then save the page to your Research Pocket

Contributing

We welcome contributions to ResearchPocket! If you're interested in helping out, here are a few ways you can contribute:

• Reporting bugs
• Suggesting enhancements
• Writing documentation
• Submitting pull requests

We participate in Hacktoberfest! During October, we encourage contributors to join us in improving ResearchPocket. Look for issues tagged with hacktoberfest to get started.

For more detailed information about contributing to this project, including our Hacktoberfest participation, please check out our CONTRIBUTING.md guide.

Cli help

• Basic Help

  RESEARCH 🔖
  
  Manage your reading lists and generate a static site with your saved articles.
  
  Usage: research [OPTIONS] [COMMAND]
  
  Commands:
      pocket    Pocket related actions
      local     Add a new item to the database stored locally
      fetch     Gets all data from authenticated providers
      list      Lists all items in the database
      init      Initializes the database
      generate  Generate a static site
      export    Export data from the current database
      handle    Handle operations related to the research:// URL scheme
      help      Print this message or the help of the given subcommand(s)
  
  Options:
          --db <DB>   Database url [env: DATABASE_URL=] [default: ./research.sqlite]
      -d, --debug...  Turn debugging information on
      -h, --help      Print help
      -V, --version   Print version
  

• List

  Lists all items in the database
  
  Usage: research list [OPTIONS]
  
  Options:
    -t, --tags <TAGS>...  Filter by tags separated by commas Example: --tags rust,sql
    -l, --limit <LIMIT>   Limit the number of items to display
    -f, --favorite-only   Favorite items only (Default: false)
    -h, --help            Print help
  
  

• Init

  Initializes the database
  
  Usage: research init <PATH>
  
  Arguments:
    <PATH>
  
  Options:
    -h, --help  Print help
  

• Local

  Add a new item to the database stored locally
  
  Usage: research local <COMMAND>
  
  Commands:
    add       Add an item to the local provider in the database
    list      List all items in the local provider
    favorite  Mark an item as favorite in the local provider
    help      Print this message or the help of the given subcommand(s)
  
  Options:
    -h, --help  Print help
  

• Pocket

  Pocket related actions
  
  Usage: research pocket <COMMAND>
  
  Commands:
    auth      Authenticate using a consumer key
    fetch     Fetch items from pocket
    add       Add an item to pocket
    favorite  Mark an item as favorite in pocket
    help      Print this message or the help of the given subcommand(s)
  
  Options:
    -h, --help  Print help
  
  

• Fetch

  Gets all data from authenticated providers
  
  Usage: research fetch
  
  Options:
    -h, --help  Print help
  

• Generate

  Here's an example of how to generate a static site:

  $ research --db <path/to/research.sqlite> generate --assets <path/to/assets> <path/to/output>
  

  Optionally add --download-tailwind to download and reuse the tailwindcss binary in the assets directory.

    Generate a static site
  
    Usage: research generate [OPTIONS] <OUTPUT>
  
    Arguments:
      <OUTPUT>  The path to the output directory
  
    Options:
          --assets <ASSETS>    Path to required site assets (main.css, search.js, tailwind.config.js) [default: ./assets]
          --download-tailwind  Download Tailwind binary to <ASSETS>/tailwindcss if not found
      -h, --help               Print help