Basic Configuration

Hugo's configuration file has hundreds of possible settings, which is bound to overwhelm beginners. This page's purpose is to highlight the settings in hugo.yaml that matter most, so you don't get lost in the sheer volume of options.

baseURL

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

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

locale

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

locale: 'zh-TW'

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

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

title: 'My Site'

theme

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

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

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

params

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 on localized settings, see the languages documentation.

markup

markup.goldmark

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

renderer unsafe

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

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 management is important enough to warrant its own page. See URLs and Routing.

Splitting Configuration Files

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

archetypes

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.