Metadata-Version: 1.1
Name: pockyll
Version: 0.1.1
Summary: sync your pocket bookmarks to Jekyll linkposts
Home-page: https://github.com/mkirchner/pockyll/
Author: Marc Kirchner
Author-email: mail@marc-kirchner.de
License: MIT
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?"<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.
          [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> <!-- HERE -->
                  <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> <!-- HERE -->
                  <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
        
Keywords: jekyll pocket blog linkpost
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
