Texinfo is the official documentation format of the GNU project. It is used by many non-GNU projects as well.
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.).
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.
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”.
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.
Obviously, it creates web output from Texinfo files, using
texi2any, but there’s more going on.
The Makefile defines all targets and uses m4, awk,
and a couple of other standard tools to create the site.
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
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.
It’s also m4 that creates Atom XML and RSS XML files, which
are then included in the generated files.
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.
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.
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.