Convert highlights and notes on your Kindle to nice HTML, Markdown, or JSON.
Ruby Gherkin HTML
Permalink
Failed to load latest commit information.
bin
features
lib
spec
.gitignore
.rspec
.ruby-version
.travis.yml
CHANGELOG.txt
Gemfile
Gemfile.lock
LICENSE.txt
README.md
Rakefile
example.png
klipbook.gemspec

README.md

Klipbook

Build Status

Klipbook takes the highlights and notes that you've created on your Kindle and outputs them into nice HTML, Markdown, or JSON.

An example of a HTML clippings file generated by Klipbook

Example
of a clippings file

What sources does it support?

Klipbook can take your highlights from a clippings file off a physical Kindle device or from the Kindle highlights site itself.

When should I use the file and when should I use the site?

If your books are purchased from Amazon directly then use the site. The site is the canonical source and will contain all of your notes and highlights from across all of your Kindle devices and applications. Currently the Amazon highlights site only shows clippings for books you've purchased on Amazon.

If your books are personal documents and you've read them on your Kindle device itself then you should use the file from that device as a source i.e. your Kindle device only keeps clippings that you make directly on it.

How does it work?

Klipbook supports two commands: list and export.

list shows the books in the specified source and export exports books to a different format.

Specifying an Input Source

Both commands require you to specify the source of your clippings.

Reading from a clippings file

Copy your clippings file (called "My Clippings.txt" on a 3rd generation Kindle) from your Kindle device to your local drive via USB.

Then specify the path to your clippings via:

$ klipbook list --from-file "My Clippings.txt"

Reading from the highlights site

Specify your Amazon credentials to klipbook and it will scrape the site and output a clippings file.

$ klipbook list --from-site my-username@blah.com:my-password

Note that the scraping requires a network connection (obviously) and can take a while so please be patient.

List

The list command lists the books available in the specified source.

$ klipbook list --from-file "My Clippings.txt"

Book list:
[1] The Big Sleep by Raymond Chandler
[2] How to jump out of a plane without a parachute and survive by Rip Rockjaw

By default it will only list the latest book. This can be overrided with the --count switch.

Export

export reads the clippings from your source and writes them out in the specified format.

You can specify the directory to export into with the --output-dir switch. This defaults to the current directory.

You can also specify a maximum number of books you'd like exported with the --count switch.

Klipbook will not overwrite an exiting file by default. You can change this with the --force flag.

Export to Html

You can export clippings into a pretty html file for each book.

$ klipbook export --from-file "My Clippings.txt" --format html

Export to JSON

You can export clippings into a JSON file for each book.

$ klipbook export --from-file "My Clippings.txt" --format json

Export to Markdown

You can export clippings into a markdown file for each book.

$ klipbook export --from-file "My Clippings.txt" --format markdown

Set defaults

If you don't feel like having your Amazon credentials in your shell history you can set your default source in the klipbook rc file: ~/.klipbookrc.

This is a YAML file and you can specify default values for the source and the output directory (note the use of snake case) e.g.

$ cat ~/.klipbookrc

:from_site: my-username@blah.com:my-password
:output_dir: /path/to/my/default/output/directory

Command line options override the defaults stored in the rc file.

Installation

Klipbook is a Ruby gem. To install simply run:

$ gem install klipbook

Supported Devices

Klipbook has been tested on clippings files from 3rd generation Kindles and the Kindle Touch.

Tested platforms

Klipbook has been tested on Mac OS X El Capitan using Ruby 2.3.1.

Contributing to Klipbook

Fork the project on Github, add tests for your changes, and submit a well described pull request.

Copyright

Copyright (c) 2016 Ray Grasso. See LICENSE.txt for further details.