Basic Configuration

Hugo's configuration file has hundreds of options you can set. This article highlights the settings in hugo.yaml most worth paying attention to, so you don't get lost in the sheer number of options.

baseURL (external link) Link to this heading

The site's production URL, which needs a trailing slash:

baseURL: 'https://example.com/'

locale (external link) Link to this heading

The site's language code, which affects output like the RSS feed and the HTML lang attribute:

locale: 'en-US'

Info

Hugo's docs reference RFC 5646 extensively, which seems to imply you need to follow its casing rules strictly. But internally, Hugo actually forces every language string to lowercase, with one exception: locale, which is used purely for template rendering and never touched by Hugo's internal processing. This means:

Only locale should follow the language-REGION format (e.g. en-US), with the language subtag in lowercase and the region subtag in uppercase.
Everything else stays lowercase for consistency, always. You never need to worry about casing beyond that.

title (external link) Link to this heading

The site title, used by most themes in the header and the browser tab title:

title: 'My Site'

theme (external link) Link to this heading

Specifies which theme to use, matched by theme name (for the git submodule approach):

theme: ['ananke']

The theme lives in the themes/ananke directory.

The Hugo Modules approach doesn't use themes and is installed as a module instead:

module:
  imports:
    - path: github.com/gohugo-ananke/ananke

taxonomies (external link) Link to this heading

Custom taxonomies. This setting determines whether Hugo processes tags at all. Whether tags are actually rendered is up to the theme:

taxonomies:
  tag: tags
  category: categories

pagination (external link) Link to this heading

Settings for paginated lists:

pagination:
  pagerSize: 10  # Number of posts per page
  path: p        # Pagination path

The site's navigation menu.

menus:
  main:
    - name: Home
      pageRef: /
      weight: 10
    - name: Posts
      pageRef: /posts
      weight: 20

name is the displayed label.
pageRef refers to a logical path.
Lower weight numbers sort earlier.
If a target directory doesn't render, try adding an identifier field to resolve it.

menu settings can be placed under the languages block to support localization, for example:

hugo.yaml

languages:
  en-us:
    label: English
    locale: en-US
    weight: 1
    menus:
      main:
        - name: Home
          pageRef: /
          weight: 10
        - name: Posts
          pageRef: /posts
          weight: 20
  fr-fr:
    label: Français
    locale: fr-FR
    weight: 2
    menus:
      main:
        - name: Accueil
          pageRef: /
          weight: 10
        - name: Articles
          pageRef: /posts
          weight: 20

For more settings that support localization, see the languages documentation (external link).

params Link to this heading

The block for theme-specific settings. Its contents are entirely up to the theme, so consult your theme's documentation:

params:
  showToc: true

Like menus, params can be moved under languages.params to support localization. For more settings that support localization, see the languages documentation (external link).

markup (external link) Link to this heading

markup.goldmark Link to this heading

Goldmark (external link) is what converts Markdown to HTML internally in Hugo. This setting controls the fine grained conversion rules.

renderer unsafe (external link) Link to this heading

Whether raw HTML inside Markdown content is allowed to render. Defaults to false:

markup:
  goldmark:
    renderer:
      unsafe: true

When this isn't enabled, HTML tags in your content are stripped out.

extensions typographer (external link) Link to this heading

Controls how characters like ..., ", and ' are rendered. By default they're converted to curly variants.

markup:
  goldmark:
    extensions:
      typographer:
        apostrophe: "&rsquo;"
        disable: false
        ellipsis: "&hellip;"
        emDash: "&mdash;"
        enDash: "&ndash;"
        leftAngleQuote: "&laquo;"
        leftDoubleQuote: "&ldquo;"
        leftSingleQuote: "&lsquo;"
        rightAngleQuote: "&raquo;"
        rightDoubleQuote: "&rdquo;"
        rightSingleQuote: "&rsquo;"

Permalinks Link to this heading

Link management is important enough to warrant its own page. See URL Management.

Splitting Configuration Files Link to this heading

If your configuration file becomes too large or complex, you can use a configuration directory (external link) to split different keys into separate files.

archetypes Link to this heading

archetypes isn't a setting inside hugo.yaml. It's a directory in your project.

It controls the default content of Markdown files created by hugo new content. hugo-community-docs recommends removing draft: true from it first, so you don't waste time debugging a page that simply didn't build because you forgot the -D flag.