obsidian-pocket

:heavy_exclamation_mark: I (@nybbles) am looking for someone to take over as the maintainer of obsidian-pocket. If you are interested, please reach out (@nimalan on Twitter or nybbles on the Obsidian Discord). The transition would start with the new maintainer taking on issues and contributing PRs.

This plugin for Obsidian that allows you to sync your Pocket reading list into Obsidian, so that you can easily create Obsidian notes directly from your Pocket reading list.

Initial setup

After the plugin has been enabled, you will be able to see a "Pocket" option under the "Plugin options" section of the settings panel. Click on it to go to the obsidian-pocket settings tab, where you can connect your Pocket account and set up the obsidian-pocket plugin.

Connect your Pocket account

Click on "Connect your Pocket account" to begin the Pocket authorization flow by opening a web page on your default browser. You will be asked whether you want to give permission to this plugin to access your Pocket data. Then you will be redirected back to Obsidian. Your Pocket account should now be connected.

The "Disconnect your Pocket account" button can be used to remove the Pocket authorization that was just provided.

Specify settings

The obsidian-pocket settings tab will contain a number of settings that affect how obsidian-pocket syncs Pocket items and creates Pocket item notes, as described below:

It is highly encouraged that you use the default Pocket item notes template and front matter URL key. If you decide to customize these option, please ensure that your Pocket item notes do end up having a valid front matter key for Pocket item URL.

Usage

Available commands

Syncing Pocket items

You can sync your Pocket items using an Obsidian command: "Sync Pocket list", or the button in the obsidian-pocket settings tab.

You can either sync all Pocket items or just Pocket items with a particular tag that you specify, using the "Pocket sync tag" setting. Leave it blank to sync all Pocket items, or specify a Pocket tag to limit your sync to just Pocket items with that tag.

Opening and using the Pocket list

Once the Pocket list is downloaded and stored, open the command palette and search for "Pocket" to see the list of available commands. The command to open the Pocket list is "Open Pocket list". The Pocket list is shown in a screenshot above.

The Pocket list can be used to browse through the items you've saved to Pocket and to create a note for any Pocket item by clicking on its title. You can also go directly to the URL for the Pocket item.

Pocket tags in Obsidian

Pocket tags are synced and presented in the Pocket list. Pocket supports tags with spaces in them, whereas Obsidian does not. The way that obsidian-pocket handles Pocket tags with spaces can be configured in the "Multi-word Pocket tag converter options" setting shown in the screenshot above.

The available options are:

• (Enabled by default) Snake case ('#tag with spaces' becomes #tag_with_spaces)
• Camel case ('#tag with spaces' becomes #TagWithSpaces)
• Do nothing ('#tag with spaces' remains unchanged)

These settings only affect the Pocket tags displayed in the Pocket list, and the tags that are inserted into a Pocket item note if you have {{tags}} in your Pocket item note template (see below for using templates for Pocket item notes). They do not affect already-existing Obsidian tags or Pocket tags.

Notes for Pocket items

Click on any Pocket item's title to create a note (or navigate to an existing note) for that Pocket item. Notes for Pocket items will be created in the Pocket item notes folder, which can be configured in settings. If no Pocket item notes folder is set, then Pocket item notes will be created in the root folder.

A template for new Pocket item notes can be specified in settings.

Open the Pocket item URL in your browser using Meta+click for Linux and Mac OS (e.g. command+click on Mac OS) and using Alt+click for Windows.

Notes in Obisidan are matched to Pocket items based on a specific tag in their frontmatter. The tag that is used is "URL" by default, but can be changed in settings.

This means that while Pocket item notes are created by default in the Pocket items notes folder, they can be moved elsewhere and/or renamed without breaking the connection to the Pocket item with matching URL. It also means that you can create notes with the URL frontmatter and they will be automatically connected to the relevant Pocket item note with the matching URL, although the Pocket item template would not be used in that case.

Use the "Index all files by URL" command to ensure that obsidian-pocket knows about all files that contain a frontmatter tag for URL, thereby allow it to match those notes to Pocket items. This index is maintained by obsidian-pocket automatically, so you should not need to run it.

:warning: As of version 0.8.0 of obsidian-pocket, Obsidian notes are matched to Pocket items only using the front matter URL key, and no longer matched by title. The last version to support matching by title was version 0.7.2. This functionality was removed because it did not work correctly with Pocket items that had the same title, but different URLs.

Using custom templates for Pocket notes

:warning: Please use the default template and front matter URL key, unless you are confident that you can customize these settings while ensuring that the Pocket item notes have valid frontmatter YAML and that the URL frontmatter key matches what you have asked obsidian-pocket to look for.

Templates for Pocket notes work similar to any other template in Obsidian, see here, except that only the following variables are supported:

This is the default template in obsidian-pocket. It will populate the YAML frontmatter of the Pocket item note with all available metadata used in the correct places so that YAML frontmatter is valid, hashtags work correctly and the Pocket item's main image is displayed (if available):

---
Title: "{{title}}"
URL: {{url}}
Pocket URL: {{pocket-url}}
Tags: [pocket, {{tags-no-hash}}]
Excerpt: >
    {{excerpt}}
---
{{tags}}
{{image}}

If you had saved this URL to Pocket with the tag "Carbon removal", synced it to Obsidian using this plugin and then created a note for the corresponding Pocket item with the above template, your note would start off containing the following:

---
Title: "Carbon removal hype is becoming a dangerous distraction"
URL: https://www.technologyreview.com/2021/07/08/1027908/carbon-removal-hype-is-a-dangerous-distraction-climate-change/
Pocket URL: https://getpocket.com/read/1337
Tags: [pocket, carbon_removal]
Excerpt: >
    In February, oil giant Shell trumpeted a scenario in which the world pulls
    global warming back to 1.5 ˚C by 2100, even as natural gas, oil, and coal
    continue to generate huge shares of the world’s energy.
---
#carbon_removal
![image](http://via.placeholder.com/640x360)

Note that in the example template, the title is quoted so that the YAML frontmatter is valid, even if the Pocket item has a title with colons in it.

Feature requests, bug reports and PRs

Feature requests, bug reports and PRs are welcome! Please use https://github.com/nybbles/obsidian-pocket/issues for this. Please file feature requests under https://github.com/nybbles/obsidian-pocket/labels/enhancement, or comment in existing feature requests to indicate your interest.

Please provide console logs if you are filing a bug report, so that it can be reproduced and fixed. You can copy/paste console logs from the Obsidian dev console, which can be opened by going to View > Toggle Developer Tools in Obsidian.

Design overview and security considerations

This plugin runs completely locally. The only external party it communicates with is Pocket, via the Pocket API. All of your data from Pocket and your Pocket access token are stored locally.

This plugin stores your Pocket data locally in Obsidian's IndexedDB.

Support

If you find this plugin valuable, please let me know! It is great to hear from people who use what I've built. If you really like this plugin and want to express that by buying me a coffee, please do 🙏🏾.

Please don't feel obligated to donate!