nblock's ~

About using the static blogging engine rstblog

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.

Further information

This cheat sheet might be interesting if you need some hints for writing content in reStructuredText.

This might also help you to setup your own rstblog site.


permalink | tweet this

tagged archlinux, aur, python and rstblog