Hello World

2023-05-19 – #Frontend

Technical Considerations
- Hugo
- AsciiDocs
Theme
End

This is my own website! And this is the obligatory hello world.

I don’t even know what I will write here. I mostly saw doing it as a technical exercise. In this post I will walk you through my reasoning in setting up the page.

Technical Considerations

Hugo

Using a static side generator for a blog is almost a no-brainer for computer people. The question then becomes which static side generator to use.

The big ones are Jekyll, Gatsby and Hugo as far as I know. Hugo itself gains a lot of popularity generally. Another big plus is that it supports AsciiDocs out of the box…

AsciiDocs

Now normally I would write a blog using Markdown as a markup language. But Markdown is too mainstream for me. But with Markdown there are problems: It has very few features. It is even lacking some basic features everyone would expect like commenting the markup file. The different flavours of Markdown then add their own spin to enhance it and make up for the shortcomings. That situation leads to even more confusion.

So I chose AsciiDocs, partly for the numerous features such as:

Asciidocs has support for these small "warning" and "notes" blocks, that you will always see in technical documentations. The syntax for that is also cool, as it is really just CAUTION: my message. It’s one of those universally accepted feature that Markdown doesn’t have a standard syntax for.

Caution

I still don’t have a good excuse to use these blocks

Look! Now you are reading a sideblock - except if you read this on a phone, then you don’t have the screen real estate for that 😔📱

Asciidocs has a special syntax for sideblocks. With enough CSS it actually also looks like a sideblock but in Hugo you will have to give meaning to the word yourself. This feature allows me to do these super neat side annotations on my own text.
Standardization

Table 1. Table Title
Column 1, Header Row	Column 2, Header Row
Cell in column 1, row 1	Cell in column 2, row 1
Cell in column 1, row 2	Cell in column 2, row 2

Theme

I wrote my own hugo theme for this site. It is meant to be simple and maintainable and still accomondate all needed visuals. By that I mean that all the cool features that AsciiDocs specifices and that are then rendered into HTML should also look solid when they are displayed using the theme.

Currently there are a few major design choices:

Side notes

Reminder: This is a sidenote

The side notes on the left that got introduced earlier are defining a lot of the visuals already. They are inspired by Tufte CSS. In Tufte they are meant to show footnotes which would otherwise be displayed at the very bottom of the page - which is a constraint that doesn’t make much sense on the internet. Now I end up having both: Footnotes and sidenotes. ^[1] I think I will end up using footnotes for serious citation (if I will ever get to do this) and sidenotes for when the text might drift into a different direction that I don’t want to end up in.

The Terms of Content

To visually balance the sidenotes on the left side, I decided to add an optional ToC on the right side. Again, if you are on a phone, you won’t be able to see it due to the small screen.

The only javascript in this whole theme is currently being used for the ToC highlighting of the current section and it is about 20 lines long. It’s still all usable without javascript but I think it gives a nice touch.

Colors

I decided to opt for a light theme as they generally look more professional and clean on the internet. Ideally the site would use the preferred colorscheme through a media query like that:

@media (prefers-color-scheme: dark) {
    //...
}

Important

Add the RSS

End

That’s about it.

1. See? A footnote! 🦶