Dec 22, 2022

Restarting my personal website

I once had a blog… with only a few articles on it. The last one dates from 2017. Not sure what caused me to abandon my blog back then. I do think it is time to revive it.

Adding to that, I’m not naming it a blog anymore but a personal website. Besides some blog-worthy articles, I feel the need to start writing about much more. Here we go!

Coming from Hugo as my static site generator, I felt some limitations in authoring content in Markdown. The theming is quite good, but rigid to a certain extent as well. The last few months were filled with yak-shaving over my ultimate static website setup. A few different setups passed my keyboard and screen and while I learned a lot, I didn’t come to a conclusion. Thinking about it, it struck me I hadn’t really defined any evaluation criteria.

Git Driven

One of the system tested for my website was Sanity. I can see this content system offering the power needed to support big corporations, but the amount of work needed to support the content types I needed was way too much to go fast.

Another option was CMS systems like Wordpress and Drupal. It seems I forgot way I once got away from these: my content was in a database and… plugin/extension hell! Brrrr…

What I eventually kept from my Hugo setup was that I wanted my content in source control. Git would be it and that allowed me to eliminate a whole category of tools!

Content Type

Earlier in this article, I hinted at limitations in authoring content in Markdown. Yes, Markdown is a simple format which is easy to learn, but when the Markdown format doesn’t offer you any markup for a specific need, you are out of luck. Markdown doesn’t have a standard way to extend it. Ever did a search on “flavored markdown”?

Why do you think so many people made their own flavor of Markdown? Lack of extensibility! That started my evaluation of alternative content formats to Markdown:

reStructuredText
BBCode
AsciiDoc
Wikitext

I’m not going to bore you with the whole evaluation of these tools beyond mentioning I settled on AsciiDoc. The syntax is close enough to Markdown to transition fast in using it. But the main selling feature to me is Substitutions. A number of the default syntax features are extensible due to this. For instance, the syntax for a xref (cross-reference) is like this:

xref:link-macro-attributes[use attributes within the link macro]

xref is actually a standard macro in AsciiDoc that has additional configuration which can be passed after the colon and in between the square brackets. Most AsciiDoc processing tools allow for content processors to be plugged in and I already made use of this to link my Github Gists:

gist::ringods/168c2cf7726a536deb9c[file=push-to-server.sh]

I configured my processing tools with a handler for the gist macro. Done! The second best-selling feature is document to document cross references. In your content, you have a standard way to create references from one source document to another, meaning you don’t have to know what the generated URL will be for any of your documents. Your tools will create these source references to the proper content URLs.

Full Control over Styling

When I read about the extensibility of AsciiDoc by way of these substitutions, I did want full control over the generated HTML & styling for my custom macros. That was not hard to get right in the AsciiDoc tools ecosystem: with an extensible markup language, the extensibility of the tools was a given!

When generating HTML from your content, the AsciiDoc tools have a standard HTML generator, but you can override which HTML is generated for every of the AsciiDoc syntax elements the reference provides. Now that is cumbersome: I still would like to create a theme and map templates to pages.

Antora!

Searching deeper into the AsciiDoc tool ecosystem, I stumbled onto Antora. Antora classifies itself as a multi-repository documentation site generator, which clearly is not what I wanted to do. I clicked the Docs link and started reading. Hours passed and the number of features which just clicked for me, grew:

content can be spread over multiple git repos
concepts like sites, components & component versions allow for easy (and possibly multi-version) structuring
site UI (aka theme) support

This is only a small selection of what I could envision using in the future. What made me decide to settle with Antora are extensions, a feature introduced in v3.

Different from the lower level rendering extensions talked about earlier on, Antora extensions allow to hook into the whole lifecycle model of collecting content, classifying it, creating a navigation structure for it, before all of this is generated as a static site. How much more control does someone wants or needs?

First results

With everything decided, I didn’t want to wait to long to revive my site. This is the first new article on an MVP of the revived site. I’ll write more about this setup in subsequent articles, now that will only happen after some upcoming holidays. Along the road, I will also extend my site with new page styles, new integrations and website sections. Stay tuned! If you are curious about the sources of this site, as well as the site UI, go and have a look!

Merry Christmas & Happy New Year!