Host Hugo with Netlify

Hugo is a static site generator that enables you to write your website’s content as Markdown files, and render them to nice-looking websites using Hugo themes. The word “static” in this context means that the files Hugo renders are meant to be served as-is, there is no “backend” for the site (unless you add custom Javascript code).

Static sites are perfect for many different kinds of websites, from personal blogs like this site to product sites (i.e. Brave browser’s website) to an organization’s home page (i.e. the LetsEncrypt project’s site) to documentation sites (i.e. DigitalOcean’s documentation). With a static site generator, you do not have to deal with web code like HTML or Javascript, but you still have the option of creating your own custom themes if that appeals to you.

When Hugo renders your source code into a website, it outputs everything you need to start serving the site to a public/ directory, allowing you to host the page in Docker, or on a VPS you control, or with a service like Netlify. You could even host your site on a Raspberry Pi you own (although I would recommend looking into running the site in a Docker container, instead of a Canonical Snap). Anywhere that can serve HTML should be able to serve your compiled Hugo website.

This blog will run through the basic steps to initialize a Hugo project, host it on Github, and setup hosting with Netlify.

Requirements

• Hugo
  • You should also pick a Hugo theme, i.e. PaperMod
• Go (optional)
  • You can add themes as a Hugo module instead of using Git submodules.
• Git
• Github account
• Netlify account

Initialize Hugo repository

There are different ways of structuring the repository, like putting the site’s content in a src/ directory or storing multiple Hugo sites in a single monorepo. This guide assumes you follow the default steps for initializing a Hugo project, where all source code is in the “root” of the repository.

First, cd to a path where you want to initialize your Hugo site, i.e. ~/git or just ~/ and initialize the site with:

1

hugo new site <your-blog-name>

Replace <your-blog-name> above with the name of your blog. The documentation uses quickstart as an example. You can name the site whatever you want, and can change it later by editing the hugo.toml/hugo.yml file the hugo new site command creates. When you run the Hugo command, you will see output with some first steps and instructions for editing the hugo.toml to change the site’s configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

$> hugo new site your-site-name
Congratulations! Your new Hugo site was created in /home/username/git/your-site-name.

Just a few more steps...

1. Change the current directory to /home/username/git/your-site-name.
2. Create or install a theme:
   - Create a new theme with the command "hugo new theme <THEMENAME>"
   - Or, install a theme from https://themes.gohugo.io/
3. Edit hugo.toml, setting the "theme" property to the theme name.
4. Create new content with the command "hugo new content <SECTIONNAME>/<FILENAME>.<FORMAT>".
5. Start the embedded web server with the command "hugo server --buildDrafts".

See documentation at https://gohugo.io/.

This is an example of the files hugo new site creates:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

your-site-name/
├── themes
├── static
├── layouts
├── i18n
├── hugo.toml
├── data
├── content
├── assets
└── archetypes
    └── default.md

Since this blog post is not meant to be an in-depth tutorial of how to build a website with Hugo, we will not go into detail on every single file and folder this command creates, but some important things to know are:

• The themes/ directory is where you store themes added as Git submodules.
  • This guide assumes you are using Hugo modules to install themes, instead of the old Git submodule way, so you will not need to interact with the themes/ directory.
  • This is also where you would store a custom theme, if you wanted to create your own Hugo theme for your site.
• The static/ directory is where you would store static assets for your site, including images and a favicon.ico for the site.
  • Although counter-intuitive, it is generally considered best practice to include the binaries for your static resources in the Git repository.
  • Save your favicon.ico to static/favicon.ico (if you have one), and any images you use in your posts in static/img (this directory doesn’t exist by default, you have to create it).
• The layouts/ directory is where you can create Hugo templates for finer-grained control of how content is displayed on your site.

The hugo.toml file is the main configuration file for your site. If you prefer YAML, you can copy the contents of hugo.toml into convertsimple.com, delete or rename hugo.toml to hugo.yaml/hugo.yml, and paste the converted configuration into the YAML file. Hugo will detect a file named hugo.yml or hugo.toml wherever you run hugo commands from. This guide assumes you are using YAML for your configuration.

1

hugo new site site-name --format yaml

Convert Site to Hugo Module

Next, initialize your site as a Hugo module:

1

hugo mod init github.com/username/your-site-name

After running this, you will see a go.mod file. This allows Go to mannage your site so you can install themes like they are Go packages. For example, to install the PaperMod theme by editing your hugo.yml file and adding the following block of code:

1
2
3

module:
  imports:
    - path: github.com/adityatelange/hugo-PaperMod

The full hugo.yml should now look like this:

1
2
3
4
5
6
7

baseURL: 'https://example.org/'
languageCode: en-us
title: My New Hugo Site

module:
  imports:
    - path: github.com/adityatelange/hugo-PaperMod

Run Local Hugo Development Server

Now you can test running the server with hugo serve, which will compile the site and start serving it at http://localhost:1313/ by default. To change the host address, i.e. to access it from another machine on the network, use --bind 0.0.0.0, and to change the port use -p <port>. This is Hugo’s development server. As you edit files, the server will ‘hot reload,’ re-compiling the Markdown you write and restarting the server.

Hugo does this very quickly. Each page takes mere milliseconds to render, even those with images or a lot of text, and it caches between rebuilds, only re-rendering the new content. This leads to a pleasant “change something and see it instantly” writing experience.

If you start the server with -D, Hugo will also render your drafts in the development server.

Git Repository Setup

Run git init -b main in your Hugo site’s directory to initialize a new Git repository. Before committing any code, add a .gitignore that ignores Hugo’s public/ and resources/ directories that it creates when you run the development server:

1
2

/public/
/resources/

Then, do your initial commit:

1
2

git add *
git commit -m "Initial commit"

Create a repository on Github for your Hugo site. This should match the URL you used when you create the Hugo module with hugo mod init github.com/user/your-site-name. Add the remote to your local repository:

1

git remote set origin git@github.com:username/your-site-name.git

And push your code with git push -u origin main.

Netlify Setup

Create an account on Netlify. During the setup process, you will be asked to create a project. Allow Netlify to integrate with your Github and find the repository with your Hugo site. If you already have a Netlify site, add a new project and use “Import an existing project” and find your Hugo repository.

When you are prompted to input build settings like the base directory/package directory, the build command, the publish directory, etc, leave all of these blank. You can optionally leave the functions directory as netlify/functions. If you set values here, the site will fail to build because the hugo.yml interferes with these settings. Do your site configuration in hugo.yml, not Netlify.

When asked which branch to trigger Netlify deploys on, you have a decision to make: do you want your site to deploy every single time you open a PR to the main branch, including times where you are doing small cleanup chores like updating the .gitignore, or setting up a new pipeline? Or do you want to have more control over deploys, i.e. only when merging into a branch named netlify?

I chose the latter, and created a netlify branch, then configured Netlify to deploy from the netlify branch instead of main. I also turned off deployment previews, so any PR into netlify will trigger a deploy.

netlify.toml Config

After finishing the setup, create a netlify.toml file in the root of your Hugo repository :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

[build.environment]
HUGO_BASEURL = "https://netlify-project-name.netlify.app"
HUGO_VERSION = "0.152.2"
HUGO_ENV = "production"
NODE_VERSION = "24"
HUGO_ENABLEGITINFO = "true"

[build]
command = "hugo --gc --minify"
publish = "public"

This file tells Netlify how to build your Hugo site. Commit it to git with git add * && git commit -m "Add netlify config" and push to main with git push. Even better, create a new branch before adding/committing your code, i.e. git switch -c feat/netlify-setup, then add the files and commit message. When you push, use git push -u origin feat/netlify-setup. Merge the branch into the main branch in Github.

Example Production Hugo Dockerfile

If you plan to host your Hugo site yourself, you can set up a Dockerfile to build your site and serve it behind a proxy like Caddy or NGINX.

You can use a multi-stage Docker build to have a smaller final image that only has your rendered HTML and the Caddy server to serve it:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

FROM hugomods/hugo:exts AS builder

WORKDIR /src

## Copy Hugo site files & config
COPY archetypes/ archetypes/
COPY assets/ assets/
COPY content/ content/
COPY layouts/ layouts/
COPY static/ static/
COPY hugo.yml go.mod go.sum .hugo_build.lock ./

ARG HUGO_BASEURL=http://localhost/

RUN hugo \
  --minify \
  --gc \
  --baseURL="${HUGO_BASEURL}" \
  --destination /output/public

FROM caddy:alpine

COPY --from=builder /output/public /usr/share/caddy

COPY ./Caddyfile /etc/caddy/Caddyfile

EXPOSE 80 443

CMD ["caddy", "run", "--config", "/etc/caddy/Caddyfile"]

Create a Caddyfile the container will use to configure the Caddy server:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  # debug
  email {$CADDY_EMAIL}
}

{$CADDY_SITE_ADDRESS} {
  root * /usr/share/caddy
  file_server
  encode gzip

  header {
    X-Content-Type-Options nosniff
    X-Frame-Options DENY
  }
}

When you build the container, you will need to set environment variables for CADDY_EMAIL (for automated LetsEncrypt SSL certificates) and CADDY_SITE_ADDRESS (for handling connections coming to the Caddy URL). The 2 env vars are “build arguments”, which you can inject in your docker build command using --build-arg ARG_NAME=value. For example, to build this Dockerfile:

1

docker build --build-arg CADDY_EMAIL="youremail@address.com" --build-arg CADDY_SITE_ADDRESS="myblog.com" .

Check Links with Lychee

Lychee is a fast link checker you can use to check your site for broken links. You can install it locally and point it at your live site, or you can run it against the public/ directory after Hugo builds to check your links before deploying.

Lychee’s syntax is simple:

1
2
3
4
5

## Check links on your live site
lychee https://your-site-name.com

## Check links in the public/ directory after a Hugo build
lychee public/

As a Github action:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

---
name: "Test Blog Links"

on:
  ## Allow manual runs
  workflow_dispatch:
  
  ## Every 6 hours
  schedule:
    - cron: "0 */6 * * *"

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - name: Test live site links
        uses: lycheeverse/lychee-action@v1
        with:
          args: >-
            --base-verification false 
            --no-progress 
            "${{ vars.HUGO_BASEURL }}"/*

Or in a full pipeline that builds the site and then tests the public/ directory (this is useful to do before deploying):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

---
name: "PR checks"

on:
  pull_request:
    branches: [netlify]
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

env:
  HUGO_VERSION: "0.154.3"

jobs:
  test:
    name: Build & test Hugo site
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Vale prose linting
        uses: errata-ai/vale-action@v2.1.1
        with:
          files: '["content/**.{md}"]'

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: ${{ env.HUGO_VERSION }}
          extended: true

      - name: Build site
        run: hugo --gc --minify

      - name: Check links with Lychee
        uses: lycheeverse/lychee-action@v1
        with:
          args: "public/**/*.html --base ."
          fail: false

Closing

Building a blog with Hugo is fun, and relatively quick and easy to get up and running. You can build a complex site for your product, or a simple blog you update a couple times a year, all with the same tooling. The minimal amount of configuration you need to get started lends itself to quick development, while still allowing you to build up a more complex configuration over time. Hugo modules make it even easier to install themes and site extensions, and the ability to host the site anywhere that can serve static web files gives you a ton of flexibility to where you put the site online.

This guide did not go in-depth on configuring and customizing Hugo, nor did it walk through creating content for the site. The Hugo quickstart guide will do a better job of walking you through building your first blog, and I highly recommend keeping this site open and using the search bar at the top as you’re learning to find new ways of using Hugo.