TheBlackzone Logo

How TheBlackzone is maintained

Over the years I have changed the ways to maintain the content of my websites numerous times. The current version is created with the help of the GNU m4 macro processor, which is a quite unusual - some people would even call it "esoteric" - way to create a website. Reasons enough to give you a brief insight on how I do it.

A bit of history

In the History Of TheBlackzone I already mentioned a couple of tools I used in the past, but here is a more complete list in chronological order:

When it became clear that the Habari weblog system was no longer developed and it would be just a matter of time until the next PHP upgrade will cause it to break, I started looking for something new. I didn't want to bother with another blogging system and was looking into creating static HTML pages instead. But I didn't want to edit them as pure HTML code like I did 20 years ago.

So, the first option I was looking at were some of the plenty so-called static site generators. These tools take some form of textual input (mainly Markdown texts) and convert them to static HTML pages. But after having tried a couple of them, it became clear that they were not my cup of tea and I decided to go another way.

At first I created a couple of scripts that took Markdown files and converted them to HTML pages with the help of Pandoc. This was pretty much the same thing the static site generators did, but in a leaner way and with more fine-grained control. It worked great and did exactly what I wanted. However, after a while I found my self putting more and more native HTML code into the Markdown source files because I reached the limits of Markdown's formatting capabilities. And while Pandoc easily handles that kind of mixture between HTML and Markdown, I didn't like the "mess"...

Nowadays

My current solution based on m4 macro processing is a different approach. Instead of creating a source file in some format (Markdown) and convert it to HTML, it uses HTML pages that contain macros, which are expanded to HTML code by the macro processor.

This works much like a templating system and to give you an idea of it, here is the (simplified) m4 "template" of this page (without the text):

_HEADER_

<h1>_TITLE_</h1>

<p>Here is some text in HTML format.</p>

_FOOTER_

"_HEADER_", "_FOOTER_" and "_TITLE_" in this example are the macros, that will be expanded to full HTML code based on the macro definition. "_HEADER_", for example, includes the HTML header code, containing everything until the page content text starts. "_FOOTER_" expands to the HTML page footer code that closes the page, while "_TITLE_" just contains the page title. The macros themselves are created in external files and just referenced when executing the macro processor.

Basically all that the m4 macro processor does, is just to replace a text with a defined replacement. In practice this simple mechanism is quite powerful. m4 works recursively, so a macro definition can contain other macros. It is also programmable and can execute external commands. The introductory text of the m4 manual sums up its capabilities quite well:

m4 is a macro processor, in the sense that it copies its input to the output, expanding macros as it goes. Macros are either builtin or user-defined, and can take any number of arguments. Besides just doing macro expansion, m4 has builtin functions for including named files, running shell commands, doing integer arithmetic, manipulating text in various ways, performing recursion, etc.… m4 can be used either as a front-end to a compiler, or as a macro processor in its own right.

While m4 is doing the work of creating the HTML pages, there are also two suplimentary scripts written in BASH (and the usual set of Unix tools, like grep, awk, sed, find, etc.). These scripts are used for creating the content of the front page ("Latest Posts") and the navigation page. Basically they read through the m4 files, extract some metadata from it and build an excerpt of the posts for the front page and a list of pages and posts for the navigation page. All the functionality is brought together in a Makefile.

Conclusion

I am quite satisfied with my current system and it works pretty well. It can also be easily adjusted by changing the macro definitions or tweaking the scripts.

The funny part is, m4 has been sitting right under my nose for many years. It has been with Unix and Linux since decades and is heavily used by the GNU autoconf tools, which I regularly use. But the enlightenment to use it for the creation of my website came fairly late.

Also, my investment in learning the m4 macro processor has paid off because I can use it on other occasions as well (software development, system administration and text processing).

Related resources:

Back to About