So, how did you make this website?

It was simple, really. I used Hugo and GitHub Pages. (Along with some other tools and infrastructure.) This post is intended to be a simple and to-the-point guide on how to make this exact website, but I’ll also do my best to point out which choices could be made differently to create a slightly different website than this. I may or may not update this guide in the future to reflect any changes I make to the structure of the site. This guide shouldn’t be too difficult to follow for someone without much programming experience, so more advanced users might want to skip around a little. With that, here we go!

Making the website

The first step, in my opinion, should be to build the website itself. There’s no sense in worrying yourself about hosting options and infrastructure before you’ve even created a presentable website to host. A simple portfolio/blog site such as this is called a static site, meaning that there are no underlying databases or other backend functionality. That’s not to say that the website can’t be made interactive with JavaScript, CSS animations, etc., but there is no work being done on the server’s part when a user interacts with the website.

The easiest way to create a static site is to use a static site generator (SSG). There are many of these available, but the most popular are Hugo and Jekyll. Both function very similarly, and are supported by basically every hosting platform. Jekyll is generally considered to be more compatible with GitHub Pages than Hugo, but I didn’t find this to be the case in my own testing. There are many Jekyll themes that are not compatible with GitHub Pages, whereas just about any Hugo theme can be made compatible using free GitHub Actions workflows. For this reason, I decided to create this website using Hugo over Jekyll, but many of the steps in this guide could be used with Jekyll as well.

Installing Hugo

In order to begin working with Hugo, you need to install it onto your device. It should be fully compatible with Windows, Linux, BSD, and MacOS. Although, if you’re using Windows, I’d recommend installing Windows Subsystem for Linux first since Linux is generally more predictable than Windows, and will make following this guide a lot easier. If you have some kind of limited operating system like a Chromebook or mobile device, things are a little trickier, but you should be able to simply skip ahead to the setup of GitHub pages and then do all of your development directly on GitHub, rather than installing anything locally. To install Hugo, you’ll need to install both the Hugo program and Git onto your device. Git is the program we’ll be using to install themes, keep track of changes to our site, and publish them to GitHub. You can install git from the git website, then Hugo from the Hugo website by scrolling down to the “Package Managers” section for your operating system. Windows users using WSL should follow the Linux instructions for Debian.

Creating a new site

With all the tools we need installed, now it’s time to initialize a new Hugo site. First, open a terminal. Navigate to the folder where you want your website files to live. This could simply be your Documents folder, or wherever sounds good to you. To check that Hugo is installed properly, you can run the command hugo version, which should display a number greater than v0.146.0. Assuming Hugo is installed, you can then create your site with the command hugo new site mysite, where “mysite” can be replaced with any name you want for your website, as long as there are no spaces. Hugo will create a new folder for your website, which you can enter with cd mysite. There are many files in here, but most of them are irrelevant to us for our simple website. We’ll be using hugo.toml to change settings for our site, and placing files in content/ and static/ for the pages and images in our site, respectively. Before we do this though, it’s time to choose a theme!

Installing a theme

Themes in Hugo are essentially templates for your website, similar to what you’d find in a traditional website builder like Wix or Squarespace. They give you starting layouts and pages to easily place your content into, so that you don’t have to do any frontend programming yourself. They often come with their own custom settings and pages, designed to make customization as easy for you as simply editing some text in your hugo.toml file. Hugo themes can be found in many different places online, and there’s no “wrong” way to find one. The simplest way to locate a theme, however, is to look through the official listing on Hugo’s own website. This is where I found the theme I currently use for this website, Poison by Luke Orth.

Once you’ve found a theme that looks just right, installing it is easy. Some themes will have custom instructions or warnings in the README of their repository, but for the most part, Hugo’s official instructions will work fine. First, locate the URL to your theme’s repository. This should be the “download” link on the Hugo theme page, and will usually be a page on GitHub. Once you’ve copied this link, switch back to your terminal. We can instruct git to begin tracking our website by running the command git init, which will give us the ability to install themes. Next, we run the command git submodule add <URL here>.git themes/<theme name here>. Notice that the URL should have .git typed at the end, and that the theme name after themes/ should be written the same as it is after the / at the end of the URL. For example, if I’m installing Poison, my URL will be typed as https://github.com/lukeorth/poison.git, and the last argument in the command will be written as themes/poison. This command downloads and installs the theme you’ve chosen into the themes folder of your website, which makes it available for us to use.

Now, we simply have to select the theme we’ve installed by setting it in our hugo.toml file. This would be a good time to check whether your theme comes with an example configuration file, which would probably be mentioned somewhere in the README file on its GitHub page. If there is one, copy it. Our hugo.toml file is simply a text file, so you can edit it using your favorite text editor. Something basic like Notepad will work fine, but I would recommend using a code-focused text editor like Notepad++, Sublime Text, Vim, etc. If you’ve copied an example file, highlight everything in the file and paste over it. Otherwise, simply add to the very top of the file: theme = '<theme name>', keeping the quotation marks and using the same theme name as before.

Testing the site

With this, our theme should be enabled! Now we just have to test it. To test your website anytime you want, you can simply run the command hugo server, which will host a local copy of your website and give you a link to view it, which should be near the end of the output and start with http://. Now, simply try clicking this link or copying it into your web browser, and fingers crossed, your website should load! It won’t look like much at this point since we haven’t created a homepage yet, but you’ll most likely be able to see a bit of your chosen theme showing.

Now that we have our theme fully installed, this would be a great time to save some of our changes. The best way to do this is by creating a commit using git, which is essentially a labeled snapshot in time of the current state of our website. This is easily done by running the command git commit -m "Theme installed", where the part in quotes after -m is our commit message. Feel free to write anything you want in your commit message, as long as it will help your future self remember what you changed with this commit.

Adding content

All that’s left in creating our website is to start adding some content! Most Hugo themes are centered around blog posts, so that’s what I’ll focus on here, but most themes should come with some instructions in their README on creating standalone pages as well.

Theme components

First of all, if your Hugo theme comes with any settings for the base content of your website, that should be filled out first. Many Hugo themes have a sidebar, homepage, or other component that is a constant throughout the website. You should be able to edit this by changing settings in your hugo.toml, as is explained in your theme’s README or example config. In my case, the Poison theme comes with an example hugo.toml config that includes many settings for the sidebar such as brand, description, various URLs for the icon links, and some color settings. I can control the content on the sidebar of my website simply by changing these settings. If you can’t find these settings with your theme, don’t worry about it for now. You can always come back and change these later. More importantly, let’s try adding a page and see how it looks.

Blog posts

Hugo blog posts are typically stored in the content/posts/ folder. To create your first post, use the same text editor as before to create a new file called my-first-post.md in this folder. The .md extension indicates that we’ll be writing this post in a format called Markdown. Markdown is a way of formatting text online that was popularized by GitHub README files and Discord chat rooms, among other uses. You can simply treat this file as plaintext if you wish, but formatting in markdown is easy for anyone to get used to. The basics are this:

• *example* Asterisks around your text make it italic.
• **example** Double asterisks around your text make it bold.
• # example A pound sign before your text makes it a headline.
• - example A dash before your text adds a bullet point.
• A blank line can be placed between paragraphs to separate them properly.

More details on markdown can easily be found with some searching, but this should be enough to get started. Before we can begin writing our post, however, we have to include some information in the front matter of our file. This is essentially some basic data about our post that will determine how it’s displayed on the website, such as a title and date. The front matter of a Hugo post can be written in a few different programming languages, but the simplest option is to use TOML, which is the same as our hugo.toml configuration file.

To signal the start of our front matter, we type in three plus signs, like this: +++. Then on the next line, we can begin adding TOML data in the format name = value. To add a title to our post, we’ll add title = 'My First Post'. Then, on the next line, we’ll add the current date and time in the format date = YYYY-MM-DDThh:mm:ss-hh:mm, which is a very scary looking format! Don’t worry though, it’s simple. The letter “T” towards the center of this format is exactly that, the letter “T”. It’s not meant to be replaced with anything, but simply to distinguish between the date and the time. The part before the “T” is simply the date in year-month-day format, and the part between the “T” and the “-” sign is the current time in hour:minute:second format. Finally, the part after the minus sign represents your current timezone relative to UTC in hour:minute format. I live in New York, so my time zone is EST. A quick search online reveals that EST is UTC-5 hours, so I write -05:00 for my time zone. If you live in a time zone that is ahead of UTC, you can replace the minus sign with a plus. Finally, with our date and time in place, we can close our front matter with another three plus signs: +++. Thus, our file should currently look something like this:

+++
title = 'My First Post'
date = 2026-02-10T15:23:00-05:00
+++

Now, all that’s left is to write some content in our post! Everything below the front matter is treated as markdown, so the formatting rules explained above apply. Feel free to write anything you want, and when you’re done, make sure to save the file. With our first post written, we can once again run hugo server and navigate to our website. If your theme is working correctly, there should be a link to your new post visible somewhere on the page. Click through to your post and take a look at your hard work!

Multimedia

This part is optional, but was important for my website since the Poison theme has a prominent image front and center in the sidebar. Just as pages and text content can be added through the content/ folder, multimedia such as images and videos can be added in the static/ folder. Any images in this folder can be linked to your pages using the markdown image syntax, ![alt text](image file). Theme settings are also able to access these images, which is how Poison is able to place a photo in the sidebar. To achieve this, place the photo you’d like to use somewhere in static/, such as static/images/headshot.png. Then, in your hugo.toml file, Poison has a setting called brand_image which should be set to the path of your file, starting with static/ as the root. For example, /images/headshot.png. Many other themes will have a similar setting that should be set in the same way.

Most websites also have what’s called a favicon, which is the image that appears at the corner of the tab in your browser bar. This should typically be a small image in .png or .ico format. To set a favicon, simply rename your compatible image file to favicon.png, favicon.ico, etc., and place it in the root of static/. Unless your theme has a setting that overrides this, Hugo should automatically locate your favicon and load it into the browser.

Done!

We now have a complete website on our computer with all of the content we want to include! With this done, it’s important to perform another git commit -m "Done!" to save our changes. Once we’re publishing our website through GitHub Pages, our published website will only update when we git commit our changes, not when we merely save the files.

Hosting and Publishing

This part of the guide is coming soon! In the meantime, feel free to start looking at registrars for a great domain name.