Roar is a static website generator, forked from Growl, which in turn is heavily inspired from Jekyll, and which shamelessly stole some really cool ideas from Jekyll.
Nevertheless Growl brought some nice features:
- Minimal dependencies
- Easy to install (and use? ;])
- Easy to extend
The Growl based site of xfire's blog is also available on github.
On top, Roar departs from Growl in some aspects:
- Even less dependencies (e.g. Yaml is no longer used)
- Packaged for the PyPi
- Actively maintained
The following basic packages are needed:
> apt-get install python
All other is optional depending on you own needs.
I recommend using Jinja2 as the templating engine. Roar will use Jinja2 as default, if it is installed.
> apt-get install python-jinja2
You are free to use some other templating engine like Django, Mako or Cheetah. for examples how to configure them, see extending Roar.
After installing all needed packages, you can use roar
directly or copy it to a place which is in your $PATH.
> ./roar ...
> cp roar /usr/local/bin
Simply call roar with the source directory:
> roar my.site
Roar will then generate the output in the directory my.site/_deploy.
if you want Roar to spit the generated stuff into another directory,
simply specify this director as second parameter.
> roar my.site /tmp/my.site.output
-
--serve[:port](default port: 8080)Generate the site to the deploy directory and then start a simple webserver. this is intended to be used for testing purposes only.
roar my.site --serve 1234
-
--deployTrigger deploy process. this does nothing per default, but you can add actions using hooks. (see
_hooks/deploy_rsync.py)
Roar will ignore all files and directories which starts with
a . or a _. (this can be changed via Site.IGNORE, see
extending Roar)
All files ending with _ or a transformer extension (Config.transformers)
are processed as pages. in these cases, the ending will be striped from
the filename. E.g.
index.html_->index.htmlatom.xml_->atom.xmlsomefile.txt.markdown->somefile.txt
Some directories beginning with an _ are special to Roar:
_deploy/the default deploy directory_layout/contains your site layouts_posts/contains your posts_hooks/contains all your hooks (see extending roar)_libs/contains third party code (see extending roar)
All pages and posts must have an rfc822 header. An empty line
separates the header from the content. Example:
layout: post
title: my post title
category: spam, eggs
<html>
<!-- more content here -->
</html>
If no headers are needed, and empty rfc822 header section consisting
of an empty line before the actual content will work.
All data defined in this header will be attached to the corresponding object and can be accessed in your template code. an example in Jinja2 may look like
<ul>
{% for post in site.posts|reverse %}
<li>{{ post.title }} - {{ post.date }}</li>
{% endfor %}
</ul>
in the context of your template, you have access to one or more of the following objects.
This holds the site wide informations.
-
site.nowCurrent date and time when you run roar. this is a Python datetime object.
{{ site.now.year }}-{{site.now.month}}
-
site.postsChronological list of all posts.
{% for post in site.posts|reverse|slice(8) %} {{ post.content }} {% endfor %}
-
site.unpublished_postsChronological list of all unpublished posts. e.g. all posts which set
publishtofalse. -
site.categoriesDictionary mapping category <-> posts.
-
{% for cat in site.categories %}
- {{ cat }}
-
{% for post in site.categories.get(cat) %}
- {{ post.title }} - {{ post.date }} {% endfor %}
{% endfor %}
- {{ cat }}
-
page.urlThe relative URL to the page.
-
page.transformedThe transformed content. no layouts are applied here.
-
post.dateA
datetimeobject with the publish date of the post. -
post.urlRelative URL to the post.
-
post.publishIf set to
false, the post will be generated, but is not in the list ofsite.posts. Instead it's in thesite.unpublished_postslist.If
publishis not set, Roar will assume this astrueand the post will be normally published. -
post.contentThe transformed content. Exactly the layout specified in the
rfc822header is applied (no recursive applying). -
post.transformedThe transformed content. No layouts are applied here.
Roar is very easy extendable via Python code placed in the _hooks and
_libs directory.
If the _libs directory exists, it is added to the Python module search path
(sys.path), so Python modules dropped there will be available in the code.
All files in the _hooks directory, which end with .py, are executed
directly in the global scope of the roar script. Thus a hook can freely
shape Roar's code at will. Roar loves that! ;)
Here are some examples of what can be done. But you sure can imagine other cool things.
New transformers can be registered in the Config class by adding a
filename extension <-> transformation function mapping to the transformers
attribute. here's an example for markdown2:
import markdown2
import functools
Config.transformers['noop'] = lambda source: source
Config.transformers['markdown2'] = functools.partial(
markdown2.markdown,
extras={'code-color': {"noclasses": True}})
The transformation function must return the transformed source text which is given as the only parameter. so if you need to add more parameters to your transformation function, best use the functools module as you see in the example above.
Roar decides to ignore files which filenames start with one of the tokens
defined in Site.IGNORE. so a hook with the following content will make
Roar ignore all files begining with ., _ and foo.
Site.IGNORE += ('foo',)
Simply add your content to Site.CONTEXT like these examples:
Site.CONTEXT.author = 'Rico Schiekel'
Site.CONTEXT.site = AttrDict(author = 'Rico Schiekel')
Note: Site.CONTEXT.site has to be an AttrDict instance!
As an example, we would display the currently processed post, while Roar chomps your input.
Create a new file (e.g. verbose.py) in the _hooks directory with the
following content:
@wrap(Post.write)
def verbose_post_write(forig, self):
print 'post: %s - %s\n' % (self.date.strftime('%Y-%m-%d'), self.title)
return forig(self)
Roar offers the helper decorator wrap, which wraps an existing method
of a class with a new one. the original method is given to your new function
as the first parameter (forig).
Please report bugs here.