Frequently asked questions
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 three editions: standard, extended, and extended/deploy. While the standard edition provides core functionality, the extended and extended/deploy editions offer advanced features.
Feature extended edition extended/deploy edition Encode to the WebP format when processing images. You can decode WebP images with any edition. ✔️ ✔️ Transpile Sass to CSS using the embedded LibSass transpiler. You can use the Dart Sass transpiler with any edition. ✔️ ✔️ Deploy your site directly to a Google Cloud Storage bucket, an AWS S3 bucket, or an Azure Storage container. See details. ❌ ✔️ When you attempt to use a feature that is not available in the edition that you installed, Hugo throws this error:
this feature is not available in this edition of Hugo
To resolve, install a different edition based on the feature table above. 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 totrue
? - 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
. - Is
- Why is a given page not published?
- In the
content/section/page.md
file, or in thecontent/section/page/index.md
file:- Is
draft
set totrue
? - 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
. - Is
- 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
orPaginator
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. - Why isn’t Hugo’s development server detecting file changes?
- In its default configuration, Hugo’s file watcher may not be able detect file changes when:
- Running Hugo within Windows Subsystem for Linux (WSL/WSL2) with project files on a Windows partition
- Running Hugo locally with project files on a removable drive
- Running Hugo locally with project files on a storage server accessed via the NFS, SMB, or CIFS protocols
In these cases, instead of monitoring native file system events, use the
--poll
command line flag. For example, to poll the project files every 700 milliseconds, use--poll 700ms
. - Why is my page Scratch or Store missing a value?
- The
Scratch
andStore
methods on aPage
object allow you to create a scratch pad on the given page to store and manipulate data. Values are often set within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are not determinate until Hugo renders the page content.If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a noop variable:
{{ $noop := .Content }} {{ .Store.Get "mykey" }}
You can trigger content rendering with other methods as well. See next FAQ.
- Which page methods trigger content rendering?
- The following methods on a
Page
object trigger content rendering:Content
,ContentWithoutSummary
,FuzzyWordCount
,Len
,Plain
,PlainWords
,ReadingTime
,Summary
,Truncated
, andWordCount
.
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.