danchoi / kindlefodder

Bring web docs to the Kindle
MIT License
366 stars 45 forks source link

Kindlefodder

Kindlefodder is a Ruby framework and a collection of recipes for translating website-bound books and documentation into Kindle ebooks that are easy to navigate and a pleasure to peruse. Web browsers are good for scanning information, but Kindles are a lot better when you want to block out distractions and actually learn something.

The ebooks posted here will in most cases be derived from material published under a Creative Commons license. I am grateful to the original authors for writing such good and useful material. They are welcome to take these ebooks and recipes, modify them, and distribute them under their own name.

You can download these ebooks now

Here are a few Kindle ebooks generated with the Kindlefodder framework. You can download them and transfer them to your Kindle via USB.

GitHub Projects

screen screen

This is a collection of READMEs and Wiki Pages from useful GitHub projects. (Work in progress)

Heroku Guide

screen screen

Thoughbot Playbook

screen screen

Pro Git by Scott Chacon

screen screen

If you enjoy the Kindlefodder version, I encourage you to buy the print version to support the author. I own the print version.

jQuery Reference

screen screen

jQuery Fundamentals by Rebecca Murphey et al.

screen screen

Frontend Docs Bundle: Haml/Sass/CoffeeScript/Backbone.js Reference

screen screen

Ruby on Rails Guides

screen screen

The code used to generate this ebook is actually the evolutionary ancestor to the Kindlefodder project. That code is available in the docrails_kindle project.

The Art of Unix Programming by Eric Steven Raymond

screen screen

This one is my personal favorite.

If you enjoy the Kindlefodder version, I encourage you to buy the print version or the official Kindle version as well, to support the author. I have both versions.

Writing your own ebook recipes

Read on if you're interested in learning how to contribute recipes for turning web documentation for other products and services into Kindle ebooks.

If you want to turn web content into an ebook but don't have the time or skill to write the Kindlefodder recipe, you can post an issue requesting help from someone who might be interested in writing that recipe.

Otherwise, my software outfit, Kaja Software LLC, may be willing to do it for a reasonable fee. Send your inquiry to info@kajasoftware.com.

Requirements

Also, download Amazon's KindleGen 2 tool and put it on your PATH.

How to write a recipe

Fork this project and git clone your fork. cd into the cloned project directory.

Run bundle install to make sure you have the required dependencies (nokogiri and kindlerb) in the gem path.

Create a recipe file in the recipes/ directory.

Follow the existing recipes as models. The recipes/heroku.rb recipe was the first and is also the most extensively commented.

The requirements of a recipe should be simple and straightforward. I've tried to minimize the amount of work a recipe has to do by abstracting away all the low-level details of generating Kindle MOBI documents. You won't have to think about NCX and OPF files, just fetching HTML source material, cleaning the HTML up, and splitting it up into Kindle sections and articles. Images will be downloaded, converted to grayscale gifs, resized, and incorporated into the ebook automatically (as long as the src attributes of the img tags point to absolute URLs).

Still, writing recipe code to clean up and extract Kindle-friendly content can sometimes be time-consuming, depending on the source. Often you will have to strip out or tweak HTML content to make it work better in Kindle format. But thanks to the expressive power of Ruby and Nokogiri, performing the necessary HTML plastic surgery on a source usually takes me no more than 20 minutes.

Once you finish your recipe, generate the ebook with this command:

ruby -Ilib recipes/your_new_recipe.rb

If all goes well, you should have a nice Kindle ebook version of the web documentation you processed.

Now submit a pull request on your fork so I can pull in your recipe.

All recipe contributors will be recognized and thanked heartily on this page.

If you're working on a recipe, you may want post a Github issue saying what you're working on and give it the "recipe in progress" label. This will help prevent unnecessary duplication of effort.

Working with Docker

A Dockerfile is provided to build an image with all dependencies. In order to build image, run

docker build -t kindlefodder .

In order to build your recipe, run

docker run --rm -v $PWD/src:/usr/app/src kindlefodder recipes/your_new_recipe.rb

Issues

This project is new and rough around the edges, so please feel welcome to report issues and contribute to the code.

Kindlefeeder

Kindlefodder is based on what I learned making Kindlefeeder, a feed aggregation service that bundles your favorite RSS and Atom feeds -- like the full content of the front page items of Hacker News -- into Kindle ebooks delivered to your Kindle. There are free and paid versions of this service.