#generate-static #ssg #pocket #web-page #reading-list #save-it-later

app research

Manage your reading lists and generate a static site with your saved articles

13 releases

0.1.19 Oct 13, 2024
0.1.17 Sep 28, 2024
0.1.12 May 14, 2024
0.1.7 Feb 18, 2024

#64 in Command line utilities

Download history 83/week @ 2024-09-20 309/week @ 2024-09-27 18/week @ 2024-10-04 161/week @ 2024-10-11 14/week @ 2024-10-18

573 downloads per month

Apache-2.0

595KB
2K SLoC

Research Pocket 🔖

The last save-it-later tool you'll ever need


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

Hashnode logo

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
    

Dependencies

~38–70MB
~1M SLoC