growl - python based, easy extendable, blog aware, static site generator
growl is a static website generator, which is heavily inspired from jekyll, and which shamelessly stole some really cool ideas from jekyll.
nevertheless growl brings some nice features:
- minimal dependencies
- easy to install (and use? ;])
- easy to extend
the growl based site of my blog is also available on github.
installation
prequisites
the following basic packages are needed:
> apt-get install python python-yaml
all other is optional depending on you own needs.
I recommend using jinja2 as the templating engine. growl 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 growl.
finish the installation
after installing all needed packages, you can use growl.py
directly or copy it to a place which is in your $PATH
.
> ./growl.py ...
> cp growl.py /usr/local/bin
usage
simply call growl.py
with the source directory:
> growl.py my.site
growl will then generate the output in the directory my.site/_deploy
.
if you want growl to spit the generated stuff into another directory,
simply specify this director as second parameter.
> growl.py my.site /tmp/my.site.output
options
-
--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.
growl.py --serve -1234 my.site
-
--deploy
trigger deploy process. this does nothing per default, but you can add actions using hooks. (see
_hooks/deploy_rsync.py
) -
--autoreload
or-r
relaunch growl each time a modification occurs on the content files. (Please note: you will be unable to use Growl's built-in webserver when you use --autoreload. To see your changes in the browser, simply navigate to your
_deploy
directory and open up a new terminal instance and use Python's built-in webserver in conjunction with Growl.)growl.py -r my.site
then, in a new terminal window:
cd my.site/_deploy/
python -m SimpleHTTPServer
and point your browser to 0.0.0.0:8000.
input data
growl will ignore all files and directories which starts with
a .
or a _
. (this can be changed via Site.IGNORE
, see
extending growl)
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.html
atom.xml_
->atom.xml
somefile.txt.markdown
->somefile.txt
some directories beginning with an _
are special to growl:
_deploy/
the default deploy directory_layout/
contains your site layouts_posts/
contains your posts_hooks/
contains all your hooks (see extending growl)_libs/
contains third party code (see extending growl)
all pages and posts optionally can have an yaml header. this header must begin and end with a line containing 3 hyphen. e.g.
---
layout: post
title: my post title
category: spam, eggs
---
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.
site
this holds the site wide informations.
-
site.now
current date and time when you run growl. this is a python datetime object.
{{ site.now.year }}-{{site.now.month}}
-
site.posts
a chronological list of all posts.
{% for post in site.posts|reverse|slice(8) %} {{ post.content }} {% endfor %}
-
site.unpublished_posts
a chronological list of all unpublished posts. e.g. all posts which set
publish
to false. -
site.categories
a dictionary mapping category <-> posts.
-
{% for cat in site.categories %}
- {{ cat }}
-
{% for post in site.categories.get(cat) %}
- {{ post.title }} - {{ post.date }} {% endfor %}
{% endfor %}
- {{ cat }}
page
-
page.url
the relative url to the page.
-
page.transformed
the transformed content. no layouts are applied here.
post
-
post.date
a datetime object with the publish date of the post
-
post.url
the relative url to the post
-
post.publish
if set to false, the post will be generated, but is not in the list of
site.posts
. instead it's in thesite.unpublished_posts
list.if
publish
is not set, growl will assume this as true and the post will be normally published. -
post.content
the transformed content. exactly the layout specified in the yaml header is applied. (no recursive applying)
-
post.transformed
the transformed content. no layouts are applied here.
extending growl
growl 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 ends with .py
, are executed
directly in the global scope of the growl.py file. thus a hook can freely
shape growls code at will. growl loves that! ;)
here are some examples of what can be done. but you sure can imagine other cool things.
configuring template engines
register new transformers
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.
change which files will be ignored
growl 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
growl ignore all files begining with .
, _
and foo
.
Site.IGNORE += ('foo',)
define global template context content
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!
add some verbosity
as an example, we would display the currently processed post, while growl chomp 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)
growl 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
).
bug reporting
please report bugs here.