@import "./shortcodes.css";
@import "./tableofcontents.css";
@import "./view-transitions.css";
+@import "./todo-lists.css";
--- /dev/null
+ul.todo {
+ padding-left: 0;
+}
+
+ul.todo li {
+ display: flex;
+ gap: 0.8em;
+}
+
+ul.todo li input[type="checkbox"] {
+ width: 1em;
+ height: 1em;
+ flex-shrink: 0;
+ margin-top: 0.3em;
+}
padding-right: max(env(safe-area-inset-right), 1rem);
}
-@media screen(md) {
+@media (min-width: theme('--breakpoint-md')) {
.px-main {
padding-left: max(env(safe-area-inset-left), 2rem);
padding-right: max(env(safe-area-inset-right), 2rem);
}
}
-@media screen(lg) {
+@media (min-width: theme('--breakpoint-lg')) {
.px-main {
padding-left: max(env(safe-area-inset-left), 3rem);
padding-right: max(env(safe-area-inset-right), 3rem);
--- /dev/null
+---
+_comment: Do not remove front matter.
+---
+
+The returned collection follows a hierarchical sort where each subsequent dimension acts as a tie-breaker for the one above it.
+
+1. [Language](g) is sorted by [weight](g) in ascending order, falling back to lexicographical order if weights are tied or undefined.
+1. [Version](g) is then sorted by weight in ascending order, with Hugo defaulting to a descending semantic sort for any ties.
+1. [Role](g) is finally sorted by weight in ascending order, using lexicographical order as the final fallback.
_comment: Do not remove front matter.
---
-In this site configuration we enable rendering of [emoji shortcodes], and add emoji shortcodes before (pre) and after (post) each menu entry:
+In this project configuration we enable rendering of [emoji shortcodes], and add emoji shortcodes before (pre) and after (post) each menu entry:
{{< code-toggle file=hugo >}}
enableEmoji = true
- The `Prev` method points to page-3
- The `Next` method points to page-1
-To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [site configuration], or use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility.
+To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [project configuration], or use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility.
-[site configuration]: /configuration/page/
+[project configuration]: /configuration/page/
[`Next`]: /methods/pages/prev
[`Prev`]: /methods/pages/prev
- The `PrevInSection` method points to page-3
- The `NextInSection` method points to page-1
-To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [site configuration], or use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility.
+To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [project configuration], or use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility.
-[site configuration]: /configuration/page/
+[project configuration]: /configuration/page/
[`Next`]: /methods/pages/prev
[`Prev`]: /methods/pages/prev
: Specify one of `crop`, `fill`, `fit`, or `resize`. This is applicable to the [`Process`][] method and the [`images.Process`][] filter. If you specify an action, you must also provide dimensions.
anchor
-: The focal point used when cropping or filling an image. Valid options include `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. The `Smart` option utilizes the [`smartcrop.js`][] library to identify the most interesting area of the image. This defaults to the [`anchor`][] parameter in your site configuration.
+: The focal point used when cropping or filling an image. Valid options include `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. The `Smart` option utilizes the [`smartcrop.js`][] library to identify the most interesting area of the image. This defaults to the [`anchor`][] parameter in your project configuration.
background color
-: The background color used when converting transparent images to formats that do not support transparency, such as PNG to JPEG. This color also fills the empty space created when rotating an image by a non-orthogonal angle if the space is not transparent and a background color is not specified in the processing specification. The value must be an RGB [hexadecimal color][]. This defaults to the [`bgColor`][] parameter in your site configuration.
+: The background color used when converting transparent images to formats that do not support transparency, such as PNG to JPEG. This color also fills the empty space created when rotating an image by a non-orthogonal angle if the space is not transparent and a background color is not specified in the processing specification. The value must be an RGB [hexadecimal color][]. This defaults to the [`bgColor`][] parameter in your project configuration.
compression
: {{< new-in 0.153.5 />}}
-: The encoding strategy used for the image. Options are `lossy` or `lossless`. Note that `lossless` is only supported by the WebP format. This defaults to the [`compression`][] parameter in your site configuration.
+: The encoding strategy used for the image. Options are `lossy` or `lossless`. Note that `lossless` is only supported by the WebP format. This defaults to the [`compression`][] parameter in your project configuration.
dimensions
: The dimensions of the resulting image, in pixels. The format is `WIDTHxHEIGHT` where `WIDTH` and `HEIGHT` are whole numbers. When resizing an image, you may specify only the width (such as `600x`) or only the height (such as `x400`) for proportional scaling. Specifying both width and height when resizing an image may result in non-proportional scaling. When cropping, fitting, or filling, you must provide both width and height such as `600x400`.
: The format of the resulting image. Valid options include `bmp`, `gif`, `jpeg`, `png`, `tiff`, or `webp`. This defaults to the format of the source image.
hint
-: The encoding preset used when processing WebP images, equivalent to the `-preset` flag for the [`cwebp`][] CLI. Valid options include `drawing`, `icon`, `photo`, `picture`, or `text`. This defaults to the [`hint`][] parameter in your site configuration.
+: The encoding preset used when processing WebP images, equivalent to the `-preset` flag for the [`cwebp`][] CLI. Valid options include `drawing`, `icon`, `photo`, `picture`, or `text`. This defaults to the [`hint`][] parameter in your project configuration.
Value|Example
:--|:--
`text`|Image that is primarily text
quality
-: The visual fidelity of the image, applicable to JPEG and WebP formats when using `lossy` compression. The format is `qQUALITY` where `QUALITY` is a whole number between `1` and `100`, inclusive. Lower numbers prioritize smaller file size, while higher numbers prioritize visual clarity. This defaults to the [`quality`][] parameter in your site configuration.
+: The visual fidelity of the image, applicable to JPEG and WebP formats when using `lossy` compression. The format is `qQUALITY` where `QUALITY` is a whole number between `1` and `100`, inclusive. Lower numbers prioritize smaller file size, while higher numbers prioritize visual clarity. This defaults to the [`quality`][] parameter in your project configuration.
resampling filter
-: The algorithm used to calculate new pixels when resizing, fitting, or filling an image. Common options include `box`, `lanczos`, `catmullRom`, `mitchellNetravali`, `linear`, or `nearestNeighbor`. This defaults to the [`resampleFilter`][] parameter in your site configuration.
+: The algorithm used to calculate new pixels when resizing, fitting, or filling an image. Common options include `box`, `lanczos`, `catmullRom`, `mitchellNetravali`, `linear`, or `nearestNeighbor`. This defaults to the [`resampleFilter`][] parameter in your project configuration.
Filter|Description
:--|:--
rotation
: The number of whole degrees to rotate an image counter-clockwise. The format is `rDEGREES` where `DEGREES` is a whole number. Hugo performs rotation before any other transformations, so your [target dimensions](#dimensions) and any [anchor](#anchor) should refer to the image orientation after rotation. Use `r90`, `r180`, or `r270` for orthogonal rotations, or arbitrary angles such as `r45`. To rotate clockwise, use a negative number such as `r-45`. To automatically rotate an image based on its Exif orientation tag, use the [`images.AutoOrient`][] filter instead of manual rotation.
- Rotating by non-orthogonal values increases the image extents to fit the rotated corners. For formats supporting alpha channels such as PNG or WebP, this resulting empty space is transparent by default. If the target format does not support transparency such as JPEG, or if you explicitly specify a [background color](#background-color) in the processing specification, the space is filled. If a color is required but not specified in the processing string, it defaults to the [`bgColor`][] parameter in your site configuration.
+ Rotating by non-orthogonal values increases the image extents to fit the rotated corners. For formats supporting alpha channels such as PNG or WebP, this resulting empty space is transparent by default. If the target format does not support transparency such as JPEG, or if you explicitly specify a [background color](#background-color) in the processing specification, the space is filled. If a color is required but not specified in the processing string, it defaults to the [`bgColor`][] parameter in your project configuration.
[`anchor`]: /configuration/imaging/#anchor
[`bgcolor`]: /configuration/imaging/#bgcolor
## Capture a Taxonomy object
-Consider this site configuration:
+Consider this project configuration:
{{< code-toggle file=hugo >}}
[taxonomies]
_comment: Do not remove front matter.
---
-By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your site configuration, and specify a URL to return when the path cannot be resolved.
+By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your project configuration, and specify a URL to return when the path cannot be resolved.
{{< code-toggle file=hugo >}}
refLinksErrorLevel = 'warning'
## Content management
[Multidimensional content model]
-: Generate pages across any combination of language, role, and version from a single source. This allows a single piece of content to be published to multiple [sites](g) within your project, removing the need to duplicate files for different audiences or versions.
+: Generate pages across any combination of language, version, and role from a single source. This allows a single piece of content to be published to multiple [sites](g) within your project, removing the need to duplicate files for different audiences or versions.
[Content adapters]
-: Create content adapters to dynamically add content when building your site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML.
+: Create content adapters to dynamically add content when building your project. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML.
[Taxonomies]
: Classify content to establish simple or complex logical relationships between pages. For example, create an authors taxonomy, and assign one or more authors to each page. Among other uses, the taxonomy system provides an inverted, weighted index to render a list of related pages, ordered by relevance.
---
## hugo
-Build your site
+Build your project
### Synopsis
-hugo is the main command, used to build your Hugo site.
+hugo is the main command, used to build your Hugo project.
Hugo is a Fast and Flexible Static Site Generator
built with love by spf13 and friends in Go.
### SEE ALSO
-* [hugo build](/commands/hugo_build/) - Build your site
+* [hugo build](/commands/hugo_build/) - Build your project
* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell
-* [hugo config](/commands/hugo_config/) - Display site configuration
+* [hugo config](/commands/hugo_config/) - Display project configuration
* [hugo convert](/commands/hugo_convert/) - Convert front matter to another format
-* [hugo deploy](/commands/hugo_deploy/) - Deploy your site to a cloud provider
+* [hugo deploy](/commands/hugo_deploy/) - Deploy your project to a cloud provider
* [hugo env](/commands/hugo_env/) - Display version and environment info
* [hugo gen](/commands/hugo_gen/) - Generate documentation and syntax highlighting styles
-* [hugo import](/commands/hugo_import/) - Import a site from another system
+* [hugo import](/commands/hugo_import/) - Import a project from another system
* [hugo list](/commands/hugo_list/) - List content
* [hugo mod](/commands/hugo_mod/) - Manage modules
* [hugo new](/commands/hugo_new/) - Create new content
* [hugo server](/commands/hugo_server/) - Start the embedded web server
* [hugo version](/commands/hugo_version/) - Display version
-
---
## hugo build
-Build your site
+Build your project
### Synopsis
-build is the main command, used to build your Hugo site.
+build is the main command, used to build your Hugo project.
Hugo is a Fast and Flexible Static Site Generator
built with love by spf13 and friends in Go.
### SEE ALSO
-* [hugo](/commands/hugo/) - Build your site
-
+* [hugo](/commands/hugo/) - Build your project
### SEE ALSO
-* [hugo](/commands/hugo/) - Build your site
+* [hugo](/commands/hugo/) - Build your project
* [hugo completion bash](/commands/hugo_completion_bash/) - Generate the autocompletion script for bash
* [hugo completion fish](/commands/hugo_completion_fish/) - Generate the autocompletion script for fish
* [hugo completion powershell](/commands/hugo_completion_powershell/) - Generate the autocompletion script for powershell
* [hugo completion zsh](/commands/hugo_completion_zsh/) - Generate the autocompletion script for zsh
-
### SEE ALSO
* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell
-
### SEE ALSO
* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell
-
### SEE ALSO
* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell
-
### SEE ALSO
* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell
-
---
## hugo config
-Display site configuration
+Display project configuration
### Synopsis
-Display site configuration, both default and custom settings.
+Display project configuration, both default and custom settings.
```
hugo config [command] [flags]
### SEE ALSO
-* [hugo](/commands/hugo/) - Build your site
+* [hugo](/commands/hugo/) - Build your project
* [hugo config mounts](/commands/hugo_config_mounts/) - Print the configured file mounts
-
### SEE ALSO
-* [hugo config](/commands/hugo_config/) - Display site configuration
-
+* [hugo config](/commands/hugo_config/) - Display project configuration
### SEE ALSO
-* [hugo](/commands/hugo/) - Build your site
+* [hugo](/commands/hugo/) - Build your project
* [hugo convert toJSON](/commands/hugo_convert_tojson/) - Convert front matter to JSON
* [hugo convert toTOML](/commands/hugo_convert_totoml/) - Convert front matter to TOML
* [hugo convert toYAML](/commands/hugo_convert_toyaml/) - Convert front matter to YAML
-
### SEE ALSO
* [hugo convert](/commands/hugo_convert/) - Convert front matter to another format
-
### SEE ALSO
* [hugo convert](/commands/hugo_convert/) - Convert front matter to another format
-
### SEE ALSO
* [hugo convert](/commands/hugo_convert/) - Convert front matter to another format
-
---
## hugo deploy
-Deploy your site to a cloud provider
+Deploy your project to a cloud provider
### Synopsis
-Deploy your site to a cloud provider
+Deploy your project to a cloud provider
See https://gohugo.io/hosting-and-deployment/hugo-deploy/ for detailed
documentation.
### SEE ALSO
-* [hugo](/commands/hugo/) - Build your site
-
+* [hugo](/commands/hugo/) - Build your project
### SEE ALSO
-* [hugo](/commands/hugo/) - Build your site
-
+* [hugo](/commands/hugo/) - Build your project
### SEE ALSO
-* [hugo](/commands/hugo/) - Build your site
+* [hugo](/commands/hugo/) - Build your project
* [hugo gen chromastyles](/commands/hugo_gen_chromastyles/) - Generate CSS stylesheet for the Chroma code highlighter
* [hugo gen doc](/commands/hugo_gen_doc/) - Generate Markdown documentation for the Hugo CLI
* [hugo gen man](/commands/hugo_gen_man/) - Generate man pages for the Hugo CLI
-
### SEE ALSO
* [hugo gen](/commands/hugo_gen/) - Generate documentation and syntax highlighting styles
-
### SEE ALSO
* [hugo gen](/commands/hugo_gen/) - Generate documentation and syntax highlighting styles
-
### SEE ALSO
* [hugo gen](/commands/hugo_gen/) - Generate documentation and syntax highlighting styles
-
---
## hugo import
-Import a site from another system
+Import a project from another system
### Synopsis
-Import a site from another system.
+Import a project from another system.
Import requires a subcommand, e.g. `hugo import jekyll jekyll_root_path target_path`.
### SEE ALSO
-* [hugo](/commands/hugo/) - Build your site
+* [hugo](/commands/hugo/) - Build your project
* [hugo import jekyll](/commands/hugo_import_jekyll/) - hugo import from Jekyll
-
### Synopsis
hugo import from Jekyll.
-
+
Import from Jekyll requires two paths, e.g. `hugo import jekyll jekyll_root_path target_path`.
```
### SEE ALSO
-* [hugo import](/commands/hugo_import/) - Import a site from another system
-
+* [hugo import](/commands/hugo_import/) - Import a project from another system
### SEE ALSO
-* [hugo](/commands/hugo/) - Build your site
+* [hugo](/commands/hugo/) - Build your project
* [hugo list all](/commands/hugo_list_all/) - List all content
* [hugo list drafts](/commands/hugo_list_drafts/) - List draft content
* [hugo list expired](/commands/hugo_list_expired/) - List expired content
* [hugo list future](/commands/hugo_list_future/) - List future content
* [hugo list published](/commands/hugo_list_published/) - List published content
-
### SEE ALSO
* [hugo list](/commands/hugo_list/) - List content
-
### SEE ALSO
* [hugo list](/commands/hugo_list/) - List content
-
### SEE ALSO
* [hugo list](/commands/hugo_list/) - List content
-
### SEE ALSO
* [hugo list](/commands/hugo_list/) - List content
-
### SEE ALSO
* [hugo list](/commands/hugo_list/) - List content
-
This is not needed if you only operate on modules inside /themes or if you have vendored them via "hugo mod vendor".
-Note that Hugo will always start out by resolving the components defined in the site
+Note that Hugo will always start out by resolving the components defined in the project
configuration, provided by a _vendor directory (if no --ignoreVendorPaths flag provided),
Go Modules, or a folder inside the themes directory, in that order.
### SEE ALSO
-* [hugo](/commands/hugo/) - Build your site
+* [hugo](/commands/hugo/) - Build your project
* [hugo mod clean](/commands/hugo_mod_clean/) - Delete the Hugo Module cache for the current project
* [hugo mod get](/commands/hugo_mod_get/) - Resolves dependencies in your current Hugo project
* [hugo mod graph](/commands/hugo_mod_graph/) - Print a module dependency graph
* [hugo mod tidy](/commands/hugo_mod_tidy/) - Remove unused entries in go.mod and go.sum
* [hugo mod vendor](/commands/hugo_mod_vendor/) - Vendor all module dependencies into the _vendor directory
* [hugo mod verify](/commands/hugo_mod_verify/) - Verify dependencies
-
### SEE ALSO
* [hugo mod](/commands/hugo_mod/) - Manage modules
-
Run "go help get" for more information. All flags available for "go get" is also relevant here.
-Note that Hugo will always start out by resolving the components defined in the site
+Note that Hugo will always start out by resolving the components defined in the project
configuration, provided by a _vendor directory (if no --ignoreVendorPaths flag provided),
Go Modules, or a folder inside the themes directory, in that order.
### SEE ALSO
* [hugo mod](/commands/hugo_mod/) - Manage modules
-
### SEE ALSO
* [hugo mod](/commands/hugo_mod/) - Manage modules
-
### SEE ALSO
* [hugo mod](/commands/hugo_mod/) - Manage modules
-
* [hugo mod](/commands/hugo_mod/) - Manage modules
* [hugo mod npm pack](/commands/hugo_mod_npm_pack/) - Experimental: Prepares and writes a composite package.json file for your project
-
### SEE ALSO
* [hugo mod npm](/commands/hugo_mod_npm/) - Various npm helpers
-
### SEE ALSO
* [hugo mod](/commands/hugo_mod/) - Manage modules
-
### SEE ALSO
* [hugo mod](/commands/hugo_mod/) - Manage modules
-
### SEE ALSO
* [hugo mod](/commands/hugo_mod/) - Manage modules
-
You can also specify the kind with `-k KIND`.
-If archetypes are provided in your theme or site, they will be used.
+If archetypes are provided in your theme or project, they will be used.
-Ensure you run this within the root directory of your site.
+Ensure you run this within the root directory of your project.
### Options
### SEE ALSO
-* [hugo](/commands/hugo/) - Build your site
+* [hugo](/commands/hugo/) - Build your project
* [hugo new content](/commands/hugo_new_content/) - Create new content
-* [hugo new site](/commands/hugo_new_site/) - Create a new site
+* [hugo new project](/commands/hugo_new_project/) - Create a new project
* [hugo new theme](/commands/hugo_new_theme/) - Create a new theme
-
You can also specify the kind with `-k KIND`.
-If archetypes are provided in your theme or site, they will be used.
+If archetypes are provided in your theme or project, they will be used.
-Ensure you run this within the root directory of your site.
+Ensure you run this within the root directory of your project.
```
hugo new content [path] [flags]
### SEE ALSO
* [hugo new](/commands/hugo_new/) - Create new content
-
--- /dev/null
+---
+title: "hugo new project"
+slug: hugo_new_project
+url: /commands/hugo_new_project/
+---
+## hugo new project
+
+Create a new project
+
+### Synopsis
+
+Create a new project at the specified path.
+
+```
+hugo new project [path] [flags]
+```
+
+### Options
+
+```
+ -f, --force init inside non-empty directory
+ --format string preferred file format (toml, yaml or json) (default "toml")
+ -h, --help help for project
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo new](/commands/hugo_new/) - Create new content
+++ /dev/null
----
-title: "hugo new site"
-slug: hugo_new_site
-url: /commands/hugo_new_site/
----
-## hugo new site
-
-Create a new site
-
-### Synopsis
-
-Create a new site at the specified path.
-
-```
-hugo new site [path] [flags]
-```
-
-### Options
-
-```
- -f, --force init inside non-empty directory
- --format string preferred file format (toml, yaml or json) (default "toml")
- -h, --help help for site
-```
-
-### Options inherited from parent commands
-
-```
- --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
- --config string config file (default is hugo.yaml|json|toml)
- --configDir string config dir (default "config")
- -d, --destination string filesystem path to write files to
- -e, --environment string build environment
- --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
- --logLevel string log level (debug|info|warn|error)
- --noBuildLock don't create .hugo_build.lock file
- --quiet build in quiet mode
- -M, --renderToMemory render to memory (mostly useful when running the server)
- -s, --source string filesystem path to read files relative from
- --themesDir string filesystem path to themes directory
-```
-
-### SEE ALSO
-
-* [hugo new](/commands/hugo_new/) - Create new content
-
### SEE ALSO
* [hugo new](/commands/hugo_new/) - Create new content
-
### Synopsis
-Hugo provides its own webserver which builds and serves the site.
+Hugo provides its own webserver which builds and serves the project.
While hugo server is high performance, it is a webserver with limited options.
The `hugo server` command will by default write and serve files from disk, but
faster in some cases, but it will consume more memory.
By default hugo will also watch your files for any changes you make and
-automatically rebuild the site. It will then live reload any open browser pages
-and push the latest content to them. As most Hugo sites are built in a fraction
+automatically rebuild the project. It will then live reload any open browser pages
+and push the latest content to them. As most Hugo projects are built in a fraction
of a second, you will be able to save and see your changes nearly instantly.
```
--noChmod don't sync permission mode of files
--noHTTPCache prevent HTTP caching
--noTimes don't sync modification time of files
- -O, --openBrowser open the site in a browser after server startup
+ -O, --openBrowser open the project in a browser after server startup
--panicOnWarning panic on first WARNING log
--poll string set this to a poll interval, e.g --poll 700ms, to use a poll based approach to watch for file system changes
-p, --port int port on which the server will listen (default 1313)
### SEE ALSO
-* [hugo](/commands/hugo/) - Build your site
+* [hugo](/commands/hugo/) - Build your project
* [hugo server trust](/commands/hugo_server_trust/) - Install the local CA in the system trust store
-
### SEE ALSO
* [hugo server](/commands/hugo_server/) - Start the embedded web server
-
### SEE ALSO
-* [hugo](/commands/hugo/) - Build your site
-
+* [hugo](/commands/hugo/) - Build your project
: (`string`) The designated directory for data files. Default is `data`. {{% module-mounts-note %}}
defaultContentLanguage
-: (`string`) The projects's default content language, conforming to the syntax described in [RFC 5646][]. This value must match one of the defined [language keys][]. Default is `en`.
+: (`string`) The projects's [default language](g), conforming to the syntax described in [RFC 5646][].
defaultContentLanguageInSubdir
: (`bool`) Whether to publish the default content language to a subdirectory matching the [`defaultContentLanguage`][]. Default is `false`.
defaultContentRole
: {{< new-in 0.153.0 />}}
-: (`string`) The project's default content [role](g). Default is `guest`.
+: (`string`) The project's [default role](g).
defaultContentRoleInSubdir
: {{< new-in 0.153.0 />}}
defaultContentVersion
: {{< new-in 0.153.0 />}}
-: (`string`) The project's default content version. Default is `v1.0.0`.
+: (`string`) The project's [default version](g).
defaultContentVersionInSubdir
: {{< new-in 0.153.0 />}}
disableDefaultSiteRedirect
: {{< new-in 0.154.5 />}}
-: (bool) Whether to disable generation of the alias redirect to the [default site](g). When [`defaultContentLanguageInSubdir`][], [`defaultContentRoleInSubdir`][], or [`defaultContentVersionInSubdir`][] is `true`, this prevents the root directory from redirecting to the default site's subdirectory. Conversely, when these are `false`, it prevents the subdirectories from redirecting back to the root. The default site is the site with the default content language, version, and role. Default is `false`.
+: (bool) Whether to disable generation of the alias redirect to the [default site](g). When [`defaultContentLanguageInSubdir`][], [`defaultContentRoleInSubdir`][], or [`defaultContentVersionInSubdir`][] is `true`, this prevents the root directory from redirecting to the default site's subdirectory. Conversely, when these are `false`, it prevents the subdirectories from redirecting back to the root. Default is `false`.
disableHugoGeneratorInject
: (`bool`) Whether to disable injection of a `<meta name="generator">` tag into the home page. Default is `false`.
: (`bool`) Whether to enable generation of a `robots.txt` file. Default is `false`.
environment
-: (`string`) The build environment. Default is `production` when running `hugo` and `development` when running `hugo server`.
+: (`string`) The build environment. Default is `production` when running `hugo build` and `development` when running `hugo server`.
frontmatter
: See [configure front matter][].
: (`bool`) Whether to remove [non-spacing marks][] from [composite characters][] in content paths. Default is `false`.
renderSegments
-: (`[]string`) A slice of [segments](g) to render. If omitted, all segments are rendered. This option is typically set via a command-line flag, such as `hugo --renderSegments segment1,segment2`. The provided segment names must correspond to those defined in the [`segments`][] configuration.
+: (`[]string`) A slice of [segments](g) to render. If omitted, all segments are rendered. This option is typically set via a command-line flag, such as `hugo build --renderSegments segment1,segment2`. The provided segment names must correspond to those defined in the [`segments`][] configuration.
resourceDir
: (`string`) The designated directory for caching output from [asset pipelines](g). Default is `resources`.
[embedded Open Graph template]: <{{% eturl opengraph %}}>
[embedded RSS template]: <{{% eturl rss %}}>
[IANA Time Zone Database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
-[language keys]: /configuration/languages/#language-keys
[module mounts]: /configuration/module/#mounts
[non-spacing marks]: https://www.compart.com/en/unicode/category/Mn
[os.UserCacheDir]: https://pkg.go.dev/os#UserCacheDir
>
> Built for speed, there may be "false positive" detections (e.g., HTML elements that are not HTML elements) while parsing the published site. These "false positives" are infrequent and inconsequential.
-Due to the nature of partial server builds, new HTML entities are added while the server is running, but old values will not be removed until you restart the server or run a regular `hugo` build.
+Due to the nature of partial server builds, new HTML entities are added while the server is running, but old values will not be removed until you restart the server or run `hugo build`.
[`config/production`]: /configuration/introduction/#configuration-directory
: (`string`) The designated cache directory. See [details](/configuration/all/#cachedir).
`:project`
-: (`string`) The base directory name of the current Hugo project. This ensures isolated file caches for each project, preventing the `hugo --gc` command from affecting other projects on the same machine.
+: (`string`) The base directory name of the current Hugo project. This ensures isolated file caches for each project, preventing the `hugo build --gc` command from affecting other projects on the same machine.
`:resourceDir`
: (`string`) The designated directory for caching output from [asset pipelines](g). See [details](/configuration/all/#resourcedir).
## Garbage collection
-As you modify your site or change your configuration, cached files from previous builds may remain on disk, consuming unnecessary space. Use the `hugo --gc` command to remove these expired or unused entries from the file cache.
+As you modify your site or change your configuration, cached files from previous builds may remain on disk, consuming unnecessary space. Use the `hugo build --gc` command to remove these expired or unused entries from the file cache.
[`resources.GetRemote`]: /functions/resources/getremote/
## Target
<!-- TODO
-Update the <version> and <date> below when we actually get around to deprecating _target.
-
-We deprecated the `_target` front matter key in favor of `target` in <version> on <date>. Remove footnote #1 on or after 2027-05-01 (15 months after deprecation).
+We deprecated the `_target` front matter key in favor of `target` in v0.156.0 on 2026-02-17. Remove footnote #1 on or after 2027-05-17 (15 months after deprecation).
-->
The `target`[^1] keyword allows you to target specific pages or [environments](g). For example, to cascade a "color" parameter to pages within the "articles" section, including the "articles" section page itself:
Within the `YYYY-MM-DD-HH-MM-SS` format, the date and time values may be separated by any character including a space (e.g., `2025-02-01T14-30-00`).
- Hugo resolves the extracted date to the [`timeZone`] defined in your site configuration, falling back to the system time zone. After extracting the date, Hugo uses the remaining part of the file name to generate the page's [`slug`], but only if you haven't already specified a slug in the page's front matter.
+ Hugo resolves the extracted date to the [`timeZone`] defined in your project configuration, falling back to the system time zone. After extracting the date, Hugo uses the remaining part of the file name to generate the page's [`slug`], but only if you haven't already specified a slug in the page's front matter.
For example, if you name your file `2025-02-01-article.md`, Hugo will set the date to `2025-02-01` and the slug to `article`.
`:git`
-: The Git author date for the file's last revision. To enable access to the Git author date, set [`enableGitInfo`] to `true`, or use the `--enableGitInfo` flag when building your site.
+: The Git author date for the file's last revision. To enable access to the Git author date, set [`enableGitInfo`] to `true`, or use the `--enableGitInfo` flag when building your project.
## Example
-Consider this site configuration:
+Consider this project configuration:
{{< code-toggle file=hugo >}}
[frontmatter]
## Configuration file
-Create a site configuration file in the root of your project directory, naming it `hugo.toml`, `hugo.yaml`, or `hugo.json`, with that order of precedence.
+Create a project configuration file in the root of your project directory, naming it `hugo.toml`, `hugo.yaml`, or `hugo.json`, with that order of precedence.
```text
my-project/
```
> [!note]
-> For versions v0.109.0 and earlier, the site configuration file was named `config`. While you can still use this name, it's recommended to switch to the newer naming convention, `hugo`.
+> For versions v0.109.0 and earlier, the project configuration file was named `config`. While you can still use this name, it's recommended to switch to the newer naming convention, `hugo`.
A simple example:
phone = '+1 202-555-1212'
{{< /code-toggle >}}
-To use a different configuration file when building your site, use the `--config` flag:
+To use a different configuration file when building your project, use the `--config` flag:
```sh
-hugo --config other.toml
+hugo build --config other.toml
```
Combine two or more configuration files, with left-to-right precedence:
```sh
-hugo --config a.toml,b.yaml,c.json
+hugo build --config a.toml,b.yaml,c.json
```
> [!note]
## Configuration directory
-Instead of a single site configuration file, split your configuration by [environment](g), root configuration key, and language. For example:
+Instead of a single project configuration file, split your configuration by [environment](g), root configuration key, and language. For example:
```text
my-project/
└── params.toml
```
-Considering the structure above, when running `hugo --environment staging`, Hugo will use every setting from `config/_default` and merge `staging`'s on top of those.
+Considering the structure above, when running `hugo build --environment staging`, Hugo will use every setting from `config/_default` and merge `staging`'s on top of those.
-Let's take an example to understand this better. Let's say you are using Google Analytics for your website. This requires you to specify a [Google tag ID] in your site configuration:
+Let's take an example to understand this better. Let's say you are using Google Analytics for your website. This requires you to specify a [Google tag ID] in your project configuration:
{{< code-toggle file=hugo >}}
[services.googleAnalytics]
{{< /code-toggle >}}
- You do not need to include other parameters in this file. Include only those parameters that are specific to your production environment. Hugo will merge these parameters with the default configuration.
- - By default, Hugo sets its `environment` to `production` when running `hugo`. The analytics code will use the `G-PPPPPPPPP` tag ID.
+ - By default, Hugo sets its `environment` to `production` when running `hugo build`. The analytics code will use the `G-PPPPPPPPP` tag ID.
1. `config/staging/hugo.toml`
{{< /code-toggle >}}
- You do not need to include other parameters in this file. Include only those parameters that are specific to your staging environment. Hugo will merge these parameters with the default configuration.
- - To build your staging site, run `hugo --environment staging`. The analytics code will use the `G-SSSSSSSSS` tag ID.
+ - To build your staging site, run `hugo build --environment staging`. The analytics code will use the `G-SSSSSSSSS` tag ID.
## Merge configuration settings
: (`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`.
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. Note that `HUGO_MEMORYLIMIT` is a "best effort" setting. Don't expect Hugo to build a million pages with only 1 GB of memory. You can get more information about how this behaves during the build by building with `hugo --logLevel info` and look for the `dynacache` label.
+: (`int`) The maximum amount of system memory, in gigabytes, that Hugo can use while rendering your site. Default is 25% of total system memory. Note that `HUGO_MEMORYLIMIT` is a "best effort" setting. Don't expect Hugo to build a million pages with only 1 GB of memory. You can get more information about how this behaves during the build by running `hugo build --logLevel info` and look for the `dynacache` label.
HUGO_NUMWORKERMULTIPLIER
: (`int`) The number of workers used in parallel processing. Default is the number of logical CPUs.
## Current configuration
-Display the complete site configuration with:
+Display the complete project configuration with:
```sh
hugo config
Access this value from a template using the [`Language.LanguageCode`][] method on a `Site` or `Page` object.
languageDirection
-: (`string`) The language direction, either left-to-right (`ltr`) or right-to-left (`rtl`). Use this value in your templates with the global [`dir`][] HTML attribute. Access this value from a template using the [`Language.LanguageDirection`][] method on a `Site` or `Page` object.
+: (`string`) The language direction, either left-to-right (`ltr`) or right-to-left (`rtl`). Use this value in your templates with the global [`dir`][] HTML attribute. Access this value from a template using the [`Language.LanguageDirection`][] method on a `Site` or `Page` object. Default is `ltr`.
languageName
: (`string`) The language name, typically used when rendering a language switcher. Access this value from a template using the [`Language.LanguageName`][] method on a `Site` or `Page` object.
weight
: (`int`) The language [weight](g). When set to a non-zero value, this is the primary sort criteria for this language. Access this value from a template using the [`Language.Weight`][] method on a `Site` or `Page` object.
+## Sort order
+
+Hugo sorts languages by weight in ascending order, then lexicographically in ascending order. This affects build order and complement selection.
+
## Localized settings
Some configuration settings can be defined separately for each language. For example:
{{< per-lang-config-keys >}}
-Any key not defined in a `languages` object will fall back to the global value in the root of the site configuration.
+Any key not defined in a `languages` object will fall back to the global value in the root of your project configuration.
## Language keys
Files with ending with `.md`, `.mdown`, or `.markdown` are processed as Markdown, unless you've explicitly set a different format using the `markup` field in your front matter.
-To use a different renderer for Markdown files, specify one of `asciidocext`, `org`, `pandoc`, or `rst` in your site configuration.
+To use a different renderer for Markdown files, specify one of `asciidocext`, `org`, `pandoc`, or `rst` in your project configuration.
`defaultMarkdownHandler`|Renderer
:--|:--
#### Extras
-{{< new-in 0.126.0 />}}
-
Enable [deleted text], [inserted text], [mark text], [subscript], and [superscript] elements in Markdown.
Element|Markdown|Rendered
Follow the steps below to enable syntax highlighting.
Step 1
-: Set the `source-highlighter` attribute in your site configuration. For example:
+: Set the `source-highlighter` attribute in your project configuration. For example:
{{< code-toggle file=hugo >}}
[markup.asciidocExt.attributes]
### Troubleshooting
-Run `hugo --logLevel debug` to examine Hugo's call to the Asciidoctor executable:
+Run `hugo build --logLevel debug` to examine Hugo's call to the Asciidoctor executable:
```txt
INFO 2019/12/22 09:08:48 Rendering book-as-pdf.adoc with C:\Ruby26-x64\bin\asciidoctor.bat using asciidoc args [--no-header-footer -r asciidoctor-html5s -b html5s -r asciidoctor-diagram --base-dir D:\prototypes\hugo_asciidoc_ddd\docs -a outdir=D:\prototypes\hugo_asciidoc_ddd\build -] ...
There are three ways to define menu entries:
1. [Automatically]
-1. [In front matter]
-1. In site configuration
+1. In [front matter]
+1. In your project configuration
-This page covers the site configuration method.
+This page covers the project configuration method.
## Example
[`Menus`]: /methods/site/menus/
[Automatically]: /content-management/menus/#define-automatically
-[In front matter]: /content-management/menus/#define-in-front-matter
+[front matter]: /content-management/menus/#define-in-front-matter
[menu templates]: /templates/menu/
[menus]: /content-management/menus/
: (`bool`) Whether to exclude this output format from the values returned by the [`AlternativeOutputFormats`][] method on a `Page` object. Default is `false`.
noUgly
-: (`bool`) Whether to disable ugly URLs for this output format when [`uglyURLs`][] are enabled in your site configuration. Default is `false`.
+: (`bool`) Whether to disable ugly URLs for this output format when [`uglyURLs`][] are enabled in your project configuration. Default is `false`.
path
: (`string`) The first segment of the publication path for this output format. This path segment is relative to the root of your [`publishDir`][]. If omitted, Hugo will use the file's original content path for publishing.
: (`bool`) Whether to return the rendering output format rather than the main output format when invoking the [`Permalink`][] and [`RelPermalink`][] methods on a `Page` object. Along with [`isHTML`](#ishtml), this must be `true` to create [alias redirects][]. Enabled by default for the `html` and `amp` output formats. Default is `false`.
protocol
-: (`string`) The protocol (scheme) of the URL for this output format. For example, `https://` or `webcal://`. Default is the scheme of the [`baseURL`][] parameter in your site configuration, typically `https://`.
+: (`string`) The protocol (scheme) of the URL for this output format. For example, `https://` or `webcal://`. Default is the scheme of the [`baseURL`][] parameter in your project configuration, typically `https://`.
rel
: (`string`) The relationship of the output format to the current page. Hugo uses this property to determine the [canonical output format](g) of the current page. For the predefined `html` output format, the default value is `canonical`; for all other predefined output formats, the default value is `alternate`.
: (`bool`) Whether to publish files to the root of the publish directory. Default is `false`.
ugly
-: (`bool`) Whether to enable uglyURLs for this output format when `uglyURLs` is `false` in your site configuration. Default is `false`.
+: (`bool`) Whether to enable uglyURLs for this output format when `uglyURLs` is `false` in your project configuration. Default is `false`.
weight
: (`int`) When set to a non-zero value, Hugo uses the `weight` as the first criteria when sorting output formats, falling back to the name of the output format. Lighter items float to the top, while heavier items sink to the bottom. Hugo renders output formats sequentially based on the sort order. Default is `0`, except for the `html` output format, which has a default weight of `10`.
## List output formats
-To access output formats, each `Page` object provides two methods: [`OutputFormats`][] (for all formats, including the current one) and [`AlternativeOutputFormats`][]. Use `AlternativeOutputFormats` to create a link `rel` list within your site's `head` element, as shown below:
+To access output formats, each `Page` object provides two methods: [`OutputFormats`][] (for all formats, including the current one) and [`AlternativeOutputFormats`][]. Use `AlternativeOutputFormats` to create a link `rel` list within a `head` element, as shown below:
```go-html-template
{{ range .AlternativeOutputFormats }}
outputs = ['json']
{{< /code-toggle >}}
-In its default configuration, Hugo will render both the `html` and `json` output formats for this page. The `outputs` field appends to, rather than replaces, the site's configured outputs.
+In its default configuration, Hugo will render both the `html` and `json` output formats for this page. The `outputs` field appends to, rather than replaces, the project's configured outputs.
[`Permalink`]: /methods/page/permalink/
[`RelPermalink`]: /methods/page/relpermalink/
- [`Next`](/methods/page/next/) and [`Prev`](/methods/page/prev/)
- [`NextInSection`](/methods/page/nextinsection/) and [`PrevInSection`](/methods/page/previnsection/)
-This is based on this default site configuration:
+This is based on this default project configuration:
{{< code-toggle config=page />}}
└── _index.md
```
-And this site configuration:
+And this project configuration:
{{< code-toggle file=hugo >}}
defaultContentLanguage = 'en'
> [!note]
> To understand Hugo's related content identification, please refer to the [related content] page.
-Hugo provides a sensible default configuration for identifying related content, but you can customize it in your site configuration, either globally or per language.
+Hugo provides a sensible default configuration for identifying related content, but you can customize it in your project configuration, either globally or per language.
## Default configuration
{{< code-toggle config=related />}}
> [!note]
-> Adding a `related` section to your site configuration requires you to provide a full configuration. You cannot override individual default values without specifying all related settings.
+> Adding a `related` section to your project configuration requires you to provide a full configuration. You cannot override individual default values without specifying all related settings.
## Top-level options
{{< code-toggle config=roles />}}
-To define "guest" and "member" roles:
+## Settings
+
+Use the following setting to define how Hugo orders roles.
+
+weight
+: (`int`) The role [weight](g).
+
+## Sort order
+
+Hugo sorts roles by weight in ascending order, then lexicographically in ascending order. This affects build order and complement selection.
+
+## Example
+
+The following configuration demonstrates how to define multiple roles with specific weights.
{{< code-toggle >}}
[roles.guest]
[roles.member]
weight = 10
{{< /code-toggle >}}
-
-Roles are sorted by their [weight](g) in descending order, then by their name in descending order. This affects build order and complement selection.
> [!note]
> Setting an allowlist to the string `none` will completely disable the associated feature.
-You can also override the site configuration with environment variables. For example, to block `resources.GetRemote` from accessing any URL:
+You can also override your project configuration with environment variables. For example, to block `resources.GetRemote` from accessing any URL:
```txt
export HUGO_SECURITY_HTTP_URLS=none
Render specific segments using the [`renderSegments`] configuration or the `--renderSegments` flag:
-```bash
-hugo --renderSegments segment1
+```sh
+hugo build --renderSegments segment1
```
You can configure multiple segments and use a comma-separated list with `--renderSegments` to render them all.
-```bash
-hugo --renderSegments segment1,segment2
+```sh
+hugo build --renderSegments segment1,segment2
```
[`renderSegments`]: /configuration/all/#rendersegments
tag: tags
{{< /code-toggle >}}
-To disable the taxonomy system, use the [`disableKinds`] setting in the root of your site configuration to disable the `taxonomy` and `term` page [kinds](g).
+To disable the taxonomy system, use the [`disableKinds`] setting in the root of your project configuration to disable the `taxonomy` and `term` page [kinds](g).
{{< code-toggle file=hugo >}}
disableKinds = ['taxonomy','term']
{{< code-toggle config=versions />}}
-To define "v1.0.0" and "v2.0.0" versions:
+## Settings
+
+Use the following setting to define how Hugo orders versions.
+
+weight
+: (`int`) The language [weight](g).
+
+## Sort order
+
+Hugo sorts versions by weight in ascending order, then by their [semantic version][] in descending order. This affects build order and complement selection.
+
+## Example
+
+The following configuration demonstrates how to define multiple versions with specific weights.
{{< code-toggle >}}
[versions."v1.0.0"]
-weight = 0
+weight = 20
[versions."v2.0.0"]
-weight = 0
+weight = 10
{{< /code-toggle >}}
-Versions are sorted by their [weight](g) in ascending order, then by their [semantic version] in descending order. This affects build order and complement selection.
-
[semantic version]: https://semver.org/
### Configure Disqus
-Disqus comments require you set a single value in your [site's configuration file][configuration] like so:
+Disqus comments require you set a single value in your [project configuration][configuration]:
{{< code-toggle file=hugo >}}
[services.disqus]
---
title: Content adapters
-description: Create content adapters to dynamically add content when building your site.
+description: Create content adapters to dynamically add content when building your project.
categories: []
keywords: []
---
-{{< new-in 0.126.0 />}}
-
## Overview
A content adapter is a template that dynamically creates pages when building a site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML.
### EnableAllDimensions
-By default, Hugo executes the content adapter only once for the first matching site in the [sites matrix](g). Use this method to expand execution to every possible combination of language, role, and version.
+By default, Hugo executes the content adapter only once for the first matching site in the [sites matrix](g). Use this method to expand execution to every possible combination of language, version, and role.
For more fine-grained control, define a `sites.matrix` in front matter or in a content mount.
### Translations by file name
-With this site configuration:
+With this project configuration:
{{< code-toggle file=hugo >}}
[languages.en]
### Translations by content directory
-With this site configuration:
+With this project configuration:
{{< code-toggle file=hugo >}}
[languages.en]
If the content adapter also creates `books/the-hunchback-of-notre-dame`, the content of the published page is indeterminate. You can not define the processing order.
-To detect page collisions, use the `--printPathWarnings` flag when building your site.
+To detect page collisions, use the `--printPathWarnings` flag when building your project.
[content formats]: /content-management/formats/#classification
[front matter field]: /content-management/front-matter/#fields
Create your content in [Markdown] preceded by front matter.
-Markdown is Hugo's default content format. Hugo natively renders Markdown to HTML using [Goldmark]. Goldmark is fast and conforms to the [CommonMark] and [GitHub Flavored Markdown] specifications. You can configure Goldmark in your [site configuration][configure goldmark].
+Markdown is Hugo's default content format. Hugo natively renders Markdown to HTML using [Goldmark]. Goldmark is fast and conforms to the [CommonMark] and [GitHub Flavored Markdown] specifications. You can configure Goldmark in your [project configuration][configure goldmark].
Hugo provides custom Markdown features including:
Create your content in the [AsciiDoc] format preceded by front matter. Hugo renders AsciiDoc content to HTML using the Asciidoctor executable. You must install Asciidoctor and its dependencies (Ruby) to render the AsciiDoc content format.
-You can configure the AsciiDoc renderer in your [site configuration][configure asciidoc].
+You can configure the AsciiDoc renderer in your [project configuration][configure asciidoc].
In its default configuration, Hugo passes these CLI flags when calling the Asciidoctor executable:
--no-header-footer
```
-The CLI flags passed to the Asciidoctor executable depend on configuration. You may inspect the flags when building your site:
+The CLI flags passed to the Asciidoctor executable depend on configuration. You may inspect the flags when building your project:
```text
-hugo --logLevel info
+hugo build --logLevel info
```
[AsciiDoc]: https://asciidoc.org/
## Taxonomies
-Classify content by adding taxonomy terms to front matter. For example, with this site configuration:
+Classify content by adding taxonomy terms to front matter. For example, with this project configuration:
{{< code-toggle file=hugo >}}
[taxonomies]
### Target
<!-- TODO
-Update the <version> and <date> below when we actually get around to deprecating _target.
-
-We deprecated the `_target` front matter key in favor of `target` in <version> on <date>. Remove footnote #1 on or after 2027-05-01 (15 months after deprecation).
+We deprecated the `_target` front matter key in favor of `target` in v0.156.0 on 2026-02-17. Remove footnote #1 on or after 2027-05-17 (15 months after deprecation).
-->
The `target`[^1] keyword allows you to target specific pages or [environments](g). For example, to cascade a "color" parameter from the home page only to pages within the "articles" section, including the "articles" section page itself:
{{< /code-toggle >}}
> [!note]
-> For multilingual sites, defining cascade values in your site configuration is often more efficient. This avoids repeating the same cascade values on the home, section, taxonomy, or term page for each language. See [details](/configuration/cascade/).
+> For multilingual sites, defining cascade values in your project configuration is often more efficient. This avoids repeating the same cascade values on the home, section, taxonomy, or term page for each language. See [details](/configuration/cascade/).
>
> If you choose to define cascade values in front matter for a multilingual site, you must create a corresponding home, section, taxonomy, or term page for every language.
{{% include "/_common/parsable-date-time-strings.md" %}}
-To override the default time zone, set the [`timeZone`](/configuration/all/#timezone) in your site configuration. The order of precedence for determining the time zone is:
+To override the default time zone, set the [`timeZone`](/configuration/all/#timezone) in your project configuration. The order of precedence for determining the time zone is:
1. The time zone offset in the date/time string
-1. The time zone specified in your site configuration
+1. The time zone specified in your project configuration
1. The `Etc/UTC` time zone
[`aliases`]: /methods/page/aliases/
### Caching
-Hugo processes images on demand and returns a new resource object. To ensure subsequent builds remain fast, Hugo caches the results in the directory specified in the [file cache] section of your site configuration.
+Hugo processes images on demand and returns a new resource object. To ensure subsequent builds remain fast, Hugo caches the results in the directory specified in the [file cache][] section of your project configuration.
-If you host your site with Netlify, include the following in your site configuration to persist the image cache between builds:
+If you host your site with Netlify, include the following in your project configuration to persist the image cache between builds:
```toml
[caches]
If you change image processing methods, or rename/remove images, the cache will eventually contain unused files. To remove them and reclaim disk space, run Hugo's garbage collection:
```text
-hugo --gc
+hugo build --gc
```
### Resource usage
[`RelPermalink`]: /methods/resource/relpermalink/
[`Resize`]: /methods/resource/resize/
[`Width`]: /methods/resource/width/
+[file cache]: /configuration/caches/
## Block elements
-Update your site configuration to enable Markdown attributes for block-level elements.
+Update your project configuration to enable Markdown attributes for block-level elements.
{{< code-toggle file=hugo >}}
[markup.goldmark.parser.attribute]
````text
## Section 1 {class=foo}
-```bash {class=foo linenos=inline}
+```sh {class=foo linenos=inline}
declare a=1
echo "${a}"
```
Whether an equation or expression appears inline, or as a block, depends on the delimiters that surround the mathematical markup. Delimiters are defined in pairs, where each pair consists of an opening and closing delimiter. The opening and closing delimiters may be the same, or different.
> [!note]
-> You can configure Hugo to render mathematical markup on the client side using the MathJax or KaTeX display engine, or you can render the markup with the [`transform.ToMath`][] function while building your site.
+> You can configure Hugo to render mathematical markup on the client side using the MathJax or KaTeX display engine, or you can render the markup with the [`transform.ToMath`][] function while building your project.
>
> The first approach is described below.
Follow these instructions to include mathematical equations and expressions in your Markdown using LaTeX markup.
Step 1
-: Enable and configure the Goldmark [passthrough extension][] in your site configuration. The passthrough extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves.
+: Enable and configure the Goldmark [passthrough extension][] in your project configuration. The passthrough extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves.
{{< code-toggle file=hugo copy=true >}}
[markup.goldmark.extensions.passthrough]
math = true
{{< /code-toggle >}}
- The configuration above enables mathematical rendering on every page unless you set the `math` parameter to `false` in front matter. To enable mathematical rendering as needed, set the `math` parameter to `false` in your site configuration, and set the `math` parameter to `true` in front matter. Use this parameter in your base template as shown in [Step 3][].
+ The configuration above enables mathematical rendering on every page unless you set the `math` parameter to `false` in front matter. To enable mathematical rendering as needed, set the `math` parameter to `false` in your project configuration, and set the `math` parameter to `true` in front matter. Use this parameter in your base template as shown in [Step 3][].
> [!note]
> The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration and JavaScript, you must double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting.
</script>
```
- The delimiters above must match the delimiters in your site configuration.
+ The delimiters above must match the delimiters in your project configuration.
Step 3
: Conditionally call the _partial_ template from the base template.
</head>
```
- The example above loads the _partial_ template if you have set the `math` parameter in front matter to `true`. If you have not set the `math` parameter in front matter, the conditional statement falls back to the `math` parameter in your site configuration.
+ The example above loads the _partial_ template if you have set the `math` parameter in front matter to `true`. If you have not set the `math` parameter in front matter, the conditional statement falls back to the `math` parameter in your project configuration.
Step 4
-: If you set the `math` parameter to `false` in your site configuration, you must set the `math` parameter to `true` in front matter. For example:
+: If you set the `math` parameter to `false` in your project configuration, you must set the `math` parameter to `true` in front matter. For example:
{{< code-toggle file=content/math-examples.md fm=true >}}
title = 'Math examples'
</script>
```
-The delimiters above must match the delimiters in your site configuration.
+The delimiters above must match the delimiters in your project configuration.
## Chemistry
1. Automatically
1. In front matter
-1. In site configuration
+1. In your project configuration
> [!note]
> Although you can use these methods in combination when defining a menu, the menu will be easier to conceptualize and maintain if you use one method throughout the site.
## Define automatically
-To automatically define a menu entry for each top-level [section](g) of your site, enable the section pages menu in your site configuration.
+To automatically define a menu entry for each top-level [section](g) of your site, enable the section pages menu in your project configuration.
{{< code-toggle file=hugo >}}
sectionPagesMenu = "main"
Access the entry with `site.Menus.main` in your templates. See [menu templates] for details.
-## Define in site configuration
+## Define in project configuration
See [configure menus](/configuration/menus/).
Localization of menu entries depends on how you define them:
- When you define menu entries [automatically] using the section pages menu, you must use translation tables to localize each entry.
-- When you define menu entries [in front matter], they are already localized based on the front matter itself. If the front matter values are insufficient, use translation tables to localize each entry.
-- When you define menu entries [in site configuration], you must create language-specific menu entries under each language key. If the names of the menu entries are insufficient, use translation tables to localize each entry.
+- When you define menu entries in [front matter], they are already localized based on the front matter itself. If the front matter values are insufficient, use translation tables to localize each entry.
+- When you define menu entries in your [project configuration], you must create language-specific menu entries under each language key. If the names of the menu entries are insufficient, use translation tables to localize each entry.
### Create language-specific menu entries
The `identifier` depends on how you define menu entries:
- If you define the menu entry [automatically] using the section pages menu, the `identifier` is the page's `.Section`.
-- If you define the menu entry [in site configuration] or [in front matter], set the `identifier` property to the desired value.
+- If you define the menu entry in your [project configuration] or in [front matter], set the `identifier` property to the desired value.
-For example, if you define menu entries in site configuration:
+For example, if you define menu entries in project configuration:
{{< code-toggle file=hugo >}}
[[menus.main]]
To track down missing translation strings, run Hugo with the `--printI18nWarnings` flag:
```sh
-hugo --printI18nWarnings | grep i18n
+hugo build --printI18nWarnings | grep i18n
i18n|MISSING_TRANSLATION|en|wordCount
```
[config]: /configuration/
[configuration directory]: /configuration/introduction/#configuration-directory
[example menu template]: /templates/menu/#example
+[front matter]: /content-management/menus/#define-in-front-matter
[i18func]: /functions/lang/translate/
-[in front matter]: /content-management/menus/#define-in-front-matter
-[in site configuration]: /content-management/menus/#define-in-site-configuration
[lang.FormatAccounting]: /functions/lang/formataccounting/
[lang.FormatCurrency]: /functions/lang/formatcurrency/
[lang.FormatNumber]: /functions/lang/formatnumber/
[lang.FormatNumberCustom]: /functions/lang/formatnumbercustom/
[lang.FormatPercent]: /functions/lang/formatpercent/
[lang.Merge]: /functions/lang/merge/
+[project configuration]: /content-management/menus/#define-in-project-configuration
## Path breakdown in Hugo
-The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseURL = "https://example.org/"` in your [site's configuration file][config].
+The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseURL = "https://example.org/"` in your [project configuration][config].
### Index pages: `_index.md`
> [!note]
> This behavior is limited to Markdown content. Shared page resources for other [content formats] are copied into each language bundle.
-Consider this site configuration:
+Consider this project configuration:
{{< code-toggle file=hugo >}}
defaultContentLanguage = 'de'
>
> You can also configure Hugo to `always` use the embedded link or image render hook, use it only as a `fallback`, or `never` use it. See [details](/configuration/markup/#renderhookslinkuseembedded).
-Although duplicating shared page resources is inefficient, you can enable this feature in your site configuration if desired:
+Although duplicating shared page resources is inefficient, you can enable this feature in your project configuration if desired:
{{< code-toggle file=hugo >}}
[markup.goldmark]
Hugo's security model is based on the premise that template and configuration authors are trusted, but content authors are not. This model enables generation of HTML output safe against code injection.
-To conform with this security model, creating _shortcode_ templates within content is disabled by default. If you trust your content authors, you can enable this functionality in your site's configuration:
+To conform with this security model, creating _shortcode_ templates within content is disabled by default. If you trust your content authors, you can enable this functionality in your project configuration:
{{< code-toggle file=hugo >}}
[security]
## Automatic summary
-If you do not define the summary manually or in front matter, Hugo automatically defines the summary based on the [`summaryLength`] in your site configuration.
+If you do not define the summary manually or in front matter, Hugo automatically defines the summary based on the [`summaryLength`] in your project configuration.
[`summaryLength`]: /configuration/all/#summarylength
: The language of the code to highlight. Choose from one of the [supported languages]. This value is case-insensitive.
OPTIONS
-: One or more space-separated or comma-separated key-value pairs wrapped in braces. Set default values for each option in your [site configuration]. The key names are case-insensitive.
+: One or more space-separated or comma-separated key-value pairs wrapped in braces. Set default values for each option in your [project configuration]. The key names are case-insensitive.
[supported languages]: #languages
-[site configuration]: /configuration/markup/#highlight
+[project configuration]: /configuration/markup/#highlight
For example, with this Markdown:
---
title: URL management
-description: Control the structure and appearance of URLs through front matter entries and settings in your site configuration.
+description: Control the structure and appearance of URLs through front matter entries and settings in your project configuration.
categories: []
keywords: []
aliases: [/extras/permalinks/,/extras/aliases/,/extras/urls/,/doc/redirects/,/doc/alias/,/doc/aliases/]
content/posts/post-1.md → https://example.org/posts/post-1/
```
-You can change the structure and appearance of URLs with front matter values and site configuration options.
+You can change the structure and appearance of URLs with front matter values and project configuration options.
## Front matter
{{% include "/_common/permalink-tokens.md" %}}
-## Site configuration
+## Project configuration
### Permalinks
### Defining aliases
-To add redirects to a page, list the previous paths in the [`aliases`][aliases_field] field in your front matter. Hugo resolves these to [server-relative](g) paths during the build process, accounting for the [`baseURL`][] and [content dimension](g) prefixes such as language, role, or version.
+To add redirects to a page, list the previous paths in the [`aliases`][aliases_field] field in your front matter. Hugo resolves these to [server-relative](g) paths during the build process, accounting for the [`baseURL`][] and [content dimension](g) prefixes such as language, version, or role.
{{< code-toggle file=content/examples/example-1.en.md fm=true >}}
title = 'Example 1'
See the [`Aliases`][aliases_method] method page for a complete example of how to iterate through pages to generate these rules.
-If you implement server-side redirects, you should disable the generation of individual HTML files by setting [`disableAliases`][] to `true` in your site configuration. This setting only prevents the generation of the physical HTML files; the `Aliases` method on a `Page` object remains available for use in your configuration templates.
+If you implement server-side redirects, you should disable the generation of individual HTML files by setting [`disableAliases`][] to `true` in your project configuration. This setting only prevents the generation of the physical HTML files; the `Aliases` method on a `Page` object remains available for use in your configuration templates.
[`baseURL`]: /configuration/all/#baseurl
[`disableAliases`]: /configuration/all/#disablealiases
To build and install a specific release:
```sh
-CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@v0.155.3
+CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@v0.156.0
```
To build and install at the latest commit on the master branch:
`params.minversion`|Applicable to the quick start page: the minimum Hugo version required|
`params.permalink`|Reserved for use by the news content adapter|
`params.reference (used in glossary term)`|Applicable to glossary entries: a URL for additional information|
-`params.searchable`|Whether to add the content of this page to the search index. The default value is cascaded down from the site configuration; `true` if the page kind is `page`, and `false` if the page kind is one of `home`, `section`, `taxonomy`, or `term`. Add this field to override the default value.|
+`params.searchable`|Whether to add the content of this page to the search index. The default value is cascaded down from the project configuration; `true` if the page kind is `page`, and `false` if the page kind is one of `home`, `section`, `taxonomy`, or `term`. Add this field to override the default value.|
`params.show_publish_date`|Whether to show the `publishDate` when rendering the page|
`weight`|The page weight|
`aliases`|Previous URLs used to access this page|
```
````
-### Site configuration
+### Project configuration
-Use the [code-toggle shortcode](#code-toggle) to include site configuration examples:
+Use the [code-toggle shortcode](#code-toggle) to include project configuration examples:
```text
{{</* code-toggle file=hugo */>}}
### code-toggle
-Use the `code-toggle` shortcode to display examples of site configuration, front matter, or data files. This shortcode takes these arguments:
+Use the `code-toggle` shortcode to display examples of project configuration, front matter, or data files. This shortcode takes these arguments:
config
-: (`string`) The section of `site.Data.docs.config` to render.
+: (`string`) The section of `hugo.Data.docs.config` to render.
copy
: (`bool`) Whether to display a copy-to-clipboard button. Default is `false`.
datakey:
-: (`string`) The section of `site.Data.docs` to render.
+: (`string`) The section of `hugo.Data.docs` to render.
file
-: (`string`) The file name to display above the rendered code. Omit the file extension for site configuration examples.
+: (`string`) The file name to display above the rendered code. Omit the file extension for project configuration examples.
fm
: (`bool`) Whether to render the code as front matter. Default is `false`.
skipHeader
-: (`bool`) Whether to omit top-level key(s) when rendering a section of `site.Data.docs.config`.
+: (`bool`) Whether to omit top-level key(s) when rendering a section of `hugo.Data.docs.config`.
```text
{{</* code-toggle file=hugo copy=true */>}}
aliases: [/functions/isset]
---
-For example, consider this site configuration:
+For example, consider this project configuration:
{{< code-toggle file=hugo >}}
[params]
<a href="https://example.org?a=1&b=2">Link</a>
```
-You can also pass in a map from your site configuration or front matter. For example:
+You can also pass in a map from your project configuration or front matter. For example:
{{< code-toggle file=content/example.md fm=true >}}
title = 'Example'
## Sort a slice
-The examples below assume this site configuration:
+The examples below assume this project configuration:
{{< code-toggle file=hugo >}}
[params]
## Sort a map
-The examples below assume this site configuration:
+The examples below assume this project configuration:
{{< code-toggle file=hugo >}}
[params.authors.a]
```go-html-template
{{ $pages := where .Site.RegularPages "Section" "books" }}
-{{ $books := where .Site.Data.books "genres" "suspense" }}
+{{ $books := where hugo.Data.books "genres" "suspense" }}
```
## Arguments
{{ $pages := where .Site.RegularPages "Section" "in" .Site.MainSections }}
```
-With this construct, a theme author can instruct users to specify their main sections in the site configuration:
+With this construct, a theme author can instruct users to specify their main sections in their project configuration:
{{< code-toggle file=hugo >}}
mainSections = ['blog','galleries']
{{< /code-toggle >}}
-If `mainSections` is not defined in the site configuration, the `MainSections` method returns a slice with one element---the top-level section with the most pages.
+If `mainSections` is not defined in your project configuration, the `MainSections` method returns a slice with one element---the top-level section with the most pages.
## Boolean/undefined comparison
There's one key exception where you can skip this step: you have committed your `resources` directory to your repository. This is only possible if:
- You have not changed Hugo's default asset cache location.
-- You have not set [`useResourceCacheWhen`][] to never in your sites configuration.
+- You have not set [`useResourceCacheWhen`][] to never in your project configuration.
By committing the `resources` directory, you're providing the pre-built CSS files directly to your CI/CD platform, so it doesn't need to run the Sass compilation itself.
: Install the Tailwind CSS CLI v4.0 or later:
```sh {copy=true}
- npm install --save-dev tailwindcss @tailwindcss/cli
+ npm install --save-dev tailwindcss @tailwindcss/cli @tailwindcss/typography
```
The Tailwind CSS CLI is also available as a [standalone executable]. You must install it outside of your project directory and ensure its path is included in your system's `PATH` environment variable.
[standalone executable]: https://github.com/tailwindlabs/tailwindcss/releases/latest
Step 2
-: Add this to your site configuration:
+: Add this to your project configuration:
{{< code-toggle file=hugo copy=true >}}
[build]
```css {file="assets/css/main.css" copy=true}
@import "tailwindcss";
+ @plugin "@tailwindcss/typography";
@source "hugo_stats.json";
```
---
```go-html-template
-<pre>{{ debug.Dump site.Data.books }}</pre>
+<pre>{{ debug.Dump hugo.Data.books }}</pre>
```
```json
Use the `--logLevel info` command line flag when you build the site.
```sh
-hugo --logLevel info
+hugo build --logLevel info
```
The results are displayed in the console at the end of the build. You can have as many timers as you want and if you don't stop them, they will be stopped at the end of build.
{{% include "/_common/functions/fmt/format-string.md" %}}
-The `erroridf` function evaluates the format string, then prints the result to the ERROR log and fails the build. Unlike the [`errorf`] function, you may suppress errors logged by the `erroridf` function by adding the message ID to the `ignoreLogs` array in your site configuration.
+The `erroridf` function evaluates the format string, then prints the result to the ERROR log and fails the build. Unlike the [`errorf`] function, you may suppress errors logged by the `erroridf` function by adding the message ID to the `ignoreLogs` array in your project configuration.
This template code:
```text
ERROR You should consider fixing this.
-You can suppress this error by adding the following to your site configuration:
+You can suppress this error by adding the following to your project configuration:
ignoreLogs = ['error-42']
```
{{% include "/_common/functions/fmt/format-string.md" %}}
-The `warnidf` function evaluates the format string, then prints the result to the WARNING log. Unlike the [`warnf`] function, you may suppress warnings logged by the `warnidf` function by adding the message ID to the `ignoreLogs` array in your site configuration.
+The `warnidf` function evaluates the format string, then prints the result to the WARNING log. Unlike the [`warnf`] function, you may suppress warnings logged by the `warnidf` function by adding the message ID to the `ignoreLogs` array in your project configuration.
This template code:
```text
WARN You should consider fixing this.
-You can suppress this warning by adding the following to your site configuration:
+You can suppress this warning by adding the following to your project configuration:
ignoreLogs = ['warning-42']
```
--- /dev/null
+---
+title: hugo.Data
+description: Returns a data structure composed from the files in the data directory.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: map
+ signatures: [hugo.Data]
+---
+
+{{< new-in 0.156.0 />}}
+
+Use the `hugo.Data` function to access data within the `data` directory, or within any directory [mounted] to the `data` directory. Supported data formats include JSON, TOML, YAML, and XML.
+
+> [!note]
+> Although Hugo can unmarshal CSV files with the [`transform.Unmarshal`] function, do not place CSV files in the `data` directory. You cannot access data within CSV files using this method.
+
+Consider this `data` directory:
+
+```text
+data/
+├── books/
+│ ├── fiction.yaml
+│ └── nonfiction.yaml
+├── films.json
+├── paintings.xml
+└── sculptures.toml
+```
+
+And these data files:
+
+```yaml {file="data/books/fiction.yaml"}
+- title: The Hunchback of Notre Dame
+ author: Victor Hugo
+ isbn: 978-0140443530
+- title: Les Misérables
+ author: Victor Hugo
+ isbn: 978-0451419439
+```
+
+```yaml {file="data/books/nonfiction.yaml"}
+- title: The Ancien Régime and the Revolution
+ author: Alexis de Tocqueville
+ isbn: 978-0141441641
+- title: Interpreting the French Revolution
+ author: François Furet
+ isbn: 978-0521280495
+```
+
+Access the data by [chaining](g) the [identifiers](g):
+
+```go-html-template
+{{ range $category, $books := hugo.Data.books }}
+ <p>{{ $category | title }}</p>
+ <ul>
+ {{ range $books }}
+ <li>{{ .title }} ({{ .isbn }})</li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+Hugo renders this to:
+
+```html
+<p>Fiction</p>
+<ul>
+ <li>The Hunchback of Notre Dame (978-0140443530)</li>
+ <li>Les Misérables (978-0451419439)</li>
+</ul>
+<p>Nonfiction</p>
+<ul>
+ <li>The Ancien Régime and the Revolution (978-0141441641)</li>
+ <li>Interpreting the French Revolution (978-0521280495)</li>
+</ul>
+```
+
+To limit the listing to fiction, and sort by title:
+
+```go-html-template
+<ul>
+ {{ range sort hugo.Data.books.fiction "title" }}
+ <li>{{ .title }} ({{ .author }})</li>
+ {{ end }}
+</ul>
+```
+
+To find a fiction book by ISBN:
+
+```go-html-template
+{{ range where hugo.Data.books.fiction "isbn" "978-0140443530" }}
+ <li>{{ .title }} ({{ .author }})</li>
+{{ end }}
+```
+
+In the template examples above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function. For example:
+
+```go-html-template
+{{ index hugo.Data.books "historical-fiction" }}
+```
+
+[`index`]: /functions/collections/indexfunction/
+[`transform.Unmarshal`]: /functions/transform/unmarshal/
+[mounted]: /configuration/module/#mounts
Command|Environment
:--|:--
-`hugo`|`production`
-`hugo --environment staging`|`staging`
+`hugo build`|`production`
+`hugo build --environment staging`|`staging`
`hugo server`|`development`
`hugo server --environment staging`|`staging`
---
```go-html-template
-{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.155.3">
+{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.156.0">
```
signatures: [hugo.IsMultihost]
---
-Site configuration:
+Project configuration:
{{< code-toggle file=hugo >}}
defaultContentLanguage = 'de'
signatures: [hugo.IsMultilingual]
---
-Site configuration:
+Project configuration:
{{< code-toggle file=hugo >}}
defaultContentLanguage = 'de'
--- /dev/null
+---
+title: hugo.Sites
+description: Returns a collection of all sites for all dimensions.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: page.Sites
+ signatures: [hugo.Sites]
+---
+
+{{< new-in 0.156.0 />}}
+
+{{% include "/_common/functions/hugo/sites-collection.md" %}}
+
+With this project configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = true
+defaultContentVersionInSubdir = true
+
+[languages.de]
+contentDir = 'content/de'
+languageCode = 'de-DE'
+languageDirection = 'ltr'
+languageName = 'Deutsch'
+title = 'Projekt Dokumentation'
+weight = 1
+
+[languages.en]
+contentDir = 'content/en'
+languageCode = 'en-US'
+languageDirection = 'ltr'
+languageName = 'English'
+title = 'Project Documentation'
+weight = 2
+
+[versions.'v1.0.0']
+[versions.'v2.0.0']
+[versions.'v3.0.0']
+{{< /code-toggle >}}
+
+This template:
+
+```go-html-template
+<ul>
+ {{ range hugo.Sites }}
+ <li><a href="{{ .Home.RelPermalink }}">{{ .Title }} {{ .Version.Name }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Produces a list of links to each home page:
+
+```html
+<ul>
+ <li><a href="/v3.0.0/de/">Projekt Dokumentation v3.0.0</a></li>
+ <li><a href="/v2.0.0/de/">Projekt Dokumentation v2.0.0</a></li>
+ <li><a href="/v1.0.0/de/">Projekt Dokumentation v1.0.0</a></li>
+ <li><a href="/v3.0.0/en/">Project Documentation v3.0.0</a></li>
+ <li><a href="/v2.0.0/en/">Project Documentation v2.0.0</a></li>
+ <li><a href="/v1.0.0/en/">Project Documentation v1.0.0</a></li>
+</ul>
+```
+
+To render a link to the home page of the [default site](g):
+
+```go-html-template
+{{ with hugo.Sites.Default }}
+ <a href="{{ .Home.RelPermalink }}">{{ .Title }}</a>
+{{ end }}
+```
+
+This is equivalent to:
+
+```go-html-template
+{{ with index hugo.Sites 0 }}
+ <a href="{{ .Home.RelPermalink }}">{{ .Title }}</a>
+{{ end }}
+```
---
```go-html-template
-{{ hugo.Version }} → 0.155.3
+{{ hugo.Version }} → 0.156.0
```
> [!note]
> Of the formats supported by Hugo's imaging pipeline, only PNG and WebP have an alpha channel to support transparency. If your source image has a different format and you require transparent masked areas, convert it to either PNG or WebP as shown in the example below.
-When applying a mask to a non-transparent image format such as JPEG, the masked areas will be filled with the color specified by the `bgColor` parameter in your [site configuration]. You can override that color with a `Process` image filter:
+When applying a mask to a non-transparent image format such as JPEG, the masked areas will be filled with the color specified by the `bgColor` parameter in your [project configuration]. You can override that color with a `Process` image filter:
```go-html-template
{{ $filter := images.Process "#00ff00" }}
[`Filter`]: /methods/resource/filter/
[`images.Filter`]: /functions/images/filter/
-[site configuration]: /configuration/imaging/
+[project configuration]: /configuration/imaging/
```
Step 3
-: Add the babel executable to Hugo's `security.exec.allow` list in your site configuration:
+: Add the babel executable to Hugo's `security.exec.allow` list in your project configuration:
{{< code-toggle file=hugo >}}
[security.exec]
import * as data from 'my/module/data.json';
```
-Any imports in a file outside `assets` or that does not resolve to a component inside `assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`.
+Any imports in a file outside `assets` or that does not resolve to a component inside `assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo build`.
Also note the new `params` option that can be passed from template to your JS files, e.g.:
Use the `js.Build` function to include Node.js dependencies.
-Any imports in a file outside `assets` or that does not resolve to a component inside `assets` will be resolved by [esbuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`.
+Any imports in a file outside `assets` or that does not resolve to a component inside `assets` will be resolved by [esbuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo build`.
The start directory for resolving npm packages (aka. packages that live inside a `node_modules` directory) is always the main project directory.
If the key is not found in the translation table for the `defaultContentLanguage`, the `lang.Translate` function returns an empty string.
> [!note]
-> To list missing and fallback translations, set [`printI18nWarnings`][] to `true` in your site configuration, or use the `--printI18nWarnings` flag when building your site.
+> To list missing and fallback translations, set [`printI18nWarnings`][] to `true` in your project configuration, or use the `--printI18nWarnings` flag when building your project.
>
-> To render placeholders for missing and fallback translations, set [`enableMissingTranslationPlaceholders`][] to `true` in your site configuration.
+> To render placeholders for missing and fallback translations, set [`enableMissingTranslationPlaceholders`][] to `true` in your project configuration.
## Translation tables
i18n/pt-BR.toml
```
-The base name must match the [`languageCode`][] or [language key][] as defined in your site configuration. Hugo selects the translation table based on the `languageCode`, falling back to the language key if a matching translation table does not exist.
+The base name must match the [`languageCode`][] or [language key][] as defined in your project configuration. Hugo selects the translation table based on the `languageCode`, falling back to the language key if a matching translation table does not exist.
Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7][] are also supported. You may omit the `art-x-` prefix for brevity. For example:
- The `CI` environment variable
- Any environment variable beginning with `HUGO_`
-To access other environment variables, adjust your site configuration. For example, to allow access to the `HOME` and `USER` environment variables:
+To access other environment variables, adjust your project configuration. For example, to allow access to the `HOME` and `USER` environment variables:
{{< code-toggle file=hugo >}}
[security.funcs]
{{ getenv "USER" }} → victor
```
-You can pass values when building your site:
+You can pass values when building your project:
```sh
MY_VAR1=foo MY_VAR2=bar hugo
Hugo publishes the resource to the target path when you call its [`Publish`], [`Permalink`], or [`RelPermalink`] methods.
-Let's say you have a CSS file that you wish to populate with values from your site configuration:
+Let's say you have a CSS file that you wish to populate with values from your project configuration:
```go-html-template {file="assets/css/template.css"}
body {
}
```
-And your site configuration contains:
+And your project configuration contains:
{{< code-toggle file=hugo >}}
[params.style]
```json
{
"build_date": "2026-01-11T11:27:49-08:00",
- "hugo_version": "0.155.3",
+ "hugo_version": "0.156.0",
"last_modified": "2026-01-11T11:27:59-08:00"
}
```
{{< new-in 0.141.0 >}}
The `Err` method on the returned resource was removed in v0.141.0.
-Use the [`try`] statement instead, as shown in the [error handling] example below.
-
+Use the [`try`](/functions/go-template/try) statement instead, as shown in the [error handling](#error-handling) example below.
{{< /new-in >}}
```go-html-template
For example, you will see the error above if you attempt to download an executable.
-Although the allowlist contains entries for common media types, you may encounter situations where Hugo is unable to resolve the media type of a file that you know to be safe. In these situations, edit your site configuration to add the media type to the allowlist. For example:
+Although the allowlist contains entries for common media types, you may encounter situations where Hugo is unable to resolve the media type of a file that you know to be safe. In these situations, edit your project configuration to add the media type to the allowlist. For example:
{{< code-toggle file=hugo >}}
[security.http]
- An _addition_ to the allowlist; it does not _replace_ the allowlist
- An array of [regular expressions](g)
-[allowlist]: https://en.wikipedia.org/wiki/Whitelist
-[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
-
[`try`]: /functions/go-template/try
+[allowlist]: https://en.wikipedia.org/wiki/Whitelist
[configure file caches]: /configuration/caches/
+[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
[error handling]: #error-handling
HUGO_ENVIRONMENT
: The current Hugo environment, set with the `--environment` command line flag.
-Default is `production` for `hugo` and `development` for `hugo server`.
+Default is `production` for `hugo build` and `development` for `hugo server`.
HUGO_PUBLISHDIR
: The absolute path to the publish directory, typically `public`. This value points to a directory on disk, even when rendering to memory with the `--renderToMemory` command line flag.
{{ title "table of contents (TOC)" }} → Table of Contents (TOC)
```
-By default, Hugo follows the capitalization rules published in the [Associated Press Stylebook]. Change your [site configuration] if you would prefer to:
+By default, Hugo follows the capitalization rules published in the [Associated Press Stylebook]. Change your [project configuration] if you would prefer to:
- Follow the capitalization rules published in the [Chicago Manual of Style]
- Capitalize the first letter of every word
[Associated Press Stylebook]: https://www.apstylebook.com/
[Chicago Manual of Style]: https://www.chicagomanualofstyle.org/home.html
-[site configuration]: /configuration/all/#title-case-style
+[project configuration]: /configuration/all/#title-case-style
## Examples
-The examples below help visualize template execution and require a `debug` parameter set to `true` in your site configuration:
+The examples below help visualize template execution and require a `debug` parameter set to `true` in your project configuration:
{{< code-toggle file=hugo >}}
[params]
{{% include "/_common/parsable-date-time-strings.md" %}}
-To override the default time zone, set the [`timeZone`] in your site configuration or provide a second argument to the `time.AsTime` function. For example:
+To override the default time zone, set the [`timeZone`] in your project configuration or provide a second argument to the `time.AsTime` function. For example:
```go-html-template
{{ time.AsTime "15 Oct 2023" "America/Los_Angeles" }}
1. The time zone offset in the date/time string
1. The time zone provided as the second argument to the `time.AsTime` function
-1. The time zone specified in your site configuration
+1. The time zone specified in your project configuration
1. The `Etc/UTC` time zone
[IANA Time Zone database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
{{% include "/_common/parsable-date-time-strings.md" %}}
-To override the default time zone, set the [`timeZone`] in your site configuration. The order of precedence for determining the time zone is:
+To override the default time zone, set the [`timeZone`] in your project configuration. The order of precedence for determining the time zone is:
1. The time zone offset in the date/time string
-1. The time zone specified in your site configuration
+1. The time zone specified in your project configuration
1. The `Etc/UTC` time zone
[`timeZone`]: /configuration/all/#timezone
See the list of [emoji shortcodes] for available emoticons.
-The `emojify` function can be called in your templates but not directly in your content files by default. For emojis in content files, set [`enableEmoji`] to `true` in your site's configuration. Then you can write emoji shorthand directly into your content files;
+The `emojify` function can be called in your templates but not directly in your content files by default. For emojis in content files, set [`enableEmoji`] to `true` in your project configuration. Then you can write emoji shorthand directly into your content files;
```text
I :heart: Hugo!
: (`string`) The language of the code to highlight. Choose from one of the [supported languages]. This value is case-insensitive.
OPTIONS
-: (`map or string`) A map or comma-separated key-value pairs wrapped in quotation marks. Set default values for each option in your [site configuration]. The key names are case-insensitive.
+: (`map or string`) A map or comma-separated key-value pairs wrapped in quotation marks. Set default values for each option in your [project configuration]. The key names are case-insensitive.
-[site configuration]: /configuration/markup#highlight
+[project configuration]: /configuration/markup#highlight
[supported languages]: /content-management/syntax-highlighting#languages
## Examples
Note that the above requires some additional plugins to be installed:
-```bash
+```sh
npm i sanity-plugin-media @sanity/code-input
```
Instead of client-side JavaScript rendering of mathematical markup using MathJax or KaTeX, create a passthrough render hook which calls the `transform.ToMath` function.
Step 1
-: Enable and configure the Goldmark [passthrough extension][] in your site configuration. The passthrough extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves.
+: Enable and configure the Goldmark [passthrough extension][] in your project configuration. The passthrough extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves.
[passthrough extension]: /configuration/markup/#passthrough
Use this function with both monolingual and multilingual configurations. The URL returned by this function depends on:
- Whether the input begins with a slash (`/`)
-- The `baseURL` in your site configuration
+- The `baseURL` in your project configuration
- The language prefix, if any
-This is the site configuration for the examples that follow:
+This is the project configuration for the examples that follow:
{{< code-toggle file=hugo >}}
defaultContentLanguage = 'en'
## Input does not begin with a slash
-If the input does not begin with a slash, the path in the resulting URL will be relative to the `baseURL` in your site configuration.
+If the input does not begin with a slash, the path in the resulting URL will be relative to the `baseURL` in your project configuration.
When rendering the `en` site with `baseURL = https://example.org/`
## Input begins with a slash
-If the input begins with a slash, the path in the resulting URL will be relative to the protocol+host of the `baseURL` in your site configuration.
+If the input begins with a slash, the path in the resulting URL will be relative to the protocol+host of the `baseURL` in your project configuration.
When rendering the `en` site with `baseURL = https://example.org/`
With multilingual configurations, use the [`urls.AbsLangURL`] function instead. The URL returned by this function depends on:
- Whether the input begins with a slash (`/`)
-- The `baseURL` in your site configuration
+- The `baseURL` in your project configuration
## Input does not begin with a slash
-If the input does not begin with a slash, the path in the resulting URL will be relative to the `baseURL` in your site configuration.
+If the input does not begin with a slash, the path in the resulting URL will be relative to the `baseURL` in your project configuration.
With `baseURL = https://example.org/`
## Input begins with a slash
-If the input begins with a slash, the path in the resulting URL will be relative to the protocol+host of the `baseURL` in your site configuration.
+If the input begins with a slash, the path in the resulting URL will be relative to the protocol+host of the `baseURL` in your project configuration.
With `baseURL = https://example.org/`
## Sanitizing logic
-With the default Markdown renderer, Goldmark, the sanitizing logic is controlled by your site configuration:
+With the default Markdown renderer, Goldmark, the sanitizing logic is controlled by your project configuration:
{{< code-toggle file=hugo >}}
[markup.goldmark.parser]
Use this function with both monolingual and multilingual configurations. The URL returned by this function depends on:
- Whether the input begins with a slash (`/`)
-- The `baseURL` in your site configuration
+- The `baseURL` in your project configuration
- The language prefix, if any
-This is the site configuration for the examples that follow:
+This is the project configuration for the examples that follow:
{{< code-toggle file=hugo >}}
defaultContentLanguage = 'en'
## Input does not begin with a slash
-If the input does not begin with a slash, the resulting URL will be relative to the `baseURL` in your site configuration.
+If the input does not begin with a slash, the resulting URL will be relative to the `baseURL` in your project configuration.
When rendering the `en` site with `baseURL = https://example.org/`
## Input begins with a slash
-If the input begins with a slash, the resulting URL will be relative to the protocol+host of the `baseURL` in your site configuration.
+If the input begins with a slash, the resulting URL will be relative to the protocol+host of the `baseURL` in your project configuration.
When rendering the `en` site with `baseURL = https://example.org/`
With multilingual configurations, use the [`urls.RelLangURL`] function instead. The URL returned by this function depends on:
- Whether the input begins with a slash (`/`)
-- The `baseURL` in your site configuration
+- The `baseURL` in your project configuration
## Input does not begin with a slash
-If the input does not begin with a slash, the resulting URL will be relative to the `baseURL` in your site configuration.
+If the input does not begin with a slash, the resulting URL will be relative to the `baseURL` in your project configuration.
With `baseURL = https://example.org/`
## Input begins with a slash
-If the input begins with a slash, the resulting URL will be relative to the protocol+host of the `baseURL` in your site configuration.
+If the input begins with a slash, the resulting URL will be relative to the protocol+host of the `baseURL` in your project configuration.
With `baseURL = https://example.org/`
Use the `urlize` function to create a link to a [term page](g).
-Consider this site configuration:
+Consider this project configuration:
{{< code-toggle file=hugo >}}
[taxonomies]
aliases: [/overview/source-directory/]
---
-Each Hugo project is a directory, with subdirectories that contribute to the content, structure, behavior, and presentation of your site.
+Each Hugo project is a directory, with subdirectories that contribute to content, structure, behavior, and presentation.
-## Site skeleton
+## Project skeleton
-Hugo generates a project skeleton when you create a new site. For example, this command:
+Hugo generates a project skeleton when you create a new project. For example, this command:
```sh
-hugo new site my-site
+hugo new project my-project
```
Creates this directory structure:
```txt
-my-site/
+my-project/
├── archetypes/
│ └── default.md
├── assets/
├── layouts/
├── static/
├── themes/
-└── hugo.toml <-- site configuration
+└── hugo.toml <-- project configuration
```
-Depending on requirements, you may wish to organize your site configuration into subdirectories:
+Depending on requirements, you may wish to organize your project configuration into subdirectories:
```txt
-my-site/
+my-project/
├── archetypes/
│ └── default.md
├── assets/
-├── config/ <-- site configuration
+├── config/ <-- project configuration
│ └── _default/
│ └── hugo.toml
├── content/
└── themes/
```
-When you build your site, Hugo creates a `public` directory, and typically a `resources` directory as well:
+When you build your project, Hugo creates a `public` directory, and typically a `resources` directory as well:
```txt
-my-site/
+my-project/
├── archetypes/
│ └── default.md
├── assets/
├── data/
├── i18n/
├── layouts/
-├── public/ <-- created when you build your site
-├── resources/ <-- created when you build your site
+├── public/ <-- created when you build your project
+├── resources/ <-- created when you build your project
├── static/
└── themes/
```
## Directories
-Each of the subdirectories contributes to the content, structure, behavior, or presentation of your site.
+Each of the subdirectories contributes to content, structure, behavior, or presentation.
archetypes
: The `archetypes` directory contains templates for new content. See [details](/content-management/archetypes/).
: The `assets` directory contains global resources typically passed through an asset pipeline. This includes resources such as images, CSS, Sass, JavaScript, and TypeScript. See [details](/hugo-pipes/introduction/).
config
-: The `config` directory contains your site configuration, possibly split into multiple subdirectories and files. For projects with minimal configuration or projects that do not need to behave differently in different environments, a single configuration file named `hugo.toml` in the root of the project is sufficient. See [details](/configuration/introduction/#configuration-directory).
+: The `config` directory contains your project configuration, possibly split into multiple subdirectories and files. For projects with minimal configuration or projects that do not need to behave differently in different environments, a single configuration file named `hugo.toml` in the root of the project is sufficient. See [details](/configuration/introduction/#configuration-directory).
content
-: The `content` directory contains the markup files (typically Markdown) and page resources that comprise the content of your site. See [details](/content-management/organization/).
+: The `content` directory contains the markup files (typically Markdown) and page resources that comprise the content of your project. See [details](/content-management/organization/).
data
: The `data` directory contains data files (JSON, TOML, YAML, or XML) that augment content, configuration, localization, and navigation. See [details](/content-management/data-sources/).
i18n
-: The `i18n` directory contains translation tables for multilingual sites. See [details](/content-management/multilingual/).
+: The `i18n` directory contains translation tables for multilingual projects. See [details](/content-management/multilingual/).
layouts
: The `layouts` directory contains templates to transform content, data, and resources into a complete website. See [details](/templates/).
public
-: The `public` directory contains the published website, generated when you run the `hugo` or `hugo server` commands. Hugo recreates this directory and its content as needed. See [details](/getting-started/usage/#build-your-site).
+: The `public` directory contains the published website, generated when you run the `hugo build` or `hugo server` commands. Hugo recreates this directory and its content as needed. See [details](/getting-started/usage/#build-your-project).
resources
-: The `resources` directory contains cached output from Hugo's asset pipelines, generated when you run the `hugo` or `hugo server` commands. By default this cache directory includes CSS and images. Hugo recreates this directory and its content as needed.
+: The `resources` directory contains cached output from Hugo's asset pipelines, generated when you run the `hugo build` or `hugo server` commands. By default this cache directory includes CSS and images. Hugo recreates this directory and its content as needed.
static
-: The `static` directory contains files that will be copied to the `public` directory when you build your site. For example: `favicon.ico`, `robots.txt`, and files that verify site ownership. Before the introduction of [page bundles](g) and [asset pipelines](/hugo-pipes/introduction/), the `static` directory was also used for images, CSS, and JavaScript.
+: The `static` directory contains files that will be copied to the `public` directory when you build your project. For example: `favicon.ico`, `robots.txt`, and files that verify website ownership. Before the introduction of [page bundles](g) and [asset pipelines](/hugo-pipes/introduction/), the `static` directory was also used for images, CSS, and JavaScript.
themes
: The `themes` directory contains one or more [themes](g), each in its own subdirectory.
```text
home/
└── user/
- ├── my-site/
+ ├── my-project/
│ ├── content/
│ │ ├── books/
│ │ │ ├── _index.md
└── film-2.md
```
-You can include the shared content when you build your site using mounts. In your site configuration:
+You can include the shared content using mounts. In your project configuration:
{{< code-toggle file=hugo >}}
[[module.mounts]]
```text
home/
└── user/
- └── my-site/
+ └── my-project/
├── content/
│ ├── books/
│ │ ├── _index.md
---
title: Quick start
-description: Create a Hugo site in minutes.
+description: Create your first Hugo project.
categories: []
keywords: []
params:
- minVersion: v0.146.0
+ minVersion: v0.156.0
weight: 10
aliases: [/quickstart/,/overview/quickstart/]
---
In this tutorial you will:
-1. Create a site
+1. Create a project
1. Add content
-1. Configure the site
-1. Publish the site
+1. Configure the project
+1. Publish the project
## Prerequisites
You must also be comfortable working from the command line.
-## Create a site
+## Create a project
### Commands
>
> - Do not use the Command Prompt
> - Do not use Windows PowerShell
-> - Run these commands from [PowerShell] or a Linux terminal such as WSL or Git > Bash
+> - Run these commands from [PowerShell][] or a Linux terminal such as WSL or Git > Bash
>
-> PowerShell and Windows PowerShell [are different applications].
+> PowerShell and Windows PowerShell [are different applications][].
Verify that you have installed Hugo {{% param "minVersion" %}} or later.
hugo version
```
-Run these commands to create a Hugo site with the [Ananke] theme. The next section provides an explanation of each command.
+Run these commands to create a Hugo project with the [Ananke][] theme. The next section provides an explanation of each command.
```text
-hugo new site quickstart
+hugo new project quickstart
cd quickstart
git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
hugo server
```
-View your site at the URL displayed in your terminal. Press `Ctrl + C` to stop Hugo's development server.
+View your project at the URL displayed in your terminal. Press `Ctrl + C` to stop Hugo's development server.
### Explanation of commands
-Create the [site skeleton] for your project in the `quickstart` directory.
+Create the [project skeleton][] for your project in the `quickstart` directory.
```text
-hugo new site quickstart
+hugo new project quickstart
```
Change the current directory to the root of your project.
git init
```
-Clone the [Ananke] theme into the `themes` directory, adding it to your project as a [Git submodule].
+Clone the [Ananke][] theme into the `themes` directory, adding it to your project as a [Git submodule][].
```text
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
```
-Append a line to the site configuration file, indicating the current theme.
+Append a line to your project configuration file, indicating the current theme.
```text
echo "theme = 'ananke'" >> hugo.toml
```
-Start Hugo's development server to view the site.
+Start Hugo's development server.
```text
hugo server
## Add content
-Add a new page to your site.
+Add a new page to your project.
```text
hugo new content content/posts/my-first-post.md
+++
```
-Notice the `draft` value in the [front matter] is `true`. By default, Hugo does not publish draft content when you build the site. Learn more about [draft, future, and expired content].
+Notice the `draft` value in the [front matter][] is `true`. By default, Hugo does not publish draft content when you build the project. Learn more about [draft, future, and expired content][].
-Add some [Markdown] to the body of the post, but do not change the `draft` value.
+Add some [Markdown][] to the body of the post, but do not change the `draft` value.
```text
+++
Visit the [Hugo](https://gohugo.io) website!
```
-Save the file, then start Hugo's development server to view the site. You can run either of the following commands to include draft content.
+Save the file, then start Hugo's development server. You can run either of the following commands to include draft content.
```text
hugo server --buildDrafts
hugo server -D
```
-View your site at the URL displayed in your terminal. Keep the development server running as you continue to add and change content.
+View your project at the URL displayed in your terminal. Keep the development server running as you continue to add and change content.
When satisfied with your new content, set the front matter `draft` parameter to `false`.
> [!note]
-> Hugo's rendering engine conforms to the CommonMark [specification] for Markdown. The CommonMark organization provides a useful [live testing tool] powered by the reference implementation.
+> Hugo's rendering engine conforms to the CommonMark [specification][] for Markdown. The CommonMark organization provides a useful [live testing tool][] powered by the reference implementation.
-## Configure the site
+## Configure the project
-With your editor, open the [site configuration] file (`hugo.toml`) in the root of your project.
+With your editor, open your [project configuration][] file (`hugo.toml`) in the root of your project.
```text
baseURL = 'https://example.org/'
languageCode = 'en-us'
-title = 'My New Hugo Site'
+title = 'My New Hugo Project'
theme = 'ananke'
```
Make the following changes:
-1. Set the `baseURL` for your production site. This value must begin with the protocol and end with a slash, as shown above.
-1. Set the `languageCode` to your language and region.
-1. Set the `title` for your production site.
+1. Set the `baseURL` for your project. This value must begin with the protocol and end with a slash, as shown above.
+1. Set the `languageCode` to your locale.
+1. Set the `title` for your project.
Start Hugo's development server to see your changes, remembering to include draft content.
> [!note]
> Most theme authors provide configuration guidelines and options. Make sure to visit your theme's repository or documentation site for details.
>
-> [The New Dynamic], authors of the Ananke theme, provide [documentation] for configuration and usage. They also provide a [demonstration site].
+> [The New Dynamic][], authors of the Ananke theme, provide [documentation][] for configuration and usage. They also provide a [demonstration site][].
-## Publish the site
+## Publish the project
-In this step you will _publish_ your site, but you will not _deploy_ it.
+In this step you will _publish_ your project, but you will not _deploy_ it.
-When you _publish_ your site, Hugo creates the entire static site in the `public` directory in the root of your project. This includes the HTML files, and assets such as images, CSS files, and JavaScript files.
-
-When you publish your site, you typically do _not_ want to include [draft, future, or expired content]. The command is simple.
+When you publish your project, Hugo renders all build artifacts to the `public` directory in the root of your project. This includes the HTML files for every site, along with assets such as images, CSS, and JavaScript. The command is simple.
```text
hugo
```
-To learn how to _deploy_ your site, see the [host and deploy] section.
+To learn how to _deploy_ your project, see the [host and deploy][] section.
## Ask for help
-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.
+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.
## Other resources
-For other resources to help you learn Hugo, including books and video tutorials, see the [external learning resources](/getting-started/external-learning-resources/) page.
+For other resources to help you learn Hugo, including books and video tutorials, see the [external learning resources][] page.
[Ananke]: https://github.com/theNewDynamic/gohugo-theme-ananke
[are different applications]: https://learn.microsoft.com/en-us/powershell/scripting/whats-new/differences-from-windows-powershell?view=powershell-7.3
[demonstration site]: https://gohugo-ananke-theme-demo.netlify.app/
-[site skeleton]: /getting-started/directory-structure/#site-skeleton
[documentation]: https://github.com/theNewDynamic/gohugo-theme-ananke#readme
[draft, future, and expired content]: /getting-started/usage/#draft-future-and-expired-content
-[draft, future, or expired content]: /getting-started/usage/#draft-future-and-expired-content
+[external learning resources]: /getting-started/external-learning-resources/
[forum]: https://discourse.gohugo.io/
[front matter]: /content-management/front-matter/
[Git submodule]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
[live testing tool]: https://spec.commonmark.org/dingus/
[Markdown]: https://daringfireball.net/projects/markdown
[PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows
+[project configuration]: /configuration/
+[project skeleton]: /getting-started/directory-structure/#project-skeleton
[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132
-[site configuration]: /configuration/
[specification]: https://spec.commonmark.org/
[The New Dynamic]: https://www.thenewdynamic.com/
hugo server --help
```
-## Build your site
+## Build your project
-To build your site, `cd` into your project directory and run:
+To build your project, `cd` into your project directory and run:
```sh
-hugo
+hugo build
```
-The [`hugo`] command builds your site, publishing the files to the `public` directory. To publish your site to a different directory, use the [`--destination`] flag or set [`publishDir`] in your site configuration.
+The [`hugo build`] command builds your project, publishing the files to the `public` directory. To publish your project to a different directory, use the [`--destination`] flag or set [`publishDir`] in your project configuration.
> [!note]
-> Hugo does not clear the `public` directory before building your site. Existing files are overwritten, but not deleted. This behavior is intentional to prevent the inadvertent removal of files that you may have added to the `public` directory after the build.
+> Hugo does not clear the `public` directory before building your project. Existing files are overwritten, but not deleted. This behavior is intentional to prevent the inadvertent removal of files that you may have added to the `public` directory after the build.
>
> Depending on your needs, you may wish to manually clear the contents of the `public` directory before every build.
> [!note]
> Hugo publishes descendants of draft, future, and expired [node](g) pages. To prevent publication of these descendants, use the [`cascade`] front matter field to cascade [build options] to the descendant pages.
-You can override the default behavior when running `hugo` or `hugo server` with command line flags:
+You can override the default behavior when running `hugo build` or `hugo server` with command line flags:
```sh
-hugo --buildDrafts # or -D
-hugo --buildExpired # or -E
-hugo --buildFuture # or -F
+hugo build --buildDrafts # or -D
+hugo build --buildExpired # or -E
+hugo build --buildFuture # or -F
```
-Although you can also set these values in your site configuration, it can lead to unwanted results unless all content authors are aware of, and understand, the settings.
+Although you can also set these values in your project configuration, it can lead to unwanted results unless all content authors are aware of, and understand, the settings.
> [!note]
-> As noted above, Hugo does not clear the `public` directory before building your site. Depending on the _current_ evaluation of the four conditions above, after the build your `public` directory may contain extraneous files from a previous build.
+> As noted above, Hugo does not clear the `public` directory before building your project. Depending on the _current_ evaluation of the four conditions above, after the build your `public` directory may contain extraneous files from a previous build.
>
> A common practice is to manually clear the contents of the `public` directory before each build to remove draft, expired, and future content.
## Deploy your site
> [!note]
-> As noted above, Hugo does not clear the `public` directory before building your site. Manually clear the contents of the `public` directory before each build to remove draft, expired, and future content.
+> As noted above, Hugo does not clear the `public` directory before building your project. Manually clear the contents of the `public` directory before each build to remove draft, expired, and future content.
When you are ready to deploy your site, run:
[`--destination`]: /commands/hugo/#options
[`cascade`]: /content-management/front-matter/#cascade
[`hugo server`]: /commands/hugo_server/
-[`hugo`]: /commands/hugo/
+[`hugo build`]: /commands/hugo/
[`publishDir`]: /configuration/all/#publishdir
[build options]: /content-management/build-options/
[front matter]: /content-management/front-matter/
## Configuration
-Create a deployment target in your [site configuration]. The only required parameters are [`name`] and [`url`]:
+Create a deployment target in your [project configuration]. The only required parameters are [`name`] and [`url`]:
{{< code-toggle file=hugo >}}
[deployment]
To deploy to a target:
-```bash
+```sh
hugo deploy [--target=<target name>]
```
[Google Cloud]: https://cloud.google.com/
[installation]: /installation/
[Quick Start]: /getting-started/quick-start/
-[site configuration]: /configuration/deployment/
+[project configuration]: /configuration/deployment/
- Deploying from an [Rclone](https://rclone.org) compatible operating system
- You have [installed Rclone](https://rclone.org/install/).
-**NB**: You can remove ``--interactive`` in the commands below once you are comfortable with rclone, if you wish. Also, ``--gc`` and ``--minify`` are optional in the ``hugo`` commands below.
+**NB**: You can remove `--interactive` in the commands below once you are comfortable with rclone, if you wish. Also, `--gc` and `--minify` are optional in the commands below.
## Getting started
The spoiler is that you can even deploy your entire website from any compatible OS with no configuration. Using SFTP for example:
```txt
-hugo --gc --minify
+hugo build --gc --minify
rclone sync --interactive --sftp-host sftp.example.com --sftp-user www-data --sftp-ask-password public/ :sftp:www/
```
The [Rclone docs](https://rclone.org/docs/) provide [an example of configuring Rclone to use SFTP](https://rclone.org/sftp/).
-For the next commands, we will assume you configured a remote you named ``hugo-www``
+For the next commands, we will assume you configured a remote you named `hugo-www`.
The above 'spoiler' commands could become:
```txt
-hugo --gc --minify
+hugo build --gc --minify
rclone sync --interactive public/ hugo-www:www/
```
HOST=my-server.com
DIR=my/directory/to/topologix.fr/ # the directory where your website files should go
-hugo && rsync -avz --delete public/ ${USER}@${HOST}:~/${DIR} # this will delete everything on the server that's not in the local public directory
+hugo build && rsync -avz --delete public/ ${USER}@${HOST}:~/${DIR} # this will delete everything on the server that's not in the local public directory
exit 0
```
variables:
# Application versions
DART_SASS_VERSION: 1.97.3
- GO_VERSION: 1.25.6
- HUGO_VERSION: 0.155.3
+ GO_VERSION: 1.26.0
+ HUGO_VERSION: 0.156.0
# Time zone
TZ: Europe/Oslo
# Cache
build:
commands:
- echo "Building site..."
- - hugo --gc --minify
+ - hugo build --gc --minify
artifacts:
baseDirectory: public
files:
main() {
DART_SASS_VERSION=1.97.3
- GO_VERSION=1.25.6
- HUGO_VERSION=0.155.3
- NODE_VERSION=24.13.0
+ GO_VERSION=1.26.0
+ HUGO_VERSION=0.156.0
+ NODE_VERSION=24.13.1
export TZ=Europe/Oslo
# Build the site
echo "Building the site..."
- hugo --gc --minify
+ hugo build --gc --minify
}
After that Firebase has been set in your project with [CI/CD](g). After that run:
```sh
-hugo && firebase deploy
+hugo build && firebase deploy
```
With this you will have the app initialized manually. After that you can manage and fix your GitHub workflow from <https://github.com/your-account/your-repo/actions>.
Step 2
-: In your site configuration, change the location of the image cache to the [`cacheDir`] as shown below:
+: In your project configuration, change the location of the image cache to the [`cacheDir`] as shown below:
{{< code-toggle file=hugo copy=true >}}
[caches.images]
runs-on: ubuntu-latest
env:
DART_SASS_VERSION: 1.97.3
- GO_VERSION: 1.25.6
- HUGO_VERSION: 0.155.3
- NODE_VERSION: 24.13.0
+ GO_VERSION: 1.26.0
+ HUGO_VERSION: 0.156.0
+ NODE_VERSION: 24.13.1
TZ: Europe/Oslo
steps:
- name: Checkout
hugo-
- name: Build the site
run: |
- hugo \
+ hugo build \
--gc \
--minify \
--baseURL "${{ steps.pages.outputs.base_url }}/" \
## BaseURL
-The `baseURL` in your [site configuration](/configuration/) must reflect the full URL of your GitLab pages repository if you are using the default GitLab Pages URL (e.g., `https://<YourUsername>.gitlab.io/<your-hugo-site>/`) and not a custom domain.
+The `baseURL` in your [project configuration](/configuration/) must reflect the full URL of your GitLab pages repository if you are using the default GitLab Pages URL (e.g., `https://<YourUsername>.gitlab.io/<your-hugo-site>/`) and not a custom domain.
## Configure GitLab CI/CD
variables:
# Application versions
DART_SASS_VERSION: 1.97.3
- HUGO_VERSION: 0.155.3
- NODE_VERSION: 24.13.0
+ HUGO_VERSION: 0.156.0
+ NODE_VERSION: 24.13.1
# Git
GIT_DEPTH: 0
GIT_STRATEGY: clone
TZ: Europe/Oslo
image:
- name: golang:1.25.6-bookworm
+ name: golang:1.26.0-bookworm
pages:
stage: deploy
# Build site
- echo "Building site..."
- - hugo --gc --minify --baseURL "${CI_PAGES_URL}"
+ - hugo build --gc --minify --baseURL "${CI_PAGES_URL}"
# Compress published files
- echo "Compressing published files..."
```text {file="netlify.toml" copy=true}
[build.environment]
DART_SASS_VERSION = "1.97.3"
- GO_VERSION = "1.25.6"
- HUGO_VERSION = "0.155.3"
- NODE_VERSION = "24.13.0"
+ GO_VERSION = "1.26.0"
+ HUGO_VERSION = "0.156.0"
+ NODE_VERSION = "24.13.1"
TZ = "Europe/Oslo"
[build]
publish = "public"
command = """\
git config core.quotepath false && \
- hugo --gc --minify --baseURL "${URL}"
+ hugo build --gc --minify --baseURL "${URL}"
"""
```
```text {file="netlify.toml" copy=true}
[build.environment]
DART_SASS_VERSION = "1.97.3"
- GO_VERSION = "1.25.6"
- HUGO_VERSION = "0.155.3"
- NODE_VERSION = "24.13.0"
+ GO_VERSION = "1.26.0"
+ HUGO_VERSION = "0.156.0"
+ NODE_VERSION = "24.13.1"
TZ = "Europe/Oslo"
[build]
rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" && \
export PATH="${HOME}/.local/dart-sass:${PATH}" && \
git config core.quotepath false && \
- hugo --gc --minify --baseURL "${URL}"
+ hugo build --gc --minify --baseURL "${URL}"
"""
```
- key: DART_SASS_VERSION
value: 1.97.3
- key: GO_VERSION
- value: 1.25.6
+ value: 1.26.0
- key: HUGO_VERSION
- value: 0.155.3
+ value: 0.156.0
- key: NODE_VERSION
- value: 24.13.0
+ value: 24.13.1
- key: TZ
value: Europe/Oslo
```
# Build the site
echo "Building the site..."
- hugo --gc --minify --baseURL "${RENDER_EXTERNAL_URL}"
+ hugo build --gc --minify --baseURL "${RENDER_EXTERNAL_URL}"
}
## BaseURL
-The [`baseURL`][] in your site configuration must reflect the full URL provided by SourceHut Pages if you are using the default address (e.g. `https://<YourUsername>.srht.site/`). If you want to use another domain, check the [custom domain section][] of the official documentation.
+The [`baseURL`][] in your project configuration must reflect the full URL provided by SourceHut Pages if you are using the default address (e.g. `https://<YourUsername>.srht.site/`). If you want to use another domain, check the [custom domain section][] of the official documentation.
[`baseURL`]: /configuration/all/#baseurl
[custom domain section]: https://srht.site/custom-domains
[hut]: https://sr.ht/~xenrox/hut/
```sh
-hugo
+hugo build
tar -C public -cvz . > site.tar.gz
hut init
hut pages publish -d <YourUsername>.srht.site site.tar.gz
tasks:
- package: |
cd $site
- hugo
+ hugo build
tar -C public -cvz . > ../site.tar.gz
- upload: |
hut pages publish -d $site site.tar.gz
export PATH="$HOME/.local/dart-sass:$PATH"
sass --version # Verify installation
cd $site
- hugo
+ hugo build
tar -C public -cvz . > ../site.tar.gz
- upload: |
hut pages publish -d $site site.tar.gz
main() {
DART_SASS_VERSION=1.97.3
- GO_VERSION=1.25.6
- HUGO_VERSION=0.155.3
- NODE_VERSION=24.13.0
+ GO_VERSION=1.26.0
+ HUGO_VERSION=0.156.0
+ NODE_VERSION=24.13.1
export TZ=Europe/Oslo
# Build the site
echo "Building the site"
- hugo --gc --minify --baseURL "https://${VERCEL_PROJECT_PRODUCTION_URL}"
+ hugo build --gc --minify --baseURL "https://${VERCEL_PROJECT_PRODUCTION_URL}"
}
---
title: Use Hugo Modules
-description: How to use Hugo Modules.
+description: Use modules to manage the content, layout, presentation, and behavior of your site.
categories: []
keywords: []
weight: 20
aliases: [/themes/usage/,/themes/installing/,/installing-and-using-themes/]
---
-## Prerequisite
+> [!note]
+> To work with modules you must install [Git][] and [Go][] 1.18 or later.
-{{% include "/_common/gomodules-info.md" %}}
+## Introduction
-## Initialize a new module
+{{% glossary-term module %}}
-Use `hugo mod init` to initialize a new Hugo Module. If it fails to guess the module path, you must provide it as an argument, e.g.:
+- Modules can be imported in any combination or sequence.
+- Module imports are recursive; importing Module A can trigger the import of Module B, and so on.
+- Modules can provide configuration files and directories, subject to the constraints described in the [merge configuration settings][] section of the documentation.
+- External directories, including those from non-Hugo projects, can be mounted to create a [unified file system](g).
+
+## Import
+
+To import a module, first initialize the project itself as a module. For example:
```sh
-hugo mod init github.com/<your_user>/<your_project>
+hugo mod init github.com/user/project
```
-Also see the [CLI Doc](/commands/hugo_mod_init/).
+This will generate a [`go.mod`][] file in the project root.
+
+> [!note]
+> The module name is a unique identifier rather than a hosting requirement. Using a name like `github.com/user/project` is a common convention but it does not mean you must use Git or host your code on GitHub. You can use any name you like if you do not plan to have others import your project as a module. For example, you could use a simple name such as `my-project` when you run the initialization command.
-## Use a module for a theme
+Then define one or more imports in your project configuration. This contrived example imports three modules, each containing custom shortcodes:
-The easiest way to use a Module for a theme is to import it in the configuration.
+{{< code-toggle file=hugo >}}
+[module]
+ [[module.imports]]
+ path = 'shortcodes-a'
+ [[module.imports]]
+ path = '/home/user/shortcodes-b'
+ [[module.imports]]
+ path = 'github.com/user/shortcodes-c'
+{{< /code-toggle >}}
-1. Initialize the hugo module system: `hugo mod init github.com/<your_user>/<your_project>`
-1. Import the theme:
+Import precedence is top-down. For example, if `shortcodes-a`, `shortcodes-b`, and `shortcodes-c` each define an `image` shortcode, the `image` shortcode from `shortcodes-a` will take effect.
- {{< code-toggle file=hugo >}}
- [module]
- [[module.imports]]
- path = "github.com/spf13/hyde"
- {{< /code-toggle >}}
+> [!note]
+> If multiple modules contain data files or [translation tables](g) with identical paths, the data is deeply merged, following top-down precedence.
-## Update modules
+When you build your project, Hugo will:
-Modules will be downloaded and added when you add them as imports to your configuration. See [configure modules](/configuration/module/#imports).
+1. Download the modules
+1. Cache them for future use
+1. Generate a [`go.sum`][] file in the project root
-To update or manage versions, you can use `hugo mod get`.
+See [configuring module imports][] for details and options.
-Some examples:
+## Update
-### Update all modules
+When you import a module, Hugo creates `go.mod` and `go.sum` files in your project root, storing version and checksum data. Clearing the module cache and rebuilding will re-download the originally imported module version, as specified in the `go.mod` file, ensuring consistent builds. Modules can be updated to other versions as needed.
+
+To update a module to the latest version:
```sh
-hugo mod get -u
+hugo mod get -u github.com/user/shortcodes-c
```
-### Update all modules recursively
+To update a module to a specific version:
```sh
-hugo mod get -u ./...
+hugo mod get -u github.com/user/shortcodes-c@v0.42.0
```
-### Update one module
+To update all modules to the latest version:
```sh
-hugo mod get -u github.com/gohugoio/myShortcodes
+hugo mod get -u
```
-### Get a specific version
+To recursively update all modules to the latest version:
```sh
-hugo mod get github.com/gohugoio/myShortcodes@v1.0.7
+hugo mod get -u ./...
```
-Also see the [CLI Doc](/commands/hugo_mod_get/).
-
-## Make and test changes in a module
+## Tidy
-One way to do local development of a module imported in a project is to add a replace directive to a local directory with the source in `go.mod`:
+To remove unused entries from the `go.mod` and `go.sum` files:
```sh
-replace github.com/bep/hugotestmods/mypartials => /Users/bep/hugotestmods/mypartials
+hugo mod tidy
```
-If you have the `hugo server` running, the configuration will be reloaded and `/Users/bep/hugotestmods/mypartials` put on the watch list.
+## Cache
-Instead of modifying the `go.mod` files, you can also use the modules configuration [`replacements`](/configuration/module/#top-level-options) option.
+Hugo caches modules to avoid repeated downloads during site builds. By default, these are stored in the `modules` directory within the [`cacheDir`][].
-## Print dependency graph
+To clean the module cache for the current project:
-Use `hugo mod graph` from the relevant module directory and it will print the dependency graph, including vendoring, module replacement or disabled status.
-
-E.g.:
+```sh
+hugo mod clean
+```
-```txt
-hugo mod graph
+To clean the module cache for all projects:
-github.com/bep/my-modular-site github.com/bep/hugotestmods/mymounts@v1.2.0
-github.com/bep/my-modular-site github.com/bep/hugotestmods/mypartials@v1.0.7
-github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myassets@v1.0.4
-github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myv2@v1.0.0
-DISABLED github.com/bep/my-modular-site github.com/spf13/hyde@v0.0.0-20190427180251-e36f5799b396
-github.com/bep/my-modular-site github.com/bep/hugo-fresh@v1.0.1
-github.com/bep/my-modular-site in-themesdir
+```sh
+hugo mod clean --all
```
-Also see the [CLI Doc](/commands/hugo_mod_graph/).
+For details on cache location and eviction, see [configuring file caches][].
-## Vendor your modules
+## Vendor
-`hugo mod vendor` will write all the module dependencies to a `_vendor` directory, which will then be used for all subsequent builds.
+{{% glossary-term vendor %}}
-Note that:
+Vendoring a module provides the benefits described above and allows for local inspection of its [components](g).
-- You can run `hugo mod vendor` on any level in the module tree.
-- Vendoring will not store modules stored in your `themes` directory.
-- Most commands accept a `--ignoreVendorPaths` flag, which will then not use the vendored modules in `_vendor` for the module paths matching the given [glob pattern](g).
-
-Also see the [CLI Doc](/commands/hugo_mod_vendor/).
+```sh
+hugo mod vendor
+```
-## Tidy go.mod, go.sum
+This command creates a `_vendor` directory containing copies of all imported modules, used in subsequent builds. Note that:
-Run `hugo mod tidy` to remove unused entries in `go.mod` and `go.sum`.
+- The `hugo mod vendor` command can be run from any module tree level.
+- Modules within the `themes` directory are not vendored.
+- The `--ignoreVendorPaths` flag allows you to exclude vendored modules matching a [glob pattern](g) from specific commands.
-Also see the [CLI Doc](/commands/hugo_mod_clean/).
+> [!important]
+> Instead of modifying files directly within the `_vendor` directory, override them by creating a corresponding file with the same relative path in your project's root.
-## Clean module cache
+To remove the vendored modules, delete the `_vendor` directory.
-Run `hugo mod clean` to delete the entire modules cache.
+## Replace
-Note that you can also configure the `modules` cache with a `maxAge`. See [configure caches](/configuration/caches/).
+For local module development, use a `replace` directive in `go.mod` pointing to your local directory:
-Also see the [CLI Doc](/commands/hugo_mod_clean/).
+```text
+replace github.com/user/module => /home/user/projects/module
+```
-## Module workspaces
+With `hugo serve`r running, this change will trigger a configuration reload and add the local directory to the watch list. Alternatively, configure replacements by setting the [`replacements`][] parameter in your project configuration.
-Workspace support was added in [Go 1.18](https://go.dev/blog/get-familiar-with-workspaces) and Hugo got solid support for it in the `v0.109.0` version.
+## Workspace
-A common use case for a workspace is to simplify local development of a site with its theme modules.
+{{% glossary-term "workspace" %}}
-A workspace can be configured in a `*.work` file and activated with the [module.workspace](/configuration/module/) setting, which for this use is commonly controlled via the `HUGO_MODULE_WORKSPACE` OS environment variable.
+Workspaces simplify local development of sites with modules. Create a `.work` file to define a workspace, and activate it via the [`workspace`][] configuration parameter or the `HUGO_MODULE_WORKSPACE` environment variable.
-See the [hugo.work](https://github.com/gohugoio/hugo/blob/master/docs/hugo.work) file in the Hugo Docs repo for an example:
+A `.work` file example:
```text
-go 1.20
+go 1.24
use .
-use ../gohugoioTheme
+use ../my-hugo-module
```
-Using the `use` directive, list all the modules you want to work on, pointing to its relative location. As in the example above, it's recommended to always include the main project (the `.`) in the list.
-
-With that you can start the Hugo server with that workspace enabled:
+Use the `use` directive to list module paths, including the main project (`.`). Start the Hugo server with the workspace enabled:
```sh
HUGO_MODULE_WORKSPACE=hugo.work hugo server --ignoreVendorPaths "**"
```
-The `--ignoreVendorPaths` flag is added above to ignore any of the vendored dependencies inside `_vendor`. If you don't use vendoring, you don't need that flag. But now the server is set up watching the files and directories in the workspace and you can see your local edits reloaded.
+The `--ignoreVendorPaths` flag, used to ignore vendored dependencies (if applicable), enables live reloading of local edits within the workspace.
+
+## Graph
+
+To generate a [dependency graph](g), including vendoring, module replacement, and disabled module information, execute `hugo mod graph` within the target module directory. For example:
+
+```sh
+$ hugo mod graph
+
+github.com/bep/my-modular-site github.com/bep/hugotestmods/mymounts@v1.2.0
+github.com/bep/my-modular-site github.com/bep/hugotestmods/mypartials@v1.0.7
+github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myassets@v1.0.4
+github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myv2@v1.0.0
+DISABLED github.com/bep/my-modular-site github.com/spf13/hyde@v0.0.0-20190427180251-e36f5799b396
+github.com/bep/my-modular-site github.com/bep/hugo-fresh@v1.0.1
+github.com/bep/my-modular-site in-themesdir
+```
+
+## Mounts
+
+Imported modules automatically mount their component directories to Hugo's [unified file system](g). You can also manually mount any directory, including those from non-Hugo projects, to component directories.
+
+See [configuring module mounts][] for details.
+
+[`cacheDir`]: /configuration/all/#cachedir
+[`go.mod`]: https://go.dev/ref/mod#go-mod-file
+[`go.sum`]: https://go.dev/ref/mod#go-sum-files
+[`replacements`]: /configuration/module/#replacements
+[`workspace`]: /configuration/module/#workspace
+[configuring file caches]: /configuration/caches/
+[configuring module imports]: /configuration/module/#imports
+[configuring module mounts]: /configuration/module/#mounts
+[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+[Go]: https://go.dev/doc/install
+[merge configuration settings]: /configuration/introduction/#merge-configuration-settings
## Package managers
-<!--
### Snap
[Snap] is a free and open-source package manager for Linux. Available for [most distributions], snap packages are simple to install and are automatically updated.
[strictly confined]: https://snapcraft.io/docs/snap-confinement
[most distributions]: https://snapcraft.io/docs/installing-snapd
[Snap]: https://snapcraft.io/
--->
{{% include "/_common/installation/homebrew.md" %}}
---
title: Duration methods
linkTitle: Duration
-description: Use these methods with time.Duration values.
+description: Use these methods with a time.Duration value.
categories: []
keywords: []
---
Use the `Children` method when rendering a nested menu.
-With this site configuration:
+With this project configuration:
{{< code-toggle file=hugo >}}
[[menus.main]]
Use the `HasChildren` method when rendering a nested menu.
-With this site configuration:
+With this project configuration:
{{< code-toggle file=hugo >}}
[[menus.main]]
If you define the menu entry [automatically], the `Name` method returns the page's [`LinkTitle`], falling back to its [`Title`].
-If you define the menu entry [in front matter] or [in site configuration], the `Name` method returns the `name` property of the given menu entry. If the `name` is not defined, and the menu entry resolves to a page, the `Name` returns the page [`LinkTitle`], falling back to its [`Title`].
-
-[`LinkTitle`]: /methods/page/linktitle/
-[`Title`]: /methods/page/title/
-[automatically]: /content-management/menus/#define-automatically
-[in front matter]: /content-management/menus/#define-in-front-matter
-[in site configuration]: /content-management/menus/#define-in-site-configuration
+If you define the menu entry in [front matter] or in your [project configuration], the `Name` method returns the `name` property of the given menu entry. If the `name` is not defined, and the menu entry resolves to a page, the `Name` returns the page [`LinkTitle`], falling back to its [`Title`].
```go-html-template
<ul>
{{ end }}
</ul>
```
+
+[`LinkTitle`]: /methods/page/linktitle/
+[`Title`]: /methods/page/title/
+[automatically]: /content-management/menus/#define-automatically
+[front matter]: /content-management/menus/#define-in-front-matter
+[project configuration]: /content-management/menus/#define-in-project-configuration
## Explanation
-If you specify a `pageRef` property when [defining a menu entry] in your site configuration, Hugo looks for a matching page when rendering the entry.
+If you specify a `pageRef` property when [defining a menu entry] in your project configuration, Hugo looks for a matching page when rendering the entry.
If a matching page is found:
</ul>
```
-In the above note that Hugo populates the `href` attribute of the second `anchor` element with the `pageRef` property as defined in the site configuration because the template code falls back to the `PageRef` method.
+In the above note that Hugo populates the `href` attribute of the second `anchor` element with the `pageRef` property as defined in your project configuration because the template code falls back to the `PageRef` method.
[`HasMenuCurrent`]: /methods/page/hasmenucurrent/
[`IsMenuCurrent`]: /methods/page/ismenucurrent/
[`Page`]: /methods/menu-entry/page/
[`URL`]: /methods/menu-entry/url/
-[defining a menu entry]: /content-management/menus/#define-in-site-configuration
+[defining a menu entry]: /content-management/menus/#define-in-project-configuration
signatures: [MENUENTRY.Params]
---
-When you define menu entries [in site configuration] or [in front matter], you can include a `params` key to attach additional information to the entry. For example:
+When you define menu entries in your [project configuration] or in [front matter], you can include a `params` key to attach additional information to the entry. For example:
{{< code-toggle file=hugo >}}
[[menus.main]]
See the [menu templates] section for more information.
[menu templates]: /templates/menu/#menu-entry-parameters
-[in front matter]: /content-management/menus/#define-in-front-matter
-[in site configuration]: /content-management/menus/
+[front matter]: /content-management/menus/#define-in-front-matter
+[project configuration]: /content-management/menus/
If you define the menu entry [automatically], the `Weight` method returns the page's [`Weight`].
-If you define the menu entry [in front matter] or [in site configuration], the `Weight` method returns the `weight` property, falling back to the page's `Weight`.
-
-[`Weight`]: /methods/page/weight/
-[automatically]: /content-management/menus/#define-automatically
-[in front matter]: /content-management/menus/#define-in-front-matter
-[in site configuration]: /content-management/menus/#define-in-site-configuration
+If you define the menu entry in [front matter] or in your [project configuration], the `Weight` method returns the `weight` property, falling back to the page's `Weight`.
In this contrived example, we limit the number of menu entries based on weight:
{{ end }}
</ul>
```
+
+[`Weight`]: /methods/page/weight/
+[automatically]: /content-management/menus/#define-automatically
+[front matter]: /content-management/menus/#define-in-front-matter
+[project configuration]: /content-management/menus/#define-in-project-configuration
---
title: Rel
-description: Returns the rel value of the given output format, either the default or as defined in the site configuration.
+description: Returns the rel value of the given output format, either the default or as defined in your project configuration.
categories: []
keywords: []
params:
| page-relative | `content/examples/a.en.md` | `../a-old` | `/en/a-old/` |
| site-relative | `content/examples/a.en.md` | `/a-old` | `/en/a-old/` |
-### Site configuration
+### Project configuration
-To implement this, you must update your site configuration to:
+To implement this, you must update your project configuration to:
1. Disable the generation of default HTML redirect files by setting `disableAliases` to `true`.
1. Define a [media type][] named `text/redirects` to handle the file format.
To ensure the resulting `_redirects` file is valid, the template uses the [`strings.FindRE`][] function to check for whitespace such as tabs or newlines within the alias string. If whitespace is detected, Hugo will throw an error and fail the build to prevent generating an invalid file.
```go-html-template {file="layouts/home.redirects" copy=true}
-{{- if not (hugo.Store.Get "has_printed_redirects") -}}
- {{- range .Sites -}}
+{{- if site.IsDefault -}}
+ {{- range hugo.Sites -}}
{{- range $p := .Pages -}}
{{- range .Aliases -}}
{{- if findRE `\s` . -}}
{{- end -}}
{{- end -}}
{{- end -}}
- {{- hugo.Store.Set "has_printed_redirects" true -}}
{{- end -}}
```
signatures: [PAGE.AllTranslations]
---
-With this site configuration:
+With this project configuration:
{{< code-toggle file=hugo >}}
defaultContentLanguage = 'en'
>
> Themes that are not actively maintained may still use `.Data.Pages` in their templates. Although that syntax remains functional, use one of these methods instead: [`Pages`], [`RegularPages`], or [`RegularPagesRecursive`]
-The examples that follow are based on this site configuration:
+The examples that follow are based on this project configuration:
{{< code-toggle file=hugo >}}
[taxonomies]
{{< /code-toggle >}}
> [!note]
-> The date field in front matter is often considered to be the creation date, You can change its meaning, and its effect on your site, in the site configuration. See [details].
+> The date field in front matter is often considered to be the creation date, You can change its meaning, and its effect on your project, in your project configuration. See [details].
The date is a [time.Time] value. Format and localize the value with the [`time.Format`] function, or use it with any of the [time methods].
signatures: [PAGE.Draft]
---
-By default, Hugo does not publish draft pages when you build your site. To include draft pages when you build your site, use the `--buildDrafts` command line flag.
+By default, Hugo does not publish draft pages when you build your project. To include draft pages when you build your project, use the `--buildDrafts` command line flag.
{{< code-toggle file=content/posts/post-1.md fm=true >}}
title = 'Post 1'
signatures: [PAGE.ExpiryDate]
---
-By default, Hugo excludes expired pages when building your site. To include expired pages, use the `--buildExpired` command line flag.
+By default, Hugo excludes expired pages when building your project. To include expired pages, use the `--buildExpired` command line flag.
Set the expiry date in front matter:
### IsContentAdapter
-{{< new-in 0.126.0 />}}
-
(`bool`) Reports whether the file is a [content adapter].
```go-html-template
(`template.HTML`) Returns a TOC as a nested list, either ordered or unordered, identical to the HTML returned by the [`TableOfContents`] method. This method take three arguments: the start level (`int`), the end level (`int`), and a boolean (`true` to return an ordered list, `false` to return an unordered list).
-Use this method when you want to control the start level, end level, or list type independently from the table of contents settings in your site configuration.
+Use this method when you want to control the start level, end level, or list type independently from the table of contents settings in your project configuration.
```go-html-template
{{ $startLevel := 2 }}
Install Git, create a repository, and commit your project files.
-You must also allow Hugo to access your repository. In your site configuration:
+You must also allow Hugo to access your repository. In your project configuration:
{{< code-toggle file=hugo >}}
enableGitInfo = true
{{< /code-toggle >}}
-Alternatively, use the command line flag when building your site:
+Alternatively, use the command line flag when building your project:
```sh
-hugo --enableGitInfo
+hugo build --enableGitInfo
```
> [!note]
By default, when `enableGitInfo` is `true`, the `Lastmod` method on a `Page` object returns the Git AuthorDate of the last commit that included the file.
-You can change this behavior in your [site configuration].
+You can change this behavior in your [project configuration].
## Hosting considerations
[details]: /configuration/front-matter/#dates
[gitmailmap]: https://git-scm.com/docs/gitmailmap
-[site configuration]: /configuration/front-matter/
+[project configuration]: /configuration/front-matter/
See [menu templates] for a complete example.
> [!note]
-> When using this method you must either define the menu entry in front matter, or specify a `pageRef` property when defining the menu entry in your site configuration.
+> When using this method you must either define the menu entry in front matter, or specify a `pageRef` property when defining the menu entry in your project configuration.
[menu templates]: /templates/menu/#example
See [menu templates] for a complete example.
> [!note]
-> When using this method you must either define the menu entry in front matter, or specify a `pageRef` property when defining the menu entry in your site configuration.
+> When using this method you must either define the menu entry in front matter, or specify a `pageRef` property when defining the menu entry in your project configuration.
[menu templates]: /templates/menu/#example
signatures: [PAGE.IsTranslated]
---
-With this site configuration:
+With this project configuration:
{{< code-toggle file=hugo >}}
defaultContentLanguage = 'en'
---
title: Language
-description: Returns the language object for the given page.
+description: Returns the Language object for the given page.
categories: []
keywords: []
params:
signatures: [PAGE.Language]
---
-The `Language` method on a `Page` object returns the language object for the given page. The language object is derived from the language definition in the site configuration.
+The `Language` method on a `Page` object returns the `Language` object for the given page, derived from the language definition in your project configuration.
-You can also use the `Language` method on a `Site` object. See [details].
+You can also use the `Language` method on a `Site` object. See [details][].
## Methods
-The examples below assume the following in the site configuration:
+The examples below assume the following in your project configuration:
{{< code-toggle file=hugo >}}
[languages.de]
{{< new-in 0.153.0 />}}
-(`bool`) Reports whether this is the default language object as defined by the [`defaultContentLanguage`][] setting in the site configuration.
+(`bool`) Reports whether this is the [default language][].
```go-html-template
{{ .Language.IsDefault }} → true
### Lang
-(`string`) The language tag as defined by [RFC 5646]. This is the lower cased key from the site configuration.
+(`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from your project configuration.
```go-html-template
{{ .Language.Lang }} → de
### LanguageCode
-(`string`) The language code from the site configuration. Falls back to `Lang` if not defined.
+(`string`) Returns the [`languageCode`][] from your project configuration. Falls back to `Lang` if not defined.
```go-html-template
{{ .Language.LanguageCode }} → de-DE
### LanguageDirection
-(`string`) The language direction from the site configuration, either `ltr` or `rtl`.
+(`string`) Returns the [`languageDirection`][] from your project configuration.
```go-html-template
{{ .Language.LanguageDirection }} → ltr
### LanguageName
-(`string`) The language name from the site configuration.
+(`string`) Returns the [`languageName`][] from your project configuration.
```go-html-template
{{ .Language.LanguageName }} → Deutsch
### Name
-(`string`) The language tag as defined by [RFC 5646]. This is the lower cased key used in the site configuration. This is an alias for `Lang`.
+{{< new-in 0.153.0 />}}
+
+(`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from your project configuration. This is an alias for `Lang`.
```go-html-template
-{{ .Site.Language.Name }} → de
+{{ .Language.Name }} → de
```
### Weight
-(`int`) The language weight from the site configuration which determines its order in the slice of languages returned by the `Languages` method on a `Site` object.
+(`int`) Returns the language [`weight`][] from your project configuration.
```go-html-template
{{ .Language.Weight }} → 2
```
-[`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage
-[details]: /methods/site/language/
+[`languageCode`]: /configuration/languages/#languagecode
+[`languageDirection`]: /configuration/languages/#languagedirection
+[`languageName`]: /configuration/languages/#languagename
+[`weight`]: /configuration/languages/#weight
+[default language]: /quick-reference/glossary/#default-language
+[details]: /methods/page/language/
[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
Pagination is the process of splitting a list page into two or more pagers, where each pager contains a subset of the page collection and navigation links to other pagers.
-By default, the number of elements on each pager is determined by your [site configuration]. The default is `10`. Override that value by providing a second argument, an integer, when calling the `Paginate` method.
+By default, the number of elements on each pager is determined by your [project configuration]. The default is `10`. Override that value by providing a second argument, an integer, when calling the `Paginate` method.
> [!note]
> There is also a `Paginator` method on `Page` objects, but it can neither filter nor sort the page collection.
[home]: /templates/types/#home
[section]: /templates/types/#section
-[site configuration]: /configuration/pagination/
+[project configuration]: /configuration/pagination/
[taxonomy]: /templates/types/#taxonomy
[term]: /templates/types/#term
Pagination is the process of splitting a list page into two or more pagers, where each pager contains a subset of the page collection and navigation links to other pagers.
-The number of elements on each pager is determined by your [site configuration]. The default is `10`.
+The number of elements on each pager is determined by your [project configuration]. The default is `10`.
You can invoke pagination in [home], [section], [taxonomy], and [term] templates. Each of these receives a collection of regular pages in [context](g). When you invoke the `Paginator` method, it paginates the page collection received in context.
[home]: /templates/types/#home
[section]: /templates/types/#section
-[site configuration]: /configuration/pagination/
+[project configuration]: /configuration/pagination/
[taxonomy]: /templates/types/#taxonomy
[term]: /templates/types/#term
[`Paginate`]: /methods/page/paginate/
signatures: [PAGE.Permalink]
---
-Site configuration:
+Project configuration:
{{< code-toggle file=hugo >}}
title = 'Documentation'
signatures: [PAGE.PublishDate]
---
-By default, Hugo excludes pages with future publish dates when building your site. To include future pages, use the `--buildFuture` command line flag.
+By default, Hugo excludes pages with future publish dates when building your project. To include future pages, use the `--buildFuture` command line flag.
Set the publish date in front matter:
signatures: [PAGE.RelPermalink]
---
-Site configuration:
+Project configuration:
{{< code-toggle file=hugo >}}
title = 'Documentation'
---
title: Rotate
-description: Returns a collection of all pages sharing the same identity across the specified dimension, including the current page, sorted by the dimension's weight.
+description: Returns a collection of pages that vary along the specified dimension while sharing the current page's values for the other dimensions, including the current page, sorted by the dimension's default sort order.
categories: []
keywords: []
params:
{{< new-in 0.153.0 />}}
-The `Rotate` method on a `Page` object returns a collection of all pages sharing the same identity across the specified [dimension](g), including the current page, sorted by the dimension's weight.
+The rotate method on a page object returns a collection of pages that vary along the specified [dimension](g), while holding the other dimensions constant. The result includes the current page and is sorted according to the rules of the specified dimension. For example, rotating along [language](g) returns all language variants that share the current page's [version](g) and [role](g).
-The `DIMENSION` argument must be one of `language`, `role`, or `version`.
+The `DIMENSION` argument must be one of `language`, `version`, or `role`.
-To render a list of all translations of the current page, including the current page:
+## Sort order
+
+Use the following rules to understand how Hugo sorts the collection returned by the `Rotate` method.
+
+| Dimension | Primary Sort | Secondary Sort |
+| :--- | :--- | :--- |
+| Language | Weight ascending | Lexicographical ascending |
+| Version | Weight ascending | Semantic version descending |
+| Role | Weight ascending | Lexicographical ascending |
+
+## Examples
+
+To render a list of the current page's language variants, including the current page, while sharing its current version and role:
```go-html-template
-{{ with .Rotate "language" }}
- {{ range . }}
- <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
- {{ end }}
+{{/* Returns languages sorted by weight ascending, then lexicographically ascending */}}
+{{ range .Rotate "language" }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
```
-To render a list of all [roles](g) of the current page, including the current page:
+To render a list of the current page's version variants, including the current page, while sharing its current language and role:
```go-html-template
-{{ with .Rotate "role" }}
- {{ range . }}
- <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
- {{ end }}
+{{/* Returns versions sorted by weight ascending, then semantic version descending */}}
+{{ range .Rotate "version" }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
```
-To render a list of all versions of the current page, including the current page:
+To render a list of the current page's role variants, including the current page, while sharing its current language and version:
```go-html-template
-{{ with .Rotate "version" }}
- {{ range . }}
- <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
- {{ end }}
+{{/* Returns roles sorted by weight ascending, then lexicographically ascending */}}
+{{ range .Rotate "role" }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
```
## Example
-With this site configuration:
+With this project configuration:
{{< code-toggle file=hugo >}}
[sitemap]
---
title: Sites
-description: Returns a collection of all Site objects, one for each language, ordered by language weight.
+description: Returns a collection of all sites for all dimensions.
categories: []
keywords: []
params:
functions_and_methods:
returnType: page.Sites
signatures: [PAGE.Sites]
+expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0
---
-This is a convenience method to access `.Site.Sites`.
+{{< deprecated-in 0.156.0 >}}
+Use [`hugo.Sites`] instead.
-With this site configuration:
+[`hugo.Sites`]: /functions/hugo/sites/
+{{< /deprecated-in >}}
+
+{{% include "/_common/functions/hugo/sites-collection.md" %}}
+
+With this project configuration:
{{< code-toggle file=hugo >}}
defaultContentLanguage = 'de'
-defaultContentLanguageInSubdir = false
+defaultContentLanguageInSubdir = true
+defaultContentVersionInSubdir = true
[languages.de]
+contentDir = 'content/de'
languageCode = 'de-DE'
languageDirection = 'ltr'
languageName = 'Deutsch'
weight = 1
[languages.en]
+contentDir = 'content/en'
languageCode = 'en-US'
languageDirection = 'ltr'
languageName = 'English'
title = 'Project Documentation'
weight = 2
+
+[versions.'v1.0.0']
+[versions.'v2.0.0']
+[versions.'v3.0.0']
{{< /code-toggle >}}
This template:
```go-html-template
<ul>
{{ range .Sites }}
- <li><a href="{{ .Home.Permalink }}">{{ .Title }}</a></li>
+ <li><a href="{{ .Home.RelPermalink }}">{{ .Title }} {{ .Version.Name }}</a></li>
{{ end }}
</ul>
```
```html
<ul>
- <li><a href="https://example.org/de/">Projekt Dokumentation</a></li>
- <li><a href="https://example.org/en/">Project Documentation</a></li>
+ <li><a href="/v3.0.0/de/">Projekt Dokumentation v3.0.0</a></li>
+ <li><a href="/v2.0.0/de/">Projekt Dokumentation v2.0.0</a></li>
+ <li><a href="/v1.0.0/de/">Projekt Dokumentation v1.0.0</a></li>
+ <li><a href="/v3.0.0/en/">Project Documentation v3.0.0</a></li>
+ <li><a href="/v2.0.0/en/">Project Documentation v2.0.0</a></li>
+ <li><a href="/v1.0.0/en/">Project Documentation v1.0.0</a></li>
</ul>
```
```go-html-template
{{ with .Sites.Default }}
- <a href="{{ .Home.Permalink }}">{{ .Title }}</a>
+ <a href="{{ .Home.RelPermalink }}">{{ .Title }}</a>
{{ end }}
```
```go-html-template
{{ with index .Sites 0 }}
- <a href="{{ .Home.Permalink }}">{{ .Title }}</a>
+ <a href="{{ .Home.RelPermalink }}">{{ .Title }}</a>
{{ end }}
```
</nav>
```
-By default, the `TableOfContents` method returns an unordered list of level 2 and level 3 headings. You can adjust this in your site configuration:
+By default, the `TableOfContents` method returns an unordered list of level 2 and level 3 headings. You can adjust this in your project configuration:
{{< code-toggle file=hugo >}}
[markup.tableOfContents]
taxonomy|taxonomy name (capitalized and pluralized)
term|term name (capitalized and pluralized)
-You can disable automatic capitalization and pluralization in your site configuration:
+You can disable automatic capitalization and pluralization in your project configuration:
{{< code-toggle file=hugo >}}
capitalizeListTitles = false
pluralizeListTitles = false
{{< /code-toggle >}}
-You can change the capitalization style in your site configuration to one of `ap`, `chicago`, `go`, `firstupper`, or `none`. For example:
+You can change the capitalization style in your project configuration to one of `ap`, `chicago`, `go`, `firstupper`, or `none`. For example:
{{< code-toggle file=hugo >}}
titleCaseStyle = "firstupper"
The translation key creates a relationship between all translations of a given page. The translation key is derived from the file path, or from the `translationKey` parameter if defined in front matter.
-With this site configuration:
+With this project configuration:
{{< code-toggle file=hugo >}}
defaultContentLanguage = 'en'
signatures: [PAGE.Translations]
---
-With this site configuration:
+With this project configuration:
{{< code-toggle file=hugo >}}
defaultContentLanguage = 'en'
{{< new-in 0.128.0 />}}
-The number of pages per pager is determined by the optional second argument passed to the [`Paginate`] method, falling back to the `pagerSize` as defined in your [site configuration].
+The number of pages per pager is determined by the optional second argument passed to the [`Paginate`] method, falling back to the `pagerSize` as defined in your [project configuration].
[`Paginate`]: /methods/page/paginate/
-[site configuration]: /templates/pagination/#configuration
+[project configuration]: /templates/pagination/#configuration
```go-html-template
{{ $pages := where site.RegularPages "Type" "posts" }}
---
title: Pager methods
linkTitle: Pager
-description: Use these methods with Pager objects when building navigation for a paginated list page.
+description: Use these methods with a Pager object when building navigation for a paginated list page.
keywords: []
---
signatures: [PAGES.ByDate]
---
-When sorting by date, the value is determined by your [site configuration], defaulting to the `date` field in front matter.
+When sorting by date, the value is determined by your [project configuration], defaulting to the `date` field in front matter.
-[site configuration]: /configuration/front-matter/#dates
+[project configuration]: /configuration/front-matter/#dates
```go-html-template
{{ range .Pages.ByDate }}
signatures: [PAGES.ByExpiryDate]
---
-When sorting by expiration date, the value is determined by your [site configuration], defaulting to the `expiryDate` field in front matter.
+When sorting by expiration date, the value is determined by your [project configuration], defaulting to the `expiryDate` field in front matter.
-[site configuration]: /configuration/front-matter/#dates
+[project configuration]: /configuration/front-matter/#dates
```go-html-template
{{ range .Pages.ByExpiryDate }}
---
title: ByLanguage
-description: Returns the given page collection sorted by language in ascending order.
+description: Returns the given page collection sorted by language.
categories: []
keywords: []
params:
signatures: [PAGES.ByLanguage]
---
+When sorting by language, Hugo orders the page collection using the following priority:
+
+1. Language weight (ascending)
+1. Date (descending)
+1. LinkTitle (ascending)
+
+This method is rarely, if ever, needed. Page collections that already contain multiple languages, such as those returned by the [`Rotate`][], [`Translations`][], or [`AllTranslations`][] methods on a `Page` object, are already sorted by language weight.
+
+This contrived example aggregates pages from all sites and then sorts them by language:
+
```go-html-template
-{{ range .Site.AllPages.ByLanguage }}
+{{ $p := slice }}
+{{ range hugo.Sites }}
+ {{ range .Pages }}
+ {{ $p = $p | append . }}
+ {{ end }}
+{{ end }}
+
+{{ range $p.ByLanguage }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
```
To sort in descending order:
```go-html-template
-{{ range .Site.AllPages.ByLanguage.Reverse }}
+{{ range $p.ByLanguage.Reverse }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
```
+
+[`AllTranslations`]: /methods/page/alltranslations/
+[`Rotate`]: /methods/page/rotate/
+[`Translations`]: /methods/page/translations/
signatures: [PAGES.ByLastmod]
---
-When sorting by last modification date, the value is determined by your [site configuration], defaulting to the `lastmod` field in front matter.
+When sorting by last modification date, the value is determined by your [project configuration], defaulting to the `lastmod` field in front matter.
-[site configuration]: /configuration/front-matter/#dates
+[project configuration]: /configuration/front-matter/#dates
```go-html-template
{{ range .Pages.ByLastmod }}
signatures: [PAGES.ByParam PARAM]
---
-If the given parameter is not present in front matter, Hugo will use the matching parameter in your site configuration if present.
+If the given parameter is not present in front matter, Hugo will use the matching parameter in your project configuration if present.
```go-html-template
{{ range .Pages.ByParam "author" }}
signatures: [PAGES.ByPublishDate]
---
-When sorting by publish date, the value is determined by your [site configuration], defaulting to the `publishDate` field in front matter.
+When sorting by publish date, the value is determined by your [project configuration], defaulting to the `publishDate` field in front matter.
-[site configuration]: /configuration/front-matter/#dates
+[project configuration]: /configuration/front-matter/#dates
```go-html-template
{{ range .Pages.ByPublishDate }}
signatures: ['PAGES.GroupByDate LAYOUT [SORT]']
---
-When grouping by date, the value is determined by your [site configuration], defaulting to the `date` field in front matter.
+When grouping by date, the value is determined by your [project configuration], defaulting to the `date` field in front matter.
The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized](g) for language and region.
[`time.Format`]: /functions/time/format/
[layout string]: #layout-string
-[site configuration]: /configuration/front-matter/#dates
+[project configuration]: /configuration/front-matter/#dates
{{% include "/_common/methods/pages/group-sort-order.md" %}}
signatures: ['PAGES.GroupByExpiryDate LAYOUT [SORT]']
---
-When grouping by expiration date, the value is determined by your [site configuration], defaulting to the `expiryDate` field in front matter.
+When grouping by expiration date, the value is determined by your [project configuration], defaulting to the `expiryDate` field in front matter.
The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized](g) for language and region.
[`time.Format`]: /functions/time/format/
[layout string]: #layout-string
-[site configuration]: /configuration/front-matter/#dates
+[project configuration]: /configuration/front-matter/#dates
{{% include "/_common/methods/pages/group-sort-order.md" %}}
signatures: ['PAGES.GroupByLastmod LAYOUT [SORT]']
---
-When grouping by last modification date, the value is determined by your [site configuration], defaulting to the `lastmod` field in front matter.
+When grouping by last modification date, the value is determined by your [project configuration], defaulting to the `lastmod` field in front matter.
The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized](g) for language and region.
[`time.Format`]: /functions/time/format/
[layout string]: #layout-string
-[site configuration]: /configuration/front-matter/#dates
+[project configuration]: /configuration/front-matter/#dates
{{% include "/_common/methods/pages/group-sort-order.md" %}}
signatures: ['PAGES.GroupByPublishDate LAYOUT [SORT]']
---
-When grouping by publish date, the value is determined by your [site configuration], defaulting to the `publishDate` field in front matter.
+When grouping by publish date, the value is determined by your [project configuration], defaulting to the `publishDate` field in front matter.
The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized](g) for language and region.
[`time.Format`]: /functions/time/format/
[layout string]: #layout-string
-[site configuration]: /configuration/front-matter/#dates
+[project configuration]: /configuration/front-matter/#dates
{{% include "/_common/methods/pages/group-sort-order.md" %}}
### Tags
-(`meta.Tags`) Returns a collection of available Exif fields for this image. Availability is determined by the [`includeFields`][] and [`excludeFields`][] settings in your site configuration.
+(`meta.Tags`) Returns a collection of available Exif fields for this image. Availability is determined by the [`includeFields`][] and [`excludeFields`][] settings in your project configuration.
## Examples
### Exif
-(`meta.Tags`) Returns a collection of available Exif fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your site configuration.
+(`meta.Tags`) Returns a collection of available Exif fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your project configuration.
### IPTC
-(`meta.Tags`) Returns a collection of available IPTC fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your site configuration.
+(`meta.Tags`) Returns a collection of available IPTC fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your project configuration.
### XMP
-(`meta.Tags`) Returns a collection of available XMP fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your site configuration.
+(`meta.Tags`) Returns a collection of available XMP fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your project configuration.
## Examples
---
title: Resource methods
linkTitle: Resource
-description: Use these methods with global, page, and remote Resource objects.
+description: Use these methods with a global, page, or remote Resource object.
categories: []
keywords: []
---
functions_and_methods:
returnType: page.Pages
signatures: [SITE.AllPages]
+expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0
---
+{{< deprecated-in 0.156.0 >}}
+See [details](https://discourse.gohugo.io/t/56732).
+{{< /deprecated-in >}}
+
This method returns all page [kinds](g) in all languages, in the [default sort order](g). That includes the home page, section pages, taxonomy pages, term pages, and regular pages.
In most cases you should use the [`RegularPages`] method instead.
---
title: BaseURL
-description: Returns the base URL as defined in the site configuration.
+description: Returns the base URL as defined in your project configuration.
categories: []
keywords: []
params:
signatures: [SITE.BaseURL]
---
-Site configuration:
+Project configuration:
{{< code-toggle file=hugo >}}
baseURL = 'https://example.org/docs/'
---
title: BuildDrafts
-description: Reports whether the current build includes draft pages.
+description: Reports reports whether draft publishing is enabled for the current build.
categories: []
keywords: []
params:
functions_and_methods:
returnType: bool
signatures: [SITE.BuildDrafts]
+expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0
---
+{{< deprecated-in 0.156.0 >}}
+See [details](https://discourse.gohugo.io/t/56732).
+{{< /deprecated-in >}}
+
By default, draft pages are not published when building a site. You can change this behavior with a command line flag:
```sh
-hugo --buildDrafts
+hugo build --buildDrafts
```
-Or by setting `buildDrafts` to `true` in your site configuration:
+Or by setting `buildDrafts` to `true` in your project configuration:
{{< code-toggle file=hugo >}}
buildDrafts = true
---
title: Config
-description: Returns a subset of the site configuration.
+description: Returns a subset of your project configuration.
categories: []
keywords: []
params:
signatures: [SITE.Config]
---
-The `Config` method on a `Site` object provides access to a subset of the site configuration, specifically the `services` and `privacy` keys.
+The `Config` method on a `Site` object provides access to a subset of your project configuration, specifically the `services` and `privacy` keys.
## Services
---
title: Copyright
-description: Returns the copyright notice as defined in the site configuration.
+description: Returns the copyright notice as defined in your project configuration.
categories: []
keywords: []
params:
signatures: [SITE.Copyright]
---
-Site configuration:
+Project configuration:
{{< code-toggle file=hugo >}}
copyright = '© 2023 ABC Widgets, Inc.'
functions_and_methods:
returnType: map
signatures: [SITE.Data]
+expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0
---
+{{< deprecated-in 0.156.0 >}}
+Use [`hugo.Data`](/functions/hugo/data/) instead.
+{{< /deprecated-in >}}
+
Use the `Data` method on a `Site` object to access data within the `data` directory, or within any directory [mounted] to the `data` directory. Supported data formats include JSON, TOML, YAML, and XML.
> [!note]
The `Dimension` method on a `Site` object returns the dimension object for the given [dimension](g).
-The `DIMENSION` argument must be one of `language`, `role`, or `version`.
+The `DIMENSION` argument must be one of `language`, `version`, or `role`.
Example|Returns|Equivalent to
:--|:--|:--
`{{ .Site.Dimension "language" }}`|`langs.Language`|`{{ .Site.Language }}`
-`{{ .Site.Dimension "role" }}`|`roles.Role`|`{{ .Site.Role }}`
`{{ .Site.Dimension "version" }}`|`version.Version`|`{{ .Site.Version }}`
+`{{ .Site.Dimension "role" }}`|`roles.Role`|`{{ .Site.Role }}`
```go-html-template
{{ $languageObject := .Site.Dimension "language" }}
{{ $languageObject.IsDefault }} → true
{{ $languageObject.Name }} → en
-{{ $roleObject := .Site.Dimension "role" }}
-{{ $roleObject.IsDefault }} → true
-{{ $roleObject.Name }} → guest
-
{{ $versionObject := .Site.Dimension "version" }}
{{ $versionObject.IsDefault }} → true
{{ $versionObject.Name }} → v1.0.0
+
+{{ $roleObject := .Site.Dimension "role" }}
+{{ $roleObject.IsDefault }} → true
+{{ $roleObject.Name }} → guest
```
To get a page from a different language, query the `Sites` object:
```go-html-template
-{{ with where .Site.Sites "Language.Lang" "eq" "de" }}
+{{ with where hugo.Sites "Language.Lang" "eq" "de" }}
{{ with index . 0 }}
{{ with .GetPage "/works/paintings/starry-night" }}
{{ .Title }} → Sternenklare Nacht
This method is commonly used to generate a link to the home page. For example:
-Site configuration:
+Project configuration:
{{< code-toggle file=hugo >}}
baseURL = 'https://example.org/docs/'
--- /dev/null
+---
+title: IsDefault
+description: Reports whether the given site is the default site across all dimensions.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [SITE.IsDefault]
+---
+
+{{< new-in 0.156.0 />}}
+
+The `IsDefault` method on a `Site` object reports whether the given site is the [default site](g) across all dimensions: [language](g), [version](g), and [role](g). This is useful to ensure that a block of code executes only once per build, regardless of the number of [sites](g) generated by your [dimensions](g).
+
+For example, the following configuration defines a matrix of sites across language and version dimensions.
+
+{{< code-toggle file=hugo >}}
+[languages.de]
+contentDir = 'content/de'
+languageCode = 'de-DE'
+languageDirection = 'ltr'
+languageName = 'Deutsch'
+title = 'Projekt Dokumentation'
+weight = 1
+
+[languages.en]
+contentDir = 'content/en'
+languageCode = 'en-US'
+languageDirection = 'ltr'
+languageName = 'English'
+title = 'Project Documentation'
+weight = 2
+
+[versions.'v1.0.0']
+[versions.'v2.0.0']
+[versions.'v3.0.0']
+{{< /code-toggle >}}
+
+If you call an initialization partial to handle one-time build logic or global variable setup, wrap that call in an [`if`][] statement using this function. This prevents the logic from being executed for every dimensional variation.
+
+```go-html-template
+{{ if .Site.IsDefault }}
+ {{ partial "init.html" . }}
+{{ end }}
+```
+
+In this setup, the code block is only executed for the English version v3.0.0 site. English is selected because it has the lowest weight, and version v3.0.0 is selected because it is the first version when sorted semantically in descending order.
+
+[`if`]: /functions/go-template/if/
---
title: Language
-description: Returns the language object for the given site.
+description: Returns the Language object for the given site.
categories: []
keywords: []
params:
signatures: [SITE.Language]
---
-The `Language` method on a `Page` object returns the language object for the given page. The language object is derived from the language definition in the site configuration.
+The `Language` method on a `Site` object returns the `Language` object for the given site, derived from the language definition in your project configuration.
-You can also use the `Language` method on a `Page` object. See [details].
+You can also use the `Language` method on a `Page` object. See [details][].
## Methods
-The examples below assume the following in the site configuration:
+The examples below assume the following in your project configuration:
{{< code-toggle file=hugo >}}
[languages.de]
{{< new-in 0.153.0 />}}
-(`bool`) Reports whether this is the default language object as defined by the [`defaultContentLanguage`][] setting in the site configuration.
+(`bool`) Reports whether this is the [default language][].
```go-html-template
{{ .Site.Language.IsDefault }} → true
### Lang
-(`string`) The language tag as defined by [RFC 5646]. This is the lower cased key from the site configuration.
+(`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from your project configuration.
```go-html-template
{{ .Site.Language.Lang }} → de
### LanguageCode
-(`string`) The language code from the site configuration. Falls back to `Lang` if not defined.
+(`string`) Returns the [`languageCode`][] from your project configuration. Falls back to `Lang` if not defined.
```go-html-template
{{ .Site.Language.LanguageCode }} → de-DE
### LanguageDirection
-(`string`) The language direction from the site configuration, either `ltr` or `rtl`.
+(`string`) Returns the [`languageDirection`][] from your project configuration.
```go-html-template
{{ .Site.Language.LanguageDirection }} → ltr
### LanguageName
-(`string`) The language name from the site configuration.
+(`string`) Returns the [`languageName`][] from your project configuration.
```go-html-template
{{ .Site.Language.LanguageName }} → Deutsch
### Name
-(`string`) The language tag as defined by [RFC 5646]. This is the lower cased key from the site configuration. This is an alias for `Lang`.
+{{< new-in 0.153.0 />}}
+
+(`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from your project configuration. This is an alias for `Lang`.
```go-html-template
{{ .Site.Language.Name }} → de
### Weight
-(`int`) The language weight from the site configuration which determines its order in the slice of languages returned by the `Languages` method on a `Site` object.
+(`int`) Returns the language [`weight`][] from your project configuration.
```go-html-template
{{ .Site.Language.Weight }} → 1
>
```
-[`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage
+[`languageCode`]: /configuration/languages/#languagecode
+[`languageDirection`]: /configuration/languages/#languagedirection
+[`languageName`]: /configuration/languages/#languagename
+[`weight`]: /configuration/languages/#weight
+[default language]: /quick-reference/glossary/#default-language
[details]: /methods/page/language/
[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
signatures: [SITE.LanguagePrefix]
---
-Consider this site configuration:
+Consider this project configuration:
{{< code-toggle file=hugo >}}
defaultContentLanguage = 'de'
functions_and_methods:
returnType: langs.Languages
signatures: [SITE.Languages]
+expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0
---
-The `Languages` method on a `Site` object returns a collection of language objects for all sites, ordered by language weight. Each language object points to its language definition in the site configuration.
+{{< deprecated-in 0.156.0 >}}
+See [details](https://discourse.gohugo.io/t/56732).
+{{< /deprecated-in >}}
+
+The `Languages` method on a `Site` object returns a collection of language objects for all sites, ordered by language weight. Each language object points to its language definition in your project configuration.
To inspect the data structure:
<pre>{{ debug.Dump .Site.Languages }}</pre>
```
-With this site configuration:
+With this project configuration:
{{< code-toggle file=hugo >}}
defaultContentLanguage = 'de'
---
title: MainSections
-description: Returns a slice of the main section names as defined in the site configuration, falling back to the top-level section with the most pages.
+description: Returns a slice of the main section names as defined in your project configuration, falling back to the top-level section with the most pages.
categories: []
keywords: []
params:
signatures: [SITE.MainSections]
---
-Site configuration:
+Project configuration:
{{< code-toggle file=hugo >}}
mainSections = ['books','films']
{{ .Site.MainSections }} → [books films]
```
-If `mainSections` is not defined in the site configuration, this method returns a slice with one element---the top-level section with the most pages.
+If `mainSections` is not defined in your project configuration, this method returns a slice with one element---the top-level section with the most pages.
With this content structure, the "films" section has the most pages:
{{ .Site.MainSections }} → [films]
```
-When creating a theme, instead of hardcoding section names when listing the most relevant pages on the front page, instruct site authors to set `mainSections` in their site configuration.
+When creating a theme, instead of hardcoding section names when listing the most relevant pages on the front page, instruct users to set `mainSections` in their project configuration.
Then your _home_ template can do something like this:
signatures: [SITE.Param KEY]
---
-The `Param` method on a `Site` object is a convenience method to return the value of a user-defined parameter in the site configuration.
+The `Param` method on a `Site` object is a convenience method to return the value of a user-defined parameter in your project configuration.
{{< code-toggle file=hugo >}}
[params]
---
title: Params
-description: Returns a map of custom parameters as defined in the site configuration.
+description: Returns a map of custom parameters as defined in your project configuration.
categories: []
keywords: []
params:
signatures: [SITE.Params]
---
-With this site configuration:
+With this project configuration:
{{< code-toggle file=hugo >}}
[params]
---
title: Role
-description: Returns the role object for the given site.
+description: Returns the Role object for the given site.
categories: []
keywords: []
params:
functions_and_methods:
- returnType: roles.RoleSite
+ returnType: roles.Role
signatures: [SITE.Role]
---
{{< new-in 0.153.0 />}}
-The `Role` method on a `Site` object returns the role object for the given site. The role object is derived from the role definition in the site configuration.
+The `Role` method on a `Site` object returns the `Role` object for the given site, derived from the role definition in your project configuration.
## Methods
### IsDefault
-(`bool`) Reports whether this is the default role object as defined by the [`defaultContentRole`][] setting in the site configuration.
+(`bool`) Reports whether this is the [default role][].
```go-html-template
{{ .Site.Role.IsDefault }} → true
### Name
-(`string`) Returns the role name. This is the lower cased key from the site configuration.
+(`string`) Returns the role name. This is the lowercased key from your project configuration.
```go-html-template
{{ .Site.Role.Name }} → guest
```
-[`defaultContentRole`]: /configuration/all/#defaultcontentrole
+[default role]: /quick-reference/glossary/#default-role
---
title: Sites
-description: Returns a collection of all Site objects, one for each language, ordered by default content language then by language weight.
+description: Returns a collection of all sites for all dimensions.
categories: []
keywords: []
params:
functions_and_methods:
returnType: page.Sites
signatures: [SITE.Sites]
+expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0
---
-With this site configuration:
+{{< deprecated-in 0.156.0 >}}
+Use [`hugo.Sites`] instead.
+
+[`hugo.Sites`]: /functions/hugo/sites/
+{{< /deprecated-in >}}
+
+{{% include "/_common/functions/hugo/sites-collection.md" %}}
+
+With this project configuration:
{{< code-toggle file=hugo >}}
defaultContentLanguage = 'de'
-defaultContentLanguageInSubdir = false
+defaultContentLanguageInSubdir = true
+defaultContentVersionInSubdir = true
[languages.de]
+contentDir = 'content/de'
languageCode = 'de-DE'
languageDirection = 'ltr'
languageName = 'Deutsch'
weight = 1
[languages.en]
+contentDir = 'content/en'
languageCode = 'en-US'
languageDirection = 'ltr'
languageName = 'English'
title = 'Project Documentation'
weight = 2
+
+[versions.'v1.0.0']
+[versions.'v2.0.0']
+[versions.'v3.0.0']
{{< /code-toggle >}}
This template:
```go-html-template
<ul>
{{ range .Site.Sites }}
- <li><a href="{{ .Home.Permalink }}">{{ .Title }}</a></li>
+ <li><a href="{{ .Home.RelPermalink }}">{{ .Title }} {{ .Version.Name }}</a></li>
{{ end }}
</ul>
```
```html
<ul>
- <li><a href="https://example.org/de/">Projekt Dokumentation</a></li>
- <li><a href="https://example.org/en/">Project Documentation</a></li>
+ <li><a href="/v3.0.0/de/">Projekt Dokumentation v3.0.0</a></li>
+ <li><a href="/v2.0.0/de/">Projekt Dokumentation v2.0.0</a></li>
+ <li><a href="/v1.0.0/de/">Projekt Dokumentation v1.0.0</a></li>
+ <li><a href="/v3.0.0/en/">Project Documentation v3.0.0</a></li>
+ <li><a href="/v2.0.0/en/">Project Documentation v2.0.0</a></li>
+ <li><a href="/v1.0.0/en/">Project Documentation v1.0.0</a></li>
</ul>
```
```go-html-template
{{ with .Site.Sites.Default }}
- <a href="{{ .Home.Permalink }}">{{ .Title }}</a>
+ <a href="{{ .Home.RelPermalink }}">{{ .Title }}</a>
{{ end }}
```
```go-html-template
{{ with index .Site.Sites 0 }}
- <a href="{{ .Home.Permalink }}">{{ .Title }}</a>
+ <a href="{{ .Home.RelPermalink }}">{{ .Title }}</a>
{{ end }}
```
For example, on a book review site you might create two taxonomies; one for genres and another for authors.
-With this site configuration:
+With this project configuration:
{{< code-toggle file=hugo >}}
[taxonomies]
---
title: Title
-description: Returns the title as defined in the site configuration.
+description: Returns the title as defined in your project configuration.
categories: []
keywords: []
params:
signatures: [SITE.Title]
---
-Site configuration:
+Project configuration:
{{< code-toggle file=hugo >}}
title = 'My Documentation Site'
---
title: Version
-description: Returns the version object for the given site.
+description: Returns the Version object for the given site.
categories: []
keywords: []
params:
{{< new-in 0.153.0 />}}
-The `Version` method on a `Site` object returns the version object for the given site. The version object is derived from the version definition in the site configuration.
+The `Version` method on a `Site` object returns the `Version` object for the given site, derived from the version definition in your project configuration.
## Methods
### IsDefault
-(`bool`) Reports whether this is the default version object as defined by the [`defaultContentVersion`][] setting in the site configuration.
+(`bool`) Reports whether this is the [default version][].
```go-html-template
{{ .Site.Version.IsDefault }} → true
### Name
-(`string`) Returns the version name. This is the lower cased key from the site configuration.
+(`string`) Returns the version name. This is the lowercased key from your project configuration.
```go-html-template
{{ .Site.Version.Name }} → v1.0.0
```
-[`defaultContentVersion`]: /configuration/all/#defaultcontentversion
+[default version]: /quick-reference/glossary/#default-version
---
title: Site methods
linkTitle: Site
-description: Use these methods with Site objects.
+description: Use these methods with a Site object.
categories: []
keywords: []
aliases: [/variables/site/]
---
title: Taxonomy methods
linkTitle: Taxonomy
-description: Use these methods with Taxonomy objects.
+description: Use these methods with a Taxonomy object.
keywords: []
aliases: [/variables/taxonomy/]
---
---
title: Time methods
linkTitle: Time
-description: Use these methods with time.Time values.
+description: Use these methods with a time.Time value.
categories: []
keywords: []
---
--- /dev/null
+---
+title: build artifacts
+---
+
+The _build artifacts_ are the static files produced during the [_build_](g) process. These assets are stored in the `public` directory by default and represent the final, ready-to-deploy output of the project.
title: build
---
-To _build_ (verb) a site is to generate HTML files and assets such as images, CSS files, and JavaScript files. The build process includes rendering and resource transformations.
+To _build_ (verb) is to generate the static files for a [_project_](g), including HTML, images, CSS, and JavaScript. This process involves rendering templates, transforming resources, and resolving the matrix of [_language_](g), [_role_](g), and [_version_](g) defined in your project configuration.
title: canonical output format
---
-The _canonical output format_ is the [_output format_](g) for the current page where the format's [`rel`][] property is set to `canonical` in your site configuration, if such a format exists. If there is only one _output format_ for the current page, that is the _canonical output format_, regardless of whether the format's `rel` property is set to `canonical`.
+The _canonical output format_ is the [_output format_](g) for the current page where the format's [`rel`][] property is set to `canonical` in your project configuration, if such a format exists. If there is only one _output format_ for the current page, that is the _canonical output format_, regardless of whether the format's `rel` property is set to `canonical`.
By default, `html` is the only predefined _output format_ with this setting; the `rel` property for all others is set to `alternate`. If two or more _output formats_ for the current page have their `rel` property set to `canonical`, the _canonical output format_ is the first one specified in:
- The [`outputs`][outputs_front_matter] front matter field of the current page, or
- - The [`outputs`][outputs_site_config] section of your site configuration for the current [_page kind_](g).
+ - The [`outputs`][outputs_project_config] section of your project configuration for the current [_page kind_](g).
[`rel`]: /configuration/output-formats/#rel
[outputs_front_matter]: /configuration/outputs/#outputs-per-page
- [outputs_site_config]: /configuration/outputs/#outputs-per-page-kind
+ [outputs_project_config]: /configuration/outputs/#outputs-per-page-kind
title: component
---
-A _component_ is a collection of related files, housed within the [_unified file system_](g), that fulfills a specific function in building a Hugo website. These components are categorized into seven types: [_archetypes_](g), assets, content, data, templates, [_translation tables_](g), and static files, and can be defined within the project or provided by [_modules_](g).
-
- Each component has a dedicated directory within the unified file system:
+A _component_ is a collection of related files, housed within the [_unified file system_](g), that fulfills a specific function in building a Hugo [_project_](g). These components are categorized into seven types: [_archetypes_](g), assets, content, data, templates, [_translation tables_](g), and static files, and can be defined within the project or provided by [_modules_](g). Each component has a dedicated directory within the unified file system:
Component|Directory within the unified file system
:--|:--
--- /dev/null
+---
+title: default language
+---
+
+The _default language_ is is the value defined by the [`defaultContentLanguage`][] setting, falling back to the first language in the project, and finally to `en`. The first language is identified by the lowest [_weight_](g), using lexicographical order as the final fallback if weights are tied or undefined.
+
+ See also: [_language_](g).
+
+ [`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage
--- /dev/null
+---
+title: default role
+---
+
+The _default role_ is the value defined by the [`defaultContentRole`][] setting, falling back to the first role in the project, and finally to `guest`. The first role is identified by the lowest [_weight_](g), using lexicographical order as the final fallback if weights are tied or undefined.
+
+ See also: [_role_](g).
+
+ [`defaultContentRole`]: /configuration/all/#defaultcontentrole
title: default site
---
-The _default site_ is the [_site_](g) identified by the primary value in each [_content dimension_](g). Specifically, it is the site that combines the first language, the first [_role_](g), and the first version defined in your site configuration.
-
- The "first" language and role are those with the lowest [weight](g). If weights are tied or undefined, Hugo defaults to lexicographical order. Similarly, the "first" version is the one with the lowest weight; if weights are tied or undefined, it is identified as the last version when sorted semantically.
+The _default site_ is the [_site_](g) with the [_default language_](g), [_default version_](g), and [_default role_](g).
--- /dev/null
+---
+title: default version
+---
+
+The _default version_ is the value defined by the [`defaultContentVersion`][] setting, falling back to the first version in the project, and finally to `v1.0.0`. The first version is identified by the lowest [_weight_](g), using a descending semantic sort as the final fallback if weights are tied or undefined.
+
+ See also: [_version_](g).
+
+ [`defaultContentVersion`]: /configuration/all/#defaultcontentversion
--- /dev/null
+---
+title: dependency graph
+---
+
+A _dependency graph_ visually represents the relationships between the [_modules_](g) used in a Hugo project. It shows how modules depend on each other, forming a network of dependencies.
title: dimension
---
-A _dimension_ is a categorized axis of content variation that allows multiple variations of a logical page to exist simultaneously. The three dimensions are language, [_role_](g), and version. For example, a logical page may exist in 6 languages, 4 versions, and 2 _roles_.
+A _dimension_ is a categorized axis of content variation that allows multiple variations of a logical page to exist simultaneously. The three dimensions are [_language_](g), [_role_](g), and [_version_](g). For example, a logical page may exist in 6 languages, 4 versions, and 2 roles.
Typically one of `development`, `staging`, or `production`, each _environment_ may exhibit different behavior depending on configuration and template logic. For example, in a production environment you might minify and fingerprint CSS, but that probably doesn't make sense in a development environment.
- When running the built-in development server with the `hugo server` command, the environment is set to `development`. When building your site with the `hugo` command, the environment is set to `production`. To override the environment value, use the `--environment` command line flag or the `HUGO_ENVIRONMENT` environment variable.
+ When running the built-in development server with the `hugo server` command, the environment is set to `development`. When building your project with the `hugo build` command, the environment is set to `production`. To override the environment value, use the `--environment` command line flag or the `HUGO_ENVIRONMENT` environment variable.
To determine the current environment within a template, use the [`hugo.Environment`](/functions/hugo/environment/) function.
A _glob slice_ is a [_slice_](g) of [_glob patterns_](g). Within the _slice_, a _glob_ can be negated by prefixing it with an exclamation mark (`!`) and one space. Matches in negated patterns short-circuit the evaluation of the rest of the _slice_, and are useful for early coarse grained exclusions.
- The following example illustrates how to use _glob slices_ to define a [_sites matrix_](g) in your site configuration:
+ The following example illustrates how to use _glob slices_ to define a [_sites matrix_](g) in your project configuration:
```toml
[sites.matrix]
--- /dev/null
+---
+title: language
+---
+
+A _language_ is a [_dimension_](g) that facilitates the localization and internationalization of content. While [_version_](g) focuses on lifecycle and [_role_](g) focuses on audience, the language dimension allows a logical page to be represented in different locales across the project.
+
+ See also: [_default language_](g).
title: page-relative
---
- A _page-relative_ path is resolved relative to the current page's location in the content hierarchy. These paths do not begin with a leading slash. Examples include `old-name`, `./old-name`, and `../old-name`.
+A _page-relative_ path is resolved relative to the current page's location in the content hierarchy. These paths do not begin with a leading slash. Examples include `old-name`, `./old-name`, and `../old-name`.
See also: [_site-relative_](g), [_server-relative_](g).
--- /dev/null
+---
+title: project
+---
+
+A _project_ is a collection of [_components_](g) used to generate one or more [sites](g). While a project may consist of only a single site, Hugo allows a single project to generate a matrix of sites based on [_language_](g), [role](g), and [_version_](g). The project serves as the parent container for the common assets and logic used across all sites within the build.
reference:
---
-A _regular expression_, also known as a _regex_, is a sequence of characters that defines a search pattern. Use the [RE2 syntax] when defining regular expressions in your templates or site configuration.
+A _regular expression_, also known as a _regex_, is a sequence of characters that defines a search pattern. Use the [RE2 syntax] when defining regular expressions in your templates or in your project configuration.
[RE2 syntax]: https://github.com/google/re2/wiki/syntax
title: role
---
-A _role_ is a [_dimension_](g) that allows a logical page to be served in different forms depending on the target audience. Common use cases include user personas, access control, and intended audience.
+A _role_ is a [_dimension_](g) that allows a logical page to be served in different forms depending on the target audience. While [_language_](g) focuses on localization and [_version_](g) focuses on lifecycle, the role dimension allows a project to generate variations of a page without duplicating content.
+
+ See also: [_default role_](g).
title: server-relative
---
- A _server-relative_ path is the final path from the web server's root, used in the generated site. These paths always begin with a leading slash and account for the [`baseURL`] and [_content dimension_](g) prefixes such as language, [_role_](g), or version. For example, `/en/examples/old-name/` is a server-relative path.
+A _server-relative_ path is the final path from the web server's root, used in the generated site. These paths always begin with a leading slash and account for the [`baseURL`] and [_content dimension_](g) prefixes such as language, [_role_](g), or version. For example, `/en/examples/old-name/` is a server-relative path.
See also: [_page-relative_](g), [_site-relative_](g).
title: site-relative
---
- A _site-relative_ path is resolved relative to the root of the content directory. These paths begin with a leading slash. For example, `/old-name` is a site-relative path.
+A _site-relative_ path is resolved relative to the root of the content directory. These paths begin with a leading slash. For example, `/old-name` is a site-relative path.
See also: [_page-relative_](g), [_server-relative_](g).
title: site root
---
-The _site root_ is the root directory of the current [_site_](g), relative to the [`publishDir`][]. The _site root_ may include one or more content [_dimension_](g) prefixes, such as language, [_role_](g), or version.
+The _site root_ is the root directory of the current [_site_](g), relative to the [`publishDir`][]. The _site root_ may include one or more content [_dimension_](g) prefixes, such as [_language_](g), [_role_](g), or [_version_](g).
Project description|Site root examples
:--|:--|:--
title: site
---
-A _site_ is a specific instance of your project representing a unique combination of language, [_role_](g), and version. While a simple project may consist of only a single site, Hugo's multidimensional content model allows a single codebase to generate a matrix of sites simultaneously. Each site operates with its own configuration, set of pages, and output destination, allowing you to serve tailored content to different audiences from one unified source.
+A _site_ is a specific instance of your [_project_](g) representing a unique combination of [_language_](g), [_role_](g), and [_version_](g). While a simple project may consist of only a single site, Hugo's multidimensional content model allows a single codebase to generate a matrix of sites simultaneously.
title: sites complements
---
-_sites complements_ is a configuration object defined in content front matter or a file mount. The links will point to the complementary sites. The configuration is structured as a map of [_glob slices_](g).
+A _sites complements_ is a configuration object defined in content front matter or a file mount. The links will point to the complementary [_sites_](g). The configuration is structured as a map of [_glob slices_](g).
title: sites matrix
---
-_sites matrix_ is a configuration object defined in content front matter or a file mount to precisely control which sites the content should be generated for. When defined in a file mount for [_templates_](g), it controls which sites the template will be applied to.
-
- In Hugo's multidimensional content model, the matrix defines the intersection of three dimensions: language, role, and version. The configuration is structured as a map of [_glob slices_](g).
+A _sites matrix_ is a configuration object defined in content front matter or a file mount to precisely control which [_sites_](g) the content should be generated for. When defined in a file mount for templates, it controls which sites the template will be applied to. In Hugo multidimensional content model, the matrix defines the intersection of three dimensions: [_language_](g), [_role_](g), and [_version_](g). The configuration is structured as a map of [_glob slices_](g).
See also [_sites complements_](g), [front matter: sites](/content-management/front-matter/#sites), [module mounts: sites](/configuration/module/#sites), and [segments: sites](/configuration/segments/#sites).
--- /dev/null
+---
+title: version
+---
+
+A _version_ is a [_dimension_](g) that represents a specific iteration, release, or lifecycle stage of content. While [_language_](g) focuses on localization and [_role_](g) focuses on audience, the version dimension allows you to maintain multiple states of the same content simultaneously using [semantic versioning].
+
+ See also: [_default version_](g).
+
+ [semantic versioning]: https://semver.org/
--- /dev/null
+---
+title: workspace
+params:
+ reference: /hugo-modules/use-modules/#workspace
+---
+
+A _workspace_ is a collection of [_modules_](g) on disk.
A _wrapper component_ is an interface pattern that encloses other content through composition rather than fixed parameters. It provides a reusable shell to handle layout, styling, or logic, allowing the calling template to inject arbitrary content into the component's interior.
- See also: [_partial decorator_](g)
+ See also: [_partial decorator_](g).
Regardless of method, use any of the syntax highlighting styles below.
-Set the default syntax highlighting style in your site configuration:
+Set the default syntax highlighting style in your project configuration:
{{< code-toggle file=hugo >}}
[markup.highlight]
This Markdown example contains a fenced code block:
````text {file="content/example.md"}
-```bash {class="my-class" id="my-codeblock" lineNos=inline tabWidth=2}
+```sh {class="my-class" id="my-codeblock" lineNos=inline tabWidth=2}
declare a=1
echo "$a"
exit
{{- end -}}
```
-Note that the above requires the following site configuration:
+Note that the above requires the following project configuration:
{{< code-toggle file=hugo >}}
[markup.goldmark.parser]
## Embedded
-Hugo includes an [embedded image render hook] to resolve Markdown image destinations. You can adjust its behavior in your site configuration. This is the default setting:
+Hugo includes an [embedded image render hook] to resolve Markdown image destinations. You can adjust its behavior in your project configuration. This is the default setting:
{{< code-toggle file=hugo >}}
[markup.goldmark.renderHooks.image]
The embedded image render hook resolves internal Markdown destinations by looking for a matching [page resource](g), falling back to a matching [global resource](g). Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination.
-You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your site configuration:
+You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your project configuration:
{{< code-toggle file=hugo >}}
[[module.mounts]]
## Embedded
-Hugo includes an [embedded link render hook] to resolve Markdown link destinations. You can adjust its behavior in your site configuration. This is the default setting:
+Hugo includes an [embedded link render hook] to resolve Markdown link destinations. You can adjust its behavior in your project configuration. This is the default setting:
{{< code-toggle file=hugo >}}
[markup.goldmark.renderHooks.link]
The embedded link render hook resolves internal Markdown destinations by looking for a matching page, falling back to a matching [page resource](g), then falling back to a matching [global resource](g). Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination.
-You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your site configuration:
+You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your project configuration:
{{< code-toggle file=hugo >}}
[[module.mounts]]
This is an \(inline\) passthrough element with opening and closing inline delimiters.
```
-Update your site configuration to enable the Passthrough extension and define opening and closing delimiters for each passthrough element type, either `block` or `inline`. For example:
+Update your project configuration to enable the Passthrough extension and define opening and closing delimiters for each passthrough element type, either `block` or `inline`. For example:
{{< code-toggle file=hugo >}}
[markup.goldmark.extensions.passthrough]
The `figure` shortcode resolves internal Markdown destinations by looking for a matching [page resource](g), falling back to a matching [global resource](g). Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination.
-You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your site configuration:
+You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your project configuration:
{{< code-toggle file=hugo >}}
[[module.mounts]]
: (`string`) The language of the code to highlight. Choose from one of the [supported languages]. This value is case-insensitive.
OPTIONS
-: (`string`) Zero or more space-separated key-value pairs wrapped in quotation marks. Set default values for each option in your [site configuration]. The key names are case-insensitive.
+: (`string`) Zero or more space-separated key-value pairs wrapped in quotation marks. Set default values for each option in your [project configuration]. The key names are case-insensitive.
## Example
## Options
-Pass the options when calling the shortcode. You can set their default values in your [site configuration].
+Pass the options when calling the shortcode. You can set their default values in your [project configuration].
{{% include "_common/syntax-highlighting-options.md" %}}
[Chroma]: https://github.com/alecthomas/chroma
[content format]: /content-management/formats/
[highlighting styles]: /quick-reference/syntax-highlighting-styles/
-[site configuration]: /configuration/markup/#highlight
+[project configuration]: /configuration/markup/#highlight
[source code]: <{{% eturl highlight %}}>
[supported languages]: /content-management/syntax-highlighting/#languages
## Privacy
-Adjust the relevant privacy settings in your site configuration.
+Adjust the relevant privacy settings in your project configuration.
{{< code-toggle config=privacy.instagram />}}
---
title: Param shortcode
linkTitle: Param
-description: Insert a parameter from front matter or site configuration into your content using the param shortcode.
+description: Insert a parameter from front matter or your project configuration into your content using the param shortcode.
categories: []
keywords: []
---
## Privacy
-Adjust the relevant privacy settings in your site configuration.
+Adjust the relevant privacy settings in your project configuration.
{{< code-toggle config=privacy.vimeo />}}
## Privacy
-Adjust the relevant privacy settings in your site configuration.
+Adjust the relevant privacy settings in your project configuration.
{{< code-toggle config=privacy.x />}}
The source code for the simple version of the shortcode is available [in this file].
-If you enable simple mode you may want to disable the hardcoded inline styles by setting `disableInlineCSS` to `true` in your site configuration. The default value for this setting is `false`.
+If you enable simple mode you may want to disable the hardcoded inline styles by setting `disableInlineCSS` to `true` in your project configuration. The default value for this setting is `false`.
{{< code-toggle config=services.x />}}
## Privacy
-Adjust the relevant privacy settings in your site configuration.
+Adjust the relevant privacy settings in your project configuration.
{{< code-toggle config=privacy.youTube />}}
### Privacy {#privacy-disqus}
-Adjust the relevant privacy settings in your site configuration.
+Adjust the relevant privacy settings in your project configuration.
{{< code-toggle config=privacy.disqus />}}
### Privacy {#privacy-google-analytics}
-Adjust the relevant privacy settings in your site configuration.
+Adjust the relevant privacy settings in your project configuration.
{{< code-toggle config=privacy.googleAnalytics />}}
tags = []
{{</ code-toggle >}}
-Hugo uses the page title and description for the title and description metadata.
-The first 6 URLs from the `images` array are used for image metadata.
-If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with file names matching `*feature*`, `*cover*`, or `*thumbnail*` are used for image metadata.
+Hugo uses the page title and description for the title and description metadata. The first 6 URLs from the `images` array are used for image metadata. If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with file names matching `*feature*`, `*cover*`, or `*thumbnail*` are used for image metadata.
Various optional metadata can also be set:
>
> `{{ partial "twitter_cards.html" . }}`
-Hugo includes an embedded template for [X (Twitter) Cards](https://developer.x.com/en/docs/twitter-for-websites/cards/overview/abouts-cards),
-metadata used to attach rich media to Tweets linking to your site.
+Hugo includes an embedded template for [X (Twitter) Cards](https://developer.x.com/en/docs/twitter-for-websites/cards/overview/abouts-cards), metadata used to attach rich media to Tweets linking to your site.
To include the embedded template:
images = ["post-cover.png"]
{{</ code-toggle >}}
-If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with file names matching `*feature*`, `*cover*`, or `*thumbnail*` are used for image metadata.
-If no image resources with those names are found, the images defined in the [site config](/configuration/) are used instead.
-If no images are found at all, then an image-less Twitter `summary` card is used instead of `summary_large_image`.
+If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with file names matching `*feature*`, `*cover*`, or `*thumbnail*` are used for image metadata. If no image resources with those names are found, the images defined in your [project configuration](/configuration/) are used instead. If no images are found at all, then an image-less Twitter `summary` card is used instead of `summary_large_image`.
Hugo uses the page title and description for the card's title and description fields. The page summary is used if no description is given.
-Set the value of `twitter:site` in your site configuration:
+Set the value of `twitter:site` in your project configuration:
{{< code-toggle file=hugo >}}
[params.social]
`Page`|[`Params`](methods/page/params/)|Returns a map of custom parameters as defined in the front matter of the given page.
`Page`|[`Title`](methods/page/title/)|Returns the title of the given page.
`Site`|[`Data`](methods/site/data/)|Returns a data structure composed from the files in the `data` directory.
-`Site`|[`Params`](methods/site/params/)|Returns a map of custom parameters as defined in the site configuration.
-`Site`|[`Title`](methods/site/title/)|Returns the title as defined in the site configuration.
+`Site`|[`Params`](methods/site/params/)|Returns a map of custom parameters as defined in your project configuration.
+`Site`|[`Title`](methods/site/title/)|Returns the title as defined in the your project configuration.
Chain the method to its object with a dot (`.`) as shown below, remembering that the leading dot represents the [current context].
See documentation for the [`Params`](/methods/site/params/) method on a `Site` object.
-With this site configuration:
+With this project configuration:
{{< code-toggle file=hugo >}}
title = 'ABC Widgets'
Three factors determine how to render a menu:
-1. The method used to define the menu entries: [automatic], [in front matter], or [in site configuration]
+1. The method used to define the menu entries: [automatic], in [front matter], or in your [project configuration]
1. The menu structure: flat or nested
-1. The method used to [localize the menu entries]: site configuration or translation tables
+1. The method used to [localize the menu entries]: project configuration or translation tables
The example below handles every combination.
## Menu entry parameters
-When you define menu entries [in site configuration] or [in front matter], you can include a `params` key as shown in these examples:
+When you define menu entries in your [project configuration] or in [front matter], you can include a `params` key as shown in these examples:
-- [Menu entry defined in site configuration]
+- [Menu entry defined in your project configuration]
- [Menu entry defined in front matter]
This simplistic example renders a `class` attribute for each anchor element. Code defensively using `with` or `if` to handle entries where `params.class` is not defined.
[automatic]: /content-management/menus/#define-automatically
[define menu entries]: /content-management/menus/
[defining menu entries]: /content-management/menus/
-[in front matter]: /content-management/menus/#define-in-front-matter
-[in site configuration]: /content-management/menus/#define-in-site-configuration
+[front matter]: /content-management/menus/#define-in-front-matter
[localize the menu entries]: /content-management/multilingual/#menus
[menu entry defined in front matter]: /content-management/menus/#example
-[menu entry defined in site configuration]: /configuration/menus
+[menu entry defined in your project configuration]: /configuration/menus
[menu methods]: /methods/menu/
[multilingual]: /content-management/multilingual/#menus
+[project configuration]: /content-management/menus/#define-in-project-configuration
- Paginate any page collection
- Filter, sort, and group the page collection
-- Override the number of pages per pager as defined in your site configuration
+- Override the number of pages per pager as defined in your project configuration
By comparison, the `Paginator` method paginates the page collection passed into the template, and you cannot override the number of pages per pager.
└── _index.md
```
-And this site configuration:
+And this project configuration:
{{< code-toggle file=hugo >}}
[pagination]
└── index.html
```
-To disable alias generation for the first pager, change your site configuration:
+To disable alias generation for the first pager, change your project configuration:
{{< code-toggle file=hugo >}}
[pagination]
aliases: [/extras/robots-txt/]
---
-To generate a robots.txt file from a template, change the [site configuration]:
+To generate a robots.txt file from a template, change your [project configuration]:
{{< code-toggle file=hugo >}}
enableRobotsTXT = true
> [!note]
> To create a robots.txt file without using a template:
>
-> 1. Set `enableRobotsTXT` to `false` in the site configuration.
+> 1. Set `enableRobotsTXT` to `false` in your project configuration.
> 1. Create a robots.txt file in the `static` directory.
>
-> Remember that Hugo copies everything in the static director to the root of `publishDir` (typically `public`) when you build your site.
+> Remember that Hugo copies everything in the static director to the root of `publishDir` (typically `public`) when you build your project.
[embedded template]: <{{% eturl robots %}}>
-[site configuration]: /configuration/
+[project configuration]: /configuration/
## Configuration
-By default, when you build your site, Hugo generates RSS feeds for home, section, taxonomy, and term pages. Control feed generation in your site configuration. For example, to generate feeds for home and section pages, but not for taxonomy and term pages:
+By default, when you build your project, Hugo generates RSS feeds for home, section, taxonomy, and term pages. Control feed generation in your project configuration. For example, to generate feeds for home and section pages, but not for taxonomy and term pages:
{{< code-toggle file=hugo >}}
[outputs]
disableKinds = ['rss']
{{< /code-toggle >}}
-By default, the number of items in each feed is unlimited. Change this as needed in your site configuration:
+By default, the number of items in each feed is unlimited. Change this as needed in your project configuration:
{{< code-toggle file=hugo >}}
[services.rss]
Set `limit` to `-1` to generate an unlimited number of items per feed.
-The built-in RSS template will render the following values, if present, from your site configuration:
+The built-in RSS template will render the following values, if present, from your project configuration:
{{< code-toggle file=hugo >}}
copyright = '© 2023 ABC Widgets, Inc.'
## Disable sitemap generation
-You may disable sitemap generation in your site configuration:
+You may disable sitemap generation in your project configuration:
{{< code-toggle file=hugo >}}
disableKinds = ['sitemap']
And for all the other community projects around Hugo:
- [diego](https://github.com/ttybitnik/diego) - A CLI tool that integrates with Hugo to assist in importing and utilizing exported social media data from popular services on Hugo websites.
-- [Emacs Easy Hugo](https://github.com/masasam/emacs-easy-hugo) - Emacs package for writing blog posts in Markdown or org-mode and building your site with Hugo.
+- [Emacs Easy Hugo](https://github.com/masasam/emacs-easy-hugo) - Emacs package for writing blog posts in Markdown or org-mode and building your project with Hugo.
- [Hugo SFTP Upload](https://github.com/thomasmey/HugoSftpUpload) - Sync the local build of your Hugo website with your remote web server via SFTP.
- [HugoPhotoSwipe](https://github.com/GjjvdBurg/HugoPhotoSwipe) - Make it easy to create image galleries using PhotoSwipe.
- [JAMStack Themes](https://jamstackthemes.dev/ssg/hugo/) - A collection of site themes filterable by static site generator and supported CMS to help build CMS-connected sites using Hugo (linking to Hugo-specific themes).
### Environment variables
`HUGO_MINIFY_TDEWOLFF_HTML_KEEPCOMMENTS=true`
-: Retain HTML comments even if minification is enabled. This takes precedence over `minify.tdewolff.html.keepComments` in the site configuration. If you minify without keeping HTML comments when performing this audit, you will not be able to detect when raw HTML has been omitted.
+: Retain HTML comments even if minification is enabled. This takes precedence over `minify.tdewolff.html.keepComments` in your project configuration. If you minify without keeping HTML comments when performing this audit, you will not be able to detect when raw HTML has been omitted.
`HUGO_ENABLEMISSINGTRANSLATIONPLACEHOLDERS=true`
-: Show a placeholder instead of the default value or an empty string if a translation is missing. This takes precedence over `enableMissingTranslationPlaceholders` in the site configuration.
+: Show a placeholder instead of the default value or an empty string if a translation is missing. This takes precedence over `enableMissingTranslationPlaceholders` in your project configuration.
### Grep options
To see the INFO messages, you must use the `--logLevel` command line flag:
```text
-hugo --logLevel info
+hugo build --logLevel info
```
To limit the output to deprecation notices:
```text
-hugo --logLevel info | grep deprecate
+hugo build --logLevel info | grep deprecate
```
Run the above command every time you upgrade Hugo.
---
title: Logging
-description: Enable logging to inspect events while building your site.
+description: Enable logging to inspect events while building your project.
categories: []
keywords: []
---
: Display error messages only.
```sh
- hugo --logLevel error
+ hugo build --logLevel error
```
warn
: Display warning and error messages.
```sh
- hugo --logLevel warn
+ hugo build --logLevel warn
```
info
: Display information, warning, and error messages.
```sh
- hugo --logLevel info
+ hugo build --logLevel info
```
debug
: Display debug, information, warning, and error messages.
```sh
- hugo --logLevel debug
+ hugo build --logLevel debug
```
> [!note]
Hugo is fast, but inefficient templates impede performance. Enable template metrics to determine which templates take the most time, and to identify caching opportunities:
```sh
-hugo --templateMetrics --templateMetricsHints
+hugo build --templateMetrics --templateMetricsHints
```
The result will look something like this:
Description: |-
Append appends args up to the last one to the slice in the last argument.
This construct allows template constructs like this:
-
+
{{ $pages = $pages | append $p2 $p1 }}
-
+
Note that with 2 arguments where both are slices of the same type,
the first slice will be appended to the second:
-
+
{{ $pages = $pages | append .Site.RegularPages }}
Examples: []
Apply:
Description: |-
Complement gives the elements in the last element of ls that are not in
any of the others.
-
+
All elements of ls must be slices or arrays of comparable types.
-
+
The reasoning behind this rather clumsy API is so we can do this in the templates:
-
+
{{ $c := .Pages | complement $last4 }}
Examples:
- - '{{ slice "a" "b" "c" "d" "e" "f" | complement (slice "b" "c") (slice "d" "e") }}'
Index returns the result of indexing its first argument by the following
arguments. Thus "index x 1 2 3" is, in Go syntax, x[1][2][3]. Each
indexed item must be a map, slice, or array.
-
+
Adapted from Go stdlib src/text/template/funcs.go.
-
+
We deviate from the stdlib mostly because of https://github.com/golang/go/issues/14751.
Examples: []
Intersect:
Description: |-
Merge creates a copy of the final parameter in params and merges the preceding
parameters into it in reverse order.
-
+
Currently only maps are supported. Key handling is case insensitive.
Examples:
- - '{{ dict "title" "Hugo Rocks!" | collections.Merge (dict "title" "Default Title" "description" "Yes, Hugo Rocks!") | sort }}'
- args
Description: |-
Seq creates a sequence of integers from args. It's named and used as GNU's seq.
-
+
Examples:
-
+
3 => 1, 2, 3
1 2 4 => 1, 3
-3 => -1, -2, -3
- v2
Description: |-
Conditional can be used as a ternary operator.
-
+
It returns v1 if cond is true, else v2.
Examples:
- - '{{ cond (eq (add 2 2) 4) "2+2 is 4" "what?" | safeHTML }}'
Dump returns a object dump of val as a string.
Note that not every value passed to Dump will print so nicely, but
we'll improve on that.
-
+
We recommend using the "go" Chroma lexer to format the output
nicely.
-
+
Also note that the output from Dump may change from Hugo version to the next,
so don't depend on a specific output.
Examples:
- v
Description: |-
Humanize returns the humanized form of v.
-
+
If v is either an integer or a string containing an integer
value, the behavior is to add the appropriate ordinal.
Examples:
Description: |-
FormatAccounting returns the currency representation of number for the given currency and precision
for the current language in accounting notation.
-
+
The return value is formatted with at least two decimal places.
Examples:
- - '{{ 512.5032 | lang.FormatAccounting 2 "NOK" }}'
Description: |-
FormatCurrency returns the currency representation of number for the given currency and precision
for the current language.
-
+
The return value is formatted with at least two decimal places.
Examples:
- - '{{ 512.5032 | lang.FormatCurrency 2 "USD" }}'
so if you organize your resources in sub-folders, you need to be explicit about it, e.g.:
"images/*.png". To match any PNG image anywhere in the bundle you can do "**.png", and
to match all PNG images below the images folder, use "images/**.jpg".
-
+
The matching is case insensitive.
-
+
Match matches by using the files name with path relative to the file system root
with Unix style slashes (/) and no leading slash, e.g. "images/logo.png".
-
+
See https://github.com/gobwas/glob for the full rules set.
-
+
It looks for files in the assets file system.
-
+
See Match for a more complete explanation about the rules used.
Examples: []
Minify:
expression in content. Each element is a slice of strings holding the text
of the leftmost match of the regular expression and the matches, if any, of
its subexpressions.
-
+
By default all matches will be included. The number of matches can be
limited with the optional limit parameter. A return value of nil indicates
no match.
- s
Description: |-
Emojify returns a copy of s with all emoji codes replaced with actual emojis.
-
+
See http://www.emoji-cheat-sheet.com/
Examples:
- - '{{ "I :heart: Hugo" | emojify }}'
<div
x-data
- class="render-hook-codeblock font-mono not-prose relative mt-6 mb-8 border-1 border-gray-200 dark:border-gray-800 bg-light dark:bg-dark">
+ class="render-hook-codeblock font-mono not-prose relative mt-6 mb-8 border border-gray-200 dark:border-gray-800 bg-light dark:bg-dark">
{{- $fileSelectClass := "select-none" }}
{{- if $copy }}
{{- $fileSelectClass = "select-text" }}
*/}}
{{/* prettier-ignore-end */ -}}
{{- $t := debug.Timer "validateKeywords" }}
-{{- $allowedKeywords := collections.Apply site.Data.keywords "strings.ToLower" "." }}
+{{- $allowedKeywords := collections.Apply hugo.Data.keywords "strings.ToLower" "." }}
{{- range $p := site.Pages }}
{{- range .Params.keywords }}
{{- if not (in $allowedKeywords (lower .)) }}
{{ $isFooter := (eq $gtag "footer") }}
{{ $utmSource := cond $isFooter "hugofooter" "hugohome" }}
{{ $containerClass := .containerClass | default "mx-auto max-w-7xl px-6 lg:px-8" }}
-{{ with .ctx.Site.Data.sponsors }}
+{{ with hugo.Data.sponsors }}
<div class="{{ $containerClass }}">
<h2 class="font-bold text-2xl mb-6 tracking-tighter">Hugo Sponsors</h2>
<div class="grid grid-cols-1 lg:grid-cols-3 gap-x-8 gap-y-6">
<th>Identifiers</th>
</thead>
<tbody>
- {{- range site.Data.docs.chroma.lexers }}
+ {{- range hugo.Data.docs.chroma.lexers }}
<tr>
<td>{{ .Name }}</td>
<td>
{{- /*
Renders syntax-highlighted configuration data in JSON, TOML, and YAML formats.
-@param {string} [config] The section of site.Data.docs.config to render.
+@param {string} [config] The section of hugo.Data.docs.config to render.
@param {bool} [copy=false] Whether to display a copy-to-clipboard button.
-@param {string} [dataKey] The section of site.Data.docs to render.
+@param {string} [dataKey] The section of hugo.Data.docs to render.
@param {string} [file] The file name to display above the rendered code.
@param {bool} [fm=false] Whether to render the code as front matter.
-@param {bool} [skipHeader=false] Whether to omit top level key(s) when rendering a section of site.Data.docs.config.
+@param {bool} [skipHeader=false] Whether to omit top level key(s) when rendering a section of hugo.Data.docs.config.
@example {{< code-toggle file=hugo config=build />}}
{{- if $config }}
{{- $file = $file | default "hugo" }}
{{- $sections := (split $config ".") }}
- {{- $configSection := index $.Site.Data.docs.config $sections }}
+ {{- $configSection := index hugo.Data.docs.config $sections }}
{{- $code = dict $sections $configSection }}
{{- if $skipHeader }}
{{- $code = $configSection }}
{{- else if $dataKey }}
{{- $file = $file | default $dataKey }}
{{- $sections := (split $dataKey ".") }}
- {{- $code = index $.Site.Data.docs $sections }}
+ {{- $code = index hugo.Data.docs $sections }}
{{- else }}
{{- $code = $.Inner }}
{{- end }}
{{ $package := (index .Params 0) }}
{{ $listname := (index .Params 1) }}
-{{ $list := (index (index .Site.Data.docs $package) $listname) }}
+{{ $list := (index (index hugo.Data.docs $package) $listname) }}
{{ $fields := after 2 .Params }}
*/ -}}
{{/* prettier-ignore-end */ -}}
{{- with $filename := or (.Get "filename") (.Get 0) }}
- {{- with site.Data.embedded_template_urls }}
+ {{- with hugo.Data.embedded_template_urls }}
{{- with index . $filename }}
- {{- urls.JoinPath site.Data.embedded_template_urls.base_url . }}
+ {{- urls.JoinPath hugo.Data.embedded_template_urls.base_url . }}
{{- else }}
{{- errorf "The %q shortcode was unable to find a URL for the embedded template named %q. Check the name. See %s" $.Name $filename $.Position }}
{{- end }}
{{/* Build slice of filtered pages. */}}
{{ with $filter }}
- {{ with index site.Data.page_filters . }}
+ {{ with index hugo.Data.page_filters . }}
{{ range . }}
{{ with site.GetPage . }}
{{ $filteredPages = $filteredPages | append . }}
{{/* prettier-ignore-end */ -}}
{{- /* Create scratch map of key:filename. */}}
{{- $s := newScratch }}
-{{- range $k, $v := site.Data.docs.config }}
+{{- range $k, $v := hugo.Data.docs.config }}
{{- if or (reflect.IsMap .) (reflect.IsSlice .) }}
{{- $s.Set $k ($k | humanize | anchorize) }}
{{- end }}
{{- $examples := $examples | append $example }}
{{- /* Render */}}
-{{- with site.Data.docs.chroma.styles }}
+{{- with hugo.Data.docs.chroma.styles }}
{{- range $style := . }}
### {{ $style }} {class="!mt-7 !mb-6"}{{/* Do not indent. */}}
command = "npm ls && hugo --gc --minify"
[build.environment]
- HUGO_VERSION = "0.155.3"
+ HUGO_VERSION = "0.156.0"
[context.production.environment]
HUGO_ENV = "production"
projects / brevno-suite / hugo / commitdiff