Skip to content

introduction.md

Latest commit

 

History

History
317 lines (232 loc) · 10.5 KB

introduction.md

File metadata and controls

317 lines (232 loc) · 10.5 KB
title Introduction
description Configure your site using files, directories, and environment variables.
categories
keywords
weight 10

Sensible defaults

Hugo offers many configuration options, but its defaults are often sufficient. A new project requires only these settings:

{{< code-toggle file=hugo >}} baseURL = 'https://example.org/' locale = 'en-us' title = 'My New Hugo Site' {{< /code-toggle >}}

Only define settings that deviate from the defaults. A smaller configuration file is easier to read, understand, and debug. Keep your configuration concise.

Note

The best configuration file is a short configuration file.

Configuration file

Create a project configuration file in the root of your project directory, naming it hugo.toml, hugo.yaml, or hugo.json, with that order of precedence.

my-project/
└── hugo.toml

Note

For versions v0.109.0 and earlier, the project configuration file was named config. While you can still use this name, it's recommended to switch to the newer naming convention, hugo.

A simple example:

{{< code-toggle file=hugo >}} baseURL = 'https://example.org/' locale = 'en-us' title = 'ABC Widgets, Inc.' [params] subtitle = 'The Best Widgets on Earth' [params.contact] email = 'info@example.org' phone = '+1 202-555-1212' {{< /code-toggle >}}

To use a different configuration file when building your project, use the --config flag:

hugo build --config other.toml

Combine two or more configuration files, with left-to-right precedence:

hugo build --config a.toml,b.yaml,c.json

Note

See the specifications for each file format: TOML, YAML, and JSON.

Configuration directory

Instead of a single project configuration file, split your configuration by environment, root configuration key, and language. For example:

my-project/
└── config/
    ├── _default/
    │   ├── hugo.toml
    │   ├── menus.en.toml
    │   ├── menus.de.toml
    │   └── params.toml
    └── production/
        └── params.toml

The root configuration keys are {{< root-configuration-keys >}}.

Root key

{{< new-in 0.162.0 />}}

When splitting the configuration by root key, you may omit or include the root key in the component file. For example, these are equivalent:

{{< code-toggle file=config/_default/hugo >}} [params] foo = 'bar' {{< /code-toggle >}}

{{< code-toggle file=config/_default/params >}} foo = 'bar' {{< /code-toggle >}}

This also applies to keys whose values are maps of slices, such as menus. For example, these are equivalent:

{{< code-toggle file=config/_default/menus >}} [[main]] name = 'Home' pageRef = '/' weight = 10 {{< /code-toggle >}}

{{< code-toggle file=config/_default/menus >}} [[menus.main]] name = 'Home' pageRef = '/' weight = 10 {{< /code-toggle >}}

For pure slice-typed keys such as cascade and permalinks, including the root key is required. For example:

{{< code-toggle file=config/_default/cascade >}} [[cascade]] [cascade.params] color = 'red' [cascade.target] path = '/articles/**' {{< /code-toggle >}}

Note

Hugo unwraps the root key only when it is the sole top-level key in the file and matches the file's basename.

Recursive parsing

Hugo parses the config directory recursively, allowing you to organize the files into subdirectories. For example:

my-project/
└── config/
    └── _default/
        ├── navigation/
        │   ├── menus.de.toml
        │   └── menus.en.toml
        └── hugo.toml

Example

my-project/
└── config/
    ├── _default/
    │   ├── hugo.toml
    │   ├── menus.en.toml
    │   ├── menus.de.toml
    │   └── params.toml
    ├── production/
    │   ├── hugo.toml
    │   └── params.toml
    └── staging/
        ├── hugo.toml
        └── params.toml

Considering the structure above, when running hugo build --environment staging, Hugo will use every setting from config/_default and merge staging's on top of those.

Let's take an example to understand this better. Let's say you are using Google Analytics for your website. This requires you to specify a Google tag ID in your project configuration:

{{< code-toggle file=hugo >}} [services.googleAnalytics] ID = 'G-XXXXXXXXX' {{< /code-toggle >}}

Now consider the following scenario:

  1. You don't want to load the analytics code when running hugo server.
  2. You want to use different Google tag IDs for your production and staging environments. For example:
    • G-PPPPPPPPP for production
    • G-SSSSSSSSS for staging

To satisfy these requirements, configure your site as follows:

  1. config/_default/hugo.toml

    • Exclude the services.googleAnalytics section. This will prevent loading of the analytics code when you run hugo server.
    • By default, Hugo sets its environment to development when running hugo server. In the absence of a config/development directory, Hugo uses the config/_default directory.

  2. config/production/hugo.toml

    • Include this section only:

      {{< code-toggle file=hugo >}} [services.googleAnalytics] ID = 'G-PPPPPPPPP' {{< /code-toggle >}}

    • You do not need to include other parameters in this file. Include only those parameters that are specific to your production environment. Hugo will merge these parameters with the default configuration.

    • By default, Hugo sets its environment to production when running hugo build. The analytics code will use the G-PPPPPPPPP tag ID.

  3. config/staging/hugo.toml

    • Include this section only:

      {{< code-toggle file=hugo >}} [services.googleAnalytics] ID = 'G-SSSSSSSSS' {{< /code-toggle >}}

    • You do not need to include other parameters in this file. Include only those parameters that are specific to your staging environment. Hugo will merge these parameters with the default configuration.

    • To build your staging site, run hugo build --environment staging. The analytics code will use the G-SSSSSSSSS tag ID.

Merge configuration settings

Hugo merges configuration settings from themes and modules, prioritizing the project's own settings. Given this simplified project structure with two themes:

project/
├── themes/
│   ├── theme-a/
│   │   └── hugo.toml
│   └── theme-b/
│       └── hugo.toml
└── hugo.toml

and this project-level configuration:

{{< code-toggle file=hugo >}} baseURL = 'https://example.org/' locale = 'en-us' title = 'My New Hugo Site' theme = ['theme-a','theme-b'] {{< /code-toggle >}}

Hugo merges settings in this order:

  1. Project configuration (hugo.toml in the project root)
  2. theme-a configuration
  3. theme-b configuration

The _merge setting within each top-level configuration key controls which settings are merged and how they are merged.

The value for _merge can be one of:

none : No merge.

shallow : Only add values for new keys.

deep : Add values for new keys, merge existing.

Note that you don't need to be so verbose as in the default setup below; a _merge value higher up will be inherited if not set.

{{< code-toggle file=hugo dataKey="config_helpers.mergeStrategy" skipHeader=true />}}

Note

Hugo can merge map configuration values from modules and themes into the project configuration, but cannot merge slice values. This applies to top-level slice keys such as menus, as well as to map keys whose values are slices, such as the per-kind format lists in outputs.

Environment variables

You can also configure settings using operating system environment variables:

export HUGO_BASEURL=https://example.org/
export HUGO_ENABLEGITINFO=true
export HUGO_ENVIRONMENT=staging
hugo

The above sets the baseURL, enableGitInfo, and environment configuration options and then builds your site.

Note

An environment variable takes precedence over the values set in the configuration file. This means that if you set a configuration value with both an environment variable and in the configuration file, the value in the environment variable will be used.

Environment variables simplify configuration for CI/CD platforms by allowing you to set values directly within their respective configuration and workflow files.

Note

Environment variable names must be prefixed with HUGO_.

To set custom site parameters, prefix the name with HUGO_PARAMS_.

For snake_case variable names, the standard HUGO_ prefix won't work. Hugo infers the delimiter from the first character following HUGO. This allows for variations like HUGOxPARAMSxAPI_KEY=abcdefgh using any permitted delimiter.

In addition to configuring standard settings, environment variables may be used to override default values for certain internal settings:

DART_SASS_BINARY : (string) The absolute path to the Dart Sass executable. By default, Hugo searches for the executable in each of the paths in the PATH environment variable.

HUGO_FILE_LOG_FORMAT : (string) A format string for the file path, line number, and column number displayed when reporting errors, or when calling the Position method from a shortcode or Markdown render hook. Valid tokens are :file, :line, and :col. Default is :file::line::col.

HUGO_MEMORYLIMIT : (int) The maximum amount of system memory, in gigabytes, that Hugo can use while rendering your site. Default is 25% of total system memory. Note that HUGO_MEMORYLIMIT is a "best effort" setting. Don't expect Hugo to build a million pages with only 1 GB of memory. You can get more information about how this behaves during the build by running hugo build --logLevel info and look for the dynacache label.

HUGO_NUMWORKERMULTIPLIER : (int) The number of workers used in parallel processing. Default is the number of logical CPUs.

Current configuration

Display the complete project configuration with:

hugo config

Display a specific configuration setting with:

hugo config | grep [key]

Display the configured file mounts with:

hugo config mounts