How to start building websites with Hugo

How to start building websites with Hugo

In this short tutorial, I would like to show you how to build websites with Hugo. Hugo is a trendy framework for building websites that is easy to set up if you know at least some basic coding. However, this tutorial is intended for complete beginners who have no prior experience with web development and coding. First, we will prepare our development environment. Then I will show you where to download a custom theme and how to use it.

Development environment

First, you will need an editor where you can modify the website files - write the content and modify the code. One of the most popular editors is VS Code. However, there are also other editors like Atom or Sublime Text. VS Code has a rich database of extensions and an active community. Atom is very similar in many aspects, but it can be slightly slower than VS Code. Sublime Text is a paid editor, and it is very quick compared to VS Code and Atom. Still, the extension community is not as rich as in the case of Atom or VS Code. It's entirely up to you which editor you choose.

If you are a macOS user, installing Homebrew, a package manager for macOS, is a good idea and almost a necessity. This step will significantly improve your developer experience. To install Homebrew, visit its website and follow the described steps. The brew tells you to put the line of code somewhere - in the macOS terminal. It is an application you can find in the Launchpad on your macOS. What is a package manager? A package manager is a collection of tools that automate installing, upgrading, configuring, and removing applications in a consistent manner. Windows users will need to install Chocolatey, a package manager for Windows. The terminal application depends on the version of Windows you use. Windows 11 offers a Windows Terminal application that defaults to PowerShell; on Windows 10, you can download the Windows Terminal application from the Microsoft Store. You can paste the code to Windows Terminal from the Chocolatey website. We will use this Terminal later to run Hugo. If you are a Linux user, you will already have a preinstalled package manager, which is part of your Linux distribution.

When you successfully install a package manager for your operating system, you need to install Git. This tool will track any changes you make to project files. You can install Git in different ways, depending on the operating system you use:

On macOS, we will use Homebrew that we installed in the previous step and input this command into the Terminal:

1brew install git

On Linux, we can use the built-in package manager; I will use Ubuntu's apt-get package manager:

1apt-get install git

On Windows, we can download the Git installer from the Git website.

Now, we can install Hugo. Similarly, as in the case of Git, this step differs by the operating system you use. On macOS, we again use Homebrew and put the command into the Terminal:

1brew install hugo

On Linux:

1apt-get install hugo

and on Windows, we will use Chocolatey:

1choco install hugo -confirm

Now we can try whether Hugo was installed correctly. Try to write the following command to the Terminal:

1hugo version

If Hugo was not installed successfully, you will be presented with a variation of the "command not found" message. However, if the installation was successful, you should see information about the version of Hugo you are using, e.g.:

1hugo v0.96.0+extended darwin/arm64 BuildDate=unknown

Choosing a theme

Hugo has plenty of themes; some are paid, and some are free. You can also write your own theme. It is good to start with an existing theme if you do not have prior experience with web development. In time, you will be able to modify it to suit your needs. Many free themes can be found on Hugo's website and also on GitHub. Paid themes can be found on this website.

After you choose your favorite theme, download the zip file. On GitHub, it can be downloaded by clicking on the green button code and selecting the option "Download ZIP". Now you can create your Hugo site project. However, before starting, ensure that you are in a directory (the place) where you want your website projects. This directory can be anywhere on your computer - it can be in your home folder, documents, or anywhere else. On macOS, I suggest creating the Websites folder in your home directory, which is the directory where you are when you open the Terminal. Use the cd (change directory) command to navigate the Terminal. The structure is following:

1cd folderName

You can write the path separated by slashes if you want to go into sub-directories.

1cd folderName/folderName/folderName

If you want to create a folder, you can use the mkdir (make directory) command:

1mkdir folderName

Write the following command when you are in the directory where you want to have your Hugo project. The project's name can be anything, but it should not contain spaces and diacritics.

1hugo new site <NAME_OF_YOUR_SITE>

Then you should extract the content of the zip file to the /themes folder in the directory of your Hugo site. Now you will need to modify the config.toml file. Add the following line to the config:

1theme = '<Name of the theme folder>'

This will ensure that Hugo loads the theme you chose. Now you can start adding content to your Hugo website. Content should be in the /content folder and MD format. MD stands for Markdown, a markup language that allows you to format your content. See these guidelines for help.

How to view your website

To view the website, you will need to start the Hugo server, which can be done via the following command:

1hugo serve

This command must be executed in the root directory of your project in the terminal. The root directory is the directory that has the name that you defined when you run the hugo new site <NAME_OF_YOUR_SITE> command. After running this command, you should see the following output:

1                   | EN
2-------------------+-----
3  Pages            | 46
4  Paginator pages  |  0
5  Non-page files   |  3
6  Static files     |  0
7  Processed images |  0
8  Aliases          | 19
9  Sitemaps         |  1
10  Cleaned          |  0
11
12Built in 134 ms
13Watching for changes in /Users/<Username>/Websites/MyHugoProject/{archetypes,content,data,layouts,static,themes}
14Watching for config changes in /Users/<Username>/Websites/MyHugoProject/config.toml
15Environment: "development"
16Serving pages from memory
17Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
18Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
19Press Ctrl+C to stop

The message tells you the number of content processed by the Hugo framework in the table. It also tells you that the Hugo framework monitors your website's folders - note the curly brackets with folder names like content, data, etc. Thus, any change you make in these folders will be automatically shown on the website in your browser. You can also find info about where the website is (accessible from your browser). The default address is: http://localhost:1313. Finally, there is a message on how to stop the hot-reloading process; this can be achieved by pressing [CTRL] + [C] on your keyboard (when you have finished modifying the content, [CTRL] + [C] will end the session).