Proud to present my new website developed with Hugo and hosted on GitHub Pages and discuss here how I built the site.

How did I build this website?

NOTE: I am not trying to write a full tutorial, there are (too) many already out there. I am outlining how I went about building this website and I am documenting some things I had to learn the hard way, i.e. lost too much time for something that was relatively simple in hindsight but I just did not find it easily in the existing tutorials.

HUGO

I am using Hugo since it’s actively being developed, has various themes, and builds a static website from source files on your computer. You do not get locked into a hosting service’s proprietary publishing software or templates.

I further prefer the command-line nature of building the site with the hugo command and the publication of the site also happens from the commandline with git. I edit the ‘source’ files (.md, .yml, .html, …) with vscode but you can use anything else.

Template

First, I googled site:edu “powered by Hugo” to see what templates academics are using. The ones that I liked were ‘PaperMod’, ‘Hugo Cards’, and ‘Hugo Coder’ for a personal profile site; ‘Docks’ and ‘Academic Theme` are probably more suited for a research group site.

I settled for PaperMod and more specifically used the modified version by Pascal Michaillet; he provides a template website, that I downloaded through a zip file1 and unzipped on my computer. The template already has the correct hugo folders, includes a config.yml and includes the theme files, so it is very easy to get started. From here on, it was mostly editing the existing files and adding my own materials.

Configuring the Site

config.yml is the key file you need to customize from the template to make the site your own.

  • baseURL is important; it is the base URL for where you will be publishing the site; it needs to end with a /.
  • menu is for the menu in the upper right corner of the pages
  • params: –> profileMode: –> enabled: true is what makes the root page a picture with some text and buttons.
  • params: –> socialIcons: show up on the profile page.

Building Pages

  • You need to get familiar with Markdown since that is the easiest way to write new content for Hugo. You can also have html files and even org files I believe.

  • When you want to create a page, you have to put a file in the contents folder. E.g. if you make a file first_page.md in contents, then when you run hugo build you will get a file /first_page/index.html generated in the build folder (typically public or docs), which can be accessed as <baseURL>/first_page once you post the site.

  • The .md files need to have the right heading to get processed by hugo:

---
title: "First Page"
date: 2025-01-25
description: "First Page"
---

  • There are hugo commands to create new contents like hugo new

  • Static material goes into the static folder under the correct subfolder; so, e.g., images for the first_page.md can be put in static/first_page/img/first_image.png and can then be added to first_page.md with ![](img/first_image.png)

  • I had an older website and at this point have in many cases brought over the html files and converted them in md files with the right header, but still the html inside; see e.g. Publications

Some Tips

  • hugo server is very handy to view your webpages in a browser as you are writing them; some times the changes ‘do not take’, so you have to exit it and restart it.

  • The links to other pages or static material are sometimes a bit hard to figure out, but hugo server can be quite helpful with that.

  • Two ways of putting a figure in an .md file:

    • ![](../images/photo_1996.gif) is standard markdown,
    • \{\{< figure src=\"../images/photo_jan_2011.png\" height=\"200px\">\}\} is a hugo directive that allows you to control the size of the figure; the \ do not need to be included, I needed them here to avoid errors for this page.

  • You can have links to headers in md pages; the link on top will point to the header below:

| [Books](#books) | 

## Books 
- A first book to read

GitHub Pages

I am using GitHub pages to host this site at https://peterkinget.github.io (so this my baseURL with an extra / at the end).

You need to be familiar with GitHub repositories to understand the notes below.

Repositories

  • I have a public repository peterkinget.github.io as GitHub recommends. I am only publishing the final site there though, not the original, full hugo site.

  • I have a separate ‘source’ repository hugo-site that I use to sync the full hugo folder on my computer. That folder gets published also as https://peterkinget.github.io/hugo-site/ (again, make sure the baseURL is correct in config.yml). I find it useful to keep things separate and can verify updates before posting them on my actual site.

Publishing a repository

  • In Github go to your repository –> Settings –> Pages –> ‘Deploy from a branch’ –> main & /docs. If all goes right, GitHub puts the URL on the top of this settings page, but you might have to wait a bit.

  • Check the ‘Actions’ tab for the repository to see if the publishing was successful.

  • You need to instruct hugo to build in the /docs folder by having publishDir: docs near the top of your config.yml since GitHub can only serve your site from a /docs folder.

  • Since my base URL is set to https://peterkinget.github.io/hugo-site/ in my ‘source’ hugo-site repo, I have to tell hugo to build the site with a different baseURL when I am ready to upload it to the peterkinget.github.io repo using hugo build --baseURL "https://<the correct baseURL>/"; then clear ( with rm) the peterkinget.github.io folder on my computer and mv the files from hugo-site/docs into the peterkinget.github.io/ folder, followed by the git commands to add, commit, and push that folder to the repository.

Some Tips

  • When you update your repository on GitHub, it will start processing the files right away. To see the progress and any possible issues look at Actions for your repository.

  • If you decide to start a hugo site from scratch (and not from a template site like above), then you will likely install the ’theme’ using git. Make sure to add it as a submodule, since you will sync your overall folder to your own repository. You will need to use something like git submodule add <URL_for_theme_repository> <theme_folder> and not git clone, otherwise GitHub will later have trouble publishing your site (see Actions mentioned above).

  • You can use GitHub workflows to make the hugo site from the repository, but I have not tried that yet. Here is a link I am saving for possible future use.

TO-DO

  • Understand the ‘posts’ and ‘posting’ better, including tags and categories.
  • Add commenting to posts using utterances.

  1. By using zip instead of git clone it’s easier to then later connect the folder to your own GitHub repository. ↩︎