Helpful Information:  Using Hugo for This Site

Hey there!

Our resident nerd, who shall remain nameless…  made this site using the Hugo framework.
Earlier this morning they had this to say about the experience:

Hugo is what’s known as a framework, which come in various forms and assist in building a website.  For this site we had a basic pre-existing design written in plain html/css and the brief was to take away the tedious task of manually editing code for each post and be able to make quick simple changes across the site.  You can think of it as a simplified version of wordpress, the main difference being that the site is assembled on your computer as a fixed chunk of code, which can be edited in the traditional way and just directly uploaded to the root html directory of your hosting service - no apps necessary.
Hugo is a good choice for this as it is designed for what’s known as ‘static’ sites - no nothing to do with making your hair stand on end - this just means the content doesn’t update in response to user input, like say an e-commerce site that displays products and allows logins etc.  Using Hugo we would be able to convert the existing code to a template and the posts could be then written in markdown which is a simple format using hash marks to denote headings, ‘>’ for quotes, the ‘|’ symbol to create tables etc.  This vastly streamlines the process of writing and publishing posts.  It’s also easy to tag or categorise posts, add images and group posts together in a list as on the Magazine front page .

The typical approach to using this framework is to download a ‘theme’ which is a pre-made template where all the hard work is done for you.  If you find a theme that suits your purposes then go ahead, this is the best way and saves a lot of effort.  However, for this application given the extant code and clear design specification, we needed to create our own template.  This inevitably involved a lot of headscratching and some late nights - but we got there in the end!  In general Hugo is fairly straightforward and quite - as the SV types would say - “auto-magical”; but there can be some quite frustrating moments that require either a deep-dive into the code or a quick cobbled together hack at least.  We’ll leave you to guess which one we recommend and which we tended to embrace…

One particular moment was an annoying phenomenon whereby the list of posts mentioned above - instead of providing a link through to each post itself- would redirect to …a list of the posts.  Our solution was to alter the ‘context’ of the code segment (a word you’ll see coming up a lot in this, ahem, context) by adding {{ range .Section }} directly preceeding the list code.  This is not a ‘correct’ solution as it effectively creates a nested list of posts within a list of sections, which given that we had only one section is OK …for now.

Other gotchas include setting hugo server -D -disableFastRender options (this is the command you type from the commandline to preview the site locally.) Related to this - refreshing or emptying your browser cache - is sometimes necessary before some changes, especially to stylesheets will appear. All interactions with Hugo are via the command line interface or CLI, which is a fancy way of saying you type commands in a terminal program instead of clicking on buttons and menus etc. in a graphical user interface which is more typical. The CLI is considered by some to be more efficient and quicker, and we had no complaints due to familiarity with open source unix-like operating systems. The original CLI was a teletype - a kind of electro-mechanical typewriter which operated like a kind of primitive fax-machine (remember those?) to relay commands to and from the computer which was usually the size of two large filing cabinets!

One hack we found which we would tentatively class in the ‘almost elegant’ category was a way to format return links.  The brief was that links back to the main page would return to the same place on the list as you were before, to save scrolling back again.  While there are other more ‘proper’ ways to do this, we found that formatting the id of the index post link as the hyphenated date of the post, and the href of the return link likewise, gave us the result needed without too much websearching and blank stares.  The basic code is id="{{ .PublishDate.Format "04-03-2-1-2006" }}" and href="/index.html#{{ .PublishDate.Format "04-03-2-1-2006" }}".  The date in the code is the way golang (more on this below) lets you format dates by re-arranging their prespecified date in the way you want it presented.  This is detailed in the documentation’s familiar brusque manner .

Hugo is written in Go, or more searchably, golang. The language is comparitively new to the scene and is the brainchild of the legendary Ken Thompson along with Rob Pike, Robert Griesemer, and many other valuable contributions by various open-source participants. The former two characters being behind the now ubiquitous UTF-8 encoding that delivers the text of this website and indeed most of the world wide web today. Ken Thompson himself was a crucial force within the bell labs creation of Unix, an ancient operating system whose legacy surprisingly enough infuses many of todays core software - Linux, MacOS, Android, FreeBSD to name a few.  But here at Magazine, we insist that scenious - not genius - is the true phenomenon to be in awe of - á la Eno.

We are well aware that this ‘newbie’ style of programmming is nothing to be proud of, we are simply sharing our experience to help those who similarly favour an ad-hoc half-in-half-out approach!

∞  Last edit/update on: 22 / 3 / 2023