Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 340 lines (222 sloc) 13.056 kb
3d7ace49 » colszowka
2010-02-13 Added documentation
1 = Serious
c7d9c349 » colszowka
2010-02-12 Initial commit to serious.
2
f8fa495c » colszowka
2010-02-13 Removed rdoc links due to bug in github: http://support.github.com/di…
3 Serious is a blog engine inspired by other filesystem-based engines like jekyll (http://jekyllrb.com/)
e0fe780a » colszowka
2010-02-13 Updated docs
4 and toto (http://cloudhead.io/toto) and is based upon Sinatra and rack, thus can be hosted
383c12b9 » colszowka
2010-02-13 Added disqus
5 very easily (and for free) on heroku (http://heroku.com).
3d7ace49 » colszowka
2010-02-13 Added documentation
6
7 The articles are stored in plain text files with an opinionated naming scheme which is used for
8 getting the date and permalink of your article: <code>articles/2010-02-14-will-you-be-my-valentine.txt</code>
9
10 The actual content of the article is lazy-loaded only when accessed, so things don't get messy when a lot
11 of articles has to be maintained. Articles consist of a YAML front, an optional summary and the body,
12 so a basic article looks something like this:
13
14 title: My shiny article
15 author: Christoph Olszowka
16
17 Some nice summary.
18 ~
19 ## Some content. You can use markdown in your articles, and also <%= "erb" %>
20 <% highlight do %>
ea9c55e4 » colszowka
2010-02-13 Gemspec for 0.2. Added binary serious, which allows for easy creation…
21 puts "it will also syntax-highlight your codes"
3d7ace49 » colszowka
2010-02-13 Added documentation
22 <% end %>
23
24 There are quite a few assumptions made by this format: You have to specify your title in yaml format
25 upfront. You can also specify an author for this article. If you don't, it will fall-back to the
26 default one (see configuration). Then two newlines must follow to seperate the yaml from the actual
27 content. After this, you can type your blog post. If you want a summary, add in the summary/body
28 delimiter "~", so Serious knows what you want.
29
f8fa495c » colszowka
2010-02-13 Removed rdoc links due to bug in github: http://support.github.com/di…
30 Serious makes use of StupidFormatter (http://github.com/colszowka/stupid_formatter) for formatting
3d7ace49 » colszowka
2010-02-13 Added documentation
31 your articles, so you get ERb, Markdown and Coderay syntax highlighting for free and can customize
f8fa495c » colszowka
2010-02-13 Removed rdoc links due to bug in github: http://support.github.com/di…
32 the processing chain to your liking, add custom ERb helpers and so on. See the documentation of
33 stupid_formatter (http://rdoc.info/projects/colszowka/stupid_formatter) to learn how to
3d7ace49 » colszowka
2010-02-13 Added documentation
34 customize the formatting.
35
3a0dff15 » colszowka
2011-08-01 Added a note about future dates on articles for delayed publishing to…
36 Articles with a date in the future will not appear on the site, thus allowing you to prepare article
37 that should be published later.
38
3d7ace49 » colszowka
2010-02-13 Added documentation
39 == Getting started
40
41 Install the gem:
42
43 sudo gem install serious
44
0b8c017b » colszowka
2010-02-13 Updated documentation with generator tutorial
45 You can use the supplied generator using the <code>serious</code> executable provided with the gem.
46 Type <code>serious</code> in your shell to see the available options.
3d7ace49 » colszowka
2010-02-13 Added documentation
47
0b8c017b » colszowka
2010-02-13 Updated documentation with generator tutorial
48 By default the generator will create the app with gem-based public and views directories and initialize
49 a git repository. To host your app on heroku instantly, supply the --heroku option, which will use
50 the heroku gem to create your app and push it to heroku via git. Type:
51
52 serious my-fancy-blog --heroku
53
54 And you can go to http://my-fancy-blog.heroku.com to see your new blog!
55
56 == The setup
57
58 The directory basic directory structure of your Serious site would be something like this:
3d7ace49 » colszowka
2010-02-13 Added documentation
59
60 serious_blog/
61 - articles
2e263c86 » colszowka
2010-02-13 Pages done
62 - 2010-02-14-will-you-be-my-valentine.txt
63 - pages
64 - about.txt
3d7ace49 » colszowka
2010-02-13 Added documentation
65 - config.ru
79958c66 » colszowka
2010-08-17 Use Bundler instead of heroku .gems file for new blogs
66 - Gemfile
5c627231 » colszowka
2010-02-13 Added Rake tasks, updated docs
67 - Rakefile
3d7ace49 » colszowka
2010-02-13 Added documentation
68
69 The config.ru is pretty straight-forward if you want to stick to the defaults:
70
71 require 'serious'
72 Serious.set :title, "My Sweet Little Blog"
73 Serious.set :author, "Christoph Olszowka"
74 Serious.set :url, 'http://mysweetlittleblog.heroku.com'
75 run Serious
76
79958c66 » colszowka
2010-08-17 Use Bundler instead of heroku .gems file for new blogs
77 The Gemfile to resolve dependencies (i.e. when hosting on heroku)
3d7ace49 » colszowka
2010-02-13 Added documentation
78
79958c66 » colszowka
2010-08-17 Use Bundler instead of heroku .gems file for new blogs
79 source :rubygems
61470b91 » colszowka
2011-02-09 Fixed unneccesary version in Gemfile example in README
80 gem "serious"
3d7ace49 » colszowka
2010-02-13 Added documentation
81
2e263c86 » colszowka
2010-02-13 Pages done
82 The Rakefile, which is obviously totally optional but highly recommended looks like this:
5c627231 » colszowka
2010-02-13 Added Rake tasks, updated docs
83
84 require 'serious'
85 require 'serious/tasks'
2e263c86 » colszowka
2010-02-13 Pages done
86
170942bc » colszowka
2011-02-09 Updated README with supported rubies note
87 == Supported Rubies
88
89 The gem tests are run against 1.8.7, REE, 1.9.1 and 1.9.2, so Serious should run fine at least
90 on those interpreters - it is highly recommended to go with 1.9.2 though.
91
0b8c017b » colszowka
2010-02-13 Updated documentation with generator tutorial
92 == Creating heroku app manually
93
3d7ace49 » colszowka
2010-02-13 Added documentation
94 Assuming you've got the heroku gem installed and set up and you've set up git for your blog with
0b8c017b » colszowka
2010-02-13 Updated documentation with generator tutorial
95 <code>git init</code> or sticked with the generator, which created your git repo, you can now do:
3d7ace49 » colszowka
2010-02-13 Added documentation
96
97 heroku create mysweetlittleblog
98 git push heroku master
99
100 Point your browser to the url, and bang, you're ready!
101
f2842d93 » colszowka
2010-02-13 Updated thin doc
102 == Running locally
0b8c017b » colszowka
2010-02-13 Updated documentation with generator tutorial
103
f2842d93 » colszowka
2010-02-13 Updated thin doc
104 You might also want to test your blog locally. Use the <code>rake server</code> command inside
105 your site's directory.
106
107 You can also use thin (<code>sudo gem install thin</code>) with:
18ef75a0 » colszowka
2010-02-13 Even more docs
108
109 thin -R config.ru start
110
8afc08d0 » colszowka
2010-02-13 Fixed docs
111 Go to <code>localhost:3000</code> and enjoy.
18ef75a0 » colszowka
2010-02-13 Even more docs
112
c52bf374 » colszowka
2010-02-13 Improved docs
113 == Archives
114
115 The whole archives can be accessed at <code>/archives</code>. Archives by year, month and date
116 are available at <code>/2009</code> (all of 2009), <code>/2009/05</code> (May 2009),
117 <code>/2009/05/15</code> (May 15th 2009).
118
2e263c86 » colszowka
2010-02-13 Pages done
119 == Static pages
120
121 Static pages are quite similar to blog articles, in that their formatting and processing is the same.
122 They have a yaml front matter, content that gets piped through the StupidFormatter and so on.
123 The filename sans the extension serves as the permalink, pages can be reached via
124 <code>/pages/PERMALINK</code>, so the content in pages/about.txt will be served at
125 <code>/pages/about</code>
126
f74941b7 » colszowka
2010-02-13 Added rackup server rake task and documentation
127 == Rake tasks
128
129 If you've set up the Rakefile in your site's main directory like mentioned above (this happens
130 automatically when generating with the <code>serious</code> executable), you have the following
131 tasks available:
132
133 rake article:create # Creates a new article
134 rake article:validate # Validates all articles, making sure they can be processed correctly
135 rake server # Runs a server hosting your site on localhost:3000 using rackup
136
137 The default is article:create, so to create a new article, just type <code>rake</code>,
138 specify your title and optionally a date and you're ready to go!
139
140 It's highly recommended that you run the <code>article:validate</code> task before publishing,
141 since it will make sure everything gets processed correctly.
142
143 Please be aware that you have to run the Rake tasks from the top level directory (where your
144 <code>config.ru</code> file resides) since the config.ru file will be loaded to reflect your
145 settings.
146
383c12b9 » colszowka
2010-02-13 Added disqus
147 == Comments with disqus
148
149 You can activate comments for articles very easily with disqus (http://disqus.com) by setting
150 the <code>disqus</code> property to your disqus-id (e.g. 'myfancysite'). Disqus developer mode will
151 be automatically activated for requests served by http://localhost so you can preview your settings
152 and layout properly.
153
154 Serious.set :disqus, 'yourid'
683156da » colszowka
2010-02-13 Added google analytics
155
156 == Google Analytics
157
158 You can activate Google Analytics by setting the <code>google_analytics</code> property to your
159 tracker id (something like 'UA-123123-5'). The required code will then be included to your site.
160 For requests served from http://localhost, the inclusion is skipped.
161
162 Serious.set :google_analytics, 'UA-123123-5'
383c12b9 » colszowka
2010-02-13 Added disqus
163
683156da » colszowka
2010-02-13 Added google analytics
164 == Configuration options
3d7ace49 » colszowka
2010-02-13 Added documentation
165
166 Inside your config.ru, you can customize the settings for your Serious site.
167
168 === Custom view templates or public folder
169
170 ==== Changing the path to the public folder
171
172 Say you want to stick with the default view templates, but are willing to customize the css
173 to make things prettier. You can do so. Get the provided css from <code>lib/serious/site/public</code>
174 and point Serious to your new public folder, which assumingly lies in the current working directory
175 (which is where your config.ru file is)
176
177 Serious.set :public, File.join(Dir.getwd, 'public')
178
179 Serious will now serve the public directory from your custom location, but still get the views
180 provided with the gem.
181
182 ==== Changing the path to the views
183
184 Accordingly, if you want to stick with the default css, but want to customize the templates (would anyone
185 want to do this?), specify the views path and get the provided ones from the gem as a starting point.
186
187 Serious.set :views, File.join(Dir.getwd, 'views')
188
189 ==== Setting the root
190
191 The most likely case though will surely be that you want to move both <code>public</code> and
192 <code>views</code> into your site. Again, just copy over the provided assets from the gems
193 <code>lib/serious/site/</code> folder into your own site and modify them to your liking.
194 You'll have to specify a new root for your site, set to the current working directory, where
195 your config.ru resides:
196
197 Serious.set :root, Dir.getwd
198
199 Note that you do not have to specify the views and public folders separately, they'll be hosted
200 from the roots views and public subdirectory.
201
18ef75a0 » colszowka
2010-02-13 Even more docs
202 === Setting the articles path
203
204 You want your articles hosted from your home directory or fancy a different folder name?
205 Use the :article property, which defaults to the articles subdirectory of the current
206 working dir (a.k.a. where your config.ru sits)
207
208 Serious.set :articles, '/home/youruser/myblogposts'
209
ba89a03b » colszowka
2010-02-14 Updated rdoc with static pages
210 === Setting the pages path
211
212 Similarily to the articles path, the pages will be served from your sites working directory's
213 subdirectory <code>pages</code>. Customize this with:
214
215 Serious.set :pages, '/home/youruser/mystaticpages'
216
3d7ace49 » colszowka
2010-02-13 Added documentation
217 === The title
218
219 The title is used for your atom feed, the site name and so on. It defaults to 'Serious' and you
220 can specify it with:
221
222 Serious.set :title, "My Sweet Little Blog"
223
224 === The author
225
226 If you don't want to specify the author for each article separately in the YAML front matter,
227 you can define the blog author, which will be used as a fall-back when no custom article author
228 is given in the YAML. It defaults to 'unknown'
229
230 Serious.set :author, "Christoph Olszowka"
231
232 === The url
233
234 Well, your site has to know where it lives to provide proper links in your atom feed. Configure this
235 with the url setting, which defaults to 'http://localhost:3000'
236
237 Serious.set :url, 'http://localhost:3000'
4b0c9ff2 » colszowka
2010-02-13 Customizible date formats
238
239 === The date format
240
241 There is a helper in the Date class for formatting dates according to the configuration specified
242 in Serious.date_format and which is used in the frontend. It defaults to "%B %o %Y", which expands
243 to (i.e.) 'December 24th, 2009'. Notice that %o is a custom flag that is not built-in in the default
244 strftime method of Date. It returns the ordinal name of the day. Customize with:
245
246 Serious.set :date_format, "%Y-%m-%d"
3d7ace49 » colszowka
2010-02-13 Added documentation
247
383c12b9 » colszowka
2010-02-13 Added disqus
248 === Disqus comments
249
250 To enable disqus comments, specify your disqus id with the disqus property. Disqus is disabled
683156da » colszowka
2010-02-13 Added google analytics
251 by default. See section above for more information on disqus and comments.
383c12b9 » colszowka
2010-02-13 Added disqus
252
253 Serious.set :disqus, 'yourdisqusid'
254
3c86b21f » colszowka
2010-02-13 Minor fixes in rdoc formatting
255 === Google Analytics
683156da » colszowka
2010-02-13 Added google analytics
256
257 To enable google analytics, specify your tracker id at the property <code>google_analytics</code>.
258 See section above for more information on Google Analytics.
259
260 Serious.set :google_analytics, 'UA-123123-5'
261
3c86b21f » colszowka
2010-02-13 Minor fixes in rdoc formatting
262 === Custom feed url in layout
fa1c3ae5 » colszowka
2010-02-13 Custom feed url implemented
263
264 If you want to specify a different feed url for the head link tag, for example to point your readers
2d0dc3e9 » colszowka
2010-02-13 Updated documentation for feed_url
265 to Feedburner, you can do so by specifiyng the <code>feed_url</code> option and setting up your
266 feed to be burned by feedburner based upon <code>http://yoururl.com/atom.xml</code>.
fa1c3ae5 » colszowka
2010-02-13 Custom feed url implemented
267
268 Serious.set :feed_url, 'http://feeds.feedburner.com/myfeedurl'
269
3d7ace49 » colszowka
2010-02-13 Added documentation
270 === Displayed items
271
272 You can specify how many items you want displayed across your site:
273
274 ==== Amount of feed items
275
276 To customize the amount of items in your atom feed (living under /atom.xml), set the
277 items_in_feed property to an integer. This defaults to 25.
278
279 Serious.set :items_in_feed, 50
280
281 ==== Amount of items with summary on index
282
283 On your index page, the most recent items will be displayed including the summary (or the whole
284 post if you did not use the summary/body delimiter). This defaults to 3 items, but can be customized:
285
286 Serious.set :items_on_index, 5
287
288 ==== Amount of archive items on index
289
290 Below the items with summaries on your main page, there's also a list of 'archived' items, which
291 only includes the title and date. This defaults to 10 items, but can be customized as well:
292
293 Serious.set :archived_on_index, 10
294
295 === Cache timeout
296
297 All pages served are automatically getting a Cache-Control header, so they get cached in your
f8fa495c » colszowka
2010-02-13 Removed rdoc links due to bug in github: http://support.github.com/di…
298 visitor's browsers as well as in Varnish on Heroku (http://docs.heroku.com/http-caching)
3d7ace49 » colszowka
2010-02-13 Added documentation
299 (or some similar tool when you host yourself). The timeout is set to 300 seconds by default, but
300 can be customized with:
301
302 Serious.set :cache_timeout, 300
d200db06 » colszowka
2010-02-13 Updated docs
303
304 === Article formatting
305
306 You can define the formatting chain for StupidFormatter with:
307
308 StupidFormatter.chain = [StupidFormatter::RDiscount]
309
f8fa495c » colszowka
2010-02-13 Removed rdoc links due to bug in github: http://support.github.com/di…
310 You'll surely want to read the documentation of StupidFormatter (http://github.com/colszowka/stupid_formatter)
d200db06 » colszowka
2010-02-13 Updated docs
311 to learn how to add your own formatters or erb helpers.
c7d9c349 » colszowka
2010-02-12 Initial commit to serious.
312
fbe5271e » colszowka
2010-02-12 Updated readme with TODO
313 == TODO
3d7ace49 » colszowka
2010-02-13 Added documentation
314
5b781478 » colszowka
2010-02-25 Removed font-face custom fonts from default setup due to problems wit…
315 * unescaped special chars in yaml front matter can lead to errors
316 * text not readable in android
317 * valid xhtml in demo setup
3d7ace49 » colszowka
2010-02-13 Added documentation
318 * make summary delim configurable
5b781478 » colszowka
2010-02-25 Removed font-face custom fonts from default setup due to problems wit…
319 * improve caching
c52bf374 » colszowka
2010-02-13 Improved docs
320 * make it possible to host in subdirectories
3d7ace49 » colszowka
2010-02-13 Added documentation
321 * allow for choice between erb/haml templates
fbe5271e » colszowka
2010-02-12 Updated readme with TODO
322
c7d9c349 » colszowka
2010-02-12 Initial commit to serious.
323 == Note on Patches/Pull Requests
324
325 * Fork the project.
326 * Make your feature addition or bug fix.
327 * Add tests for it. This is important so I don't break it in a
328 future version unintentionally.
329 * Commit, do not mess with rakefile, version, or history.
330 (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
331 * Send me a pull request. Bonus points for topic branches.
332
c52bf374 » colszowka
2010-02-13 Improved docs
333 == Thanks
334
335 Alexis Sellier for toto, the main inspiration for this gem
336 Ryan Bates for the great coderay css
337
c7d9c349 » colszowka
2010-02-12 Initial commit to serious.
338 == Copyright
339
cc549981 » colszowka
2010-02-12 Implemented article backend with quite extensive tests
340 Copyright (c) 2010 Christoph Olszowka. See LICENSE for details.
Something went wrong with that request. Please try again.