Skip to main content

sync your pocket bookmarks to Jekyll linkposts

Project description

# Pockyll

Pockyll is a python tool to create [Jekyll][j] linkposts from your
[pocket][pocket] collections because automated linkpost updates are like death

> "You wanna buy some death sticks?"<br>
> "You don't want to sell me death sticks."<br>
> "I don't wanna sell you death sticks."<br>
> "You want to go home an rethink your life."<br>
> "I want to go home and rethink my life."<br>
> -- Elan Sleazebaggano & Obi-Wan Kenobi

## Features

* Pocket item/bookmark syncing that converts your saved & tagged pocket items
into linkposts that merge seamlessly with standard Jekyll posts
* Linkpost management fully compatible with tools like e.g.
* Incremental update support
* Tag-specific syncing
* Pocket OAuth authentication

## Installation

### Concept
Using pockyll to manage [pocket][pocket] bookmarks requires two pieces: the
`pockyll` executable (which pulls your pocket bookmarks into your Jekyll site)
and changes to your site setup (in order to enable Jekyll to deal with
linkposts properly).

### Installing pockyll

Either get the package from PyPi

$ pip install pockyll

or clone the repo and install manually

$ git clone
$ cd pockyll
$ python install

### Pockyll setup

1. Login into [pocket][pocket_login], [create a new
application][pocket_newapp] that has *retrieve* permissions.
2. Switch into your Jekyll site directory
3. Generate a a dummy config file `_pockyll.yml`. This can be accomplished

$ pockyll init

4. In `_pockyll.yml` enter the `pocket_consumer_key` created in step 1.
Edit other fields as required.
5. Authenticate the pockyll app against the pocket API

$ pockyll auth

This will open a browser window and ask for pocket authentication.

### Site setup

By default, pockyll will define a variable `type` with the value `reference`
in every linkpost. It will also and include the target link in the `ref`
variable inside the YAML post header:

title: "Clojure, The Good Parts"
date: 2016-04-19T23:05:26
type: "reference"

Writing code that differentiates between normal and linkposts is
therefore straightforward. You can simply use the post type as an indicator.
Here is an example for a root directory `index.html` file that inserts the
link to the post for every normal post and the link to the reference for every

<div id="home">
<ul id="blog-posts" class="posts fa-ul">
{% for post in site.posts %}
{% if post.type == "reference" %}
<li><i class="fa-li fa fa-bookmark-o"></i>
<a href="{{ post.ref }}">{{ post.title }}</a> <!-- HERE -->
<span>{{ | date_to_string }}</span></li>
{% else %}
<li><i class="fa-li fa fa-pencil-square"></i>
<a href="{{ post.url }}">{{ post.title }}</a> <!-- HERE -->
<span>{{ | date_to_string }}</span></li>
{% endif %}
{% endfor %}

For normal posts, the link points to `post.url`. If the post
is a linkpost, the link points to `post.ref`, thus enabling direct external

## Syncing Jekyll linkposts with Pocket

Once you have your site configured, it is time to sync your pocket bookmarks.

1. `pockyll sync` (one-way sync of all new posts tagged with any
of `pocket_sync_tags`)
2. `jekyll build`
3. Optional: `jekyll serve` and marvel at the linkposts on your local server at

## Examples

mk@kowalski:~/src/mysite$ pockyll sync
Requesting new items from Pocket API...
Syncing 164 items.
FIXME: ['FIXME', u'', u'1227075798']
FIXME: ['FIXME', u'', u'374320379']
FIXME: ['FIXME', None, u'0']
Skipping: ['FIXME', None, u'0']
FIXME: ['FIXME', u'', u'1264106151']
FIXME: ['FIXME', u'', u'1152066420']
FIXME: ['FIXME', u'', u'393364879']
Done (skipped 1).

This is an example of an initial sync of a jekyll site against pocket (hence
the number of items). Pockyll automatically 'fixes' missing titles but skips
items that lack a URI or an ID. I would now change into the `linkpost_dir`,
grep all files for the `title: "FIXME"` string and start editing, e.g.:

vim `grep -l 'title: "FIXME"' *`

## Customization

Pockyll is configured using a `_pockyll.yml` configuration file located in
your Jekyll base directory. After successful OAuth authentication, the file
contains your secret Pocket access token. Hence, please make sure to
*include the pockyll configuration into your `.gitignore` file!*

### Configuration file

The overall configuration file structure looks like this:

pocket_consumer_key: ***secret***
pocket_access_token: ***secret***
pocket_redirect_uri: ''
pocket_sync_tags: ['blog']
pocket_since: 12326342
linkpost_dir: '_posts/linkposts'

### Options

- `pocket_consumer_key`: this is the consumer key you obtain from the
pocket developer API.
- `pocket_access_token`: the access token. Pockyll automatically stores
the token in the configuration file after the first successful OAuth
authentication event.
- `pocket_redirect_uri`: the location to which your are redirected
after successful authentication (this can be anything).
- `pocket_sync_tags`: a list of pocket tags that should be synced to
- `pocket_since`: pocket timestamp that marks the last sync.
Automatically updated by pockyll.
- `linkpost_dir`: the directory where linkposts should be synced
to. Change this to e.g. `_drafts/linkposts` if you want to review changes
before publication. In that case use

## License

Vanilla [MIT](

## Contact
Feel free to open issues if you run into trouble or have suggestions. Pull
Requests always welcome.


Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pockyll, version 0.1.1
Filename, size File type Python version Upload date Hashes
Filename, size pockyll-0.1.1.tar.gz (6.6 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page