Configure Hugo

Configuration File

Hugo uses the config.toml, config.yaml, or config.json (if found in the site root) as the default site config file.

The user can choose to override that default with one or more site config files using the command line --config switch.

Examples:

hugo --config debugconfig.toml
hugo --config a.toml,b.toml,c.toml

TODO: distinct config.toml and others (the root object files)

Configuration Directory

In addition to using a single site config file, one can use the configDir directory (default to config/) to maintain easier organization and environment specific settings.

Each file represents a configuration root object, such as Params, Menus, Languages etc…
Each directory holds a group of files containing settings unique to an environment.
Files can be localized to become language specific.

config
├── _default
│   ├── config.toml
│   ├── languages.toml
│   ├── menus.en.toml
│   ├── menus.zh.toml
│   └── params.toml
├── staging
│   ├── config.toml
│   └── params.toml
└── production
    ├── config.toml
    └── params.toml

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

All Configuration Settings

The following is the full list of Hugo-defined variables with their default value in parentheses. Users may choose to override those values in their site config file(s).

archetypeDir (“archetypes”): The directory where Hugo finds archetype files (content templates).
assetDir (“assets”): The directory where Hugo finds asset files used in Hugo Pipes.
baseURL: Hostname (and path) to the root, e.g. http://bep.is/
blackfriday: See Configure Blackfriday
buildDrafts (false): Include drafts when building.
buildExpired (false): Include content already expired.
buildFuture (false): Include content with publishdate in the future.
caches: See Configure File Caches
canonifyURLs (false): Enable to turn relative URLs into absolute.
contentDir (“content”): The directory from where Hugo reads content files.
dataDir (“data”): The directory from where Hugo reads data files.
defaultContentLanguage (“en”): Content without language indicator will default to this language.
defaultContentLanguageInSubdir (false): Render the default content language in subdir, e.g. content/en/. The site root / will then redirect to /en/.
disableHugoGeneratorInject (false): Hugo will, by default, inject a generator meta tag in the HTML head on the home page only. You can turn it off, but we would really appreciate if you don’t, as this is a good way to watch Hugo’s popularity on the rise.
disableKinds ([]): Enable disabling of all pages of the specified Kinds. Allowed values in this list: "page", "home", "section", "taxonomy", "taxonomyTerm", "RSS", "sitemap", "robotsTXT", "404".
disableLiveReload (false): Disable automatic live reloading of browser window.
disablePathToLower (false): Do not convert the url/path to lowercase.
enableEmoji (false): Enable Emoji emoticons support for page content; see the Emoji Cheat Sheet.
enableGitInfo (false): Enable .GitInfo object for each page (if the Hugo site is versioned by Git). This will then update the Lastmod parameter for each page using the last git commit date for that content file.
enableInlineShortcodes: Enable inline shortcode support. See Inline Shortcodes.
enableMissingTranslationPlaceholders (false): Show a placeholder instead of the default value or an empty string if a translation is missing.
enableRobotsTXT (false): Enable generation of robots.txt file.
frontmatter: See Front matter Configuration.
footnoteAnchorPrefix (“”): Prefix for footnote anchors.
footnoteReturnLinkContents (“”): Text to display for footnote return links.
googleAnalytics (“”): Google Analytics tracking ID.
hasCJKLanguage (false): If true, auto-detect Chinese/Japanese/Korean Languages in the content. This will make .Summary and .WordCount behave correctly for CJK languages.
imaging: See Image Processing Config.
languages: See Configure Languages.
languageCode (“”): The site’s language code.
languageName (“”): The site’s language name.
disableLanguages: See Disable a Language
layoutDir (“layouts”): The directory from where Hugo reads layouts (templates).
log (false): Enable logging.
logFile (“”): Log File path (if set, logging enabled automatically).
menu: See Add Non-content Entries to a Menu.
metaDataFormat (“toml”): Front matter meta-data format. Valid values: "toml", "yaml", or "json".
newContentEditor (“”): The editor to use when creating new content.
noChmod (false): Don’t sync permission mode of files.
noTimes (false): Don’t sync modification time of files.
paginate (10): Default number of elements per page in pagination.
paginatePath (“page”): The path element used during pagination (https://example.com/page/2).
permalinks: See Content Management.
pluralizeListTitles (true): Pluralize titles in lists.
preserveTaxonomyNames (false): Preserve special characters in taxonomy names (“Gérard Depardieu” vs “Gerard Depardieu”).
publishDir (“public”): The directory to where Hugo will write the final static site (the HTML files etc.).
pygmentsCodeFencesGuessSyntax (false): Enable syntax guessing for code fences without specified language.
pygmentsStyle (“monokai”): Color-theme or style for syntax highlighting. See Pygments Color Themes.
pygmentsUseClasses (false): Enable using external CSS for syntax highlighting.
related: See Related Content.
relativeURLs (false): Enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs.
refLinksErrorLevel (“ERROR”): When using ref or relref to resolve page links and a link cannot resolved, it will be logged with this logg level. Valid values are ERROR (default) or WARNING. Any ERROR will fail the build (exit -1).
refLinksNotFoundURL: URL to be used as a placeholder when a page reference cannot be found in ref or relref. Is used as-is.
rssLimit (unlimited): Maximum number of items in the RSS feed.
sectionPagesMenu (“”): See “Section Menu for Lazy Bloggers”.
sitemap: Default sitemap configuration.
staticDir (“static”): A directory or a list of directories from where Hugo reads static files.
stepAnalysis (false): Display memory and timing of different steps of the program.
summaryLength (70): The length of text to show in a .Summary.
taxonomies: See Configure Taxonomies.
theme (“”): Theme to use (located by default in /themes/THEMENAME/).
themesDir (“themes”): The directory where Hugo reads the themes from.
timeout (10000): Timeout for generating page contents, in milliseconds (defaults to 10 seconds). Note: this is used to bail out of recursive content generation, if your pages are slow to generate (e.g., because they require large image processing or depend on remote contents) you might need to raise this limit.
title (“”): Site title.
uglyURLs (false): When enabled, creates URL of the form /filename.html instead of /filename/.
verbose (false): Enable verbose output.
verboseLog (false): Enable verbose logging.
watch (false): Watch filesystem for changes and recreate as needed.

If you are developing your site on a *nix machine, here is a handy shortcut for finding a configuration option from the command line:

cd ~/sites/yourhugosite
hugo config | grep emoji

which shows output like

enableemoji: true

Configuration Lookup Order

Similar to the template lookup order, Hugo has a default set of rules for searching for a configuration file in the root of your website’s source directory as a default behavior:

./config.toml
./config.yaml
./config.json

In your config file, you can direct Hugo as to how you want your website rendered, control your website’s menus, and arbitrarily define site-wide parameters specific to your project.

Example Configuration

The following is a typical example of a configuration file. The values nested under params: will populate the .Site.Params variable for use in templates:

config.

baseURL: https://yoursite.example.com/
footnoteReturnLinkContents: ↩
params:
  AuthorName: Jon Doe
  GitHubUser: spf13
  ListOfFoo:
  - foo1
  - foo2
  SidebarRecentLimit: 5
  Subtitle: Hugo is Absurdly Fast!
permalinks:
  posts: /:year/:month/:title/
title: My Hugo Site

baseURL = "https://yoursite.example.com/"
footnoteReturnLinkContents = "↩"
title = "My Hugo Site"

[params]
  AuthorName = "Jon Doe"
  GitHubUser = "spf13"
  ListOfFoo = ["foo1", "foo2"]
  SidebarRecentLimit = 5
  Subtitle = "Hugo is Absurdly Fast!"

[permalinks]
  posts = "/:year/:month/:title/"

{
   "baseURL": "https://yoursite.example.com/",
   "footnoteReturnLinkContents": "↩",
   "params": {
      "AuthorName": "Jon Doe",
      "GitHubUser": "spf13",
      "ListOfFoo": [
         "foo1",
         "foo2"
      ],
      "SidebarRecentLimit": 5,
      "Subtitle": "Hugo is Absurdly Fast!"
   },
   "permalinks": {
      "posts": "/:year/:month/:title/"
   },
   "title": "My Hugo Site"
}

Configure with Environment Variables

In addition to the 3 config options already mentioned, configuration key-values can be defined through operating system environment variables.

For example, the following command will effectively set a website’s title on Unix-like systems:

$ env HUGO_TITLE="Some Title" hugo

This is really useful if you use a service such as Netlify to deploy your site. Look at the Hugo docs Netlify configuration file for an example.

Ignore Files When Rendering

The following statement inside ./config.toml will cause Hugo to ignore files ending with .foo and .boo when rendering:

ignoreFiles = [ "\\.foo$", "\\.boo$" ]

The above is a list of regular expressions. Note that the backslash (\) character is escaped in this example to keep TOML happy.

Configure Front Matter

Configure Dates

Dates are important in Hugo, and you can configure how Hugo assigns dates to your content pages. You do this by adding a frontmatter section to your config.toml.

The default configuration is:

[frontmatter]
date = ["date", "publishDate", "lastmod"]
lastmod = [":git", "lastmod", "date", "publishDate"]
publishDate = ["publishDate", "date"]
expiryDate = ["expiryDate"]

If you, as an example, have a non-standard date parameter in some of your content, you can override the setting for date:

[frontmatter]
date = ["myDate", ":default"]

The :default is a shortcut to the default settings. The above will set .Date to the date value in myDate if present, if not we will look in date,publishDate, lastmod and pick the first valid date.

In the list to the right, values starting with “:” are date handlers with a special meaning (see below). The others are just names of date parameters (case insensitive) in your front matter configuration. Also note that Hugo have some built-in aliases to the above: lastmod => modified, publishDate => pubdate, published and expiryDate => unpublishdate. With that, as an example, using pubDate as a date in front matter, will, by default, be assigned to .PublishDate.

The special date handlers are:

:fileModTime: Fetches the date from the content file’s last modification timestamp.

An example:

[frontmatter]
lastmod = ["lastmod", ":fileModTime", ":default"]

The above will try first to extract the value for .Lastmod starting with the lastmod front matter parameter, then the content file’s modification timestamp. The last, :default should not be needed here, but Hugo will finally look for a valid date in :git, date and then publishDate.

:filename: Fetches the date from the content file’s filename. For example, 2018-02-22-mypage.md will extract the date 2018-02-22. Also, if slug is not set, mypage will be used as the value for .Slug.

An example:

[frontmatter]
date  = [":filename", ":default"]

The above will try first to extract the value for .Date from the filename, then it will look in front matter parameters date, publishDate and lastly lastmod.

:git: This is the Git author date for the last revision of this content file. This will only be set if --enableGitInfo is set or enableGitInfo = true is set in site config.

Configure Blackfriday

Blackfriday is Hugo’s built-in Markdown rendering engine.

Hugo typically configures Blackfriday with sane default values that should fit most use cases reasonably well.

However, if you have specific needs with respect to Markdown, Hugo exposes some of its Blackfriday behavior options for you to alter. The following table lists these Hugo options, paired with the corresponding flags from Blackfriday’s source code ( html.go and markdown.go).

Blackfriday Options

taskLists: default: true
Blackfriday flag:
Purpose: false turns off GitHub-style automatic task/TODO list generation.
smartypants: default: true
Blackfriday flag: HTML_USE_SMARTYPANTS
Purpose: false disables smart punctuation substitutions, including smart quotes, smart dashes, smart fractions, etc. If true, it may be fine-tuned with the angledQuotes, fractions, smartDashes, and latexDashes flags (see below).
smartypantsQuotesNBSP: default: false
Blackfriday flag: HTML_SMARTYPANTS_QUOTES_NBSP
Purpose: true enables French style Guillemets with non-breaking space inside the quotes.
angledQuotes: default: false
Blackfriday flag: HTML_SMARTYPANTS_ANGLED_QUOTES
Purpose: true enables smart, angled double quotes. Example: “Hugo” renders to «Hugo» instead of “Hugo”.
fractions: default: true
Blackfriday flag: HTML_SMARTYPANTS_FRACTIONS
Purpose: false disables smart fractions.
Example: 5/12 renders to ⁵⁄₁₂(<sup>5</sup>&frasl;<sub>12</sub>).
Caveat: Even with fractions = false, Blackfriday still converts 1/2, 1/4, and 3/4 respectively to ½ (½), ¼ (¼) and ¾ (¾), but only these three.
smartDashes: default: true
Blackfriday flag: HTML_SMARTY_DASHES
Purpose: false disables smart dashes; i.e., the conversion of multiple hyphens into an en-dash or em-dash. If true, its behavior can be modified with the latexDashes flag below.
latexDashes: default: true
Blackfriday flag: HTML_SMARTYPANTS_LATEX_DASHES
Purpose: false disables LaTeX-style smart dashes and selects conventional smart dashes. Assuming smartDashes:
If true, -- is translated into – (–), whereas --- is translated into — (—).
However, spaced single hyphen between two words is translated into an en dash— e.g., “12 June - 3 July” becomes 12 June – 3 July upon rendering.
hrefTargetBlank: default: false
Blackfriday flag: HTML_HREF_TARGET_BLANK
Purpose: true opens ~~external links~~ absolute links in a new window or tab. While the target="_blank" attribute is typically used for external links, Blackfriday does that for all absolute links (ref). One needs to make note of this if they use absolute links throughout, for internal links too (for example, by setting canonifyURLs to true or via absURL).
nofollowLinks: default: false
Blackfriday flag: HTML_NOFOLLOW_LINKS
Purpose: true creates ~~external links~~ absolute links with nofollow being added to their rel attribute. Thereby crawlers are advised to not follow the link. While the rel="nofollow" attribute is typically used for external links, Blackfriday does that for all absolute links. One needs to make note of this if they use absolute links throughout, for internal links too (for example, by setting canonifyURLs to true or via absURL).
noreferrerLinks: default: false
Blackfriday flag: HTML_NOREFERRER_LINKS
Purpose: true creates ~~external links~~ absolute links with noreferrer being added to their rel attribute. Thus when following the link no referrer information will be leaked. While the rel="noreferrer" attribute is typically used for external links, Blackfriday does that for all absolute links. One needs to make note of this if they use absolute links throughout, for internal links too (for example, by setting canonifyURLs to true or via absURL).
plainIDAnchors: default true
Blackfriday flag: FootnoteAnchorPrefix and HeaderIDSuffix
Purpose: true renders any heading and footnote IDs without the document ID.
Example: renders #my-heading instead of #my-heading:bec3ed8ba720b970
extensions: default: []
Purpose: Enable one or more Blackfriday’s Markdown extensions (EXTENSION_*).
Example: Include hardLineBreak in the list to enable Blackfriday’s EXTENSION_HARD_LINE_BREAK.
See Blackfriday extensions section for information on all extensions.
extensionsmask: default: []
Purpose: Disable one or more of Blackfriday’s Markdown extensions (EXTENSION_*).
Example: Include autoHeaderIds as false in the list to disable Blackfriday’s EXTENSION_AUTO_HEADER_IDS.
See Blackfriday extensions section for information on all extensions.

Blackfriday extensions

noIntraEmphasis

default: enabled
Purpose: The “_” character is commonly used inside words when discussing code, so having Markdown interpret it as an emphasis command is usually the wrong thing. When enabled, Blackfriday lets you treat all emphasis markers as normal characters when they occur inside a word.

tables

default: enabled
Purpose: When enabled, tables can be created by drawing them in the input using the below syntax: Example:

   Name | Age
--------|------
    Bob | 27
  Alice | 23

fencedCode

default: enabled
Purpose: When enabled, in addition to the normal 4-space indentation to mark code blocks, you can explicitly mark them and supply a language (to make syntax highlighting simple).

You can use 3 or more backticks to mark the beginning of the block, and the same number to mark the end of the block.

Example:

 ```md
# Heading Level 1
Some test
## Heading Level 2
Some more test
```

autolink

default: enabled
Purpose: When enabled, URLs that have not been explicitly marked as links will be converted into links.

strikethrough

default: enabled
Purpose: When enabled, text wrapped with two tildes will be crossed out.
Example: ~~crossed-out~~

laxHtmlBlocks

default: disabled
Purpose: When enabled, loosen up HTML block parsing rules.

spaceHeaders

default: enabled
Purpose: When enabled, be strict about prefix header rules.

hardLineBreak

default: disabled
Purpose: When enabled, newlines in the input translate into line breaks in the output.

tabSizeEight

default: disabled
Purpose: When enabled, expand tabs to eight spaces instead of four.

footnotes

default: enabled
Purpose: When enabled, Pandoc-style footnotes will be supported. The footnote marker in the text that will become a superscript text; the footnote definition will be placed in a list of footnotes at the end of the document.
Example:

This is a footnote.[^1]

[^1]: the footnote text.

noEmptyLineBeforeBlock

default: disabled
Purpose: When enabled, no need to insert an empty line to start a (code, quote, ordered list, unordered list) block.

headerIds

default: enabled
Purpose: When enabled, allow specifying header IDs with {#id}.

titleblock

default: disabled
Purpose: When enabled, support Pandoc-style title blocks.

autoHeaderIds

default: enabled
Purpose: When enabled, auto-create the header ID’s from the headline text.

backslashLineBreak

default: enabled
Purpose: When enabled, translate trailing backslashes into line breaks.

definitionLists

default: enabled
Purpose: When enabled, a simple definition list is made of a single-line term followed by a colon and the definition for that term.
Example:

Cat
: Fluffy animal everyone likes

Internet
: Vector of transmission for pictures of cats

Terms must be separated from the previous definition by a blank line.

joinLines

default: enabled
Purpose: When enabled, delete newlines and join the lines.

config.

blackfriday:
  angledQuotes: true
  extensions:
  - hardLineBreak
  fractions: false
  plainIDAnchors: true

[blackfriday]
  angledQuotes = true
  extensions = ["hardLineBreak"]
  fractions = false
  plainIDAnchors = true

{
   "blackfriday": {
      "angledQuotes": true,
      "extensions": [
         "hardLineBreak"
      ],
      "fractions": false,
      "plainIDAnchors": true
   }
}

Configure Additional Output Formats

Hugo v0.20 introduced the ability to render your content to multiple output formats (e.g., to JSON, AMP html, or CSV). See Output Formats for information on how to add these values to your Hugo project’s configuration file.

Configure File Caches

Since Hugo 0.52 you can configure more than just the cacheDir. This is the default configuration:

[caches]
[caches.getjson]
dir = ":cacheDir/:project"
maxAge = -1
[caches.getcsv]
dir = ":cacheDir/:project"
maxAge = -1
[caches.images]
dir = ":resourceDir/_gen"
maxAge = -1
[caches.assets]
dir = ":resourceDir/_gen"
maxAge = -1

You can override any of these cache setting in your own config.toml.

The keywords explained

:cacheDir: This is the value of the cacheDir config option if set (can also be set via OS env variable HUGO_CACHEDIR). It will fall back to /opt/build/cache/hugo_cache/ on Netlify, or a hugo_cache directory below the OS temp dir for the others. This means that if you run your builds on Netlify, all caches configured with :cacheDir will be saved and restored on the next build. For other CI vendors, please read their documentation. For an CircleCI example, see this configuration.
:project: The base directory name of the current Hugo project. This means that, in its default setting, every project will have separated file caches, which means that when you do hugo --gc you will not touch files related to other Hugo projects running on the same PC.
:resourceDir: This is the value of the resourceDir config option.
maxAge: This is the duration before a cache entry will be evicted, -1 means forever and 0 effectively turns that particular cache off. Uses Go’s time.Duration, so valid values are "10s" (10 seconds), "10m" (10 minutes) and "10h" (10 hours).
dir: The absolute path to where the files for this cache will be stored. Allowed starting placeholders are :cacheDir and :resourceDir (see above).

Configure Hugo

Configuration File

Configuration Directory

All Configuration Settings

Configuration Lookup Order

Example Configuration

Configure with Environment Variables

Ignore Files When Rendering

Configure Front Matter

Configure Dates

Configure Blackfriday

Blackfriday Options

Blackfriday extensions

Configure Additional Output Formats

Configure File Caches

The keywords explained

Configuration Format Specs

See Also

“Configure Hugo” was last updated: January 29, 2019: A little bit of naming reorganisation (8fb631a0)