Hello Web!

Hello web!, I feel that this is the appropriate first post/thing to write. At this moment I have yet to host this blog anywhere other than locally, and many other things about it are sure to change before I publish it, but still no place like the present to start.

Now that the preamble is out of the way, time to talk about why and how I made this blog. The why is quite simple, I have often searched for a specific bit of information, spent many, many, many hours to find it and understand it, only to forget about it at some later point. This wouldn’t be a problem if I never again needed that knowledge, but, as it happens, I often do need to recall it. At the same time I’m thinking some other poor sod might be in their searching period, so might as well try and help them as well.

Now for the how. This is a bit more complex, but I’ll do my best to keep it nice, short, and to the point. I had 4 main requirements for functionality:

1. I wanted to be able to write my posts in as simple syntax as possible, while still retaining the power of raw html, and due to my already existing experience with markdown, that’s what I went for. Now I needed to find something to translate my .md files into .html ones.

2. I also wanted to ship as little JS and CSS as possible while still having a reasonably good UX for the site. One non-negotiable was that I wanted the blog to have a light and dark mode, as well as properly react to the user’s preferences on this matter (this is a pet peeve of mine).

3. I wanted to be able to write maths in $$inline-maths\LaTeX$$ notation and have it rendered in an appropriate way.

4. I wanted to have as fewer dependencies as possible. If feasible I wanted to develop this myself so I could be certain that I will have access to it in the next 5, 10, maybe even 40 years.

After looking around I went with hugo. It checked almost all the boxes, except for the dependency one, but the power to template your pages and in the end still ship a static site, was the deciding factor. Another bonus was the community and resources behind it, Luke Smith has some good intro videos on this topic, which I took ample advantage of.

After making the aforementioned choice, I got nerd sniped. Hugo requires that you have a theme selected, without it, it will not display anything. So naturally, now I had to choose a theme for this blog. Luckily they have a page dedicated to this. Here are some themes that I considered and used as inspiration: m10c, Hugo - Classic, Terminal, xterm. The majority of them shipped too much JS and CSS for my liking. So I “just had” to make my own. This kickstarted another project that would take about 2 months (I forgot when I started working on this) or more of on-again, off-again work. PostZ FS is the result of this, a minimal theme that I keep updating whenever I encounter a new issue with my posts. At the moment this theme ships about 120 lines of JS, and around 625 lines of CSS in total, not counting the imports that make katex work. The JS code could be simplified by moving away from OOP.

One neat thing about this theme is that it can use only one $ to denote an inline math block (e.g. $\LaTeX$ => $$inline-maths\LaTeX$$). The trick to do this is to change the delimiters that katex uses to determine if it’s an inline block or block, and also do some pre-processing on the page to be rendered.

• hugo.toml : This is the configuration file for hugo

 1[markup.goldmark.extensions.passthrough]
 2# allow passthrough step needed for latex maths rendering
 3# allows the use of "layouts/_default/_markup/render-passthrough.html" to pre-process
 4enable = true
 5
 6[markup.goldmark.extensions.passthrough.delimiters]
 7# delimiters for the passthrough
 8# tells the pre-process step what kind of block it deals with
 9block = [['$$', '$$']]
10inline = [['$', '$']]

• partials/head/katex.html : Partial that gets added to pages to render inline maths

 1<!-- Call "katex" to render math -->
 2<script>
 3  document.addEventListener("DOMContentLoaded", function() {
 4    renderMathInElement(document.body, {
 5      delimiters: [
 6        {left: '$$block-maths', right: '$$', display: true},     // block
 7        {left: '$$inline-maths', right: '$$', display: false},  // inline
 8      ],
 9      throwOnError : false,
10      output: "html",
11    });
12  });
13</script>

• layouts/_default/_markup/render-passthrough.html : Hugo template for callback from goldmark for passthrough

 1<!-- This is where pre-process happens and allows for the use of  -->
 2<!-- just one "$" symbol for inline maths  -->
 3{{ if eq .Type "block" }}
 4<!-- If block process as block -->
 5<div class="block-maths-container">
 6  $$block-maths{{.Inner}}$$
 7</div>
 8{{- else -}}
 9<!-- If inline keep spaces in the math code -->
10<span class="inline-maths-container">
11  {{- range $index, $element := (split .Inner " ") -}}
12    {{- if gt $index 0 -}}
13      &#32;
14    {{- end -}}
15    $$inline-maths{{ $element }}$$
16  {{- end -}}
17</span>
18{{- end -}}