Introduction

Why a static website generator and why Hugo?

  • because it’s a simple solution that works. For business card sites or blogs, you don’t need a complex backend.
  • All settings in one file hugo.toml or hugo.yaml in a declarative style, so everything is very concise. The TOML and YAML formats are so simple that you can set up a site without even delving into learning these formats.
  • You don’t need to delve into HTML, CSS, and JS to create content. Content is created in Markdown .md files. Markdown format is much simpler. There are plenty of Markdown syntax guides on the internet. For example, here.
  • The Hugo program is just a single binary file written in Go and has no additional dependencies. Hugo generates a site very quickly.

Installation

The Hugo website has a great guide on how to install Hugo for different operating systems and different package managers. But there is one caveat.
Operating systems like Debian or MX Linux are focused on stability, so some packages in their repositories may be outdated.
And the first thing you will do after creating a project using Hugo will be to install a site theme. And if Hugo is an outdated version, a significant number of themes will not work correctly.
Therefore, for operating systems like Debian or MX Linux, I recommend downloading the latest stable version of Hugo as a .deb file from the Hugo GitHub repository and installing it.
Additionally, you will need Git for your operating system.

Creating a project

It’s very simple. Open a terminal and run the command

hugo new site <ProjectName>

Hugo will create a folder named after your project <ProjectName> with all the necessary files and folders inside, as well as the hugo.toml configuration file.
To have Hugo create a project with a settings file in YAML format, you need to run the following command.

hugo new site <ProjectName> --format yaml

Some templates for Hugo provide sample site theme settings in YAML format on their websites, so you may want to use this format.

Installing the theme

You can choose a theme on the Hugo website. Then, go to the theme page and follow the installation instructions. There are several installation methods.
It is worth choosing the one recommended in the instructions.
For example, for the PeperMod theme:

  1. Open a terminal and go to the root of the project folder
cd <ProjectName>
  1. Initialize a local Git repository
git init
  1. Install the theme as a Git submodule (recommended method for this theme)
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
git submodule update --init --recursive
  1. Next, add the line to the hugo.yaml configuration file
theme: ["PaperMod"]

Settings

Settings for the entire site are in the hugo.toml or hugo.yaml file. (There are also settings for each page of the site in a Markdown file. The “front matter” metadata block in this case is placed at the beginning of the .md file.)
The baseURL parameter in the hugo.yaml file specifies the address of your published site.
For example, to run the site locally, the settings would be as follows:

baseURL: http://localhost:1313

After that, you can generate the site.

hugo

And start the server locally.

hugo server  # або 'hugo server --baseURL="http://localhost:1313/"'

Next, open your site in the browser at the address specified in the settings.
http://localhost:1313
Settings specific to each theme are set by the parameter - params.
There are a lot of configuration options, so I won’t describe them all. You can find detailed information on the Hugo website
Also on the PeperMod theme page there is a sample site with settings for this theme.

Content filling

All content is stored in the content folder. Let’s create a new page for the site with the command

hugo new content/FirstPage.md

Hugo will create a file with the default.md template, which is stored in the archetypes folder.
Next, edit the FirstPage.md file, regenerate the site, and start the server.

hugo
hugo server -D

The -D option means “Include content marked as draft”. When you finish editing the FirstPage.md file, you should change the draft parameter in the metadata block of the same file, “front matter”.

draft: false

After that, the page will be displayed on the website.

Adding an image

All images are stored in the static or assets folders.
The cover image for a single page is specified in the .md metadata block of the file.

cover:
  image: cover.png
  caption: "Page cover"

Site-wide images are configured in hugo.yaml

params:
  env: production
  images: ["og-default.png"]
  cover:
    hidden: false
  label:
    icon: "logo.svg"
    iconHeight: 45
  assets:
    favicon: "favicon.ico"
    favicon16x16: "favicon.ico"
    favicon32x32: "favicon.ico"

The images parameter specifies which image will be used for the cover when publishing the link on social networks. For this setting to work, you need to set env:production.
The label parameter specifies the site logo.
The favicon, favicon16x16 and favicon32x32 parameters set the site icon in the browser tab.
Please note that favicon, favicon16x16 and favicon32x32 must all be specified, even if there is only one image!
The value of the hidden: false parameter in the configuration is -

params:
  cover:
    hidden: false

means to show page cover images by default. For an individual page, you can disable this behavior in the page’s .md file.

Website publishing

You can publish a site for free, for example on GitHub Pages.
To do this, you need to create an account on GitHub with your UserName and a repository named UserName.github.io.
This is necessary so that your site gets the URL - UserName.github.io.
After that, upload your site from the public folder in your project to this repository. There are several ways to do this. Let’s consider the option with two repositories.
We create one in the root of the project for the source code.

cd mywebsite
git init # if the repository is not yet initialized
echo "public/" >> .gitignore
git add .
git commit -m "Initial commit."

The second one is in the public folder.

cd public
git init
git remote add origin git@github.com:username/username.github.io.git
cd ..
hugo
cd public
git add .
git commit -m "Deploy $(date)"
git push origin main --force

Important --force is necessary because the contents of public/ are regenerated each time hugo is run.

Another option is to use one repository for source code and for publishing the site.
In this case, create a separate repository branch for the generated code git checkout -b gh-pages.
Also in this case, in the repository settings on GitHub Settings -> Pages, in the Source -> Deploy from a branch section, specify the gh-pages branch and the folder where the site is located in this branch (/ is the root of the project).