HUGO

  • News
  • Docs
  • Themes
  • Community
  • GitHub
Star

What's on this Page

    • Configuration Lookup Order
    • YAML Configuration
      • All Variables, YAML
    • TOML Configuration
      • All Variables, TOML
    • Environmental Variables
    • Ignore Files When Rendering
    • Configure Blackfriday
    • Configure Additional Output Formats
    • Configuration Format Specs
GETTING STARTED FUNDAMENTALS

Configure Hugo

Often the default settings are good enough, but the config file can provide highly granular control over how your site is rendered.

The directory structure of a Hugo website—or more precisely, the source organization of files containing the website’s content and templates—provides most of the configuration information that Hugo needs in order to generate a finished website.

Because of Hugo’s sensible defaults, many websites may not need a configuration file. Hugo is designed to recognize certain typical usage patterns.

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:

  1. ./config.toml
  2. ./config.yaml
  3. ./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.

YAML Configuration

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

config.yml

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

All Variables, YAML

The following is the full list of Hugo-defined variables in an example YAML file. The values provided in this example represent the default values used by Hugo.

config.yml

archetypeDir:               "archetypes"
# hostname (and path) to the root, e.g. http://spf13.com/
baseURL:                    ""
# include content marked as draft
buildDrafts:                false
# include content with publishdate in the future
buildFuture:                false
# include content already expired
buildExpired:               false
# enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs. See the "URL Management" page
relativeURLs:               false
canonifyURLs:               false
# config file (default is path/config.yaml|json|toml)
config:                     "config.toml"
contentDir:                 "content"
dataDir:                    "data"
defaultExtension:           "html"
defaultLayout:              "post"
# Missing translations will default to this content language
defaultContentLanguage:     "en"
# Renders the default content language in subdir, e.g. /en/. The root directory / will redirect to /en/
defaultContentLanguageInSubdir: false
disableLiveReload:          false
# Do not build RSS files
disableRSS:                 false
# Do not build Sitemap file
disableSitemap:             false
# Enable GitInfo feature
enableGitInfo:              false
# Build robots.txt file
enableRobotsTXT:            false
# Do not render 404 page
disable404:                 false
# Do not inject generator meta tag on homepage
disableHugoGeneratorInject: false
# Allows you to disable all page types and will render nothing related to 'kind';
# values = "page", "home", "section", "taxonomy", "taxonomyTerm", "RSS", "sitemap", "robotsTXT", "404"
disableKinds: []
# Do not make the url/path to lowercase
disablePathToLower:         false                   ""
# Enable Emoji emoticons support for page content; see emoji-cheat-sheet.com
enableEmoji:                false
# Show a placeholder instead of the default value or an empty string if a translation is missing
enableMissingTranslationPlaceholders: false
footnoteAnchorPrefix:       ""
footnoteReturnLinkContents: ""
# google analytics tracking id
googleAnalytics:            ""
# if true, auto-detect Chinese/Japanese/Korean Languages in the content. (.Summary and .WordCount can work properly in CJKLanguage)
hasCJKLanguage:             false
languageCode:               ""
layoutDir:                  "layouts"
# Enable Logging
log:                        false
# Log File path (if set, logging enabled automatically)
logFile:                    ""
# "toml","yaml", or "json"
metaDataFormat:             "toml"
newContentEditor:           ""
# Don't sync permission mode of files
noChmod:                    false
# Don't sync modification time of files
noTimes:                    false
# Pagination
paginate:                   10
paginatePath:               "page"
# See "content-management/permalinks"
permalinks:
# Pluralize titles in lists using inflect
pluralizeListTitles:        true
# Preserve special characters in taxonomy names ("Gérard Depardieu" vs "Gerard Depardieu")
preserveTaxonomyNames:      false
# filesystem path to write files to
publishDir:                 "public"
# enables syntax guessing for code fences without specified language
pygmentsCodeFencesGuessSyntax: false
# color-codes for highlighting derived from this style
pygmentsStyle:              "monokai"
# true use pygments-css or false will color code directly
pygmentsUseClasses:         false
# maximum number of items in the RSS feed
rssLimit:                   15
# see "Section Menu for Lazy Bloggers", /templates/menu-templates for more info
SectionPagesMenu:           ""
# default sitemap configuration map
sitemap:
# filesystem path to read files relative from
source:                     ""
staticDir:                  "static"
# display memory and timing of different steps of the program
stepAnalysis:               false
# display metrics about template executions
templateMetrics:            false
# theme to use (located by default in /themes/THEMENAME/)
themesDir:                  "themes"
theme:                      ""
title:                      ""
# Title Case style guide for the title func and other automatic title casing in Hugo.
// Valid values are "AP" (default), "Chicago" and "Go" (which was what you had in Hugo <= 0.25.1).
// See https://www.apstylebook.com/ and http://www.chicagomanualofstyle.org/home.html
titleCaseStyle:             "AP"
# if true, use /filename.html instead of /filename/
uglyURLs:                   false
# verbose output
verbose:                    false
# verbose logging
verboseLog:                 false
# watch filesystem for changes and recreate as needed
watch:                      true
taxonomies:
  - category:               "categories"
  - tag:                    "tags"

TOML Configuration

The following is an example of a TOML configuration file. The values under [params] will populate the .Site.Params variable for use in templates:

config.toml

contentDir = "content"
layoutDir = "layouts"
publishDir = "public"
buildDrafts = false
baseURL = "https://yoursite.example.com/"
canonifyURLs = true
title = "My Hugo Site"

[taxonomies]
  category = "categories"
  tag = "tags"

[params]
  subtitle = "Hugo is Absurdly Fast!"
  author = "John Doe"

All Variables, TOML

The following is the full list of Hugo-defined variables in an example TOML file. The values provided in this example represent the default values used by Hugo.

config.toml

archetypeDir =                "archetypes"
# hostname (and path) to the root, e.g. http://spf13.com/
baseURL =                     ""
# include content marked as draft
buildDrafts =                 false
# include content with publishdate in the future
buildFuture =                 false
# include content already expired
buildExpired =                false
# enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs.
relativeURLs =                false
canonifyURLs =                false
# config file (default is path/config.yaml|json|toml)
config =                     "config.toml"
contentDir =                  "content"
dataDir =                     "data"
defaultExtension =            "html"
defaultLayout =               "post"
# Missing translations will default to this content language
defaultContentLanguage =      "en"
# Renders the default content language in subdir, e.g. /en/. The root directory / will redirect to /en/
defaultContentLanguageInSubdir =  false
disableLiveReload =           false
# Do not build RSS files
disableRSS =                  false
# Do not build Sitemap file
disableSitemap =              false
# Enable GitInfo feature
enableGitInfo =               false
# Build robots.txt file
enableRobotsTXT =             false
# Do not render 404 page
disable404 =                  false
# Do not inject generator meta tag on homepage
disableHugoGeneratorInject =  false
# Allows you to disable all page types and will render nothing related to 'kind';
# values = "page", "home", "section", "taxonomy", "taxonomyTerm", "RSS", "sitemap", "robotsTXT", "404"
disableKinds = []
# Do not make the url/path to lowercase
disablePathToLower =          false
# Enable Emoji emoticons support for page content; see emoji-cheat-sheet.com
enableEmoji =                 false
# Show a placeholder instead of the default value or an empty string if a translation is missing
enableMissingTranslationPlaceholders = false
footnoteAnchorPrefix =        ""
footnoteReturnLinkContents =  ""
# google analytics tracking id
googleAnalytics =             ""
# if true, auto-detect Chinese/Japanese/Korean Languages in the content. (.Summary and .WordCount can work properly in CJKLanguage)
hasCJKLanguage =              false
languageCode =                ""
layoutDir =                   "layouts"
# Enable Logging
log =                         false
# Log File path (if set, logging enabled automatically)
logFile =
# maximum number of items in the RSS feed
rssLimit =                    15
# "toml","yaml", or "json"
metaDataFormat =              "toml"
newContentEditor =            ""
# Don't sync permission mode of files
noChmod =                     false
# Don't sync modification time of files
noTimes =                     false
# Pagination
paginate =                    10
paginatePath =                "page"
# See "content-management/permalinks"
permalinks =
# Pluralize titles in lists using inflect
pluralizeListTitles =         true
# Preserve special characters in taxonomy names ("Gérard Depardieu" vs "Gerard Depardieu")
preserveTaxonomyNames =       false
# filesystem path to write files to
publishDir =                  "public"
# enables syntax guessing for code fences without specified language
pygmentsCodeFencesGuessSyntax = false
# color-codes for highlighting derived from this style
pygmentsStyle =               "monokai"
# true: use pygments-css or false: color-codes directly
pygmentsUseClasses =          false
# see "Section Menu for Lazy Bloggers", /templates/menu-templates for more info
SectionPagesMenu =
# default sitemap configuration map
sitemap =
# filesystem path to read files relative from
source =                      ""
staticDir =                   "static"
# display memory and timing of different steps of the program
stepAnalysis =                false
# theme to use (located by default in /themes/THEMENAME/)
themesDir =                   "themes"
theme =                       ""
title =                       ""
# if true, use /filename.html instead of /filename/
uglyURLs =                    false
# verbose output
verbose =                     false
# verbose logging
verboseLog =                  false
# watch filesystem for changes and recreate as needed
watch =                       true
[taxonomies]
  category = "categories"
  tag = "tags"

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

Environmental 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

Names must be prefixed with HUGO_ and the configuration key must be set in uppercase when setting operating system environment variables.

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 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 5⁄12(<sup>5</sup>&frasl;<sub>12</sub>).
Caveat: Even with fractions = false, Blackfriday still converts 1/2, 1/4, and 3/4 respectively to ½ (&frac12;), ¼ (&frac14;) and ¾ (&frac34;), 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 – (&ndash;), whereas --- is translated into — (&mdash;).
However, spaced single hyphen between two words is translated into an en dash— e.g., “12 June - 3 July” becomes 12 June &ndash; 3 July upon rendering.
hrefTargetBlank
default: false
Blackfriday flag: HTML_HREF_TARGET_BLANK
Purpose: true opens external links in a new window or tab.
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: []
Blackfriday flag: EXTENSION_*
Purpose: Enable one or more Blackfriday’s Markdown extensions (if they aren’t Hugo defaults).
Example: Include hardLineBreak in the list to enable Blackfriday’s EXTENSION_HARD_LINK_BREAK.
See Blackfriday extensions section for more information.
extensionsmask
default: []
Blackfriday flag: EXTENSION_*
Purpose: Enable one or more of Blackfriday’s Markdown extensions (if they aren’t Hugo defaults).
Example: Include autoHeaderIds as false in the list to disable Blackfriday’s EXTENSION_AUTO_HEADER_IDS.
See Blackfriday extensions section for more information.

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.

  1. Blackfriday flags are case sensitive as of Hugo v0.15.
  2. Blackfriday flags must be grouped under the blackfriday key and can be set on both the site level and the page level. Any setting on a page will override its respective site setting.

bf-config.toml

[blackfriday]
  angledQuotes = true
  fractions = false
  plainIDAnchors = true
  extensions = ["hardLineBreak"]
bf-config.yml

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

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.

Configuration Format Specs

  • TOML Spec
  • YAML Spec
  • JSON Spec

See Also

  • Data Templates
  • Front Matter
  • jsonify
  • About Hugo
    • Overview
    • Hugo Features
    • The Benefits of Static
    • Roadmap
    • License
  • Getting Started
    • Get Started Overview
    • Quick Start
    • Install Hugo
    • Basic Usage
    • Directory Structure
    • Configuration
  • Themes
    • Themes Overview
    • Install and Use Themes
    • Customize a Theme
    • Create a Theme
  • Content Management
    • Content Management Overview
    • Organization
    • Supported Content Formats
    • Front Matter
    • Shortcodes
    • Related Content
    • Sections
    • Types
    • Archetypes
    • Taxonomies
    • Summaries
    • Links and Cross References
    • URL Management
    • Menus
    • Table of Contents
    • Comments
    • Multilingual and i18n
    • Syntax Highlighting
  • Templates
    • Templates Overview
    • Introduction
    • Template Lookup Order
    • Custom Output Formats
    • Base Templates and Blocks
    • List Page Templates
    • Homepage Template
    • Section Templates
    • Taxonomy Templates
    • Single Page Templates
    • Content View Templates
    • Data Templates
    • Partial Templates
    • Shortcode Templates
    • Local File Templates
    • 404 Page
    • Menu Templates
    • Pagination
    • RSS Templates
    • Sitemap Template
    • Robots.txt
    • Internal Templates
    • Alternative Templating
    • Template Debugging
  • Functions
    • Functions Quick Reference
    • .AddDate
    • .Format
    • .Get
    • .GetPage
    • .Param
    • .Scratch
    • .Unix
    • Math
    • absLangURL
    • absURL
    • after
    • apply
    • base64
    • chomp
    • countrunes
    • countwords
    • dateFormat
    • default
    • delimit
    • dict
    • echoParam
    • emojify
    • eq
    • findRE
    • first
    • ge
    • getenv
    • gt
    • hasPrefix
    • highlight
    • htmlEscape
    • htmlUnescape
    • humanize
    • i18n
    • imageConfig
    • in
    • index
    • int
    • intersect
    • isset
    • jsonify
    • lang.NumFmt
    • last
    • le
    • lower
    • lt
    • markdownify
    • md5
    • ne
    • now
    • partialCached
    • plainify
    • pluralize
    • print
    • printf
    • println
    • querify
    • range
    • readDir
    • readFile
    • ref
    • relLangURL
    • relURL
    • relref
    • render
    • replace
    • replaceRE
    • safeCSS
    • safeHTML
    • safeHTMLAttr
    • safeJS
    • safeURL
    • seq
    • sha
    • shuffle
    • singularize
    • slice
    • slicestr
    • sort
    • split
    • string
    • strings.TrimLeft
    • strings.TrimPrefix
    • strings.TrimRight
    • strings.TrimSuffix
    • substr
    • time
    • title
    • trim
    • truncate
    • union
    • uniq
    • upper
    • urlize
    • urls.Parse
    • where
    • with
  • Variables
    • Variables Overview
    • Site Variables
    • Page Variables
    • Shortcode Variables
    • Taxonomy Variables
    • File Variables
    • Menu Variables
    • Hugo Variables
    • Git Variables
    • Sitemap Variables
  • CLI
  • Troubleshooting
    • Troubleshoot
    • Accented Characters in URLs
    • Build Performance
    • EOF Error
  • Tools
    • Developer Tools Overview
    • Migrations
    • Starter Kits
    • Frontends
    • Editor Plug-ins
    • Search
    • Other Projects
  • Hosting & Deployment
    • Hosting & Deployment Overview
    • Host-Agnostic Deploys with Nanobox
    • Host on Netlify
    • Host on Firebase
    • Host on GitHub
    • Host on GitLab
    • Host on Bitbucket
    • Deployment with Wercker
    • Deployment with Rsync
  • Contribute
    • Contribute to Hugo
    • Development
    • Documentation
    • Themes
“Configure Hugo” was last updated: October 13, 2017: Initial commit (a48229f)
Improve this page
By the Hugo Authors

The Hugo logos are copyright © Steve Francia 2013–2017.

The Hugo Gopher is based on an original work by Renée French.

  • File an Issue
  • Get Help
  • Discuss the Source Code
  • @GoHugoIO
  • @spf13
  • @bepsays
  • News
  • Docs
  • Themes
  • Community
  • GitHub
  • About Hugo
  • Getting Started
  • Themes
  • Content Management
  • Templates
  • Functions
  • Variables
  • CLI
  • Troubleshooting
  • Tools
  • Hosting & Deployment
  • Contribute