mirror of
https://github.com/gohugoio/hugo.git
synced 2025-08-24 21:56:05 +02:00
Merge commit '8b9803425e63e1b1801f8d5d676e96368d706722'
This commit is contained in:
Bjørn Erik Pedersen
@@ -73,15 +73,11 @@ my-project/
|
||||
│ ├── menus.en.toml
|
||||
│ ├── menus.de.toml
|
||||
│ └── params.toml
|
||||
├── production/
|
||||
│ ├── hugo.toml
|
||||
│ └── params.toml
|
||||
└── staging/
|
||||
├── hugo.toml
|
||||
└── production/
|
||||
└── params.toml
|
||||
```
|
||||
|
||||
The root configuration keys are `build`, `caches`, `cascade`, `deployment`, `frontmatter`, `imaging`, `languages`, `markup`, `mediatypes`, `menus`, `minify`, `module`, `outputformats`, `outputs`, `params`, `permalinks`, `privacy`, `related`, `security`, `server`, `services`, `sitemap`, and `taxonomies`.
|
||||
The root configuration keys are `build`, `caches`, `cascade`, `deployment`, `frontmatter`, `imaging`, `languages`, `markup`, `mediatypes`, `menus`, `minify`, `module`, `outputformats`, `outputs`, `params`, `permalinks`, `privacy`, `related`, `security`, `segments`, `server`, `services`, `sitemap`, and `taxonomies`.
|
||||
|
||||
### Omit the root key
|
||||
|
||||
@@ -226,25 +222,33 @@ See [Configure Build](#configure-build).
|
||||
|
||||
###### buildFuture
|
||||
|
||||
(`bool`) Include content with publishdate in the future. Default is `false`.
|
||||
(`bool`) Include content with a future publication date. Default is `false`.
|
||||
|
||||
###### caches
|
||||
|
||||
See [Configure File Caches](#configure-file-caches).
|
||||
|
||||
###### capitalizeListTitles
|
||||
|
||||
{{< new-in 0.123.3 >}}
|
||||
|
||||
(`bool`) Whether to capitalize automatic list titles. Applicable to section, taxonomy, and term pages. Default is `true`. You can change the capitalization style in your site configuration to one of `ap`, `chicago`, `go`, `firstupper`, or `none`. See [details].
|
||||
|
||||
[details]: /getting-started/configuration/#configure-title-case
|
||||
|
||||
###### cascade
|
||||
|
||||
Pass down down default configuration values (front matter) to pages in the content tree. The options in site config is the same as in page front matter, see [Front Matter Cascade](/content-management/front-matter#front-matter-cascade).
|
||||
Pass down default configuration values (front matter) to pages in the content tree. The options in site config is the same as in page front matter, see [Front Matter Cascade](/content-management/front-matter#cascade).
|
||||
|
||||
{{% note %}}
|
||||
For a website in a single language, define the `[[cascade]]` in [Front Matter](/content-management/front-matter#front-matter-cascade). For a multilingual website, define the `[[cascade]]` in [Site Config](../../getting-started/configuration/#cascade).
|
||||
For a website in a single language, define the `[[cascade]]` in [Front Matter](/content-management/front-matter#cascade). For a multilingual website, define the `[[cascade]]` in [Site Config](/getting-started/configuration/#cascade).
|
||||
|
||||
To remain consistent and prevent unexpected behavior, do not mix these strategies.
|
||||
{{% /note %}}
|
||||
|
||||
###### canonifyURLs
|
||||
|
||||
(`bool`) Enable to turn relative URLs into absolute. Default is `false`. See [details](/content-management/urls/#canonical-urls).
|
||||
(`bool`) See [details](/content-management/urls/#canonical-urls) before enabling this feature. Default is `false`.
|
||||
|
||||
###### cleanDestinationDir
|
||||
|
||||
@@ -324,8 +328,11 @@ See [image processing configuration](/content-management/image-processing/#imagi
|
||||
|
||||
(`string`) A language tag as defined by [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646). This value is used to populate:
|
||||
|
||||
- The `<language>` element in the internal [RSS template](https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/rss.xml)
|
||||
- The `lang` attribute of the `<html>` element in the internal [alias template](https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/alias.html)
|
||||
- The `<language>` element in the embedded [RSS template]({{% eturl rss %}})
|
||||
- The `lang` attribute of the `<html>` element in the embedded [alias template]({{% eturl alias %}})
|
||||
- The `og:locale` `meta` element in the embedded [Open Graph template]({{% eturl opengraph %}})
|
||||
|
||||
When present in the root of the configuration, this value is ignored if one or more language keys exists. Please specify this value independently for each language key.
|
||||
|
||||
###### languages
|
||||
|
||||
@@ -369,7 +376,7 @@ Module configuration see [module configuration](/hugo-modules/configuration/).
|
||||
|
||||
###### outputFormats
|
||||
|
||||
See [Configure Output Formats](#configure-additional-output-formats).
|
||||
See [custom output formats].
|
||||
|
||||
###### paginate
|
||||
|
||||
@@ -385,20 +392,12 @@ See [Content Management](/content-management/urls/#permalinks).
|
||||
|
||||
###### pluralizeListTitles
|
||||
|
||||
(`bool`) Pluralize titles in lists. Default is `true`.
|
||||
(`bool`) Whether to pluralize automatic list titles. Applicable to section pages. Default is `true`.
|
||||
|
||||
###### publishDir
|
||||
|
||||
(`string`) The directory to where Hugo will write the final static site (the HTML files etc.). Default is `public`.
|
||||
|
||||
###### related
|
||||
|
||||
See [Related Content](/content-management/related/#configure-related-content).
|
||||
|
||||
###### relativeURLs
|
||||
|
||||
(`bool`) Enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs. Default is `false`. See [details](/content-management/urls/#relative-urls).
|
||||
|
||||
###### refLinksErrorLevel
|
||||
|
||||
(`string`) When using `ref` or `relref` to resolve page links and a link cannot be resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`). Default is `ERROR`.
|
||||
@@ -407,6 +406,20 @@ See [Related Content](/content-management/related/#configure-related-content).
|
||||
|
||||
(`string`) URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is.
|
||||
|
||||
###### related
|
||||
|
||||
See [Related Content](/content-management/related/#configure-related-content).
|
||||
|
||||
###### relativeURLs
|
||||
|
||||
(`bool`) See [details](/content-management/urls/#relative-urls) before enabling this feature. Default is `false`.
|
||||
|
||||
###### renderSegments
|
||||
|
||||
{{< new-in 0.124.0 >}}
|
||||
|
||||
(`string slice`) A list of segments to render. If not set, everything will be rendered. This is more commonly set in a CLI flag, e.g. `hugo --renderSegments segment1,segment2`. The segment names must match the names in the [segments](#configure-segments) configuration.
|
||||
|
||||
###### removePathAccents
|
||||
|
||||
(`bool`) Removes [non-spacing marks](https://www.compart.com/en/unicode/category/Mn) from [composite characters](https://en.wikipedia.org/wiki/Precomposed_character) in content paths. Default is `false`.
|
||||
@@ -421,7 +434,11 @@ See [Menus](/content-management/menus/#define-automatically).
|
||||
|
||||
###### security
|
||||
|
||||
See [Security Policy](/about/security-model/#security-policy).
|
||||
See [Security Policy](/about/security/#security-policy).
|
||||
|
||||
###### segments
|
||||
|
||||
See [Segments](#configure-segments).
|
||||
|
||||
###### sitemap
|
||||
|
||||
@@ -429,7 +446,9 @@ Default [sitemap configuration](/templates/sitemap-template/#configuration).
|
||||
|
||||
###### summaryLength
|
||||
|
||||
(`int`) The length of text in words to show in a [`.Summary`](/content-management/summaries/#automatic-summary-splitting). Default is `70`.
|
||||
(`int`) Applicable to automatic summaries, the approximate number of words to render when calling the [`Summary`] method on a `Page` object. Default is `70`.
|
||||
|
||||
[`Summary`]: /methods/page/summary/
|
||||
|
||||
###### taxonomies
|
||||
|
||||
@@ -605,6 +624,39 @@ to = "/404.html"
|
||||
status = 404
|
||||
{{< /code-toggle >}}
|
||||
|
||||
With a multilingual site, define the redirect for the default content language last:
|
||||
|
||||
{{< code-toggle file=config/development/server >}}
|
||||
defaultContentLanguage = 'en'
|
||||
defaultContentLanguageInSubdir = false
|
||||
[[redirects]]
|
||||
from = '/fr/**'
|
||||
to = '/fr/404.html'
|
||||
status = 404
|
||||
|
||||
[[redirects]] # Default language must be last.
|
||||
from = '/**'
|
||||
to = '/404.html'
|
||||
status = 404
|
||||
{{< /code-toggle >}}
|
||||
|
||||
If you are serving the default content language from a subdirectory:
|
||||
|
||||
{{< code-toggle file=config/development/server >}}
|
||||
defaultContentLanguage = 'en'
|
||||
defaultContentLanguageInSubdir = true
|
||||
[[redirects]]
|
||||
from = '/fr/**'
|
||||
to = '/fr/404.html'
|
||||
status = 404
|
||||
|
||||
[[redirects]] # Default language must be last.
|
||||
from = '/**'
|
||||
to = '/en/404.html'
|
||||
status = 404
|
||||
{{< /code-toggle >}}
|
||||
|
||||
|
||||
## Configure title case
|
||||
|
||||
By default, Hugo follows the capitalization rules published in the [Associated Press Stylebook] when creating automatic section titles, and when transforming strings with the [`strings.Title`] function.
|
||||
@@ -626,15 +678,31 @@ firstupper
|
||||
none
|
||||
: Disable transformation of automatic section titles, and disable the transformation performed by the `strings.Title` function. This is useful if you would prefer to manually capitalize section titles as needed, and to bypass opinionated theme usage of the `strings.Title` function.
|
||||
|
||||
[`strings.Title`]: /functions/strings/title
|
||||
[`strings.Title`]: /functions/strings/title/
|
||||
[Associated Press Stylebook]: https://www.apstylebook.com/
|
||||
[Chicago Manual of Style]: https://www.chicagomanualofstyle.org/home.html
|
||||
[site configuration]: /getting-started/configuration/#configure-title-case
|
||||
|
||||
## Configuration environment variables
|
||||
|
||||
DART_SASS_BINARY
|
||||
: (`string`) The absolute path to the Dart Sass executable. By default, Hugo searches for the executable in each of the paths in the `PATH` environment variable.
|
||||
|
||||
HUGO_ENVIRONMENT
|
||||
: (`string`) Overrides the default [environment], typically one of `development`, `staging`, or `production`.
|
||||
|
||||
[environment]: /getting-started/glossary/#environment
|
||||
|
||||
HUGO_FILE_LOG_FORMAT
|
||||
: (`string`) A format string for the file path, line number, and column number displayed when reporting errors, or when calling the `Position` method from a shortcode or Markdown render hook. Valid tokens are `:file`, `:line`, and `:col`. Default is `:file::line::col`.
|
||||
|
||||
{{< new-in 0.123.0 >}}
|
||||
|
||||
HUGO_MEMORYLIMIT
|
||||
: (`int`) The maximum amount of system memory, in gigabytes, that Hugo can use while rendering your site. Default is 25% of total system memory.
|
||||
|
||||
HUGO_NUMWORKERMULTIPLIER
|
||||
: Can be set to increase or reduce the number of workers used in parallel processing in Hugo. If not set, the number of logical CPUs will be used.
|
||||
: (`int`) The number of workers used in parallel processing. Default is the number of logical CPUs.
|
||||
|
||||
## Configure with environment variables
|
||||
|
||||
@@ -726,10 +794,6 @@ The above will try first to extract the value for `.Date` from the file name, th
|
||||
`: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 configuration.
|
||||
|
||||
## 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 minify
|
||||
|
||||
See the [tdewolff/minify] project page for details.
|
||||
@@ -769,7 +833,7 @@ dir
|
||||
|
||||
This is the directory where Hugo by default will store its file caches. See [Configure File Caches](#configure-file-caches).
|
||||
|
||||
This can be set using the `cacheDir` config option or via the OS env variable `HUGO_CACHEDIR`.
|
||||
This can be set using the `cacheDir` config option or via the OS environment variable `HUGO_CACHEDIR`.
|
||||
|
||||
If this is not set, Hugo will use, in order of preference:
|
||||
|
||||
@@ -779,10 +843,123 @@ If this is not set, Hugo will use, in order of preference:
|
||||
|
||||
If you want to know the current value of `cacheDir`, you can run `hugo config`, e.g: `hugo config | grep cachedir`.
|
||||
|
||||
[`time`]: /functions/time/astime
|
||||
[`.Site.Params`]: /variables/site/
|
||||
[directory structure]: /getting-started/directory-structure
|
||||
[`time`]: /functions/time/astime/
|
||||
[`.Site.Params`]: /method/site/params/
|
||||
[directory structure]: /getting-started/directory-structure/
|
||||
[lookup order]: /templates/lookup-order/
|
||||
[Output Formats]: /templates/output-formats/
|
||||
[custom output formats]: /templates/output-formats/
|
||||
[templates]: /templates/
|
||||
[static-files]: /content-management/static-files/
|
||||
|
||||
|
||||
## Configure HTTP cache
|
||||
|
||||
{{< new-in 0.127.0 >}}
|
||||
|
||||
Note that this configuration is currently only relevant when using the [resources.GetRemote] function.
|
||||
|
||||
The caching in Hugo is layered:
|
||||
|
||||
```goat {.w-40}
|
||||
.-----------.
|
||||
| dynacache |
|
||||
'-----+-----'
|
||||
|
|
||||
v
|
||||
.----------.
|
||||
| HTTP cache |
|
||||
'-----+----'
|
||||
|
|
||||
v
|
||||
.----------.
|
||||
| file cache |
|
||||
'-----+----'
|
||||
```
|
||||
|
||||
Dynacache
|
||||
: A in memory LRU cache that gets evicted on changes, [Cache Buster](#configure-cache-busters) matches and in low memory situations.
|
||||
|
||||
HTTP Cache
|
||||
: Enables HTTP cache behavior (RFC 9111) for remote resources. This works best for resources with properly set up HTTP cache headers. The HTTP cache uses the [file cache] to store and serve cached resources.
|
||||
|
||||
File Cache
|
||||
: See [file cache].
|
||||
|
||||
The default HTTP cache disables everything:
|
||||
|
||||
{{< code-toggle config=HTTPCache />}}
|
||||
|
||||
caching
|
||||
: Enabled RFC 9111 cache behavior _for_ a configured set of resources. Stale resources will be refreshed from the [file cache] even if their configured TTL isn't reached.
|
||||
|
||||
polling
|
||||
: Enables polling _for_ a set of resources. Note that you can enable polling for resources even if HTTP caching is disabled. This setting is only used when in watch mode (e.g. `hugo server`). When a changed resource is detected, that change triggers a rebuild of pages using that resource.
|
||||
|
||||
[resources.GetRemote]: /functions/resources/getremote/
|
||||
[file cache]: #configure-file-caches
|
||||
|
||||
## Configure segments
|
||||
|
||||
{{< new-in 0.124.0 >}}
|
||||
|
||||
{{% note %}}
|
||||
The `segments` configuration is currently only used to configure partitioned rendering.
|
||||
This feature is only about what gets rendered when, Hugo's entire object graph (sites and pages) is
|
||||
always available.
|
||||
{{% /note %}}
|
||||
|
||||
* Each segment consists of zero or more `exclude` filters and zero or more `include` filters.
|
||||
* Each filter consists of one or more field Glob matchers.
|
||||
* Each filter in a section (`exclude` or `include`) is ORed together, each matcher in a filter is ANDed together.
|
||||
|
||||
The fields that can be used in the filters are:
|
||||
|
||||
path
|
||||
: The logical page [path].
|
||||
|
||||
lang
|
||||
: The [page language].
|
||||
|
||||
kind
|
||||
: The [kind] of the page.
|
||||
|
||||
output
|
||||
: The [output format] of the page.
|
||||
|
||||
It is recommended to put coarse grained filters (e.g. for language and output format) in the excludes section, e.g.:
|
||||
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[segments.segment1]
|
||||
[[segments.segment1.excludes]]
|
||||
lang = "n*"
|
||||
[[segments.segment1.excludes]]
|
||||
lang = "en"
|
||||
output = "rss"
|
||||
[[segments.segment1.includes]]
|
||||
kind = "{home,term,taxonomy}"
|
||||
[[segments.segment1.includes]]
|
||||
path = "{/docs,/docs/**}"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
With the above you can render only the pages in `segment1` by configuring the [renderSegments](#rendersegments) or setting the `--renderSegments` flag:
|
||||
|
||||
```bash
|
||||
hugo --renderSegments segment1
|
||||
```
|
||||
|
||||
Multiple segments can be configured, and the `--renderSegments` flag can take a comma separated list of segments.
|
||||
|
||||
Some use cases for this feature:
|
||||
|
||||
* Splitting builds of big sites.
|
||||
* Enable faster builds during development by only rendering a subset of the site.
|
||||
* Partial rebuilds, e.g. render the home page and the "news section" every hour, render the entire site once a week.
|
||||
* Render only e.g. the JSON output format to push to e.g. a search index.
|
||||
|
||||
[path]: /methods/page/path/
|
||||
[page language]: /methods/page/language/
|
||||
[kind]: /getting-started/glossary/#page-kind
|
||||
[output format]: /getting-started/glossary/#output-format
|
||||
[type]: /getting-started/glossary/#content-type
|
||||
|
||||
|
||||
Reference in New Issue
Block a user