Website update!


1. Well, the more it changes, the more it stays the same!

I have migrated my website from the antora SSG to Hugo. These two technologies are both SSG’s ( Static site generators) Otherwise the excellent 'Antora' was mostly to experiment with its functionality.

Antora is the very best solution for managing documentation. I did also fully realize that this was not the best solution to force on a blog. But really its only weak point at this time is the lack of multilingual functionality as much for sites as the documentation itself.

I am convinced however that its authors will remediate that as we do live in a multilingual world!

Ok, that said, in turning (back) to Hugo, I had three objectives:

  • Multilingual support

  • Use a CSS framework

  • Host documents in Asciidoctor format

As for creating a multilingual site with a static site generator, in my opinion there is nothing better out there than hugo. Without going into all the details, it si the fastest around, has great documentation and most importantly supports multiple languages exceptionally well.

As for this second point, the CSS framework, I chose Bulma. I did do a lot of research and have previously had some experience with Bootstrap, and I could have chosen among a few contenders. (This subject deserves a post in itself…​.)

Bulma is not too 'fat', is based on flexbox, and has no java (a plus), as well as a large following. Note however that I do have an opinionated viewpoint on CSS frameworks. In my new site for post lists, I used my own grid elements instead of the flexbox solution provided by Bulma. In my opinion, with the caveat that web development is not my trade, that for someone going into that, it is better to do your own site scaffolding with simple grid/flexbox and then use a css framwork for the buttons, tags, and other elements.

This way the end result with be at least a bit more portable.

But what is more important is the knowledge acquired will also be much more portable and can be used everywhere.

My site uses exclusively documents in asciidoc format.

This is a format that allows easy conversion to docbook (its raison d’être), html, pdf and creates beautiful destination documents. The integration of Asciidoctor (the tool) and Hugo is not yet well supported. Hugo must call Asciidoctor as an external tool to convert the docs to web pages. Paranoically, the Go programming language in which HuGO is written supports this natively. We can only hop that Hugo will gain some more functionality with this in the future.

One other challenge here that merits a whole post is we are forcing a combination of CSS from Bulma and Asciidoctor. For now, I have only had to make a few manual adjustments to my css to correct some personality differences between Bulma and Asciidoctor. I have not doubt that some more issues will appear. However it is at least possible for the most part to let Bulma take care of the style of the butttons, cards, and website elements, and then apply the asciidoctor css only to the posts and articles. I am happy with the results for now.

So there you go! There will some adjustments to be made and bugs to work out.

But soon I will submit a theme template to Hugo!