It may seem that a static personal website is something from the past. After all, we live in LinkedIn/Twitter days where you can have your professional/personal pages with very little overhead. Therefore why would someone undergo the burden of planning, implementing, hosting and feeding their own page?

Certainly the claim above has it’s merits and the vast majority of people goes with it – including some carrying the needed technical knowledge to go against it. The fact that I am writing this post makes it obvious that I am one of the few not following the crowd.

After all, I see this just as another DIY project, where in most cases there are other products of solutions available, but choosing to build your own thing is a great learning opportunity and you might just end up with something that you are proud of.

That’s enough introduction, let’s jump into my building process.

Design #

I didn’t want to start from scratch. First because following some template will allow me to get to the fun part faster, and also because I am not the most artistic individual, therefore I wanted to avoid styling as much as I could. Finally, as much as I defend DIY for learning, we shouldn’t reinvent the wheel all the time.

Now, if you google or ask chatGPT for static website generators, you will find an overwhelming amount of alternatives to choose from (seriously, give it a shot). Then it became the time to filter my candidates. First, let’s list what I was looking for.

• I don’t want to do styling. Therefore, I must choose a framework with a plethora of themes available.
• I don’t intend to write front-end functionalities. Thus, I must find something with built-in support for the few bits of UX that I care about. Let’s say a search functionality and light/dark mode switcher is enough.
• It must use languages that I am familiar with, or at least curious about.
• Markdown support is a must.

My refined search led me to a few candidates. Jekyll, Hugo, Zola and Pelican. From these, the first to be discarded was Pelican for two reasons: I simply didn’t find themes that I could be happy with, and (oddly enough) because it’s written in Python, which is already my go-to language, meaning that there wouldn’t be much to learn.

Between my remaining candidates, I chose to give Jekyll a shot. Mostly, I was biased by my academic background. I’ve seen so many academics’ pages built with ready to go Jekyll themes that are quite tailored to an academic portfolio, allowing you to highlight your research, talks, and share some blog posts. I went with academic pages (check it out).

Getting started was a breeze. I forked the academic pages repository, set up the github pages and everything was ready, all I had to do was adding my content. I went ahead and fed the page with my research and CV in just a couple of hours. Amazing, right? Hmm… yes and no. As much as I wanted a quick start, my page was simply ready, and although I felt it was missing some flavor, I couldn’t justify trying to tweak the theme too much. The bottom line is that this process was a bit too efficient, which made it not too rewarding and didn’t give me the feeling that I got my own corner in the web. Now what?

I went back to my other alternatives and decided to give Hugo a shot. But why not Zola, you may ask. Well, I am not much of a Rustacean. Most of the times, you can completely avoid writing or reading any rust while using Zola. Although, I wanted to be able to play around with the building blocks of my page whenever needed. Go (which Hugo is based on) is just a lot simpler. In addition, Hugo is a lot more popular, and I quickly found a couple of themes that I could experiment with.

Setup #

Hugo has an extremely easy setup (see here). Simply install Hugo, clone some theme (or create your own from scratch if you are a try-hard), and fire up the server. I chose the congo theme. It’s relatively minimalist, lightweight and have a great documentation, I highly recommend you to check it out here.

My long term goal was to host my website from my raspberry Pi. Therefore, I took the very dubious decision to fire up the development server from a Docker container. My plan was simply to avoid downloading Hugo and it’s dependencies on my windows machine. It turns out that this is not a common practice in Hugo’s community, so I had to write the Dockerfile. To those who are eccentric enough to do the same, I share it below.

FROM hugomods/hugo:exts

# Create the Hugo site and remove the OG hugo config
RUN hugo new site website
RUN rm website/hugo.toml
  
# Set working directory
WORKDIR /src/website

# Download the theme (congo)
RUN git clone --depth=1 --branch v2.10.0 https://github.com/jpanther/congo.git ./themes/congo

# Copy local (content) files
COPY ./website .

# Run the Hugo server
CMD ["hugo", "server"]

Note that this setup copies some local files (the website directory) to the container. This is the config and the actual content of the website. I wont go over the details here because congo offers an extensive description on how to setup the configuration and the contents directories.

Personalization #

At this point, I had a blank (although nicely themed) website. It was time to add some content. First I set up my front page and CV. I love that these (and any other content) is filled with markdown files, this is particularly handy for those used to take notes with Obsidian.

Next, I wanted a place to display my research. I added a menu for it up top and filled some more markdown files as examples. When I launched the server I noticed that, by default, I had nowhere to put my coauthors and the publication venue in evidence. In addition, the theme enforce full dates (YYYY-MM-DD) to be used. To be honest, I can’t tell even the publication year of most my research, let alone the month and day.

Finally, I had a reason to tinker with the theme. To begin with, I had to understand how the layout files work. When you run hugo server, hugo copies the layout files from the theme. However, it does not overwrite any files that you already got a local version for, all you have to do is write your own files while respecting the theme’s directory structure and file names.

To be fair, for how small of a tweak I wanted to make, I had to modify quite a few things, the process was pretty fun however. I got to play with some Go templates, something I haven’t done before. In particular, one thing I am very proud of is the pop-up I created to provide the bibtex citation for my research papers, check it out.

Pretend this is a citation :)
            

I ended up with six new html files. My layouts directory looked like this.

layouts
├── _default
│   └── single.html
├── partials
│   ├── article-meta.html
│   └── functions
│       └── date.html
└── shortcodes
    ├── citation.html
    ├── goto_article.html
    └── summary.html

All I had left to do was finally feeding my research to the website. However, there is some boilerplate that you must fill for each content item. I am not a big fan of boilerplate copy pasting. Instead, I wrote a quick bash script to create a new article.

# Check if a filename is provided as an argument
if [ -z "$1" ]; then
  echo "Usage: $0 <filename>"
  exit 1
fi

# Get the filename from the first argument
filename="$1"

# Define the content
content='---
title: 
coauthors: ["V Coscrato"]
date: XXXX-01-01
summary: 
venue: 
paperurl: 
citation: "<br />"
tags: ["", "english"]
---

# These are some very handy shortcodes
{{< summary >}}
{{< goto_article >}}
{{< citation >}}'

# Create the file with the specified content
if mkdir "website/content/research/$filename" && echo "$content" > "website/content/research/$filename/index.md";  then
    echo "Article 'website/content/research/$filename/index.md' created with the specified content."
else
    echo "Failed to create file 'website/content/research/$filename/index.md'"
fi

I chmod’ed the script to make it executable and now all I had to do to create a new article was running ./create_article.sh <article_name> from my working directory. With this, I very quickly added all the items I wanted and fired the website.