Texiblog

Texinfo is the official documentation format of the GNU project. It is used by many non-GNU projects as well.

GNU Texinfo manual

texiblog is my home-grown solution for building a static site, and is what is behind my personal website. It uses texi2any to create the HTML from Texinfo files, adds some styling options, creates updated menus from the posts (to provide an easy way to check recent articles), and uses m4 throughout as a pre-processor and as a way to create the Atom and RSS XML files, as well as other niceties.

The code is available at the texiblog Notabug repository.

In the next sections I will go a bit more in-depth about it, but the short version is that using Texinfo produces a content-focused website, with minimal distractions, easily viewable through any browser, and makes it natural to maintain a structure that is predictable, easy to use, and maps well into other formats, such as a PDF, or a standalone .info file.

There’s some traction on “Brutalism in web design”, and if taken in one of its forms – the one that focus on showing content with minimal distractions, as described in David Copeland’s “Guidelines for Brutalist Web Design”, a good description of this approach – this approach closely follows it, but not because of an explicit desire to do so, but because those are the results of using the Texinfo toolchain (See Creating a web page and blog, the Texinfo way.).

Why Texinfo for a personal site.

There are a lot of “markdown” flavours out there, and I have previously (and currently) used AsciiDoc and Markdown.

I am far from the first one using this approach: using TeX for websites was reasonably common, and one will find examples as this “Worse is Better” copy on Jamie Zawinki’s site, which were initially created with latex2html.

Texinfo is simpler than LaTeX, and its usage as the documentation format for the GNU project makes it come with some really good features for a static web site, especially when the goal is to keep focus on the content.

Stargrave’s example

When I started to think about this idea I went searching for existing examples, and I found Sergey Matveev’s homepage, which is not only created using Texinfo (texi2html, most likely), he does an in-depth comparison of formats and why he chose Texinfo. The entire site had exactly the “feel” I was after: good indexing, simple navigation that is easy to use, and a degree of familiarity that comes from reading a lot of GNU documentation (in info or converted to HTML), which I find “clean”.

Technomancy and m4

Texinfo already comes with texi2any, the current replacement of texi2HTML, so much of the heavy-lifting is already done for us. I needed some extra features, and for that Phil Hagelberg – aka technomancy provided additional inspiration: his entire website is made through a Makefile and m4 – which some of you will remember as the language used for the configuration of Sendmail, at least those that didn’t directly edited the generated file – which it’s awesome in itself, but also made me investigate how could I leverage parts of it for my solution.

Chrisman Brown does a good description of the m4 approach used there, and it made be learn a bit more about m4: I initially had a bunch of scripts that worked on templates, and in the end I was left with only the Makefile, with m4 doing the work.

What does it do

Obviously, it creates web output from Texinfo files, using texi2any, but there’s more going on.

Makefile

The Makefile defines all targets and uses m4, awk, and a couple of other standard tools to create the site.

M4 configuration files

The main configuration is done with m4, which is used to generate any Texinfo file that needs processing, as well as defining the main configuration variables (e.g., website title).

$ ls -1 src/*.m4
src/atom.m4
src/config.m4
src/config.texi.m4
src/feed.m4
src/posts.m4
src/rss.m4
CSS

There’s a case for not adding anything to the output: the result is indeed ready to use. I have opted for some tweaks, especially in terms of maximum width to keep the text more readable, as well as some slight changes to how the page works on different screen sizes.

Atom and RSS feeds

It’s also m4 that creates Atom XML and RSS XML files, which are then included in the generated files.

Post descriptions and dates

texi2any has a nifty feature that does without the need to manually create Texinfo menus by hand: when exporting to HTML, it creates a table of contents for any sections “under” the Top node.

This would work great, except for two things: using a menu allows me to add a description to the entry, which in the case of posts (i.e. the “blog” aspect of this) can be used to indicate the date. Additionally, it’s useful to have control on what gets shown in some sections, especially at the very start of the page where I want to give quick links to the most important sections.

The downside of this is that automatically generated menus do not have a description, so m4 (again) goes through all files under src/posts/ and creates a menu using the @date field.

Texinfo macros

Some macros are added to either simplify some things, or make other possible: the @date macro is important to make the previously described menu automation work, while others such as @imagec simplify adding a float, with an image and a caption.

Post-processing

This is a bit open-ended, but currently includes changing the navigation bar to always include a link to the home page (that’s the [Top] link that appears last, and which isn’t a part of the default navbar).

More than 90% of the approach is simply based on writing Texinfo files.


This document was generated on December 29, 2023 using texi2any.