The netlify.toml file is a configuration file used to customize and automate the deployment of a site on Netlify. When deploying a Hugo site on Netlify, netlify.toml allows you to define the build process, environment variables, and deployment settings.

Here’s a detailed introduction to using netlify.toml for a Hugo site:

Basic Structure of netlify.toml

The netlify.toml file is written in the TOML format and typically resides in the root of your project. A simple example for a Hugo site looks like this:

1
2
3
4
5
6
7

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

[build.environment]
  HUGO_VERSION = "0.115.2" # Specify the Hugo version
  HUGO_ENV = "production"  # Set the Hugo environment to production

Key Sections

  1. [build] Section This defines the build settings for your site.

    • command: Specifies the build command to generate the static site. For Hugo, the default is:

      1

      command = "hugo --gc --minify"
      • --gc: Enables garbage collection to clean up unused resources.
      • --minify: Minifies the HTML, CSS, and JS for optimized delivery.

    • publish: The directory where Hugo generates the static site. For Hugo, it’s usually:

      1

      publish = "public"

  2. [build.environment] Section Sets environment variables for the build process.

    • HUGO_VERSION: Defines the Hugo version to use during the build. This is essential because Netlify doesn’t always default to the latest Hugo version.

      1

      HUGO_VERSION = "0.115.2"

      Replace "0.115.2" with the desired Hugo version.

    • HUGO_ENV: Sets the environment to production or development. For live sites, use:

      1

      HUGO_ENV = "production"

    • Other environment variables (if needed):

      1
2

      GO_VERSION = "1.20" # If using Go modules
GIT_SUBMODULE_STRATEGY = "recursive" # If using Git submodules

  3. [[redirects]] Section Sets up redirects for your site. This is useful for SEO, custom routes, or handling 404s.

    Example: Redirect /old-page to /new-page:

    1
2
3
4
5

    [[redirects]]
  from = "/old-page"
  to = "/new-page"
  status = 301
  force = true

  4. [[headers]] Section Configures custom HTTP headers for your site.

    Example: Add a security header:

    1
2
3
4
5

    [[headers]]
  for = "/*" # Applies to all paths
  [headers.values]
    Content-Security-Policy = "default-src 'self'"
    X-Frame-Options = "DENY"

  5. [[plugins]] Section Adds Netlify Build Plugins for additional functionality.

    Example: Install a plugin to optimize images:

    1
2

    [[plugins]]
  package = "@netlify/plugin-image-optim"

Example Full Configuration for a Hugo Site

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

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

[build.environment]
  HUGO_VERSION = "0.115.2"
  HUGO_ENV = "production"
  GIT_SUBMODULE_STRATEGY = "recursive"

[[redirects]]
  from = "/old-blog/*"
  to = "/new-blog/:splat"
  status = 301
  force = true

[[headers]]
  for = "/*"
  [headers.values]
    Content-Security-Policy = "default-src 'self'; script-src 'self' 'unsafe-inline';"
    X-Frame-Options = "SAMEORIGIN"

[[plugins]]
  package = "@netlify/plugin-lighthouse"

Deployment Workflow

  1. Add netlify.toml to Your Hugo Project Place the netlify.toml file in the root of your project.

  2. Push Changes to Git Netlify automatically detects changes when you push to the connected repository. Ensure the netlify.toml file is committed:

    1
2
3

    git add netlify.toml
git commit -m "Add netlify.toml for Hugo deployment"
git push

  3. Trigger Build on Netlify

    • Log in to Netlify and link your repository if it’s not already connected.
    • Netlify will read the netlify.toml file and build the site accordingly.

Common Issues and Tips

  1. Incorrect Hugo Version:

    • Ensure the HUGO_VERSION in netlify.toml matches the one used locally.

  2. Using Git Submodules:

    • Add GIT_SUBMODULE_STRATEGY = "recursive" to handle submodules during deployment.

  3. Using Go Modules:

    • Set GO_VERSION to ensure the correct version of Go is used.
    • Go modules dependencies are fetched automatically by Hugo.

  4. Custom Domain and Redirects:

    • Configure redirects in netlify.toml for better control of URL structure.

  5. Performance Optimization:

    • Use the --gc and --minify flags in the build command.
    • Consider adding plugins like @netlify/plugin-lighthouse to analyze site performance.

With a properly configured netlify.toml, deploying a Hugo site to Netlify becomes efficient and automated, ensuring a consistent and optimized build process.

For more advanced configurations and options, refer to the Netlify documentation.

Reference:

Netlify Documentation Netlify Build Plugins Netlify Redirects Netlify Headers Netlify Environment Variables Netlify Build Command Netlify Build Plugins