Blog internals (or learning new things to fix stuff)

As I am not a web programmer, I tried to get an idea of what is required to self-host the Google fonts and the Fontawesome icon set. Searching the web quickly yielded some articles for the Google fonts problem and Fontawesome has pretty good documentation itself on how to self-host. So the next step would be to integrate this into the zen theme that I use and see how much of this can and should be contributed back to the Nikola project.

Unfortunately until now I used Nikola as a black box that (mostly) did what I expected of it, but to solve this issue I obviously needed to learn more about the inner workings of it. With my specific changes in mind I decided to concentrate my learning on the theming aspect of Nikola, i.e. on the help documents Creating a Theme and Theming Nikola. This entailed reading up on other topics related to web development as well. Studying Cascading Style Sheets, for example, I realized that "basic CSS" seems to be so uncomfortable that people came up with higher level languages compiling into CSS, like sass or less. The zen theme has this to say in its README.md file:

WARNING: The themes use Less for their styles, but you don't need a Less compiler installed to use it.

So we should keep in mind that theme.css is the output of a compiler with the source files located in the less/ directory.

Nikola comes with 6 themes contained in the Nikola repository itself:

• base, base-jinja
• bootblog4, bootblog4-jinja
• bootstrap4, bootstrap4-jinja

Apart from those, there are also quite a lot of community themes. Looking at the themes gallery, it is not obvious at all, which of the themes are "first level" themes living next to the code itself and which live in their own nikola-themes GitHub repository. Once you decide to use a Nikola theme, you will install a copy of it into the directory you build your blog from and thus loose the connection to improvements in the upstream repository. Unless you check yourself from time to time if something happened there, you will not be able to leverage any subsequent changes or fixes in the upstream theme. If you do find there were changes, there is no easy way to upgrade your theme then to remove your old one, install the new one and see if things still work as you expect.

As I was sure my problem is also relevant for a lot of Nikola users, I explicitly set out to fix things in the proper "upstream" repository. It turns out that community Nikola themes have their own and community Nikola plugins (see below) also live in their own plugins GitHub repo.

As we learned, the theme used in the blog is a copy of the upstream theme at the time of theme installation. So before doing anything, I decided that I would need to synchronize the theme used in my blog with its current version in the upstream repository. So I renamed theme/zen to theme/zen-old and re-installed the zen theme according to the manual. Having a clean slate would now allow me to introduce my changes to self-host the fonts.

To be on the safe side, I wiped the whole output/ directory of my blog and recreated the site from scratch. As I was only doing incremental builds over the last years, I was also interested in how long a complete build would take - turns out its around 11 seconds.

Opening the newly recreated blog on my local machine looked okay, but opening the web console of Firefox showed a prominent error:

Uncaught ReferenceError: moment is not defined

As I was expecting to start my changes from a clean state, I was surprised to see this error coming from the upstream code base. So I tried inquiring on the Nikola mailing list what this was all about. Not getting any helpful information, I tried to find the reason for myself. After some poking I found that the implementation of "fancy dates" (turning absolute date and timestamps into something like "10 hours ago") in the base themes was switched in commit f1d480d8 from a solution using moment-with-locales.min.js to a solution using luxon.min.js. So it looks like this change in the core Nikola repository was not propagated to at least some)the zen theme in the community themes repository.

So before even considering the changes required for self-hosting, I decided to fix this bug while still here.

And finally as I learned that the background is of course also replaceable an idea began to form in my mind. Only recently Jamie Zawinski announced the 30th anniversary of XScreenSaver and this reminded me of my time at TU Karlsruhe when I was staring a lot at the graphical gems contained in the XScreenSaver collection. By default, XScreenSaver seems not to be installed in a standard Debian Bookworm installation anymore, but a quick

dzu@krikkit:~$ sudo apt install xscreensaver \
 xscreensaver-data-extra xscreensaver-gl-extra

fixes the situation for me. This allows me to start the GUI for browsing the included screensaver modules:

dzu@krikkit:~$ xscreensaver-demo 

The list is so long that I only looked at a subset from the beginning of the list. But many entries brought back memories from some 25 years ago.

After a while I decided a snapshot from flipflop would be nice to have. Playing around with the parameters I found that the installation in Debian puts all the binaries into /usr/libexec/xscreensaver, so they are not on the regular PATH for any user. XScreenSaver also has a tool called xscreensaver-getimage which is called by some graphical demos to retrieve a screenshot, a random picture or even a snapshot from the webcam. For flipflop the option --texture will make it call out to that program to get a random picture and put it inside a specific window. But calling flipflop --texture from the command line does not have a correct PATH setup and so xscreensaver-getimage cannot be found. This results in a black/dark-grey test pattern to end up being used in the demo hack. Even though it's the result of a user error, I found the irony somehow fitting with my blog as I do write about problems quite a lot.

So after taking a screenshot of flipflip and cropping it to the same x dimension of the original background of the zen theme I had a .png file I wanted to use. Copying it into the assets/images directory in the themes/zen folder in the blog itself will copy it to the output/ directory when building the blog. Searching for the exact place where the old background is specified, I found the file name referenced in assets/css/theme.css. Changing it there is easy, but remember what we found in the beginning of the post, namely that theme.css is a file generated by a less compiler. So the proper place to change the variables is in the source file less/variables.less:

// Resources
//----------
@sidebarBackground: url('../images/blue-mocha-grunge.jpg') @darkBlue;
@primaryBackground: url('../images/cream-dust.png') @white;

While reading up on the Fontawesome icons, I decided to also include a link to my Codeberg space into the navigational bar. Unfortunately, the real Codeberg icon is not in the Fontawesome set, there are a lot of icons there with a relation to git. In the end I decided to go for git-alt.

Writing my blog posts in ReST or in Asciidoc the post Syntax Colors For My Blog already described how pygments is being used to do the actual syntax coloring of the content. For various reasons I switched to the Org mode for Emacs syntax in the meantime for posts and even though most things worked as expected, I could not yet get syntax colors for shell-sessions to work at all. I.e. marking sources with console or shell-session did not result in colorful output. Realizing that the Nikola plugin for Org mode was probably something that I could now make sense of with my broadened understanding of the Nikola ecosystem, I dived right in and sure enough found the problem in less than 5 minutes. The plugin consists mostly of a python function to be called with two filenames, the source and the destination. The bulk of the work is done by Emacs itself. From the command line, it is instructed to evaluate the contents of init.el and finally the ELisp function nikola-html-export contained in this file is called to do the hard work.

This function calls another function org-html-src-block defined here to "translate" the babel names for source blocks to the lexer name that pygments understands. And sure enough this function uses the alist org-pygment-language-alist for this mapping. Simply adding entries for console and shell-session also fixes this problem, so I worked it into a pull request for the Nikola plugins repository.

As this was so easy, adding yet another two entries for diff and udiff was easy, so I also enabled them in my blog. The results are already used in this post showing the diffs while changing the background picture.

The beauty of Free Software is that you are usually able to fix your own problems if you are willing to invest enough to time to learn and understand the context "close" to your specific problem. Even though this appears to be very time-consuming, you will usually learn a lot of things along the way. And you simply have to feel the satisfaction of having fixed a specific problem in a larger code base for yourself. It is worth it!