Hugo is a great and popular tool for creating static sites quickly and easily. In this guide, we’ll cover how to set up a Hugo development environment on your pc, and how to create a new Hugo website in just a few minutes.

1. Install the Hugo environment

We’ll need to set up the Hugo development environment on our computer.

I use Windows as my operating system so all of the installation part below is relevant to this OS. However, Hugo site includes detailed installation instructions for a variety of other operating systems as well. Detailed instructions for Windows are available there as well.

  1. Create a folder for Hugo sites on your computer. This can be in C:\Hugo\ or in any other path.

  2. Create two subfolders inside this main Hugo folder: C:\Hugo\Sites and C:\Hugo\bin.

  3. Download the latest version of Hugo from its releases page on GitHub. Make sure to download the hugo_extended version. Choose the correct ZIP file according to your OS configuration. For example, my computer is using Windows 64 bit, so I’ll choose the hugo_extended_0.92.0_windows-64bit.zip file, where 0.92.0 will be changed according to the latest version available.

  4. Unzip/extract the ZIP file inside the C:\Hugo\bin folder you created earlier. You should now have three files in this folder: hugo.exe, LICENCE, and readme.md.

  5. Add Hugo to Windows PATH. This step is required in order to be able to use the hugo commands in the terminal later on.

    • In the Windows search bar in the taskbar, type Environment Variables and choose the “Edit the system environment variables” option.
    • In the window that was opened, press the “Environment Variables…” button on the bottom.
    • Under the top section of “User variables”, double click on the “Path” row.
    • Click “New”.
    • Type in the path of the bin folder you created earlier (e.g. C:\hugo\bin).
    • Click “OK” to exit the window.

  6. Make sure Hugo was configured correctly by typing hugo help in the terminal (command prompt). If you see a text starting with “hugo is the main command, used to build your Hugo site.” - the Hugo environment has been successfully installed.

This is it. You should now have a ready-to-use Hugo environment on your local development computer (yes, that simple!).

Now, just before creating the actual site, let’s take a quick break to talk about formatting, as this can be relevant for the site creation.

2. Formats: YAML vs. TOML vs. JSON

Hugo creates and uses a primary config file to set most of the site settings. It supports several formats: yaml, toml, json.

You can achieve all desired configurations with all three options, and actually Hugo’s documentation is detailed enough and includes a lot of code available in all three options (example).

So choosing a specific format is mainly a matter of personal preference (in my opinion yaml has the easiest syntax to read), and also how much the format is common among other developers who shares code (I find yaml to be very common so it’s easy enough to find code snippets in this format).

However, even if the format you’re using is different from the format of the code that you found and would like to use, no worries - you can easily convert it to your format using online tools. For example, YAML to TOML converters.

3. Create a new Hugo website

To create a new Hugo site:

  1. Use your terminal to navigate to the Sites subfolder in your Hugo folder: cd C:\Hugo\Sites - adjust the path to the one that you used.
  2. Type hugo new site <site name>. Make sure to replace <site name> with the actual name. Notice this command will create the site with the default format which is toml. If you would like to use a different format, set the “-f” option. For example, create a site that uses the yaml format by typing the following: hugo new site <site name> -f yaml.

4. Add a theme to the site

You can now add a theme which will change the styling (and some of the functionality) of your website.

While you can of course develop your own theme, Hugo offers a large library of great themes to choose from: https://themes.gohugo.io/.

Most of the themes will provide a link to a demo, so you can check out what it looks and feels like on a live site.

Each theme may include slightly different installation steps. Take a look at the theme’s documentation to learn more about its installation and the different features it includes (and how to configure those).

Hugo’s quick start guide uses “Ananke” as the theme for demonstration. Change the paths and the names below according to the theme you chose.

There are 3 main methods for installing a theme:

Method 1: Git - submodule

  1. cd to the site folder: cd <site name>.
  2. Type:
git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
git submodule update --init --recursive

Method 2: Git - clone

  1. cd to the site folder: cd <site name>.
  2. Type:
git init
git clone https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke

Method 3: ZIP file

  1. Go to https://github.com/theNewDynamic/gohugo-theme-ananke.
  2. Click the “Code” green button > “Download ZIP”.
  3. Extract the folder in site-folder/themes.
  4. Rename the folder to ananke.

The first two methods use Git to install the theme. This way you’ll be able to easily update your theme to a newer version once it’s available. However, you can manually download the theme as a ZIP file from its Git repository and extract it in the themes folder, as described in method 3. This way the theme files are backed up in your GitHub account (as we’ll cover in step 5), since they are included in your repository and being tracked.

Now edit the config file in the root folder of the site and set the theme that you’ve just installed by adding a new line: theme: "ananke" (change ananke to the theme that was used. This syntax assumes you’re using yaml as the format. Use theme = "ananke" if you’re using toml).

5. Git integration

While this step is optional, it is always recommended to use Git for managing a development project. Git allows you to track changes in the files, easily roll back to older versions, collaborate with other programmers, create an automated deployment process, and more.

  1. Create a new GitHub repository for the site, at https://repo.new/.
  2. Create a new .gitignore file in the site’s root folder.
  3. Add the relevant files and folders that Git shouldn’t track. For me, the .gitignore file for Hugo projects (inspired by the .gitignore of GitHub and Twitter - links in the References section) would be:
# Generated files by hugo
/public/*
/resources/_gen/

# Track changes in redirects for Cloudflare Pages
# https://developers.cloudflare.com/pages/platform/redirects/
!/public/_redirects

# Executable may be added to repository
hugo.exe
hugo.darwin
hugo.linux

# Temporary lock file while building
/.hugo_build.lock

# Dependency directories
node_modules

# OS - Mac
.DS_Store

# .idea folder
.idea

# Logs
logs
*.log

# Temporary files
.cache
.tmp
.cache
.sass-cache
  1. In the terminal, cd to the site folder: cd <site name>.
  2. If not done already in step 4: git init.
  3. Then type the following commands (adjust the URL to the URL of your repository):
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/yourgithubusername/githubrepo.git
git push -u origin main
  1. If you’re using GitHub Desktop, add the repository to the software:
    • Side menu > “Add”.
    • “Add existing repository…”.
    • Choose the location of the site root folder.
    • “Add repository”.

6. See it in action

Now it’s time to see the new site in action, on your localhost server.

  1. Start the Hugo server by typing: hugo server -D in the terminal.
  2. Navigate to http://localhost:1313/ in your browser to see the new site (it may use other port than 1313. Look at the URL that was printed in the terminal).
  3. Make changes to your Hugo site as you like. You can add content, or play around with the configuration file to define different settings.

As long as the Hugo server (hugo server -D) is working in the background, you can come back to the browser and see the changes. Some of them will automatically be visible, and some (like some server settings) will require refreshing the page.

7. Generate the static site

Once you’re happy with the site, you can generate the static version of it. These files can be deployed to production in order to have the site live.

Simply type hugo -D in the terminal to generate the static pages. By default, these files will be available under the public folder in your site. This path can be changed using the -d flag or by setting the publishdir option in the config file.

Notice that many of the front-end application hosting solutions, like Cloudflare Pages, can build the static site pages for you as part of its deployment process, so you won’t even need to generate it yourself. You can read more about it in my other post: How to deploy a Hugo site with Cloudflare Pages.

References