{{ $query_params := .query_params | default "" }}
{{ $url := printf "%s?%s%s" .link $query_params (querify "utm_source" (.utm_source | default $utmSource ) "utm_medium" "banner" "utm_campaign" (.utm_campaign | default "hugosponsor") "utm_content" (.utm_content | default "gohugoio")) | safeURL }}
{{ $logo := resources.Get .logo }}
- {{ if hugo.IsProduction }}
- {{ $gtagID := printf "Sponsor %s %s" .name $gtag | title }}
-
- {{ with $logo }}{{ .Content | safeHTML }}{{ end }}
-
+ {{ $gtagID := printf "Sponsor %s %s" .name $gtag | title }}
+ {{ $classes := "" }}
+ {{ if .show_on_hover }}
+ {{ $classes = printf "%s show-on-hover" $classes }}
+ {{ end }}
+ {{ if $isFooter }}
+ {{ $classes = printf "%s f3" $classes }}
{{ else }}
-
- {{ with $logo }}{{ .Content | safeHTML }}{{ end }}
-
+ {{ $classes = printf "%s f1" $classes }}
{{ end }}
+
+ {{ with $logo }}
+ {{ .Content | safeHTML }}
+ {{ else }}
+ {{ .name }}
+ {{ end }}
+
{{ end }}
diff --git a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/utilities/get-remote-data.html b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/utilities/get-remote-data.html
new file mode 100644
index 00000000000..69ac41da40a
--- /dev/null
+++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/utilities/get-remote-data.html
@@ -0,0 +1,23 @@
+{{/*
+Parses the serialized data from the given URL and returns a map or an array.
+
+Supports CSV, JSON, TOML, YAML, and XML.
+
+@param {string} . The URL from which to retrieve the serialized data.
+@returns {any}
+
+@example {{ partial "get-remote-data.html" "https://example.org/foo.json" }}
+*/}}
+
+{{ $url := . }}
+{{ $data := dict }}
+{{ with resources.GetRemote $url }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else }}
+ {{ $data = .Content | transform.Unmarshal }}
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+{{ end }}
+{{ return $data }}
diff --git a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/eturl.html b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/eturl.html
new file mode 100644
index 00000000000..c0cf30aec7b
--- /dev/null
+++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/eturl.html
@@ -0,0 +1,36 @@
+{{- /*
+Renders an absolute URL to the source code for an embedded template.
+
+Accepts either positional or named parameters, and depends on the
+embedded_templates.toml file in the data directory.
+
+@param {string} filename The embedded template's file name, excluding extension.
+
+@returns template.HTML
+
+@example {{% et robots.txt %}}
+@example {{% et filename=robots.txt %}}
+*/}}
+
+{{- /* Get parameters. */}}
+{{- $filename := "" -}}
+{{- if .IsNamedParams -}}
+ {{- $filename = .Get "filename" -}}
+{{- else -}}
+ {{- $filename = .Get 0 -}}
+{{- end -}}
+
+{{- /* Render. */}}
+{{- with $filename -}}
+ {{- with site.Data.embedded_template_urls -}}
+ {{- with index . $filename -}}
+ {{- urls.JoinPath site.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 -}}
+ {{- else -}}
+ {{- errorf "The %q shortcode was unable to find the embedded_template_urls data file in the site's data directory. See %s" $.Name $.Position -}}
+ {{- end -}}
+{{- else -}}
+ {{- errorf "The %q shortcodes requires a named or positional parameter, the file name of the embedded template, excluding its extension. See %s" .Name .Position -}}
+{{- end -}}
diff --git a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/img.html b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/img.html
index 50d4da9edba..dd8c60e18bd 100644
--- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/img.html
+++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/img.html
@@ -119,8 +119,8 @@
{{- end }}
{{- $validFilters := slice
- "autoorient" "brightness" "colorbalance" "colorize" "contrast" "gamma"
- "gaussianblur" "grayscale" "hue" "invert" "none" "opacity" "overlay"
+ "autoorient" "brightness" "colorbalance" "colorize" "contrast" "dither"
+ "gamma" "gaussianblur" "grayscale" "hue" "invert" "none" "opacity" "overlay"
"padding" "pixelate" "process" "saturation" "sepia" "sigmoid" "text"
"unsharpmask"
}}
@@ -198,6 +198,8 @@
{{- $ctx = merge $ctx (dict "argName" "percentage" "argValue" (index $filterArgs 0) "min" -100 "max" 100) }}
{{- template "validate-arg-value" $ctx }}
{{- $f = images.Contrast (index $filterArgs 0) }}
+{{- else if eq $filter "dither" }}
+ {{- $f = images.Dither }}
{{- else if eq $filter "gamma" }}
{{- $ctx = merge $ctx (dict "argsRequired" 1) }}
{{- template "validate-arg-count" $ctx }}
@@ -354,7 +356,7 @@
{{- if $u.IsAbs }}
{{- with resources.GetRemote $u.String }}
{{- with .Err }}
- {{- errorf "%s" }}
+ {{- errorf "%s" . }}
{{- else }}
{{- /* This is a remote resource. */}}
{{- $r = . }}
diff --git a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/new-in.html b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/new-in.html
index e22a91f3d96..606d2219ca5 100644
--- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/new-in.html
+++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/new-in.html
@@ -27,9 +27,7 @@
{{- warnf "This call to the %q shortcode should be removed: %s. The button is now hidden because the specified version (%s) is older than the display threshold." $.Name $.Position $version }}
{{- end }}
{{- else }}
-
+ New in v{{ $version }}
{{- end }}
{{- else }}
{{- errorf "The %q shortcode requires a positional parameter (version). See %s" .Name .Position }}
diff --git a/docs/_vendor/github.com/gohugoio/gohugoioTheme/static/images/GitHub-Mark-64px.png b/docs/_vendor/github.com/gohugoio/gohugoioTheme/static/images/GitHub-Mark-64px.png
deleted file mode 100644
index 9965f8d33aa..00000000000
Binary files a/docs/_vendor/github.com/gohugoio/gohugoioTheme/static/images/GitHub-Mark-64px.png and /dev/null differ
diff --git a/docs/_vendor/github.com/gohugoio/gohugoioTheme/static/images/Github.svg b/docs/_vendor/github.com/gohugoio/gohugoioTheme/static/images/Github.svg
new file mode 100644
index 00000000000..f202ff8783f
--- /dev/null
+++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/static/images/Github.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/_vendor/modules.txt b/docs/_vendor/modules.txt
index a63ac09b9d6..100c6fc6f21 100644
--- a/docs/_vendor/modules.txt
+++ b/docs/_vendor/modules.txt
@@ -1 +1 @@
-# github.com/gohugoio/gohugoioTheme v0.0.0-20240201183016-8e648a3b5342
+# github.com/gohugoio/gohugoioTheme v0.0.0-20240619093131-b595d5fb8c52
diff --git a/docs/assets/images/examples/zion-national-park-grayscale.jpg b/docs/assets/images/examples/zion-national-park-grayscale.jpg
deleted file mode 100644
index 908bd88c6b9..00000000000
Binary files a/docs/assets/images/examples/zion-national-park-grayscale.jpg and /dev/null differ
diff --git a/docs/config/_default/menus/menus.en.toml b/docs/config/_default/menus/menus.en.toml
index cd337cbeeea..b0da4881787 100644
--- a/docs/config/_default/menus/menus.en.toml
+++ b/docs/config/_default/menus/menus.en.toml
@@ -1,6 +1,6 @@
[[docs]]
identifier = 'about'
-name = 'About Hugo'
+name = 'About'
pageRef = '/about/'
weight = 10
@@ -15,60 +15,60 @@ name = 'Getting started'
weight = 30
identifier = 'getting-started'
pageRef = '/getting-started/'
+
+[[docs]]
+name = 'Quick reference'
+weight = 40
+identifier = 'quick-reference'
+pageRef = '/quick-reference/'
post = 'break'
[[docs]]
name = 'Content management'
-weight = 40
+weight = 50
identifier = 'content-management'
post = 'expanded'
pageRef = '/content-management/'
[[docs]]
name = 'Templates'
-weight = 50
+weight = 60
identifier = 'templates'
pageRef = '/templates/'
[[docs]]
name = 'Functions'
-weight = 60
+weight = 70
identifier = 'functions'
pageRef = '/functions/'
[[docs]]
name = 'Methods'
-weight = 70
+weight = 80
identifier = 'methods'
pageRef = '/methods/'
[[docs]]
-name = 'Quick reference'
-weight = 80
-identifier = 'quick-reference'
-pageRef = '/quick-reference/'
-
-[[docs]]
-name = 'Variables'
-weight = 85
-identifier = 'variables'
-pageRef = '/variables/'
+name = 'Render hooks'
+weight = 90
+identifier = 'render-hooks'
+pageRef = '/render-hooks/'
[[docs]]
name = 'Hugo Modules'
-weight = 90
+weight = 100
identifier = 'modules'
pageRef = '/hugo-modules/'
[[docs]]
name = 'Hugo Pipes'
-weight = 100
+weight = 110
identifier = 'hugo-pipes'
pageRef = '/hugo-pipes/'
[[docs]]
name = 'CLI'
-weight = 110
+weight = 120
post = 'break'
identifier = 'commands'
pageRef = '/commands/'
@@ -77,25 +77,25 @@ pageRef = '/commands/'
[[docs]]
name = 'Troubleshooting'
-weight = 120
+weight = 130
identifier = 'troubleshooting'
pageRef = '/troubleshooting/'
[[docs]]
name = 'Developer tools'
-weight = 130
+weight = 140
identifier = 'developer-tools'
pageRef = '/tools/'
[[docs]]
name = 'Hosting and deployment'
-weight = 140
+weight = 150
identifier = 'hosting-and-deployment'
pageRef = '/hosting-and-deployment/'
[[docs]]
name = 'Contribute'
-weight = 150
+weight = 160
post = 'break'
identifier = 'contribute'
pageRef = '/contribute/'
diff --git a/docs/content/en/_index.md b/docs/content/en/_index.md
index 69d40ebcf62..96ba0c4132a 100644
--- a/docs/content/en/_index.md
+++ b/docs/content/en/_index.md
@@ -15,7 +15,7 @@ features:
- heading: Shortcodes
image_path: /images/icon-shortcodes.svg
tagline: Hugo's shortcodes are Markdown's hidden superpower.
- copy: We love the beautiful simplicity of markdown’s syntax, but there are times when we want more flexibility. Hugo shortcodes allow for both beauty and flexibility.
+ copy: We love the beautiful simplicity of Markdown’s syntax, but there are times when we want more flexibility. Hugo shortcodes allow for both beauty and flexibility.
- heading: Built-in Templates
image_path: /images/icon-built-in-templates.svg
diff --git a/docs/content/en/about/_index.md b/docs/content/en/about/_index.md
index 3a831902917..333a9ba36f8 100644
--- a/docs/content/en/about/_index.md
+++ b/docs/content/en/about/_index.md
@@ -1,16 +1,16 @@
---
title: About Hugo
-linkTitle: Overview
-description: Hugo's features, roadmap, license, and motivation.
+linkTitle: In this section
+description: Learn about Hugo and its features, security model, and privacy protections.
categories: []
keywords: []
menu:
docs:
- identifier: about-hugo-overview
+ identifier: about-hugo-in-this-section
parent: about
weight: 10
weight: 10
aliases: [/about-hugo/,/docs/]
---
-Hugo is not your average static site generator.
+Learn about Hugo and its features, privacy protections, and security model.
diff --git a/docs/content/en/about/benefits.md b/docs/content/en/about/benefits.md
deleted file mode 100644
index 82952c4e6e4..00000000000
--- a/docs/content/en/about/benefits.md
+++ /dev/null
@@ -1,36 +0,0 @@
----
-title: Benefits of static site generators
-linkTitle: Static site generators
-description: Improved performance, security and ease of use are just a few of the reasons static site generators are so appealing.
-categories: [about]
-keywords: [ssg,static,performance,security]
-menu:
- docs:
- parent: about
- weight: 40
-weight: 40
----
-
-The purpose of website generators is to render content into HTML files. Most are "dynamic site generators." That means the HTTP server---i.e., the program that sends files to the browser to be viewed---runs the generator to create a new HTML file every time an end user requests a page.
-
-Over time, dynamic site generators were programmed to cache their HTML files to prevent unnecessary delays in delivering pages to end users. A cached page is a static version of a web page.
-
-Hugo takes caching a step further and all HTML files are rendered on your computer. You can review the files locally before copying them to the computer hosting the HTTP server. Since the HTML files aren't generated dynamically, we say that Hugo is a *static site generator*.
-
-This has many benefits. The most noticeable is performance. HTTP servers are *very* good at sending files---so good, in fact, that you can effectively serve the same number of pages with a fraction of the memory and CPU needed for a dynamic site.
-
-## More on static site generators
-
-* ["An Introduction to Static Site Generators", David Walsh]
-* ["Hugo vs. WordPress page load speed comparison: Hugo leaves WordPress in its dust", GettingThingsTech][hugovwordpress]
-* ["Static Site Generators", O'Reilly]
-* [StaticGen: Top Open-Source Static Site Generators (GitHub Stars)]
-* ["Top 10 Static Website Generators", Netlify blog]
-* ["The Resurgence of Static", dotCMS][dotcms]
-
-["An Introduction to Static Site Generators", David Walsh]: https://davidwalsh.name/introduction-static-site-generators
-["Static Site Generators", O'Reilly]: https://github.com/gohugoio/hugoDocs/files/1242701/static-site-generators.pdf
-["Top 10 Static Website Generators", Netlify blog]: https://www.netlify.com/blog/2016/05/02/top-ten-static-website-generators/
-[hugovwordpress]: https://gettingthingstech.com/hugo-vs.-wordpress-page-load-speed-comparison-hugo-leaves-wordpress-in-its-dust/
-[StaticGen: Top Open-Source Static Site Generators (GitHub Stars)]: https://www.staticgen.com/
-[dotcms]: https://dotcms.com/blog/post/the-resurgence-of-static
diff --git a/docs/content/en/about/features.md b/docs/content/en/about/features.md
index a94ce5526e9..ff7e9ce138e 100644
--- a/docs/content/en/about/features.md
+++ b/docs/content/en/about/features.md
@@ -1,6 +1,6 @@
---
-title: Hugo features
-description: Hugo boasts blistering speed, robust content management, and a powerful templating language making it a great fit for all kinds of static websites.
+title: Features
+description: Hugo's rich and powerful feature set provides the framework and tools to create static sites that build in seconds, often less.
categories: [about]
keywords: []
menu:
@@ -11,70 +11,126 @@ weight: 30
toc: true
---
-## General
-
-* [Extremely fast] build times (< 1 ms per page)
-* Completely cross platform, with [easy installation][install] on macOS, Linux, Windows, and more
-* Renders changes on the fly with [LiveReload] as you develop
-* [Powerful theming]
-* [Host your site anywhere][hostanywhere]
-
-## Organization
-
-* Straightforward [organization for your projects], including website sections
-* Customizable [URLs]
-* Support for configurable [taxonomies], including categories and tags
-* [Sort content] as you desire through powerful template [functions]
-* Automatic [table of contents] generation
-* [Dynamic menu] creation
-* [Pretty URLs] support
-* [Permalink] pattern support
-* Redirects via [aliases]
-
-## Content
-
-* Native Markdown and Emacs Org-Mode support, as well as other languages via *external helpers* (see [supported formats])
-* TOML, YAML, and JSON metadata support in [front matter]
-* Customizable [homepage]
-* Multiple [content types]
-* Automatic and user defined [content summaries]
-* [Shortcodes] to enable rich content inside of Markdown
-* ["Minutes to Read"][pagevars] functionality
-* ["WordCount"][pagevars] functionality
-
-## Additional features
-
-* Integrated [Disqus] comment support
-* Integrated [Google Analytics] support
-* Automatic [RSS] creation
-* Support for [Go] HTML templates
-* [Syntax highlighting] powered by [Chroma]
-
-[aliases]: /content-management/urls/#aliases
-[Chroma]: https://github.com/alecthomas/chroma
-[content summaries]: /content-management/summaries/
-[content types]: /content-management/types/
-[Disqus]: https://disqus.com/
-[Dynamic menu]: /templates/menu-templates/
-[Extremely fast]: https://github.com/bep/hugo-benchmark
-[front matter]: /content-management/front-matter/
-[functions]: /functions/
-[Go]: https://pkg.go.dev/html/template
-[Google Analytics]: https://google-analytics.com/
-[homepage]: /templates/homepage/
-[hostanywhere]: /hosting-and-deployment/
-[install]: /installation/
-[LiveReload]: /getting-started/usage/
-[organization for your projects]: /getting-started/directory-structure/
-[pagevars]: /variables/page/
-[Permalink]: /content-management/urls/#permalinks
-[Powerful theming]: /hugo-modules/theme-components/
-[Pretty URLs]: /content-management/urls/
-[RSS]: /templates/rss/
+## Framework
+
+[Multiplatform]
+: Install Hugo's single executable on Linux, macOS, Windows, and more.
+
+[Multilingual]
+: Localize your project for each language and region, including translations, images, dates, currencies, numbers, percentages, and collation sequence. Hugo's multilingual framework supports single-host and multihost configurations.
+
+[Output formats]
+: Render each page of your site to one or more output formats, with granular control by page kind, section, and path. While HTML is the default output format, you can add JSON, RSS, CSV, and more. For example, create a REST API to access content.
+
+[Templates]
+: Create templates usings variables, functions, and methods to transform your content, resources, and data into a published page. While HTML templates are the most common, you can create templates for any output format.
+
+[Themes]
+: Reduce development time and cost by using one of the hundreds of themes contributed by the Hugo community. Themes are available for corporate sites, documentation projects, image portfolios, landing pages, personal and professional blogs, resumes, CVs, and more.
+
+[Modules]
+: Reduce development time and cost by creating or importing packaged combinations of archetypes, assets, content, data, templates, translation tables, static files, or configuration settings. A module may serve as the basis for a new site, or to augment an existing site.
+
+[Privacy]
+: Configure the behavior of Hugo's embedded templates and shortcodes to facilitate compliance with regional privacy regulations, including the [GDPR] and [CCPA].
+
+[Security]
+: 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. Other protections prevent "shelling out" to arbitrary applications, limit access to specific environment variables, prevent connections to arbitrary remote data sources, and more.
+
+## Content authoring
+
+[Content formats]
+: Create your content using Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, or reStructuredText. Markdown is the default content format, conforming to the [CommonMark] and [GitHub Flavored Markdown] specifications.
+
+[Markdown attributes]
+: Apply HTML attributes such as `class` and `id` to Markdown images and block elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables.
+
+[Markdown extensions]
+: Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more.
+
+[Markdown render hooks]
+: Override the conversion of Markdown to HTML when rendering fenced code blocks, headings, images, and links. For example, render every standalone image as an HTML `figure` element.
+
+[Diagrams]
+: Use fenced code blocks and Markdown render hooks to include diagrams in your content.
+
+[Mathematics]
+: Include mathematical equations and expressions in Markdown using LaTeX or TeX typesetting syntax.
+
+[Syntax highlighting]
+: Syntactically highlight code examples using Hugo's embedded syntax highlighter, enabled by default for fenced code blocks in Markdown. The syntax highlighter supports hundreds of code languages and dozens of styles.
+
+[Shortcodes]
+: Use Hugo's embedded shortcodes, or create your own, to insert complex content. For example, use shortcodes to include `audio` and `video` elements, render tables from local or remote data sources, insert snippets from other pages, and more.
+
+## Content management
+
+[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.
+
+[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.
+
+[Data]
+: Augment your content using local or remote data sources including CSV, JSON, TOML, YAML, and XML. For example, create a shortcode to render an HTML table from a remote CSV file.
+
+[Menus]
+: Provide rapid access to content via Hugo's menu system, configured automatically, globally, or on a page-by-page basis. The menu system is a key component of Hugo's multilingual architecture.
+
+[URL management]
+: Serve any page from any path via global configuration or on a page-by-page basis.
+
+
+## Asset pipelines
+
+[CSS bundling]
+: Transpile Sass to CSS, bundle, tree shake, minify, create source maps, perform SRI hashing, and integrate with PostCSS.
+
+[JavaScript bundling]
+: Transpile TypeScript and JSX to JavaScript, bundle, tree shake, minify, create source maps, and perform SRI hashing.
+
+[Image processing]
+: Convert, resize, crop, rotate, adjust colors, apply filters, overlay text and images, and extract EXIF data.
+
+## Performance
+
+[Caching]
+: Reduce build time and cost by rendering a partial template once then cache the result, either globally or within a given context. For example, cache the result of an asset pipeline to prevent reprocessing on every rendered page.
+
+[Segmentation]
+: Reduce build time and cost by partitioning your sites into segments. For example, render the home page and the "news section" every hour, and render the entire site once a week.
+
+[Minification]
+: Minify HTML, CSS, and JavaScript to reduce file size, bandwidth consumption, and loading times.
+
+[CCPA]: https://en.wikipedia.org/wiki/California_Consumer_Privacy_Act
+[CSS bundling]: /functions/resources/tocss/
+[Caching]: /functions/partials/includecached/
+[CommonMark]: https://spec.commonmark.org/current/
+[Content adapters]: /content-management/content-adapters/
+[Content formats]: /content-management/formats/
+[Data]: /content-management/data-sources/
+[Diagrams]: /content-management/diagrams/
+[GDPR]: https://en.wikipedia.org/wiki/General_Data_Protection_Regulation
+[GitHub Flavored Markdown]: https://github.github.com/gfm/
+[Image processing]: /content-management/image-processing/
+[JavaScript bundling]: /functions/js/build/
+[Markdown attributes]: /content-management/markdown-attributes/
+[Markdown extensions]: /getting-started/configuration-markup/#goldmark-extensions
+[Markdown render hooks]: /render-hooks/introduction/
+[Mathematics]: /content-management/mathematics/
+[Menus]: /content-management/menus/
+[Minification]: /getting-started/configuration/#configure-minify
+[Modules]: https://gohugo.io/hugo-modules/
+[Multilingual]: /content-management/multilingual/
+[Multiplatform]: /installation/
+[Output formats]: /templates/output-formats/
+[Privacy]: /about/privacy/
+[Security]: /about/security/
+[Segmentation]: /getting-started/configuration/#configure-segments
[Shortcodes]: /content-management/shortcodes/
-[sort content]: /templates/
-[supported formats]: /content-management/formats/
[Syntax highlighting]: /content-management/syntax-highlighting/
-[table of contents]: /content-management/toc/
-[taxonomies]: /content-management/taxonomies/
-[URLs]: /content-management/urls/
+[Taxonomies]: /content-management/taxonomies/
+[Templates]: templates/introduction/
+[Themes]: https://themes.gohugo.io/
+[URL management]: /content-management/urls/
diff --git a/docs/content/en/about/introduction.md b/docs/content/en/about/introduction.md
new file mode 100644
index 00000000000..d89938eed6d
--- /dev/null
+++ b/docs/content/en/about/introduction.md
@@ -0,0 +1,39 @@
+---
+title: Introduction
+description: Hugo is a static site generator written in Go, optimized for speed and designed for flexibility.
+categories: [about]
+keywords: []
+menu:
+ docs:
+ identifier: about-introduction
+ parent: about
+ weight: 20
+weight: 20
+aliases: [/about/what-is-hugo/,/about/benefits/]
+---
+
+Hugo is a [static site generator] written in [Go], optimized for speed and designed for flexibility. With its advanced templating system and fast asset pipelines, Hugo renders a complete site in seconds, often less.
+
+Due to its flexible framework, multilingual support, and powerful taxonomy system, Hugo is widely used to create:
+
+- Corporate, government, nonprofit, education, news, event, and project sites
+- Documentation sites
+- Image portfolios
+- Landing pages
+- Business, professional, and personal blogs
+- Resumes and CVs
+
+Use Hugo's embedded web server during development to instantly see changes to content, structure, behavior, and presentation. Then deploy the site to your host, or push changes to your Git provider for automated builds and deployment.
+
+And with [Hugo Modules], you can share content, assets, data, translations, themes, templates, and configuration with other projects via public or private Git repositories.
+
+Learn more about Hugo's [features], [privacy protections], and [security model].
+
+[Go]: https://go.dev
+[Hugo Modules]: /hugo-modules/
+[static site generator]: https://en.wikipedia.org/wiki/Static_site_generator
+[features]: /about/features
+[security model]: /about/security
+[privacy protections]: /about/privacy
+
+{{< youtube 0RKpf3rK57I >}}
diff --git a/docs/content/en/about/license.md b/docs/content/en/about/license.md
index e488bb87a43..f434b233e7e 100644
--- a/docs/content/en/about/license.md
+++ b/docs/content/en/about/license.md
@@ -2,12 +2,12 @@
title: License
description: Hugo is released under the Apache 2.0 license.
categories: [about]
-keywords: [license,apache]
+keywords: [apache]
menu:
docs:
parent: about
- weight: 70
-weight: 70
+ weight: 60
+weight: 60
---
## Apache License
diff --git a/docs/content/en/about/hugo-and-gdpr.md b/docs/content/en/about/privacy.md
similarity index 84%
rename from docs/content/en/about/hugo-and-gdpr.md
rename to docs/content/en/about/privacy.md
index daf4e80f07d..dcc3b3439f1 100644
--- a/docs/content/en/about/hugo-and-gdpr.md
+++ b/docs/content/en/about/privacy.md
@@ -1,16 +1,16 @@
---
-title: Hugo and the General Data Protection Regulation
-linkTitle: Hugo and the GDPR
-description: About how to configure your Hugo site to meet the new regulations.
+title: Privacy
+linkTitle: Privacy
+description: Configure your site to facilitate compliance with regional privacy regulations.
categories: [about]
keywords: ["GDPR", "Privacy", "Data Protection"]
menu:
docs:
parent: about
- weight: 60
-weight: 60
+ weight: 40
+weight: 40
toc: true
-aliases: [/privacy/,/gdpr/]
+aliases: [/gdpr/,/about/hugo-and-gdpr/]
---
General Data Protection Regulation ([GDPR](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation)) is a regulation in EU law on data protection and privacy for all individuals within the European Union and the European Economic Area. It became enforceable on 25 May 2018.
@@ -22,7 +22,7 @@ aliases: [/privacy/,/gdpr/]
Note that:
* These settings have their defaults setting set to _off_, i.e. how it worked before Hugo `0.41`. You must do your own evaluation of your site and apply the appropriate settings.
- * These settings work with the [internal templates](/templates/internal/). Some theme may contain custom templates for embedding services like Google Analytics. In that case these options have no effect.
+ * These settings work with the [embedded templates](/templates/embedded/). Some theme may contain custom templates for embedding services like Google Analytics. In that case these options have no effect.
* We will continue this work and improve this further in future Hugo versions.
## All privacy settings
@@ -36,8 +36,6 @@ disable = false
[privacy.googleAnalytics]
disable = false
respectDoNotTrack = false
-anonymizeIP = false
-useSessionStorage = false
[privacy.instagram]
disable = false
simple = false
@@ -78,19 +76,9 @@ disable = true
### GoogleAnalytics
-anonymizeIP
-: Enabling this will make it so the users' IP addresses are anonymized within Google Analytics.
-
respectDoNotTrack
: Enabling this will make the GA templates respect the "Do Not Track" HTTP header.
-useSessionStorage
-: Enabling this will disable the use of Cookies and use Session Storage to Store the GA Client ID.
-
-{{% note %}}
-`useSessionStorage` is not supported when using Google Analytics v4 (gtag.js).
-{{% /note %}}
-
### Instagram
simple
diff --git a/docs/content/en/about/security-model.md b/docs/content/en/about/security.md
similarity index 79%
rename from docs/content/en/about/security-model.md
rename to docs/content/en/about/security.md
index af1dd7d75b5..29f2c7ed184 100644
--- a/docs/content/en/about/security-model.md
+++ b/docs/content/en/about/security.md
@@ -1,5 +1,6 @@
---
-title: Hugo's security model
+title: Security model
+linkTitle: Security
description: A summary of Hugo's security model.
categories: [about]
keywords: [security,privacy]
@@ -9,7 +10,7 @@ menu:
weight: 50
weight: 50
toc: true
-aliases: [/security/]
+aliases: [/about/security-model/]
---
## Runtime security
@@ -21,9 +22,8 @@ But when developing and building your site, the runtime is the `hugo` executable
**Hugo's main approach is that of sandboxing and a security policy with strict defaults:**
* Hugo has a virtual file system and only the main project (not third-party components) is allowed to mount directories or files outside the project root.
-* Only the main project can walk symbolic links.
* User-defined components have read-only access to the filesystem.
-* We shell out to some external binaries to support [Asciidoctor](/content-management/formats/#list-of-content-formats) and similar, but those binaries and their flags are predefined and disabled by default (see [Security Policy](#security-policy)). General functions to run arbitrary external OS commands have been [discussed](https://github.com/gohugoio/hugo/issues/796), but not implemented because of security concerns.
+* We shell out to some external binaries to support [Asciidoctor](/content-management/formats/#formats) and similar, but those binaries and their flags are predefined and disabled by default (see [Security Policy](#security-policy)). General functions to run arbitrary external OS commands have been [discussed](https://github.com/gohugoio/hugo/issues/796), but not implemented because of security concerns.
## Security policy
@@ -33,7 +33,16 @@ The default configuration is listed below. Any build using features not in the a
{{< code-toggle config=security />}}
-Note that these and other configuration settings in Hugo can be overridden by the OS environment. If you want to block all remote HTTP fetching of data:
+By default, Hugo permits the [`resources.GetRemote`] function to download files with media types corresponding to an internal allow list. To add media types to the allow list:
+
+[`resources.GetRemote`]: /functions/resources/getremote
+
+{{< code-toggle file=hugo >}}
+[security.http]
+mediaTypes = ['^image/avif$']
+{{< /code-toggle >}}
+
+Note that these and other configuration settings in Hugo can be overridden by the OS environment. For example, if you want to block all remote HTTP fetching of data:
```txt
HUGO_SECURITY_HTTP_URLS=none hugo
diff --git a/docs/content/en/about/what-is-hugo.md b/docs/content/en/about/what-is-hugo.md
deleted file mode 100644
index e4326d1735d..00000000000
--- a/docs/content/en/about/what-is-hugo.md
+++ /dev/null
@@ -1,57 +0,0 @@
----
-title: What is Hugo
-description: Hugo is a fast and modern static site generator written in Go, and designed to make website creation fun again.
-categories: [about]
-keywords: []
-menu:
- docs:
- parent: about
- weight: 20
-weight: 20
-toc: true
-aliases: [/overview/introduction/,/about/why-i-built-hugo/]
----
-
-Hugo is a general-purpose website framework. Technically speaking, Hugo is a [static site generator]. Unlike systems that dynamically build a page with each visitor request, Hugo builds pages when you create or update your content. Since websites are viewed far more often than they are edited, Hugo is designed to provide an optimal viewing experience for your website's end users and an ideal writing experience for website authors.
-
-Websites built with Hugo are extremely fast and secure. Hugo sites can be hosted anywhere, including [Netlify], [Heroku], [GoDaddy], [DreamHost], [GitHub Pages], [GitLab Pages], [Surge], [Firebase], [Google Cloud Storage], [Amazon S3], [Rackspace], [Azure], and [CloudFront] and work well with CDNs. Hugo sites run without the need for a database or dependencies on expensive runtimes like Ruby, Python, or PHP.
-
-We think of Hugo as the ideal website creation tool with nearly instant build times, able to rebuild whenever a change is made.
-
-## How fast is Hugo?
-
-{{< youtube "CdiDYZ51a2o" >}}
-
-## What does Hugo do?
-
-In technical terms, Hugo takes a source directory of files and templates and uses these as input to create a complete website.
-
-## Who should use Hugo?
-
-Hugo is for people that prefer writing in a text editor over a browser.
-
-Hugo is for people who want to hand code their own website without worrying about setting up complicated runtimes, dependencies and databases.
-
-Hugo is for people building a blog, a company site, a portfolio site, documentation, a single landing page, or a website with thousands of pages.
-
-[@spf13]: https://twitter.com/spf13
-[Amazon S3]: https://aws.amazon.com/s3/
-[Azure]: https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website
-[CloudFront]: https://aws.amazon.com/cloudfront/
-[DreamHost]: https://www.dreamhost.com/
-[Firebase]: https://firebase.google.com/docs/hosting/
-[GitHub Pages]: https://pages.github.com/
-[GitLab Pages]: https://about.gitlab.com/features/pages/
-[Go language]: https://go.dev/
-[GoDaddy]: https://www.godaddy.com/
-[Google Cloud Storage]: https://cloud.google.com/storage/
-[Heroku]: https://www.heroku.com/
-[Jekyll]: https://jekyllrb.com/
-[Middleman]: https://middlemanapp.com/
-[Nanoc]: https://nanoc.ws/
-[Netlify]: https://netlify.com
-[Rackspace]: https://www.rackspace.com/cloud/files
-[Surge]: https://surge.sh
-[contributing to it]: https://github.com/gohugoio/hugo
-[rackspace]: https://www.rackspace.com/openstack/public/files
-[static site generator]: /about/benefits/
diff --git a/docs/content/en/commands/hugo.md b/docs/content/en/commands/hugo.md
index cbc1ea0ecee..cfbe66053fd 100644
--- a/docs/content/en/commands/hugo.md
+++ b/docs/content/en/commands/hugo.md
@@ -57,7 +57,7 @@ hugo [flags]
--printUnusedTemplates print warnings on unused templates.
--quiet build in quiet mode
--renderSegments strings named segments to render (configured in the segments config)
- --renderToMemory render to memory (mostly useful when running the server)
+ -M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--templateMetrics display metrics about template executions
--templateMetricsHints calculate some improvement hints when combined with --templateMetrics
diff --git a/docs/content/en/commands/hugo_completion.md b/docs/content/en/commands/hugo_completion.md
index a09b0398515..21635e81e63 100644
--- a/docs/content/en/commands/hugo_completion.md
+++ b/docs/content/en/commands/hugo_completion.md
@@ -31,7 +31,7 @@ See each sub-command's help for details on how to use the generated script.
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_completion_bash.md b/docs/content/en/commands/hugo_completion_bash.md
index 802fcf0a416..bface97c6c3 100644
--- a/docs/content/en/commands/hugo_completion_bash.md
+++ b/docs/content/en/commands/hugo_completion_bash.md
@@ -54,7 +54,7 @@ hugo completion bash
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_completion_fish.md b/docs/content/en/commands/hugo_completion_fish.md
index ce0020e86b0..3a9cf0df2c3 100644
--- a/docs/content/en/commands/hugo_completion_fish.md
+++ b/docs/content/en/commands/hugo_completion_fish.md
@@ -45,7 +45,7 @@ hugo completion fish [flags]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_completion_powershell.md b/docs/content/en/commands/hugo_completion_powershell.md
index 80dd231f138..593573cee8a 100644
--- a/docs/content/en/commands/hugo_completion_powershell.md
+++ b/docs/content/en/commands/hugo_completion_powershell.md
@@ -42,7 +42,7 @@ hugo completion powershell [flags]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_completion_zsh.md b/docs/content/en/commands/hugo_completion_zsh.md
index 04d304421f2..c227c61258b 100644
--- a/docs/content/en/commands/hugo_completion_zsh.md
+++ b/docs/content/en/commands/hugo_completion_zsh.md
@@ -56,7 +56,7 @@ hugo completion zsh [flags]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_config.md b/docs/content/en/commands/hugo_config.md
index 873b7179bd0..fac513dceea 100644
--- a/docs/content/en/commands/hugo_config.md
+++ b/docs/content/en/commands/hugo_config.md
@@ -40,7 +40,7 @@ hugo config [command] [flags]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_config_mounts.md b/docs/content/en/commands/hugo_config_mounts.md
index 4e430c4e77a..42c8b29aa57 100644
--- a/docs/content/en/commands/hugo_config_mounts.md
+++ b/docs/content/en/commands/hugo_config_mounts.md
@@ -34,7 +34,7 @@ hugo config mounts [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_convert.md b/docs/content/en/commands/hugo_convert.md
index 39761f7d198..7b18ee6f8aa 100644
--- a/docs/content/en/commands/hugo_convert.md
+++ b/docs/content/en/commands/hugo_convert.md
@@ -33,7 +33,7 @@ See convert's subcommands toJSON, toTOML and toYAML for more information.
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_convert_toJSON.md b/docs/content/en/commands/hugo_convert_toJSON.md
index 8756c20a600..1dfb33aa066 100644
--- a/docs/content/en/commands/hugo_convert_toJSON.md
+++ b/docs/content/en/commands/hugo_convert_toJSON.md
@@ -35,7 +35,7 @@ hugo convert toJSON [flags] [args]
--logLevel string log level (debug|info|warn|error)
-o, --output string filesystem path to write files to
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
--unsafe enable less safe operations, please backup first
diff --git a/docs/content/en/commands/hugo_convert_toTOML.md b/docs/content/en/commands/hugo_convert_toTOML.md
index e360233a40b..ddd6b8270b3 100644
--- a/docs/content/en/commands/hugo_convert_toTOML.md
+++ b/docs/content/en/commands/hugo_convert_toTOML.md
@@ -35,7 +35,7 @@ hugo convert toTOML [flags] [args]
--logLevel string log level (debug|info|warn|error)
-o, --output string filesystem path to write files to
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
--unsafe enable less safe operations, please backup first
diff --git a/docs/content/en/commands/hugo_convert_toYAML.md b/docs/content/en/commands/hugo_convert_toYAML.md
index c6bec1e8dd1..bddbb88a584 100644
--- a/docs/content/en/commands/hugo_convert_toYAML.md
+++ b/docs/content/en/commands/hugo_convert_toYAML.md
@@ -35,7 +35,7 @@ hugo convert toYAML [flags] [args]
--logLevel string log level (debug|info|warn|error)
-o, --output string filesystem path to write files to
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
--unsafe enable less safe operations, please backup first
diff --git a/docs/content/en/commands/hugo_deploy.md b/docs/content/en/commands/hugo_deploy.md
index 37610441d05..a606083fc55 100644
--- a/docs/content/en/commands/hugo_deploy.md
+++ b/docs/content/en/commands/hugo_deploy.md
@@ -44,7 +44,7 @@ hugo deploy [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_env.md b/docs/content/en/commands/hugo_env.md
index 947a4325c20..9b73cea5feb 100644
--- a/docs/content/en/commands/hugo_env.md
+++ b/docs/content/en/commands/hugo_env.md
@@ -33,7 +33,7 @@ hugo env [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_gen.md b/docs/content/en/commands/hugo_gen.md
index d350638dac4..ea1696db91c 100644
--- a/docs/content/en/commands/hugo_gen.md
+++ b/docs/content/en/commands/hugo_gen.md
@@ -25,7 +25,7 @@ A collection of several useful generators.
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_gen_chromastyles.md b/docs/content/en/commands/hugo_gen_chromastyles.md
index 6ecb00bd001..cc244878c05 100644
--- a/docs/content/en/commands/hugo_gen_chromastyles.md
+++ b/docs/content/en/commands/hugo_gen_chromastyles.md
@@ -39,7 +39,7 @@ hugo gen chromastyles [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_gen_doc.md b/docs/content/en/commands/hugo_gen_doc.md
index f2d733112b3..84493ab982a 100644
--- a/docs/content/en/commands/hugo_gen_doc.md
+++ b/docs/content/en/commands/hugo_gen_doc.md
@@ -39,7 +39,7 @@ hugo gen doc [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_gen_man.md b/docs/content/en/commands/hugo_gen_man.md
index f1e355c6c4a..40267def2d4 100644
--- a/docs/content/en/commands/hugo_gen_man.md
+++ b/docs/content/en/commands/hugo_gen_man.md
@@ -36,7 +36,7 @@ hugo gen man [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_import.md b/docs/content/en/commands/hugo_import.md
index db4d19df3dc..71af58f8be2 100644
--- a/docs/content/en/commands/hugo_import.md
+++ b/docs/content/en/commands/hugo_import.md
@@ -31,7 +31,7 @@ Import requires a subcommand, e.g. `hugo import jekyll jekyll_root_path target_p
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_import_jekyll.md b/docs/content/en/commands/hugo_import_jekyll.md
index 11f87ab1204..72941367159 100644
--- a/docs/content/en/commands/hugo_import_jekyll.md
+++ b/docs/content/en/commands/hugo_import_jekyll.md
@@ -36,7 +36,7 @@ hugo import jekyll [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_list.md b/docs/content/en/commands/hugo_list.md
index 24b75678ac0..9fab42ca928 100644
--- a/docs/content/en/commands/hugo_list.md
+++ b/docs/content/en/commands/hugo_list.md
@@ -31,7 +31,7 @@ List requires a subcommand, e.g. hugo list drafts
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
@@ -40,8 +40,9 @@ List requires a subcommand, e.g. hugo list drafts
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
-* [hugo list all](/commands/hugo_list_all/) - List all posts
-* [hugo list drafts](/commands/hugo_list_drafts/) - List all drafts
-* [hugo list expired](/commands/hugo_list_expired/) - List all posts already expired
-* [hugo list future](/commands/hugo_list_future/) - List all posts dated in the future
+* [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
diff --git a/docs/content/en/commands/hugo_list_all.md b/docs/content/en/commands/hugo_list_all.md
index 50f6bfe73a5..d8dc10c9e29 100644
--- a/docs/content/en/commands/hugo_list_all.md
+++ b/docs/content/en/commands/hugo_list_all.md
@@ -5,11 +5,11 @@ url: /commands/hugo_list_all/
---
## hugo list all
-List all posts
+List all content
### Synopsis
-List all of the posts in your content directory, include drafts, future and expired pages.
+List all content including draft, future, and expired.
```
hugo list all [flags] [args]
@@ -33,7 +33,7 @@ hugo list all [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_list_drafts.md b/docs/content/en/commands/hugo_list_drafts.md
index 5ab308a76a9..f1015bbb511 100644
--- a/docs/content/en/commands/hugo_list_drafts.md
+++ b/docs/content/en/commands/hugo_list_drafts.md
@@ -5,11 +5,11 @@ url: /commands/hugo_list_drafts/
---
## hugo list drafts
-List all drafts
+List draft content
### Synopsis
-List all of the drafts in your content directory.
+List draft content.
```
hugo list drafts [flags] [args]
@@ -33,7 +33,7 @@ hugo list drafts [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_list_expired.md b/docs/content/en/commands/hugo_list_expired.md
index 19aaf667d91..35f6636e18c 100644
--- a/docs/content/en/commands/hugo_list_expired.md
+++ b/docs/content/en/commands/hugo_list_expired.md
@@ -5,11 +5,11 @@ url: /commands/hugo_list_expired/
---
## hugo list expired
-List all posts already expired
+List expired content
### Synopsis
-List all of the posts in your content directory which has already expired.
+List content with a past expiration date.
```
hugo list expired [flags] [args]
@@ -33,7 +33,7 @@ hugo list expired [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_list_future.md b/docs/content/en/commands/hugo_list_future.md
index 3a3e11cc565..bef16244178 100644
--- a/docs/content/en/commands/hugo_list_future.md
+++ b/docs/content/en/commands/hugo_list_future.md
@@ -5,11 +5,11 @@ url: /commands/hugo_list_future/
---
## hugo list future
-List all posts dated in the future
+List future content
### Synopsis
-List all of the posts in your content directory which will be posted in the future.
+List content with a future publication date.
```
hugo list future [flags] [args]
@@ -33,7 +33,7 @@ hugo list future [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_list_published.md b/docs/content/en/commands/hugo_list_published.md
new file mode 100644
index 00000000000..d53f6d94174
--- /dev/null
+++ b/docs/content/en/commands/hugo_list_published.md
@@ -0,0 +1,45 @@
+---
+title: "hugo list published"
+slug: hugo_list_published
+url: /commands/hugo_list_published/
+---
+## hugo list published
+
+List published content
+
+### Synopsis
+
+List content that is not draft, future, or expired.
+
+```
+hugo list published [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for published
+```
+
+### 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")
+ --debug debug output
+ -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)
+ --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
+ -v, --verbose verbose output
+```
+
+### SEE ALSO
+
+* [hugo list](/commands/hugo_list/) - Listing out various types of content
+
diff --git a/docs/content/en/commands/hugo_mod.md b/docs/content/en/commands/hugo_mod.md
index c3f1230b3e2..7fe9dc18d7b 100644
--- a/docs/content/en/commands/hugo_mod.md
+++ b/docs/content/en/commands/hugo_mod.md
@@ -40,7 +40,7 @@ See https://gohugo.io/hugo-modules/ for more information.
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_mod_clean.md b/docs/content/en/commands/hugo_mod_clean.md
index 459269b6690..e7d933da711 100644
--- a/docs/content/en/commands/hugo_mod_clean.md
+++ b/docs/content/en/commands/hugo_mod_clean.md
@@ -40,7 +40,7 @@ hugo mod clean [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_mod_get.md b/docs/content/en/commands/hugo_mod_get.md
index 84177da1865..0b8a622f629 100644
--- a/docs/content/en/commands/hugo_mod_get.md
+++ b/docs/content/en/commands/hugo_mod_get.md
@@ -64,7 +64,7 @@ hugo mod get [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_mod_graph.md b/docs/content/en/commands/hugo_mod_graph.md
index 50b8168dfb2..506bff27808 100644
--- a/docs/content/en/commands/hugo_mod_graph.md
+++ b/docs/content/en/commands/hugo_mod_graph.md
@@ -41,7 +41,7 @@ hugo mod graph [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_mod_init.md b/docs/content/en/commands/hugo_mod_init.md
index ead95c9afa4..dcea44b4bde 100644
--- a/docs/content/en/commands/hugo_mod_init.md
+++ b/docs/content/en/commands/hugo_mod_init.md
@@ -45,7 +45,7 @@ hugo mod init [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_mod_npm.md b/docs/content/en/commands/hugo_mod_npm.md
index ea80b42e6af..763b3c24766 100644
--- a/docs/content/en/commands/hugo_mod_npm.md
+++ b/docs/content/en/commands/hugo_mod_npm.md
@@ -33,7 +33,7 @@ hugo mod npm [command] [flags]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_mod_npm_pack.md b/docs/content/en/commands/hugo_mod_npm_pack.md
index fbc81606cce..47d3e28b9bb 100644
--- a/docs/content/en/commands/hugo_mod_npm_pack.md
+++ b/docs/content/en/commands/hugo_mod_npm_pack.md
@@ -48,7 +48,7 @@ hugo mod npm pack [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_mod_tidy.md b/docs/content/en/commands/hugo_mod_tidy.md
index f2df4756509..6d024564f1f 100644
--- a/docs/content/en/commands/hugo_mod_tidy.md
+++ b/docs/content/en/commands/hugo_mod_tidy.md
@@ -34,7 +34,7 @@ hugo mod tidy [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_mod_vendor.md b/docs/content/en/commands/hugo_mod_vendor.md
index 49aaf3f2f89..6f96caec29a 100644
--- a/docs/content/en/commands/hugo_mod_vendor.md
+++ b/docs/content/en/commands/hugo_mod_vendor.md
@@ -40,7 +40,7 @@ hugo mod vendor [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_mod_verify.md b/docs/content/en/commands/hugo_mod_verify.md
index d67d9b0bfd5..d3f639feab0 100644
--- a/docs/content/en/commands/hugo_mod_verify.md
+++ b/docs/content/en/commands/hugo_mod_verify.md
@@ -39,7 +39,7 @@ hugo mod verify [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_new.md b/docs/content/en/commands/hugo_new.md
index ac3a58154dc..2146f85fcc4 100644
--- a/docs/content/en/commands/hugo_new.md
+++ b/docs/content/en/commands/hugo_new.md
@@ -36,7 +36,7 @@ Ensure you run this within the root directory of your site.
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_new_content.md b/docs/content/en/commands/hugo_new_content.md
index e50f341f702..f0ea64ab7f9 100644
--- a/docs/content/en/commands/hugo_new_content.md
+++ b/docs/content/en/commands/hugo_new_content.md
@@ -48,7 +48,7 @@ hugo new content [path] [flags]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_new_site.md b/docs/content/en/commands/hugo_new_site.md
index 2c4e12a0271..a79e6f85adc 100644
--- a/docs/content/en/commands/hugo_new_site.md
+++ b/docs/content/en/commands/hugo_new_site.md
@@ -37,7 +37,7 @@ hugo new site [path] [flags]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_new_theme.md b/docs/content/en/commands/hugo_new_theme.md
index 0526fed3f1c..c3003200dff 100644
--- a/docs/content/en/commands/hugo_new_theme.md
+++ b/docs/content/en/commands/hugo_new_theme.md
@@ -36,7 +36,7 @@ hugo new theme [name] [flags]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_server.md b/docs/content/en/commands/hugo_server.md
index 1159e47066c..dada8c43e49 100644
--- a/docs/content/en/commands/hugo_server.md
+++ b/docs/content/en/commands/hugo_server.md
@@ -49,7 +49,7 @@ hugo server [command] [flags]
-l, --layoutDir string filesystem path to layout directory
--liveReloadPort int port for live reloading (i.e. 443 in HTTPS proxy situations) (default -1)
--minify minify any supported output format (HTML, XML etc.)
- --navigateToChanged navigate to changed content file on live browser reload
+ -N, --navigateToChanged navigate to changed content file on live browser reload
--noBuildLock don't create .hugo_build.lock file
--noChmod don't sync permission mode of files
--noHTTPCache prevent HTTP caching
@@ -86,7 +86,7 @@ hugo server [command] [flags]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_server_trust.md b/docs/content/en/commands/hugo_server_trust.md
index 2f2f30abb78..c4cf750fa38 100644
--- a/docs/content/en/commands/hugo_server_trust.md
+++ b/docs/content/en/commands/hugo_server_trust.md
@@ -30,7 +30,7 @@ hugo server trust [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/commands/hugo_version.md b/docs/content/en/commands/hugo_version.md
index 35015dd4edb..471edd2bb08 100644
--- a/docs/content/en/commands/hugo_version.md
+++ b/docs/content/en/commands/hugo_version.md
@@ -33,7 +33,7 @@ hugo version [flags] [args]
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
--quiet build in quiet mode
- --renderToMemory render to memory (mostly useful when running the server)
+ -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
-v, --verbose verbose output
diff --git a/docs/content/en/content-management/_common/_index.md b/docs/content/en/content-management/_common/_index.md
index 47d5812fba5..4328d4d145b 100644
--- a/docs/content/en/content-management/_common/_index.md
+++ b/docs/content/en/content-management/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
diff --git a/docs/content/en/content-management/_index.md b/docs/content/en/content-management/_index.md
index 66af2468139..8fb0cf25e1b 100644
--- a/docs/content/en/content-management/_index.md
+++ b/docs/content/en/content-management/_index.md
@@ -1,12 +1,12 @@
---
title: Content management
-linkTitle: Overview
+linkTitle: In this section
description: Hugo makes managing large static sites easy with support for archetypes, content types, menus, cross references, summaries, and more.
categories: []
keywords: []
menu:
docs:
- identifier: content-management-overview
+ identifier: content-management-in-this-section
parent: content-management
weight: 10
weight: 10
diff --git a/docs/content/en/content-management/archetypes.md b/docs/content/en/content-management/archetypes.md
index 94f03884800..f89c3f6b385 100644
--- a/docs/content/en/content-management/archetypes.md
+++ b/docs/content/en/content-management/archetypes.md
@@ -15,7 +15,7 @@ aliases: [/content/archetypes/]
## Overview
-A content file consists of [front matter] and markup. The markup is typically markdown, but Hugo also supports other [content formats]. Front matter can be TOML, YAML, or JSON.
+A content file consists of [front matter] and markup. The markup is typically Markdown, but Hugo also supports other [content formats]. Front matter can be TOML, YAML, or JSON.
The `hugo new content` command creates a new file in the `content` directory, using an archetype as a template. This is the default archetype:
@@ -70,14 +70,33 @@ If none of these exists, Hugo uses a built-in default archetype.
You can use any [template function] within an archetype. As shown above, the default archetype uses the [`replace`](/functions/strings/replace) function to replace hyphens with spaces when populating the title in front matter.
-Archetypes receive the following objects and values in [context]:
+Archetypes receive the following [context]:
-- `.Date`
-- `.Type`
-- `.Site` (see [details](/variables/site/))
-- `.File` (see [details](/variables/file/))
+Date
+: (`string`) The current date and time, formatted in compliance with RFC3339.
-As shown above, the default archetype passes `.File.ContentBaseName` as the argument to the `replace` function when populating the title in front matter.
+File
+: (`hugolib.fileInfo`) Returns file information for the current page. See [details](/methods/page/file).
+
+Type
+: (`string`) The [content type] inferred from the top-level directory name, or as specified by the `--kind` flag passed to the `hugo new content` command.
+
+[content type]: /getting-started/glossary#content-type
+
+Site
+: (`page.Site`) The current site object. See [details](/methods/site/).
+
+## Alternate date format
+
+To insert date and time with an alternate format, use the [`time.Now`] function:
+
+[`time.Now`]: /functions/time/now/
+
+{{< code-toggle file=archetypes/default.md fm=true >}}
+title = '{{ replace .File.ContentBaseName `-` ` ` | title }}'
+date = '{{ time.Now.Format "2006-01-02" }}'
+draft = true
+{{< /code-toggle >}}
## Include content
diff --git a/docs/content/en/content-management/build-options.md b/docs/content/en/content-management/build-options.md
index e8b3354bf24..a279fb651f8 100644
--- a/docs/content/en/content-management/build-options.md
+++ b/docs/content/en/content-management/build-options.md
@@ -12,10 +12,10 @@ toc: true
aliases: [/content/build-options/]
---
-Build options are stored in a reserved front matter object named `_build` with these defaults:
+Build options are stored in a reserved front matter object named `build` with these defaults:
{{< code-toggle file=content/example/index.md fm=true >}}
-[_build]
+[build]
list = 'always'
publishResources = true
render = 'always'
@@ -55,17 +55,17 @@ render
- `never`
: Never render the page to disk, and exclude it from all page collections.
-[page bundles]: content-management/page-bundles
-[page resources]: /content-management/page-resources
-[`Permalink`]: /methods/resource/permalink
-[`RelPermalink`]: /methods/resource/relpermalink
-[`Publish`]: /methods/resource/publish
+[page bundles]: /content-management/page-bundles/
+[page resources]: /content-management/page-resources/
+[`Permalink`]: /methods/resource/permalink/
+[`RelPermalink`]: /methods/resource/relpermalink/
+[`Publish`]: /methods/resource/publish/
{{% note %}}
Any page, regardless of its build options, will always be available by using the [`.Page.GetPage`] or [`.Site.GetPage`] method.
-[`.Page.GetPage`]: /methods/page/getpage
-[`.Site.GetPage`]: /methods/site/getpage
+[`.Page.GetPage`]: /methods/page/getpage/
+[`.Site.GetPage`]: /methods/site/getpage/
{{% /note %}}
## Example -- headless page
@@ -85,7 +85,7 @@ Set the build options in front matter:
{{< code-toggle file=content/headless/index.md fm=true >}}
title = 'Headless page'
-[_build]
+[build]
list = 'never'
publishResources = false
render = 'never'
@@ -121,7 +121,7 @@ In the example above, note that:
Create a unpublished section whose content and resources can be included in other pages.
-[branch bundle]: /content-management/page-bundles
+[branch bundle]: /content-management/page-bundles/
```text
content/
@@ -143,7 +143,7 @@ Set the build options in front matter, using the `cascade` keyword to "cascade"
{{< code-toggle file=content/headless/_index.md fm=true >}}
title = 'Headless section'
[[cascade]]
-[cascade._build]
+[cascade.build]
list = 'local'
publishResources = false
render = 'never'
@@ -201,10 +201,10 @@ Set the build options in front matter, using the `cascade` keyword to "cascade"
{{< code-toggle file=content/glossary/_index.md fm=true >}}
title = 'Glossary'
-[_build]
+[build]
render = 'always'
[[cascade]]
-[cascade._build]
+[cascade.build]
list = 'local'
publishResources = false
render = 'never'
@@ -247,7 +247,7 @@ Set the build options in front matter:
{{< code-toggle file=content/books/_index.md fm=true >}}
title = 'Books'
-[_build]
+[build]
render = 'never'
list = 'never'
{{< /code-toggle >}}
@@ -294,7 +294,7 @@ Set the build options in front matter, using the `cascade` keyword to "cascade"
{{< code-toggle file=content/internal/_index.md >}}
title = 'Internal'
[[cascade]]
-[cascade._build]
+[cascade.build]
render = 'never'
list = 'never'
[cascade._target]
diff --git a/docs/content/en/content-management/comments.md b/docs/content/en/content-management/comments.md
index 6e58b36e490..8f55c413c96 100644
--- a/docs/content/en/content-management/comments.md
+++ b/docs/content/en/content-management/comments.md
@@ -37,7 +37,7 @@ For many websites, this is enough configuration. However, you also have the opti
### Render Hugo's built-in Disqus partial template
-Disqus has its own [internal template](/templates/internal/#disqus) available, to render it add the following code where you want comments to appear:
+Disqus has its own [internal template](/templates/embedded/#disqus) available, to render it add the following code where you want comments to appear:
```go-html-template
{{ template "_internal/disqus.html" . }}
@@ -45,25 +45,30 @@ Disqus has its own [internal template](/templates/internal/#disqus) available, t
## Alternatives
-These are some alternatives to Disqus:
-
-* [Cactus Comments](https://cactus.chat/docs/integrations/hugo/) (Open Source, Matrix appservice, Docker install)
-* [Comentario](https://gitlab.com/comentario/comentario) (Open Source, self-hosted, Go/Angular, run locally, in Docker or Kubernetes)
-* [Commento](https://commento.io/) (Open Source, available as a service, local install, or docker image)
-* [Giscus](https://giscus.app/) (Open source, comments system powered by GitHub Discussions)
-* [Graph Comment](https://graphcomment.com/)
-* [Hyvor Talk](https://talk.hyvor.com/) (Available as a service)
-* [IntenseDebate](https://intensedebate.com/)
-* [Isso](https://isso-comments.de/) (Self-hosted, Python) ([tutorial][issotutorial])
-* [Muut](https://muut.com/)
-* [Remark42](https://remark42.com/) (Open source, Golang, Easy to run docker)
-* [ReplyBox](https://getreplybox.com/)
-* [Staticman](https://staticman.net/)
-* [Talkyard](https://blog-comments.talkyard.io/) (Open source, & serverless hosting)
-* [Utterances](https://utteranc.es/) (Open source, GitHub comments widget built on GitHub issues)
+Commercial commenting systems:
+
+- [Emote](https://emote.com/)
+- [Graph Comment](https://graphcomment.com/)
+- [Hyvor Talk](https://talk.hyvor.com/)
+- [IntenseDebate](https://intensedebate.com/)
+- [ReplyBox](https://getreplybox.com/)
+
+Open-source commenting systems:
+
+- [Cactus Comments](https://cactus.chat/docs/integrations/hugo/)
+- [Comentario](https://gitlab.com/comentario/comentario/)
+- [Comma](https://github.com/Dieterbe/comma/)
+- [Commento](https://commento.io/)
+- [Discourse](https://meta.discourse.org/t/embed-discourse-comments-on-another-website-via-javascript/31963)
+- [Giscus](https://giscus.app/)
+- [Isso](https://isso-comments.de/)
+- [Remark42](https://remark42.com/)
+- [Staticman](https://staticman.net/)
+- [Talkyard](https://blog-comments.talkyard.io/)
+- [Utterances](https://utteranc.es/)
[configuration]: /getting-started/configuration/
-[disquspartial]: /templates/internal/#disqus
+[disquspartial]: /templates/embedded/#disqus
[disqussetup]: https://disqus.com/profile/signup/
[forum]: https://discourse.gohugo.io
[front matter]: /content-management/front-matter/
@@ -71,4 +76,3 @@ These are some alternatives to Disqus:
[issotutorial]: https://stiobhart.net/2017-02-24-isso-comments/
[partials]: /templates/partials/
[MongoDB]: https://www.mongodb.com/
-[tweet]: https://twitter.com/spf13
diff --git a/docs/content/en/content-management/content-adapters.md b/docs/content/en/content-management/content-adapters.md
new file mode 100644
index 00000000000..11257b89560
--- /dev/null
+++ b/docs/content/en/content-management/content-adapters.md
@@ -0,0 +1,355 @@
+---
+title: Content adapters
+description: Create content adapters to dynamically add content when building your site.
+categories: [content management]
+keywords: []
+menu:
+ docs:
+ parent: content-management
+ weight: 290
+weight: 290
+toc: true
+---
+
+{{< 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.
+
+Unlike templates that reside in the layouts directory, content adapters reside in the content directory, no more than one per directory per language. When a content adapter creates a page, the page's [logical path] will be relative to the content adapter.
+
+```text
+content/
+├── articles/
+│ ├── _index.md
+│ ├── article-1.md
+│ └── article-2.md
+├── books/
+│ ├── _content.gotmpl <-- content adapter
+│ └── _index.md
+└── films/
+ ├── _content.gotmpl <-- content adapter
+ └── _index.md
+```
+
+Each content adapter is named _content.gotmpl and uses the same [syntax] as templates in the layouts directory. You can use any of the [template functions] within a content adapter, as well as the methods described below.
+
+## Methods
+
+Use these methods within a content adapter.
+
+###### AddPage
+
+Adds a page to the site.
+
+{{< code file=content/books/_content.gotmpl >}}
+{{ $content := dict
+ "mediaType" "text/markdown"
+ "value" "The _Hunchback of Notre Dame_ was written by Victor Hugo."
+}}
+{{ $page := dict
+ "content" $content
+ "kind" "page"
+ "path" "the-hunchback-of-notre-dame"
+ "title" "The Hunchback of Notre Dame"
+}}
+{{ .AddPage $page }}
+{{< /code >}}
+
+###### AddResource
+
+Adds a page resource to the site.
+
+{{< code file=content/books/_content.gotmpl >}}
+{{ with resources.Get "images/a.jpg" }}
+ {{ $content := dict
+ "mediaType" .MediaType.Type
+ "value" .
+ }}
+ {{ $resource := dict
+ "content" $content
+ "path" "the-hunchback-of-notre-dame/cover.jpg"
+ }}
+ {{ $.AddResource $resource }}
+{{ end }}
+{{< /code >}}
+
+Then retrieve the new page resource with something like:
+
+{{< code file=layouts/_default/single.html >}}
+{{ with .Resources.Get "cover.jpg" }}
+
+{{ end }}
+{{< /code >}}
+
+###### Site
+
+Returns the `Site` to which the pages will be added.
+
+{{< code file=content/books/_content.gotmpl >}}
+{{ .Site.Title }}
+{{< /code >}}
+
+###### Store
+
+Returns a persistent “scratch pad” to store and manipulate data. The main use case for this is to transfer values between executions when [EnableAllLanguages](#enablealllanguages) is set. See [examples](/methods/page/store/).
+
+{{< code file=content/books/_content.gotmpl >}}
+{{ .Store.Set "key" "value" }}
+{{ .Store.Get "key" }}
+{{< /code >}}
+
+###### EnableAllLanguages
+
+By default, Hugo executes the content adapter for the language defined by the _content.gotmpl file . Use this method to activate the content adapter for all languages.
+
+{{< code file=content/books/_content.gotmpl >}}
+{{ .EnableAllLanguages }}
+{{ $content := dict
+ "mediaType" "text/markdown"
+ "value" "The _Hunchback of Notre Dame_ was written by Victor Hugo."
+}}
+{{ $page := dict
+ "content" $content
+ "kind" "page"
+ "path" "the-hunchback-of-notre-dame"
+ "title" "The Hunchback of Notre Dame"
+}}
+{{ .AddPage $page }}
+{{< /code >}}
+
+## Page map
+
+Set any [front matter field] in the map passed to the [`AddPage`](#addpage) method, excluding `markup`. Instead of setting the `markup` field, specify the `content.mediaType` as described below.
+
+This table describes the fields most commonly passed to the `AddPage` method.
+
+Key|Descripion|Required
+:--|:--|:-:
+`content.mediaType`|The content [media type]. Default is `text/markdown`. See [content formats] for examples.|
+`content.value`|The content value as a string.|
+`dates.date`|The page creation date as a `time.Time` value.|
+`dates.expiryDate`|The page expiry date as a `time.Time` value.|
+`dates.lastmod`|The page last modification date as a `time.Time` value.|
+`dates.publishDate`|The page publication date as a `time.Time` value.|
+`kind`|The [page kind]. Default is `page`.|
+`params`|A map of page parameters.|
+`path`|The page's [logical path] relative to the content adapter. Do not include a leading slash or file extension.|:heavy_check_mark:
+`title`|The page title.|
+
+{{% note %}}
+While `path` is the only required field, we recommend setting `title` as well.
+
+When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C` produces a logical path of `/section/a-b-c`.
+{{% /note %}}
+
+## Resource map
+
+Construct the map passed to the [`AddResource`](#addresource) method using the fields below.
+
+Key|Descripion|Required
+:--|:--|:-:
+`content.mediaType`|The content [media type].|:heavy_check_mark:
+`content.value`|The content value as a string or resource.|:heavy_check_mark:
+`name`|The resource name.|
+`params`|A map of resource parameters.|
+`path`|The resources's [logical path] relative to the content adapter. Do not include a leading slash.|:heavy_check_mark:
+`title`|The resource title.|
+
+{{% note %}}
+If the `content.value` is a string Hugo creates a new resource. If the `content.value` is a resource, Hugo obtains the value from the existing resource.
+
+When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C/cover.jpg` produces a logical path of `/section/a-b-c/cover.jpg`.
+{{% /note %}}
+
+## Example
+
+Create pages from remote data, where each page represents a book review.
+
+Step 1
+: Create the content structure.
+
+```text
+content/
+└── books/
+ ├── _content.gotmpl <-- content adapter
+ └── _index.md
+```
+
+Step 2
+: Inspect the remote data to determine how to map key-value pairs to front matter fields.
+
+:
+
+Step 3
+: Create the content adapter.
+
+{{< code file=content/books/_content.gotmpl copy=true >}}
+{{/* Get remote data. */}}
+{{ $data := dict }}
+{{ $url := "https://gohugo.io/shared/examples/data/books.json" }}
+{{ with resources.GetRemote $url }}
+ {{ with .Err }}
+ {{ errorf "Unable to get remote resource %s: %s" $url . }}
+ {{ else }}
+ {{ $data = . | transform.Unmarshal }}
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get remote resource %s" $url }}
+{{ end }}
+
+{{/* Add pages and page resources. */}}
+{{ range $data }}
+
+ {{/* Add page. */}}
+ {{ $content := dict "mediaType" "text/markdown" "value" .summary }}
+ {{ $dates := dict "date" (time.AsTime .date) }}
+ {{ $params := dict "author" .author "isbn" .isbn "rating" .rating "tags" .tags }}
+ {{ $page := dict
+ "content" $content
+ "dates" $dates
+ "kind" "page"
+ "params" $params
+ "path" .title
+ "title" .title
+ }}
+ {{ $.AddPage $page }}
+
+ {{/* Add page resource. */}}
+ {{ $item := . }}
+ {{ with $url := $item.cover }}
+ {{ with resources.GetRemote $url }}
+ {{ with .Err }}
+ {{ errorf "Unable to get remote resource %s: %s" $url . }}
+ {{ else }}
+ {{ $content := dict "mediaType" .MediaType.Type "value" .Content }}
+ {{ $params := dict "alt" $item.title }}
+ {{ $resource := dict
+ "content" $content
+ "params" $params
+ "path" (printf "%s/cover.%s" $item.title .MediaType.SubType)
+ }}
+ {{ $.AddResource $resource }}
+ {{ end }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %s" $url }}
+ {{ end }}
+ {{ end }}
+
+{{ end }}
+{{< /code >}}
+
+Step 4
+: Create a single page template to render each book review.
+
+{{< code file=layouts/books/single.html copy=true >}}
+{{ define "main" }}
+
{{ .Title }}
+
+ {{ with .Resources.GetMatch "cover.*" }}
+
+ {{ end }}
+
+
+ {{ end }}
+
+ {{ .Content }}
+{{ end }}
+{{< /code >}}
+
+## Multilingual sites
+
+With multilingual sites you can:
+
+1. Create one content adapter for all languages using the [`EnableAllLanguages`](#enablealllanguages) method as described above.
+2. Create content adapters unique to each language. See the examples below.
+
+### Translations by file name
+
+With this site configuration:
+
+{{< code-toggle file=hugo >}}
+[languages.en]
+weight = 1
+
+[languages.de]
+weight = 2
+{{< /code-toggle >}}
+
+Include a language designator in the content adapter's file name.
+
+```text
+content/
+└── books/
+ ├── _content.de.gotmpl
+ ├── _content.en.gotmpl
+ ├── _index.de.md
+ └── _index.en.md
+```
+
+### Translations by content directory
+
+With this site configuration:
+
+{{< code-toggle file=hugo >}}
+[languages.en]
+contentDir = 'content/en'
+weight = 1
+
+[languages.de]
+contentDir = 'content/de'
+weight = 2
+{{< /code-toggle >}}
+
+Create a single content adapter in each directory:
+
+```text
+content/
+├── de/
+│ └── books/
+│ ├── _content.gotmpl
+│ └── _index.md
+└── en/
+ └── books/
+ ├── _content.gotmpl
+ └── _index.md
+```
+
+## Page collisions
+
+Two or more pages collide when they have the same publication path. Due to concurrency, the content of the published page is indeterminate. Consider this example:
+
+```text
+content/
+└── books/
+ ├── _content.gotmpl <-- content adapter
+ ├── _index.md
+ └── the-hunchback-of-notre-dame.md
+```
+
+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.
+
+[content formats]: /content-management/formats/#classification
+[front matter field]: /content-management/front-matter/#fields
+[logical path]: /getting-started/glossary/#logical-path
+[media type]: https://en.wikipedia.org/wiki/Media_type
+[page kind]: /getting-started/glossary/#page-kind
+[syntax]: /templates/introduction/
+[template functions]: /functions/
diff --git a/docs/content/en/content-management/cross-references.md b/docs/content/en/content-management/cross-references.md
index 500e388a41d..24da0bfda87 100644
--- a/docs/content/en/content-management/cross-references.md
+++ b/docs/content/en/content-management/cross-references.md
@@ -16,7 +16,7 @@ The `ref` and `relref` shortcodes display the absolute and relative permalinks t
## Use of `ref` and `relref`
-The `ref` and `relref` shortcodes require a single parameter: the path to a content document, with or without a file extension, with or without an anchor. Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site.
+The `ref` and `relref` shortcodes require a single argument: the path to a content document, with or without a file extension, with or without an anchor. Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site.
```text
.
@@ -60,7 +60,7 @@ index.md can be reference either by its path or by its containing folder without
{{}} // <- References /products/index.md
```
-To generate a hyperlink using `ref` or `relref` in markdown:
+To generate a hyperlink using `ref` or `relref` in Markdown:
```text
[About]({{}} "About Us")
@@ -70,9 +70,11 @@ Hugo emits an error or warning if a document cannot be uniquely resolved. The er
### Link to another language version
+Using `ref` or `relref` without specifying a language, will make the reference resolve to the language of the current content page.
+
To link to another language version of a document, use this syntax:
-```go-html-template
+```text
{{}}
```
@@ -80,7 +82,7 @@ To link to another language version of a document, use this syntax:
To link to another Output Format of a document, use this syntax:
-```go-html-template
+```text
{{}}
```
@@ -88,7 +90,7 @@ To link to another Output Format of a document, use this syntax:
When using Markdown document types, Hugo generates element IDs for every heading on a page. For example:
-```md
+```text
## Reference
```
@@ -100,14 +102,14 @@ produces this HTML:
Get the permalink to a heading by appending the ID to the path when using the `ref` or `relref` shortcodes:
-```go-html-template
+```text
{{}}
{{}}
```
Generate a custom heading ID by including an attribute. For example:
-```md
+```text
## Reference A {#foo}
## Reference B {id="bar"}
```
@@ -121,7 +123,7 @@ produces this HTML:
Hugo will generate unique element IDs if the same heading appears more than once on a page. For example:
-```md
+```text
## Reference
## Reference
## Reference
diff --git a/docs/content/en/content-management/data-sources.md b/docs/content/en/content-management/data-sources.md
new file mode 100644
index 00000000000..40634acef7a
--- /dev/null
+++ b/docs/content/en/content-management/data-sources.md
@@ -0,0 +1,126 @@
+---
+title: Data sources
+description: Use local and remote data sources to augment or create content.
+categories: [content management]
+keywords: [data,json,toml,yaml,xml]
+menu:
+ docs:
+ parent: content-management
+ weight: 280
+weight: 280
+toc: true
+aliases: [/extras/datafiles/,/extras/datadrivencontent/,/doc/datafiles/,/templates/data-templates/]
+---
+
+Hugo can access and [unmarshal] local and remote data sources including CSV, JSON, TOML, YAML, and XML. Use this data to augment existing content or to create new content.
+
+[unmarshal]: /getting-started/glossary/#unmarshal
+
+A data source might be a file in the data directory, a [global resource], a [page resource], or a [remote resource].
+
+[global resource]: /getting-started/glossary/#global-resource
+[page resource]: /getting-started/glossary/#page-resource
+[remote resource]: /getting-started/glossary/#remote-resource
+
+## Data directory
+
+The data directory in the root of your project may contain one or more data files, in either a flat or nested tree. Hugo merges the data files to create a single data structure, accessible with the `Data` method on a `Site` object.
+
+Hugo also merges data directories from themes and modules into this single data structure, where the data directory in the root of your project takes precedence.
+
+{{% note %}}
+Hugo reads the combined data structure into memory and keeps it there for the entire build. For data that is infrequently accessed, use global or page resources instead.
+{{% /note %}}
+
+Theme and module authors may wish to namespace their data files to prevent collisions. For example:
+
+```text
+project/
+└── data/
+ └── mytheme/
+ └── foo.json
+```
+
+{{% note %}}
+Do not place CSV files in the data directory. Access CSV files as page, global, or remote resources.
+{{% /note %}}
+
+See the documentation for the [`Data`] method on `Page` object for details and examples.
+
+[`Data`]: /methods/site/data/
+
+## Global resources
+
+Use the `resources.Get` and `transform.Unmarshal` functions to access data files that exist as global resources.
+
+See the [`transform.Unmarshal`](/functions/transform/unmarshal/#global-resource) documentation for details and examples.
+
+## Page resources
+
+Use the `Resources.Get` method on a `Page` object combined with the `transform.Unmarshal` function to access data files that exist as page resources.
+
+See the [`transform.Unmarshal`](/functions/transform/unmarshal/#page-resource) documentation for details and examples.
+
+## Remote resources
+
+Use the `resources.GetRemote` and `transform.Unmarshal` functions to access remote data.
+
+See the [`transform.Unmarshal`](/functions/transform/unmarshal/#remote-resource) documentation for details and examples.
+
+## Augment existing content
+
+Use data sources to augment existing content. For example, create a shortcode to render an HTML table from a global CSV resource.
+
+{{< code file=assets/pets.csv >}}
+"name","type","breed","age"
+"Spot","dog","Collie","3"
+"Felix","cat","Malicious","7"
+{{< /code >}}
+
+{{< code file=content/example.md lang=text >}}
+{{}}
+{{< /code >}}
+
+{{< code file=layouts/shortcodes/csv-to-table.html >}}
+{{ with $file := .Get 0 }}
+ {{ with resources.Get $file }}
+ {{ with . | transform.Unmarshal }}
+
+
+
+ {{ range index . 0 }}
+
{{ . }}
+ {{ end }}
+
+
+
+ {{ range after 1 . }}
+
+ {{ range . }}
+
{{ . }}
+ {{ end }}
+
+ {{ end }}
+
+
+ {{ end }}
+ {{ else }}
+ {{ errorf "The %q shortcode was unable to find %s. See %s" $.Name $file $.Position }}
+ {{ end }}
+{{ else }}
+ {{ errorf "The %q shortcode requires one positional argument, the path to the CSV file relative to the assets directory. See %s" .Name .Position }}
+{{ end }}
+{{< /code >}}
+
+Hugo renders this to:
+
+name|type|breed|age
+:--|:--|:--|:--
+Spot|dog|Collie|3
+Felix|cat|Malicious|7
+
+## Create new content
+
+Use [content adapters] to create new content.
+
+[content adapters]: /content-management/content-adapters/
diff --git a/docs/content/en/content-management/diagrams.md b/docs/content/en/content-management/diagrams.md
index 17407098fa5..8851034c6c2 100644
--- a/docs/content/en/content-management/diagrams.md
+++ b/docs/content/en/content-management/diagrams.md
@@ -1,20 +1,22 @@
---
title: Diagrams
-description: Use fenced code blocks and markdown render hooks to display diagrams.
+description: Use fenced code blocks and Markdown render hooks to include diagrams in your content.
categories: [content management]
keywords: [diagrams,drawing]
menu:
docs:
parent: content-management
- weight: 50
-weight: 50
+ weight: 260
+weight: 260
toc: true
---
-{{< new-in 0.93.0 >}}
## GoAT diagrams (ASCII)
-Hugo supports [GoAT](https://github.com/bep/goat) natively. This means that this code block:
+Hugo natively supports [GoAT] diagrams with an [embedded code block render hook]. This means that this code block:
+
+[GoAT]: https://github.com/bep/goat
+[embedded code block render hook]: {{% eturl render-codeblock-goat %}}
````txt
```goat
@@ -44,19 +46,21 @@ Will be rendered as:
## Mermaid diagrams
-Hugo currently does not provide default templates for Mermaid diagrams. But you can easily add your own. One way to do it would be to create `layouts/_default/_markup/render-codeblock-mermaid.html`:
+Hugo does not provide a built-in template for Mermaid diagrams. Create your own using a [code block render hook]:
-```go-html-template
+[code block render hook]: /render-hooks/code-blocks/
+
+{{< code file=layouts/_default/_markup/render-codeblock-mermaid.html >}}
{{- .Inner | safeHTML }}
{{ .Page.Store.Set "hasMermaid" true }}
-```
+{{< /code >}}
-And then include this snippet at the bottom of the content template (**Note**: below `.Content` as the render hook is not processed until `.Content` is executed):
+And then include this snippet at the bottom of the content template:
```go-html-template
-{{ if .Page.Store.Get "hasMermaid" }}
+{{ if .Store.Get "hasMermaid" }}
` → ``
-* `` → ``
+Use the `safe.JS` function to encapsulate a known safe EcmaScript5 Expression.
+
+Template authors are responsible for ensuring that typed expressions do not break the intended precedence and that there is no statement/expression ambiguity as when passing an expression like `{ foo: bar() }\n['foo']()`, which is both a valid Expression and a valid Program with a very different meaning.
+
+Use of this type presents a security risk: the encapsulated content should come from a trusted source, as it will be included verbatim in the template output.
+
+Using the `safe.JS` function to include valid but untrusted JSON is not safe. A safe alternative is to parse the JSON with the [`transform.Unmarshal`] function and then pass the resultant object into the template, where it will be converted to sanitized JSON when presented in a JavaScript context.
+
+[`transform.Unmarshal`]: /functions/transform/unmarshal/
+
+See the [Go documentation] for details.
+
+[Go documentation]: https://pkg.go.dev/html/template#JS
+
+## Example
+
+Without a safe declaration:
+
+```go-html-template
+{{ $js := "x + y" }}
+
+```
+
+Hugo renders the above to:
+
+```html
+
+```
+
+To declare the string as safe:
+
+```go-html-template
+{{ $js := "x + y" }}
+
+```
+
+Hugo renders the above to:
+
+```html
+
+```
diff --git a/docs/content/en/functions/safe/JSStr.md b/docs/content/en/functions/safe/JSStr.md
index 36d2b36fa8d..e7e232d1be3 100644
--- a/docs/content/en/functions/safe/JSStr.md
+++ b/docs/content/en/functions/safe/JSStr.md
@@ -13,12 +13,27 @@ action:
- functions/safe/URL
returnType: template.JSStr
signatures: [safe.JSStr INPUT]
+toc: true
aliases: [/functions/safejsstr]
---
-Encapsulates a sequence of characters meant to be embedded between quotes in a JavaScript expression. Use of this type presents a security risk: the encapsulated content should come from a trusted source, as it will be included verbatim in the template output.
-
-Without declaring a variable to be a safe JavaScript string:
+## Introduction
+
+{{% include "functions/_common/go-html-template-package.md" %}}
+
+## Usage
+
+Use the `safe.JSStr` function to encapsulate a sequence of characters meant to be embedded between quotes in a JavaScript expression.
+
+Use of this type presents a security risk: the encapsulated content should come from a trusted source, as it will be included verbatim in the template output.
+
+See the [Go documentation] for details.
+
+[Go documentation]: https://pkg.go.dev/html/template#JSStr
+
+## Example
+
+Without a safe declaration:
```go-html-template
{{ $title := "Lilo & Stitch" }}
@@ -27,7 +42,7 @@ Without declaring a variable to be a safe JavaScript string:
```
-Rendered:
+Hugo renders the above to:
```html
```
-To avoid escaping by Go's [html/template] package:
+To declare the string as safe:
```go-html-template
{{ $title := "Lilo & Stitch" }}
@@ -44,12 +59,10 @@ To avoid escaping by Go's [html/template] package:
```
-Rendered:
+Hugo renders the above to:
```html
```
-
-[html/template]: https://pkg.go.dev/html/template
diff --git a/docs/content/en/functions/safe/URL.md b/docs/content/en/functions/safe/URL.md
index 2da6895e536..e4b3224dacb 100644
--- a/docs/content/en/functions/safe/URL.md
+++ b/docs/content/en/functions/safe/URL.md
@@ -13,58 +13,56 @@ action:
- functions/safe/JSStr
returnType: template.URL
signatures: [safe.URL INPUT]
+toc: true
aliases: [/functions/safeurl]
---
-`safeURL` declares the provided string as a "safe" URL or URL substring (see [RFC 3986]). A URL like `javascript:checkThatFormNotEditedBeforeLeavingPage()` from a trusted source should go in the page, but by default dynamic `javascript:` URLs are filtered out since they are a frequently exploited injection vector.
+## Introduction
-Without `safeURL`, only the URI schemes `http:`, `https:` and `mailto:` are considered safe by Go templates. If any other URI schemes (e.g., `irc:` and `javascript:`) are detected, the whole URL will be replaced with `#ZgotmplZ`. This is to "defang" any potential attack in the URL by rendering it useless.
+{{% include "functions/_common/go-html-template-package.md" %}}
-The following examples use a [site `hugo.toml`][configuration] with the following [menu entry][menus]:
+## Usage
-{{< code-toggle file=hugo >}}
-[[menus.main]]
-name = "IRC: #golang at freenode"
-url = "irc://irc.freenode.net/#golang"
-{{< /code-toggle >}}
+Use the `safe.URL` function to encapsulate a known safe URL or URL substring. Schemes other than the following are considered unsafe:
-The following is an example of a sidebar partial that may be used in conjunction with the preceding front matter example:
+- `http:`
+- `https:`
+- `mailto:`
-{{< code file=layouts/partials/bad-url-sidebar-menu.html >}}
-
-
-{{< /code >}}
+Use of this type presents a security risk: the encapsulated content should come from a trusted source, as it will be included verbatim in the template output.
-This partial would produce the following HTML output:
+See the [Go documentation] for details.
+
+[Go documentation]: https://pkg.go.dev/html/template#URL
+
+## Example
+
+Without a safe declaration:
+
+```go-html-template
+{{ $href := "irc://irc.freenode.net/#golang" }}
+IRC
+```
+
+Hugo renders the above to:
```html
-
-
+IRC
```
-The odd output can be remedied by adding ` | safeURL` to our `.URL` page variable:
+{{% note %}}
+`ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context at runtime.
+{{% /note %}}
+
+To declare the string as safe:
-{{< code file=layouts/partials/correct-url-sidebar-menu.html >}}
-
-
-{{< /code >}}
+```go-html-template
+{{ $href := "irc://irc.freenode.net/#golang" }}
+IRC
+```
-With the `.URL` page variable piped through `safeURL`, we get the desired output:
+Hugo renders the above to:
```html
-
+IRC
```
-
-[configuration]: /getting-started/configuration/
-[menus]: /content-management/menus/
-[RFC 3986]: https://tools.ietf.org/html/rfc3986
diff --git a/docs/content/en/functions/strings/ContainsNonSpace.md b/docs/content/en/functions/strings/ContainsNonSpace.md
index 188aa14ba63..d4c72eea09a 100644
--- a/docs/content/en/functions/strings/ContainsNonSpace.md
+++ b/docs/content/en/functions/strings/ContainsNonSpace.md
@@ -1,6 +1,6 @@
---
title: strings.ContainsNonSpace
-description: Reports whether the given string contains any non-space characters as defined by Unicode’s White Space property.
+description: Reports whether the given string contains any non-space characters as defined by Unicode's White Space property.
categories: []
keywords: []
action:
@@ -24,7 +24,7 @@ aliases: [/functions/strings.containsnonspace]
{{ strings.ContainsNonSpace "\n abc" }} → true
```
-Common white space characters include:
+Common whitespace characters include:
```text
'\t', '\n', '\v', '\f', '\r', ' '
diff --git a/docs/content/en/functions/strings/CountRunes.md b/docs/content/en/functions/strings/CountRunes.md
index 10788e1746f..87d9da680a6 100644
--- a/docs/content/en/functions/strings/CountRunes.md
+++ b/docs/content/en/functions/strings/CountRunes.md
@@ -21,4 +21,4 @@ In contrast with the [`strings.RuneCount`] function, which counts every rune in
{{ "Hello, 世界" | strings.CountRunes }} → 8
```
-[`strings.RuneCount`]: /functions/strings/runecount
+[`strings.RuneCount`]: /functions/strings/runecount/
diff --git a/docs/content/en/functions/strings/Diff/diff-screen-capture.png b/docs/content/en/functions/strings/Diff/diff-screen-capture.png
new file mode 100644
index 00000000000..62baa45630a
Binary files /dev/null and b/docs/content/en/functions/strings/Diff/diff-screen-capture.png differ
diff --git a/docs/content/en/functions/strings/Diff/index.md b/docs/content/en/functions/strings/Diff/index.md
new file mode 100644
index 00000000000..be7bfd9118b
--- /dev/null
+++ b/docs/content/en/functions/strings/Diff/index.md
@@ -0,0 +1,33 @@
+---
+title: strings.Diff
+description: Returns an anchored diff of the two texts OLD and NEW in the unified diff format. If OLD and NEW are identical, returns an empty string.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: string
+ signatures: [strings.Diff OLDNAME OLD NEWNAME NEW]
+---
+
+{{< new-in 0.125.0 >}}
+
+Use `strings.Diff` to compare two strings and render a highlighted diff:
+
+```go-html-template
+{{ $want := `
+
The product of 6 and 7 is 42.
+
The product of 7 and 6 is 42.
+`}}
+
+{{ $got := `
+
The product of 6 and 7 is 42.
+
The product of 7 and 6 is 13.
+`}}
+
+{{ $diff := strings.Diff "want" $want "got" $got }}
+{{ transform.Highlight $diff "diff" }}
+```
+
+Rendered:
+
+
diff --git a/docs/content/en/functions/strings/FindRESubmatch.md b/docs/content/en/functions/strings/FindRESubmatch.md
index 302d1d9b4f0..3feb15bbdf4 100644
--- a/docs/content/en/functions/strings/FindRESubmatch.md
+++ b/docs/content/en/functions/strings/FindRESubmatch.md
@@ -30,7 +30,7 @@ By default, `findRESubmatch` finds all matches. You can limit the number of matc
## Practical example
-This markdown:
+This Markdown:
```text
- [Example](https://example.org)
diff --git a/docs/content/en/functions/strings/RuneCount.md b/docs/content/en/functions/strings/RuneCount.md
index 46fedf01f41..86aab0c640c 100644
--- a/docs/content/en/functions/strings/RuneCount.md
+++ b/docs/content/en/functions/strings/RuneCount.md
@@ -21,4 +21,4 @@ In contrast with the [`strings.CountRunes`] function, which excludes whitespace,
{{ "Hello, 世界" | strings.RuneCount }} → 9
```
-[`strings.CountRunes`]: /functions/strings/countrunes
+[`strings.CountRunes`]: /functions/strings/countrunes/
diff --git a/docs/content/en/functions/strings/SliceString.md b/docs/content/en/functions/strings/SliceString.md
index 2f33f8f6561..ee4ed908145 100644
--- a/docs/content/en/functions/strings/SliceString.md
+++ b/docs/content/en/functions/strings/SliceString.md
@@ -1,20 +1,26 @@
---
title: strings.SliceString
-description: Creates a slice of a half-open range, including start and end indices.
+description: Returns a substring of the given string, beginning with the start position and ending before the end position.
categories: []
keywords: []
action:
aliases: [slicestr]
- related: []
+ related:
+ - functions/strings/Substr
returnType: string
- signatures: ['strings.SliceString STRING START [END]']
+ signatures: ['strings.SliceString STRING [START] [END]']
aliases: [/functions/slicestr]
---
-For example, 1 and 4 creates a slice including elements 1 through 3.
-The `end` index can be omitted; it defaults to the string's length.
+The START and END positions are zero-based, where `0` represents the first character of the string. If START is not specified, the substring will begin at position `0`. If END is not specified, the substring will end after the last character.
```go-html-template
-{{ slicestr "BatMan" 3 }}` → Man
-{{ slicestr "BatMan" 0 3 }}` → Bat
+{{ slicestr "BatMan" }} → BatMan
+{{ slicestr "BatMan" 3 }} → Man
+{{ slicestr "BatMan" 0 3 }} → Bat
```
+
+The START and END arguments represent the endpoints of a [half-open interval], a concept that may be difficult to grasp when first encountered. You may find that the [`strings.Substr`] function is easier to understand.
+
+[half-open interval]: /getting-started/glossary/#interval
+[`strings.Substr`]: /functions/strings/substr/
diff --git a/docs/content/en/functions/strings/Split.md b/docs/content/en/functions/strings/Split.md
index a9973ea63b2..e3e0ee13eba 100644
--- a/docs/content/en/functions/strings/Split.md
+++ b/docs/content/en/functions/strings/Split.md
@@ -22,5 +22,5 @@ Examples:
{{% note %}}
The `strings.Split` function essentially does the opposite of the [`collections.Delimit`] function. While `split` creates a slice from a string, `delimit` creates a string from a slice.
-[`collections.Delimit`]: /functions/collections/delimit
+[`collections.Delimit`]: /functions/collections/delimit/
{{% /note %}}
diff --git a/docs/content/en/functions/strings/Substr.md b/docs/content/en/functions/strings/Substr.md
index 6c1852f5800..19a029e28c6 100644
--- a/docs/content/en/functions/strings/Substr.md
+++ b/docs/content/en/functions/strings/Substr.md
@@ -1,21 +1,20 @@
---
title: strings.Substr
-description: Extracts parts of a string from a specified character's position and returns the specified number of characters.
+description: Returns a substring of the given string, beginning with the start position and ending after the given length.
categories: []
keywords: []
action:
aliases: [substr]
- related: []
+ related:
+ - functions/strings/SliceString
returnType: string
- signatures: ['strings.Substr STRING START [LENGTH]']
+ signatures: ['strings.Substr STRING [START] [LENGTH]']
aliases: [/functions/substr]
---
-It normally takes two argument: `start` and `length`. It can also take one argument: `start`, i.e. `length` is omitted, in which case the substring starting from start until the end of the string will be returned.
+The start position is zero-based, where `0` represents the first character of the string. If START is not specified, the substring will begin at position `0`. Specify a negative START position to extract characters from the end of the string.
-To extract characters from the end of the string, use a negative start number.
-
-If `length` is given and is negative, that number of characters will be omitted from the end of string.
+If LENGTH is not specified, the substring will include all characters from the START position to the end of the string. If negative, that number of characters will be omitted from the end of string.
```go-html-template
{{ substr "abcdef" 0 }} → abcdef
diff --git a/docs/content/en/functions/strings/Trim.md b/docs/content/en/functions/strings/Trim.md
index 6dfac024b1e..9a87ff20680 100644
--- a/docs/content/en/functions/strings/Trim.md
+++ b/docs/content/en/functions/strings/Trim.md
@@ -32,7 +32,7 @@ To remove leading and trailing newline characters and carriage returns:
The `strings.Trim` function is commonly used in shortcodes to remove leading and trailing newlines characters and carriage returns from the content within the opening and closing shortcode tags.
-For example, with this markdown:
+For example, with this Markdown:
```text
{{}}
diff --git a/docs/content/en/functions/strings/Truncate.md b/docs/content/en/functions/strings/Truncate.md
index 17ae0afc612..2e7693eb595 100644
--- a/docs/content/en/functions/strings/Truncate.md
+++ b/docs/content/en/functions/strings/Truncate.md
@@ -20,5 +20,5 @@ Since Go templates are HTML-aware, `truncate` will intelligently handle normal s
{{% note %}}
If you have a raw string that contains HTML tags you want to remain treated as HTML, you will need to convert the string to HTML using the [`safeHTML`]function before sending the value to `truncate`. Otherwise, the HTML tags will be escaped when passed through the `truncate` function.
-[`safeHTML`]: /functions/safe/html
+[`safeHTML`]: /functions/safe/html/
{{% /note %}}
diff --git a/docs/content/en/functions/time/Duration.md b/docs/content/en/functions/time/Duration.md
index f9c26d294e3..051be7ade70 100644
--- a/docs/content/en/functions/time/Duration.md
+++ b/docs/content/en/functions/time/Duration.md
@@ -43,4 +43,4 @@ microseconds|`microsecond`, `us`, `µs`
nanoseconds|`nanosecond`, `ns`
[`time.Duration`]: https://pkg.go.dev/time#Duration
-[methods]: /methods/duration
+[methods]: /methods/duration/
diff --git a/docs/content/en/functions/time/Now.md b/docs/content/en/functions/time/Now.md
index 60e45a91c14..28ac7acfc51 100644
--- a/docs/content/en/functions/time/Now.md
+++ b/docs/content/en/functions/time/Now.md
@@ -43,6 +43,6 @@ The `time.Now` function returns a `time.Time` value, so you can chain any of the
{{ time.Now.Unix }} → 1697400955 (int64)
```
-[`time.Format`]: /functions/time/format
+[`time.Format`]: /functions/time/format/
[localize]: /getting-started/glossary/#localization
[time methods]: /methods/time/
diff --git a/docs/content/en/functions/time/ParseDuration.md b/docs/content/en/functions/time/ParseDuration.md
index 0919141322d..d3369b8994b 100644
--- a/docs/content/en/functions/time/ParseDuration.md
+++ b/docs/content/en/functions/time/ParseDuration.md
@@ -34,4 +34,4 @@ There are 86400 seconds in one day.
```
[`time.Duration`]: https://pkg.go.dev/time#Duration
-[methods]: /methods/duration
+[methods]: /methods/duration/
diff --git a/docs/content/en/functions/time/_common/_index.md b/docs/content/en/functions/time/_common/_index.md
index 47d5812fba5..4328d4d145b 100644
--- a/docs/content/en/functions/time/_common/_index.md
+++ b/docs/content/en/functions/time/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
diff --git a/docs/content/en/functions/transform/HTMLUnescape.md b/docs/content/en/functions/transform/HTMLUnescape.md
index 18031807710..1c88de6727a 100644
--- a/docs/content/en/functions/transform/HTMLUnescape.md
+++ b/docs/content/en/functions/transform/HTMLUnescape.md
@@ -25,6 +25,6 @@ In most contexts Go's [html/template] package will escape special characters. To
{{ htmlUnescape "Lilo & Stitch" | safeHTML }}
```
-[`safehtml`]: /functions/safe/html
+[`safehtml`]: /functions/safe/html/
[html entities]: https://developer.mozilla.org/en-us/docs/glossary/entity
[html/template]: https://pkg.go.dev/html/template
diff --git a/docs/content/en/functions/transform/Markdownify.md b/docs/content/en/functions/transform/Markdownify.md
index 8fb1e48ce38..7a84f43b744 100644
--- a/docs/content/en/functions/transform/Markdownify.md
+++ b/docs/content/en/functions/transform/Markdownify.md
@@ -1,6 +1,6 @@
---
title: transform.Markdownify
-description: Renders markdown to HTML.
+description: Renders Markdown to HTML.
categories: []
keywords: []
action:
@@ -24,8 +24,8 @@ To keep the wrapping `p` tags for a single paragraph, use the [`RenderString`] m
[`RenderString`]: /methods/page/renderstring/
{{% note %}}
-Although the `markdownify` function honors [markdown render hooks] when rendering markdown to HTML, use the `RenderString` method instead of `markdownify` if a render hook accesses `.Page` context. See issue [#9692] for details.
+Although the `markdownify` function honors [Markdown render hooks] when rendering Markdown to HTML, use the `RenderString` method instead of `markdownify` if a render hook accesses `.Page` context. See issue [#9692] for details.
-[markdown render hooks]: /templates/render-hooks/
+[Markdown render hooks]: /render-hooks/
[#9692]: https://github.com/gohugoio/hugo/issues/9692
{{% /note %}}
diff --git a/docs/content/en/functions/transform/Unmarshal.md b/docs/content/en/functions/transform/Unmarshal.md
index bc2b663e387..998152eb24a 100644
--- a/docs/content/en/functions/transform/Unmarshal.md
+++ b/docs/content/en/functions/transform/Unmarshal.md
@@ -46,10 +46,10 @@ assets/
```
```go-html-template
-{{ $data := "" }}
+{{ $data := dict }}
{{ $path := "data/books.json" }}
{{ with resources.Get $path }}
- {{ with unmarshal . }}
+ {{ with . | transform.Unmarshal }}
{{ $data = . }}
{{ end }}
{{ else }}
@@ -75,10 +75,10 @@ content/
```
```go-html-template
-{{ $data := "" }}
+{{ $data := dict }}
{{ $path := "books.json" }}
{{ with .Resources.Get $path }}
- {{ with unmarshal . }}
+ {{ with . | transform.Unmarshal }}
{{ $data = . }}
{{ end }}
{{ else }}
@@ -95,7 +95,7 @@ content/
A remote resource is a file on a remote server, accessible via HTTP or HTTPS.
```go-html-template
-{{ $data := "" }}
+{{ $data := dict }}
{{ $url := "https://example.org/books.json" }}
{{ with resources.GetRemote $url }}
{{ with .Err }}
@@ -112,8 +112,15 @@ A remote resource is a file on a remote server, accessible via HTTP or HTTPS.
{{ end }}
```
-[resource]: /getting-started/glossary/#resource
-[page bundle]: /content-management/page-bundles
+{{% note %}}
+When retrieving remote data, a misconfigured server may send a response header with an incorrect [Content-Type]. For example, the server may set the Content-Type header to `application/octet-stream` instead of `application/json`.
+
+In these cases, pass the resource `Content` through the `transform.Unmarshal` function instead of passing the resource itself. For example, in the above, do this instead:
+
+`{{ $data = .Content | transform.Unmarshal }}`
+
+[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
+{{% /note %}}
## Options
@@ -166,7 +173,7 @@ When unmarshaling an XML file, do not include the root node when accessing data.
Get the remote data:
```go-html-template
-{{ $data := "" }}
+{{ $data := dict }}
{{ $url := "https://example.org/books/index.xml" }}
{{ with resources.GetRemote $url }}
{{ with .Err }}
@@ -182,7 +189,7 @@ Get the remote data:
Inspect the data structure:
```go-html-template
-
{{ jsonify (dict "indent" " ") $data }}
+
{{ debug.Dump $data }}
```
List the book titles:
@@ -245,7 +252,7 @@ Let's add a `lang` attribute to the `title` nodes of our RSS feed, and a namespa
After retrieving the remote data, inspect the data structure:
```go-html-template
-
{{ jsonify (dict "indent" " ") $data }}
+
{{ debug.Dump $data }}
```
Each item node looks like this:
@@ -288,5 +295,7 @@ Hugo renders this to:
```
-[`index`]: /functions/collections/indexfunction
+[`index`]: /functions/collections/indexfunction/
[identifiers]: https://go.dev/ref/spec#Identifiers
+[resource]: /getting-started/glossary/#resource
+[page bundle]: /content-management/page-bundles/
diff --git a/docs/content/en/functions/urls/AbsLangURL.md b/docs/content/en/functions/urls/AbsLangURL.md
index 876552bb7b1..67e1781e7e2 100644
--- a/docs/content/en/functions/urls/AbsLangURL.md
+++ b/docs/content/en/functions/urls/AbsLangURL.md
@@ -20,48 +20,44 @@ Use this function with both monolingual and multilingual configurations. The URL
- The `baseURL` in site configuration
- The language prefix, if any
-In examples that follow, the project is multilingual with content in both Español (`es`) and English (`en`). The default language is Español. The returned values are from the English site.
+In examples that follow, the project is multilingual with content in both English (`en`) and Spanish (`es`). The returned values are from the English site.
### Input does not begin with a slash
-If the input does not begin with a slash, the resulting URL will be correct regardless of the `baseURL`.
+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.
With `baseURL = https://example.org/`
```go-html-template
-{{ absLangURL "" }} → https://example.org/en/
-{{ absLangURL "articles" }} → https://example.org/en/articles
-{{ absLangURL "style.css" }} → https://example.org/en/style.css
+{{ absLangURL "" }} → https://example.org/en/
+{{ absLangURL "articles" }} → https://example.org/en/articles
+{{ absLangURL "style.css" }} → https://example.org/en/style.css
```
With `baseURL = https://example.org/docs/`
```go-html-template
-{{ absLangURL "" }} → https://example.org/docs/en/
-{{ absLangURL "articles" }} → https://example.org/docs/en/articles
-{{ absLangURL "style.css" }} → https://example.org/docs/en/style.css
+{{ absLangURL "" }} → https://example.org/docs/en/
+{{ absLangURL "articles" }} → https://example.org/docs/en/articles
+{{ absLangURL "style.css" }} → https://example.org/docs/en/style.css
```
### Input begins with a slash
-If the input begins with a slash, the resulting URL will be incorrect when the `baseURL` includes a subdirectory. With a leading slash, the function returns a URL relative to the protocol+host section of the `baseURL`.
+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.
With `baseURL = https://example.org/`
```go-html-template
-{{ absLangURL "/" }} → https://example.org/en/
-{{ absLangURL "/articles" }} → https://example.org/en/articles
-{{ absLangURL "/style.css" }} → https://example.org/en/style.css
+{{ absLangURL "/" }} → https://example.org/en/
+{{ absLangURL "/articles" }} → https://example.org/en/articles
+{{ absLangURL "/style.css" }} → https://example.org/en/style.css
```
With `baseURL = https://example.org/docs/`
```go-html-template
-{{ absLangURL "/" }} → https://example.org/en/
-{{ absLangURL "/articles" }} → https://example.org/en/articles
-{{ absLangURL "/style.css" }} → https://example.org/en/style.css
+{{ absLangURL "/" }} → https://example.org/en/
+{{ absLangURL "/articles" }} → https://example.org/en/articles
+{{ absLangURL "/style.css" }} → https://example.org/en/style.css
```
-
-{{% note %}}
-The last three examples are not desirable in most situations. As a best practice, never include a leading slash when using this function.
-{{% /note %}}
diff --git a/docs/content/en/functions/urls/AbsURL.md b/docs/content/en/functions/urls/AbsURL.md
index 5b027ae84ec..1120eac422b 100644
--- a/docs/content/en/functions/urls/AbsURL.md
+++ b/docs/content/en/functions/urls/AbsURL.md
@@ -14,53 +14,49 @@ action:
aliases: [/functions/absurl]
---
-With multilingual configurations, use the [`absLangURL`] function instead. The URL returned by this function depends on:
+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 site configuration
### Input does not begin with a slash
-If the input does not begin with a slash, the resulting URL will be correct regardless of the `baseURL`.
+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.
With `baseURL = https://example.org/`
```go-html-template
-{{ absURL "" }} → https://example.org/
-{{ absURL "articles" }} → https://example.org/articles
-{{ absURL "style.css" }} → https://example.org/style.css
+{{ absURL "" }} → https://example.org/
+{{ absURL "articles" }} → https://example.org/articles
+{{ absURL "style.css" }} → https://example.org/style.css
```
With `baseURL = https://example.org/docs/`
```go-html-template
-{{ absURL "" }} → https://example.org/docs/
-{{ absURL "articles" }} → https://example.org/docs/articles
-{{ absURL "style.css" }} → https://example.org/docs/style.css
+{{ absURL "" }} → https://example.org/docs/
+{{ absURL "articles" }} → https://example.org/docs/articles
+{{ absURL "style.css" }} → https://example.org/docs/style.css
```
#### Input begins with a slash
-If the input begins with a slash, the resulting URL will be incorrect when the `baseURL` includes a subdirectory. With a leading slash, the function returns a URL relative to the protocol+host section of the `baseURL`.
+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.
With `baseURL = https://example.org/`
```go-html-template
-{{ absURL "/" }} → https://example.org/
-{{ absURL "/articles" }} → https://example.org/articles
-{{ absURL "/style.css" }} → https://example.org/style.css
+{{ absURL "/" }} → https://example.org/
+{{ absURL "/articles" }} → https://example.org/articles
+{{ absURL "/style.css" }} → https://example.org/style.css
```
With `baseURL = https://example.org/docs/`
```go-html-template
-{{ absURL "/" }} → https://example.org/
-{{ absURL "/articles" }} → https://example.org/articles
-{{ absURL "/style.css" }} → https://example.org/style.css
+{{ absURL "/" }} → https://example.org/
+{{ absURL "/articles" }} → https://example.org/articles
+{{ absURL "/style.css" }} → https://example.org/style.css
```
-{{% note %}}
-The last three examples are not desirable in most situations. As a best practice, never include a leading slash when using this function.
-{{% /note %}}
-
-[`absLangURL`]: /functions/urls/abslangurl/
+[`urls.AbsLangURL`]: /functions/urls/abslangurl/
diff --git a/docs/content/en/functions/urls/Anchorize.md b/docs/content/en/functions/urls/Anchorize.md
index 72b3d54a9eb..f3939675a7c 100644
--- a/docs/content/en/functions/urls/Anchorize.md
+++ b/docs/content/en/functions/urls/Anchorize.md
@@ -16,14 +16,14 @@ aliases: [/functions/anchorize]
## 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 site configuration:
{{< code-toggle file=hugo >}}
[markup.goldmark.parser]
autoHeadingIDType = 'github'
{{< /code-toggle >}}
-This controls the behavior of the `anchorize` function and the generation of heading IDs when rendering markdown to HTML.
+This controls the behavior of the `anchorize` function and the generation of heading IDs when rendering Markdown to HTML.
Set `autoHeadingIDType` to one of:
diff --git a/docs/content/en/functions/urls/JoinPath.md b/docs/content/en/functions/urls/JoinPath.md
index 7acecb5068f..d9822cfda83 100644
--- a/docs/content/en/functions/urls/JoinPath.md
+++ b/docs/content/en/functions/urls/JoinPath.md
@@ -27,4 +27,4 @@ aliases: [/functions/urls.joinpath]
Unlike the [`path.Join`] function, `urls.JoinPath` retains consecutive leading slashes.
-[`path.Join`]: /functions/path/join
+[`path.Join`]: /functions/path/join/
diff --git a/docs/content/en/functions/urls/Parse.md b/docs/content/en/functions/urls/Parse.md
index 2eb4eeadf19..a64116254f4 100644
--- a/docs/content/en/functions/urls/Parse.md
+++ b/docs/content/en/functions/urls/Parse.md
@@ -19,6 +19,7 @@ The `urls.Parse` function parses a URL into a [URL structure](https://godoc.org/
{{ $url := "https://example.org:123/foo?a=6&b=7#bar" }}
{{ $u := urls.Parse $url }}
+{{ $u.String }} → https://example.org:123/foo?a=6&b=7#bar
{{ $u.IsAbs }} → true
{{ $u.Scheme }} → https
{{ $u.Host }} → example.org:123
diff --git a/docs/content/en/functions/urls/RelLangURL.md b/docs/content/en/functions/urls/RelLangURL.md
index 2c10370384b..883e7dda2e8 100644
--- a/docs/content/en/functions/urls/RelLangURL.md
+++ b/docs/content/en/functions/urls/RelLangURL.md
@@ -17,51 +17,49 @@ aliases: [/functions/rellangurl]
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 site configuration
+- The `baseURL` in your site configuration
- The language prefix, if any
-In examples that follow, the project is multilingual with content in both Español (`es`) and English (`en`). The default language is Español. The returned values are from the English site.
+In examples that follow, the project is multilingual with content in both English (`en`) and Spanish (`es`). The returned values are from the English site.
### Input does not begin with a slash
-If the input does not begin with a slash, the resulting URL will be correct regardless of the `baseURL`.
+If the input does not begin with a slash, the resulting URL will be relative to the `baseURL` in your site configuration.
With `baseURL = https://example.org/`
```go-html-template
-{{ relLangURL "" }} → /en/
-{{ relLangURL "articles" }} → /en/articles
-{{ relLangURL "style.css" }} → /en/style.css
+{{ relLangURL "" }} → /en/
+{{ relLangURL "articles" }} → /en/articles
+{{ relLangURL "style.css" }} → /en/style.css
+{{ relLangURL "https://example.org/foo" }} → /en/foo
```
With `baseURL = https://example.org/docs/`
```go-html-template
-{{ relLangURL "" }} → /docs/en/
-{{ relLangURL "articles" }} → /docs/en/articles
-{{ relLangURL "style.css" }} → /docs/en/style.css
+{{ relLangURL "" }} → /docs/en/
+{{ relLangURL "articles" }} → /docs/en/articles
+{{ relLangURL "style.css" }} → /docs/en/style.css
+{{ relLangURL "https://example.org/docs/foo" }} → /docs/en/foo
```
#### Input begins with a slash
-If the input begins with a slash, the resulting URL will be incorrect when the `baseURL` includes a subdirectory. With a leading slash, the function returns a URL relative to the protocol+host section of the `baseURL`.
+If the input begins with a slash, the resulting URL will be relative to the protocol+host of the `baseURL` in your site configuration.
With `baseURL = https://example.org/`
```go-html-template
-{{ relLangURL "/" }} → /en/
-{{ relLangURL "/articles" }} → /en/articles
-{{ relLangURL "/style.css" }} → /en/style.css
+{{ relLangURL "/" }} → /en/
+{{ relLangURL "/articles" }} → /en/articles
+{{ relLangURL "/style.css" }} → /en/style.css
```
With `baseURL = https://example.org/docs/`
```go-html-template
-{{ relLangURL "/" }} → /en/
-{{ relLangURL "/articles" }} → /en/articles
-{{ relLangURL "/style.css" }} → /en/style.css
+{{ relLangURL "/" }} → /en/
+{{ relLangURL "/articles" }} → /en/articles
+{{ relLangURL "/style.css" }} → /en/style.css
```
-
-{{% note %}}
-The last three examples are not desirable in most situations. As a best practice, never include a leading slash when using this function.
-{{% /note %}}
diff --git a/docs/content/en/functions/urls/RelURL.md b/docs/content/en/functions/urls/RelURL.md
index 9320c2827fc..18ac24d109f 100644
--- a/docs/content/en/functions/urls/RelURL.md
+++ b/docs/content/en/functions/urls/RelURL.md
@@ -14,53 +14,51 @@ action:
aliases: [/functions/relurl]
---
-With multilingual configurations, use the [`relLangURL`] function instead. The URL returned by this function depends on:
+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 site configuration
+- The `baseURL` in your site configuration
### Input does not begin with a slash
-If the input does not begin with a slash, the resulting URL will be correct regardless of the `baseURL`.
+If the input does not begin with a slash, the resulting URL will be relative to the `baseURL` in your site configuration.
With `baseURL = https://example.org/`
```go-html-template
-{{ relURL "" }} → /
-{{ relURL "articles" }} → /articles
-{{ relURL "style.css" }} → /style.css
+{{ relURL "" }} → /
+{{ relURL "articles" }} → /articles
+{{ relURL "style.css" }} → /style.css
+{{ relURL "https://example.org/foo" }} → /foo
```
With `baseURL = https://example.org/docs/`
```go-html-template
-{{ relURL "" }} → /docs/
-{{ relURL "articles" }} → /docs/articles
-{{ relURL "style.css" }} → /docs/style.css
+{{ relURL "" }} → /docs/
+{{ relURL "articles" }} → /docs/articles
+{{ relURL "style.css" }} → /docs/style.css
+{{ relURL "https://example.org/docs/foo" }} → /docs/foo
```
#### Input begins with a slash
-If the input begins with a slash, the resulting URL will be incorrect when the `baseURL` includes a subdirectory. With a leading slash, the function returns a URL relative to the protocol+host section of the `baseURL`.
+If the input begins with a slash, the resulting URL will be relative to the protocol+host of the `baseURL` in your site configuration.
With `baseURL = https://example.org/`
```go-html-template
-{{ relURL "/" }} → /
-{{ relURL "/articles" }} → /articles
-{{ relURL "style.css" }} → /style.css
+{{ relURL "/" }} → /
+{{ relURL "/articles" }} → /articles
+{{ relURL "/style.css" }} → /style.css
```
With `baseURL = https://example.org/docs/`
```go-html-template
-{{ relURL "/" }} → /
-{{ relURL "/articles" }} → /articles
-{{ relURL "/style.css" }} → /style.css
+{{ relURL "/" }} → /
+{{ relURL "/articles" }} → /articles
+{{ relURL "/style.css" }} → /style.css
```
-{{% note %}}
-The last three examples are not desirable in most situations. As a best practice, never include a leading slash when using this function.
-{{% /note %}}
-
-[`relLangURL`]: /functions/urls/rellangurl/
+[`urls.RelLangURL`]: /functions/urls/rellangurl/
diff --git a/docs/content/en/functions/urls/_common/_index.md b/docs/content/en/functions/urls/_common/_index.md
index 47d5812fba5..4328d4d145b 100644
--- a/docs/content/en/functions/urls/_common/_index.md
+++ b/docs/content/en/functions/urls/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
diff --git a/docs/content/en/functions/urls/_common/anchorize-vs-urlize.md b/docs/content/en/functions/urls/_common/anchorize-vs-urlize.md
index 0f01bcf78ee..718c1409883 100644
--- a/docs/content/en/functions/urls/_common/anchorize-vs-urlize.md
+++ b/docs/content/en/functions/urls/_common/anchorize-vs-urlize.md
@@ -4,8 +4,8 @@
The [`anchorize`] and [`urlize`] functions are similar:
-[`anchorize`]: /functions/urls/anchorize
-[`urlize`]: /functions/urls/urlize
+[`anchorize`]: /functions/urls/anchorize/
+[`urlize`]: /functions/urls/urlize/
- Use the `anchorize` function to generate an HTML `id` attribute value
- Use the `urlize` function to sanitize a string for usage in a URL
diff --git a/docs/content/en/getting-started/_index.md b/docs/content/en/getting-started/_index.md
index 780b96a623c..1648f0224a1 100644
--- a/docs/content/en/getting-started/_index.md
+++ b/docs/content/en/getting-started/_index.md
@@ -1,12 +1,12 @@
---
title: Getting started
-linkTitle: Overview
+linkTitle: In this section
description: Quick start and guides for installing Hugo on your preferred operating system.
categories: []
keywords: []
menu:
docs:
- identifier: getting-started-overview
+ identifier: getting-started-in-this-section
parent: getting-started
weight: 10
weight: 10
diff --git a/docs/content/en/getting-started/configuration-markup.md b/docs/content/en/getting-started/configuration-markup.md
index 607301d3afd..ab3dfa22107 100644
--- a/docs/content/en/getting-started/configuration-markup.md
+++ b/docs/content/en/getting-started/configuration-markup.md
@@ -2,7 +2,7 @@
title: Configure markup
description: Configure rendering of markup to HTML.
categories: [getting started,fundamentals]
-keywords: [configuration,highlighting]
+keywords: [markup,markdown,goldmark,asciidoc,asciidoctor,highlighting]
menu:
docs:
parent: getting-started
@@ -14,16 +14,16 @@ toc: true
## Default handler
-By default, Hugo uses [Goldmark] to render markdown to HTML.
+Hugo uses [Goldmark] to render Markdown to HTML.
{{< code-toggle file=hugo >}}
[markup]
defaultMarkdownHandler = 'goldmark'
{{< /code-toggle >}}
-Files with the `.md` or `.markdown` extension are processed as markdown, provided that you have not specified a different [content format] using the `markup` field in front matter.
+Files with the `.md` or `.markdown` extension are processed as Markdown, provided that you have not specified a different [content format] using the `markup` field in 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 site configuration.
defaultMarkdownHandler|Description
:--|:--
@@ -33,41 +33,86 @@ defaultMarkdownHandler|Description
`pandoc`|[Pandoc]
`rst`|[reStructuredText]
-To use Asciidoc, Pandoc, or reStructuredText you must install the relevant renderer and update your [security policy].
+To use AsciiDoc, Pandoc, or reStructuredText you must install the relevant renderer and update your [security policy].
{{% note %}}
-Unless you need a unique capability provided by one of the alternate markdown handlers, we strongly recommend that you use the default setting. Goldmark is fast, well maintained, conforms to the [CommonMark] specification, and is compatible with [GitHub Flavored Markdown] (GFM).
+Unless you need a unique capability provided by one of the alternate Markdown handlers, we strongly recommend that you use the default setting. Goldmark is fast, well maintained, conforms to the [CommonMark] specification, and is compatible with [GitHub Flavored Markdown] (GFM).
[commonmark]: https://spec.commonmark.org/0.30/
[github flavored markdown]: https://github.github.com/gfm/
{{% /note %}}
[asciidoc]: https://asciidoc.org/
-[content format]: /content-management/formats/#list-of-content-formats
+[content format]: /content-management/formats/#formats
[emacs org mode]: https://orgmode.org/
[goldmark]: https://github.com/yuin/goldmark/
[pandoc]: https://pandoc.org/
[restructuredtext]: https://docutils.sourceforge.io/rst.html
-[security policy]: /about/security-model/#security-policy
+[security policy]: /about/security/#security-policy
## Goldmark
-This is the default configuration for the Goldmark markdown renderer:
+This is the default configuration for the Goldmark Markdown renderer:
{{< code-toggle config=markup.goldmark />}}
-For details on the extensions, refer to the [Goldmark documentation](https://github.com/yuin/goldmark/#built-in-extensions).
+### Goldmark extensions
+
+The extensions below, excluding Extras and Passthrough, are enabled by default.
+
+Extension|Documentation|Enabled
+:--|:--|:-:
+cjk|[Goldmark Extensions: CJK]|:heavy_check_mark:
+definitionList|[PHP Markdown Extra: Definition lists]|:heavy_check_mark:
+extras|[Hugo Goldmark Extensions: Extras]|
+footnote|[PHP Markdown Extra: Footnotes]|:heavy_check_mark:
+linkify|[GitHub Flavored Markdown: Autolinks]|:heavy_check_mark:
+passthrough|[Hugo Goldmark Extensions: Passthrough]|
+strikethrough|[GitHub Flavored Markdown: Strikethrough]|:heavy_check_mark:
+table|[GitHub Flavored Markdown: Tables]|:heavy_check_mark:
+taskList|[GitHub Flavored Markdown: Task list items]|:heavy_check_mark:
+typographer|[Goldmark Extensions: Typographer]|:heavy_check_mark:
+
+[GitHub Flavored Markdown: Autolinks]: https://github.github.com/gfm/#autolinks-extension-
+[GitHub Flavored Markdown: Strikethrough]: https://github.github.com/gfm/#strikethrough-extension-
+[GitHub Flavored Markdown: Tables]: https://github.github.com/gfm/#tables-extension-
+[GitHub Flavored Markdown: Task list items]: https://github.github.com/gfm/#task-list-items-extension-
+[Goldmark Extensions: CJK]: https://github.com/yuin/goldmark?tab=readme-ov-file#cjk-extension
+[Goldmark Extensions: Typographer]: https://github.com/yuin/goldmark?tab=readme-ov-file#typographer-extension
+[Hugo Goldmark Extensions: Extras]: https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#extras-extension
+[Hugo Goldmark Extensions: Passthrough]: https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#passthrough-extension
+[PHP Markdown Extra: Definition lists]: https://michelf.ca/projects/php-markdown/extra/#def-list
+[PHP Markdown Extra: Footnotes]: https://michelf.ca/projects/php-markdown/extra/#footnotes
+
+#### Extras extension
+
+{{< new-in 0.126.0 >}}
+
+Configure the extras extension to enable [inserted text], [mark text], [subscript], and [superscript] elements in Markdown.
+
+Element|Markdown|Rendered
+:--|:--|:--
+Inserted text|`++foo++`|`foo`
+Mark text|`==bar==`|`bar`
+Subscript|`H~2~O`|`H2O`
+Superscript|`1^st^`|`1st`
+
+[inserted text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ins
+[mark text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark
+[subscript]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sub
+[superscript]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sup
+
+#### Passthrough extension
+
+{{< new-in 0.122.0 >}}
-Some settings explained:
+Enable the passthrough extension to include mathematical equations and expressions in Markdown using LaTeX or TeX typesetting syntax. See [mathematics in Markdown] for details.
-hardWraps
-: By default, Goldmark ignores newlines within a paragraph. Set to `true` to render newlines as ` ` elements.
+[mathematics in Markdown]: content-management/mathematics/
-unsafe
-: By default, Goldmark does not render raw HTML and potentially dangerous links. If you have lots of inline HTML and/or JavaScript, you may need to turn this on.
+#### Typographer extension
-typographer
-: The typographer extension replaces certain character combinations with HTML entities as specified below:
+The Typographer extension replaces certain character combinations with HTML entities as specified below:
Markdown|Replaced by|Description
:--|:--|:--
@@ -82,104 +127,164 @@ Markdown|Replaced by|Description
`”`|`”`|right double quote
`’`|`’`|right single quote
-attribute
-: Enable custom attribute support for titles and blocks by adding attribute lists inside single curly brackets (`{.myclass class="class1 class2" }`) and placing it _after the Markdown element it decorates_, on the same line for titles and on a new line directly below for blocks.
+### Goldmark settings explained
-Hugo supports adding attributes (e.g. CSS classes) to Markdown blocks, e.g. tables, lists, paragraphs etc.
+Most of the Goldmark settings above are self-explanatory, but some require explanation.
-A blockquote with a CSS class:
+###### duplicateResourceFiles
-```md
-> foo
-> bar
-{.myclass}
-```
+{{< new-in 0.123.0 >}}
-There are some current limitations: For tables you can currently only apply it to the full table, and for lists the `ul`/`ol`-nodes only, e.g.:
-
-```md
-* Fruit
- * Apple
- * Orange
- * Banana
- {.fruits}
-* Dairy
- * Milk
- * Cheese
- {.dairies}
-{.list}
-```
+(`bool`) If `true`, shared page resources on multilingual single-host sites will be duplicated for each language. See [multilingual page resources] for details. Default is `false`.
-Note that attributes in [code fences](/content-management/syntax-highlighting/#highlighting-in-code-fences) must come after the opening tag, with any other highlighting processing instruction, e.g.:
+[multilingual page resources]: /content-management/page-resources/#multilingual
-````txt
-```go {.myclass linenos=table,hl_lines=[8,"15-17"],linenostart=199}
-// ... code
-```
-````
+{{% note %}}
+With multilingual single-host sites, setting this parameter to `false` will enable Hugo's [embedded link render hook] and [embedded image render hook]. This is the default configuration for multilingual single-host sites.
+
+[embedded image render hook]: /render-hooks/images/#default
+[embedded link render hook]: /render-hooks/links/#default
+{{% /note %}}
+
+###### parser.wrapStandAloneImageWithinParagraph
+
+(`bool`) If `true`, image elements without adjacent content will be wrapped within a `p` element when rendered. This is the default Markdown behavior. Set to `false` when using an [image render hook] to render standalone images as `figure` elements. Default is `true`.
+
+[image render hook]: /render-hooks/images/
+
+###### parser.autoHeadingIDType
+
+(`string`) The strategy used to automatically generate heading `id` attributes, one of `github`, `github-ascii` or `blackfriday`.
+
+- `github` produces GitHub-compatible `id` attributes
+- `github-ascii` drops any non-ASCII characters after accent normalization
+- `blackfriday` produces `id` attributes compatible with the Blackfriday Markdown renderer
-autoHeadingIDType ("github")
-: The strategy used for creating auto IDs (anchor names). Available types are `github`, `github-ascii` and `blackfriday`. `github` produces GitHub-compatible IDs, `github-ascii` will drop any non-ASCII characters after accent normalization, and `blackfriday` will make the IDs compatible with Blackfriday, the default Markdown engine before Hugo 0.60. Note that if Goldmark is your default Markdown engine, this is also the strategy used in the [anchorize](/functions/urls/anchorize) template func.
+This is also the strategy used by the [anchorize](/functions/urls/anchorize) template function. Default is `github`.
-## Asciidoc
+###### parser.attribute.block
-This is the default configuration for the AsciiDoc markdown renderer:
+(`bool`) If `true`, enables [Markdown attributes] for block elements. Default is `false`.
+
+[Markdown attributes]: /content-management/markdown-attributes/
+
+###### parser.attribute.title
+
+(`bool`) If `true`, enables [Markdown attributes] for headings. Default is `true`.
+
+###### renderHooks.image.enableDefault
+
+{{< new-in 0.123.0 >}}
+
+(`bool`) If `true`, enables Hugo's [embedded image render hook]. Default is `false`.
+
+[embedded image render hook]: /render-hooks/images/#default
+
+{{% note %}}
+The embedded image render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites.
+
+[duplication of shared page resources]: /getting-started/configuration-markup/#duplicateresourcefiles
+{{% /note %}}
+
+###### renderHooks.link.enableDefault
+
+{{< new-in 0.123.0 >}}
+
+(`bool`) If `true`, enables Hugo's [embedded link render hook]. Default is `false`.
+
+[embedded link render hook]: /render-hooks/links/#default
+
+{{% note %}}
+The embedded link render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites.
+
+[duplication of shared page resources]: /getting-started/configuration-markup/#duplicateresourcefiles
+{{% /note %}}
+
+###### renderer.hardWraps
+
+(`bool`) If `true`, Goldmark replaces newline characters within a paragraph with `br` elements. Default is `false`.
+
+###### renderer.unsafe
+
+(`bool`) If `true`, Goldmark renders raw HTML mixed within the Markdown. This is unsafe unless the content is under your control. Default is `false`.
+
+## AsciiDoc
+
+This is the default configuration for the AsciiDoc renderer:
{{< code-toggle config=markup.asciidocExt />}}
-attributes
-: (`map`) Variables to be referenced in your AsciiDoc file. This is a list of variable name/value maps. See Asciidoctor’s [attributes].
+### AsciiDoc settings explained
+
+###### attributes
+
+(`map`) A map of key-value pairs, each a document attributes,See Asciidoctor’s [attributes].
[attributes]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions
-backend:
-: (`string`) Don’t change this unless you know what you are doing.
+###### backend
+
+(`string`) The backend output file format. Default is `html5`.
-extensions
-: (`[]string`) Possible extensions are `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`, `asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, and `asciidoctor-question`.
+###### extensions
-failureLevel
-: (`string`) The minimum logging level that triggers a non-zero exit code (failure).
+(`string array`) An array of enabled extensions, one or more of `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`, `asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, or `asciidoctor-question`.
-noHeaderOrFooter
-: (`bool`) Output an embeddable document, which excludes the header, the footer, and everything outside the body of the document. Don’t change this unless you know what you are doing.
+{{% note %}}
+To mitigate security risks, entries in the extension array may not contain forward slashes (`/`), backslashes (`\`), or periods. Due to this restriction, extensions must be in Ruby's `$LOAD_PATH`.
+{{% /note %}}
-preserveTOC
-: (`bool`) By default, Hugo removes the table of contents generated by Asciidoctor and provides it through the built-in variable `.TableOfContents` to enable further customization and better integration with the various Hugo themes. This option can be set to true to preserve Asciidoctor’s TOC in the generated page.
+###### failureLevel
-safeMode
-: (`string`) Safe mode level `unsafe`, `safe`, `server`, or `secure`. Don’t change this unless you know what you are doing.
+(`string`) The minimum logging level that triggers a non-zero exit code (failure). Default is `fatal`.
-sectionNumbers
-: (`bool`) Auto-number section titles.
+###### noHeaderOrFooter
-trace
-: (`bool`) Include backtrace information on errors.
+(`bool`) If `true`, outputs an embeddable document, which excludes the header, the footer, and everything outside the body of the document. Default is `true`.
-verbose
-: (`bool`) Verbosely print processing information and configuration file checks to stderr.
+###### preserveTOC
-workingFolderCurrent
-: (`bool`) Sets the working directory to be the same as that of the AsciiDoc file being processed, so that [include] will work with relative paths. This setting uses the asciidoctor cli parameter --base-dir and attribute outdir=. For rendering diagrams with [asciidoctor-diagram], `workingFolderCurrent` must be set to `true`.
+(`bool`) If `true`, preserves the table of contents (TOC) rendered by Asciidoctor. By default, to make the TOC compatible with existing themes, Hugo removes the TOC rendered by Asciidoctor. To render the TOC, use the [`TableOfContents`] method on a `Page` object in your templates. Default is `false`.
-[asciidoctor-diagram]: https://asciidoctor.org/docs/asciidoctor-diagram/
-[include]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files
+[`TableOfContents`]: /methods/page/tableofcontents/
+
+###### safeMode
-Notice that for security concerns only extensions that do not have path separators (either `\`, `/` or `.`) are allowed. That means that extensions can only be invoked if they are in the Ruby's `$LOAD_PATH` (ie. most likely, the extension has been installed by the user). Any extension declared relative to the website's path will not be accepted.
+(`string`) The safe mode level, one of `unsafe`, `safe`, `server`, or `secure`. Default is `unsafe`.
-Example of how to set extensions and attributes:
+###### sectionNumbers
-```yml
+(`bool`) If `true`, numbers each section title. Default is `false`.
+
+###### trace
+
+(`bool`) If `true`, include backtrace information on errors. Default is `false`.
+
+###### verbose
+
+(`bool`)If `true`, verbosely prints processing information and configuration file checks to stderr. Default is `false`.
+
+###### workingFolderCurrent
+
+(`bool`) If `true`, sets the working directory to be the same as that of the AsciiDoc file being processed, allowing [includes] to work with relative paths. Set to `true` to render diagrams with the [asciidoctor-diagram] extension. Default is `false`.
+
+[asciidoctor-diagram]: https://asciidoctor.org/docs/asciidoctor-diagram/
+[includes]: https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#includes
+
+### AsciiDoc configuration example
+
+{{< code-toggle file=hugo >}}
[markup.asciidocExt]
extensions = ["asciidoctor-html5s", "asciidoctor-diagram"]
workingFolderCurrent = true
[markup.asciidocExt.attributes]
my-base-url = "https://example.com/"
my-attribute-name = "my value"
-```
+{{< /code-toggle >}}
+
+### AsciiDoc troubleshooting
-In a complex Asciidoctor environment it is sometimes helpful to debug the exact call to your external helper with all
-parameters. Run Hugo with `-v`. You will get an output like
+Run `hugo --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 -] ...
@@ -200,19 +305,18 @@ For CSS, see [Generate Syntax Highlighter CSS](/content-management/syntax-highli
## Table of contents
+This is the default configuration for the table of contents, applicable to Goldmark and Asciidoctor:
+
{{< code-toggle config=markup.tableOfContents />}}
-These settings only works for the Goldmark renderer:
+###### startLevel
-startLevel
-: The heading level, values starting at 1 (`h1`), to start render the table of contents.
+(`int`) Heading levels less than this value will be excluded from the table of contents. For example, to exclude `h1` elements from the table of contents, set this value to `2`. Default is `2`.
-endLevel
-: The heading level, inclusive, to stop render the table of contents.
+###### endLevel
-ordered
-: If `true`, generates an ordered list instead of an unordered list.
+(`int`) Heading levels greater than this value will be excluded from the table of contents. For example, to exclude `h4`, `h5`, and `h6` elements from the table of contents, set this value to `3`. Default is `3`.
-## Render hooks
+###### ordered
-See [Markdown Render Hooks](/templates/render-hooks/).
+(`bool`) If `true`, generates an ordered list instead of an unordered list. Default is `false`.
diff --git a/docs/content/en/getting-started/configuration.md b/docs/content/en/getting-started/configuration.md
index 3ce0077ba59..35c7d780eaa 100644
--- a/docs/content/en/getting-started/configuration.md
+++ b/docs/content/en/getting-started/configuration.md
@@ -73,15 +73,11 @@ my-project/
│ ├── menus.en.toml
│ ├── menus.de.toml
│ └── params.toml
- ├── production/
- │ ├── hugo.toml
- │ └── params.toml
- └── staging/
- ├── hugo.toml
+ └── production/
└── params.toml
```
-The root configuration keys are `build`, `caches`, `cascade`, `deployment`, `frontmatter`, `imaging`, `languages`, `markup`, `mediatypes`, `menus`, `minify`, `module`, `outputformats`, `outputs`, `params`, `permalinks`, `privacy`, `related`, `security`, `server`, `services`, `sitemap`, and `taxonomies`.
+The root configuration keys are `build`, `caches`, `cascade`, `deployment`, `frontmatter`, `imaging`, `languages`, `markup`, `mediatypes`, `menus`, `minify`, `module`, `outputformats`, `outputs`, `params`, `permalinks`, `privacy`, `related`, `security`, `segments`, `server`, `services`, `sitemap`, and `taxonomies`.
### Omit the root key
@@ -226,25 +222,33 @@ See [Configure Build](#configure-build).
###### buildFuture
-(`bool`) Include content with publishdate in the future. Default is `false`.
+(`bool`) Include content with a future publication date. Default is `false`.
###### caches
See [Configure File Caches](#configure-file-caches).
+###### capitalizeListTitles
+
+{{< new-in 0.123.3 >}}
+
+(`bool`) Whether to capitalize automatic list titles. Applicable to section, taxonomy, and term pages. Default is `true`. You can change the capitalization style in your site configuration to one of `ap`, `chicago`, `go`, `firstupper`, or `none`. See [details].
+
+[details]: /getting-started/configuration/#configure-title-case
+
###### cascade
-Pass down down default configuration values (front matter) to pages in the content tree. The options in site config is the same as in page front matter, see [Front Matter Cascade](/content-management/front-matter#front-matter-cascade).
+Pass down default configuration values (front matter) to pages in the content tree. The options in site config is the same as in page front matter, see [Front Matter Cascade](/content-management/front-matter#cascade).
{{% note %}}
-For a website in a single language, define the `[[cascade]]` in [Front Matter](/content-management/front-matter#front-matter-cascade). For a multilingual website, define the `[[cascade]]` in [Site Config](../../getting-started/configuration/#cascade).
+For a website in a single language, define the `[[cascade]]` in [Front Matter](/content-management/front-matter#cascade). For a multilingual website, define the `[[cascade]]` in [Site Config](/getting-started/configuration/#cascade).
To remain consistent and prevent unexpected behavior, do not mix these strategies.
{{% /note %}}
###### canonifyURLs
-(`bool`) Enable to turn relative URLs into absolute. Default is `false`. See [details](/content-management/urls/#canonical-urls).
+(`bool`) See [details](/content-management/urls/#canonical-urls) before enabling this feature. Default is `false`.
###### cleanDestinationDir
@@ -324,8 +328,11 @@ See [image processing configuration](/content-management/image-processing/#imagi
(`string`) A language tag as defined by [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646). This value is used to populate:
-- The `` element in the internal [RSS template](https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/rss.xml)
-- The `lang` attribute of the `` element in the internal [alias template](https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/alias.html)
+- The `` element in the embedded [RSS template]({{% eturl rss %}})
+- The `lang` attribute of the `` element in the embedded [alias template]({{% eturl alias %}})
+- The `og:locale` `meta` element in the embedded [Open Graph template]({{% eturl opengraph %}})
+
+When present in the root of the configuration, this value is ignored if one or more language keys exists. Please specify this value independently for each language key.
###### languages
@@ -369,7 +376,7 @@ Module configuration see [module configuration](/hugo-modules/configuration/).
###### outputFormats
-See [Configure Output Formats](#configure-additional-output-formats).
+See [custom output formats].
###### paginate
@@ -385,27 +392,33 @@ See [Content Management](/content-management/urls/#permalinks).
###### pluralizeListTitles
-(`bool`) Pluralize titles in lists. Default is `true`.
+(`bool`) Whether to pluralize automatic list titles. Applicable to section pages. Default is `true`.
###### publishDir
(`string`) The directory to where Hugo will write the final static site (the HTML files etc.). Default is `public`.
+###### refLinksErrorLevel
+
+(`string`) When using `ref` or `relref` to resolve page links and a link cannot be resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`). Default is `ERROR`.
+
+###### refLinksNotFoundURL
+
+(`string`) URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is.
+
###### related
See [Related Content](/content-management/related/#configure-related-content).
###### relativeURLs
-(`bool`) Enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs. Default is `false`. See [details](/content-management/urls/#relative-urls).
+(`bool`) See [details](/content-management/urls/#relative-urls) before enabling this feature. Default is `false`.
-###### refLinksErrorLevel
+###### renderSegments
-(`string`) When using `ref` or `relref` to resolve page links and a link cannot be resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`). Default is `ERROR`.
+{{< new-in 0.124.0 >}}
-###### refLinksNotFoundURL
-
-(`string`) URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is.
+(`string slice`) A list of segments to render. If not set, everything will be rendered. This is more commonly set in a CLI flag, e.g. `hugo --renderSegments segment1,segment2`. The segment names must match the names in the [segments](#configure-segments) configuration.
###### removePathAccents
@@ -421,7 +434,11 @@ See [Menus](/content-management/menus/#define-automatically).
###### security
-See [Security Policy](/about/security-model/#security-policy).
+See [Security Policy](/about/security/#security-policy).
+
+###### segments
+
+See [Segments](#configure-segments).
###### sitemap
@@ -429,7 +446,9 @@ Default [sitemap configuration](/templates/sitemap-template/#configuration).
###### summaryLength
-(`int`) The length of text in words to show in a [`.Summary`](/content-management/summaries/#automatic-summary-splitting). Default is `70`.
+(`int`) Applicable to automatic summaries, the approximate number of words to render when calling the [`Summary`] method on a `Page` object. Default is `70`.
+
+[`Summary`]: /methods/page/summary/
###### taxonomies
@@ -605,6 +624,39 @@ to = "/404.html"
status = 404
{{< /code-toggle >}}
+With a multilingual site, define the redirect for the default content language last:
+
+{{< code-toggle file=config/development/server >}}
+defaultContentLanguage = 'en'
+defaultContentLanguageInSubdir = false
+[[redirects]]
+from = '/fr/**'
+to = '/fr/404.html'
+status = 404
+
+[[redirects]] # Default language must be last.
+from = '/**'
+to = '/404.html'
+status = 404
+{{< /code-toggle >}}
+
+If you are serving the default content language from a subdirectory:
+
+{{< code-toggle file=config/development/server >}}
+defaultContentLanguage = 'en'
+defaultContentLanguageInSubdir = true
+[[redirects]]
+from = '/fr/**'
+to = '/fr/404.html'
+status = 404
+
+[[redirects]] # Default language must be last.
+from = '/**'
+to = '/en/404.html'
+status = 404
+{{< /code-toggle >}}
+
+
## Configure title case
By default, Hugo follows the capitalization rules published in the [Associated Press Stylebook] when creating automatic section titles, and when transforming strings with the [`strings.Title`] function.
@@ -626,15 +678,31 @@ firstupper
none
: Disable transformation of automatic section titles, and disable the transformation performed by the `strings.Title` function. This is useful if you would prefer to manually capitalize section titles as needed, and to bypass opinionated theme usage of the `strings.Title` function.
-[`strings.Title`]: /functions/strings/title
+[`strings.Title`]: /functions/strings/title/
[Associated Press Stylebook]: https://www.apstylebook.com/
[Chicago Manual of Style]: https://www.chicagomanualofstyle.org/home.html
[site configuration]: /getting-started/configuration/#configure-title-case
## Configuration environment variables
+DART_SASS_BINARY
+: (`string`) The absolute path to the Dart Sass executable. By default, Hugo searches for the executable in each of the paths in the `PATH` environment variable.
+
+HUGO_ENVIRONMENT
+: (`string`) Overrides the default [environment], typically one of `development`, `staging`, or `production`.
+
+[environment]: /getting-started/glossary/#environment
+
+HUGO_FILE_LOG_FORMAT
+: (`string`) A format string for the file path, line number, and column number displayed when reporting errors, or when calling the `Position` method from a shortcode or Markdown render hook. Valid tokens are `:file`, `:line`, and `:col`. Default is `:file::line::col`.
+
+{{< new-in 0.123.0 >}}
+
+HUGO_MEMORYLIMIT
+: (`int`) The maximum amount of system memory, in gigabytes, that Hugo can use while rendering your site. Default is 25% of total system memory.
+
HUGO_NUMWORKERMULTIPLIER
-: Can be set to increase or reduce the number of workers used in parallel processing in Hugo. If not set, the number of logical CPUs will be used.
+: (`int`) The number of workers used in parallel processing. Default is the number of logical CPUs.
## Configure with environment variables
@@ -726,10 +794,6 @@ The above will try first to extract the value for `.Date` from the file name, th
`:git`
: This is the Git author date for the last revision of this content file. This will only be set if `--enableGitInfo` is set or `enableGitInfo = true` is set in site configuration.
-## Configure additional output formats
-
-Hugo v0.20 introduced the ability to render your content to multiple output formats (e.g., to JSON, AMP html, or CSV). See [Output Formats] for information on how to add these values to your Hugo project's configuration file.
-
## Configure minify
See the [tdewolff/minify] project page for details.
@@ -769,7 +833,7 @@ dir
This is the directory where Hugo by default will store its file caches. See [Configure File Caches](#configure-file-caches).
-This can be set using the `cacheDir` config option or via the OS env variable `HUGO_CACHEDIR`.
+This can be set using the `cacheDir` config option or via the OS environment variable `HUGO_CACHEDIR`.
If this is not set, Hugo will use, in order of preference:
@@ -779,10 +843,123 @@ If this is not set, Hugo will use, in order of preference:
If you want to know the current value of `cacheDir`, you can run `hugo config`, e.g: `hugo config | grep cachedir`.
-[`time`]: /functions/time/astime
-[`.Site.Params`]: /variables/site/
-[directory structure]: /getting-started/directory-structure
+[`time`]: /functions/time/astime/
+[`.Site.Params`]: /method/site/params/
+[directory structure]: /getting-started/directory-structure/
[lookup order]: /templates/lookup-order/
-[Output Formats]: /templates/output-formats/
+[custom output formats]: /templates/output-formats/
[templates]: /templates/
[static-files]: /content-management/static-files/
+
+
+## Configure HTTP cache
+
+{{< new-in 0.127.0 >}}
+
+Note that this configuration is currently only relevant when using the [resources.GetRemote] function.
+
+The caching in Hugo is layered:
+
+```goat {.w-40}
+ .-----------.
+| dynacache |
+ '-----+-----'
+ |
+ v
+ .----------.
+| HTTP cache |
+ '-----+----'
+ |
+ v
+ .----------.
+| file cache |
+ '-----+----'
+```
+
+Dynacache
+: A in memory LRU cache that gets evicted on changes, [Cache Buster](#configure-cache-busters) matches and in low memory situations.
+
+HTTP Cache
+: Enables HTTP cache behavior (RFC 9111) for remote resources. This works best for resources with properly set up HTTP cache headers. The HTTP cache uses the [file cache] to store and serve cached resources.
+
+File Cache
+: See [file cache].
+
+The default HTTP cache disables everything:
+
+{{< code-toggle config=HTTPCache />}}
+
+caching
+: Enabled RFC 9111 cache behavior _for_ a configured set of resources. Stale resources will be refreshed from the [file cache] even if their configured TTL isn't reached.
+
+polling
+: Enables polling _for_ a set of resources. Note that you can enable polling for resources even if HTTP caching is disabled. This setting is only used when in watch mode (e.g. `hugo server`). When a changed resource is detected, that change triggers a rebuild of pages using that resource.
+
+[resources.GetRemote]: /functions/resources/getremote/
+[file cache]: #configure-file-caches
+
+## Configure segments
+
+{{< new-in 0.124.0 >}}
+
+{{% note %}}
+The `segments` configuration is currently only used to configure partitioned rendering.
+This feature is only about what gets rendered when, Hugo's entire object graph (sites and pages) is
+always available.
+{{% /note %}}
+
+* Each segment consists of zero or more `exclude` filters and zero or more `include` filters.
+* Each filter consists of one or more field Glob matchers.
+* Each filter in a section (`exclude` or `include`) is ORed together, each matcher in a filter is ANDed together.
+
+The fields that can be used in the filters are:
+
+path
+: The logical page [path].
+
+lang
+: The [page language].
+
+kind
+: The [kind] of the page.
+
+output
+: The [output format] of the page.
+
+It is recommended to put coarse grained filters (e.g. for language and output format) in the excludes section, e.g.:
+
+
+{{< code-toggle file=hugo >}}
+[segments.segment1]
+ [[segments.segment1.excludes]]
+ lang = "n*"
+ [[segments.segment1.excludes]]
+ lang = "en"
+ output = "rss"
+ [[segments.segment1.includes]]
+ kind = "{home,term,taxonomy}"
+ [[segments.segment1.includes]]
+ path = "{/docs,/docs/**}"
+{{< /code-toggle >}}
+
+With the above you can render only the pages in `segment1` by configuring the [renderSegments](#rendersegments) or setting the `--renderSegments` flag:
+
+```bash
+hugo --renderSegments segment1
+```
+
+Multiple segments can be configured, and the `--renderSegments` flag can take a comma separated list of segments.
+
+Some use cases for this feature:
+
+* Splitting builds of big sites.
+* Enable faster builds during development by only rendering a subset of the site.
+* Partial rebuilds, e.g. render the home page and the "news section" every hour, render the entire site once a week.
+* Render only e.g. the JSON output format to push to e.g. a search index.
+
+[path]: /methods/page/path/
+[page language]: /methods/page/language/
+[kind]: /getting-started/glossary/#page-kind
+[output format]: /getting-started/glossary/#output-format
+[type]: /getting-started/glossary/#content-type
+
diff --git a/docs/content/en/getting-started/directory-structure.md b/docs/content/en/getting-started/directory-structure.md
index f91849375df..2331d883823 100644
--- a/docs/content/en/getting-started/directory-structure.md
+++ b/docs/content/en/getting-started/directory-structure.md
@@ -78,38 +78,49 @@ my-site/
Each of the subdirectories contributes to the content, structure, behavior, or presentation of your site.
-archetypes
-: The `archetypes` directory contains templates for new content. See [details](/content-management/archetypes/).
+###### archetypes
-assets
-: 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/).
+The `archetypes` directory contains templates for new content. See [details](/content-management/archetypes/).
-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](/getting-started/configuration/#configuration-directory).
+###### assets
-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 `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/).
-data
-: The `data` directory contains data files (JSON, TOML, YAML, or XML) that augment content, configuration, localization, and navigation. See [details](/templates/data-templates/).
+###### config
-i18n
-: The `i18n` directory contains translation tables for multilingual sites. See [details](/content-management/multilingual/).
+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](/getting-started/configuration/#configuration-directory).
-layouts
-: The layouts directory contains templates to transform content, data, and resources into a complete website. See [details](/templates/).
+###### content
-public
-: The `public` directory contains the published website, generated when you run the `hugo` command. Hugo recreates this directory and its content as needed. See [details](/getting-started/usage/#build-your-site).
+The `content` directory contains the markup files (typically Markdown) and page resources that comprise the content of your site. See [details](/content-management/organization/).
-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.
+###### data
-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](/getting-started/glossary/#page-bundle) and [asset pipelines](/hugo-pipes/introduction/), the `static` directory was also used for images, CSS, and JavaScript. See [details](/content-management/static-files/).
+The `data` directory contains data files (JSON, TOML, YAML, or XML) that augment content, configuration, localization, and navigation. See [details](/content-management/data-sources/).
-themes
-: The `themes` directory contains one or more [themes](/getting-started/glossary/#theme), each in its own subdirectory.
+###### i18n
+
+The `i18n` directory contains translation tables for multilingual sites. 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).
+
+###### 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.
+
+###### 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](/getting-started/glossary/#page-bundle) 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](/getting-started/glossary/#theme), each in its own subdirectory.
## Union file system
@@ -150,7 +161,7 @@ target = 'content'
{{% note %}}
When you overlay one directory on top of another, you must mount both directories.
-If you think you need a symbolic link in your project directory, use Hugo's union file system instead.
+Hugo does not follow symbolic links. If you need the functionality provided by symbolic links, use Hugo's union file system instead.
{{% /note %}}
After mounting, the union file system has this structure:
diff --git a/docs/content/en/getting-started/external-learning-resources/build-websites-with-hugo.png b/docs/content/en/getting-started/external-learning-resources/build-websites-with-hugo.png
new file mode 100644
index 00000000000..ebed7e89f75
Binary files /dev/null and b/docs/content/en/getting-started/external-learning-resources/build-websites-with-hugo.png differ
diff --git a/docs/content/en/getting-started/external-learning-resources/hia.jpg b/docs/content/en/getting-started/external-learning-resources/hia.jpg
deleted file mode 100644
index 601947a70e9..00000000000
Binary files a/docs/content/en/getting-started/external-learning-resources/hia.jpg and /dev/null differ
diff --git a/docs/content/en/getting-started/external-learning-resources/hugo-in-action.png b/docs/content/en/getting-started/external-learning-resources/hugo-in-action.png
new file mode 100644
index 00000000000..7bc5c99302c
Binary files /dev/null and b/docs/content/en/getting-started/external-learning-resources/hugo-in-action.png differ
diff --git a/docs/content/en/getting-started/external-learning-resources/index.md b/docs/content/en/getting-started/external-learning-resources/index.md
index 634439bc6a3..d30305c2eb0 100644
--- a/docs/content/en/getting-started/external-learning-resources/index.md
+++ b/docs/content/en/getting-started/external-learning-resources/index.md
@@ -1,6 +1,6 @@
---
title: External learning resources
-description: A list of tutorials and books on Hugo.
+description: Use these third-party resources to learn Hugo.
categories: [getting started]
keywords: [books, tutorials, learning, usage]
menu:
@@ -8,30 +8,83 @@ menu:
parent: getting-started
weight: 70
weight: 70
+toc: true
---
## Books
### Hugo In Action
-[](https://www.manning.com/books/hugo-in-action)
+Hugo in Action is a step-by-step guide to using Hugo to create static websites. Working with a complete example website and source code samples, you'll learn how to build and host a low-maintenance, high-performance site that will wow your users and stay stable without relying on a third-party server.
-Hugo in Action is a step-by-step guide to using Hugo to create static websites. Working with a complete example website and source code samples, you’ll learn how to build and host a low-maintenance, high-performance site that will wow your users and stay stable without relying on a third-party server.
+[{{< img src="hugo-in-action.png" alt="Book cover: Hugo in Action" filter="process" filterArgs="resize x350 webp">}}](https://www.manning.com/books/hugo-in-action/)
+
+Author: Atishay Jain\
+Publisher: [Manning Publications](https://www.manning.com/books/hugo-in-action/)\
+Publication date: March 2022\
+Length: 488 pages\
+ISBN: 9781617297007
-[Hugo In Action Home Page](https://www.manning.com/books/hugo-in-action)
### Build Websites with Hugo
-[Build Websites with Hugo - Fast Web Development with Markdown (2020)](https://pragprog.com/titles/bhhugo/) by Brian P. Hogan.
+In this book, you'll use Hugo to build a personal portfolio site that you can use to showcase your skills and thoughts to the world. You'll build the basic skeleton, develop a custom theme, and use content templates to generate new pages quickly. You'll use internal and external data sources to embed content into your site, and render some of your content in JSON and RSS. You'll add a blog section with posts and integrate Disqus with your site, and then make your site searchable.
+
+[{{< img src="build-websites-with-hugo.png" alt="Book cover: Build Websites with Hugo" filter="process" filterArgs="resize x350 webp">}}](https://pragprog.com/titles/bhhugo/build-websites-with-hugo/)
+
+
+Author: Brian P. Hogan\
+Publisher: [Pragmatic Bookshelf](https://pragprog.com/titles/bhhugo/build-websites-with-hugo/)\
+Publication date: May 2020\
+Length: 154 pages\
+ISBN: 9781680507263
+
+## Videos
+
+### Hugo Beginner Tutorial Series
+
+Welcome to this introduction to Hugo tutorial. The goal of this series is to take you from a lion cub with basic web design knowledge to creating your first Hugo website. In this series you’ll learn how to set up a Hugo site, the basics of usingHugo layouts, partials, and templating, set up a blog, and finally use data files. By the end of this series you’ll have the foundational knowledge to build your own Hugo sites.
+
+1. [Getting set up in Hugo](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/)
+1. [Layouts in Hugo](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/layouts-in-hugo/)
+1. [Hugo Partials](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/hugo-partials/)
+1. [Hugo templating basics](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/hugo-templating-basics/)
+1. [Blogging in Hugo](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/blogging-in-hugo/)
+1. [Using Data in Hugo](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/using-data-in-hugo/)
-## Beginner tutorials
+Creator: Mike Neumegen\
+Affiliation: [CloudCannon](https://cloudcannon.com/)\
+Creation date: April 2022
-### Hugo tutorial by CloudCannon
+#### Hugo Static Site Generator
-[Step-by-step written tutorial](https://cloudcannon.com/community/learn/hugo-beginner-tutorial/) to teach you the basics of creating a Hugo site.
+This course covers the basics of using the Hugo static site generator. Work your way through the articles and we'll teach you everything you need to know to create a professional and scalable website or blog!
-## Video tutorials
-* Mike Dane explains the various features of Hugo via dedicated tutorials on [YouTube](https://www.youtube.com/watch?list=PLLAZ4kZ9dFpOnyRlyS-liKL5ReHDcj4G3&v=qtIqKaDlqXo).
+1. [Introduction](https://www.giraffeacademy.com/static-site-generators/hugo/)
+1. [Windows Installation](https://www.giraffeacademy.com/static-site-generators/hugo/installing-hugo-on-windows/)
+1. [Mac Installation](https://www.giraffeacademy.com/static-site-generators/hugo/installing-hugo-on-mac/)
+1. [Creating A New Site](https://www.giraffeacademy.com/static-site-generators/hugo/hugo-directory-structure/)
+1. [Installing & Using Themes](https://www.giraffeacademy.com/static-site-generators/hugo/installing-using-themes/)
+1. [Content Organization](https://www.giraffeacademy.com/static-site-generators/hugo/content-organization/)
+1. [Front Matter](https://www.giraffeacademy.com/static-site-generators/hugo/front-matter/)
+1. [Archetypes](https://www.giraffeacademy.com/static-site-generators/hugo/archetypes/)
+1. [Shortcodes](https://www.giraffeacademy.com/static-site-generators/hugo/archetypes/)
+1. [Taxonomies](https://www.giraffeacademy.com/static-site-generators/hugo/taxonomies/)
+1. [Template Basics](https://www.giraffeacademy.com/static-site-generators/hugo/introduction-to-templates/)
+1. [List Page Templates](https://www.giraffeacademy.com/static-site-generators/hugo/list-page-templates/)
+1. [Single Page Templates](https://www.giraffeacademy.com/static-site-generators/hugo/single-page-templates/)
+1. [Home Page Templates](https://www.giraffeacademy.com/static-site-generators/hugo/home-page-templates/)
+1. [Section Templates](https://www.giraffeacademy.com/static-site-generators/hugo/section-templates/)
+1. [Block Templates](https://www.giraffeacademy.com/static-site-generators/hugo/block-templates/)
+1. [Variables](https://www.giraffeacademy.com/static-site-generators/hugo/variables/)
+1. [Functions](https://www.giraffeacademy.com/static-site-generators/hugo/functions/)
+1. [Conditionals](https://www.giraffeacademy.com/static-site-generators/hugo/conditionals/)
+1. [Data Templates](https://www.giraffeacademy.com/static-site-generators/hugo/data-templates/)
+1. [Partial Templates](https://www.giraffeacademy.com/static-site-generators/hugo/partial-templates/)
+1. [Shortcode Templates](https://www.giraffeacademy.com/static-site-generators/hugo/shortcode-templates/)
+1. [Building & Hosting](https://www.giraffeacademy.com/static-site-generators/hugo/building-&-hosting/)
-* [Introduction to building your first Hugo site](https://cloudcannon.com/community/learn/hugo-beginner-tutorial/) by Mike Neumegen.
+Creator: Mike Dane\
+Affiliation: [Giraffe Academy](https://www.giraffeacademy.com/)\
+Creation date: September 2017
diff --git a/docs/content/en/getting-started/glossary.md b/docs/content/en/getting-started/glossary.md
index d4c1d0e26ca..c86c3fc970f 100644
--- a/docs/content/en/getting-started/glossary.md
+++ b/docs/content/en/getting-started/glossary.md
@@ -11,25 +11,28 @@ weight: 60
# Use level 6 headings for each term in the glossary.
---
-[A](#action)
-[B](#bool)
-[C](#cache)
-[D](#default-sort-order)
-[E](#environment)
-[F](#field)
-[G](#global-resource)
-[I](#identifier)
-[K](#kind)
-[L](#layout)
-[M](#map)
-[O](#object)
-[P](#page-bundle)
-[R](#regular-page)
-[S](#scalar)
-[T](#taxonomic-weight)
-[U](#unmarshal)
-[V](#variable)
-[W](#walk)
+[A](#action)
+[B](#bool)
+[C](#cache)
+[D](#default-sort-order)
+[E](#environment)
+[F](#field)
+[G](#global-resource)
+[H](#headless-bundle)
+[I](#identifier)
+[K](#kind)
+[L](#layout)
+[M](#map)
+[N](#node)
+[O](#object)
+[P](#page-bundle)
+[R](#regular-page)
+[S](#scalar)
+[T](#taxonomic-weight)
+[U](#unmarshal)
+[V](#variable)
+[W](#walk)
+[Z](#zero-time)
###### action
@@ -57,7 +60,7 @@ A data type with two possible values, either `true` or `false`.
###### branch bundle
-A [page bundle](#page-bundle) with an _index.md file and zero or more [resources](#resource). Analogous to a physical branch, a branch bundle may have descendants including regular pages, [leaf bundles](/getting-started/glossary/#leaf-bundle), and other branch bundles. See [details](/content-management/page-bundles/).
+A directory that contains an _index.md file and zero or more [resources](#resource). Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without _index.md files are also branch bundles. This includes the home page. See [details](/content-management/page-bundles/).
###### build
@@ -75,13 +78,25 @@ A software component that stores data so that future requests for the same data
Within a template, to connect one or more [identifiers](#identifier) with a dot. An identifier can represent a method, object, or field. For example, `.Site.Params.author.name` or `.Date.UTC.Hour`.
+###### CJK
+
+A collective term for the Chinese, Japanese, and Korean languages. See [details](https://en.wikipedia.org/wiki/CJK_characters).
+
+###### CLI
+
+Command line interface.
+
###### collection
An [array](#array), [slice](#slice), or [map](#map).
+###### content adapter
+
+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. See [details](/content-management/content-adapters/).
+
###### content format
-A markup language for creating content. Typically markdown, but may also be HTML, AsciiDoc, Org, Pandoc, or reStructuredText. See [details](/content-management/formats/).
+A markup language for creating content. Typically Markdown, but may also be HTML, AsciiDoc, Org, Pandoc, or reStructuredText. See [details](/content-management/formats/).
###### content type
@@ -93,7 +108,7 @@ A template called with the `.Page.Render` method. See [details](/templates/
###### context
-Represented by a dot "." within a [template action](#template-action), context is the current location in a data structure. For example, while iterating over a [collection](#collection) of pages, the context within each iteration is the page's data structure. The context received by each template depends on template type and/or how it was called. See [details](/templates/introduction/#the-dot).
+Represented by a dot "." within a [template action](#template-action), context is the current location in a data structure. For example, while iterating over a [collection](#collection) of pages, the context within each iteration is the page's data structure. The context received by each template depends on template type and/or how it was called. See [details](/templates/introduction/#context).
###### default sort order
@@ -107,15 +122,15 @@ A member of a slice or array.
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.
+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.
To determine the current environment within a template, use the [`hugo.Environment`] function.
-[`hugo.Environment`]: /functions/hugo/environment
+[`hugo.Environment`]: /functions/hugo/environment/
###### field
-A predefined key/value pair in front matter such as `date` or `title`. See also [parameter](#parameter).
+A predefined key-value pair in front matter such as `date` or `title`. See also [parameter](#parameter).
###### flag
@@ -146,10 +161,14 @@ Used within a [template action](#template-action), a function takes one or more
A file within the assets directory, or within any directory [mounted](/hugo-modules/configuration/#module-configuration-mounts) to the assets directory. Capture one or more global resources using the [`resources.Get`], [`resources.GetMatch`], [`resources.Match`], or [`resources.ByType`] functions.
-[`resources.Get`]: /functions/resources/get
-[`resources.GetMatch`]: /functions/resources/getmatch
-[`resources.Match`]: /functions/resources/match
-[`resources.ByType`]: /functions/resources/byType
+[`resources.Get`]: /functions/resources/get/
+[`resources.GetMatch`]: /functions/resources/getmatch/
+[`resources.Match`]: /functions/resources/match/
+[`resources.ByType`]: /functions/resources/byType/
+
+###### headless bundle
+
+An unpublished leaf or branch bundle whose content and resources you can include in other pages. See [build options](/content-management/build-options/).
###### identifier
@@ -187,7 +206,7 @@ See [template](#template).
###### leaf bundle
-A [page bundle](#page-bundle) with an index.md file and zero or more [resources](#resource). Analogous to a physical leaf, a leaf bundle is at the end of a branch. Hugo ignores content (but not resources) beneath the leaf bundle. See [details](/content-management/page-bundles/).
+A directory that contains an index.md file and zero or more [resources](#resource). Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants. See [details](/content-management/page-bundles/).
###### list page
@@ -197,13 +216,19 @@ Any [page kind](#page-kind) that receives a page [collection](#collection) in [c
Adaptation of a site to meet language and regional requirements. This includes translations, language-specific media, date and currency formats, etc. See [details](/content-management/multilingual/) and the [W3C definition](https://www.w3.org/International/questions/qa-i18n). Abbreviated l10n.
+###### logical path
+
+{{< new-in 0.123.0 >}}
+
+A page or page resource identifier derived from the file path, excluding its extension and language identifier. This value is neither a file path nor a URL. Starting with a file path relative to the content directory, Hugo determines the logical path by stripping the file extension and language identifier, converting to lower case, then replacing spaces with hyphens. See [examples](/methods/page/path/#examples).
+
###### map
An unordered group of elements, each indexed by a unique key. See the [Go documentation](https://go.dev/ref/spec#Map_types) for details.
-###### markdown attribute
+###### Markdown attribute
-A list of attributes, containing one or more key/value pairs, separated by spaces or commas, and wrapped by braces. Apply markdown attributes to images and block-level elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables. See [details](/getting-started/configuration-markup/#goldmark).
+A list of attributes, containing one or more key-value pairs, separated by spaces or commas, and wrapped by braces. Apply Markdown attributes to images and block-level elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables. See [details](/getting-started/configuration-markup/#goldmark).
###### marshal
@@ -217,6 +242,14 @@ Used within a [template action](#template-action) and associated with an [object
Like a [theme](#theme), a module is a packaged combination of [archetypes](#archetype), assets, content, data, [templates](#template), translation tables, static files, or configuration settings. A module may serve as the basis for a new site, or to augment an existing site. See [details](/hugo-modules/).
+###### node
+
+A class of [page kinds](#page-kind) including `home`, `section`, `taxonomy`, and `term`.
+
+###### noop
+
+An abbreviated form of "no operation", a _noop_ is a statement that does nothing.
+
###### object
A data structure with or without associated [methods](#method).
@@ -225,8 +258,8 @@ A data structure with or without associated [methods](#method).
Created by invoking the [`Alphabetical`] or [`ByCount`] method on a [taxonomy object](#taxonomy-object), which is a [map](#map), an ordered taxonomy is a [slice](#slice), where each element is an object that contains the [term](#term) and a slice of its [weighted pages](#weighted-page).
-[`Alphabetical`]: /methods/taxonomy/alphabetical
-[`ByCount`]: /methods/taxonomy/bycount
+[`Alphabetical`]: /methods/taxonomy/alphabetical/
+[`ByCount`]: /methods/taxonomy/bycount/
###### output format
@@ -242,7 +275,7 @@ A slice of page objects.
###### page kind
-A classification of pages, one of `home`, `page`, `section`, `taxonomy`, or `term`. See [details](/templates/section-templates/#page-kinds).
+A classification of pages, one of `home`, `page`, `section`, `taxonomy`, or `term`. See [details](/methods/page/kind/).
Note that there are also `RSS`, `sitemap`, `robotsTXT`, and `404` page kinds, but these are only available during the rendering of each of these respective page's kind and therefore *not* available in any of the `Pages` collections.
@@ -266,7 +299,7 @@ The process of [paginating](#paginate) a [section](#section) list.
###### parameter
-Typically, a user-defined key/value pair at the site or page level, but may also refer to a configuration setting or an [argument](#argument). See also [field](#field).
+Typically, a user-defined key-value pair at the site or page level, but may also refer to a configuration setting or an [argument](#argument). See also [field](#field).
###### partial
@@ -300,7 +333,7 @@ The host-relative URL of a published resource or a rendered page.
###### render hook
-A [template](#template) that overrides standard markdown rendering. See [details](/templates/render-hooks/).
+A [template](#template) that overrides standard Markdown rendering. See [details](/render-hooks).
###### remote resource
@@ -312,17 +345,24 @@ Any file consumed by the build process to augment or generate content, structure
Hugo supports three types of resources: [global](#global-resource), [page](#page-resource), and [remote](#remote-resource)
+###### resource type
+
+The main type of a resource's [media type]. Content files such as Markdown, HTML, AsciiDoc, Pandoc, reStructuredText, and Emacs Org Mode have resource type `page`. Other resource types include `image`, `video`, etc. Retrieve the resource type using the [`ResourceType`] method on a `Resource` object.
+
+[media type]: /methods/resource/mediatype/
+[`ResourceType`]: /methods/resource/resourcetype/
+
###### scalar
A single value, one of [string](#string), [integer](#integer), [floating point](#floating-point), or [boolean](#boolean).
###### scratch pad
-Conceptually, a [map](#map) with [methods](#method) to set, get, update, and delete values. Attach the data structure to a `Page` object using the [`Scratch`] or [`Store`] methods, or created a locally scoped scratch pad using the [`newScratch`] function.
+Conceptually, a [map](#map) with [methods](#method) to set, get, update, and delete values. Attach the data structure to a `Page` object using the [`Scratch`] or [`Store`] methods, or create a locally scoped scratch pad using the [`newScratch`] function.
-[`Scratch`]: /methods/page/scratch
-[`Store`]: /methods/page/store
-[`newScratch`]: /functions/collections/newscratch
+[`Scratch`]: /methods/page/scratch/
+[`Store`]: /methods/page/store/
+[`newScratch`]: /functions/collections/newscratch/
###### section
@@ -334,7 +374,7 @@ Content with the "section" [page kind](#page-kind). Typically a listing of [regu
###### shortcode
-A [template](#template) called from within markdown, taking zero or more [arguments](#argument). See [details](/content-management/shortcodes/).
+A [template](#template) called from within Markdown, taking zero or more [arguments](#argument). See [details](/content-management/shortcodes/).
###### slice
@@ -344,6 +384,14 @@ A numbered sequence of elements. Unlike Go's [array](#array) data type, slices a
A sequence of bytes. For example, `"What is 6 times 7?"` .
+###### string literal (interpreted)
+
+Interpreted string literals are character sequences between double quotes, as in "foo". Within the quotes, any character may appear except a newline and an unescaped double quote. The text between the quotes forms the value of the literal, with backslash escapes interpreted. See [details](https://go.dev/ref/spec#String_literals).
+
+###### string literal (raw)
+
+Raw string literals are character sequences between backticks, as in \`bar\`. Within the backticks, any character may appear except a backtick. Backslashes have no special meaning and the string may contain newlines. Carriage return characters ('\r') inside raw string literals are discarded from the raw string value. See [details](https://go.dev/ref/spec#String_literals).
+
###### taxonomic weight
Defined in front matter and unique to each taxonomy, this [weight](#weight) determines the sort order of page collections contained within a [taxonomy object](#taxonomy-object). See [details](/templates/taxonomy-templates/#assign-weight).
@@ -394,7 +442,7 @@ To transform a serialized object into a data structure. For example, transformin
###### variable
-A user-defined [identifier](#identifier) prefaced with a `$` symbol, representing a value of any data type, initialized or assigned within a [template action](#template-action). For example, `$foo` and `$bar` are variables.
+A user-defined [identifier](#identifier) prepended with a `$` symbol, representing a value of any data type, initialized or assigned within a [template action](#template-action). For example, `$foo` and `$bar` are variables.
###### walk
@@ -407,3 +455,7 @@ Used to position an element within a collection sorted by weight. Assign weights
###### weighted page
Contained within a [taxonomy object](#taxonomy-object), a weighted page is a [map](#map) with two elements: a `Page` object, and its [taxonomic weight](#taxonomic-weight) as defined in front matter. Access the elements using the `Page` and `Weight` keys.
+
+###### zero time
+
+The _zero time_ is January 1, 0001, 00:00:00 UTC. Formatted per [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) the _zero time_ is 0001-01-01T00:00:00-00:00.
diff --git a/docs/content/en/getting-started/quick-start.md b/docs/content/en/getting-started/quick-start.md
index a6c54b54c41..6e67cb73bce 100644
--- a/docs/content/en/getting-started/quick-start.md
+++ b/docs/content/en/getting-started/quick-start.md
@@ -110,7 +110,7 @@ Press `Ctrl + C` to stop Hugo's development server.
Add a new page to your site.
```text
-hugo new content posts/my-first-post.md
+hugo new content content/posts/my-first-post.md
```
Hugo created the file in the `content/posts` directory. Open the file with your editor.
@@ -125,7 +125,7 @@ draft = true
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].
-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.
[markdown]: https://commonmark.org/help/
@@ -151,8 +151,10 @@ 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.
+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.
[live testing tool]: https://spec.commonmark.org/dingus/
[specification]: https://spec.commonmark.org/
@@ -216,13 +218,13 @@ Hugo's [forum] is an active community of users and developers who answer questio
For other resources to help you learn Hugo, including books and video tutorials, see the [external learning resources](/getting-started/external-learning-resources/) page.
[Ananke]: https://github.com/theNewDynamic/gohugo-theme-ananke
-[directory structure]: /getting-started/directory-structure
+[directory structure]: /getting-started/directory-structure/
[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/
[forum]: https://discourse.gohugo.io/
-[front matter]: /content-management/front-matter
+[front matter]: /content-management/front-matter/
[Git submodule]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
[hosting and deployment]: /hosting-and-deployment/
[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
diff --git a/docs/content/en/getting-started/usage.md b/docs/content/en/getting-started/usage.md
index 268aed2e4f4..b19920907a1 100644
--- a/docs/content/en/getting-started/usage.md
+++ b/docs/content/en/getting-started/usage.md
@@ -23,7 +23,7 @@ hugo version
You should see something like:
```text
-hugo v0.122.0-b9a03bd59d5f71a529acb3e33f995e0ef332b3aa+extended linux/amd64 BuildDate=2024-01-26T15:54:24Z VendorInfo=gohugoio
+hugo v0.123.0-3c8a4713908e48e6523f058ca126710397aa4ed5+extended linux/amd64 BuildDate=2024-02-19T16:32:38Z VendorInfo=gohugoio
```
## Display available commands
@@ -65,6 +65,16 @@ Hugo allows you to set `draft`, `date`, `publishDate`, and `expiryDate` in the [
- The `publishDate` is in the future
- The `expiryDate` is in the past
+{{< new-in 0.123.0 >}}
+
+{{% note %}}
+Hugo publishes descendants of draft, future, and expired [node] pages. To prevent publication of these descendants, use the [`cascade`] front matter field to cascade [build options] to the descendant pages.
+
+[build options]: /content-management/build-options/
+[`cascade`]: /content-management/front-matter/#cascade-field
+[node]: /getting-started/glossary/#node
+{{% /note %}}
+
You can override the default behavior when running `hugo` or `hugo server` with command line flags:
```sh
@@ -130,7 +140,7 @@ public/
├── categories/
│ ├── index.html
│ └── index.xml <-- RSS feed for this section
-├── post/
+├── posts/
│ ├── my-first-post/
│ │ └── index.html
│ ├── index.html
diff --git a/docs/content/en/hosting-and-deployment/_index.md b/docs/content/en/hosting-and-deployment/_index.md
index 35fd3cf057a..b6f54d3fafc 100644
--- a/docs/content/en/hosting-and-deployment/_index.md
+++ b/docs/content/en/hosting-and-deployment/_index.md
@@ -1,12 +1,12 @@
---
title: Hosting and deployment
-linkTitle: Overview
+linkTitle: In this section
description: Site builds, automated deployments, and popular hosting solutions.
categories: []
keywords: []
menu:
docs:
- identifier: hosting-and-deployment-overview
+ identifier: hosting-and-deployment-in-this-section
parent: hosting-and-deployment
weight: 1
weight: 1
diff --git a/docs/content/en/hosting-and-deployment/hosting-on-github/index.md b/docs/content/en/hosting-and-deployment/hosting-on-github/index.md
index c3da5ba3e41..5460193a709 100644
--- a/docs/content/en/hosting-and-deployment/hosting-on-github/index.md
+++ b/docs/content/en/hosting-and-deployment/hosting-on-github/index.md
@@ -1,8 +1,8 @@
---
title: Host on GitHub Pages
-description: Deploy Hugo as a GitHub Pages project or personal/organizational site and automate the whole process with GitHub Actions
+description: Host your site on GitHub Pages with continuous deployment using project, user, or organization pages.
categories: [hosting and deployment]
-keywords: [hosting,github]
+keywords: [hosting]
menu:
docs:
parent: hosting-and-deployment
@@ -10,8 +10,6 @@ toc: true
aliases: [/tutorials/github-pages-blog/]
---
-GitHub provides free and fast static hosting over SSL for personal, organization, or project pages directly from a GitHub repository via its GitHub Pages service and automating development workflows and build with GitHub Actions.
-
## Prerequisites
1. [Create a GitHub account]
@@ -99,7 +97,7 @@ jobs:
build:
runs-on: ubuntu-latest
env:
- HUGO_VERSION: 0.122.0
+ HUGO_VERSION: 0.127.0
steps:
- name: Install Hugo CLI
run: |
@@ -122,13 +120,14 @@ jobs:
# For maximum backward compatibility with Hugo modules
HUGO_ENVIRONMENT: production
HUGO_ENV: production
+ TZ: America/Los_Angeles
run: |
hugo \
--gc \
--minify \
--baseURL "${{ steps.pages.outputs.base_url }}/"
- name: Upload artifact
- uses: actions/upload-pages-artifact@v2
+ uses: actions/upload-pages-artifact@v3
with:
path: ./public
@@ -142,7 +141,7 @@ jobs:
steps:
- name: Deploy to GitHub Pages
id: deployment
- uses: actions/deploy-pages@v3
+ uses: actions/deploy-pages@v4
{{< /code >}}
Step 7
diff --git a/docs/content/en/hosting-and-deployment/hosting-on-gitlab.md b/docs/content/en/hosting-and-deployment/hosting-on-gitlab.md
index 87c764f0087..c628922cdce 100644
--- a/docs/content/en/hosting-and-deployment/hosting-on-gitlab.md
+++ b/docs/content/en/hosting-and-deployment/hosting-on-gitlab.md
@@ -27,8 +27,8 @@ Define your [CI/CD](https://docs.gitlab.com/ee/ci/quick_start/) jobs by creating
{{< code file=.gitlab-ci.yml copy=true >}}
variables:
- DART_SASS_VERSION: 1.70.0
- HUGO_VERSION: 0.122.0
+ DART_SASS_VERSION: 1.77.1
+ HUGO_VERSION: 0.126.0
NODE_VERSION: 20.x
GIT_DEPTH: 0
GIT_STRATEGY: clone
@@ -36,7 +36,7 @@ variables:
TZ: America/Los_Angeles
image:
- name: golang:1.20.6-bookworm
+ name: golang:1.22.1-bookworm
pages:
script:
diff --git a/docs/content/en/hosting-and-deployment/hosting-on-netlify.md b/docs/content/en/hosting-and-deployment/hosting-on-netlify.md
deleted file mode 100644
index 2dcdd95f5c1..00000000000
--- a/docs/content/en/hosting-and-deployment/hosting-on-netlify.md
+++ /dev/null
@@ -1,145 +0,0 @@
----
-title: Host on Netlify
-description: Netlify can host your Hugo site with CDN, continuous deployment, 1-click HTTPS, an admin GUI, and its own CLI.
-categories: [hosting and deployment]
-keywords: [hosting,netlify]
-menu:
- docs:
- parent: hosting-and-deployment
-toc: true
----
-
-[Netlify][netlify] provides continuous deployment services, global CDN, ultra-fast DNS, atomic deploys, instant cache invalidation, one-click SSL, a browser-based interface, a CLI, and many other features for managing your Hugo website.
-
-## Assumptions
-
-* You have an account with GitHub, GitLab, or Bitbucket.
-* You have completed the [Quick Start] or have a Hugo website you are ready to deploy and share with the world.
-* You do not already have a Netlify account.
-
-## Create a Netlify account
-
-Go to [app.netlify.com] and select your preferred sign up method. This will likely be a hosted Git provider, although you also have the option to sign up with an email address.
-
-The following examples use GitHub, but other git providers will follow a similar process.
-
-
-
-Selecting GitHub will bring up an authorization modal for authentication. Select "Authorize application."
-
-
-
-## Create a new site with continuous deployment
-
-You're now already a Netlify member and should be brought to your new dashboard. Select "New site from git."
-
-
-
-Netlify will then start walking you through the steps necessary for continuous deployment. First, you'll need to select your git provider again, but this time you are giving Netlify added permissions to your repositories.
-
-
-
-And then again with the GitHub authorization modal:
-
-
-
-Select the repo you want to use for continuous deployment. If you have a large number of repositories, you can filter through them in real time using repo search:
-
-
-
-Once selected, you'll be brought to a screen for basic setup. Here you can select the branch you want to publish, your [build command], and your publish (i.e. deploy) directory. The publish directory should mirror that of what you've set in your [site configuration], the default of which is `public`. The following steps assume you are publishing from the `master` branch.
-
-## Configure Hugo version in Netlify
-
-You can [set Hugo version](https://www.netlify.com/blog/2017/04/11/netlify-plus-hugo-0.20-and-beyond/) for your environments in `netlify.toml` file or set `HUGO_VERSION` as a build environment variable in the Netlify console.
-
-For production:
-
-{{< code file=netlify.toml >}}
-[context.production.environment]
- HUGO_VERSION = "0.122.0"
-{{< /code >}}
-
-For testing:
-
-{{< code file=netlify.toml >}}
-[context.deploy-preview.environment]
- HUGO_VERSION = "0.122.0"
-{{< /code >}}
-
-The Netlify configuration file can be a little hard to understand and get right for the different environment, and you may get some inspiration and tips from this site's `netlify.toml`:
-
-{{< readfile file=netlify.toml highlight=toml >}}
-
-## Build and deploy site
-
-In the Netlify console, selecting "Deploy site" will immediately take you to a terminal for your build:.
-
-
-
-Once the build is finished---this should only take a few seconds--you should now see a "Hero Card" at the top of your screen letting you know the deployment is successful. The Hero Card is the first element that you see in most pages. It allows you to see a quick summary of the page and gives access to the most common/pertinent actions and information. You'll see that the URL is automatically generated by Netlify. You can update the URL in "Settings."
-
-
-
-
-
-[Visit the live site][visit].
-
-Now every time you push changes to your hosted git repository, Netlify will rebuild and redeploy your site.
-
-See [this blog post](https://www.netlify.com/blog/2017/04/11/netlify-plus-hugo-0.20-and-beyond/) for more details about how Netlify handles Hugo versions.
-
-## Use Hugo themes with Netlify
-
-The `git clone` method for installing themes is not supported by Netlify. If you were to use `git clone`, it would require you to recursively remove the `.git` subdirectory from the theme folder and would therefore prevent compatibility with future versions of the theme.
-
-A *better* approach is to install a theme as a proper git submodule. You can [read the GitHub documentation for submodules][ghsm] or those found on [Git's website][gitsm] for more information, but the command is similar to that of `git clone`:
-
-```txt
-cd themes
-git submodule add https://github.com//
-```
-
-It is recommended to only use stable versions of a theme (if it’s versioned) and always check the changelog. This can be done by checking out a specific release within the theme's directory.
-
-Switch to the theme's directory and list all available versions:
-
-```txt
-cd themes/
-git tag
-# exit with q
-```
-
-You can checkout a specific version as follows:
-
-```txt
-git checkout tags/
-```
-
-You can update a theme to the latest version by executing the following command in the *root* directory of your project:
-
-```txt
-git submodule update --rebase --remote
-```
-
-## Next steps
-
-You now have a live website served over HTTPS, distributed through CDN, and configured for continuous deployment. Dig deeper into the Netlify documentation:
-
-1. [Using a Custom Domain]
-2. [Setting up HTTPS on Custom Domains][httpscustom]
-3. [Redirects and Rewrite Rules]
-
-[app.netlify.com]: https://app.netlify.com
-[build command]: /getting-started/usage/#build-your-site
-[site configuration]: /getting-started/configuration/
-[ghsm]: https://github.com/blog/2104-working-with-submodules
-[gitsm]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
-[httpscustom]: https://www.netlify.com/docs/ssl/
-[hugoversions]: https://github.com/netlify/build-image/blob/master/Dockerfile#L216
-[netlify]: https://www.netlify.com/
-[netlifysignup]: https://app.netlify.com/signup
-[Quick Start]: /getting-started/quick-start/
-[Redirects and Rewrite Rules]: https://www.netlify.com/docs/redirects/
-[Using a Custom Domain]: https://www.netlify.com/docs/custom-domains/
-[visit]: https://hugo-netlify-example.netlify.com
diff --git a/docs/content/en/hosting-and-deployment/hosting-on-netlify/index.md b/docs/content/en/hosting-and-deployment/hosting-on-netlify/index.md
new file mode 100644
index 00000000000..b297bca028b
--- /dev/null
+++ b/docs/content/en/hosting-and-deployment/hosting-on-netlify/index.md
@@ -0,0 +1,129 @@
+---
+title: Host on Netlify
+description: Host your site on Netlify with continuous deployment.
+categories: [hosting and deployment]
+keywords: [hosting]
+menu:
+ docs:
+ parent: hosting-and-deployment
+toc: true
+---
+
+## Prerequisites
+
+1. [Create a Netlify account]
+2. [Install Git]
+3. [Create a Hugo site] and test it locally with `hugo server`
+4. Commit the changes to your local repository
+4. Push the local repository to your [GitHub], [GitLab], or [Bitbucket] account
+
+[Bitbucket]: https://bitbucket.org/product
+[Create a Hugo site]: /getting-started/quick-start/
+[Create a Netlify account]: https://app.netlify.com/signup
+[GitHub]: https://github.com
+[GitLab]: https://about.gitlab.com/
+[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+
+## Procedure
+
+This procedure will enable continuous deployment from a GitHub repository. The procedure is essentially the same if you are using GitLab or Bitbucket.
+
+Step 1
+: Log in to your Netlify account, navigate to the Sites page, press the **Add new site** button, and choose "Import an existing project" from the dropdown menu.
+
+Step 2
+: Select your deployment method.
+
+
+
+Step 3
+: Authorize Netlify to connect with your GitHub account by pressing the **Authorize Netlify** button.
+
+
+
+Step 4
+: Press the **Configure Netlify on GitHub** button.
+
+
+
+Step 5
+: Install the Netlify app by selecting your GitHub account.
+
+
+
+Step 6
+: Press the **Install** button.
+
+
+
+Step 7
+: Click on the site's repository from the list.
+
+
+
+Step 8
+: Set the site name and branch from which to deploy.
+
+
+
+Step 9
+: Define the build settings, press the **Add environment variables** button, then press the **New variable** button.
+
+
+
+Step 10
+: Create a new environment variable named `HUGO_VERSION` and set the value to the [latest version].
+
+[latest version]: https://github.com/gohugoio/hugo/releases/latest
+
+
+
+Step 11
+: Press the "Deploy my new site" button at the bottom of the page.
+
+
+
+Step 12
+: At the bottom of the screen, wait for the deploy to complete, then click on the deploy log entry.
+
+
+
+Step 13
+: Press the **Open production deploy** button to view the live site.
+
+
+
+## Configuration file
+
+In the procedure above we configured our site using the Netlify user interface. Most site owners find it easier to use a configuration file checked into source control.
+
+Create a new file named netlify.toml in the root of your project directory. In its simplest form, the configuration file might look like this:
+
+{{< code file=netlify.toml >}}
+[build.environment]
+HUGO_VERSION = "0.126.0"
+TZ = "America/Los_Angeles"
+
+[build]
+publish = "public"
+command = "hugo --gc --minify"
+{{< /code >}}
+
+If your site requires Dart Sass to transpile Sass to CSS, the configuration file should look something like this:
+
+{{< code file=netlify.toml >}}
+[build.environment]
+HUGO_VERSION = "0.126.0"
+DART_SASS_VERSION = "1.77.1"
+TZ = "America/Los_Angeles"
+
+[build]
+publish = "public"
+command = """\
+ curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
+ tar -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
+ rm dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
+ export PATH=/opt/build/repo/dart-sass:$PATH && \
+ hugo --gc --minify \
+ """
+{{< /code >}}
diff --git a/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-02.png b/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-02.png
new file mode 100644
index 00000000000..31fceff27aa
Binary files /dev/null and b/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-02.png differ
diff --git a/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-03.png b/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-03.png
new file mode 100644
index 00000000000..7b98e0b8f16
Binary files /dev/null and b/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-03.png differ
diff --git a/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-04.png b/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-04.png
new file mode 100644
index 00000000000..31304894b45
Binary files /dev/null and b/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-04.png differ
diff --git a/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-05.png b/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-05.png
new file mode 100644
index 00000000000..6d6eef01dca
Binary files /dev/null and b/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-05.png differ
diff --git a/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-06.png b/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-06.png
new file mode 100644
index 00000000000..1b766a78521
Binary files /dev/null and b/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-06.png differ
diff --git a/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-07.png b/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-07.png
new file mode 100644
index 00000000000..7bb3b6ecad9
Binary files /dev/null and b/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-07.png differ
diff --git a/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-08.png b/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-08.png
new file mode 100644
index 00000000000..df8e9e59f04
Binary files /dev/null and b/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-08.png differ
diff --git a/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-09.png b/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-09.png
new file mode 100644
index 00000000000..3f925accc75
Binary files /dev/null and b/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-09.png differ
diff --git a/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-10.png b/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-10.png
new file mode 100644
index 00000000000..e9196d0ce32
Binary files /dev/null and b/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-10.png differ
diff --git a/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-11.png b/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-11.png
new file mode 100644
index 00000000000..2ac2b08af72
Binary files /dev/null and b/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-11.png differ
diff --git a/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-12.png b/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-12.png
new file mode 100644
index 00000000000..e251305a4ae
Binary files /dev/null and b/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-12.png differ
diff --git a/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-13.png b/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-13.png
new file mode 100644
index 00000000000..f955f636962
Binary files /dev/null and b/docs/content/en/hosting-and-deployment/hosting-on-netlify/netlify-step-13.png differ
diff --git a/docs/content/en/hugo-modules/_index.md b/docs/content/en/hugo-modules/_index.md
index cbff13ad099..01fc21e50ac 100644
--- a/docs/content/en/hugo-modules/_index.md
+++ b/docs/content/en/hugo-modules/_index.md
@@ -1,12 +1,12 @@
---
title: Hugo Modules
-linkTitle: Overview
+linkTitle: In this section
description: How to use Hugo Modules.
categories: []
keywords: []
menu:
docs:
- identifier: hugo-modules-overview
+ identifier: hugo-modules-in-this-section
parent: modules
weight: 10
weight: 10
@@ -20,7 +20,7 @@ You can combine modules in any combination you like, and even mount directories
Hugo Modules are powered by Go Modules. For more information about Go Modules, see:
-- [https://github.com/golang/go/wiki/Modules](https://github.com/golang/go/wiki/Modules)
+- [https://go.dev/wiki/Modules](https://go.dev/wiki/Modules)
- [https://go.dev/blog/using-go-modules](https://go.dev/blog/using-go-modules)
Some example projects:
diff --git a/docs/content/en/hugo-modules/configuration.md b/docs/content/en/hugo-modules/configuration.md
index ce9e97d81fd..3aec4699bf3 100644
--- a/docs/content/en/hugo-modules/configuration.md
+++ b/docs/content/en/hugo-modules/configuration.md
@@ -147,7 +147,7 @@ When you add a mount, the default mount for the concerned target root is ignored
{{< /code-toggle >}}
source
-: The source directory of the mount. For the main project, this can be either project-relative or absolute and even a symbolic link. For other modules it must be project-relative.
+: The source directory of the mount. For the main project, this can be either project-relative or absolute. For other modules it must be project-relative.
target
: Where it should be mounted into Hugo's virtual filesystem. It must start with one of Hugo's component folders: `static`, `content`, `layouts`, `data`, `assets`, `i18n`, or `archetypes`. E.g. `content/blog`.
diff --git a/docs/content/en/hugo-modules/use-modules.md b/docs/content/en/hugo-modules/use-modules.md
index 295ff2061e7..913e4f77566 100644
--- a/docs/content/en/hugo-modules/use-modules.md
+++ b/docs/content/en/hugo-modules/use-modules.md
@@ -21,7 +21,7 @@ toc: true
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.:
```sh
-hugo mod init github.com/gohugoio/myShortcodes
+hugo mod init github.com//
```
Also see the [CLI Doc](/commands/hugo_mod_init/).
diff --git a/docs/content/en/hugo-pipes/_index.md b/docs/content/en/hugo-pipes/_index.md
index edc41b7a2d5..6e4190b8769 100755
--- a/docs/content/en/hugo-pipes/_index.md
+++ b/docs/content/en/hugo-pipes/_index.md
@@ -1,11 +1,11 @@
---
title: Hugo Pipes
-linkTitle: Overview
+linkTitle: In this section
categories: []
keywords: []
menu:
docs:
- identifier: hugo-pipes-overview
+ identifier: hugo-pipes-in-this-section
parent: hugo-pipes
weight: 10
weight: 10
diff --git a/docs/content/en/hugo-pipes/js.md b/docs/content/en/hugo-pipes/js.md
index 8a2e2f40e75..ddde8313ae7 100644
--- a/docs/content/en/hugo-pipes/js.md
+++ b/docs/content/en/hugo-pipes/js.md
@@ -17,7 +17,7 @@ action:
## Usage
-Any JavaScript resource file can be transpiled and "tree shaken" using `js.Build` which takes for argument either a string for the filepath or a dict of options listed below.
+Any JavaScript resource file can be transpiled and "tree shaken" using `js.Build` which takes for argument either a string for the file path or a dict of options listed below.
### Options
@@ -25,7 +25,7 @@ targetPath
: (`string`) If not set, the source path will be used as the base target path.
Note that the target path's extension may change if the target MIME type is different, e.g. when the source is TypeScript.
-params {{< new-in "0.96.0" >}}
+params
: (`map` or `slice`) Params that can be imported as JSON in your JS files, e.g.:
```go-html-template
diff --git a/docs/content/en/hugo-pipes/transpile-sass-to-css.md b/docs/content/en/hugo-pipes/transpile-sass-to-css.md
index 998adad82c1..ba5c3996602 100644
--- a/docs/content/en/hugo-pipes/transpile-sass-to-css.md
+++ b/docs/content/en/hugo-pipes/transpile-sass-to-css.md
@@ -43,7 +43,7 @@ targetPath
: (`string`) If not set, the transformed resource's target path will be the original path of the asset file with its extension replaced by `.css`.
vars {{< new-in 0.109.0 >}}
-: (`map`) A map of key/value pairs that will be available in the `hugo:vars` namespace. Useful for [initializing Sass variables from Hugo templates](https://discourse.gohugo.io/t/42053/).
+: (`map`) A map of key-value pairs that will be available in the `hugo:vars` namespace. Useful for [initializing Sass variables from Hugo templates](https://discourse.gohugo.io/t/42053/).
```scss
// LibSass
@@ -136,8 +136,8 @@ To install Dart Sass for your builds on GitLab Pages, the `.gitlab-ci.yml` file
```yaml
variables:
- HUGO_VERSION: 0.122.0
- DART_SASS_VERSION: 1.70.0
+ HUGO_VERSION: 0.126.0
+ DART_SASS_VERSION: 1.77.1
GIT_DEPTH: 0
GIT_STRATEGY: clone
GIT_SUBMODULE_STRATEGY: recursive
@@ -171,7 +171,7 @@ To install Dart Sass for your builds on Netlify, the `netlify.toml` file should
```toml
[build.environment]
HUGO_VERSION = "0.122.2"
-DART_SASS_VERSION = "1.70.0"
+DART_SASS_VERSION = "1.77.1"
TZ = "America/Los_Angeles"
[build]
diff --git a/docs/content/en/installation/_common/03-prebuilt-binaries.md b/docs/content/en/installation/_common/03-prebuilt-binaries.md
index d3465fa5d07..55f7cb85bd0 100644
--- a/docs/content/en/installation/_common/03-prebuilt-binaries.md
+++ b/docs/content/en/installation/_common/03-prebuilt-binaries.md
@@ -16,7 +16,7 @@ Please consult your operating system documentation if you need help setting file
If you do not see a prebuilt binary for the desired edition, operating system, and architecture, install Hugo using one of the methods described below.
-[commit information]: /variables/git
+[commit information]: /methods/page/gitinfo/
[Git]: https://git-scm.com/
[Go]: https://go.dev/
[Hugo Modules]: /hugo-modules/
diff --git a/docs/content/en/installation/_common/_index.md b/docs/content/en/installation/_common/_index.md
index 47d5812fba5..4328d4d145b 100644
--- a/docs/content/en/installation/_common/_index.md
+++ b/docs/content/en/installation/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
diff --git a/docs/content/en/installation/_index.md b/docs/content/en/installation/_index.md
index ca405b755ea..7e445a07d98 100644
--- a/docs/content/en/installation/_index.md
+++ b/docs/content/en/installation/_index.md
@@ -1,13 +1,13 @@
---
title: Installation
-linkTitle: Overview
+linkTitle: In this section
description: Install Hugo on macOS, Linux, Windows, BSD, and on any machine that can run the Go compiler tool chain.
aliases: [/getting-started/installing/]
categories: []
keywords: []
menu:
docs:
- identifier: installation-overview
+ identifier: installation-in-this-section
parent: installation
weight: 10
weight: 10
diff --git a/docs/content/en/installation/linux.md b/docs/content/en/installation/linux.md
index 7b75f149b3e..769011212f5 100644
--- a/docs/content/en/installation/linux.md
+++ b/docs/content/en/installation/linux.md
@@ -96,6 +96,7 @@ sudo apt install hugo
You can also download Debian packages from the [latest release] page.
[Debian]: https://www.debian.org/
+[Exherbo]: https://www.exherbolinux.org/
[elementary OS]: https://elementary.io/
[KDE neon]: https://neon.kde.org/
[Linux Lite]: https://www.linuxliteos.com/
@@ -105,6 +106,24 @@ You can also download Debian packages from the [latest release] page.
[Ubuntu]: https://ubuntu.com/
[Zorin OS]: https://zorin.com/os/
+### Exherbo
+
+To install the extended edition of Hugo on [Exherbo]:
+
+1. Add this line to /etc/paludis/options.conf:
+
+ ```text
+ www-apps/hugo extended
+ ```
+
+2. Install using the Paludis package manager:
+
+
+ ```sh
+ cave resolve -x repository/heirecka
+ cave resolve -x hugo
+ ```
+
### Fedora
Derivatives of the [Fedora] distribution of Linux include [CentOS], [Red Hat Enterprise Linux], and others. To install the extended edition of Hugo:
@@ -119,7 +138,7 @@ sudo dnf install hugo
### Gentoo
-Derivatives of the [Gentoo] distribution of Linux include [Calculate Linux], [Funtoo], and others. Follow the instructions below to install the extended edition of Hugo:
+Derivatives of the [Gentoo] distribution of Linux include [Calculate Linux], [Funtoo], and others. To install the extended edition of Hugo:
1. Specify the `extended` [USE] flag in /etc/portage/package.use/hugo:
diff --git a/docs/content/en/methods/_common/_index.md b/docs/content/en/methods/_common/_index.md
index 47d5812fba5..4328d4d145b 100644
--- a/docs/content/en/methods/_common/_index.md
+++ b/docs/content/en/methods/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
diff --git a/docs/content/en/methods/_common/next-prev-on-page-vs-next-prev-on-pages.md b/docs/content/en/methods/_common/next-prev-on-page-vs-next-prev-on-pages.md
index 4ae3a0f399a..f6503787844 100644
--- a/docs/content/en/methods/_common/next-prev-on-page-vs-next-prev-on-pages.md
+++ b/docs/content/en/methods/_common/next-prev-on-page-vs-next-prev-on-pages.md
@@ -9,10 +9,10 @@ The `Next` and `Prev` methods on a `Pages` object are more flexible than the `Ne
[`PAGES.Next`] and [`PAGES.Prev`]|locally defined|✔️
[`PAGE.Next`] and [`PAGE.Prev`]|globally defined|❌
-[`PAGES.Next`]: /methods/pages/next
-[`PAGES.Prev`]: /methods/pages/prev
-[`PAGE.Next`]: /methods/page/next
-[`PAGE.Prev`]: /methods/page/prev
+[`PAGES.Next`]: /methods/pages/next/
+[`PAGES.Prev`]: /methods/pages/prev/
+[`PAGE.Next`]: /methods/page/next/
+[`PAGE.Prev`]: /methods/page/prev/
locally defined
: Build the page collection every time you call `PAGES.Next` and `PAGES.Prev`. Navigation between pages is relative to the current page's position within the local collection, independent of the global collection.
@@ -31,7 +31,7 @@ With a global collection, the navigation sort order is fixed, using Hugo's defau
For example, with a global collection sorted by title, the navigation sort order will use Hugo's default sort order. This is probably not what you want or expect. For this reason, the `Next` and `Prev` methods on a `Pages` object are generally a better choice.
-[date]: /methods/page/date
-[weight]: /methods/page/weight
-[linkTitle]: /methods/page/linktitle
-[title]: /methods/page/title
+[date]: /methods/page/date/
+[weight]: /methods/page/weight/
+[linkTitle]: /methods/page/linktitle/
+[title]: /methods/page/title/
diff --git a/docs/content/en/methods/_index.md b/docs/content/en/methods/_index.md
index c12bd9d4d4a..bab637ddba6 100644
--- a/docs/content/en/methods/_index.md
+++ b/docs/content/en/methods/_index.md
@@ -1,16 +1,17 @@
---
title: Methods
-linkTitle: Overview
+linkTitle: In this section
description: A list of Hugo template methods including examples.
categories: []
keywords: []
menu:
docs:
- identifier: methods-overview
+ identifier: methods-in-this-section
parent: methods
weight: 10
weight: 10
showSectionMenu: true
+aliases: ['/variables/']
---
Use these methods within your templates.
diff --git a/docs/content/en/methods/menu-entry/KeyName.md b/docs/content/en/methods/menu-entry/KeyName.md
index 4b43596b055..409cb31d646 100644
--- a/docs/content/en/methods/menu-entry/KeyName.md
+++ b/docs/content/en/methods/menu-entry/KeyName.md
@@ -36,4 +36,4 @@ This example uses the `KeyName` method when querying the translation table on a
In the example above, we need to pass the value returned by `.KeyName` through the [`lower`] function because the keys in the translation table are lowercase.
-[`lower`]: functions/strings/tolower
+[`lower`]: /functions/strings/tolower/
diff --git a/docs/content/en/methods/menu-entry/Menu.md b/docs/content/en/methods/menu-entry/Menu.md
index 6827519bd96..63f148c1a3f 100644
--- a/docs/content/en/methods/menu-entry/Menu.md
+++ b/docs/content/en/methods/menu-entry/Menu.md
@@ -19,6 +19,6 @@ action:
Use this method with the [`IsMenuCurrent`] and [`HasMenuCurrent`] methods on a `Page` object to set "active" and "ancestor" classes on a rendered entry. See [this example].
-[`HasMenuCurrent`]: /methods/page/hasmenucurrent
-[`IsMenuCurrent`]: /methods/page/ismenucurrent
+[`HasMenuCurrent`]: /methods/page/hasmenucurrent/
+[`IsMenuCurrent`]: /methods/page/ismenucurrent/
[this example]: /templates/menu-templates/#example
diff --git a/docs/content/en/methods/menu-entry/Name.md b/docs/content/en/methods/menu-entry/Name.md
index d722da07cd6..d77c65cb55d 100644
--- a/docs/content/en/methods/menu-entry/Name.md
+++ b/docs/content/en/methods/menu-entry/Name.md
@@ -13,8 +13,8 @@ If you define the menu entry [automatically], the `Name` method returns the page
If you define the menu entry [in front matter] or [in site configuration], the `Name` method returns the `name` property, falling back to the page’s `LinkTitle`, then to its `Title`.
-[`LinkTitle`]: /methods/page/linktitle
-[`Title`]: /methods/page/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
diff --git a/docs/content/en/methods/menu-entry/Page.md b/docs/content/en/methods/menu-entry/Page.md
index b75e4af5522..bd8c1625ec5 100644
--- a/docs/content/en/methods/menu-entry/Page.md
+++ b/docs/content/en/methods/menu-entry/Page.md
@@ -46,8 +46,8 @@ If the entry is not associated with a page, we use its `url` and `name` properti
See the [menu templates] section for more information.
-[`LinkTitle`]: /methods/page/linktitle
-[`RelPermalink`]: /methods/page/relpermalink
+[`LinkTitle`]: /methods/page/linktitle/
+[`RelPermalink`]: /methods/page/relpermalink/
[define menu entries]: /content-management/menus/
[menu templates]: /templates/menu-templates/#page-references
-[methods]: /methods/page
+[methods]: /methods/page/
diff --git a/docs/content/en/methods/menu-entry/Title.md b/docs/content/en/methods/menu-entry/Title.md
index c1eec2cc05f..4082e4e9353 100644
--- a/docs/content/en/methods/menu-entry/Title.md
+++ b/docs/content/en/methods/menu-entry/Title.md
@@ -11,10 +11,10 @@ action:
If you define the menu entry [automatically], the `Title` 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 `title` property, falling back to the page’s `LinkTitle`, then to its `Title`.
+If you define the menu entry [in front matter] or [in site configuration], the `Title` method returns the `title` property, falling back to the page’s `LinkTitle`, then to its `Title`.
-[`LinkTitle`]: /methods/page/linktitle
-[`Title`]: /methods/page/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
diff --git a/docs/content/en/methods/menu-entry/URL.md b/docs/content/en/methods/menu-entry/URL.md
index c2b314b580c..bf3ec044aaf 100644
--- a/docs/content/en/methods/menu-entry/URL.md
+++ b/docs/content/en/methods/menu-entry/URL.md
@@ -20,4 +20,4 @@ For menu entries associated with a page, the `URL` method returns the page's [`R
```
-[`RelPermalink`]: /methods/page/relpermalink
+[`RelPermalink`]: /methods/page/relpermalink/
diff --git a/docs/content/en/methods/menu-entry/Weight.md b/docs/content/en/methods/menu-entry/Weight.md
index 7b0c24ae880..eab9357368c 100644
--- a/docs/content/en/methods/menu-entry/Weight.md
+++ b/docs/content/en/methods/menu-entry/Weight.md
@@ -13,7 +13,7 @@ If you define the menu entry [automatically], the `Weight` method returns the pa
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
+[`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
diff --git a/docs/content/en/methods/menu-entry/_common/_index.md b/docs/content/en/methods/menu-entry/_common/_index.md
index 47d5812fba5..4328d4d145b 100644
--- a/docs/content/en/methods/menu-entry/_common/_index.md
+++ b/docs/content/en/methods/menu-entry/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
diff --git a/docs/content/en/methods/menu/ByName.md b/docs/content/en/methods/menu/ByName.md
index 04f25c22d4b..2e28016b6a1 100644
--- a/docs/content/en/methods/menu/ByName.md
+++ b/docs/content/en/methods/menu/ByName.md
@@ -62,4 +62,4 @@ You can also sort menu entries using the [`sort`] function. For example, to sort
When using the sort function with menu entries, specify any of the following keys: `Identifier`, `Name`, `Parent`, `Post`, `Pre`, `Title`, `URL`, or `Weight`.
-[`sort`]: /functions/collections/sort
+[`sort`]: /functions/collections/sort/
diff --git a/docs/content/en/methods/menu/ByWeight.md b/docs/content/en/methods/menu/ByWeight.md
index d5cb0444b60..3774619bee0 100644
--- a/docs/content/en/methods/menu/ByWeight.md
+++ b/docs/content/en/methods/menu/ByWeight.md
@@ -73,4 +73,4 @@ You can also sort menu entries using the [`sort`] function. For example, to sort
When using the sort function with menu entries, specify any of the following keys: `Identifier`, `Name`, `Parent`, `Post`, `Pre`, `Title`, `URL`, or `Weight`.
-[`sort`]: /functions/collections/sort
+[`sort`]: /functions/collections/sort/
diff --git a/docs/content/en/methods/page/AllTranslations.md b/docs/content/en/methods/page/AllTranslations.md
index b8cc651792a..51d82d4f945 100644
--- a/docs/content/en/methods/page/AllTranslations.md
+++ b/docs/content/en/methods/page/AllTranslations.md
@@ -1,6 +1,6 @@
---
title: AllTranslations
-description: Returns all translation of the given page, including the given page.
+description: Returns all translations of the given page, including the current language.
categories: []
keywords: []
action:
@@ -63,9 +63,9 @@ And this template:
{{ with .AllTranslations }}
{{ range . }}
- {{ $langName := or .Language.LanguageName .Language.Lang }}
- {{ $langCode := or .Language.LanguageCode .Language.Lang }}
-
{{ end }}
diff --git a/docs/content/en/methods/page/BundleType.md b/docs/content/en/methods/page/BundleType.md
index 77d1d72eb33..5254757eeff 100644
--- a/docs/content/en/methods/page/BundleType.md
+++ b/docs/content/en/methods/page/BundleType.md
@@ -5,7 +5,7 @@ categories: []
keywords: []
action:
related: []
- returnType: files.ContentClass
+ returnType: string
signatures: [PAGE.BundleType]
---
diff --git a/docs/content/en/methods/page/CodeOwners.md b/docs/content/en/methods/page/CodeOwners.md
index 068c4591fea..c0baf26ad9d 100644
--- a/docs/content/en/methods/page/CodeOwners.md
+++ b/docs/content/en/methods/page/CodeOwners.md
@@ -63,4 +63,4 @@ Render the code owners for each content page:
Combine this method with [`resources.GetRemote`] to retrieve names and avatars from your Git provider by querying their API.
-[`resources.GetRemote`]: functions/resources/getremote
+[`resources.GetRemote`]: /functions/resources/getremote/
diff --git a/docs/content/en/methods/page/Content.md b/docs/content/en/methods/page/Content.md
index 40a057f0263..a9d38367c15 100644
--- a/docs/content/en/methods/page/Content.md
+++ b/docs/content/en/methods/page/Content.md
@@ -13,7 +13,7 @@ action:
signatures: [PAGE.Content]
---
-The `Content` method on a `Page` object renders markdown and shortcodes to HTML. The content does not include front matter.
+The `Content` method on a `Page` object renders Markdown and shortcodes to HTML. The content does not include front matter.
[shortcodes]: /getting-started/glossary/#shortcode
diff --git a/docs/content/en/methods/page/Data.md b/docs/content/en/methods/page/Data.md
index 4eccde6ff44..aea1042d450 100644
--- a/docs/content/en/methods/page/Data.md
+++ b/docs/content/en/methods/page/Data.md
@@ -74,7 +74,7 @@ Terms
{{% note %}}
Once you have captured the taxonomy object, use any of the [taxonomy methods] to sort, count, or capture a subset of its weighted pages.
-[taxonomy methods]: /methods/taxonomy
+[taxonomy methods]: /methods/taxonomy/
{{% /note %}}
Learn more about [taxonomy templates].
diff --git a/docs/content/en/methods/page/Date.md b/docs/content/en/methods/page/Date.md
index 83192f94cbb..113d6ca090a 100644
--- a/docs/content/en/methods/page/Date.md
+++ b/docs/content/en/methods/page/Date.md
@@ -33,7 +33,7 @@ The date is a [time.Time] value. Format and localize the value with the [`time.F
In the example above we explicitly set the date in front matter. With Hugo's default configuration, the `Date` method returns the front matter value. This behavior is configurable, allowing you to set fallback values if the date is not defined in front matter. See [details].
-[`time.Format`]: /functions/time/format
+[`time.Format`]: /functions/time/format/
[details]: /getting-started/configuration/#configure-dates
-[time methods]: /methods/time
+[time methods]: /methods/time/
[time.Time]: https://pkg.go.dev/time#Time
diff --git a/docs/content/en/methods/page/Description.md b/docs/content/en/methods/page/Description.md
index fbb43b8b53f..67171fe013a 100644
--- a/docs/content/en/methods/page/Description.md
+++ b/docs/content/en/methods/page/Description.md
@@ -10,7 +10,7 @@ action:
signatures: [PAGE.Description]
---
-Conceptually different that a [content summary], a page description is typically used in metadata about the page.
+Conceptually different from a [content summary], a page description is typically used in metadata about the page.
{{< code-toggle file=content/recipes/sushi.md fm=true >}}
title = 'How to make spicy tuna hand rolls'
@@ -25,4 +25,4 @@ description = 'Instructions for making spicy tuna hand rolls.'
{{< /code >}}
-[content summary]: /content-management/summaries
+[content summary]: /content-management/summaries/
diff --git a/docs/content/en/methods/page/ExpiryDate.md b/docs/content/en/methods/page/ExpiryDate.md
index 353546449a3..9b95ebc654d 100644
--- a/docs/content/en/methods/page/ExpiryDate.md
+++ b/docs/content/en/methods/page/ExpiryDate.md
@@ -29,7 +29,7 @@ The expiry date is a [time.Time] value. Format and localize the value with the [
In the example above we explicitly set the expiry date in front matter. With Hugo's default configuration, the `ExpiryDate` method returns the front matter value. This behavior is configurable, allowing you to set fallback values if the expiry date is not defined in front matter. See [details].
-[`time.Format`]: /functions/time/format
+[`time.Format`]: /functions/time/format/
[details]: /getting-started/configuration/#configure-dates
-[time methods]: /methods/time
+[time methods]: /methods/time/
[time.Time]: https://pkg.go.dev/time#Time
diff --git a/docs/content/en/methods/page/File.md b/docs/content/en/methods/page/File.md
index 44b752215ef..d5917157715 100644
--- a/docs/content/en/methods/page/File.md
+++ b/docs/content/en/methods/page/File.md
@@ -22,7 +22,9 @@ content/
└── book-2.md
```
-Code defensively by verifying file existence as shown in each of the examples below.
+{{% note %}}
+Code defensively by verifying file existence as shown in the examples below.
+{{% /note %}}
## Methods
@@ -80,13 +82,17 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend
{{ end }}
```
-###### Lang
+###### IsContentAdapter
+
+{{< new-in 0.126.0 >}}
+
+(`bool`) Reports whether the file is a [content adapter].
-(`string`) The language associated with the given file.
+[content adapter]: /content-management/content-adapters/
```go-html-template
{{ with .File }}
- {{ .Lang }}
+ {{ .IsContentAdapter }}
{{ end }}
```
@@ -110,6 +116,16 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend
{{ end }}
```
+###### Section
+
+(`string`) The name of the top level section in which the file resides.
+
+```go-html-template
+{{ with .File }}
+ {{ .Section }}
+{{ end }}
+```
+
###### TranslationBaseName
(`string`) The file name, excluding the extension and language identifier.
@@ -157,9 +173,10 @@ ContentBaseName|a|b|news
Dir|news/|news/b/|news/
Ext|md|md|md
Filename|/home/user/...|/home/user/...|/home/user/...
-Lang|en|en|en
+IsContentAdapter|false|false|false
LogicalName|a.en.md|index.en.md|_index.en.md
Path|news/a.en.md|news/b/index.en.md|news/_index.en.md
+Section|news|news|news
TranslationBaseName|a|index|_index
UniqueID|15be14b...|186868f...|7d9159d...
@@ -171,13 +188,7 @@ Some of the pages on a site may not be backed by a file. For example:
- Taxonomy pages
- Term pages
-Without a backing file, Hugo will throw a warning if you attempt to access a `.File` property. For example:
-
-```text
-WARN .File.ContentBaseName on zero object. Wrap it in if or with...
-```
-
-To code defensively, first check for file existence:
+Without a backing file, Hugo will throw an error if you attempt to access a `.File` property. To code defensively, first check for file existence:
```go-html-template
{{ with .File }}
diff --git a/docs/content/en/methods/page/Fragments.md b/docs/content/en/methods/page/Fragments.md
index 89f82d2ce12..7bcad1ef922 100644
--- a/docs/content/en/methods/page/Fragments.md
+++ b/docs/content/en/methods/page/Fragments.md
@@ -21,7 +21,7 @@ In a URL, whether absolute or relative, the [fragment] links to an `id` attribut
path fragment
```
-Hugo assigns an `id` attribute to each markdown [ATX] and [setext] heading within the page content. You can override the `id` with a [markdown attribute] as needed. This creates the relationship between an entry in the [table of contents] (TOC) and a heading on the page.
+Hugo assigns an `id` attribute to each Markdown [ATX] and [setext] heading within the page content. You can override the `id` with a [Markdown attribute] as needed. This creates the relationship between an entry in the [table of contents] (TOC) and a heading on the page.
Use the `Fragments` method on a `Page` object to create a table of contents with the `Fragments.ToHTML` method, or by [walking] the `Fragments.Map` data structure.
@@ -31,21 +31,21 @@ Headings
: (`map`) A nested map of all headings on the page. Each map contains the following keys: `ID`, `Level`, `Title` and `Headings`. To inspect the data structure:
```go-html-template
-
```
HeadingsMap
: (`slice`) A slice of maps of all headings on the page, with first-level keys for each heading. Each map contains the following keys: `ID`, `Level`, `Title` and `Headings`. To inspect the data structure:
```go-html-template
-
```
Identifiers.Contains ID
@@ -100,7 +100,7 @@ When using the `Fragments` methods within a shortcode, call the shortcode using
[fragment]: /getting-started/glossary/#fragment
[markdown attribute]: /getting-started/glossary/#markdown-attribute
[setext]: https://spec.commonmark.org/0.30/#setext-headings
-[table of contents]: /methods/page/tableofcontents
+[table of contents]: /methods/page/tableofcontents/
[walking]: /getting-started/glossary/#walk
-[`tableofcontents`]: /methods/page/tableofcontents
+[`tableofcontents`]: /methods/page/tableofcontents/
[render hook]: /getting-started/glossary/#render-hook
diff --git a/docs/content/en/methods/page/FuzzyWordCount.md b/docs/content/en/methods/page/FuzzyWordCount.md
index 600ad48d50e..8523edf8cf4 100644
--- a/docs/content/en/methods/page/FuzzyWordCount.md
+++ b/docs/content/en/methods/page/FuzzyWordCount.md
@@ -17,4 +17,4 @@ action:
To get the exact word count, use the [`WordCount`] method.
-[`WordCount`]: /methods/page/wordcount
+[`WordCount`]: /methods/page/wordcount/
diff --git a/docs/content/en/methods/page/GetPage.md b/docs/content/en/methods/page/GetPage.md
index b1f192d583c..9b4ced345bc 100644
--- a/docs/content/en/methods/page/GetPage.md
+++ b/docs/content/en/methods/page/GetPage.md
@@ -13,7 +13,7 @@ aliases: [/functions/getpage]
The `GetPage` method is also available on a `Site` object. See [details].
-[details]: /methods/site/getpage
+[details]: /methods/site/getpage/
When using the `GetPage` method on the `Page` object, specify a path relative to the current directory or relative to the content directory.
@@ -36,7 +36,7 @@ content/
└── _index.md
```
-The examples below depict the result of rendering works/paintings/the-mona-list.md with a single page template:
+The examples below depict the result of rendering works/paintings/the-mona-lisa.md with a single page template:
```go-html-template
{{ with .GetPage "starry-night" }}
diff --git a/docs/content/en/methods/page/HeadingsFiltered.md b/docs/content/en/methods/page/HeadingsFiltered.md
index a39c48da1ff..d741b57cefb 100644
--- a/docs/content/en/methods/page/HeadingsFiltered.md
+++ b/docs/content/en/methods/page/HeadingsFiltered.md
@@ -14,5 +14,5 @@ action:
Use in conjunction with the [`Related`] method on a [`Pages`] object. See [details].
[`Pages`]: /methods/pages/
-[`Related`]: /methods/pages/related
+[`Related`]: /methods/pages/related/
[details]: /content-management/related/#index-content-headings-in-related-content
diff --git a/docs/content/en/methods/page/InSection.md b/docs/content/en/methods/page/InSection.md
index b98fbc808c5..41ce918f388 100644
--- a/docs/content/en/methods/page/InSection.md
+++ b/docs/content/en/methods/page/InSection.md
@@ -98,5 +98,5 @@ Gaining a thorough understanding of context is critical for anyone writing templ
{{% /note %}}
[context]: /getting-started/glossary/#context
-[`with`]: /functions/go-template/with
-[`else`]: /functions/go-template/else
+[`with`]: /functions/go-template/with/
+[`else`]: /functions/go-template/else/
diff --git a/docs/content/en/methods/page/IsAncestor.md b/docs/content/en/methods/page/IsAncestor.md
index ca23c0868cc..8ace8463c46 100644
--- a/docs/content/en/methods/page/IsAncestor.md
+++ b/docs/content/en/methods/page/IsAncestor.md
@@ -1,6 +1,6 @@
---
title: IsAncestor
-description: Reports whether PAGE1 in an ancestor of PAGE2.
+description: Reports whether PAGE1 is an ancestor of PAGE2.
categories: []
keywords: []
action:
@@ -96,5 +96,5 @@ Gaining a thorough understanding of context is critical for anyone writing templ
{{% /note %}}
[context]: /getting-started/glossary/#context
-[`with`]: /functions/go-template/with
-[`else`]: /functions/go-template/else
+[`with`]: /functions/go-template/with/
+[`else`]: /functions/go-template/else/
diff --git a/docs/content/en/methods/page/IsDescendant.md b/docs/content/en/methods/page/IsDescendant.md
index f1042564e40..2c0599d915e 100644
--- a/docs/content/en/methods/page/IsDescendant.md
+++ b/docs/content/en/methods/page/IsDescendant.md
@@ -1,6 +1,6 @@
---
title: IsDescendant
-description: Reports whether PAGE1 in a descendant of PAGE2.
+description: Reports whether PAGE1 is a descendant of PAGE2.
categories: []
keywords: []
action:
@@ -95,5 +95,5 @@ Gaining a thorough understanding of context is critical for anyone writing templ
{{% /note %}}
[context]: /getting-started/glossary/#context
-[`with`]: /functions/go-template/with
-[`else`]: /functions/go-template/else
+[`with`]: /functions/go-template/with/
+[`else`]: /functions/go-template/else/
diff --git a/docs/content/en/methods/page/Keywords.md b/docs/content/en/methods/page/Keywords.md
index 5ad37ce51e6..ef68c27f598 100644
--- a/docs/content/en/methods/page/Keywords.md
+++ b/docs/content/en/methods/page/Keywords.md
@@ -11,7 +11,7 @@ action:
By default, Hugo evaluates the keywords when creating collections of [related content].
-[related content]: /content-management/related
+[related content]: /content-management/related/
{{< code-toggle file=content/recipes/sushi.md fm=true >}}
title = 'How to make spicy tuna hand rolls'
@@ -32,7 +32,7 @@ Or use the [delimit] function:
{{ delimit .Keywords ", " ", and " }} → tuna, sriracha, nori, and rice
```
-[delimit]: /functions/collections/delimit
+[delimit]: /functions/collections/delimit/
Keywords are also a useful [taxonomy]:
@@ -43,4 +43,4 @@ keyword = 'keywords'
category = 'categories'
{{< /code-toggle >}}
-[taxonomy]: /content-management/taxonomies
+[taxonomy]: /content-management/taxonomies/
diff --git a/docs/content/en/methods/page/Language.md b/docs/content/en/methods/page/Language.md
index 4e65107da0c..321b44e561f 100644
--- a/docs/content/en/methods/page/Language.md
+++ b/docs/content/en/methods/page/Language.md
@@ -34,7 +34,7 @@ Lang
```
LanguageCode
-: (`string`) The language code from the site configuration.
+: (`string`) The language code from the site configuration. Falls back to `Lang` if not defined.
```go-html-template
{{ .Language.LanguageCode }} → de-DE
@@ -61,5 +61,5 @@ Weight
{{ .Language.Weight }} → 2
```
-[details]: /methods/site/language
+[details]: /methods/site/language/
[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
diff --git a/docs/content/en/methods/page/Lastmod.md b/docs/content/en/methods/page/Lastmod.md
index c1692233d4b..78760d55680 100644
--- a/docs/content/en/methods/page/Lastmod.md
+++ b/docs/content/en/methods/page/Lastmod.md
@@ -33,8 +33,8 @@ In the example above we explicitly set the last modification date in front matte
Learn more about [date configuration].
-[`gitinfo`]: /methods/page/gitinfo
-[`time.format`]: /functions/time/format
+[`gitinfo`]: /methods/page/gitinfo/
+[`time.format`]: /functions/time/format/
[date configuration]: /getting-started/configuration/#configure-dates
-[time methods]: /methods/time
+[time methods]: /methods/time/
[time.time]: https://pkg.go.dev/time#time
diff --git a/docs/content/en/methods/page/LinkTitle.md b/docs/content/en/methods/page/LinkTitle.md
index 746e433bb80..0ce32e64160 100644
--- a/docs/content/en/methods/page/LinkTitle.md
+++ b/docs/content/en/methods/page/LinkTitle.md
@@ -12,7 +12,7 @@ action:
The `LinkTitle` method returns the `linkTitle` field as defined in front matter, falling back to the value returned by the [`Title`] method.
-[`Title`]: /methods/page/title
+[`Title`]: /methods/page/title/
{{< code-toggle file=content/articles/healthy-desserts.md fm=true >}}
title = 'Seventeen delightful recipes for healthy desserts'
diff --git a/docs/content/en/methods/page/NextInSection.md b/docs/content/en/methods/page/NextInSection.md
index 73f82d754a1..59a35d03dcb 100644
--- a/docs/content/en/methods/page/NextInSection.md
+++ b/docs/content/en/methods/page/NextInSection.md
@@ -65,7 +65,7 @@ With the `PrevInSection` and `NextInSection` methods, the navigation sort order
For example, with a page collection sorted by title, the navigation sort order will use Hugo’s default sort order. This is probably not what you want or expect. For this reason, the Next and Prev methods on a Pages object are generally a better choice.
-[date]: /methods/page/date
-[weight]: /methods/page/weight
-[linkTitle]: /methods/page/linktitle
-[title]: /methods/page/title
+[date]: /methods/page/date/
+[weight]: /methods/page/weight/
+[linkTitle]: /methods/page/linktitle/
+[title]: /methods/page/title/
diff --git a/docs/content/en/methods/page/Pages.md b/docs/content/en/methods/page/Pages.md
index 2f329eeec6b..d446292e2fc 100644
--- a/docs/content/en/methods/page/Pages.md
+++ b/docs/content/en/methods/page/Pages.md
@@ -75,7 +75,7 @@ In the last example, the collection includes pages in the resources subdirectory
{{% note %}}
When used with a `Site` object, the `Pages` method recursively returns all pages within the site. See [details].
-[details]: /methods/site/pages
+[details]: /methods/site/pages/
{{% /note %}}
```go-html-template
diff --git a/docs/content/en/methods/page/Paginator.md b/docs/content/en/methods/page/Paginator.md
index b1540286ad5..b411e6ec077 100644
--- a/docs/content/en/methods/page/Paginator.md
+++ b/docs/content/en/methods/page/Paginator.md
@@ -28,7 +28,7 @@ Although simple to invoke, with the `Paginator` method you can neither filter no
The [`Paginate`] method is more flexible, and strongly recommended.
-[`paginate`]: /methods/page/paginate
+[`paginate`]: /methods/page/paginate/
{{% /note %}}
{{% note %}}
diff --git a/docs/content/en/methods/page/Param.md b/docs/content/en/methods/page/Param.md
index b2932d98102..daf09a5b4f0 100644
--- a/docs/content/en/methods/page/Param.md
+++ b/docs/content/en/methods/page/Param.md
@@ -29,6 +29,7 @@ Content:
title = 'Example'
date = 2023-01-01
draft = false
+[params]
display_toc = false
{{< /code-toggle >}}
diff --git a/docs/content/en/methods/page/Params.md b/docs/content/en/methods/page/Params.md
index 13416ada74f..219b5de9d7b 100644
--- a/docs/content/en/methods/page/Params.md
+++ b/docs/content/en/methods/page/Params.md
@@ -17,8 +17,9 @@ With this front matter:
{{< code-toggle file=content/news/annual-conference.md >}}
title = 'Annual conference'
date = 2023-10-17T15:11:37-07:00
+[params]
display_related = true
-[author]
+[params.author]
email = 'jsmith@example.org'
name = 'John Smith'
{{< /code-toggle >}}
@@ -38,6 +39,6 @@ In the template example above, each of the keys is a valid identifier. For examp
{{ index .Params "key-with-hyphens" }} → 2023
```
-[`index`]: /functions/collections/indexfunction
+[`index`]: /functions/collections/indexfunction/
[chaining]: /getting-started/glossary/#chain
[identifiers]: /getting-started/glossary/#identifier
diff --git a/docs/content/en/methods/page/Parent.md b/docs/content/en/methods/page/Parent.md
index 9d9ed7ea3b4..db01eb5897f 100644
--- a/docs/content/en/methods/page/Parent.md
+++ b/docs/content/en/methods/page/Parent.md
@@ -21,7 +21,7 @@ action:
{{% note %}}
The parent section of a regular page is the [current section].
-[current section]: /methods/page/currentsection
+[current section]: /methods/page/currentsection/
{{% /note %}}
Consider this content structure:
diff --git a/docs/content/en/methods/page/Path.md b/docs/content/en/methods/page/Path.md
new file mode 100644
index 00000000000..b65120d4d8e
--- /dev/null
+++ b/docs/content/en/methods/page/Path.md
@@ -0,0 +1,157 @@
+---
+title: Path
+description: Returns the logical path of the given page.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/File
+ - methods/page/RelPermalink
+ returnType: string
+ signatures: [PAGE.Path]
+toc: true
+---
+
+{{< new-in 0.123.0 >}}
+
+The `Path` method on a `Page` object returns the logical path of the given page, regardless of whether the page is backed by a file.
+
+[logical path]: /getting-started/glossary#logical-path
+
+```go-html-template
+{{ .Path }} → /posts/post-1
+```
+
+This value is neither a file path nor a relative URL. It is a logical identifier for each page, independent of content format, language, and URL modifiers.
+
+{{% note %}}
+Beginning with the release of [v0.92.0] in January 2022, Hugo emitted a warning whenever calling the `Path` method. The warning indicated that this method would change in a future release.
+
+The meaning of, and value returned by, the `Path` method on a `Page` object changed with the release of [v0.123.0] in February 2024.
+
+[v0.92.0]: https://github.com/gohugoio/hugo/releases/tag/v0.92.0
+[v0.123.0]: https://github.com/gohugoio/hugo/releases/tag/v0.123.0
+{{% /note %}}
+
+To determine the logical path for pages backed by a file, Hugo starts with the file path, relative to the content directory, and then:
+
+1. Strips the file extension
+2. Strips the language identifier
+3. Converts the result to lower case
+4. Replaces spaces with hyphens
+
+The value returned by the `Path` method on a `Page` object is independent of content format, language, and URL modifiers such as the `slug` and `url` front matter fields.
+
+## Examples
+
+### Monolingual site
+
+Note that the logical path is independent of content format and URL modifiers.
+
+File path|Front matter slug|Logical path
+:--|:--|:--
+`content/_index.md`||`/`
+`content/posts/_index.md`||`/posts`
+`content/posts/post-1.md`|`foo`|`/posts/post-1`
+`content/posts/post-2.html`|`bar`|`/posts/post-2`
+
+### Multilingual site
+
+Note that the logical path is independent of content format, language identifiers, and URL modifiers.
+
+File path|Front matter slug|Logical path
+:--|:--|:--
+`content/_index.en.md`||`/`
+`content/_index.de.md`||`/`
+`content/posts/_index.en.md`||`/posts`
+`content/posts/_index.de.md`||`/posts`
+`content/posts/posts-1.en.md`|`foo`|`/posts/post-1`
+`content/posts/posts-1.de.md`|`foo`|`/posts/post-1`
+`content/posts/posts-2.en.html`|`bar`|`/posts/post-2`
+`content/posts/posts-2.de.html`|`bar`|`/posts/post-2`
+
+### Pages not backed by a file
+
+The `Path` method on a `Page` object returns a value regardless of whether the page is backed by a file.
+
+```text
+content/
+└── posts/
+ └── post-1.md <-- front matter: tags = ['hugo']
+```
+
+When you build the site:
+
+```text
+public/
+├── posts/
+│ ├── post-1/
+│ │ └── index.html .Page.Path = /posts/post-1
+│ └── index.html .Page.Path = /posts
+├── tags/
+│ ├── hugo/
+│ │ └── index.html .Page.Path = /tags/hugo
+│ └── index.html .Page.Path = /tags
+└── index.html .Page.Path = /
+```
+
+## Finding pages
+
+These methods, functions, and shortcodes use the logical path to find the given page:
+
+Methods|Functions|Shortcodes
+:--|:--|:--
+[`Site.GetPage`]|[`urls.Ref`]|[`ref`]
+[`Page.GetPage`]|[`urls.RelRef`]|[`relref`]
+[`Page.Ref`]||
+[`Page.RelRef`]||
+[`Shortcode.Ref`]||
+[`Shortcode.RelRef`]||
+
+[`urls.Ref`]: /functions/urls/ref/
+[`urls.RelRef`]: /functions/urls/relref/
+[`Page.GetPage`]: /methods/page/getpage/
+[`Site.GetPage`]: /methods/site/getpage/
+[`ref`]: /content-management/shortcodes/#ref
+[`relref`]: /content-management/shortcodes/#relref
+[`Page.Ref`]: /methods/page/ref/
+[`Page.RelRef`]: /methods/page/relref/
+[`Shortcode.Ref`]: /methods/shortcode/ref
+[`Shortcode.RelRef`]: /methods/shortcode/relref
+
+{{% note %}}
+Specify the logical path when using any of these methods, functions, or shortcodes. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree.
+{{% /note %}}
+
+
+## Logical tree
+
+Just as file paths form a file tree, logical paths form a logical tree.
+
+A file tree:
+
+```text
+content/
+└── s1/
+ ├── p1/
+ │ └── index.md
+ └── p2.md
+```
+
+The same content represented as a logical tree:
+
+```text
+content/
+└── s1/
+ ├── p1
+ └── p2
+```
+
+A key difference between these trees is the relative path from p1 to p2:
+
+- In the file tree, the relative path from p1 to p2 is `../p2.md`
+- In the logical tree, the relative path is `p2`
+
+{{% note %}}
+Remember to use the logical path when using any of the methods, functions, or shortcodes listed in the previous section. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree.
+{{% /note %}}
diff --git a/docs/content/en/methods/page/Plain.md b/docs/content/en/methods/page/Plain.md
index 6fdf60b62cf..3aae1ed6174 100644
--- a/docs/content/en/methods/page/Plain.md
+++ b/docs/content/en/methods/page/Plain.md
@@ -13,7 +13,7 @@ action:
signatures: [PAGE.Plain]
---
-The `Plain` method on a `Page` object renders markdown and [shortcodes] to HTML, then strips the HTML [tags]. It does not strip HTML [entities]. The plain content does not include front matter.
+The `Plain` method on a `Page` object renders Markdown and [shortcodes] to HTML, then strips the HTML [tags]. It does not strip HTML [entities]. The plain content does not include front matter.
To prevent Go's [html/template] package from escaping HTML entities, pass the result through the [`htmlUnescape`] function.
@@ -25,4 +25,4 @@ To prevent Go's [html/template] package from escaping HTML entities, pass the re
[html/template]: https://pkg.go.dev/html/template
[entities]: https://developer.mozilla.org/en-US/docs/Glossary/Entity
[tags]: https://developer.mozilla.org/en-US/docs/Glossary/Tag
-[`htmlUnescape`]: /functions/
+[`htmlUnescape`]: /functions/transform/htmlunescape/
diff --git a/docs/content/en/methods/page/PlainWords.md b/docs/content/en/methods/page/PlainWords.md
index 4bc79d2412d..4f70193fefa 100644
--- a/docs/content/en/methods/page/PlainWords.md
+++ b/docs/content/en/methods/page/PlainWords.md
@@ -15,7 +15,7 @@ action:
The `PlainWords` method on a `Page` object calls the [`Plain`] method, then uses Go's [`strings.Fields`] function to split the result into words.
{{% note %}}
-_Fields splits the string s around each instance of one or more consecutive white space characters, as defined by [`unicode.IsSpace`], returning a slice of substrings of s or an empty slice if s contains only white space._
+_Fields splits the string s around each instance of one or more consecutive whitespace characters, as defined by [`unicode.IsSpace`], returning a slice of substrings of s or an empty slice if s contains only whitespace._
[`unicode.IsSpace`]: https://pkg.go.dev/unicode#IsSpace
{{% /note %}}
@@ -32,5 +32,5 @@ To determine the approximate number of unique words on a page:
{{ .PlainWords | uniq }} → 42
```
-[`Plain`]: /methods/page/plain
+[`Plain`]: /methods/page/plain/
[`strings.Fields`]: https://pkg.go.dev/strings#Fields
diff --git a/docs/content/en/methods/page/PrevInSection.md b/docs/content/en/methods/page/PrevInSection.md
index c09e4580f7a..e6daf66c443 100644
--- a/docs/content/en/methods/page/PrevInSection.md
+++ b/docs/content/en/methods/page/PrevInSection.md
@@ -66,7 +66,7 @@ With the `PrevInSection` and `NextInSection` methods, the navigation sort order
For example, with a page collection sorted by title, the navigation sort order will use Hugo’s default sort order. This is probably not what you want or expect. For this reason, the Next and Prev methods on a Pages object are generally a better choice.
-[date]: /methods/page/date
-[weight]: /methods/page/weight
-[linkTitle]: /methods/page/linktitle
-[title]: /methods/page/title
+[date]: /methods/page/date/
+[weight]: /methods/page/weight/
+[linkTitle]: /methods/page/linktitle/
+[title]: /methods/page/title/
diff --git a/docs/content/en/methods/page/PublishDate.md b/docs/content/en/methods/page/PublishDate.md
index b1c0717a9b8..d1f2eb2a12d 100644
--- a/docs/content/en/methods/page/PublishDate.md
+++ b/docs/content/en/methods/page/PublishDate.md
@@ -29,7 +29,7 @@ The publish date is a [time.Time] value. Format and localize the value with the
In the example above we explicitly set the publish date in front matter. With Hugo's default configuration, the `PublishDate` method returns the front matter value. This behavior is configurable, allowing you to set fallback values if the publish date is not defined in front matter. See [details].
-[`time.Format`]: /functions/time/format
+[`time.Format`]: /functions/time/format/
[details]: /getting-started/configuration/#configure-dates
-[time methods]: /methods/time
+[time methods]: /methods/time/
[time.Time]: https://pkg.go.dev/time#Time
diff --git a/docs/content/en/methods/page/RawContent.md b/docs/content/en/methods/page/RawContent.md
index 258a294d094..12686c69525 100644
--- a/docs/content/en/methods/page/RawContent.md
+++ b/docs/content/en/methods/page/RawContent.md
@@ -25,7 +25,7 @@ This is useful when rendering a page in a plain text [output format].
[Shortcodes] within the content are not rendered. To get the raw content with shortcodes rendered, use the [`RenderShortcodes`] method on a `Page` object.
[shortcodes]: /getting-started/glossary/#shortcode
-[`RenderShortcodes`]: /methods/page/rendershortcodes
+[`RenderShortcodes`]: /methods/page/rendershortcodes/
{{% /note %}}
-[output format]: /templates/output-formats
+[output format]: /templates/output-formats/
diff --git a/docs/content/en/methods/page/RegularPages.md b/docs/content/en/methods/page/RegularPages.md
index b0ca7b1e193..d3327702ea0 100644
--- a/docs/content/en/methods/page/RegularPages.md
+++ b/docs/content/en/methods/page/RegularPages.md
@@ -72,7 +72,7 @@ In the last example, the collection includes pages in the resources subdirectory
{{% note %}}
When used with the `Site` object, the `RegularPages` method recursively returns all regular pages within the site. See [details].
-[details]: /methods/site/regularpages
+[details]: /methods/site/regularpages/
{{% /note %}}
```go-html-template
diff --git a/docs/content/en/methods/page/Render.md b/docs/content/en/methods/page/Render.md
index bc3f58352c0..9a70d2bedc5 100644
--- a/docs/content/en/methods/page/Render.md
+++ b/docs/content/en/methods/page/Render.md
@@ -70,6 +70,6 @@ layouts/_default/li.html
See [content views] for more examples.
-[content views]: /templates/views
-[`partial`]: /functions/partials/include
+[content views]: /templates/views/
+[`partial`]: /functions/partials/include/
[content type]: /getting-started/glossary/#content-type
diff --git a/docs/content/en/methods/page/RenderShortcodes.md b/docs/content/en/methods/page/RenderShortcodes.md
index 4636bf8f5ba..a4120f69a45 100644
--- a/docs/content/en/methods/page/RenderShortcodes.md
+++ b/docs/content/en/methods/page/RenderShortcodes.md
@@ -22,11 +22,12 @@ Use this method in shortcode templates to compose a page from multiple content f
For example:
{{< code file=layouts/shortcodes/include.html >}}
-{{ $p := site.GetPage (.Get 0) }}
-{{ $p.RenderShortcodes }}
+{{ with site.GetPage (.Get 0) }}
+ {{ .RenderShortcodes }}
+{{ end }}
{{< /code >}}
-Then in your markdown:
+Then call the shortcode in your Markdown:
{{< code file=content/about.md lang=md >}}
{{%/* include "/snippets/services.md" */%}}
@@ -34,14 +35,14 @@ Then in your markdown:
{{%/* include "/snippets/leadership.md" */%}}
{{< /code >}}
-Each of the included markdown files can contain calls to other shortcodes.
+Each of the included Markdown files can contain calls to other shortcodes.
## Shortcode notation
In the example above it's important to understand the difference between the two delimiters used when calling a shortcode:
- `{{}}` tells Hugo that the rendered shortcode does not need further processing. For example, the shortcode content is HTML.
-- `{{%/* myshortcode */%}}` tells Hugo that the rendered shortcode needs further processing. For example, the shortcode content is markdown.
+- `{{%/* myshortcode */%}}` tells Hugo that the rendered shortcode needs further processing. For example, the shortcode content is Markdown.
Use the latter for the "include" shortcode described above.
@@ -75,4 +76,4 @@ https://example.org/privacy/
An *emphasized* word.
```
-Note that the shortcode within the content file was rendered, but the surrounding markdown was preserved.
+Note that the shortcode within the content file was rendered, but the surrounding Markdown was preserved.
diff --git a/docs/content/en/methods/page/RenderString.md b/docs/content/en/methods/page/RenderString.md
index 5782cd2b1ac..1a92c78c60a 100644
--- a/docs/content/en/methods/page/RenderString.md
+++ b/docs/content/en/methods/page/RenderString.md
@@ -47,5 +47,5 @@ Render with [Pandoc]:
{{ .RenderString $opts $s }} →
H2O
```
-[markup identifier]: /content-management/formats/#list-of-content-formats
+[markup identifier]: /content-management/formats/#classification
[pandoc]: https://www.pandoc.org/
diff --git a/docs/content/en/methods/page/Resources.md b/docs/content/en/methods/page/Resources.md
index 140b50020ed..54a61a2e45c 100644
--- a/docs/content/en/methods/page/Resources.md
+++ b/docs/content/en/methods/page/Resources.md
@@ -75,11 +75,11 @@ With the `GetMatch` and `Match` methods, Hugo determines a match using a case-in
{{% include "functions/_common/glob-patterns.md" %}}
-[`resources.ByType`]: /functions/resources/ByType
-[`resources.GetMatch`]: /functions/resources/ByType
-[`resources.Get`]: /functions/resources/ByType
-[`resources.Match`]: /functions/resources/ByType
-[`resources`]: /functions/resources
+[`resources.ByType`]: /functions/resources/ByType/
+[`resources.GetMatch`]: /functions/resources/ByType/
+[`resources.Get`]: /functions/resources/ByType/
+[`resources.Match`]: /functions/resources/ByType/
+[`resources`]: /functions/resources/
[glob pattern]: https://github.com/gobwas/glob#example
[media type]: https://en.wikipedia.org/wiki/Media_type
[page bundle]: /getting-started/glossary/#page-bundle
diff --git a/docs/content/en/methods/page/Scratch.md b/docs/content/en/methods/page/Scratch.md
index f9ce7f7fb68..8fef31893fb 100644
--- a/docs/content/en/methods/page/Scratch.md
+++ b/docs/content/en/methods/page/Scratch.md
@@ -1,6 +1,6 @@
---
title: Scratch
-description: Creates a "scratch pad" on the given page to store and manipulate data.
+description: Returns a "scratch pad" on the given page to store and manipulate data.
categories: []
keywords: []
action:
@@ -9,6 +9,7 @@ action:
- functions/collections/NewScratch
returnType: maps.Scratch
signatures: [PAGE.Scratch]
+toc: true
aliases: [/extras/scratch/,/doc/scratch/,/functions/scratch]
---
@@ -16,8 +17,28 @@ The `Scratch` method on a `Page` object creates a [scratch pad] to store and man
To create a locally scoped scratch pad that is not attached to a `Page` object, use the [`newScratch`] function.
-[`Store`]: /methods/page/store
-[`newScratch`]: functions/collections/newscratch
+[`Store`]: /methods/page/store/
+[`newScratch`]: /functions/collections/newscratch/
[scratch pad]: /getting-started/glossary/#scratch-pad
{{% include "methods/page/_common/scratch-methods.md" %}}
+
+## Determinate values
+
+The `Scratch` method is often used to set scratch pad values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are not determinate until Hugo renders the page content.
+
+If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop] variable:
+
+[noop]: /getting-started/glossary/#noop
+
+```go-html-template
+{{ $noop := .Content }}
+{{ .Store.Get "mykey" }}
+```
+
+You can also trigger content rendering with the `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount` methods. For example:
+
+```go-html-template
+{{ $noop := .WordCount }}
+{{ .Store.Get "mykey" }}
+```
diff --git a/docs/content/en/methods/page/Section.md b/docs/content/en/methods/page/Section.md
index 30c8a983788..8e027a5a11f 100644
--- a/docs/content/en/methods/page/Section.md
+++ b/docs/content/en/methods/page/Section.md
@@ -50,5 +50,5 @@ This is similar to using the [`Type`] method with the `where` function
However, if the `type` field in front matter has been defined on one or more pages, the page collection based on `Type` will be different than the page collection based on `Section`.
-[`where`]: /functions/collections/where
-[`Type`]: /methods/page/type
+[`where`]: /functions/collections/where/
+[`Type`]: /methods/page/type/
diff --git a/docs/content/en/methods/page/Sections.md b/docs/content/en/methods/page/Sections.md
index d64440038bd..4cce1a4fbbd 100644
--- a/docs/content/en/methods/page/Sections.md
+++ b/docs/content/en/methods/page/Sections.md
@@ -35,11 +35,11 @@ content/
│ ├── bidding.md
│ └── payment.md
├── books/
-│ ├── _index.md <-- front matter: weight = 10
+│ ├── _index.md <-- front matter: weight = 20
│ ├── book-1.md
│ └── book-2.md
├── films/
-│ ├── _index.md <-- front matter: weight = 20
+│ ├── _index.md <-- front matter: weight = 10
│ ├── film-1.md
│ └── film-2.md
└── _index.md
diff --git a/docs/content/en/methods/page/Site.md b/docs/content/en/methods/page/Site.md
index 34748facd52..d83c45e0a60 100644
--- a/docs/content/en/methods/page/Site.md
+++ b/docs/content/en/methods/page/Site.md
@@ -12,7 +12,7 @@ action:
See [Site methods].
-[Site methods]: /methods/site
+[Site methods]: /methods/site/
```go-html-template
{{ .Site.Title }}
diff --git a/docs/content/en/methods/page/Sitemap.md b/docs/content/en/methods/page/Sitemap.md
index 08ff3f5d067..d6159267dce 100644
--- a/docs/content/en/methods/page/Sitemap.md
+++ b/docs/content/en/methods/page/Sitemap.md
@@ -14,15 +14,22 @@ Access to the `Sitemap` method on a `Page` object is restricted to [sitemap temp
## Methods
-ChangeFreq
-: (`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. Default is "" (change frequency omitted from rendered sitemap).
+changefreq
+: (`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. With the default value of `""` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#changefreqdef).
```go-html-template
{{ .Sitemap.ChangeFreq }}
```
-Priority
-: (`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. Default is -1 (priority omitted from rendered sitemap).
+disable {{< new-in 0.125.0 >}}
+: (`bool`) Whether to disable page inclusion. Default is `false`. Set to `true` in front matter to exclude the page.
+
+```go-html-template
+{{ .Sitemap.Disable }}
+```
+
+priority
+: (`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. With the default value of `-1` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#priority).
```go-html-template
{{ .Sitemap.Priority }}
diff --git a/docs/content/en/methods/page/Sites.md b/docs/content/en/methods/page/Sites.md
index 1fbdfcdcde8..cd240655e3e 100644
--- a/docs/content/en/methods/page/Sites.md
+++ b/docs/content/en/methods/page/Sites.md
@@ -52,10 +52,10 @@ Produces a list of links to each home page:
```
-To render a link to home page of the primary (first) language:
+To render a link to the home page of the site corresponding to the default content language:
```go-html-template
-{{ with .Sites.First }}
+{{ with .Sites.Default }}
{{ .Title }}
{{ end }}
```
diff --git a/docs/content/en/methods/page/Store.md b/docs/content/en/methods/page/Store.md
index 8bc16034b72..e7090fe7951 100644
--- a/docs/content/en/methods/page/Store.md
+++ b/docs/content/en/methods/page/Store.md
@@ -1,6 +1,6 @@
---
title: Store
-description: Creates a persistent "scratch pad" on the given page to store and manipulate data.
+description: Returns a persistent "scratch pad" on the given page to store and manipulate data.
categories: []
keywords: []
action:
@@ -9,6 +9,7 @@ action:
- functions/collections/NewScratch
returnType: maps.Scratch
signatures: [PAGE.Store]
+toc: true
aliases: [/functions/store]
---
@@ -16,8 +17,8 @@ The `Store` method on a `Page` object creates a persistent [scratch pad] to stor
To create a locally scoped scratch pad that is not attached to a `Page` object, use the [`newScratch`] function.
-[`Scratch`]: /methods/page/scratch
-[`newScratch`]: functions/collections/newscratch
+[`Scratch`]: /methods/page/scratch/
+[`newScratch`]: /functions/collections/newscratch/
[scratch pad]: /getting-started/glossary/#scratch-pad
## Methods
@@ -102,3 +103,23 @@ Removes the given key.
{{ .Store.Set "greeting" "Hello" }}
{{ .Store.Delete "greeting" }}
```
+
+## Determinate values
+
+The `Store` method is often used to set scratch pad values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are not determinate until Hugo renders the page content.
+
+If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop] variable:
+
+[noop]: /getting-started/glossary/#noop
+
+```go-html-template
+{{ $noop := .Content }}
+{{ .Store.Get "mykey" }}
+```
+
+You can also trigger content rendering with the `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount` methods. For example:
+
+```go-html-template
+{{ $noop := .WordCount }}
+{{ .Store.Get "mykey" }}
+```
diff --git a/docs/content/en/methods/page/Summary.md b/docs/content/en/methods/page/Summary.md
index 37ce865893b..e4542d25814 100644
--- a/docs/content/en/methods/page/Summary.md
+++ b/docs/content/en/methods/page/Summary.md
@@ -11,10 +11,14 @@ action:
signatures: [PAGE.Summary]
---
+
+
+
+
There are three ways to define the [content summary]:
1. Let Hugo create the summary based on the first 70 words. You can change the number of words by setting the `summaryLength` in your site configuration.
-2. Manually split the content with a `<--more-->` tag in markdown. Everything before the tag is included in the summary.
+2. Manually split the content with a `` tag in Markdown. Everything before the tag is included in the summary.
3. Create a `summary` field in front matter.
To list the pages in a section with a summary beneath each link:
@@ -26,4 +30,4 @@ To list the pages in a section with a summary beneath each link:
{{ end }}
```
-[content summary]: /content-management/summaries
+[content summary]: /content-management/summaries/
diff --git a/docs/content/en/methods/page/TableOfContents.md b/docs/content/en/methods/page/TableOfContents.md
index 2ab182e8ca7..38c3ff17bd1 100644
--- a/docs/content/en/methods/page/TableOfContents.md
+++ b/docs/content/en/methods/page/TableOfContents.md
@@ -8,9 +8,10 @@ action:
- methods/page/Fragments
returnType: template.HTML
signatures: [PAGE.TableOfContents]
+aliases: [/content-management/toc/]
---
-The `TableOfContents` method on a `Page` object returns an ordered or unordered list of the markdown [ATX] and [setext] headings within the page content.
+The `TableOfContents` method on a `Page` object returns an ordered or unordered list of the Markdown [ATX] and [setext] headings within the page content.
[atx]: https://spec.commonmark.org/0.30/#atx-headings
[setext]: https://spec.commonmark.org/0.30/#setext-headings
diff --git a/docs/content/en/methods/page/Title.md b/docs/content/en/methods/page/Title.md
index 52e46ff44be..5c2c98d6b23 100644
--- a/docs/content/en/methods/page/Title.md
+++ b/docs/content/en/methods/page/Title.md
@@ -20,19 +20,21 @@ title = 'About us'
{{ .Title }} → About us
```
-With section pages not backed by a file, the `Title` method returns the section name, pluralized and converted to title case.
-
-To disable [pluralization]:
+With section, taxonomy, and term pages not backed by a file, the `Title` method returns the section name, capitalized and pluralized. You can disable these transformations by setting [`capitalizeListTitles`] and [`pluralizeListTitles`] in your site configuration. For example:
{{< code-toggle file=hugo >}}
+capitalizeListTitles = false
pluralizeListTitles = false
{{< /code-toggle >}}
-To change the [title case style], specify one of `ap`, `chicago`, `go`, `firstupper`, or `none`:
+You can change the capitalization style in your site configuration to one of `ap`, `chicago`, `go`, `firstupper`, or `none`. For example:
{{< code-toggle file=hugo >}}
-titleCaseStyle = "ap"
+titleCaseStyle = "firstupper"
{{< /code-toggle >}}
-[pluralization]: /functions/inflect/pluralize
-[title case style]: /getting-started/configuration/#configure-title-case
+ See [details].
+
+[`capitalizeListTitles`]: /getting-started/configuration/#capitalizelisttitles
+[`pluralizeListTitles`]: /getting-started/configuration/#pluralizelisttitles
+[details]: /getting-started/configuration/#configure-title-case
diff --git a/docs/content/en/methods/page/Translations.md b/docs/content/en/methods/page/Translations.md
index 1ed25663072..597a9aeb604 100644
--- a/docs/content/en/methods/page/Translations.md
+++ b/docs/content/en/methods/page/Translations.md
@@ -1,6 +1,6 @@
---
title: Translations
-description: Returns all translation of the given page, excluding the current language.
+description: Returns all translations of the given page, excluding the current language.
categories: []
keywords: []
action:
@@ -63,9 +63,9 @@ And this template:
{{ with .Translations }}
{{ range . }}
- {{ $langName := or .Language.LanguageName .Language.Lang }}
- {{ $langCode := or .Language.LanguageCode .Language.Lang }}
-
{{ end }}
diff --git a/docs/content/en/methods/page/Truncated.md b/docs/content/en/methods/page/Truncated.md
index e6051f0cd4a..0785f40cb08 100644
--- a/docs/content/en/methods/page/Truncated.md
+++ b/docs/content/en/methods/page/Truncated.md
@@ -13,7 +13,7 @@ action:
There are three ways to define the [content summary]:
1. Let Hugo create the summary based on the first 70 words. You can change the number of words by setting the `summaryLength` in your site configuration.
-2. Manually split the content with a `<--more-->` tag in markdown. Everything before the tag is included in the summary.
+2. Manually split the content with a `<--more-->` tag in Markdown. Everything before the tag is included in the summary.
3. Create a `summary` field in front matter.
{{% note %}}
@@ -32,4 +32,4 @@ The `Truncated` method returns `true` if the content length exceeds the summary
{{ end }}
```
-[content summary]: /content-management/summaries
+[content summary]: /content-management/summaries/
diff --git a/docs/content/en/methods/page/WordCount.md b/docs/content/en/methods/page/WordCount.md
index bb1fdcf9414..70fe407ab85 100644
--- a/docs/content/en/methods/page/WordCount.md
+++ b/docs/content/en/methods/page/WordCount.md
@@ -17,4 +17,4 @@ action:
To round up to nearest multiple of 100, use the [`FuzzyWordCount`] method.
-[`FuzzyWordCount`]: /methods/page/fuzzywordcount
+[`FuzzyWordCount`]: /methods/page/fuzzywordcount/
diff --git a/docs/content/en/methods/page/_common/_index.md b/docs/content/en/methods/page/_common/_index.md
index 47d5812fba5..4328d4d145b 100644
--- a/docs/content/en/methods/page/_common/_index.md
+++ b/docs/content/en/methods/page/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
diff --git a/docs/content/en/methods/page/_common/output-format-definition.md b/docs/content/en/methods/page/_common/output-format-definition.md
index 25944464a7c..412c5cee692 100644
--- a/docs/content/en/methods/page/_common/output-format-definition.md
+++ b/docs/content/en/methods/page/_common/output-format-definition.md
@@ -8,4 +8,4 @@ Hugo generates one or more files per page when building a site. For example, whe
[taxonomy]: /getting-started/glossary/#taxonomy
[term]: /getting-started/glossary/#term
[page kind]: /getting-started/glossary/#page-kind
-[details]: /templates/output-formats
+[details]: /templates/output-formats/
diff --git a/docs/content/en/methods/pager/First.md b/docs/content/en/methods/pager/First.md
new file mode 100644
index 00000000000..85e2e0dd376
--- /dev/null
+++ b/docs/content/en/methods/pager/First.md
@@ -0,0 +1,44 @@
+---
+title: First
+description: Returns the first pager in the pager collection.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/pager/Last
+ - methods/pager/Prev
+ - methods/pager/Next
+ - methods/pager/HasPrev
+ - methods/pager/HasNext
+ - methods/page/Paginate
+ returnType: page.Pager
+ signatures: [PAGER.First]
+---
+
+Use the `First` method to build navigation between pagers.
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+
+{{ end }}
+```
+
+You can also write the above without using the `HasNext` method:
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+
+{{ end }}
+```
+
+You can also write the above without using the `HasPrev` method:
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+
+{{ end }}
+```
diff --git a/docs/content/en/methods/pager/_index.md b/docs/content/en/methods/pager/_index.md
new file mode 100644
index 00000000000..58a1def7b17
--- /dev/null
+++ b/docs/content/en/methods/pager/_index.md
@@ -0,0 +1,14 @@
+---
+title: Pager methods
+linkTitle: Pager
+description: Use these methods with Pager objects when paginating a list page.
+keywords: []
+menu:
+ docs:
+ identifier:
+ parent: methods
+---
+
+Use these methods with Pager objects when building navigation for a [paginated] list page.
+
+[paginated]: /templates/pagination/
diff --git a/docs/content/en/methods/pages/_common/_index.md b/docs/content/en/methods/pages/_common/_index.md
index 47d5812fba5..4328d4d145b 100644
--- a/docs/content/en/methods/pages/_common/_index.md
+++ b/docs/content/en/methods/pages/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
diff --git a/docs/content/en/methods/resource/Colors.md b/docs/content/en/methods/resource/Colors.md
index 1452d558f78..b062210baf3 100644
--- a/docs/content/en/methods/resource/Colors.md
+++ b/docs/content/en/methods/resource/Colors.md
@@ -5,18 +5,174 @@ categories: []
keywords: []
action:
related: []
- returnType: '[]string'
+ returnType: '[]images.Color'
signatures: [RESOURCE.Colors]
+toc: true
+math: true
---
{{< new-in 0.104.0 >}}
+The `Resources.Colors` method returns a slice of the most dominant colors in an image, ordered from most dominant to least dominant. This method is fast, but if you also downsize your image you can improve performance by extracting the colors from the scaled image.
+
+{{% include "methods/resource/_common/global-page-remote-resources.md" %}}
+
+## Methods
+
+Each color is an object with the following methods:
+
+ColorHex
+{{< new-in 0.125.0 >}}
+: (`string`) Returns the [hexadecimal color] value, prefixed with a hash sign.
+
+Luminance
+{{< new-in 0.125.0 >}}
+: (`float64`) Returns the [relative luminance] of the color in the sRGB colorspace in the range [0, 1]. A value of `0` represents the darkest black, while a value of `1` represents the lightest white.
+
+{{% note %}}
+Image filters such as [`images.Dither`], [`images.Padding`], and [`images.Text`] accept either hexadecimal color values or `images.Color` objects as arguments.
+
+Hugo renders an `images.Color` object as a hexadecimal color value.
+
+[`images.Dither`]: /functions/images/dither/
+[`images.Padding`]: /functions/images/padding/
+[`images.Text`]: /functions/images/text/
+{{% /note %}}
+
+[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
+[relative luminance]: https://www.w3.org/TR/WCAG21/#dfn-relative-luminance
+
+## Sorting
+
+As a contrived example, create a table of an image's dominant colors with the most dominant color first, and display the relative luminance of each dominant color:
+
```go-html-template
{{ with resources.Get "images/a.jpg" }}
- {{ .Colors }} → [#bebebd #514947 #768a9a #647789 #90725e #a48974]
+
+
+
+
Color
+
Relative luminance
+
+
+
+ {{ range .Colors }}
+
+
{{ .ColorHex }}
+
{{ .Luminance | lang.FormatNumber 4 }}
+
+ {{ end }}
+
+
{{ end }}
```
-This method is fast, but if you also scale down your images, it would be good for performance to extract the colors from the scaled image.
+Hugo renders this to:
-{{% include "methods/resource/_common/global-page-remote-resources.md" %}}
+ColorHex|Relative luminance
+:--|:--
+`#bebebd`|`0.5145`
+`#514947`|`0.0697`
+`#768a9a`|`0.2436`
+`#647789`|`0.1771`
+`#90725e`|`0.1877`
+`#a48974`|`0.2704`
+
+To sort by dominance with the least dominant color first:
+
+```go-html-template
+{{ range .Colors | collections.Reverse }}
+```
+
+To sort by relative luminance with the darkest color first:
+
+```go-html-template
+{{ range sort .Colors "Luminance" }}
+```
+
+To sort by relative luminance with the lightest color first, use either of these constructs:
+
+```go-html-template
+{{ range sort .Colors "Luminance" | collections.Reverse }}
+{{ range sort .Colors "Luminance" "desc" }}
+```
+
+## Examples
+
+### Image borders
+
+To add a 5 pixel border to an image using the most dominant color:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ $mostDominant := index .Colors 0 }}
+ {{ $filter := images.Padding 5 $mostDominant }}
+ {{ with .Filter $filter }}
+
+ {{ end }}
+{{ end }}
+```
+
+To add a 5 pixel border to an image using the darkest dominant color:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ $darkest := index (sort .Colors "Luminance") 0 }}
+ {{ $filter := images.Padding 5 $darkest }}
+ {{ with .Filter $filter }}
+
+ {{ end }}
+{{ end }}
+```
+
+### Light text on dark background
+
+To create a text box where the foreground and background colors are derived from an image's lightest and darkest dominant colors:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ $darkest := index (sort .Colors "Luminance") 0 }}
+ {{ $lightest := index (sort .Colors "Luminance" "desc") 0 }}
+
+
+
This is light text on a dark background.
+
+
+{{ end }}
+```
+
+### WCAG contrast ratio
+
+In the previous example we placed light text on a dark background, but does this color combination conform to [WCAG] guidelines for either the [minimum] or the [enhanced] contrast ratio?
+
+The WCAG defines the [contrast ratio] as:
+
+$$contrast\ ratio = { L_1 + 0.05 \over L_2 + 0.05 }$$
+
+where $L_1$ is the relative luminance of the lightest color and $L_2$ is the relative luminance of the darkest color.
+
+Calculate the contrast ratio to determine WCAG conformance:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ $lightest := index (sort .Colors "Luminance" "desc") 0 }}
+ {{ $darkest := index (sort .Colors "Luminance") 0 }}
+ {{ $cr := div
+ (add $lightest.Luminance 0.05)
+ (add $darkest.Luminance 0.05)
+ }}
+ {{ if ge $cr 7.5 }}
+ {{ printf "The %.2f contrast ratio conforms to WCAG Level AAA." $cr }}
+ {{ else if ge $cr 4.5 }}
+ {{ printf "The %.2f contrast ratio conforms to WCAG Level AA." $cr }}
+ {{ else }}
+ {{ printf "The %.2f contrast ratio does not conform to WCAG guidelines." $cr }}
+ {{ end }}
+{{ end }}
+```
+
+
+[WCAG]: https://en.wikipedia.org/wiki/Web_Content_Accessibility_Guidelines
+[contrast ratio]: https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio
+[enhanced]: https://www.w3.org/WAI/WCAG22/quickref/?showtechniques=145#contrast-enhanced
+[minimum]: https://www.w3.org/WAI/WCAG22/quickref/?showtechniques=145#contrast-minimum
diff --git a/docs/content/en/methods/resource/Content.md b/docs/content/en/methods/resource/Content.md
index a5945ff6568..4135113e973 100644
--- a/docs/content/en/methods/resource/Content.md
+++ b/docs/content/en/methods/resource/Content.md
@@ -12,7 +12,7 @@ toc:
The `Content` method on a `Resource` object returns `template.HTML` when the resource type is `page`, otherwise it returns a `string`.
-[resource type]: /methods/resource/resourcetype
+[resource type]: /methods/resource/resourcetype/
{{< code file=assets/quotations/kipling.txt >}}
He travels the fastest who travels alone.
diff --git a/docs/content/en/methods/resource/Data.md b/docs/content/en/methods/resource/Data.md
index 0fbaf619906..43108fce835 100644
--- a/docs/content/en/methods/resource/Data.md
+++ b/docs/content/en/methods/resource/Data.md
@@ -13,7 +13,7 @@ action:
The `Data` method on a resource returned by the [`resources.GetRemote`] function returns information from the HTTP response.
-[`resources.GetRemote`]: functions/resources/getremote
+[`resources.GetRemote`]: /functions/resources/getremote/
```go-html-template
{{ $url := "https://example.org/images/a.jpg" }}
@@ -50,4 +50,4 @@ TransferEncoding
: (`string`) The transfer encoding.
-[`resources.GetRemote`]: functions/resources/getremote
+[`resources.GetRemote`]: /functions/resources/getremote/
diff --git a/docs/content/en/methods/resource/Err.md b/docs/content/en/methods/resource/Err.md
index f4b410aa7ab..6baa30e4747 100644
--- a/docs/content/en/methods/resource/Err.md
+++ b/docs/content/en/methods/resource/Err.md
@@ -13,7 +13,7 @@ action:
The `Err` method on a resource returned by the [`resources.GetRemote`] function returns an error message if the HTTP request fails, else nil. If you do not handle the error yourself, Hugo will fail the build.
-[`resources.GetRemote`]: functions/resources/getremote
+[`resources.GetRemote`]: /functions/resources/getremote/
In this example we send an HTTP request to a nonexistent domain:
diff --git a/docs/content/en/methods/resource/Exif.md b/docs/content/en/methods/resource/Exif.md
index 765b4c92ff0..1d00ef3bc9a 100644
--- a/docs/content/en/methods/resource/Exif.md
+++ b/docs/content/en/methods/resource/Exif.md
@@ -15,7 +15,7 @@ Applicable to JPEG and TIFF images, the `Exif` method on an image `Resource` obj
## Methods
Date
-: (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`]function.
+: (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`] function.
Lat
: (`float64`) Returns the GPS latitude in degrees.
@@ -75,4 +75,4 @@ To list specific values:
[exif]: https://en.wikipedia.org/wiki/Exif
[site configuration]: /content-management/image-processing/#exif-data
-[`time.Format`]: /functions/time/format
+[`time.Format`]: /functions/time/format/
diff --git a/docs/content/en/methods/resource/Filter.md b/docs/content/en/methods/resource/Filter.md
index 329168da7c9..9db6bbe1764 100644
--- a/docs/content/en/methods/resource/Filter.md
+++ b/docs/content/en/methods/resource/Filter.md
@@ -39,7 +39,7 @@ To apply two or more filters, executing from left to right:
You can also apply image filters using the [`images.Filter`] function.
-[`images.Filter`]: /functions/images/filter
+[`images.Filter`]: /functions/images/filter/
{{% include "methods/resource/_common/global-page-remote-resources.md" %}}
diff --git a/docs/content/en/methods/resource/Key.md b/docs/content/en/methods/resource/Key.md
index 15927aea909..deeba9ab39c 100644
--- a/docs/content/en/methods/resource/Key.md
+++ b/docs/content/en/methods/resource/Key.md
@@ -1,6 +1,7 @@
---
title: Key
description: Returns the unique key for the given resource, equivalent to its publishing path.
+draft: true
categories: []
keywords: []
action:
@@ -40,6 +41,6 @@ The `Key` method is useful if you need to get the resource's publishing path wit
{{% include "methods/resource/_common/global-page-remote-resources.md" %}}
-[`Permalink`]: /methods/resource/permalink
-[`RelPermalink`]: /methods/resource/relpermalink
-[`resources.Copy`]: /functions/resources/copy
+[`Permalink`]: /methods/resource/permalink/
+[`RelPermalink`]: /methods/resource/relpermalink/
+[`resources.Copy`]: /functions/resources/copy/
diff --git a/docs/content/en/methods/resource/Name.md b/docs/content/en/methods/resource/Name.md
index 01b75e5b244..694b67baa8e 100644
--- a/docs/content/en/methods/resource/Name.md
+++ b/docs/content/en/methods/resource/Name.md
@@ -1,6 +1,6 @@
---
title: Name
-description: Returns the name of the given resource as optionally defined in front matter, falling back to a relative path or hashed file name depending on resource type.
+description: Returns the name of the given resource as optionally defined in front matter, falling back to its file path.
categories: []
keywords: []
action:
@@ -20,51 +20,63 @@ With a [global resource], the `Name` method returns the path to the resource, re
```text
assets/
└── images/
- └── a.jpg
+ └── Sunrise in Bryce Canyon.jpg
```
```go-html-template
-{{ with resources.Get "images/a.jpg" }}
- {{ .Name }} → images/a.jpg
+{{ with resources.Get "images/Sunrise in Bryce Canyon.jpg" }}
+ {{ .Name }} → /images/Sunrise in Bryce Canyon.jpg
{{ end }}
```
## Page resource
-With a [page resource], the `Name` method returns the path to the resource, relative to the page bundle.
+With a [page resource], if you create an element in the `resources` array in front matter, the `Name` method returns the value of the `name` parameter.
```text
content/
-├── posts/
-│ ├── post-1/
-│ │ ├── images/
-│ │ │ └── a.jpg
-│ │ └── index.md
-│ └── _index.md
+├── example/
+│ ├── images/
+│ │ └── a.jpg
+│ └── index.md
└── _index.md
```
+{{< code-toggle file=content/example/index.md fm=true >}}
+title = 'Example'
+[[resources]]
+src = 'images/a.jpg'
+name = 'Sunrise in Bryce Canyon'
+{{< /code-toggle >}}
+
```go-html-template
{{ with .Resources.Get "images/a.jpg" }}
- {{ .Name }} → images/a.jpg
+ {{ .Name }} → Sunrise in Bryce Canyon
{{ end }}
```
-If you create an element in the `resources` array in front matter, the `Name` method returns the value of the `name` parameter:
+You can also capture the image by specifying its `name` instead of its path:
-{{< code-toggle file=content/posts/post-1.md fm=true >}}
-title = 'Post 1'
-[[resources]]
-src = 'images/a.jpg'
-name = 'cat'
-title = 'Felix the cat'
-[resources.params]
-temperament = 'malicious'
-{{< /code-toggle >}}
+```go-html-template
+{{ with .Resources.Get "Sunrise in Bryce Canyon" }}
+ {{ .Name }} → Sunrise in Bryce Canyon
+{{ end }}
+```
+
+If you do not create an element in the `resources` array in front matter, the `Name` method returns the file path, relative to the page bundle.
+
+```text
+content/
+├── example/
+│ ├── images/
+│ │ └── Sunrise in Bryce Canyon.jpg
+│ └── index.md
+└── _index.md
+```
```go-html-template
-{{ with .Resources.Get "cat" }}
- {{ .Name }} → cat
+{{ with .Resources.Get "images/Sunrise in Bryce Canyon.jpg" }}
+ {{ .Name }} → images/Sunrise in Bryce Canyon.jpg
{{ end }}
```
## Remote resource
@@ -73,10 +85,11 @@ With a [remote resource], the `Name` method returns a hashed file name.
```go-html-template
{{ with resources.GetRemote "https://example.org/images/a.jpg" }}
- {{ .Name }} → a_18432433023265451104.jpg
+ {{ .Name }} → /a_18432433023265451104.jpg
{{ end }}
```
[global resource]: /getting-started/glossary/#global-resource
+[logical path]: /getting-started/glossary/#logical-path
[page resource]: /getting-started/glossary/#page-resource
[remote resource]: /getting-started/glossary/#remote-resource
diff --git a/docs/content/en/methods/resource/Params.md b/docs/content/en/methods/resource/Params.md
index 275182c4691..ff6707f0b22 100644
--- a/docs/content/en/methods/resource/Params.md
+++ b/docs/content/en/methods/resource/Params.md
@@ -62,4 +62,4 @@ Hugo renders:
See the [page resources] section for more information.
-[page resources]: /content-management/page-resources
+[page resources]: /content-management/page-resources/
diff --git a/docs/content/en/methods/resource/Permalink.md b/docs/content/en/methods/resource/Permalink.md
index ab0ad41b0e4..e0fa9aa870a 100644
--- a/docs/content/en/methods/resource/Permalink.md
+++ b/docs/content/en/methods/resource/Permalink.md
@@ -7,7 +7,6 @@ action:
related:
- methods/resource/RelPermalink
- methods/resource/Publish
- - methods/resource/Key
returnType: string
signatures: [RESOURCE.Permalink]
---
diff --git a/docs/content/en/methods/resource/Process.md b/docs/content/en/methods/resource/Process.md
index 3c88492df44..550b06401e4 100644
--- a/docs/content/en/methods/resource/Process.md
+++ b/docs/content/en/methods/resource/Process.md
@@ -59,8 +59,8 @@ The `Process` method is also available as a filter, which is more effective if y
example=true
>}}
-[`Crop`]: /methods/resource/crop
-[`Fill`]: /methods/resource/fill
-[`Fit`]: /methods/resource/fit
-[`Resize`]: /methods/resource/resize
-[`images.Process`]: /functions/images/process
+[`Crop`]: /methods/resource/crop/
+[`Fill`]: /methods/resource/fill/
+[`Fit`]: /methods/resource/fit/
+[`Resize`]: /methods/resource/resize/
+[`images.Process`]: /functions/images/process/
diff --git a/docs/content/en/methods/resource/Publish.md b/docs/content/en/methods/resource/Publish.md
index b090bfe5ab9..05344c65822 100644
--- a/docs/content/en/methods/resource/Publish.md
+++ b/docs/content/en/methods/resource/Publish.md
@@ -7,7 +7,6 @@ action:
related:
- methods/resource/Permalink
- methods/resource/RelPermalink
- - methods/resource/Key
returnType: nil
signatures: [RESOURCE.Publish]
---
diff --git a/docs/content/en/methods/resource/RelPermalink.md b/docs/content/en/methods/resource/RelPermalink.md
index 2b96c35d739..190cdf64ae1 100644
--- a/docs/content/en/methods/resource/RelPermalink.md
+++ b/docs/content/en/methods/resource/RelPermalink.md
@@ -7,7 +7,6 @@ action:
related:
- methods/resource/Permalink
- methods/resource/Publish
- - methods/resource/Key
returnType: string
signatures: [RESOURCE.RelPermalink]
---
diff --git a/docs/content/en/methods/resource/Title.md b/docs/content/en/methods/resource/Title.md
index e30f86d2e29..c620c2448c8 100644
--- a/docs/content/en/methods/resource/Title.md
+++ b/docs/content/en/methods/resource/Title.md
@@ -20,73 +20,65 @@ With a [global resource], the `Title` method returns the path to the resource, r
```text
assets/
└── images/
- └── a.jpg
+ └── Sunrise in Bryce Canyon.jpg
```
```go-html-template
-{{ with resources.Get "images/a.jpg" }}
- {{ .Title }} → images/a.jpg
+{{ with resources.Get "images/Sunrise in Bryce Canyon.jpg" }}
+ {{ .Title }} → /images/Sunrise in Bryce Canyon.jpg
{{ end }}
```
## Page resource
-With a [page resource], the `Title` method returns the path to the resource, relative to the page bundle.
+With a [page resource], if you create an element in the `resources` array in front matter, the `Title` method returns the value of the `title` parameter.
```text
content/
-├── posts/
-│ ├── post-1/
-│ │ ├── images/
-│ │ │ └── a.jpg
-│ │ └── index.md
-│ └── _index.md
+├── example/
+│ ├── images/
+│ │ └── a.jpg
+│ └── index.md
└── _index.md
```
-```go-html-template
-{{ with .Resources.Get "images/a.jpg" }}
- {{ .Title }} → images/a.jpg
-{{ end }}
-```
-
-If you create an element in the `resources` array in front matter, the `Title` method returns the value of the `title` parameter:
-
-{{< code-toggle file=content/posts/post-1.md fm=true >}}
-title = 'Post 1'
+{{< code-toggle file=content/example/index.md fm=true >}}
+title = 'Example'
[[resources]]
src = 'images/a.jpg'
-name = 'cat'
-title = 'Felix the cat'
-[resources.params]
-temperament = 'malicious'
+title = 'A beautiful sunrise in Bryce Canyon'
{{< /code-toggle >}}
```go-html-template
-{{ with .Resources.Get "cat" }}
- {{ .Title }} → Felix the cat
+{{ with .Resources.Get "images/a.jpg" }}
+ {{ .Title }} → A beautiful sunrise in Bryce Canyon
{{ end }}
```
-If the page resource is a content file, the `Title` methods return the `title` field as defined in front matter.
+If you do not create an element in the `resources` array in front matter, the `Title` method returns the file path, relative to the page bundle.
```text
content/
-├── lessons/
-│ ├── lesson-1/
-│ │ ├── _objectives.md <-- resource type = page
-│ │ └── index.md
-│ └── _index.md
+├── example/
+│ ├── images/
+│ │ └── Sunrise in Bryce Canyon.jpg
+│ └── index.md
└── _index.md
```
+```go-html-template
+{{ with .Resources.Get "Sunrise in Bryce Canyon.jpg" }}
+ {{ .Title }} → images/Sunrise in Bryce Canyon.jpg
+{{ end }}
+```
+
## Remote resource
With a [remote resource], the `Title` method returns a hashed file name.
```go-html-template
{{ with resources.GetRemote "https://example.org/images/a.jpg" }}
- {{ .Title }} → a_18432433023265451104.jpg
+ {{ .Title }} → /a_18432433023265451104.jpg
{{ end }}
```
diff --git a/docs/content/en/methods/resource/_common/_index.md b/docs/content/en/methods/resource/_common/_index.md
index 47d5812fba5..4328d4d145b 100644
--- a/docs/content/en/methods/resource/_common/_index.md
+++ b/docs/content/en/methods/resource/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
diff --git a/docs/content/en/methods/shortcode/Get.md b/docs/content/en/methods/shortcode/Get.md
index cd674614f12..8874c764961 100644
--- a/docs/content/en/methods/shortcode/Get.md
+++ b/docs/content/en/methods/shortcode/Get.md
@@ -1,6 +1,6 @@
---
title: Get
-description: Returns the value of the given parameter.
+description: Returns the value of the given argument.
categories: []
keywords: []
action:
@@ -8,44 +8,44 @@ action:
- methods/shortcode/IsNamedParams
- methods/shortcode/Params
returnType: any
- signatures: [SHORTCODE.Get PARAM]
+ signatures: [SHORTCODE.Get ARG]
toc: true
---
-Specify the parameter by position or by name. When calling a shortcode within markdown, use either positional or named parameters, but not both.
+Specify the argument by position or by name. When calling a shortcode within Markdown, use either positional or named argument, but not both.
{{% note %}}
-Some shortcodes support positional parameters, some support named parameters, and others support both. Refer to the shortcode's documentation for usage details.
+Some shortcodes support positional arguments, some support named arguments, and others support both. Refer to the shortcode's documentation for usage details.
{{% /note %}}
-## Positional parameters
+## Positional arguments
-This shortcode call uses positional parameters:
+This shortcode call uses positional arguments:
{{< code file=content/about.md lang=md >}}
{{}}
{{< /code >}}
-To retrieve parameters by position:
+To retrieve arguments by position:
{{< code file=layouts/shortcodes/myshortcode.html >}}
{{ printf "%s %s." (.Get 0) (.Get 1) }} → Hello world.
{{< /code >}}
-## Named parameters
+## Named arguments
-This shortcode call uses named parameters:
+This shortcode call uses named arguments:
{{< code file=content/about.md lang=md >}}
{{}}
{{< /code >}}
-To retrieve parameters by name:
+To retrieve arguments by name:
{{< code file=layouts/shortcodes/myshortcode.html >}}
{{ printf "%s %s." (.Get "greeting") (.Get "firstName") }} → Hello world.
{{< /code >}}
{{% note %}}
-Parameter names are case-sensitive.
+Argument names are case-sensitive.
{{% /note %}}
diff --git a/docs/content/en/methods/shortcode/Inner.md b/docs/content/en/methods/shortcode/Inner.md
index de7c284cb2c..9271adb34a0 100644
--- a/docs/content/en/methods/shortcode/Inner.md
+++ b/docs/content/en/methods/shortcode/Inner.md
@@ -46,13 +46,13 @@ Is rendered to:
```
{{% note %}}
-Content between opening and closing shortcode tags may include leading and/or trailing newlines, depending on placement within the markdown. Use the [`trim`] function as shown above to remove both carriage returns and newlines.
+Content between opening and closing shortcode tags may include leading and/or trailing newlines, depending on placement within the Markdown. Use the [`trim`] function as shown above to remove both carriage returns and newlines.
-[`trim`]: /functions/strings/trim
+[`trim`]: /functions/strings/trim/
{{% /note %}}
{{% note %}}
-In the example above, the value returned by `Inner` is markdown, but it was rendered as plain text. Use either of the following approaches to render markdown to HTML.
+In the example above, the value returned by `Inner` is Markdown, but it was rendered as plain text. Use either of the following approaches to render Markdown to HTML.
{{% /note %}}
@@ -60,7 +60,7 @@ In the example above, the value returned by `Inner` is markdown, but it was rend
Let's modify the example above to pass the value returned by `Inner` through the [`RenderString`] method on the `Page` object:
-[`RenderString`]: /methods/page/renderstring
+[`RenderString`]: /methods/page/renderstring/
{{< code file=layouts/shortcodes/card.html >}}
@@ -86,8 +86,8 @@ Hugo renders this to:
You can use the [`markdownify`] function instead of the `RenderString` method, but the latter is more flexible. See [details].
-[details]: /methods/page/renderstring
-[`markdownify`]: /functions/transform/markdownify
+[details]: /methods/page/renderstring/
+[`markdownify`]: /functions/transform/markdownify/
## Use alternate notation
@@ -99,9 +99,9 @@ We design the **best** widgets in the world.
{{%/* /card */%}}
{{< /code >}}
-When you use the `{{%/* */%}}` notation, Hugo renders the entire shortcode as markdown, requiring the following changes.
+When you use the `{{%/* */%}}` notation, Hugo renders the entire shortcode as Markdown, requiring the following changes.
-First, configure the renderer to allow raw HTML within markdown:
+First, configure the renderer to allow raw HTML within Markdown:
{{< code-toggle file=hugo >}}
[markup.goldmark.renderer]
@@ -110,7 +110,7 @@ unsafe = true
This configuration is not unsafe if _you_ control the content. Read more about Hugo's [security model].
-Second, because we are rendering the entire shortcode as markdown, we must adhere to the rules governing [indentation] and inclusion of [raw HTML blocks] as provided in the [CommonMark] specification.
+Second, because we are rendering the entire shortcode as Markdown, we must adhere to the rules governing [indentation] and inclusion of [raw HTML blocks] as provided in the [CommonMark] specification.
{{< code file=layouts/shortcodes/card.html >}}
@@ -150,4 +150,4 @@ When using the `{{%/* */%}}` notation, do not pass the value returned by `Inner`
[commonmark]: https://commonmark.org/
[indentation]: https://spec.commonmark.org/0.30/#indented-code-blocks
[raw html blocks]: https://spec.commonmark.org/0.30/#html-blocks
-[security model]: /about/security-model/
+[security model]: /about/security/
diff --git a/docs/content/en/methods/shortcode/InnerDeindent.md b/docs/content/en/methods/shortcode/InnerDeindent.md
index 136412bc75c..b5f5cf20614 100644
--- a/docs/content/en/methods/shortcode/InnerDeindent.md
+++ b/docs/content/en/methods/shortcode/InnerDeindent.md
@@ -14,7 +14,7 @@ Similar to the [`Inner`] method, `InnerDeindent` returns the content between ope
This allows us to effectively bypass the rules governing [indentation] as provided in the [CommonMark] specification.
-Consider this markdown, an unordered list with a small gallery of thumbnail images within each list item:
+Consider this Markdown, an unordered list with a small gallery of thumbnail images within each list item:
{{< code file=content/about.md lang=md >}}
- Gallery one
@@ -42,7 +42,7 @@ With this shortcode, calling `Inner` instead of `InnerDeindent`:
{{< /code >}}
-Hugo renders the markdown to:
+Hugo renders the Markdown to:
```html
@@ -73,7 +73,7 @@ Although technically correct per the CommonMark specification, this is not what
{{< /code >}}
-Hugo renders the markdown to:
+Hugo renders the Markdown to:
```html
@@ -96,4 +96,4 @@ Hugo renders the markdown to:
[commonmark]: https://commonmark.org/
[indentation]: https://spec.commonmark.org/0.30/#indented-code-blocks
-[`Inner`]: /methods/shortcode/inner
+[`Inner`]: /methods/shortcode/inner/
diff --git a/docs/content/en/methods/shortcode/IsNamedParams.md b/docs/content/en/methods/shortcode/IsNamedParams.md
index 83eeb2f74b7..a1d93ddac59 100644
--- a/docs/content/en/methods/shortcode/IsNamedParams.md
+++ b/docs/content/en/methods/shortcode/IsNamedParams.md
@@ -1,6 +1,6 @@
---
title: IsNamedParams
-description: Reports whether the shortcode call uses named parameters.
+description: Reports whether the shortcode call uses named arguments.
categories: []
keywords: []
action:
@@ -10,7 +10,7 @@ action:
signatures: [SHORTCODE.IsNamedParams]
---
-To support both positional and named parameters when calling a shortcode, use the `IsNamedParams` method to determine how the shortcode was called.
+To support both positional and named arguments when calling a shortcode, use the `IsNamedParams` method to determine how the shortcode was called.
With this shortcode template:
diff --git a/docs/content/en/methods/shortcode/Name.md b/docs/content/en/methods/shortcode/Name.md
index 18bddfe1f12..fcf92718f4e 100644
--- a/docs/content/en/methods/shortcode/Name.md
+++ b/docs/content/en/methods/shortcode/Name.md
@@ -11,19 +11,19 @@ action:
signatures: [SHORTCODE.Name]
---
-The `Name` method is useful for error reporting. For example, if your shortcode requires a "greeting" parameter:
+The `Name` method is useful for error reporting. For example, if your shortcode requires a "greeting" argument:
{{< code file=layouts/shortcodes/myshortcode.html >}}
{{ $greeting := "" }}
{{ with .Get "greeting" }}
{{ $greeting = . }}
{{ else }}
- {{ errorf "The %q shortcode requires a 'greeting' parameter. See %s" .Name .Position }}
+ {{ errorf "The %q shortcode requires a 'greeting' argument. See %s" .Name .Position }}
{{ end }}
{{< /code >}}
-In the absence of a "greeting" parameter, Hugo will throw an error message and fail the build:
+In the absence of a "greeting" argument, Hugo will throw an error message and fail the build:
```text
-ERROR The "myshortcode" shortcode requires a 'greeting' parameter. See "/home/user/project/content/about.md:11:1"
+ERROR The "myshortcode" shortcode requires a 'greeting' argument. See "/home/user/project/content/about.md:11:1"
```
diff --git a/docs/content/en/methods/shortcode/Ordinal.md b/docs/content/en/methods/shortcode/Ordinal.md
index 95494025886..6f3580d0fcf 100644
--- a/docs/content/en/methods/shortcode/Ordinal.md
+++ b/docs/content/en/methods/shortcode/Ordinal.md
@@ -32,7 +32,7 @@ This shortcode performs error checking, then renders an HTML `img` element with
{{ errorf "The %q shortcode was unable to find %s. See %s" $.Name $src $.Position }}
{{ end }}
{{ else }}
- {{ errorf "The %q shortcode requires a 'src' parameter. See %s" .Name .Position }}
+ {{ errorf "The %q shortcode requires a 'src' argument. See %s" .Name .Position }}
{{ end }}
{{< /code >}}
@@ -46,5 +46,5 @@ Hugo renders the page to:
{{% note %}}
In the shortcode template above, the [`with`] statement is used to create conditional blocks. Remember that the `with` statement binds context (the dot) to its expression. Inside of a `with` block, preface shortcode method calls with a `$` to access the top level context passed into the template.
-[`with`]: /functions/go-template/with
+[`with`]: /functions/go-template/with/
{{% /note %}}
diff --git a/docs/content/en/methods/shortcode/Params.md b/docs/content/en/methods/shortcode/Params.md
index 63df768a62a..c0772e36a3f 100644
--- a/docs/content/en/methods/shortcode/Params.md
+++ b/docs/content/en/methods/shortcode/Params.md
@@ -1,6 +1,6 @@
---
title: Params
-description: Returns a collection of the shortcode parameters.
+description: Returns a collection of the shortcode arguments.
categories: []
keywords: []
action:
@@ -10,7 +10,7 @@ action:
signatures: [SHORTCODE.Params]
---
-When you call a shortcode using positional parameters, the `Params` method returns a slice.
+When you call a shortcode using positional arguments, the `Params` method returns a slice.
{{< code file=content/about.md lang=md >}}
{{}}
@@ -21,7 +21,7 @@ When you call a shortcode using positional parameters, the `Params` method retur
{{ index .Params 1 }} → world
{{< /code >}}
-When you call a shortcode using named parameters, the `Params` method returns a map.
+When you call a shortcode using named arguments, the `Params` method returns a map.
{{< code file=content/about.md lang=md >}}
{{}}
diff --git a/docs/content/en/methods/shortcode/Parent.md b/docs/content/en/methods/shortcode/Parent.md
index 50ae521daf7..c500af3759d 100644
--- a/docs/content/en/methods/shortcode/Parent.md
+++ b/docs/content/en/methods/shortcode/Parent.md
@@ -9,7 +9,7 @@ action:
signatures: [SHORTCODE.Parent]
---
-This is useful for inheritance of common shortcode parameters from the root.
+This is useful for inheritance of common shortcode arguments from the root.
In this contrived example, the "greeting" shortcode is the parent, and the "now" shortcode is child.
@@ -45,6 +45,6 @@ Welcome. Today is {{}}.
The "now" shortcode formats the current time using:
-1. The `dateFormat` parameter passed to the "now" shortcode, if present
-2. The `dateFormat` parameter passed to the "greeting" shortcode, if present
+1. The `dateFormat` argument passed to the "now" shortcode, if present
+2. The `dateFormat` argument passed to the "greeting" shortcode, if present
3. The default layout string defined at the top of the shortcode
diff --git a/docs/content/en/methods/shortcode/Position.md b/docs/content/en/methods/shortcode/Position.md
index 565a158bfe5..6f047c01b1a 100644
--- a/docs/content/en/methods/shortcode/Position.md
+++ b/docs/content/en/methods/shortcode/Position.md
@@ -11,21 +11,21 @@ action:
signatures: [SHORTCODE.Position]
---
-The `Position` method is useful for error reporting. For example, if your shortcode requires a "greeting" parameter:
+The `Position` method is useful for error reporting. For example, if your shortcode requires a "greeting" argument:
{{< code file=layouts/shortcodes/myshortcode.html >}}
{{ $greeting := "" }}
{{ with .Get "greeting" }}
{{ $greeting = . }}
{{ else }}
- {{ errorf "The %q shortcode requires a 'greeting' parameter. See %s" .Name .Position }}
+ {{ errorf "The %q shortcode requires a 'greeting' argument. See %s" .Name .Position }}
{{ end }}
{{< /code >}}
-In the absence of a "greeting" parameter, Hugo will throw an error message and fail the build:
+In the absence of a "greeting" argument, Hugo will throw an error message and fail the build:
```text
-ERROR The "myshortcode" shortcode requires a 'greeting' parameter. See "/home/user/project/content/about.md:11:1"
+ERROR The "myshortcode" shortcode requires a 'greeting' argument. See "/home/user/project/content/about.md:11:1"
```
{{% note %}}
diff --git a/docs/content/en/methods/shortcode/Scratch.md b/docs/content/en/methods/shortcode/Scratch.md
index 3ab195a3f03..fcfc99d5386 100644
--- a/docs/content/en/methods/shortcode/Scratch.md
+++ b/docs/content/en/methods/shortcode/Scratch.md
@@ -1,6 +1,6 @@
---
title: Scratch
-description: Creates a "scratch pad" scoped to the shortcode to store and manipulate data.
+description: Returns a "scratch pad" scoped to the shortcode to store and manipulate data.
categories: []
keywords: []
action:
@@ -16,7 +16,7 @@ The `Scratch` method within a shortcode creates a [scratch pad] to store and man
With the introduction of the [`newScratch`] function, and the ability to [assign values to template variables] after initialization, the `Scratch` method within a shortcode is obsolete.
[assign values to template variables]: https://go.dev/doc/go1.11#text/template
-[`newScratch`]: functions/collections/newscratch
+[`newScratch`]: /functions/collections/newscratch/
{{% /note %}}
[scratch pad]: /getting-started/glossary/#scratch-pad
diff --git a/docs/content/en/methods/shortcode/Site.md b/docs/content/en/methods/shortcode/Site.md
index fa2d274deba..af2a755ee80 100644
--- a/docs/content/en/methods/shortcode/Site.md
+++ b/docs/content/en/methods/shortcode/Site.md
@@ -12,7 +12,7 @@ action:
See [Site methods].
-[Site methods]: /methods/site
+[Site methods]: /methods/site/
```go-html-template
{{ .Site.Title }}
diff --git a/docs/content/en/methods/site/AllPages.md b/docs/content/en/methods/site/AllPages.md
index 8df6348f9b5..e02c2cbbc15 100644
--- a/docs/content/en/methods/site/AllPages.md
+++ b/docs/content/en/methods/site/AllPages.md
@@ -16,7 +16,7 @@ This method returns all page [kinds] in all languages. That includes the home pa
In most cases you should use the [`RegularPages`] method instead.
-[`RegularPages`]: methods/site/regularpages
+[`RegularPages`]: /methods/site/regularpages/
[kinds]: /getting-started/glossary/#page-kind
```go-html-template
diff --git a/docs/content/en/methods/site/BaseURL.md b/docs/content/en/methods/site/BaseURL.md
index f9c43bca357..ea965a56889 100644
--- a/docs/content/en/methods/site/BaseURL.md
+++ b/docs/content/en/methods/site/BaseURL.md
@@ -30,8 +30,8 @@ There is almost never a good reason to use this method in your templates. Its us
Use the [`absURL`], [`absLangURL`], [`relURL`], or [`relLangURL`] functions instead.
-[`absURL`]: /functions/urls/absURL
-[`absLangURL`]: /functions/urls/absLangURL
-[`relURL`]: /functions/urls/relURL
-[`relLangURL`]: /functions/urls/relLangURL
+[`absURL`]: /functions/urls/absURL/
+[`absLangURL`]: /functions/urls/absLangURL/
+[`relURL`]: /functions/urls/relURL/
+[`relLangURL`]: /functions/urls/relLangURL/
{{% /note %}}
diff --git a/docs/content/en/methods/site/Data.md b/docs/content/en/methods/site/Data.md
index b78caddec5e..65cdadd0147 100644
--- a/docs/content/en/methods/site/Data.md
+++ b/docs/content/en/methods/site/Data.md
@@ -20,7 +20,7 @@ Use the `Data` method on a `Site` object to access data within the data director
{{% 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.
-[`transform.Unmarshal`]: /functions/transform/unmarshal
+[`transform.Unmarshal`]: /functions/transform/unmarshal/
{{% /note %}}
Consider this data directory:
@@ -101,8 +101,14 @@ To find a fiction book by ISBN:
{{ 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:
+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:
-[`index`]: /functions/collections/indexfunction
+[identifier]: /getting-started/glossary/#identifier
+
+```go-html-template
+{{ index .Site.Data.books "historical-fiction" }}
+```
+
+[`index`]: /functions/collections/indexfunction/
[chaining]: /getting-started/glossary/#chain
[identifiers]: /getting-started/glossary/#identifier
diff --git a/docs/content/en/methods/site/DisqusShortname.md b/docs/content/en/methods/site/DisqusShortname.md
index 2d444748504..0e900ac4ed5 100644
--- a/docs/content/en/methods/site/DisqusShortname.md
+++ b/docs/content/en/methods/site/DisqusShortname.md
@@ -13,5 +13,5 @@ expiryDate: 2024-10-30 # deprecated 2023-10-30
{{% deprecated-in 0.120.0 %}}
Use [`Site.Config.Services.Disqus.Shortname`] instead.
-[`Site.Config.Services.Disqus.Shortname`]: /methods/site/config
+[`Site.Config.Services.Disqus.Shortname`]: /methods/site/config/
{{% /deprecated-in %}}
diff --git a/docs/content/en/methods/site/GetPage.md b/docs/content/en/methods/site/GetPage.md
index b7d4b8f32f5..3505e582abd 100644
--- a/docs/content/en/methods/site/GetPage.md
+++ b/docs/content/en/methods/site/GetPage.md
@@ -13,7 +13,7 @@ toc: true
The `GetPage` method is also available on `Page` objects, allowing you to specify a path relative to the current page. See [details].
-[details]: /methods/page/getpage
+[details]: /methods/page/getpage/
When using the `GetPage` method on a `Site` object, specify a path relative to the content directory.
diff --git a/docs/content/en/methods/site/GoogleAnalytics.md b/docs/content/en/methods/site/GoogleAnalytics.md
index 50f479b492d..c5897445212 100644
--- a/docs/content/en/methods/site/GoogleAnalytics.md
+++ b/docs/content/en/methods/site/GoogleAnalytics.md
@@ -13,5 +13,5 @@ expiryDate: 2024-10-30 # deprecated 2023-10-30
{{% deprecated-in 0.120.0 %}}
Use [`Site.Config.Services.GoogleAnalytics.ID`] instead.
-[`Site.Config.Services.GoogleAnalytics.ID`]: /methods/site/config
+[`Site.Config.Services.GoogleAnalytics.ID`]: /methods/site/config/
{{% /deprecated-in %}}
diff --git a/docs/content/en/methods/site/IsDevelopment.md b/docs/content/en/methods/site/IsDevelopment.md
index c009ba0de95..6f443316ba9 100644
--- a/docs/content/en/methods/site/IsDevelopment.md
+++ b/docs/content/en/methods/site/IsDevelopment.md
@@ -13,7 +13,7 @@ expiryDate: 2024-10-30 # deprecated 2023-10-30
{{% deprecated-in 0.120.0 %}}
Use [`hugo.IsDevelopment`] instead.
-[`hugo.IsDevelopment`]: /functions/hugo/isdevelopment
+[`hugo.IsDevelopment`]: /functions/hugo/isdevelopment/
{{% /deprecated-in %}}
```go-html-template
diff --git a/docs/content/en/methods/site/IsMultiLingual.md b/docs/content/en/methods/site/IsMultiLingual.md
index 61cc5e46240..a14283787b1 100644
--- a/docs/content/en/methods/site/IsMultiLingual.md
+++ b/docs/content/en/methods/site/IsMultiLingual.md
@@ -1,6 +1,6 @@
---
title: IsMultiLingual
-description: Reports whether the site is multilingual.
+description: Reports whether there are two or more configured languages.
categories: []
keywords: []
action:
@@ -9,6 +9,12 @@ action:
signatures: [SITE.IsMultiLingual]
---
+{{% deprecated-in 0.124.0 %}}
+Use [`hugo.IsMultilingual`] instead.
+
+[`hugo.IsMultilingual`]: /functions/hugo/ismultilingual/
+{{% /deprecated-in %}}
+
Site configuration:
{{< code-toggle file=hugo >}}
diff --git a/docs/content/en/methods/site/IsServer.md b/docs/content/en/methods/site/IsServer.md
index 3d5ce41b56d..a688c553a5b 100644
--- a/docs/content/en/methods/site/IsServer.md
+++ b/docs/content/en/methods/site/IsServer.md
@@ -13,7 +13,7 @@ expiryDate: 2024-10-30 # deprecated 2023-10-30
{{% deprecated-in 0.120.0 %}}
Use [`hugo.IsServer`] instead.
-[`hugo.IsServer`]: /functions/hugo/isserver
+[`hugo.IsServer`]: /functions/hugo/isserver/
{{% /deprecated-in %}}
```go-html-template
diff --git a/docs/content/en/methods/site/Language.md b/docs/content/en/methods/site/Language.md
index 1babc099bbd..7179038e427 100644
--- a/docs/content/en/methods/site/Language.md
+++ b/docs/content/en/methods/site/Language.md
@@ -35,7 +35,7 @@ Lang
```
LanguageCode
-: (`string`) The language code from the site configuration.
+: (`string`) The language code from the site configuration. Falls back to `Lang` if not defined.
```go-html-template
{{ .Site.Language.LanguageCode }} → de-DE
@@ -68,16 +68,10 @@ Some of the methods above are commonly used in a base template as attributes for
```go-html-template
+
{{ debug.Dump .Site.Languages }}
```
With this site configuration:
diff --git a/docs/content/en/methods/site/LastChange.md b/docs/content/en/methods/site/LastChange.md
index aceee691d02..2a8c3e49152 100644
--- a/docs/content/en/methods/site/LastChange.md
+++ b/docs/content/en/methods/site/LastChange.md
@@ -9,13 +9,19 @@ action:
signatures: [SITE.LastChange]
---
+{{% deprecated-in 0.123.0 %}}
+Use [`.Site.Lastmod`] instead.
+
+[`.Site.Lastmod`]: /methods/site/lastmod/
+{{% /deprecated-in %}}
+
The `LastChange` method on a `Site` object returns a [`time.Time`] value. Use this with time [functions] and [methods]. For example:
```go-html-template
-{{ .Site.LastChange | time.Format ":date_long" }} → October 16, 2023
+{{ .Site.LastChange | time.Format ":date_long" }} → January 31, 2024
```
[`time.Time`]: https://pkg.go.dev/time#Time
-[functions]: /functions/time
-[methods]: /methods/time
+[functions]: /functions/time/
+[methods]: /methods/time/
diff --git a/docs/content/en/methods/site/Lastmod.md b/docs/content/en/methods/site/Lastmod.md
new file mode 100644
index 00000000000..08148195637
--- /dev/null
+++ b/docs/content/en/methods/site/Lastmod.md
@@ -0,0 +1,23 @@
+---
+title: Lastmod
+description: Returns the last modification date of site content.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: time.Time
+ signatures: [SITE.Lastmod]
+---
+
+{{< new-in 0.123.0 >}}
+
+The `Lastmod` method on a `Site` object returns a [`time.Time`] value. Use this with time [functions] and [methods]. For example:
+
+```go-html-template
+{{ .Site.Lastmod | time.Format ":date_long" }} → January 31, 2024
+
+```
+
+[`time.Time`]: https://pkg.go.dev/time#Time
+[functions]: /functions/time/
+[methods]: /methods/time/
diff --git a/docs/content/en/methods/site/Menus.md b/docs/content/en/methods/site/Menus.md
index c204fe97b2d..98ce4e879de 100644
--- a/docs/content/en/methods/site/Menus.md
+++ b/docs/content/en/methods/site/Menus.md
@@ -88,7 +88,7 @@ You will typically render a menu using a partial template. As the active menu en
The example above is simplistic. Please see the [menu templates] section for more information.
-[menu templates]: /templates/menu-templates
+[menu templates]: /templates/menu-templates/
-[`partial`]: /functions/partials/include
-[`partialCached`]: /functions/partials/includecached
+[`partial`]: /functions/partials/include/
+[`partialCached`]: /functions/partials/includecached/
diff --git a/docs/content/en/methods/site/Pages.md b/docs/content/en/methods/site/Pages.md
index 583e98c11c9..ac6e13c4a14 100644
--- a/docs/content/en/methods/site/Pages.md
+++ b/docs/content/en/methods/site/Pages.md
@@ -16,7 +16,7 @@ This method returns all page [kinds] in the current language. That includes the
In most cases you should use the [`RegularPages`] method instead.
-[`RegularPages`]: methods/site/regularpages
+[`RegularPages`]: /methods/site/regularpages/
[kinds]: /getting-started/glossary/#page-kind
```go-html-template
diff --git a/docs/content/en/methods/site/Params.md b/docs/content/en/methods/site/Params.md
index 518d93bf3e5..95e016b81e6 100644
--- a/docs/content/en/methods/site/Params.md
+++ b/docs/content/en/methods/site/Params.md
@@ -33,7 +33,7 @@ Access the custom parameters by [chaining] the [identifiers]:
{{ .Site.Params.author.name }} → John Smith
{{ $layout := .Site.Params.layouts.rfc_1123 }}
-{{ .Site.LastChange.Format $layout }} → Tue, 17 Oct 2023 13:21:02 PDT
+{{ .Site.Lastmod.Format $layout }} → Tue, 17 Oct 2023 13:21:02 PDT
```
In the template example 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:
@@ -42,6 +42,6 @@ In the template example above, each of the keys is a valid identifier. For examp
{{ index .Site.Params "copyright-year" }} → 2023
```
-[`index`]: /functions/collections/indexfunction
+[`index`]: /functions/collections/indexfunction/
[chaining]: /getting-started/glossary/#chain
[identifiers]: /getting-started/glossary/#identifier
diff --git a/docs/content/en/methods/site/Sites.md b/docs/content/en/methods/site/Sites.md
index f7bafd3ed2c..ac287d3b4df 100644
--- a/docs/content/en/methods/site/Sites.md
+++ b/docs/content/en/methods/site/Sites.md
@@ -1,6 +1,6 @@
---
title: Sites
-description: Returns a collection of all Site objects, one for each language, ordered by language weight.
+description: Returns a collection of all Site objects, one for each language, ordered by default content language then by language weight.
categories: []
keywords: []
action:
@@ -49,10 +49,10 @@ Produces a list of links to each home page:
```
-To render a link to home page of the primary (first) language:
+To render a link to the home page of the site corresponding to the default content language:
```go-html-template
-{{ with .Site.Sites.First }}
+{{ with .Site.Sites.Default }}
{{ .Title }}
{{ end }}
```
diff --git a/docs/content/en/methods/site/Taxonomies.md b/docs/content/en/methods/site/Taxonomies.md
index 72bfc75d56c..219fe188b11 100644
--- a/docs/content/en/methods/site/Taxonomies.md
+++ b/docs/content/en/methods/site/Taxonomies.md
@@ -95,5 +95,5 @@ Hugo's taxonomy system is powerful, allowing you to classify content and create
Please see the [taxonomies] section for a complete explanation and examples.
-[taxonomies]: content-management/taxonomies/
+[taxonomies]: /content-management/taxonomies/
{{% /note %}}
diff --git a/docs/content/en/methods/taxonomy/Alphabetical.md b/docs/content/en/methods/taxonomy/Alphabetical.md
index 7845dbf3d5e..ea90cfdf9df 100644
--- a/docs/content/en/methods/taxonomy/Alphabetical.md
+++ b/docs/content/en/methods/taxonomy/Alphabetical.md
@@ -34,7 +34,7 @@ To reverse the sort order:
To inspect the data structure:
```go-html-template
-
```
{{% include "methods/taxonomy/_common/ordered-taxonomy-element-methods.md" %}}
diff --git a/docs/content/en/methods/taxonomy/ByCount.md b/docs/content/en/methods/taxonomy/ByCount.md
index 40f58420a5b..68143ccff2f 100644
--- a/docs/content/en/methods/taxonomy/ByCount.md
+++ b/docs/content/en/methods/taxonomy/ByCount.md
@@ -34,7 +34,7 @@ To reverse the sort order:
To inspect the data structure:
```go-html-template
-
```
{{% include "methods/taxonomy/_common/ordered-taxonomy-element-methods.md" %}}
diff --git a/docs/content/en/methods/taxonomy/Get.md b/docs/content/en/methods/taxonomy/Get.md
index 3bac86f08a3..79d25b704bd 100644
--- a/docs/content/en/methods/taxonomy/Get.md
+++ b/docs/content/en/methods/taxonomy/Get.md
@@ -43,7 +43,7 @@ You could also use the [`index`] function, but the syntax is more verbose:
To inspect the data structure:
```go-html-template
-
{{ jsonify (dict "indent" " ") $weightedPages }}
+
{{ debug.Dump $weightedPages }}
```
## Example
@@ -66,7 +66,7 @@ Hugo renders:
```
[chaining]: /getting-started/glossary/#chain
-[`index`]: /functions/collections/indexfunction
+[`index`]: /functions/collections/indexfunction/
[identifier]: /getting-started/glossary/#identifier
[term]: /getting-started/glossary/#term
[weighted pages]: /getting-started/glossary/#weighted-page
diff --git a/docs/content/en/methods/taxonomy/Page.md b/docs/content/en/methods/taxonomy/Page.md
new file mode 100644
index 00000000000..e148ac5c70c
--- /dev/null
+++ b/docs/content/en/methods/taxonomy/Page.md
@@ -0,0 +1,26 @@
+---
+title: Page
+description: Returns the taxonomy page or nil if the taxonomy has no terms.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: page.Page
+ signatures: [TAXONOMY.Page]
+---
+
+{{< new-in 0.125.0 >}}
+
+This `TAXONOMY` method returns nil if the taxonomy has no terms, so you must code defensively:
+
+```go-html-template
+{{ with .Site.Taxonomies.tags.Page }}
+ {{ .LinkTitle }}
+{{ end }}
+```
+
+This is rendered to:
+
+```html
+Tags
+```
diff --git a/docs/content/en/methods/taxonomy/_common/_index.md b/docs/content/en/methods/taxonomy/_common/_index.md
index 47d5812fba5..4328d4d145b 100644
--- a/docs/content/en/methods/taxonomy/_common/_index.md
+++ b/docs/content/en/methods/taxonomy/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
diff --git a/docs/content/en/methods/taxonomy/_common/get-a-taxonomy-object.md b/docs/content/en/methods/taxonomy/_common/get-a-taxonomy-object.md
index 4c4fc42c91c..6bf86cd85a8 100644
--- a/docs/content/en/methods/taxonomy/_common/get-a-taxonomy-object.md
+++ b/docs/content/en/methods/taxonomy/_common/get-a-taxonomy-object.md
@@ -41,7 +41,7 @@ To capture the "genres" taxonomy object when rendering its page with a taxonomy
To inspect the data structure:
```go-html-template
-
{{ jsonify (dict "indent" " ") $taxonomyObject }}
+
{{ debug.Dump $taxonomyObject }}
```
Although the [`Alphabetical`] and [`ByCount`] methods provide a better data structure for ranging through the taxonomy, you can render the weighted pages by term directly from the `Taxonomy` object:
@@ -60,9 +60,9 @@ Although the [`Alphabetical`] and [`ByCount`] methods provide a better data stru
In the example above, the first anchor element is a link to the term page.
-[`Alphabetical`]: /methods/taxonomy/alphabetical
-[`ByCount`]: /methods/taxonomy/bycount
+[`Alphabetical`]: /methods/taxonomy/alphabetical/
+[`ByCount`]: /methods/taxonomy/bycount/
-[`data`]: /methods/page/data
+[`data`]: /methods/page/data/
[`terms`]: /methods/page/data/#in-a-taxonomy-template
-[`taxonomies`]: /methods/site/taxonomies
+[`taxonomies`]: /methods/site/taxonomies/
diff --git a/docs/content/en/methods/taxonomy/_common/ordered-taxonomy-element-methods.md b/docs/content/en/methods/taxonomy/_common/ordered-taxonomy-element-methods.md
index 9c94729ba7e..7201ad3188a 100644
--- a/docs/content/en/methods/taxonomy/_common/ordered-taxonomy-element-methods.md
+++ b/docs/content/en/methods/taxonomy/_common/ordered-taxonomy-element-methods.md
@@ -21,5 +21,5 @@ Term
WeightedPages
: (`page.WeightedPages`) Returns a slice of weighted pages to which the term is assigned, sorted by [taxonomic weight]. The `Pages` method above is more flexible, allowing you to sort and group.
-[methods]: /methods/pages
+[methods]: /methods/pages/
[taxonomic weight]: /getting-started/glossary/#taxonomic-weight
diff --git a/docs/content/en/methods/time/Format.md b/docs/content/en/methods/time/Format.md
index fc3e2635cec..d526b7b64f8 100644
--- a/docs/content/en/methods/time/Format.md
+++ b/docs/content/en/methods/time/Format.md
@@ -27,7 +27,7 @@ aliases: [/methods/time/format]
To [localize] the return value, use the [`time.Format`] function instead.
[localize]: /getting-started/glossary/#localization
-[`time.Format`]: /functions/time/format
+[`time.Format`]: /functions/time/format/
{{% /note %}}
Use the `Format` method with any `time.Time` value, including the four predefined front matter dates:
@@ -44,7 +44,7 @@ Use the `Format` method with any `time.Time` value, including the four predefine
{{% note %}}
Use the [`time.Format`] function to format string representations of dates, and to format raw TOML dates that exclude time and time zone offset.
-[`time.Format`]: /functions/time/format
+[`time.Format`]: /functions/time/format/
{{% /note %}}
## Layout string
diff --git a/docs/content/en/methods/time/Round.md b/docs/content/en/methods/time/Round.md
new file mode 100644
index 00000000000..988c56ba94e
--- /dev/null
+++ b/docs/content/en/methods/time/Round.md
@@ -0,0 +1,26 @@
+---
+title: Round
+description: Returns the result of rounding TIME to the nearest multiple of DURATION since January 1, 0001, 00:00:00 UTC.
+categories: []
+keywords: []
+action:
+ related:
+ - functions/time/AsTime
+ - functions/time/ParseDuration
+ - methods/time/Truncate
+ returnType: time.Time
+ signatures: [TIME.Round DURATION]
+---
+
+The rounding behavior for halfway values is to round up.
+
+The `Round` method operates on TIME as an absolute duration since the [zero time]; it does not operate on the presentation form of the time. If DURATION is a multiple of one hour, `Round` may return a time with a non-zero minute, depending on the time zone.
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $d := time.ParseDuration "1h"}}
+
+{{ ($t.Round $d).Format "2006-01-02T15:04:05-00:00" }} → 2023-01-28T00:00:00-00:00
+```
+
+[zero time]: /getting-started/glossary/#zero-time
diff --git a/docs/content/en/methods/time/Truncate.md b/docs/content/en/methods/time/Truncate.md
new file mode 100644
index 00000000000..da6e0b26bad
--- /dev/null
+++ b/docs/content/en/methods/time/Truncate.md
@@ -0,0 +1,24 @@
+---
+title: Truncate
+description: Returns the result of rounding TIME down to a multiple of DURATION since January 1, 0001, 00:00:00 UTC.
+categories: []
+keywords: []
+action:
+ related:
+ - functions/time/AsTime
+ - functions/time/ParseDuration
+ - methods/time/Round
+ returnType: time.Time
+ signatures: [TIME.Truncate DURATION]
+---
+
+The `Truncate` method operates on TIME as an absolute duration since the [zero time]; it does not operate on the presentation form of the time. If DURATION is a multiple of one hour, `Truncate` may return a time with a non-zero minute, depending on the time zone.
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $d := time.ParseDuration "1h"}}
+
+{{ ($t.Truncate $d).Format "2006-01-02T15:04:05-00:00" }} → 2023-01-27T23:00:00-00:00
+```
+
+[zero time]: /getting-started/glossary/#zero-time
diff --git a/docs/content/en/methods/time/YearDay.md b/docs/content/en/methods/time/YearDay.md
index 40d7d6aabc5..f380cdffe9e 100644
--- a/docs/content/en/methods/time/YearDay.md
+++ b/docs/content/en/methods/time/YearDay.md
@@ -1,6 +1,6 @@
---
title: YearDay
-description: Returns the day of the year of the given time.Time value, in the range [1, 365] for non-leap years, and [1,366] in leap years.
+description: Returns the day of the year of the given time.Time value, in the range [1, 365] for non-leap years, and [1, 366] in leap years.
categories: []
keywords: []
action:
diff --git a/docs/content/en/news/_index.md b/docs/content/en/news/_index.md
index e37c33a3cea..a1959bd1d49 100644
--- a/docs/content/en/news/_index.md
+++ b/docs/content/en/news/_index.md
@@ -1,4 +1,7 @@
---
-title: Hugo News
+title: News
+outputs:
+ - html
+ - rss
aliases: [/release-notes/]
---
diff --git a/docs/content/en/quick-reference/_index.md b/docs/content/en/quick-reference/_index.md
index 492cfa09b76..b5f434e2d77 100644
--- a/docs/content/en/quick-reference/_index.md
+++ b/docs/content/en/quick-reference/_index.md
@@ -1,12 +1,12 @@
---
title: Quick reference guides
-linkTitle: Overview
+linkTitle: In this section
description: Quick reference guides to Hugo's features, functions, and methods.
categories: []
keywords: []
menu:
docs:
- identifier: quick-reference-overview
+ identifier: quick-reference-in-this-section
parent: quick-reference
weight: 10
weight: 10
diff --git a/docs/content/en/quick-reference/emojis.md b/docs/content/en/quick-reference/emojis.md
index e6b1ed415f1..8ae01098be4 100644
--- a/docs/content/en/quick-reference/emojis.md
+++ b/docs/content/en/quick-reference/emojis.md
@@ -1,6 +1,6 @@
---
title: Emojis
-description: Include emoji shortcodes in your markdown or templates.
+description: Include emoji shortcodes in your Markdown or templates.
categories: [quick reference]
keywords: [emoji]
menu:
@@ -11,13 +11,13 @@ weight: 20
toc: true
---
-Configure Hugo to enable emoji processing in markdown:
+Configure Hugo to enable emoji processing in Markdown:
{{< code-toggle file=hugo >}}
enableEmoji = true
{{< /code-toggle >}}
-With emoji processing enabled, this markdown:
+With emoji processing enabled, this Markdown:
```md
Hello! :wave:
@@ -37,8 +37,8 @@ To process an emoji shortcode from within a template, use the [`emojify`] functi
{{ "Hello! :wave:" | .RenderString }}
```
-[`emojify`]: /functions/transform/emojify
-[`RenderString`]: /methods/page/renderstring
+[`emojify`]: /functions/transform/emojify/
+[`RenderString`]: /methods/page/renderstring/
## Introduction
diff --git a/docs/content/en/quick-reference/page-collections.md b/docs/content/en/quick-reference/page-collections.md
index 795eb494dc1..eca65a93e08 100644
--- a/docs/content/en/quick-reference/page-collections.md
+++ b/docs/content/en/quick-reference/page-collections.md
@@ -31,7 +31,7 @@ Use these `Site` methods when rendering lists on any page.
Use the [`where`] function to filter page collections.
-[`where`]: /functions/collections/where
+[`where`]: /functions/collections/where/
## Sort
diff --git a/docs/content/en/variables/_common/_index.md b/docs/content/en/render-hooks/_common/_index.md
similarity index 79%
rename from docs/content/en/variables/_common/_index.md
rename to docs/content/en/render-hooks/_common/_index.md
index 47d5812fba5..4328d4d145b 100644
--- a/docs/content/en/variables/_common/_index.md
+++ b/docs/content/en/render-hooks/_common/_index.md
@@ -7,7 +7,7 @@ cascade:
---
diff --git a/docs/content/en/render-hooks/_common/pageinner.md b/docs/content/en/render-hooks/_common/pageinner.md
new file mode 100644
index 00000000000..de1316cbab7
--- /dev/null
+++ b/docs/content/en/render-hooks/_common/pageinner.md
@@ -0,0 +1,42 @@
+---
+# Do not remove front matter.
+---
+
+## PageInner details
+
+{{< new-in 0.125.0 >}}
+
+The primary use case for `PageInner` is to resolve links and [page resources] relative to an included `Page`. For example, create an "include" shortcode to compose a page from multiple content files, while preserving a global context for footnotes and the table of contents:
+
+{{< code file=layouts/shortcodes/include.html >}}
+{{ with site.GetPage (.Get 0) }}
+ {{ .RenderShortcodes }}
+{{ end }}
+{{< /code >}}
+
+Then call the shortcode in your Markdown:
+
+{{< code file=content/posts/p1.md >}}
+{{%/* include "/posts/p2" */%}}
+{{< /code >}}
+
+Any render hook triggered while rendering `/posts/p2` will get:
+
+- `/posts/p1` when calling `Page`
+- `/posts/p2` when calling `PageInner`
+
+`PageInner` falls back to the value of `Page` if not relevant, and always returns a value.
+
+{{% note %}}
+The `PageInner` method is only relevant for shortcodes that invoke the [`RenderShortcodes`] method, and you must call the shortcode using the `{{%/*..*/%}}` notation.
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes/
+{{% /note %}}
+
+As a practical example, Hugo's embedded link and image render hooks use the `PageInner` method to resolve markdown link and image destinations. See the source code for each:
+
+- [Embedded link render hook]({{% eturl render-link %}})
+- [Embedded image render hook]({{% eturl render-image %}})
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes/
+[page resources]: /getting-started/glossary/#page-resource
diff --git a/docs/content/en/render-hooks/_index.md b/docs/content/en/render-hooks/_index.md
new file mode 100644
index 00000000000..8cf72c4e821
--- /dev/null
+++ b/docs/content/en/render-hooks/_index.md
@@ -0,0 +1,17 @@
+---
+title: Render hooks
+linkTitle: In this section
+description: Create render hooks to override the rendering of Markdown to HTML.
+categories: []
+keywords: []
+menu:
+ docs:
+ identifier: render-hooks-in-this-section
+ parent: render-hooks
+ weight: 10
+weight: 10
+showSectionMenu: false
+aliases: [/templates/render-hooks/]
+---
+
+Create render hooks to override the rendering of Markdown to HTML.
diff --git a/docs/content/en/render-hooks/code-blocks.md b/docs/content/en/render-hooks/code-blocks.md
new file mode 100755
index 00000000000..0c11c7864bb
--- /dev/null
+++ b/docs/content/en/render-hooks/code-blocks.md
@@ -0,0 +1,152 @@
+---
+title: Code block render hooks
+linkTitle: Code blocks
+description: Create a code block render hook to override the rendering of Markdown code blocks to HTML.
+categories: [render hooks]
+keywords: []
+menu:
+ docs:
+ parent: render-hooks
+ weight: 30
+weight: 30
+toc: true
+---
+
+## Markdown
+
+This Markdown example contains a fenced code block:
+
+{{< code file=content/example.md lang=text >}}
+```bash {class="my-class" id="my-codeblock" lineNos=inline tabWidth=2}
+declare a=1
+echo "$a"
+exit
+```
+{{< /code >}}
+
+A fenced code block consists of:
+
+- A leading [code fence]
+- An optional [info string]
+- A code sample
+- A trailing code fence
+
+[code fence]: https://spec.commonmark.org/0.31.2/#code-fence
+[info string]: https://spec.commonmark.org/0.31.2/#info-string
+
+In the previous example, the info string contains:
+
+- The language of the code sample (the first word)
+- An optional space-delimited or comma-delimited list of attributes (everything within braces)
+
+The attributes in the info string can be generic attributes or highlighting options.
+
+In the example above, the _generic attributes_ are `class` and `id`. In the absence of special handling within a code block render hook, Hugo adds each generic attribute to the HTML element surrounding the rendered code block. Consistent with its content security model, Hugo removes HTML event attributes such as `onclick` and `onmouseover`. Generic attributes are typically global HTML attributes, but you may include custom attributes as well.
+
+In the example above, the _highlighting options_ are `lineNos` and `tabWidth`. Hugo uses the [Chroma] syntax highlighter to render the code sample. You can control the appearance of the rendered code by specifying one or more [highlighting options].
+
+[Chroma]: https://github.com/alecthomas/chroma/
+[highlighting options]: /functions/transform/highlight/#options
+
+{{% note %}}
+Although `style` is a global HTML attribute, when used in an info string it is a highlighting option.
+{{% /note %}}
+
+## Context
+
+Code block render hook templates receive the following [context]:
+
+[context]: /getting-started/glossary/#context
+
+###### Attributes
+
+(`map`) The generic attributes from the info string.
+
+###### Inner
+
+(`string`) The content between the leading and trailing code fences, excluding the info string.
+
+###### Options
+
+(`map`) The highlighting options from the info string.
+
+###### Ordinal
+
+(`int`) The zero-based ordinal of the code block on the page.
+
+###### Page
+
+(`page`) A reference to the current page.
+
+###### PageInner
+
+{{< new-in 0.125.0 >}}
+
+(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes
+
+###### Position
+
+(`text.Position`) The position of the code block within the page content.
+
+###### Type
+
+(`string`) The first word of the info string, typically the code language.
+
+## Examples
+
+In its default configuration, Hugo renders fenced code blocks by passing the code sample through the Chroma syntax highlighter and wrapping the result. To create a render hook that does the same thing:
+
+[CommonMark specification]: https://spec.commonmark.org/current/
+
+{{< code file=layouts/_default/_markup/render-codeblock.html copy=true >}}
+{{ $result := transform.HighlightCodeBlock . }}
+{{ $result.Wrapped }}
+{{< /code >}}
+
+Although you can use one template with conditional logic to control the behavior on a per-language basis, you can also create language-specific templates.
+
+```text
+layouts/
+└── _default/
+ └── _markup/
+ ├── render-codeblock-mermaid.html
+ ├── render-codeblock-python.html
+ └── render-codeblock.html
+```
+
+For example, to create a code block render hook to render [Mermaid] diagrams:
+
+[Mermaid]: https://mermaid.js.org/
+
+{{< code file=layouts/_default/_markup/render-codeblock-mermaid.html copy=true >}}
+
+ {{- .Inner | safeHTML }}
+
+{{ .Page.Store.Set "hasMermaid" true }}
+{{< /code >}}
+
+Then include this snippet at the bottom of the your base template:
+
+{{< code file=layouts/_default/baseof.html copy=true >}}
+{{ if .Store.Get "hasMermaid" }}
+
+{{ end }}
+{{< /code >}}
+
+See the [diagrams] page for details.
+
+[diagrams]: /content-management/diagrams/#mermaid-diagrams
+
+## Embedded
+
+Hugo includes an [embedded code block render hook] to render [GoAT diagrams].
+
+[embedded code block render hook]: {{% eturl render-codeblock-goat %}}
+[GoAT diagrams]: /content-management/diagrams/#goat-diagrams-ascii
+
+{{% include "/render-hooks/_common/pageinner.md" %}}
diff --git a/docs/content/en/render-hooks/headings.md b/docs/content/en/render-hooks/headings.md
new file mode 100755
index 00000000000..c48bb11e183
--- /dev/null
+++ b/docs/content/en/render-hooks/headings.md
@@ -0,0 +1,79 @@
+---
+title: Heading render hooks
+linkTitle: Headings
+description: Create a heading render hook to override the rendering of Markdown headings to HTML.
+categories: [render hooks]
+keywords: []
+menu:
+ docs:
+ parent: render-hooks
+ weight: 40
+weight: 40
+toc: true
+---
+
+## Context
+
+Heading render hook templates receive the following [context]:
+
+[context]: /getting-started/glossary/#context
+
+###### Anchor
+
+(`string`) The `id` attribute of the heading element.
+
+###### Attributes
+
+(`map`) The Markdown attributes, available if you configure your site as follows:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.parser.attribute]
+title = true
+{{< /code-toggle >}}
+
+###### Level
+
+(`int`) The heading level, 1 through 6.
+
+###### Page
+
+(`page`) A reference to the current page.
+
+###### PageInner
+
+{{< new-in 0.125.0 >}}
+
+(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes
+
+###### PlainText
+
+(`string`) The heading text as plain text.
+
+###### Text
+
+(`string`) The heading text.
+
+## Examples
+
+In its default configuration, Hugo renders Markdown headings according to the [CommonMark specification] with the addition of automatic `id` attributes. To create a render hook that does the same thing:
+
+[CommonMark specification]: https://spec.commonmark.org/current/
+
+{{< code file=layouts/_default/_markup/render-heading.html copy=true >}}
+
+ {{- .Text | safeHTML -}}
+
+{{< /code >}}
+
+To add an anchor link to the right of each heading:
+
+{{< code file=layouts/_default/_markup/render-heading.html copy=true >}}
+
+ {{ .Text | safeHTML }}
+ #
+
+{{< /code >}}
+
+{{% include "/render-hooks/_common/pageinner.md" %}}
diff --git a/docs/content/en/render-hooks/images.md b/docs/content/en/render-hooks/images.md
new file mode 100755
index 00000000000..e68cd1b9515
--- /dev/null
+++ b/docs/content/en/render-hooks/images.md
@@ -0,0 +1,163 @@
+---
+title: Image render hooks
+linkTitle: Images
+description: Create an image render to hook override the rendering of Markdown images to HTML.
+categories: [render hooks]
+keywords: []
+menu:
+ docs:
+ parent: render-hooks
+ weight: 50
+weight: 50
+toc: true
+---
+
+## Markdown
+
+A Markdown image has three components: the image description, the image destination, and optionally the image title.
+
+```text
+
+ ------------ ------------------ ---------
+ description destination title
+```
+
+These components are passed into the render hook [context] as shown below.
+
+[context]: /getting-started/glossary/#context
+
+## Context
+
+Image render hook templates receive the following context:
+
+###### Attributes
+
+(`map`) The Markdown attributes, available if you configure your site as follows:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.parser]
+wrapStandAloneImageWithinParagraph = false
+[markup.goldmark.parser.attribute]
+block = true
+{{< /code-toggle >}}
+
+###### Destination
+
+(`string`) The image destination.
+
+###### IsBlock
+
+(`bool`) Returns true if a standalone image is not wrapped within a paragraph element.
+
+###### Ordinal
+
+(`int`) The zero-based ordinal of the image on the page.
+
+###### Page
+
+(`page`) A reference to the current page.
+
+###### PageInner
+
+{{< new-in 0.125.0 >}}
+
+(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes
+
+###### PlainText
+
+(`string`) The image description as plain text.
+
+###### Text
+
+(`string`) The image description.
+
+###### Title
+
+(`string`) The image title.
+
+## Examples
+
+{{% note %}}
+With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text.
+{{% /note %}}
+
+In its default configuration, Hugo renders Markdown images according to the [CommonMark specification]. To create a render hook that does the same thing:
+
+[CommonMark specification]: https://spec.commonmark.org/current/
+
+{{< code file=layouts/_default/_markup/render-image.html copy=true >}}
+
+{{- /* chomp trailing newline */ -}}
+{{< /code >}}
+
+To render standalone images within `figure` elements:
+
+{{< code file=layouts/_default/_markup/render-image.html copy=true >}}
+{{- if .IsBlock -}}
+
+
+ {{ .Title }}
+
+{{- else -}}
+
+{{- end -}}
+{{< /code >}}
+
+Note that the above requires the following site configuration:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.parser]
+wrapStandAloneImageWithinParagraph = false
+{{< /code-toggle >}}
+
+## Default
+
+{{< new-in 0.123.0 >}}
+
+Hugo includes an [embedded image render hook] to resolve Markdown image destinations. Disabled by default, you can enable it in your site configuration:
+
+[embedded image render hook]: {{% eturl render-image %}}
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.renderHooks.image]
+enableDefault = true
+{{< /code-toggle >}}
+
+A custom render hook, even when provided by a theme or module, will override the embedded render hook regardless of the configuration setting above.
+
+{{% note %}}
+The embedded image render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites.
+
+[duplication of shared page resources]: /getting-started/configuration-markup/#duplicateresourcefiles
+{{% /note %}}
+
+The embedded image render hook resolves internal Markdown destinations by looking for a matching [page resource], falling back to a matching [global resource]. Remote destinations are passed through, and the render hook will not throw an error or warning if it is unable to resolve a destination.
+
+[page resource]: /getting-started/glossary/#page-resource
+[global resource]: /getting-started/glossary/#global-resource
+
+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:
+
+{{< code-toggle file=hugo >}}
+[[module.mounts]]
+source = 'assets'
+target = 'assets'
+
+[[module.mounts]]
+source = 'static'
+target = 'assets'
+{{< /code-toggle >}}
+
+Note that the embedded image render hook does not perform image processing. Its sole purpose is to resolve Markdown image destinations.
+
+{{% include "/render-hooks/_common/pageinner.md" %}}
diff --git a/docs/content/en/render-hooks/introduction.md b/docs/content/en/render-hooks/introduction.md
new file mode 100755
index 00000000000..ebf95c00f15
--- /dev/null
+++ b/docs/content/en/render-hooks/introduction.md
@@ -0,0 +1,85 @@
+---
+title: Introduction
+description: An introduction to Hugo's render hooks.
+categories: [render hooks]
+keywords: []
+menu:
+ docs:
+ identifier: render-hooks-introduction
+ parent: render-hooks
+ weight: 20
+weight: 20
+---
+
+When rendering Markdown to HTML, render hooks override the conversion. Each render hook is a template, with one template for each supported element type:
+
+- [Code blocks](/render-hooks/code-blocks)
+- [Headings](/render-hooks/headings)
+- [Images](/render-hooks/images)
+- [Links](/render-hooks/links)
+
+{{% note %}}
+Hugo supports multiple [content formats] including Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, and reStructuredText.
+
+The render hook capability is limited to Markdown. You cannot create render hooks for the other content formats.
+
+[content formats]: /content-management/formats/
+{{% /note %}}
+
+For example, consider this Markdown:
+
+```text
+[Hugo](https://gohugo.io)
+
+
+```
+
+Without link or image render hooks, this example above is rendered to:
+
+```html
+
+```
+
+Each render hook is a template, with one template for each supported element type:
+
+```text
+layouts/
+└── _default/
+ └── _markup/
+ ├── render-codeblock.html
+ ├── render-heading.html
+ ├── render-image.html
+ └── render-link.html
+```
+
+The template lookup order allows you to create different render hooks for each page [type], [kind], language, and [output format]. For example:
+
+```text
+layouts/
+├── _default/
+│ └── _markup/
+│ ├── render-link.html
+│ └── render-link.text.txt
+├── books/
+│ └── _markup/
+│ ├── render-link.html
+│ └── render-link.text.txt
+└── films/
+ └── _markup/
+ ├── render-link.html
+ └── render-link.text.txt
+```
+
+[kind]: /getting-started/glossary/#page-kind
+[output format]: /getting-started/glossary/#output-format
+[type]: /getting-started/glossary/#content-type
+
+The remaining pages in this section describe each type of render hook, including examples and the context received by each template.
diff --git a/docs/content/en/render-hooks/links.md b/docs/content/en/render-hooks/links.md
new file mode 100755
index 00000000000..bf048506885
--- /dev/null
+++ b/docs/content/en/render-hooks/links.md
@@ -0,0 +1,133 @@
+---
+title: Link render hooks
+linkTitle: Links
+description: Create a link render hook to override the rendering of Markdown links to HTML.
+categories: [render hooks]
+keywords: []
+menu:
+ docs:
+ parent: render-hooks
+ weight: 60
+weight: 60
+toc: true
+---
+
+## Markdown
+
+A Markdown link has three components: the link text, the link destination, and optionally the link title.
+
+```text
+[Post 1](/posts/post-1 "My first post")
+ ------ ------------- -------------
+ text destination title
+```
+
+These components are passed into the render hook [context] as shown below.
+
+[context]: /getting-started/glossary/#context
+
+## Context
+
+Link render hook templates receive the following context:
+
+[context]: /getting-started/glossary/#context
+
+###### Destination
+
+(`string`) The link destination.
+
+###### Page
+
+(`page`) A reference to the current page.
+
+###### PageInner
+
+{{< new-in 0.125.0 >}}
+
+(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes
+
+###### PlainText
+
+(`string`) The link description as plain text.
+
+###### Text
+
+(`string`) The link description.
+
+###### Title
+
+(`string`) The link title.
+
+## Examples
+
+{{% note %}}
+With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text.
+{{% /note %}}
+
+In its default configuration, Hugo renders Markdown links according to the [CommonMark specification]. To create a render hook that does the same thing:
+
+[CommonMark specification]: https://spec.commonmark.org/current/
+
+{{< code file=layouts/_default/_markup/render-link.html copy=true >}}
+
+ {{- with .Text | safeHTML }}{{ . }}{{ end -}}
+
+{{- /* chomp trailing newline */ -}}
+{{< /code >}}
+
+To include a `rel` attribute set to `external` for external links:
+
+{{< code file=layouts/_default/_markup/render-link.html copy=true >}}
+{{- $u := urls.Parse .Destination -}}
+
+ {{- with .Text | safeHTML }}{{ . }}{{ end -}}
+
+{{- /* chomp trailing newline */ -}}
+{{< /code >}}
+
+## Default
+
+{{< new-in 0.123.0 >}}
+
+Hugo includes an [embedded link render hook] to resolve Markdown link destinations. Disabled by default, you can enable it in your site configuration:
+
+[embedded link render hook]: {{% eturl render-link %}}
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.renderHooks.link]
+enableDefault = true
+{{< /code-toggle >}}
+
+A custom render hook, even when provided by a theme or module, will override the embedded render hook regardless of the configuration setting above.
+
+{{% note %}}
+The embedded link render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites.
+
+[duplication of shared page resources]: /getting-started/configuration-markup/#duplicateresourcefiles
+{{% /note %}}
+
+The embedded link render hook resolves internal Markdown destinations by looking for a matching page, falling back to a matching [page resource], then falling back to a matching [global resource]. Remote destinations are passed through, and the render hook will not throw an error or warning if it is unable to resolve a destination.
+
+[page resource]: /getting-started/glossary/#page-resource
+[global resource]: /getting-started/glossary/#global-resource
+
+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:
+
+{{< code-toggle file=hugo >}}
+[[module.mounts]]
+source = 'assets'
+target = 'assets'
+
+[[module.mounts]]
+source = 'static'
+target = 'assets'
+{{< /code-toggle >}}
+
+{{% include "/render-hooks/_common/pageinner.md" %}}
diff --git a/docs/content/en/showcase/forestry/index.md b/docs/content/en/showcase/forestry/index.md
index 32a932a7a86..fabcb7cd3e0 100644
--- a/docs/content/en/showcase/forestry/index.md
+++ b/docs/content/en/showcase/forestry/index.md
@@ -36,7 +36,7 @@ Lastly, we want to take the opportunity to give some love to other amazing tools
### What tools did we use?
* Our Norwegian designer Nichlas is in love with [**Sketch**](https://www.sketchapp.com/). From what we hear it’s a designer’s dream come true.
-* Some say our main graphic is [mesmerizing](https://twitter.com/hmncllctv/status/968907474664284160). Nichlas created it using [**3DS Max**](https://www.autodesk.com/products/3ds-max/overview).
+* Some say our main graphic is [mesmerizing](https://x.com/hmncllctv/status/968907474664284160). Nichlas created it using [**3DS Max**](https://www.autodesk.com/products/3ds-max/overview).
* [**Hugo**](https://gohugo.io/) -- of course.
* Chris can’t think of modern web development without [**Gulp**](https://gulpjs.com/) & [**Webpack**](https://webpack.js.org/). We used them to add additional build steps such as Browsersync, CSS, JS and SVG optimization.
* Speaking about adding steps to our build, our lives would be much harder without [**CircleCI**](https://circleci.com/) for continuous deployment and automated testing purposes.
diff --git a/docs/content/en/showcase/keycdn/index.md b/docs/content/en/showcase/keycdn/index.md
index d092aa07d5d..6308b34c46b 100644
--- a/docs/content/en/showcase/keycdn/index.md
+++ b/docs/content/en/showcase/keycdn/index.md
@@ -26,5 +26,5 @@ Below is an overview of what we used with Hugo to build our website:
* Our search is powered by a custom solution that we’ve built. It allows our pages, blog, and knowledge base to be searched. It uses [Axios](https://github.com/axios/axios) to send a `POST` request containing the search query. An index file in JSON generated by Hugo is searched and the results are then returned.
* Our commenting system is also powered by a custom solution that we’ve built. It uses Axios to send a `GET` request containing the slug to pull the comment thread and a `POST` request containing the name, email address, and comment when submitting a comment.
* Our contact form is a simple HTML form, which uses Axios as well.
-* Our writers use shortcodes to enhance the capability of markdown.
+* Our writers use shortcodes to enhance the capability of Markdown.
* Our entire website is delivered through KeyCDN using a Pull Zone, which means all of our edge locations are delivering our website.
diff --git a/docs/content/en/showcase/quiply-employee-communications-app/index.md b/docs/content/en/showcase/quiply-employee-communications-app/index.md
index a8c31cc33e7..e1e426ed26c 100644
--- a/docs/content/en/showcase/quiply-employee-communications-app/index.md
+++ b/docs/content/en/showcase/quiply-employee-communications-app/index.md
@@ -24,6 +24,6 @@ With the launch of our Employee Communications app Quiply we created a very simp
As our customer base and demand for marketing and communication started to grow, we needed a solution to easily grow and extend the contents of our web presence. As we do not have the need to serve dynamic content, we decided to use a static site generator. Amongst a couple of others, we tried Hugo and it became immediately clear that we'd use Hugo going forward as it compiles super-fast, is intuitive to use and offers all the features we need.
-Our website which we launched a couple of weeks ago is still growing and new content is being added constantly. By using Hugo, this can be easily done by content authors writing markdown files without always having to touch HTML or CSS code. It is available in German only for the time being, an English version is in the works.
+Our website which we launched a couple of weeks ago is still growing and new content is being added constantly. By using Hugo, this can be easily done by content authors writing Markdown files without always having to touch HTML or CSS code. It is available in German only for the time being, an English version is in the works.
Huge thanks to everyone involved in making Hugo a success.
diff --git a/docs/content/en/templates/404.md b/docs/content/en/templates/404.md
index 7fd27a35825..44858f8b151 100644
--- a/docs/content/en/templates/404.md
+++ b/docs/content/en/templates/404.md
@@ -1,7 +1,7 @@
---
title: Custom 404 page
-linkTitle: 404 page
-description: If you know how to create a single page template, you have unlimited options for creating a custom 404.
+linkTitle: 404 template
+description: Create a template to render a 404 error page.
categories: [templates]
keywords: ['404',page not found]
menu:
@@ -11,45 +11,43 @@ menu:
weight: 220
---
-When using Hugo with [GitHub Pages](https://pages.github.com/), you can provide your own template for a [custom 404 error page](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-custom-404-page-for-your-github-pages-site) by creating a 404.html template file in the root of your `layouts` folder. When Hugo generates your site, the `404.html` file will be placed in the root.
-
-404 pages will have all the regular [page variables][pagevars] available to use in the templates.
-
-In addition to the standard page variables, the 404 page has access to all site content accessible from `.Pages`.
-
-```txt
-▾ layouts/
- 404.html
-```
-
-## 404.html
-
-This is a basic example of a 404.html template:
+To render a 404 error page in the root of your site, create a 404 template in the root of the layouts directory. For example:
{{< code file=layouts/404.html >}}
{{ define "main" }}
-
-
{{ end }}
{{< /code >}}
-## Automatic loading
+For multilingual sites, add the language key to the file name:
-Your 404.html file can be set to load automatically when a visitor enters a mistaken URL path, dependent upon the web serving environment you are using. For example:
-
-* [GitHub Pages](/hosting-and-deployment/hosting-on-github/), [GitLab Pages](/hosting-and-deployment/hosting-on-gitlab/) and [Cloudflare Pages](/hosting-and-deployment/hosting-on-cloudflare-pages/). The 404 page is automatic.
-* Apache. You can specify `ErrorDocument 404 /404.html` in an `.htaccess` file in the root of your site.
-* Nginx. You might specify `error_page 404 /404.html;` in your `nginx.conf` file. [Details here](https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page).
-* Amazon AWS S3. When setting a bucket up for static web serving, you can specify the error file from within the S3 GUI.
-* Amazon CloudFront. You can specify the page in the Error Pages section in the CloudFront Console. [Details here](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/custom-error-pages.html)
-* Caddy Server. Use the `handle_errors` directive to specify error pages for one or more status codes. [Details here](https://caddyserver.com/docs/caddyfile/directives/handle_errors)
-* Netlify. Add `/* /404.html 404` to `content/_redirects`. [Details Here](https://www.netlify.com/docs/redirects/#custom-404)
-* Azure Static Web App. set `responseOverrides.404.rewrite` and `responseOverrides.404.statusCode` in configfile `staticwebapp.config.json`. [Details here](https://docs.microsoft.com/en-us/azure/static-web-apps/configuration#response-overrides)
-* Azure Storage as Static Web Site Hosting. You can specify the `Error document path` in the Static website configuration page of the Azure portal. [Details here](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website).
-* DigitalOcean App Platform. You can specify `error_document` in your app specification file or use control panel to set up error document. [Details here](https://docs.digitalocean.com/products/app-platform/how-to/manage-static-sites/#configure-a-static-site).
-* [Firebase Hosting](https://firebase.google.com/docs/hosting/full-config#404): `/404.html` automatically gets used as the 404 page.
+```text
+layouts/
+├── 404.de.html
+├── 404.en.html
+└── 404.fr.html
+```
-[pagevars]: /variables/page/
+Your production server redirects the browser to the 404 page when a page is not found. Capabilities and configuration vary by host.
+
+Host|Capabilities and configuration
+:--|:--
+Amazon CloudFront|See [details](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/GeneratingCustomErrorResponses.html).
+Amazon S3|See [details](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CustomErrorDocSupport.html).
+Apache|See [details](https://httpd.apache.org/docs/2.4/custom-error.html).
+Azure Static Web Apps|See [details](https://learn.microsoft.com/en-us/azure/static-web-apps/configuration#response-overrides).
+Azure Storage|See [details](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website#setting-up-a-static-website).
+Caddy|See [deatils](https://caddyserver.com/docs/caddyfile/directives/handle_errors).
+Cloudflare Pages|See [details](https://developers.cloudflare.com/pages/configuration/serving-pages/#not-found-behavior).
+DigitalOcean App Platform|See [details](https://docs.digitalocean.com/products/app-platform/how-to/manage-static-sites/#configure-a-static-site).
+Firebase|See [details](https://firebase.google.com/docs/hosting/full-config#404).
+GitHub Pages|Redirection to is automatic and not configurable.
+GitLab Pages|See [details](https://docs.gitlab.com/ee/user/project/pages/introduction.html#custom-error-codes-pages).
+NGINX|See [details](https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page).
+Netlify|See [details](https://docs.netlify.com/routing/redirects/redirect-options/).
diff --git a/docs/content/en/templates/_index.md b/docs/content/en/templates/_index.md
index b2197d162cf..23b2a3eaf62 100644
--- a/docs/content/en/templates/_index.md
+++ b/docs/content/en/templates/_index.md
@@ -1,12 +1,12 @@
---
title: Templates
-linkTitle: Overview
+linkTitle: In this section
description: Go templating, template types and lookup order, shortcodes, and data.
categories: []
keywords: []
menu:
docs:
- identifier: templates-overview
+ identifier: templates-in-this-section
parent: templates
weight: 10
weight: 10
diff --git a/docs/content/en/templates/base.md b/docs/content/en/templates/base.md
index 63bf2f9b293..6262e74b878 100644
--- a/docs/content/en/templates/base.md
+++ b/docs/content/en/templates/base.md
@@ -91,7 +91,7 @@ The following shows how you can override both the `"main"` and `"title"` block a
{{ end }}
{{< /code >}}
-[hugolists]: /templates/lists
+[hugolists]: /templates/lists/
[lookup]: /templates/lookup-order/
[rendering the section]: /templates/section-templates/
[singletemplate]: /templates/single-page-templates/
diff --git a/docs/content/en/templates/data-templates.md b/docs/content/en/templates/data-templates.md
deleted file mode 100644
index 435bd70b221..00000000000
--- a/docs/content/en/templates/data-templates.md
+++ /dev/null
@@ -1,177 +0,0 @@
----
-title: Data templates
-description: In addition to Hugo's built-in variables, you can specify your own custom data in templates or shortcodes that pull from both local and dynamic sources.
-categories: [templates]
-keywords: [data,dynamic,csv,json,toml,yaml,xml]
-menu:
- docs:
- parent: templates
- weight: 150
-weight: 150
-toc: true
-aliases: [/extras/datafiles/,/extras/datadrivencontent/,/doc/datafiles/]
----
-
-Hugo supports loading data from YAML, JSON, XML, and TOML files located in the `data` directory at the root of your Hugo project.
-
-{{< youtube FyPgSuwIMWQ >}}
-
-## The data directory
-
-The `data` directory should store additional data for Hugo to use when generating your site.
-
-Data files are not for generating standalone pages. They should supplement content files by:
-
-- Extending the content when the front matter fields grow out of control, or
-- Showing a larger dataset in a template (see the example below).
-
-In both cases, it's a good idea to outsource the data in their (own) files.
-
-These files must be YAML, JSON, XML, or TOML files (using the `.yml`, `.yaml`, `.json`, `.xml`, or `.toml` extension). The data will be accessible as a `map` in the `.Site.Data` variable.
-
-To access the data using the `site.Data.filename` notation, the file name must begin with an underscore or a Unicode letter, followed by zero or more underscores, Unicode letters, or Unicode digits. For example:
-
-- `123.json` - Invalid
-- `x123.json` - Valid
-- `_123.json` - Valid
-
-To access the data using the [`index`](/functions/collections/indexfunction) function, the file name is irrelevant. For example:
-
-Data file|Template code
-:--|:--
-`123.json`|`{{ index .Site.Data "123" }}`
-`x123.json`|`{{ index .Site.Data "x123" }}`
-`_123.json`|`{{ index .Site.Data "_123" }}`
-`x-123.json`|`{{ index .Site.Data "x-123" }}`
-
-## Data files in themes
-
-Data Files can also be used in themes.
-
-However, note that the theme data files are merged with the project directory taking precedence. That is, Given two files with the same name and relative path, the data in the file in the root project `data` directory will override the data from the file in the `themes//data` directory *for keys that are duplicated*).
-
-Therefore, theme authors should be careful not to include data files that could be easily overwritten by a user who decides to [customize a theme][customize]. For theme-specific data items that shouldn't be overridden, it can be wise to prefix the folder structure with a namespace; e.g. `mytheme/data//somekey/...`. To check if any such duplicate exists, run hugo with the `-v` flag.
-
-The keys in the map created with data templates from data files will be a dot-chained set of `path`, `filename`, and `key` in the file (if applicable).
-
-This is best explained with an example:
-
-## Examples
-
-### Jaco Pastorius' Solo Discography
-
-[Jaco Pastorius](https://en.wikipedia.org/wiki/Jaco_Pastorius_discography) was a great bass player, but his solo discography is short enough to use as an example. [John Patitucci](https://en.wikipedia.org/wiki/John_Patitucci) is another bass giant.
-
-The example below is a bit contrived, but it illustrates the flexibility of data Files. This example uses TOML as its file format with the two following data files:
-
-* `data/jazz/bass/jacopastorius.toml`
-* `data/jazz/bass/johnpatitucci.toml`
-
-`jacopastorius.toml` contains the content below. `johnpatitucci.toml` contains a similar list:
-
-{{< code-toggle file=data/jazz/bass/jacopastorius >}}
-discography = [
-"1974 - Modern American Music … Period! The Criteria Sessions",
-"1974 - Jaco",
-"1976 - Jaco Pastorius",
-"1981 - Word of Mouth",
-"1981 - The Birthday Concert (released in 1995)",
-"1982 - Twins I & II (released in 1999)",
-"1983 - Invitation",
-"1986 - Broadway Blues (released in 1998)",
-"1986 - Honestly Solo Live (released in 1990)",
-"1986 - Live In Italy (released in 1991)",
-"1986 - Heavy'n Jazz (released in 1992)",
-"1991 - Live In New York City, Volumes 1-7.",
-"1999 - Rare Collection (compilation)",
-"2003 - Punk Jazz: The Jaco Pastorius Anthology (compilation)",
-"2007 - The Essential Jaco Pastorius (compilation)"
-]
-{{< /code-toggle >}}
-
-The list of bass players can be accessed via `.Site.Data.jazz.bass`, a single bass player by adding the file name without the suffix, e.g. `.Site.Data.jazz.bass.jacopastorius`.
-
-You can now render the list of recordings for all the bass players in a template:
-
-```go-html-template
-{{ range $.Site.Data.jazz.bass }}
- {{ partial "artist.html" . }}
-{{ end }}
-```
-
-And then in the `partials/artist.html`:
-
-```go-html-template
-
-{{ range .discography }}
-
{{ . }}
-{{ end }}
-
-```
-
-Discover a new favorite bass player? Just add another `.toml` file in the same directory.
-
-### Accessing named values in a data file
-
-Assume you have the following data structure in your `user0123` data file located directly in `data/`:
-
-{{< code-toggle file=data/user0123 >}}
-Name: User0123
-"Short Description": "He is a **jolly good** fellow."
-Achievements:
- - "Can create a Key, Value list from Data File"
- - "Learns Hugo"
- - "Reads documentation"
-{{}}
-
-You can use the following code to render the `Short Description` in your layout:
-
-```go-html-template
-
Short Description of {{ .Site.Data.user0123.Name }}:
{{ index .Site.Data.user0123 "Short Description" | markdownify }}
-```
-
-Note the use of the [`markdownify`] function. This will send the description through the Markdown rendering engine.
-
-## Remote data
-
-Retrieve remote data using these template functions:
-
-- [`resources.GetRemote`](/functions/resources/getremote) (recommended)
-- [`data.GetCSV`](/functions/data/getcsv)
-- [`data.GetJSON`](/functions/data/getjson)
-
-## LiveReload with data files
-
-There is no chance to trigger a [LiveReload] when the content of a URL changes. However, when a *local* file changes (i.e., `data/*` and `themes//data/*`), a LiveReload will be triggered. Symlinks are not supported. Note too that because downloading data takes a while, Hugo stops processing your Markdown files until the data download has been completed.
-
-{{% note %}}
-If you change any local file and the LiveReload is triggered, Hugo will read the data-driven (URL) content from the cache. If you have disabled the cache (i.e., by running the server with `hugo server --ignoreCache`), Hugo will re-download the content every time LiveReload triggers. This can create *huge* traffic. You may reach API limits quickly.
-{{% /note %}}
-
-## Examples of data-driven content
-
-- Photo gallery JSON powered: [https://github.com/pcdummy/hugo-lightslider-example](https://github.com/pcdummy/hugo-lightslider-example)
-- GitHub Starred Repositories [in a post](https://github.com/SchumacherFM/blog-cs/blob/master/content%2Fposts%2Fgithub-starred.md) using data-driven content in a [custom short code](https://github.com/SchumacherFM/blog-cs/blob/master/layouts%2Fshortcodes%2FghStarred.html).
-
-## Specs for data formats
-
-* [TOML Spec][toml]
-* [YAML Spec][yaml]
-* [JSON Spec][json]
-* [CSV Spec][csv]
-* [XML Spec][xml]
-
-[config]: /getting-started/configuration/
-[csv]: https://tools.ietf.org/html/rfc4180
-[customize]: /hugo-modules/theme-components/
-[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf
-[LiveReload]: /getting-started/usage/#livereload
-[lookup]: /templates/lookup-order/
-[`markdownify`]: /functions/transform/markdownify
-[OAuth]: https://en.wikipedia.org/wiki/OAuth
-[partials]: /templates/partials/
-[toml]: https://toml.io/en/latest
-[variadic]: https://en.wikipedia.org/wiki/Variadic_function
-[vars]: /variables/
-[yaml]: https://yaml.org/spec/
-[xml]: https://www.w3.org/XML/
diff --git a/docs/content/en/templates/embedded.md b/docs/content/en/templates/embedded.md
new file mode 100644
index 00000000000..5b2043962d6
--- /dev/null
+++ b/docs/content/en/templates/embedded.md
@@ -0,0 +1,223 @@
+---
+title: Embedded templates
+description: Hugo provides embedded templates for common use cases.
+categories: [templates]
+keywords: [internal, analytics,]
+menu:
+ docs:
+ parent: templates
+ weight: 190
+weight: 190
+toc: true
+aliases: [/templates/internal]
+---
+
+## Disqus
+
+{{% note %}}
+To override Hugo's embedded Disqus template, copy the [source code] to a file with the same name in the layouts/partials directory, then call it from your templates using the [`partial`] function:
+
+`{{ partial "disqus.html" . }}`
+
+[`partial`]: /functions/partials/include/
+[source code]: {{% eturl disqus %}}
+{{% /note %}}
+
+Hugo includes an embedded template for [Disqus], a popular commenting system for both static and dynamic websites. To effectively use Disqus, secure a Disqus "shortname" by [signing up] for the free service.
+
+[Disqus]: https://disqus.com
+[signing up]: https://disqus.com/profile/signup/
+
+To include the embedded template:
+
+```go-html-template
+{{ template "_internal/disqus.html" . }}
+```
+
+### Configure Disqus
+
+To use Hugo's Disqus template, first set up a single configuration value:
+
+{{< code-toggle file="hugo" >}}
+[services.disqus]
+shortname = 'your-disqus-shortname'
+{{}}
+
+Hugo's Disqus template accesses this value with:
+
+```go-html-template
+{{ .Site.Config.Services.Disqus.Shortname }}
+```
+
+You can also set the following in the front matter for a given piece of content:
+
+- `disqus_identifier`
+- `disqus_title`
+- `disqus_url`
+
+## Google Analytics
+
+{{% note %}}
+To override Hugo's embedded Google Analytics template, copy the [source code] to a file with the same name in the layouts/partials directory, then call it from your templates using the [`partial`] function:
+
+`{{ partial "google_analytics.html" . }}`
+
+[`partial`]: /functions/partials/include/
+[source code]: {{% eturl google_analytics %}}
+{{% /note %}}
+
+Hugo includes an embedded template supporting [Google Analytics 4].
+
+[Google Analytics 4]: https://support.google.com/analytics/answer/10089681
+
+To include the embedded template:
+
+```go-html-template
+{{ template "_internal/google_analytics.html" . }}
+```
+
+### Configure Google Analytics
+
+Provide your tracking ID in your configuration file:
+
+{{< code-toggle file=hugo >}}
+[services.googleAnalytics]
+ID = "G-MEASUREMENT_ID"
+{{}}
+
+To use this value in your own template, access the configured ID with `{{ site.Config.Services.GoogleAnalytics.ID }}`.
+
+## Open Graph
+
+{{% note %}}
+To override Hugo's embedded Open Graph template, copy the [source code] to a file with the same name in the layouts/partials directory, then call it from your templates using the [`partial`] function:
+
+`{{ partial "opengraph.html" . }}`
+
+[`partial`]: /functions/partials/include/
+[source code]: {{% eturl opengraph %}}
+{{% /note %}}
+
+Hugo includes an embedded template for the [Open Graph protocol](https://ogp.me/), metadata that enables a page to become a rich object in a social graph.
+This format is used for Facebook and some other sites.
+
+To include the embedded template:
+
+```go-html-template
+{{ template "_internal/opengraph.html" . }}
+```
+
+### Configure Open Graph
+
+Hugo's Open Graph template is configured using a mix of configuration settings and [front matter](/content-management/front-matter/) on individual pages.
+
+{{< code-toggle file=hugo >}}
+[params]
+ description = 'Text about my cool site'
+ images = ['site-feature-image.jpg']
+ title = 'My cool site'
+ [params.social]
+ facebook_admin = 'jsmith'
+[taxonomies]
+ series = 'series'
+{{}}
+
+{{< code-toggle file=content/blog/my-post.md fm=true >}}
+title = "Post title"
+description = "Text about this post"
+date = 2024-03-08T08:18:11-08:00
+images = ["post-cover.png"]
+audio = []
+videos = []
+series = []
+tags = []
+{{}}
+
+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*` or `*cover*,*thumbnail*` are used for image metadata.
+
+Various optional metadata can also be set:
+
+- Date, published date, and last modified data are used to set the published time metadata if specified.
+- `audio` and `videos` are URL arrays like `images` for the audio and video metadata tags, respectively.
+- The first 6 `tags` on the page are used for the tags metadata.
+- The `series` taxonomy is used to specify related "see also" pages by placing them in the same series.
+
+If using YouTube this will produce a og:video tag like ``. Use the `https://youtu.be/` format with YouTube videos (example: `https://youtu.be/qtIqKaDlqXo`).
+
+## Schema
+
+{{% note %}}
+To override Hugo's embedded Schema template, copy the [source code] to a file with the same name in the layouts/partials directory, then call it from your templates using the [`partial`] function:
+
+`{{ partial "schema.html" . }}`
+
+[`partial`]: /functions/partials/include/
+[source code]: {{% eturl schema %}}
+{{% /note %}}
+
+Hugo includes an embedded template to render [microdata] `meta` elements within the `head` element of your templates.
+
+[microdata]: https://html.spec.whatwg.org/multipage/microdata.html#microdata
+
+To include the embedded template:
+
+```go-html-template
+{{ template "_internal/schema.html" . }}
+```
+
+## X (Twitter) Cards
+
+{{% note %}}
+To override Hugo's embedded Twitter Cards template, copy the [source code] to a file with the same name in the layouts/partials directory, then call it from your templates using the [`partial`] function:
+
+`{{ partial "twitter_cards.html" . }}`
+
+[`partial`]: /functions/partials/include/
+[source code]: {{% eturl twitter_cards %}}
+{{% /note %}}
+
+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:
+
+```go-html-template
+{{ template "_internal/twitter_cards.html" . }}
+```
+
+### Configure X (Twitter) Cards
+
+Hugo's X (Twitter) Card template is configured using a mix of configuration settings and [front-matter](/content-management/front-matter/) values on individual pages.
+
+{{< code-toggle file=hugo >}}
+[params]
+ images = ["site-feature-image.jpg"]
+ description = "Text about my cool site"
+{{}}
+
+{{< code-toggle file=content/blog/my-post.md >}}
+title = "Post title"
+description = "Text about this post"
+images = ["post-cover.png"]
+{{}}
+
+If `images` aren't specified in the page front-matter, then hugo searches for [image page resources](/content-management/image-processing/) with `feature`, `cover`, or `thumbnail` in their name.
+If no image resources with those names are found, the images defined in the [site config](/getting-started/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:
+
+{{< code-toggle file="hugo" copy=false >}}
+[params.social]
+twitter = "GoHugoIO"
+{{}}
+
+NOTE: The `@` will be added for you
+
+```html
+
+```
diff --git a/docs/content/en/templates/homepage.md b/docs/content/en/templates/homepage.md
index 59b7472fbc0..cd5b32604e8 100644
--- a/docs/content/en/templates/homepage.md
+++ b/docs/content/en/templates/homepage.md
@@ -12,11 +12,8 @@ toc: true
aliases: [/layout/homepage/,/templates/homepage-template/]
---
-Homepage is a `Page` and therefore has all the [page variables][pagevars] and [site variables][sitevars] available for use.
-
-{{% note %}}
The homepage template is the *only* required template for building a site and therefore useful when bootstrapping a new site and template. It is also the only required template if you are developing a single-page website.
-{{% /note %}}
+
{{< youtube ut1xtRZ1QOA >}}
@@ -32,8 +29,6 @@ See the homepage template below or [Content Organization][contentorg] for more i
## Example homepage template
-The following is an example of a homepage template that uses [partial][partials], [base] templates, and a content file at `content/_index.md` to populate the `{{ .Title }}` and `{{ .Content }}` [page variables][pagevars].
-
{{< code file=layouts/index.html >}}
{{ define "main" }}
@@ -56,10 +51,6 @@ The following is an example of a homepage template that uses [partial][partials]
{{ end }}
{{< /code >}}
-[base]: /templates/base/
[contentorg]: /content-management/organization/
[lists]: /templates/lists/
[lookup]: /templates/lookup-order/
-[pagevars]: /variables/page/
-[partials]: /templates/partials/
-[sitevars]: /variables/site/
diff --git a/docs/content/en/templates/internal.md b/docs/content/en/templates/internal.md
deleted file mode 100644
index 9438bfa6f1b..00000000000
--- a/docs/content/en/templates/internal.md
+++ /dev/null
@@ -1,221 +0,0 @@
----
-title: Internal templates
-description: Hugo ships with a group of boilerplate templates that cover the most common use cases for static websites.
-categories: [templates]
-keywords: [internal, analytics,]
-menu:
- docs:
- parent: templates
- weight: 190
-weight: 190
-toc: true
----
-
-{{% note %}}
-While the following internal templates are called similar to partials, they do *not* observe the partial template lookup order.
-{{% /note %}}
-
-## Google Analytics
-
-Hugo ships with an internal template supporting [Google Analytics 4].
-
-[Google Analytics 4]: https://support.google.com/analytics/answer/10089681
-
-### Configure Google Analytics
-
-Provide your tracking ID in your configuration file:
-
-**Google Analytics 4 (gtag.js)**
-{{< code-toggle file=hugo >}}
-[services.googleAnalytics]
-ID = "G-MEASUREMENT_ID"
-{{}}
-
-### Use the Google Analytics template
-
-Include the Google Analytics internal template in your templates where you want the code to appear:
-
-```go-html-template
-{{ template "_internal/google_analytics.html" . }}
-```
-
-To create your own template, access the configured ID with `{{ site.Config.Services.GoogleAnalytics.ID }}`.
-
-## Disqus
-
-Hugo also ships with an internal template for [Disqus comments][disqus], a popular commenting system for both static and dynamic websites. To effectively use Disqus, secure a Disqus "shortname" by [signing up for the free service][disqussignup].
-
-### Configure Disqus
-
-To use Hugo's Disqus template, first set up a single configuration value:
-
-{{< code-toggle file="hugo" >}}
-[services.disqus]
-shortname = 'your-disqus-shortname'
-{{}}
-
-Hugo's Disqus template accesses this value with:
-
-```go-html-template
-{{ .Site.Config.Services.Disqus.Shortname }}
-```
-
-You can also set the following in the front matter for a given piece of content:
-
-* `disqus_identifier`
-* `disqus_title`
-* `disqus_url`
-
-### Use the Disqus template
-
-To add Disqus, include the following line in the templates where you want your comments to appear:
-
-```go-html-template
-{{ template "_internal/disqus.html" . }}
-```
-
-### Conditional loading of Disqus comments
-
-Users have noticed that enabling Disqus comments when running the Hugo web server on `localhost` (i.e. via `hugo server`) causes the creation of unwanted discussions on the associated Disqus account.
-
-You can create the following `layouts/partials/disqus.html`:
-
-{{< code file=layouts/partials/disqus.html >}}
-
-
-
-comments powered by Disqus
-{{< /code >}}
-
-The `if` statement skips the initialization of the Disqus comment injection when you are running on `localhost`.
-
-You can then render your custom Disqus partial template as follows:
-
-```go-html-template
-{{ partial "disqus.html" . }}
-```
-
-## Open Graph
-
-An internal template for the [Open Graph protocol](https://ogp.me/), metadata that enables a page to become a rich object in a social graph.
-This format is used for Facebook and some other sites.
-
-### Configure Open Graph
-
-Hugo's Open Graph template is configured using a mix of configuration variables and [front-matter](/content-management/front-matter/) on individual pages.
-
-{{< code-toggle file=hugo >}}
-[params]
- title = "My cool site"
- images = ["site-feature-image.jpg"]
- description = "Text about my cool site"
-[taxonomies]
- series = "series"
-{{}}
-
-{{< code-toggle file=content/blog/my-post.md >}}
-title = "Post title"
-description = "Text about this post"
-date = "2006-01-02"
-images = ["post-cover.png"]
-audio = []
-videos = []
-series = []
-tags = []
-{{}}
-
-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*` or `*cover*,*thumbnail*` are used for image metadata.
-
-Various optional metadata can also be set:
-
-- Date, published date, and last modified data are used to set the published time metadata if specified.
-- `audio` and `videos` are URL arrays like `images` for the audio and video metadata tags, respectively.
-- The first 6 `tags` on the page are used for the tags metadata.
-- The `series` taxonomy is used to specify related "see also" pages by placing them in the same series.
-
-If using YouTube this will produce a og:video tag like ``. Use the `https://youtu.be/` format with YouTube videos (example: `https://youtu.be/qtIqKaDlqXo`).
-
-### Use the Open Graph template
-
-To add Open Graph metadata, include the following line between the `` tags in your templates:
-
-```go-html-template
-{{ template "_internal/opengraph.html" . }}
-```
-
-## Twitter Cards
-
-An internal template for [Twitter Cards](https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/abouts-cards),
-metadata used to attach rich media to Tweets linking to your site.
-
-### Configure Twitter Cards
-
-Hugo's Twitter Card template is configured using a mix of configuration variables and [front-matter](/content-management/front-matter/) on individual pages.
-
-{{< code-toggle file=hugo >}}
-[params]
- images = ["site-feature-image.jpg"]
- description = "Text about my cool site"
-{{}}
-
-{{< code-toggle file=content/blog/my-post.md >}}
-title = "Post title"
-description = "Text about this post"
-images = ["post-cover.png"]
-{{}}
-
-If `images` aren't specified in the page front-matter, then hugo searches for [image page resources](/content-management/image-processing/) with `feature`, `cover`, or `thumbnail` in their name.
-If no image resources with those names are found, the images defined in the [site config](/getting-started/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:
-
-{{< code-toggle file="hugo" copy=false >}}
-[params.social]
-twitter = "GoHugoIO"
-{{}}
-
-NOTE: The `@` will be added for you
-
-```html
-
-```
-
-### Use the Twitter Cards template
-
-To add Twitter card metadata, include the following line immediately after the `` element in your templates:
-
-```go-html-template
-{{ template "_internal/twitter_cards.html" . }}
-```
-
-## The internal templates
-
-The code for these templates is located [here](https://github.com/gohugoio/hugo/tree/master/tpl/tplimpl/embedded/templates).
-
-* `_internal/disqus.html`
-* `_internal/google_analytics.html`
-* `_internal/opengraph.html`
-* `_internal/pagination.html`
-* `_internal/schema.html`
-* `_internal/twitter_cards.html`
-
-[disqus]: https://disqus.com
-[disqussignup]: https://disqus.com/profile/signup/
diff --git a/docs/content/en/templates/introduction.md b/docs/content/en/templates/introduction.md
index 7fb0ddecfb0..994e8185405 100644
--- a/docs/content/en/templates/introduction.md
+++ b/docs/content/en/templates/introduction.md
@@ -1,672 +1,563 @@
---
-title: Templating
-linkTitle: Templating
-description: Hugo uses Go's `html/template` and `text/template` libraries as the basis for the templating.
+title: Introduction to templating
+linkTitle: Introduction
+description: Create templates to render your content, resources, and data.
categories: [templates,fundamentals]
-keywords: [go]
+keywords: []
menu:
docs:
+ identifier: templates-introduction
parent: templates
weight: 20
weight: 20
toc: true
-aliases: [/layouts/introduction/,/layout/introduction/, /templates/go-templates/]
---
-{{% note %}}
-The following is only a primer on Go Templates. For an in-depth look into Go Templates, check the official [Go docs](https://golang.org/pkg/text/template/).
-{{% /note %}}
-
-Go Templates provide an extremely simple template language that adheres to the belief that only the most basic of logic belongs in the template or view layer.
+A template is a file in the layouts directory of a project, theme, or module. Templates use [variables] , [functions], and [methods] to transform your content, resources, and data into a published page.
-## Basic syntax
+[functions]: /functions/
+[methods]: /methods/
+[variables]: #variables
-Go Templates are HTML files with the addition of [variables][variables] and [functions][functions]. Go Template variables and functions are accessible within `{{ }}`.
+{{% note %}}
+Hugo uses Go's [text/template] and [html/template] packages.
-### Access a predefined variable
+The text/template package implements data-driven templates for generating textual output, while the html/template package implements data-driven templates for generating HTML output safe against code injection.
-A _predefined variable_ could be a variable already existing in the
-current scope (like the `.Title` example in the [Variables](#variables) section below) or a custom variable (like the
-`$address` example in that same section).
+By default, Hugo uses the html/template package when rendering HTML files.
-```go-html-template
-{{ .Title }}
-{{ $address }}
-```
+[text/template]: https://pkg.go.dev/text/template
+[html/template]: https://pkg.go.dev/html/template
+{{% /note %}}
-Parameters for functions are separated using spaces. The general syntax is:
+For example, this HTML template initializes the `$v1` and `$v2` variables, then displays them and their product within an HTML paragraph.
```go-html-template
-{{ FUNCTION ARG1 ARG2 .. }}
+{{ $v1 := 6 }}
+{{ $v2 := 7 }}
+
The product of {{ $v1 }} and {{ $v2 }} is {{ mul $v1 $v2 }}.
```
-The following example calls the `add` function with inputs of `1` and `2`:
+While HTML templates are the most common, you can create templates for any [output format] including CSV, JSON, RSS, and plain text.
-```go-html-template
-{{ add 1 2 }}
-```
+[output format]: /templates/output-formats/
-#### Methods and fields are accessed via dot notation
+## Context
-Accessing the Page Parameter `bar` defined in a piece of content's [front matter].
+The most important concept to understand before creating a template is _context_, the data passed into each template. The data may be a simple value, or more commonly [objects] and associated [methods].
-```go-html-template
-{{ .Params.bar }}
-```
+[objects]: /getting-started/glossary/#object
+[methods]: /getting-started/glossary/#method
-#### Parentheses can be used to group items together
+For example, a template for a single page receives a `Page` object, and the `Page` object provides methods to return values or perform actions.
-```go-html-template
-{{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }}
-```
-
-#### A single statement can be split over multiple lines
-
-```go-html-template
-{{ if or
- (isset .Params "alt")
- (isset .Params "caption")
-}}
-```
+### Current context
-#### Raw string literals can include newlines
-
-```go-html-template
-{{ $msg := `Line one.
-Line two.` }}
-```
-
-## Variables
+Within a template, the dot (`.`) represents the current context.
-Each Go Template gets a data object. In Hugo, each template is passed
-a `Page`. In the below example, `.Title` is one of the elements
-accessible in that [`Page` variable][pagevars].
+{{< code file=layouts/_default/single.html >}}
+
{{ .Title }}
+{{< /code >}}
-With the `Page` being the default scope of a template, the `Title`
-element in current scope (`.` -- "the **dot**") is accessible simply
-by the dot-prefix (`.Title`):
+In the example above the dot represents the `Page` object, and we call its [`Title`] method to return the title as defined in [front matter].
-```go-html-template
-{{ .Title }}
-```
+[front matter]: /content-management/front-matter/
+[`Title`]: /methods/page/title
-Values can also be stored in custom variables and referenced later:
+The current context may change within a template. For example, at the top of a template the context might be a `Page` object, but we rebind the context to another value or object within [`range`] or [`with`] blocks.
-{{% note %}}
-The custom variables need to be prefixed with `$`.
-{{% /note %}}
+[`range`]: /functions/go-template/range/
+[`with`]: /functions/go-template/with/
-```go-html-template
-{{ $address := "123 Main St." }}
-{{ $address }}
-```
+{{< code file=layouts/_default/single.html >}}
+
{{ .Title }}
-Variables can be re-defined using the `=` operator. The example below
-prints "Var is Hugo Home" on the home page, and "Var is Hugo Page" on
-all other pages:
+{{ range slice "foo" "bar" }}
+
{{ . }}
+{{ end }}
-```go-html-template
-{{ $var := "Hugo Page" }}
-{{ if .IsHome }}
- {{ $var = "Hugo Home" }}
+{{ with "baz" }}
+
{{ . }}
{{ end }}
-Var is {{ $var }}
-```
+{{< /code >}}
-Variable names must conform to Go's naming rules for [identifiers][identifier].
+In the example above, the context changes as we `range` through the [slice] of values. In the first iteration the context is "foo", and in the second iteration the context is "bar". Inside of the `with` block the context is "baz". Hugo renders the above to:
-## Functions
+[slice]: /getting-started/glossary/#slice
-Go Templates only ship with a few basic functions but also provide a mechanism for applications to extend the original set.
+```html
+
My Page Title
+
foo
+
bar
+
baz
+```
-[Hugo template functions][functions] provide additional functionality specific to building websites. Functions are called by using their name followed by the required parameters separated by spaces. Template functions cannot be added without recompiling Hugo.
+### Template context
-### Example 1: adding numbers
+Within a `range` or `with` block you can access the context passed into the template by prepending a dollar sign (`$`) to the dot:
-```go-html-template
-{{ add 1 2 }}
-
-```
+{{< code file=layouts/_default/single.html >}}
+{{ with "foo" }}
+
{{ $.Title }} - {{ . }}
+{{ end }}
+{{< /code >}}
-### Example 2: comparing numbers
+Hugo renders this to:
-```go-html-template
-{{ lt 1 2 }}
-
+```html
+
My Page Title - foo
```
-Note that both examples make use of Go Template's [math][math] functions.
-
{{% note %}}
-There are more boolean operators than those listed in the Hugo docs in the [Go Template documentation](https://golang.org/pkg/text/template/#hdr-Functions).
+Make sure that you thoroughly understand the concept of _context_ before you continue reading. The most common templating errors made by new users relate to context.
{{% /note %}}
-## Includes
+## Actions
-When including another template, you will need to pass it the data that it would
-need to access.
+In the examples above the paired opening and closing braces represent the beginning and end of a template action, a data evaluation or control structure within a template.
-{{% note %}}
-To pass along the current context, please remember to include a trailing **dot**.
-{{% /note %}}
+A template action may contain literal values ([boolean], [string], [integer], and [float]), variables, functions, and methods.
-The templates location will always be starting at the `layouts/` directory
-within Hugo.
+[boolean]: /getting-started/glossary/#boolean
+[string]: /getting-started/glossary/#string
+[integer]: /getting-started/glossary/#integer
+[float]: /getting-started/glossary/#float
-### Partial
+{{< code file=layouts/_default/single.html >}}
+{{ $convertToLower := true }}
+{{ if $convertToLower }}
+
{{ strings.ToLower .Title }}
+{{ end }}
+{{< /code >}}
-The [`partial`][partials] function is used to include _partial_ templates using
-the syntax `{{ partial "/." . }}`.
+In the example above:
-Example of including a `layouts/partials/header.html` partial:
+- `$convertToLower` is a variable
+- `true` is a literal boolean value
+- `strings.ToLower` is a function that converts all characters to lowercase
+- `Title` is a method on a the `Page` object
-```go-html-template
-{{ partial "header.html" . }}
+Hugo renders the above to:
+
+```html
+
+
+
my page title
+
```
-### Template
+### Whitespace
-The `template` function was used to include _partial_ templates
-in much older Hugo versions. Now it's useful only for calling
-[_internal_ templates][internal templates]. The syntax is `{{ template
-"_internal/." . }}`.
+Notice the blank lines and indentation in the previous example? Although irrelevant in production when you typically minify the output, you can remove the adjacent whitespace by using template action delimiters with hyphens:
-{{% note %}}
-The available **internal** templates can be found
-[here](https://github.com/gohugoio/hugo/tree/master/tpl/tplimpl/embedded/templates).
-{{% /note %}}
+{{< code file=layouts/_default/single.html >}}
+{{- $convertToLower := true -}}
+{{- if $convertToLower -}}
+
{{ strings.ToLower .Title }}
+{{- end -}}
+{{< /code >}}
-Example of including the internal `opengraph.html` template:
+Hugo renders this to:
-```go-html-template
-{{ template "_internal/opengraph.html" . }}
+```html
+
my page title
```
-## Logic
-
-Go Templates provide the most basic iteration and conditional logic.
+Whitespace includes spaces, horizontal tabs, carriage returns, and newlines.
-### Iteration
+### Pipes
-The Go Templates make heavy use of `range` to iterate over a _map_,
-_array_, or _slice_. The following are different examples of how to
-use `range`.
+Within a template action you may [pipe] a value to function or method. The piped value becomes the final argument to the function or method. For example, these are equivalent:
-#### Example 1: using context (`.`)
+[pipe]: /getting-started/glossary/#pipeline
```go-html-template
-{{ range $array }}
- {{ . }}
-{{ end }}
+{{ strings.ToLower "Hugo" }} → hugo
+{{ "Hugo" | strings.ToLower }} → hugo
```
-#### Example 2: declaring a variable name for an array element's value
+You can pipe the result of one function or method into another. For example, these are equivalent:
```go-html-template
-{{ range $elem_val := $array }}
- {{ $elem_val }}
-{{ end }}
+{{ strings.TrimSuffix "o" (strings.ToLower "Hugo") }} → hug
+{{ "Hugo" | strings.ToLower | strings.TrimSuffix "o" }} → hug
```
-#### Example 3: declaring variable names for an array element's index _and_ value
-
-For an array or slice, the first declared variable will map to each
-element's index.
+These are also equivalent:
```go-html-template
-{{ range $elem_index, $elem_val := $array }}
- {{ $elem_index }} -- {{ $elem_val }}
-{{ end }}
+{{ mul 6 (add 2 5) }} → 42
+{{ 5 | add 2 | mul 6 }} → 42
```
-#### Example 4: declaring variable names for a map element's key _and_ value
-
-For a map, the first declared variable will map to each map element's
-key.
-
-```go-html-template
-{{ range $elem_key, $elem_val := $map }}
- {{ $elem_key }} -- {{ $elem_val }}
-{{ end }}
-```
+{{% note %}}
+Remember that the piped value becomes the final argument to the function or method to which you are piping.
+{{% /note %}}
-#### Example 5: conditional on empty _map_, _array_, or _slice_
+### Line splitting
-If the _map_, _array_, or _slice_ passed into the range is zero-length then the else statement is evaluated.
+You can split a template action over two or more lines. For example, these are equivalent:
```go-html-template
-{{ range $array }}
- {{ . }}
-{{ else }}
-
-{{ end }}
-```
+{{ $v := or .Site.Language.LanguageName .Site.Language.Lang }}
-### Conditionals
+{{ $v := or
+ .Site.Language.LanguageName
+ .Site.Language.Lang
+}}
+```
-`if`, `else`, `with`, `or`, `and` and `not` provide the framework for handling conditional logic in Go Templates. Like `range`, `if` and `with` statements are closed with an `{{ end }}`.
+You can also split [raw string literals] over two or more lines. For example, these are equivalent:
-Go Templates treat the following values as **false**:
+[raw string literals]: /getting-started/glossary/#string-literal-raw
-- `false` (boolean)
-- 0 (integer)
-- any zero-length array, slice, map, or string
+```go-html-template
+{{ $msg := "This is line one.\nThis is line two." }}
-#### Example 1: `with`
+{{ $msg := `This is line one.
+This is line two.`
+}}
+```
-It is common to write "if something exists, do this" kind of
-statements using `with`.
+## Variables
-{{% note %}}
-`with` rebinds the context `.` within its scope (just like in `range`).
-{{% /note %}}
+A variable is a user-defined [identifier] prepended with a dollar sign (`$`), representing a value of any data type, initialized or assigned within a template action. For example, `$foo` and `$bar` are variables.
-It skips the block if the variable is absent, or if it evaluates to
-"false" as explained above.
+[identifier]: /getting-started/glossary/#identifier
-```go-html-template
-{{ with .Params.title }}
-
{{ . }}
-{{ end }}
-```
+Variables may contain [scalars], [slices], [maps], or [objects].
-#### Example 2: `with` .. `else`
+[scalars]: /getting-started/glossary/#scalar
+[slices]: /getting-started/glossary/#slice
+[maps]: /getting-started/glossary/#map
+[objects]: /getting-started/glossary/#object
-Below snippet uses the "description" front-matter parameter's value if
-set, else uses the default `.Summary` [Page variable][pagevars]:
+Use `:=` to initialize a variable, and use `=` to assign a value to a variable that has been previously initialized. For example:
```go-html-template
-{{ with .Param "description" }}
- {{ . }}
-{{ else }}
- {{ .Summary }}
+{{ $total := 3 }}
+{{ range slice 7 11 21 }}
+ {{ $total = add $total . }}
{{ end }}
+{{ $total }} → 42
```
-See the [`.Param` function][param].
-
-#### Example 3: `if`
+Variables initialized inside of an `if`, `range`, or `with` block are scoped to the block. Variables initialized outside of these blocks are scoped to the template.
-An alternative (and a more verbose) way of writing `with` is using
-`if`. Here, the `.` does not get rebound.
+With variables that represent a slice or map, use the [`index`] function to return the desired value.
-Below example is "Example 1" rewritten using `if`:
+[`index`]: /functions/collections/indexfunction/
```go-html-template
-{{ if isset .Params "title" }}
-
{{ index .Params "title" }}
-{{ end }}
-```
-
-#### Example 4: `if` .. `else`
-
-Below example is "Example 2" rewritten using `if` .. `else`, and using
-[`isset`] + `.Params` variable (different from the
-[`.Param` **function**][param]) instead:
+{{ $slice := slice "foo" "bar" "baz" }}
+{{ index $slice 2 }} → baz
-```go-html-template
-{{ if (isset .Params "description") }}
- {{ index .Params "description" }}
-{{ else }}
- {{ .Summary }}
-{{ end }}
+{{ $map := dict "a" "foo" "b" "bar" "c" "baz" }}
+{{ index $map "c" }} → baz
```
-#### Example 5: `if` .. `else if` .. `else`
-
-Unlike `with`, `if` can contain `else if` clauses too.
+{{% note %}}
+Slices and arrays are zero-based; element 0 is the first element.
+{{% /note %}}
-```go-html-template
-{{ if (isset .Params "description") }}
- {{ index .Params "description" }}
-{{ else if (isset .Params "summary") }}
- {{ index .Params "summary" }}
-{{ else }}
- {{ .Summary }}
-{{ end }}
-```
+With variables that represent a map or object, [chain] identifiers to return the desired value or to access the desired method.
-#### Example 6: `and` & `or`
+[chain]: /getting-started/glossary/#chain
```go-html-template
-{{ if (and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")) }}
-```
+{{ $map := dict "a" "foo" "b" "bar" "c" "baz" }}
+{{ $map.c }} → baz
-## Pipes
-
-One of the most powerful components of Go Templates is the ability to stack actions one after another. This is done by using pipes. Borrowed from Unix pipes, the concept is simple: each pipeline's output becomes the input of the following pipe.
+{{ $homePage := .Site.Home }}
+{{ $homePage.Title }} → My Homepage
+```
-Because of the very simple syntax of Go Templates, the pipe is essential to being able to chain together function calls. One limitation of the pipes is that they can only work with a single value and that value becomes the last parameter of the next pipeline.
+{{% note %}}
+As seen above, object and method names are capitalized. Although not required, to avoid confusion we recommend beginning variable and map key names with a lowercase letter or underscore.
+{{% /note %}}
-A few simple examples should help convey how to use the pipe.
+## Functions
-### Example 1: `shuffle`
+Used within a template action, a function takes one or more arguments and returns a value. Unlike methods, functions are not associated with an object.
-The following two examples are functionally the same:
+Go's text/template and html/template packages provide a small set of functions, operators, and statements for general use. See the [go-templates] section of the function documentation for details.
-```go-html-template
-{{ shuffle (seq 1 5) }}
-```
+[go-templates]: /functions/go-template/
-```go-html-template
-{{ (seq 1 5) | shuffle }}
-```
+Hugo provides hundreds of custom [functions] categorized by namespace. For example, the `strings` namespace includes these and other functions:
-### Example 2: `index`
+[functions]: /functions
-The following accesses the page parameter called "disqus_url" and escapes the HTML. This example also uses the [`index`] function, which is built into Go Templates:
+Function|Alias
+:--|:--
+[`strings.ToLower`](/functions/strings/tolower)|`lower`
+[`strings.ToUpper`](/functions/strings/toupper)|`upper`
+[`strings.Replace`](/functions/strings/replace)|`replace`
-```go-html-template
-{{ index .Params "disqus_url" | html }}
-```
+As shown above, frequently used functions have an alias. Use aliases in your templates to reduce code length.
-### Example 3: `or` with `isset`
+When calling a function, separate the arguments from the function, and from each other, with a space. For example:
```go-html-template
-{{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr") }}
-Stuff Here
-{{ end }}
+{{ $total := add 1 2 3 4 }}
```
-Could be rewritten as
-
-```go-html-template
-{{ if isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" }}
-Stuff Here
-{{ end }}
-```
+## Methods
-## Context (aka "the dot") {#the-dot}
+Used within a template action and associated with an object, a method takes zero or more arguments and either returns a value or performs an action.
-The most easily overlooked concept to understand about Go Templates is
-that `{{ . }}` always refers to the **current context**.
+The most commonly accessed objects are the [`Page`] and [`Site`] objects. This is a small sampling of the [methods] available to each object.
-- In the top level of your template, this will be the data set made
- available to it.
-- Inside an iteration, however, it will have the value of the
- current item in the loop; i.e., `{{ . }}` will no longer refer to
- the data available to the entire page.
+[`Site`]: /methods/site/
+[`Page`]: /methods/page/
+[methods]: /methods/
-If you need to access page-level data (e.g., page parameters set in front
-matter) from within the loop, you will likely want to do one of the
-following:
+Object|Method|Description
+:--|:--|:--
+`Page`|[`Date`](methods/page/date/)|Returns the date of the given page.
+`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.
-### 1. Define a variable independent of context
+Chain the method to its object with a dot (`.`) as shown below, remembering that the leading dot represents the [current context].
-The following shows how to define a variable independent of the context.
+[current context]: #current-context
-{{< code file=tags-range-with-page-variable.html >}}
-{{ $title := .Site.Title }}
-
+{{< code file=layouts/_default/single.html >}}
+{{ .Site.Title }} → My Site Title
+{{ .Page.Title }} → My Page Title
{{< /code >}}
-{{% note %}}
-Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}` has changed. We have defined a variable outside the loop (`{{ $title }}`) that we've assigned a value so that we have access to the value from within the loop as well.
-{{% /note %}}
+The context passed into most templates is a `Page` object, so this is equivalent to the previous example:
-### 2. Use `$.` to access the global context
+{{< code file=layouts/_default/single.html >}}
+{{ .Site.Title }} → My Site Title
+{{ .Title }} → My Page Title
+{{< /code >}}
-`$` has special significance in your templates. `$` is set to the starting value of `.` ("the dot") by default. This is a [documented feature of Go text/template][dotdoc]. This means you have access to the global context from anywhere. Here is an equivalent example of the preceding code block but now using `$` to grab `.Site.Title` from the global context:
+Some methods take an argument. Separate the argument from the method with a space. For example:
-{{< code file=range-through-tags-w-global.html >}}
-
+{{< code file=layouts/_default/single.html >}}
+{{ $page := .Page.GetPage "/books/les-miserables" }}
+{{ $page.Title }} → Les Misérables
{{< /code >}}
-{{% note %}}
-The built-in magic of `$` would cease to work if someone were to mischievously redefine the special character; e.g. `{{ $ := .Site }}`. *Don't do it.* You may, of course, recover from this mischief by using `{{ $ := . }}` in a global context to reset `$` to its default value.
-{{% /note %}}
+## Comments
-## Whitespace
+{{% note %}}
+Do not attempt to use HTML comment delimiters to comment out template code.
-Go 1.6 includes the ability to trim the whitespace from either side of a Go tag by including a hyphen (`-`) and space immediately beside the corresponding `{{` or `}}` delimiter.
+Hugo strips HTML comments when rendering a page, but first evaluates any template code within the HTML comment delimiters. Depending on the template code within the HTML comment delimiters, this could cause unexpected results or fail the build.
+{{% /note %}}
-For instance, the following Go Template will include the newlines and horizontal tab in its HTML output:
+Template comments are similar to template actions. Paired opening and closing braces represent the beginning and end of a comment. For example:
-```go-html-template
-
- {{ .Title }}
-
+```text
+{{/* This is an inline comment. */}}
+{{- /* This is an inline comment with adjacent whitespace removed. */ -}}
```
-Which will output:
+Code within a comment is not parsed, executed, or displayed. Comments may be inline, as shown above, or in block form:
-```html
-
- Hello, World!
-
+```text
+{{/*
+This is a block comment.
+*/}}
+
+{{- /*
+This is a block comment with
+adjacent whitespace removed.
+*/ -}}
```
-Leveraging the `-` in the following example will remove the extra white space surrounding the `.Title` variable and remove the newline:
+You may not nest one comment inside of another.
-```go-html-template
-
- {{- .Title -}}
-
-```
+To render an HTML comment, pass a string through the [`safeHTML`] template function. For example:
-Which then outputs:
+[`safeHTML`]: /functions/safe/html
-```html
-
Hello, World!
+```go-html-template
+{{ "" | safeHTML }}
+{{ printf "" .Site.Title | safeHTML }}
```
-Go considers the following characters _whitespace_:
+## Include
-* space
-* horizontal tab
-* carriage return
-* newline
+Use the [`template`] function to include one or more of Hugo's [embedded templates]:
-## Comments
+[embedded templates]: /templates/embedded/
-In order to keep your templates organized and share information throughout your team, you may want to add comments to your templates. There are two ways to do that with Hugo.
+```go-html-template
+{{ template "_internal/google_analytics.html" . }}
+{{ template "_internal/opengraph" . }}
+{{ template "_internal/pagination.html" . }}
+{{ template "_internal/schema.html" . }}
+{{ template "_internal/twitter_cards.html" . }}
+```
-### Go templates comments
+[`partial`]: /functions/partials/include/
+[`partialCached`]: /functions/partials/includecached/
+[`template`]: functions/go-template/template/
-Go Templates support `{{/*` and `*/}}` to open and close a comment block. Nothing within that block will be rendered.
+Use the [`partial`] or [`partialCached`] function to include one or more [partial templates]:
-For example:
+[partial templates]: /templates/partials
```go-html-template
-Bonsoir, {{/* {{ add 0 + 2 }} */}}Eliott.
+{{ partial "breadcrumbs.html" . }}
+{{ partialCached "css.html" . }}
```
-Will render `Bonsoir, Eliott.`, and not care about the syntax error (`add 0 + 2`) in the comment block.
+Create your partial templates in the layouts/partials directory.
-### HTML comments
+{{% note %}}
+In the examples above, note that we are passing the current context (the dot) to each of the templates.
+{{% /note %}}
-You can add html comments by piping a string HTML code comment to `safeHTML`.
+## Examples
-For example:
+This limited set of contrived examples demonstrates some of concepts described above. Please see the [functions], [methods], and [templates] documentation for specific examples.
-```go-html-template
-{{ "" | safeHTML }}
-```
+[templates]: /templates/
-If you need variables to construct such HTML comments, just pipe `printf` to `safeHTML`.
+### Conditional blocks
-For example:
+See documentation for [`if`], [`else`], and [`end`].
+
+[`if`]: /functions/go-template/if/
+[`else`]: /functions/go-template/else/
+[`end`]: /functions/go-template/end/
```go-html-template
-{{ printf "" .Site.Title | safeHTML }}
+{{ $var := 42 }}
+{{ if eq $var 6 }}
+ {{ print "var is 6" }}
+{{ else if eq $var 7 }}
+ {{ print "var is 7" }}
+{{ else if eq $var 42 }}
+ {{ print "var is 42" }}
+{{ else }}
+ {{ print "var is something else" }}
+{{ end }}
```
-#### HTML comments containing Go templates
+### Logical operators
-HTML comments are by default stripped, but their content is still evaluated. That means that although the HTML comment will never render any content to the final HTML pages, code contained within the comment may fail the build process.
+See documentation for [`and`] and [`or`].
-{{% note %}}
-Do **not** try to comment out Go Template code using HTML comments.
-{{% /note %}}
+[`and`]: /functions/go-template/and
+[`or`]: /functions/go-template/or
```go-html-template
-
-{{ $author }}
-```
+{{ $v1 := true }}
+{{ $v2 := false }}
+{{ $v3 := false }}
+{{ $result := false }}
-The templating engine will strip the content within the HTML comment, but will first evaluate any Go Template code if present within. So the above example will render `Emma Goldman`, as the `$author` variable got evaluated in the HTML comment. But the build would have failed if that code in the HTML comment had an error.
-
-## Hugo parameters
-
-Hugo provides the option of passing values to your template layer through your [site configuration][config] (i.e. for site-wide values) or through the metadata of each specific piece of content (i.e. the [front matter]). You can define any values of any type and use them however you want in your templates, as long as the values are supported by the [front matter format](/content-management/front-matter#front-matter-formats).
+{{ if and $v1 $v2 $v3 }}
+ {{ $result = true }}
+{{ end }}
+{{ $result }} → false
-## Use content (`Page`) parameters
+{{ if or $v1 $v2 $v3 }}
+ {{ $result = true }}
+{{ end }}
+{{ $result }} → true
+```
-You can provide variables to be used by templates in individual content's [front matter].
+### Loops
-An example of this is used in the Hugo docs. Most of the pages benefit from having the table of contents provided, but sometimes the table of contents doesn't make a lot of sense. We've defined a `notoc` variable in our front matter that will prevent a table of contents from rendering when specifically set to `true`.
+See documentation for [`range`], [`else`], and [`end`].
-Here is the example front matter:
+[`range`]: /functions/go-template/range/
-{{< code-toggle file=content/example.md fm=true >}}
-title: Example
-notoc: true
-{{< /code-toggle >}}
-
-Here is an example of corresponding code that could be used inside a `toc.html` [partial template][partials]:
-
-{{< code file=layouts/partials/toc.html >}}
-{{ if not .Params.notoc }}
-
-
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $s }}
+
+ 
diff --git a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/sponsors.html b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/sponsors.html
index 6838ce36af3..3b7f6bfef17 100644
--- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/sponsors.html
+++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/sponsors.html
@@ -25,26 +25,30 @@ 
+{{ end }}
+{{< /code >}}
+
+###### Site
+
+Returns the `Site` to which the pages will be added.
+
+{{< code file=content/books/_content.gotmpl >}}
+{{ .Site.Title }}
+{{< /code >}}
+
+###### Store
+
+Returns a persistent “scratch pad” to store and manipulate data. The main use case for this is to transfer values between executions when [EnableAllLanguages](#enablealllanguages) is set. See [examples](/methods/page/store/).
+
+{{< code file=content/books/_content.gotmpl >}}
+{{ .Store.Set "key" "value" }}
+{{ .Store.Get "key" }}
+{{< /code >}}
+
+###### EnableAllLanguages
+
+By default, Hugo executes the content adapter for the language defined by the _content.gotmpl file . Use this method to activate the content adapter for all languages.
+
+{{< code file=content/books/_content.gotmpl >}}
+{{ .EnableAllLanguages }}
+{{ $content := dict
+ "mediaType" "text/markdown"
+ "value" "The _Hunchback of Notre Dame_ was written by Victor Hugo."
+}}
+{{ $page := dict
+ "content" $content
+ "kind" "page"
+ "path" "the-hunchback-of-notre-dame"
+ "title" "The Hunchback of Notre Dame"
+}}
+{{ .AddPage $page }}
+{{< /code >}}
+
+## Page map
+
+Set any [front matter field] in the map passed to the [`AddPage`](#addpage) method, excluding `markup`. Instead of setting the `markup` field, specify the `content.mediaType` as described below.
+
+This table describes the fields most commonly passed to the `AddPage` method.
+
+Key|Descripion|Required
+:--|:--|:-:
+`content.mediaType`|The content [media type]. Default is `text/markdown`. See [content formats] for examples.|
+`content.value`|The content value as a string.|
+`dates.date`|The page creation date as a `time.Time` value.|
+`dates.expiryDate`|The page expiry date as a `time.Time` value.|
+`dates.lastmod`|The page last modification date as a `time.Time` value.|
+`dates.publishDate`|The page publication date as a `time.Time` value.|
+`kind`|The [page kind]. Default is `page`.|
+`params`|A map of page parameters.|
+`path`|The page's [logical path] relative to the content adapter. Do not include a leading slash or file extension.|:heavy_check_mark:
+`title`|The page title.|
+
+{{% note %}}
+While `path` is the only required field, we recommend setting `title` as well.
+
+When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C` produces a logical path of `/section/a-b-c`.
+{{% /note %}}
+
+## Resource map
+
+Construct the map passed to the [`AddResource`](#addresource) method using the fields below.
+
+Key|Descripion|Required
+:--|:--|:-:
+`content.mediaType`|The content [media type].|:heavy_check_mark:
+`content.value`|The content value as a string or resource.|:heavy_check_mark:
+`name`|The resource name.|
+`params`|A map of resource parameters.|
+`path`|The resources's [logical path] relative to the content adapter. Do not include a leading slash.|:heavy_check_mark:
+`title`|The resource title.|
+
+{{% note %}}
+If the `content.value` is a string Hugo creates a new resource. If the `content.value` is a resource, Hugo obtains the value from the existing resource.
+
+When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C/cover.jpg` produces a logical path of `/section/a-b-c/cover.jpg`.
+{{% /note %}}
+
+## Example
+
+Create pages from remote data, where each page represents a book review.
+
+Step 1
+: Create the content structure.
+
+```text
+content/
+└── books/
+ ├── _content.gotmpl <-- content adapter
+ └── _index.md
+```
+
+Step 2
+: Inspect the remote data to determine how to map key-value pairs to front matter fields.
+
+: 
+{{- /* chomp trailing newline */ -}}
+{{< /code >}}
+
+To render standalone images within `figure` elements:
+
+{{< code file=layouts/_default/_markup/render-image.html copy=true >}}
+{{- if .IsBlock -}}
+ 