written on Tuesday, November 30, 2010
First off, fork the project from github by issuing:
git clone git://github.com/mitsuhiko/rstblog.git
Then you need to install the requisite packages. Though there are several ways around this, I've opted to go for a virtual python environment:
virtualenv venv
venv/bin/python setup.py develop
This installs a development version where in all the required packages are installed, plus links to using the just-downloaded source. Now, all you have to do is call venv/bin/run-rstblog.
So, you got the build-tool going; now the blog!
Create a directory; let's call it example.com-blog, and create rudimentary directory layout:
mkdir example.com-blog
mkdir example.com-blog/_templates
And create the following YAML-formatted configuration file in example.com-blog/config.yml:
active_modules:
- blog
- tags
author: "YOUR NAME GOES HERE"
canonical_url: http://example.com
This basically tells the system that you want to enable the blog- and tags-systems. And now, using the _templates folder...
The rstblog is quite picky about having a HTML template to build the blog on. A basic one reads about like this:
<!doctype html>
<html>
<head>
<title>{% block title %}{% endblock %}</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body>
{%block body%}
{%endblock%}
</body>
</html>
The meta header is needed, as rstblog outputs UTF-8 encoded data - and this makes the browser get it right. Everything else should be fairly straightforward HTML and Jinja2 templating.
Put it in example.com-blog/_templates/layout.html, and you're good to go.
The general style is creating folders on the form year/month/day/ and putting the individual blogposts in there, ex: example.com-blog/2010/12/10/title-of-blogpost.rst. The post has to be ReStructuredText:
# All rst files MUST start with a valid YAML document; a comment like this works.
=================
My First Blogpost
=================
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua.
To view the blog, run the built-in test-server:
venv/bin/run-rstblog serve example.com-blog
And point your browser to http://127.0.0.1:5000 and behold your new blog.
To built it permanently, run the following command:
venv/bin/run-rstblog build example.com-blog
And copy the output from example.com-blog/_build to wherever your blog is supposed to be.
At some point, you'll probably want some CSS, JavaScript and what else in there to pep things up. Create a sub-folder called static and put it in there. While I haven't checked things out thoroughly, it does somehow seem rstblog treats such a folder specially.
You will probably want About-pages and such at some point; just put a .rst file pretty much anywhere, and it will be picked up by rstblog.
If you, for example, create a ./about.rst in the root folder of the blog, it will be available at /about/index.html - and if your sever behaves like the majority out there - thusly /about.
You can put various post-specific configuration in the header of each blog-post or page, some general and some specific for the used plugins:
tags:
- tag1
- tag2
summary: This goes on the front page
So, there you have it! A static blog!
There are still a lot of stuff to do; add syntax highlighting, atom-feeds, updating nice CSS and so forth.
I have mainly written this from what I could glean from the source code and, especially from Brett Hoerner's site repository.
Note
Update 17/07/2011
Other nice resources are Matt DeBoard's guide to rstblog and, if you're coming from Tumblr, Guido Kollerie's Converting a Tumblr blog to a rstblog.