Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 134 lines (97 sloc) 7.033 kb
77cf36d @pote basic readme
authored
1 # Planet.rb
2
addfb10 @pote Nicer formatting, ignoring gemspec file
authored
3 ## Important!
4
c280552 @pote better formatting?
authored
5 This IS a work in progress, although most functionality is already implemented, do not expect much stability, and of course patches are appreciated. :)
7486524 @pote better readme
authored
6
7 This gem is also **[gloriously untested](http://jamiesharpe.info/image/comics/haters/haters_gonna_hate3.jpg)** so I will assume that each time we use it a TDD enthusiast's head explodes. I expect, of course, to add some testing later, but for now I'd rather focus on functionality.
addfb10 @pote Nicer formatting, ignoring gemspec file
authored
8
9 ## What is this devilry?
77cf36d @pote basic readme
authored
10
11 An awesome RSS/Atom feed aggregator designed with Octopress/Jekyll in mind, it will parse a given
c280552 @pote better formatting?
authored
12 list of blogs and output them in a format suitable for usage with these amazing blogging engines.
77cf36d @pote basic readme
authored
13
14 ## Main Features
15
c280552 @pote better formatting?
authored
16 * Parse blogs, save posts as plain text files, ready to use with Octopress/Jekyll.
856a18d @pote updated documentation
authored
17 * Dead easy to set up.
18 * Can be used on a regular blog, to import posts from other blogs while maintaining proper credits to the original author.
19 * Completely unobstrusive, will not mess up your Octopress or Jekyll set up by changing files around.
7486524 @pote better readme
authored
20
856a18d @pote updated documentation
authored
21 ## Basic Set Up
7486524 @pote better readme
authored
22
23 So let's assume we have an [Octopress](http://octopress.org) blog. If you are not familiar with Octopress/Jekyll I suggest to check out its [documentation](http://octopress.org/docs/) before going any further.
24
c280552 @pote better formatting?
authored
25
26 ```shell
27 ▸ ls
28 CHANGELOG.markdown README.markdown config.rb public
29 Gemfile Rakefile config.ru sass
30 Gemfile.lock _config.yml plugins source
31 ```
7486524 @pote better readme
authored
32
33 Install the planet.rb gem
34
c280552 @pote better formatting?
authored
35 ```shell
36 ▸ gem install planet
856a18d @pote updated documentation
authored
37 Successfully installed planet-0.2.4
c280552 @pote better formatting?
authored
38 1 gem installed
856a18d @pote updated documentation
authored
39 Installing ri documentation for planet-0.2.4...
40 Installing RDoc documentation for planet-0.2.4...
c280552 @pote better formatting?
authored
41 ```
7486524 @pote better readme
authored
42
43 Were we will create a sample planet.yml config file
44
c280552 @pote better formatting?
authored
45 ```shell
46 ▸ planet init
856a18d @pote updated documentation
authored
47 => Created default planet.yml
c280552 @pote better formatting?
authored
48 ```
7486524 @pote better readme
authored
49
50 You will most likely want to edit this yml file (unless you reallly really like me and [Cubox](http://cuboxlabs.com)!), after you are done, run the generate command.
51
c280552 @pote better formatting?
authored
52 ```shell
53 ▸ planet generate
4f3eae6 @pote correction to match latest gem version
authored
54 => You are missing some files in your templates directory, planet.rb will create them for you - make sure to review them on source/_layouts/!
4470299 @pote Updated usage documentation
authored
55 => Created default source/_layouts/author.html
56 => Created default source/_layouts/header.md
4f3eae6 @pote correction to match latest gem version
authored
57 => Parsing http://blog.poteland.com/atom.xml
4470299 @pote Updated usage documentation
authored
58 => Found post titled I made a pretty gem - Planet.rb - by Pablo Astigarraga
4f3eae6 @pote correction to match latest gem version
authored
59 => Parsing http://blog.cuboxlabs.com/atom.xml
856a18d @pote updated documentation
authored
60 => Found post titled Mozilla Developer Network Hack Day Montevideo 2012 - by Cubox
4470299 @pote Updated usage documentation
authored
61 => Found post titled Cubox brings back Ruby meetups to Montevideo - by Cubox
62 => Found post titled We're hiring - by Cubox
63 => Found post titled rubydeps - New gem by Cuboxer - by Cubox
64 => Found post titled Cuboxers at wroc_love.rb in Poland - by Cubox
65 => Found post titled Open Source Projects - by Cubox
66 => Found post titled Machine learning in perspective - by Cubox
67 => Found post titled Cubox on finances - by Cubox
68 => Found post titled So what is Uruguay like? - by Cubox
69 => Found post titled Supporting this weekend's Rails Bugmash - by Cubox
70 => Found post titled One App in the App Store - by Cubox
71 => Found post titled A new website - by Cubox
72 => Found post titled Google Chrome OS: Obvious to the point of being boring. - by Cubox
856a18d @pote updated documentation
authored
73 => Writing 14 posts to the source/_posts/ directory
c280552 @pote better formatting?
authored
74 ```
7486524 @pote better readme
authored
75
4470299 @pote Updated usage documentation
authored
76 And that's it! your source/_posts/ directory (or whatever you selected in your planet.yml file) should be populated with all relevant posts from the blogs you've configured, and it's ready to be consumed by Octopress. :)
7486524 @pote better readme
authored
77
856a18d @pote updated documentation
authored
78 ## planet.yml
79
80 The planet.yml file contains the basic config options for planet. It consists of some basic fields that need to be there, as well as some that can be simply ignored or just picked up from the feed. Namely
81
82 ```yaml
83 planet:
84 posts_directory: source/_posts/ # => Posts text files will be written into this directory
85 templates_directory: source/_layouts/ # => Planet specific layouts will be saved here, I suggest that it matches your Octopress/Jekyll layout directory.
86
87 blogs:
88 - author: "Cubox" # => Name that we will use as the author of this post (soon you wont have to specify this :)
89 feed: "http://blog.cuboxlabs.com/atom.xml" # => RSS/Atom feed
90 image: "http://cubox-website.s3.amazonaws.com/i-work-at-cubox/i-work-at-cubox-badge-small.png" # => Image to use when doing credits
91
92 - author: "Pablo Astigarraga"
93 feed: "http://blog.poteland.com/atom.xml"
94 image: "http://poteland.com/images/avatars/red_mage.png"
95 twitter: "poteland" # => Do you want a link to the user's twitter account next to the credits? You got it.
96 url: "http://blog.poteland.com" # => This is not needed in most cases, because it's picked up from the feed, but if it's not on the feed
97 # then planet will ask you to specify it. :)
98
99 ```
100
76f23ea @pote updated documentation
authored
101 ## Layouts
102
103 So this is pretty sweet: planet.rb doesn't really want to inject html and random stuff that you can't control into your posts, that's why it uses templates to handle the extra text (namely: the header and footer of each post). This files are by default created in source/_layouts, and this is the list of stuff you can dynamically put in there, along with what you would get form it on my own blog.
104
105 ```mustache
106 {{ post_title }} # => "I Made a Pretty Gem - Planet.rb"
107 {{ post_url }} # => "http://blog.poteland.com/blog/2012/04/14/i-made-a-pretty-gem-planet-dot-rb/"
108 {{ post_date }} # => "2012-04-14 05:17:00 UTC"
109 {{ post_content }} # => "I’ve been hurting to write this ever since we had the idea of creating a Planet for Cubox..." (Continued)
110 {{ blog_name }} # => "This is where I tell you stuff"
111 {{ blog_url }} # => "http://blog.poteland.com"
112 {{ image_url }} # => "http://poteland.com/images/avatars/red_mage.png"
113 {{ author }} # => "Pablo Astigarraga"
114 {{ twitter }} # => "poteland"
115 {{ twitter_url }} # => "http://twitter.com/poteland"
116 ```
117
1f7b798 @pote Typo.
authored
118 So feel free to customize planet.rb layouts any way you see fit (but please don't take away the author.html file! You should definitely give credit to the author of hte post)
856a18d @pote updated documentation
authored
119
6eea85d @pote cuboxlabs is using it!
authored
120 ### A quick note about Jekyll
7486524 @pote better readme
authored
121
122 You don't really need an explanation if you are using Jekyll, just initialize and generate the planet whenever you have your _posts directory and you'll be good to go :)
856a18d @pote updated documentation
authored
123
6eea85d @pote cuboxlabs is using it!
authored
124 # In The wild
125
126 planet.rb is used in the following website (that I know of)
127
128 * blog.cuboxlabs.com # => Where it coexists with Cubox's own posts, it has at the time of this writing about double the content it would have without planet.rb :)
129
856a18d @pote updated documentation
authored
130
eb2f202 @pote removed TODO (taken to github issues), added sponsoship
authored
131 # Sponsorship
132
133 This project is sponsored by the amazing people at [Cubox](http://cuboxlabs.com) that make it possible for me to work on this without dying of starvation, BIG THANKS to them! (oh, and their [blog](http://blog.cuboxlabs.com] uses planet.rb, too! ;) )
Something went wrong with that request. Please try again.