Write the flogging manual
More than thirteen years ago I set up my personal website. Proudly aligning everything with tables, hand writing HTML with .. raw:: html <del><code>pico</code></del>
vi, using "clever" apache server side includes to inherit styles from parent directories and making everything so artsy bordering unreadability. And while in the beginning writing in HTML seemed fun, in the end it became so tedious, that updating the blog came to a grinding halt (we're all not getting younger).
So in order to be able to publish again, I needed something more seasonable, with a responsive theme and simple enough to last another thirteen years. But my site accumulated so much cruft others depended on, replacing the apache alone with something more modern seemed unfeasible. Yet, my rather static content would best be served as static files by a simple web server – using an insecure scripting language on top of a complex database setup was completely out of the question. I once went through the pain of setting up and maintaining a wordpress site for my dad, there's no need to repeat that agony for something I'd like to use on a daily basis.
But all the projects out there that would allow me to generate a static site from a simple markup language, like blogofile or pelican too narrowly focussed on the use case they were born from – to generate a somewhat dynamic blog, with an optional static about page – this was not how I imagined my content to be assembled together. I wanted something richer, teasers for my blog posts on my front page, lists of all projects and songs, without the need to write my own code to do that. So – I made tomster write some code to accomplish that. However, after writing enough code to scratch his own itches, he left the code for good ;)
scratching MY itch
Enter nikola. After a good soul implemented custom post lists, I finally could describe what I imagined my site should look like in a markup language and not in code (although restructured text is not the simplest markup language). It would support bootstrap and bootswatch out of the box, solving all my skinning needs.
I will not go into much details on how to get a nikola site running, there is an excellent nikola static page primer for that. From there I installed the cosmo bootswatch skin for its free and elegant font Source Sans Pro and its simple yet modern look. nikola bootswatch_theme cosmo and I'm done.
After creating some pages and posts and giving them tags, a simple rst statement in my index.rst would be enough to list all those posts and render them via my custom template (although the default template will suffice for he sake of experiments):
.. post-list:: :all: :tags: project :template: list_projects.tmpl :id: projects :sort: prio :reverse:
Note, that the sort parameter was only added in version 7.3.4. In the process of making the pages look good it took some tricks to use the full power of bootstrap. One is to add custom classes to whole sections inline in rst:
.. class:: col-md-6 pull-left Software projects =================
The other is to skin the hell out of the default bootswatch theme using my own css themes/erdgeist/assets/css/erdgeist.css and adding it to the bundles file inside the theme.
short comings
However, even nikola is not perfect. It uses a dependency system to figure out what to rebuild when content has changed. It will however not know in which order to render pages, so that includes like the blog post previews may be missing when the front page to show them is rendered. A work around is to set the date (in the meta fields) of any page that aggregates posts with the post-list directive to something very ancient, as the site is rendered in reverse timeline order, so the then newer posts will be there when you need them.