Making my website using Hugo

This website is generated from Markdown using Hugo and the Congo theme! Here’s how I set it up.¹

Why Hugo? #

• converts from Markdown, my note-taking “language” of choice
• large database of themes and examples
• fairly intuitive, template based
• recommended by a friend :)

Also, everyone says Hugo is fast. As it is the only static site generator² I’ve ever used, I can’t comment on this, but my site has never taken more than a couple of seconds to build. This is great when iterating on designs.

How Hugo? #

Choosing a theme #

I ended up choosing Congo for my theme, for a few reasons.

1. multi-page
2. full of features but still fairly minimalist
3. seemingly well documented through the example site, with accessible code
4. customisable using (some) Tailwind CSS
5. callout boxes! (though they still need some work)
6. table of contents in blog posts

Using a theme #

Congo suggests 3 ways to import the theme. I chose the second, import it as a git submodule.

• updates are easier than naive download (see tutorial in example site)
• easy access to the example site (go to the exampleSite folder and execute hugo server --themesDir ../..)
• no risk of having Hugo delete the cache and having to redownload the theme

[!warning] This means that after cloning this repo, you should run use git clone --recursive, or follow the standard cloning with git submodule update --init themes/congo before building the website!

My previous website used Academic by WowChemy / HugoBlox, but it was too closed off for me. I like the original approach of Hugo with snippets and modularity, while with HugoBlox, anything outside of the box was inaccessible. With Congo, I was able to tweak and modify a lot of things on my own.

The project structure #

I have a private git repo with the source,³ which I work on using hugo server. Once a blog post or modification is finished, I just run hugo which generates the website files in a public folder. This folder is linked to another git repo, which is synced to the website with Github Pages.⁴ I just have to do

git add .
git commit -m "<date of update>"
git push

and we’re all set! The website gets updated almost immediately.

Maybe importing the website as a submodule would also work, and it would make it appear in the online repo nicely, but this way works fine for me.

My customisation of Congo #

• Standard customisation
  • leaves for publications and “about” page
  • storing PDFs of publications in static/<leaf name> (in my case, <leaf name> is work)
  • Enabled the light/dark button and header.layout = hybrid (see the Congo docs)
• Allowed custom alt text for the profile picture to give proper credit to Marie Morin
• Imported some icons from FontAwesome (fixed for dark mode, <path d=...> should be <path fill="currentColor" d=...>)
• Imported a TikZJax script by benrbray
• Modified badge to allow href in it (because button was too clunky)
• Preview on footnote hover (thanks to 1 2), which still needs work
• Added a parameter reverseChronological to avoid chronological order

All these modifications are visible either in assets or layouts.

To-do #

There are many things I’m still not satisfied with at the moment, which I’ll hopefully tackle eventually.

• Blog homepage
  • Flatten subsections to present every post on the list page (users can click on breadcrumbs to get back to a topic summary)
  • Display parent topic if the post is part of a series
• Callout boxes
  • Fix weird offset when it contains a list
  • Make them foldable and give them a potential title (maybe using <details>)
• Footnotes
  • preview/tooltip even on mobile
  • fix position when the footnote is at the edge of the content
  • fit width to content of footnote hover
• “Cite” button for publications, to make the Bibtex appear
• Dark / Light colour theme
  • Post-process TikZ images to fit with the theme (graft the post-process of Obsidian TikZ with the most recent or most visible fork, as motivated by this StackOverflow answer)
  • Different images depending on theme (reading list: 1 2 3)
• My own colour theme
• Colour to indicate current section in navigation bar (maybe superfluous with breadcrumbs) and/or position in Table of contents
• Automatic conversion from Obsidian to Hugo syntax (maybe with Amethyst?)
• Enable comments (see the Hugo docs)
• Improve icons support using e.g. the Icons module