About using the static blogging engine rstblog
written on Wednesday, August 31, 2011
Hi, and welcome on my site. First off, I want to tell you something about the static blogging engine I use. It's called rstblog and it has been written by Armin Ronacher. I discovered this fine piece of software when I stumbled over Armins's blog entry Python and the Principle of Least Astonishment.
These are my key points for choosing rstblog:
- Free software (BSD)
- Simple
- Produces static output
- Written in Python
- Write blog entries with vim
- Manage blog entries with git
- Does the trick for me
Installation
You can either checkout and build rstblog from source or use my PKGBUILD file in case you are an Arch Linux user.
Getting started
rstblog requires a certain directory structure to produce your blog. Here is the layout of example.org, a simple blog:
example.org
├── 2011
│ ├── 08
│ │ └── 31
│ │ └── 1st-blogpost.rst
│ └── 09
│ └── 15
│ ├── nice.rst
│ └── story.rst
├── about.rst
├── config.yml
└── _templates
└── layout.html
To get started, just download the example above.
First off, adjust the config file (config.yml) to suit your needs.
--- active_modules: [pygments, tags, blog, latex] author: your name canonical_url: http://example.org modules: pygments: style: friendly
The special folder _templates contains the Jinja2 template(s) that rstblog uses to create your blog. Just create the file layout.html, which is the most important building block for producing your blog.
<!doctype html> <html> <head> <meta charset=utf-8> <title>{% block title %}{% endblock %}</title> <link href="/feed.atom" rel="alternate" title="Feed" type="application/atom+xml"> </head> <body> <ul> <li><a href="/">home</a></li> <li><a href="/archive/">archive</a></li> <li><a href="/tags/">tags</a></li> </ul> {% block body %}{% endblock %} </body> </html>
Blog entries
rstblog distinguishes (sort of) between two different blog entries:
- Regular blog entries
- Static blog entries
Regular blog entries
Regular blog entries should be put in a directory structure that looks like this: year/month/day. Create such a structure and put your first blog entry (my-first-blog-entry.rst) in there.
public: yes tags: [rstblog, firsttry] summary: This is my first blog entry My first blog entry =================== Hello World!
Static blog entries
rstblog also allows you to create static blog entries such as an about page. Simply put a rst formatted file in the root directory of your blog.
public: yes About me ======== This is me.
Building the blog
Finally, build and view the result:
$ run-rstblog build $ run-rstblog serve Serving on http://127.0.0.1:5000/
Now point your browser to http://127.0.0.1:5000 to view the results of your work. The about entry should work as well: http://127.0.0.1:5000/about.
Additional stuff
Static content
Static content (css files, js files, …) should be placed in the directory static. During the build process the content of this folder will be copied to the directory _build/static. You can easily link to them from your blog entries using `target </static/target>`_.
Design
Your layout.html file contains Jinja2 templating code. What's missing is a css file that nicely formats your content. Just create one and put it into the directory static. Don't forget to link to it in your layout.html!
Tagging
Tagging is a nice feature that helps classifying blog entries. The first blog entry (Regular blog entries) already uses two tags, rstblog and firsttry. These tags will be used to create a tag overview page, viewable at http://127.0.0.1:5000/tags. Use as many tags as you like to classify your content.
Customize blog generation
In the default setting rstblog will build archive and tag pages for you. This is of course also template based. If you wish to modify some of the templates, copy the affected files from rstblog/rstblog/templates to your _templates folder and adjust them accordingly.
Publish your blog
This is really simple. Just copy your _build folder to your public html folder and you are done.