kindle-feeds

Fri Aug 22 2008

kindle-feeds is a command line tool that downloads Atom and RSS feeds and converts them into a special HTML file optimized for reading on the Amazon Kindle.

Here are some screenshots of the kindle-feeds output transferred to the Kindle. (Sorry for the super-amateur photography.)

REQUIREMENTS

Mac OS X Leopard users should be able to install this program and run it without any problems. GNU/Linux users should also be able to run this program, as long as Ruby and RubyGems are installed on the system. Windows users, Emmanuel Huna has written up a detailed guide on running kindle-feeds on Windows.

INSTALLATION

You can install kindle-feeds by following these steps. I’m going to assume you’re a Mac OS X Leopard user from this point forward. I’m also going to assume less UNIX knowledge than usual, so I’ll make the steps as explicit as possible and opt for basic techniques over advanced UNIX shortcuts.

First, you need to install the OS X XCode Developer Tools if you haven’t already:

  • Insert your Leopard DVD
  • When the window opens double-click Optional Installs folder
  • Open XcodeTools folder
  • Double-click XcodeTools.mpkg to install it

Next, open a Terminal window. To find the Terminal program, click on your Desktop background once (or select the Finder application using Command Apple + Tab), and then select “Go” from the menu options in the menu bar and then select “Utilities.” You’ll see a window open up containing some applications. Find and launch the one called Terminal.

A Terminal window should appear. This is the command line interface to your computer. Your Terminal window will look something like this:

Now you can install kindle-feeds by typing this simple one-line command in the Terminal:

sudo gem install kindle-feeds

Press RETURN at the end of this and all commands from here on.

Here is how it looks graphically:

You’ll be asked for your administrative password, the password you set when you created your OS X user account. After you enter your password, you’ll see some output like this:

The output may vary depending on your setup, but as long as you see “Sucessfully installed kindle-feeds-X.Y.Z,” you can assume that you have successfully installed the program.

CHOOSE YOUR FEEDS

After kindle-feeds is installed, make a directory where you will generate your kindle-feeds files. To do this, type

mkdir Documents/KindleFeeds

Go into that directory

cd Documents/KindleFeeds

Now you can run kindle-feeds by typing

kindle-feeds

This will generate the following output:

Can't find kindle_feeds.conf. Generating...
Please edit kindle_feeds.conf before running kindle-feeds again.

This is what the last few steps should look like so far:

Then open kindle_feeds.conf in a text editor and edit it so that it contains the feeds and section titles you want.

To open this file in TextEdit, type

open -a TextEdit.app kindle_feeds.conf

Now you should see a file open that looks like this:

You can edit this file to contain the feeds and sections you want. When you’re done editing, save the file. You can also quit TextEdit.

Now you can download feeds and generate your a kindle-feeds document. In the Terminal window you were using before, type

kindle-feeds

to run kindle-feeds. You’ll get output like this:

Reading kindle_feeds.conf for feed URLs.

Fetching feeds:
- General News
  - nytimes.com
  - slate.com
- Tech News
  - techcrunch.com
  - http://readwriteweb.com
  - slashdot.org
- Apple
  - macworld.com
  - macintouch.com
- Ebook
  - teleread.org/blog

Downloading http://nytimes.com
http://nytimes.com: Attempting autodiscovery...
Found feed: http://www.nytimes.com/services/xml/rss/nyt/HomePage.xml
11 entries downloaded.

Downloading http://slate.com
http://slate.com: Attempting autodiscovery...
Found feed: http://www.slate.com/rss
84 entries downloaded.

Downloading http://techcrunch.com
http://techcrunch.com: Attempting autodiscovery...
Found feed: http://feeds.feedburner.com/TechCrunch
25 entries downloaded.

Downloading http://readwriteweb.com
http://readwriteweb.com: Attempting autodiscovery...
Found feed: http://www.readwriteweb.com/rss.xml
15 entries downloaded.

Downloading http://slashdot.org
http://slashdot.org: Attempting autodiscovery...
Found feed: http://rss.slashdot.org/Slashdot/slashdot
15 entries downloaded.

Downloading http://macworld.com
http://macworld.com: Attempting autodiscovery...
Found feed: http://rss.macworld.com/macworld/feeds/main
50 entries downloaded.

Downloading http://macintouch.com
http://macintouch.com: Attempting autodiscovery...
Found feed: http://www.macintouch.com/rss.xml
41 entries downloaded.

Downloading http://teleread.org/blog
http://teleread.org/blog: Attempting autodiscovery...
Found feed: http://www.teleread.org/blog/feed/
15 entries downloaded.

Converting feeds into Kindle-compatible and optimized HTML...

Output written to file:
Kindle Feeds 08-22-2008.html

Email this file as an attachment to YOUR_KINDLE_USERNAME@kindle.com or YOUR_KINDLE_USERNAME@free.kindle.com.

Visit http://www.amazon.com/gp/help/customer/display.html?nodeId=200140600 for more help.
Done.

The result of all this processing is a file named “Kindle Feeds 08-22-2008.html” (the date-stamp portion of the filename will vary), which should appear in the directory you ran the command from.

To see the file in the Finder, type this command in the Terminal:

open .

That’s the word “open” followed by a space, followed by a period, followed by RETURN.

A Finder window should open showing the contents of your Documents/KindleFeeds directory, which will include the Kindle Feeds 08-22-2008.html file.

Note that you can’t transfer the file directly to the Kindle. You have to send this file as an email attachment to your Kindle email account for the final processing step. Depending on whether you send the file to your @kindle.com or @free.kindle.com address, the final document will be delivered wirelessly to your Kindle or sent back in processed form via email for you to transfer manually over to your Kindle via USB. Check out Amazon’s help page for detailed instructions.

To run kindle-feeds again, all you have to do is open a Terminal window, cd into your Kindle Feeds directory, and run kindle-feeds again. The program will read your feeds list in kindle_feeds.conf every time it runs and generate a new “Kindle Feeds MM-DD-YYYY.html” document each time using the latest feed content.

AUTOMATION

If you’re a programmer, it’s possible of course to automate this process with cron so that it runs every day automatically and sends the generated output to your kindle user email account for wireless delivery to your Kindle. That works out to $3 a month to peruse my favorite feeds on my Kindle without having to resort to the very slow Web Browser mode, which to me is not a bad deal.

If you’re not a programmer, you may still want to have automated daily delivery. I’m thinking of setting up a website that will let you pick your feeds and perform the conversion round-trip and delivery automatically each day (or whatever interval you want) for a small fee — maybe $2 a month per user (on top of what Amazon will charge for the Whispernet transmission). Please let me know if this is something you’re interested in on the Amazon discussion forum thread I started for kindle-feeds. If there is enough interest I’ll design and build the website for this. The website will also let you get your Kindle Feeds without going through the setup steps above.

SOURCE, BUG REPORTS, FEATURE REQUESTS

This software is open source. You can read the source and commit diffs here.

Please visit the RubyForge page for this project to file bug reports or request enhancements and features.

You can also leave comments on the Amazon discussion thread for kindle-feeds.

back to top

a tweaked version of the micro theme by seaofclouds, and powered by YAML, Textile, and this simple, home-grown ruby build script.