1 files changed, 39 insertions, 0 deletions

diff --git a/blog/2015/write-the-flogging-manual.rst b/blog/2015/write-the-flogging-manual.rst
new file mode 100644
index 0000000..278eb9f
--- /dev/null
+++ b/blog/2015/write-the-flogging-manual.rst
@@ -0,0 +1,39 @@
+.. date: 2015/03/15 18:00
+.. title: Write the flogging manual
+
+More than thirteen years ago I set up my personal website. Proudly aligning everything with tables, hand writing HTML with :del:`pico` 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 <http://blogofile.com>`_ or `pelican <http://blog.getpelican.com>`_ 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 <http://github.com/tomster/lumberjack>`_ to accomplish that. However, after writing enough code to scratch his own itches, he left the code for good ;)
+
+scratching MY itch
+==================
+
+Enter `nikola <http://getnikola.com>`_. After a good soul implemented `custom post lists <http://getnikola.com/handbook.html#post-list>`_, I finally could describe what I imagined my site should look like in a markup language and not in code (although `restructured text <http://getnikola.com/quickstart.html>`_ is not the simplest markup language). It would support `bootstrap <http://getbootstrap.com/>`_ and `bootswatch <https://bootswatch.com>`_ 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 <http://getnikola.com/creating-a-site-not-a-blog-with-nikola.html>`_ for that. From there I installed the `cosmo bootswatch skin <https://bootswatch.com/cosmo/>`_ for its free and elegant font `Source Sans Pro <http://en.wikipedia.org/wiki/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.