Molk.ch-build Project

These are the scripts I use to build molk.ch.

Source Repository

The source repository is here: molk.ch-build repository.

Custom build for molk.ch

There is a huge selection of tools out there for easily generating web sites. Particularly this kind of mainly static site, with a blog or two thrown in. So why go through the trouble of rolling my own?

Writing my own site build gives me absolute control over the generated files. I am allergic to bad generated code ("bad generated code" is usually redundant). If you don't know what I'm on about, open a simple document in your favourite word processor and save it as HTML. Open the result in a text editor - ouch! All that markup, just to say hello?! Most people are happy, or oblivious, or both, with a lesser degree of control over their sites. That's great, but not for me. The design decisions made possible (or at least easier) by writing my own build are detailed in About molk.ch.

Originally, I wanted the build to be generic, useful out-of-the-box for generating other sites.

In practice, this turned out to be 1) too much extra work, and 2) too restrictive - I don't want to limit myself to implementing only features that everybody would want.

Making the build do exactly what is needed for molk.ch has very concrete advantages, and while I doubt that anybody would want to reuse the build as-is, I think some of the code might be as interesting to read as it was to write.

Objectives

Limit repetition to an absolute minimum

Adding a new page to the site should require as little copy-pasting as at all possible. The source pages contain only the actual content, all the repetitive stuff (header, navigation, layout, etc.) is added by the build.

Automate and validate as much as possible

As well as ensuring conformance to various standards (XHTML, CSS, ATOM, etc.), formatting, minimisation, and custom checks (see check-html.sh for an example of just how pedantic validation can be!) are done by the build.

Make it easy to follow best practices for web content production

When browsing the web, I get the impression that many site producers assume that visitors have: fast computers with loads of ram, a really fast connection, and a weakness for cute design, fancy graphics and clever animations. The actual content is often buried under reams of irrelevant packaging. I believe that web pages should:

Contain an absolute minimum of non-essential content (e.g. If people visit your site to read about your band, only display your 3-minute introductory animation if people explicitly ask for it?)
Be small! The main page of many sites requires over a megabyte of stuff to load before it will display intelligibly! When people visit your site for the n'th time, and they know where they want to go next, waiting for the page to load, be parsed and displayed (maybe even wait for an animation to get it over with), only so they can click on a simple little link is an insult. Even with a fast connection, why should your site take seconds to display if the essentials can be available within milliseconds?
Separate style (CSS) and interactivity (JavaScript) from content (HTML)! This is very simple to do if done from inception, yet only a fraction of sites bother. New categories of devices connect to the internet all the time - nothing stops your site from being available on all these devices! The whole point of an open architecture like the internet/web is that you do not need to know what is going on at the other end!
Degrade gracefully - people browsing without CSS, JavaScript, Flash, etc. should be able to benefit from your site (unless your core content is fundamentally linked to one of those technologies, but most of the time, it isn't). Take it one step further by minimising the site's dependency on: Fonts, Colours, Images, Sounds, and even vision - if your site contains textual information, make it available in plain text!

Hardcode as little molk-specific stuff as possible

Stuff that appears in the final site is either in the sources, or derived from the source files (e.g. atom feeds, page summaries) and directory structure (navigation). Very little actual content is hardcoded in the build - repeated content is taken from src/fragments, navigation information is derived almost entirely from the src/content directory structure.

Learn about new technologies

I am a software developer, and I enjoy learning. I am always looking for nails to whack with intriguing hammers. This build provided concrete problems that I could apply tools I had not yet had the opportunity to work with (sed, awk, rhino, xmlstarlet, csstidy, etc.), as well as learn more about tools I was already reasonably comfortable with (emacs, bash, etc.).

Documentation

The individual scripts and files of the build are self-documenting - hopefully, the code speaks for itself. I have included inline comments when I figured something would not be immediately obvious.

I wrote an Architecture Overview, to give an idea about how the whole thing is structured, and to provide points of entry. Alternatively, you could just dive into the source root.

Licence and copying permission

It is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

See also the molk.ch Licence page. Kudos to the GNU Project and the Free Software Foundation for doing the heavy lifting, legalese-wise.