I built a new personal website with Hugo

Welcome to my website. In this first post I will go over some details on how this site was created.

So, I didn’t use a fancy CMS like Wordpress, or a platform like Medium for example. Why is that?

  • I don’t need fancy stuff that requires session management, a database, authorization etc. I just need to publish information.
  • Static HTML is fast, robust and secure.
  • Content is just Markdown files on my laptop. They are easily accessible, lots of editors support Markdown, and it is easily portable.
  • The generated site is easily portable to any HTTP server without further dependencies.
  • I am leveraging my knowledge of Git, Markdown, HTML and CSS, all widely used and community supported.
  • I am a developer and actually like using text editors and command line over GUI’s.
  • I am using free open-source tooling and free hosting. Because I’m a cheapo and have an irrational fear of vendor lock-in.
  • I don’t need thousands of followers. I am glad you are here though!

The setup

This is how I did it

  • I installed Hugo on my laptop. I use Homebrew on macOS, so:

    brew install hugo
  • I have a Github account, where I created

    • a source repository for my Hugo website configuration and content, called website
    • a target Github Pages repository for my generated site called micheldebree.github.io (the naming convention for personal Github Pages). The site is served from this repository.

    This is because Github personal pages cannot be served from a subfolder in the repository. hugo generates the static website in the subfolder public, so I cannot make do with just one repository for source and target.

  • In the source repository website, I created the initial website by following the Hugo quickstart documentation.

  • Now a trick to generate the website that ends up in the public folder, directly into the root of the target repository; checkout the target repository as a submodule of the source repository, with the name public:

    cd website
    rm -rf ./public
    git submodule add https://github.com/micheldebree/micheldebree.github.io.git public

Now I’m ready to install a theme, tweak things to my liking, and start my first post.

Custom domain with HTTPS

As you may have noticed, this site is not served from micheldebree.github.io. That is because I setup Github Pages to use my own domain name. Check out the documentation on how to do that. Basically you need to:

  • Setup the DNS records at your domain provider to point to the Github servers.

  • Add a file called CNAME to the root of your site. Because hugo copies everything in the static folder verbatim to the root of the generated site, I created the file static/CNAME with the following content:

  • The best part: Github takes care of the https automatically, so visitors will see a green lock in their browser!

Build and publish the website

I now have one website repository to work in, with a submodule for the generated website. So when I make changes, I usually do a push to both repositories:

When I made some changes that I want to commit:

git add .
git commit -m "Finally finished my first blog post"
git push

This pushes the changes to the source repository, but doesn’t push the site that is served from micheldebree.github.io

If I want to publish the changes:

cd public
git add .
git commit -m "Finally finished my first blog post"
git push

This generates the website in the public folder and pushes it to the target repository, where Github serves it to the world.

You can see how this could easily be more automated, but for now it works fine for me.