This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
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
sticks.

> "You wanna buy some death sticks?"

> "You don't want to sell me death sticks."

> "I don't wanna sell you death sticks."

> "You want to go home an rethink your life."

> "I want to go home and rethink my life."

> -- 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.
[octopress][octopress]
* 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

```bash
$ pip install pockyll
```

or clone the repo and install manually

```bash
$ git clone https://github.com/mkirchner/pockyll.git
$ cd pockyll
$ python setup.py 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
using

$ 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"
ref: https://rasterize.io/blog/clojure-the-good-parts.html
---

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
linkpost:

```html
<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>
<span>{{ post.date | date_to_string }}</span></li>
{% else %}
<li><i class="fa-li fa fa-pencil-square"></i>
<a href="{{ post.url }}">{{ post.title }}</a>
<span>{{ post.date | date_to_string }}</span></li>
{% endif %}
{% endfor %}
</ul>
</div>
```

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
linking.

## 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
<http: localhost:4000="">.

## Examples

```
mk@kowalski:~/src/mysite$ pockyll sync
Requesting new items from Pocket API...
Syncing 164 items.
FIXME: ['FIXME', u'http://insighthealthdata.com/blog/HealthyBeats/index.html' u'1227075798']
FIXME: ['FIXME', u'http://ahmetalpbalkan.com/blog/8-months-microsoft/' u'374320379']
FIXME: ['FIXME', None, u'0']
Skipping: ['FIXME', None, u'0']
FIXME: ['FIXME', u'https://www.linkedin.com/pulse/agile-dead-matthew-kern' u'1264106151']
FIXME: ['FIXME', u'http://pjreddie.com/darknet/' u'1152066420']
FIXME: ['FIXME', u'https://www.chrisstucchio.com/blog/2013/bayesian_bandit.html' u'393364879']
Done (skipped 1).
mk@kowalski:~/src/mysite$
```

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:

```yaml
pocket_consumer_key: ***secret***
pocket_access_token: ***secret***
pocket_redirect_uri: 'https://getpocket.com/a/'
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
Jekyll.
- `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](https://github.com/mkirchner/pockyll/blob/master/LICENSE)

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

[j]: http://jekyllrb.com/
[octopress]: http://octopress.org/
[pocket]: https://getpocket.com/
[pocket_login]: https://getpocket.com/login
[pocket_newapp]: https://getpocket.com/developer/apps/new
Release History

Release History

0.1.1

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
pockyll-0.1.1.tar.gz (6.6 kB) Copy SHA256 Checksum SHA256 Source May 13, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting