HUGO

  • News
  • Docs
  • Themes
  • Showcase
  • Community
  • GitHub
gohugoio Star
  • About Hugo
    • Overview
    • What is Hugo
    • Hugo features
    • Static site generators
    • Hugo's security model
    • Hugo and the GDPR
    • License
  • Installation
    • Overview
    • macOS
    • Linux
    • Windows
    • BSD
  • Getting started
    • Overview
    • Quick start
    • Basic usage
    • Directory structure
    • Configuration
    • Configure markup
    • Glossary of terms
    • External learning resources
  • Content management
    • Overview
    • Organization
    • Page bundles
    • Content formats
    • Diagrams
    • Front matter
    • Build options
    • Page resources
    • Image processing
    • Shortcodes
    • Related content
    • Sections
    • Content types
    • Archetypes
    • Taxonomies
    • Summaries
    • Links and cross references
    • URL management
    • Menus
    • Static files
    • Table of contents
    • Comments
    • Multilingual
    • Syntax highlighting
  • Templates
    • Overview
    • Templating
    • Template lookup order
    • Base templates and blocks
    • Single page templates
    • List templates
    • Homepage template
    • Section templates
    • Taxonomy templates
    • Pagination
    • Content view templates
    • Partial templates
    • Shortcode templates
    • Menu templates
    • Data templates
    • RSS templates
    • Sitemap templates
    • Local file templates
    • Internal templates
    • Render hooks
    • Custom output formats
    • 404 page
    • Robots.txt
  • Functions
    • Overview
    • cast
    • collections
    • compare
    • crypto
    • data
    • debug
    • diagrams
    • encoding
    • fmt
    • global
    • go template
    • hugo
    • images
    • inflect
    • js
    • lang
    • math
    • openapi3
    • os
    • partials
    • path
    • reflect
    • resources
    • safe
    • strings
    • templates
    • time
    • transform
    • urls
  • Methods
    • Overview
    • Duration
    • Menu
    • Menu entry
    • Page
    • Pages
    • Resource
    • Shortcode
    • Site
    • Taxonomy
    • Time
  • Quick reference
    • Overview
    • Emojis
    • Functions
    • Methods
    • Page collections
  • Variables
    • Overview
    • File variables
    • Git variables
    • Menu entry variables
    • Page variables
    • Pages variables
    • Shortcode variables
    • Site variables
    • Taxonomy variables
  • Hugo Modules
    • Overview
    • Configure Hugo modules
    • Use Hugo Modules
    • Theme components
  • Hugo Pipes
    • Overview
    • Introduction
    • Transpile Sass to CSS
    • PostCSS
    • PostProcess
    • JavaScript building
    • Babel
    • Asset minification
    • Concatenating assets
    • Fingerprinting and SRI hashing
    • Resource from string
    • Resource from template
  • CLI
  • Troubleshooting
    • Overview
    • Audit
    • Logging
    • Inspection
    • Deprecation
    • Performance
    • FAQs
  • Developer tools
    • Overview
    • Editor plugins
    • Front-ends
    • Search
    • Migrations
    • Other projects
  • Hosting and deployment
    • Overview
    • Hugo Deploy
    • Deploy with Rclone
    • Deploy with Rsync
    • Host on 21YunBox
    • Host on AWS Amplify
    • Host on Azure Static Web Apps
    • Host on Cloudflare Pages
    • Host on Firebase
    • Host on GitHub Pages
    • Host on GitLab Pages
    • Host on KeyCDN
    • Host on Netlify
    • Host on Render
  • Contribute
    • Overview
    • Development
    • Documentation
    • Themes
  • Maintenance
TROUBLESHOOTING

Frequently asked questions

These questions are frequently asked by new users.

Hugo’s forum is an active community of users and developers who answer questions, share knowledge, and provide examples. A quick search of over 20,000 topics will often answer your question. Please be sure to read about requesting help before asking your first question.

These are just a few of the questions most frequently asked by new users.

An error message indicates that a feature is not available. Why?

Hugo is available in two editions: standard and extended. With the extended edition you can (a) encode to the WebP format when processing images, and (b) transpile Sass to CSS using the embedded LibSass transpiler. The extended edition is not required to use the Dart Sass transpiler.

When you attempt to perform either of the operations above with the standard edition, Hugo throws this error:

Error: this feature is not available in your current Hugo version

To resolve, uninstall the standard edition, then install the extended edition. See the installation section for details.

Why do I see “Page Not Found” when visiting the home page?

In the content/_index.md file:

  • Is draft set to true?
  • Is the date in the future?
  • Is the publishDate in the future?
  • Is the expiryDate in the past?

If the answer to any of these questions is yes, either change the field values, or use one of these command line flags: --buildDrafts, --buildFuture, or --buildExpired.

Why is a given section not published?

In the content/section/_index.md file:

  • Is draft set to true?
  • Is the date in the future?
  • Is the publishDate in the future?
  • Is the expiryDate in the past?

If the answer to any of these questions is yes, either change the field values, or use one of these command line flags: --buildDrafts, --buildFuture, or --buildExpired.

Why is a given page not published?

In the content/section/page.md file, or in the content/section/page/index.md file:

  • Is draft set to true?
  • Is the date in the future?
  • Is the publishDate in the future?
  • Is the expiryDate in the past?

If the answer to any of these questions is yes, either change the field values, or use one of these command line flags: --buildDrafts, --buildFuture, or --buildExpired.

Why can’t I see any of a page’s descendants?

You may have an index.md file instead of an _index.md file. See details.

What is the difference between an index.md file and an _index.md file?

A directory with an index.md file is a leaf bundle. A directory with an _index.md file is a branch bundle. See details.

Why is my partial template not rendered as expected?

You may have neglected to pass the required context when calling the partial. For example:

{{/* incorrect */}}
{{ partial "_internal/pagination.html" }}

{{/* correct */}}
{{ partial "_internal/pagination.html" . }}
In a template, what’s the difference between := and = when assigning values to variables?

Use := to initialize a variable, and use = to assign a value to a variable that has been previously initialized. See details.

When I paginate a list page, why is the page collection not filtered as specified?

You are probably invoking the Paginate or Paginator method more than once on the same page. See details.

Why are there two ways to call a shortcode?

Use the {{% shortcode %}} notation if the shortcode template, or the content between the opening and closing shortcode tags, contains markdown. Otherwise use the
{{< shortcode >}} notation. See details.

Can I use environment variables to control configuration?

Yes. See details.

Why am I seeing inconsistent output from one build to the next?

The most common causes are page collisions (publishing two pages to the same path) and the effects of concurrency. Use the --printPathWarnings command line flag to check for page collisions, and create a topic on the forum if you suspect concurrency problems.

Which page methods trigger content rendering?

The following methods on a Page object triggering content rendering: Content, FuzzyWordCount, Len, Plain, PlainWords, ReadingTime, Summary, Truncated, and WordCount.

For other questions please visit the forum. A quick search of over 20,000 topics will often answer your question. Please be sure to read about requesting help before asking your first question.

Last updated: November 26, 2023: Misc additions (740f5ef9)
Improve this page
By the Hugo Authors
Hugo Logo
  • File an Issue
  • Get Help
  • @GoHugoIO
  • @spf13
  • @bepsays

Netlify badge

 

Hugo Sponsors

 

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

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

  • News
  • Docs
  • Themes
  • Showcase
  • Community
  • GitHub
  • About Hugo
  • Installation
  • Getting started
  • Content management
  • Templates
  • Functions
  • Methods
  • Quick reference
  • Variables
  • Hugo Modules
  • Hugo Pipes
  • CLI
  • Troubleshooting
  • Developer tools
  • Hosting and deployment
  • Contribute
  • Maintenance