Skip to content
Newer
Older
100644 138 lines (104 sloc) 7.09 KB
77cf36d @pote basic readme
authored Apr 8, 2012
1 # Planet.rb
2
addfb10 @pote Nicer formatting, ignoring gemspec file
authored Apr 8, 2012
3 ## Important!
4
c280552 @pote better formatting?
authored Apr 14, 2012
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 Apr 14, 2012
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 Apr 8, 2012
8
9 ## What is this devilry?
77cf36d @pote basic readme
authored Apr 8, 2012
10
11 An awesome RSS/Atom feed aggregator designed with Octopress/Jekyll in mind, it will parse a given
c280552 @pote better formatting?
authored Apr 14, 2012
12 list of blogs and output them in a format suitable for usage with these amazing blogging engines.
77cf36d @pote basic readme
authored Apr 8, 2012
13
14 ## Main Features
15
c280552 @pote better formatting?
authored Apr 14, 2012
16 * Parse blogs, save posts as plain text files, ready to use with Octopress/Jekyll.
856a18d @pote updated documentation
authored Apr 20, 2012
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 Apr 14, 2012
20
856a18d @pote updated documentation
authored Apr 20, 2012
21 ## Basic Set Up
7486524 @pote better readme
authored Apr 14, 2012
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 Apr 14, 2012
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 Apr 14, 2012
32
33 Install the planet.rb gem
34
c280552 @pote better formatting?
authored Apr 14, 2012
35 ```shell
36 ▸ gem install planet
856a18d @pote updated documentation
authored Apr 20, 2012
37 Successfully installed planet-0.2.4
c280552 @pote better formatting?
authored Apr 14, 2012
38 1 gem installed
856a18d @pote updated documentation
authored Apr 20, 2012
39 Installing ri documentation for planet-0.2.4...
40 Installing RDoc documentation for planet-0.2.4...
c280552 @pote better formatting?
authored Apr 14, 2012
41 ```
7486524 @pote better readme
authored Apr 14, 2012
42
43 Were we will create a sample planet.yml config file
44
c280552 @pote better formatting?
authored Apr 14, 2012
45 ```shell
46 ▸ planet init
856a18d @pote updated documentation
authored Apr 20, 2012
47 => Created default planet.yml
c280552 @pote better formatting?
authored Apr 14, 2012
48 ```
7486524 @pote better readme
authored Apr 14, 2012
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 Apr 14, 2012
52 ```shell
53 ▸ planet generate
4f3eae6 @pote correction to match latest gem version
authored Apr 19, 2012
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 Apr 19, 2012
55 => Created default source/_layouts/author.html
56 => Created default source/_layouts/header.md
4f3eae6 @pote correction to match latest gem version
authored Apr 19, 2012
57 => Parsing http://blog.poteland.com/atom.xml
4470299 @pote Updated usage documentation
authored Apr 19, 2012
58 => Found post titled I made a pretty gem - Planet.rb - by Pablo Astigarraga
4f3eae6 @pote correction to match latest gem version
authored Apr 19, 2012
59 => Parsing http://blog.cuboxlabs.com/atom.xml
856a18d @pote updated documentation
authored Apr 20, 2012
60 => Found post titled Mozilla Developer Network Hack Day Montevideo 2012 - by Cubox
4470299 @pote Updated usage documentation
authored Apr 19, 2012
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 Apr 20, 2012
73 => Writing 14 posts to the source/_posts/ directory
c280552 @pote better formatting?
authored Apr 14, 2012
74 ```
7486524 @pote better readme
authored Apr 14, 2012
75
4470299 @pote Updated usage documentation
authored Apr 19, 2012
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 Apr 14, 2012
77
856a18d @pote updated documentation
authored Apr 20, 2012
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 Apr 20, 2012
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
118 So feel free to customize planet.rb layouts any way you see fit (but please don't take away the author.html files! You should definitely give credit to the author of hte post)
856a18d @pote updated documentation
authored Apr 20, 2012
119
00d5c41 @pote Typo.
authored Apr 20, 2012
120 ## Jekyll Usage
7486524 @pote better readme
authored Apr 14, 2012
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 Apr 20, 2012
123
124
76f23ea @pote updated documentation
authored Apr 21, 2012
125 ## TODO:
856a18d @pote updated documentation
authored Apr 20, 2012
126
76f23ea @pote updated documentation
authored Apr 21, 2012
127 * Contemplate nested planets - images, particularly.
128 * Handle upgrade of planet template files on gem update
c446965 @pote new todo, removed old todo, bumped credits, it definitely needs to be…
authored Apr 20, 2012
129 * Create complete templates and posts directory tree if necessary
efc7128 @pote todos and stuff
authored Apr 20, 2012
130 * Write blog post on "Importing your blog to octopress with planet.rb"
131 * Find out why http://microformatique.com/optimus/?uri=http://mcdlr.com/&format=rss doesnt work
1082161 @pote todo stuff
authored Apr 20, 2012
132 * Get images from twitter if provided, or in some other magical way.
133 * Handle images that are not aligned correctly?
802e05e @pote fix problem with broken post titles
authored Apr 20, 2012
134 * Create "Participating blogs" template for the sidebar
f5f0155 @pote prioritize like a product lead!
authored Apr 20, 2012
135 * Support blog author being taken out directly from the feed so it's not required on planet.yml (move author to Post class?)
ba8911c @pote todo stuff
authored Apr 20, 2012
136 * Handle categories/tags?
1082161 @pote todo stuff
authored Apr 20, 2012
137 * Find an alternative to Feedzirra that doesnt install a million dependencies.
Something went wrong with that request. Please try again.