diff --git a/config/_default/menus/menus.en.toml b/config/_default/menus/menus.en.toml
index cd337cbeeea..e6d95589ab4 100644
--- a/config/_default/menus/menus.en.toml
+++ b/config/_default/menus/menus.en.toml
@@ -15,60 +15,66 @@ 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
+weight = 90
identifier = 'variables'
pageRef = '/variables/'
+[[docs]]
+name = 'Render hooks'
+weight = 100
+identifier = 'render-hooks'
+pageRef = '/render-hooks/'
+
[[docs]]
name = 'Hugo Modules'
-weight = 90
+weight = 110
identifier = 'modules'
pageRef = '/hugo-modules/'
[[docs]]
name = 'Hugo Pipes'
-weight = 100
+weight = 120
identifier = 'hugo-pipes'
pageRef = '/hugo-pipes/'
[[docs]]
name = 'CLI'
-weight = 110
+weight = 130
post = 'break'
identifier = 'commands'
pageRef = '/commands/'
@@ -77,25 +83,25 @@ pageRef = '/commands/'
[[docs]]
name = 'Troubleshooting'
-weight = 120
+weight = 140
identifier = 'troubleshooting'
pageRef = '/troubleshooting/'
[[docs]]
name = 'Developer tools'
-weight = 130
+weight = 150
identifier = 'developer-tools'
pageRef = '/tools/'
[[docs]]
name = 'Hosting and deployment'
-weight = 140
+weight = 160
identifier = 'hosting-and-deployment'
pageRef = '/hosting-and-deployment/'
[[docs]]
name = 'Contribute'
-weight = 150
+weight = 170
post = 'break'
identifier = 'contribute'
pageRef = '/contribute/'
diff --git a/content/en/content-management/build-options.md b/content/en/content-management/build-options.md
index 4ba0401af40..b22516ad7c9 100644
--- a/content/en/content-management/build-options.md
+++ b/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'
@@ -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'
@@ -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/content/en/content-management/diagrams.md b/content/en/content-management/diagrams.md
index 17407098fa5..3554b9be3bb 100644
--- a/content/en/content-management/diagrams.md
+++ b/content/en/content-management/diagrams.md
@@ -6,8 +6,8 @@ keywords: [diagrams,drawing]
menu:
docs:
parent: content-management
- weight: 50
-weight: 50
+ weight: 245
+weight: 245
toc: true
---
{{< new-in 0.93.0 >}}
@@ -44,16 +44,18 @@ 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" }}
diff --git a/content/en/content-management/front-matter.md b/content/en/content-management/front-matter.md
index 7dee78db25e..89cc15dadcc 100644
--- a/content/en/content-management/front-matter.md
+++ b/content/en/content-management/front-matter.md
@@ -1,6 +1,6 @@
---
title: Front matter
-description: Hugo allows you to add front matter in yaml, toml, or json to your content files.
+description: Use front matter to add metadata to your content.
categories: [content management]
keywords: [front matter,yaml,toml,json,metadata,archetypes]
menu:
@@ -12,230 +12,361 @@ toc: true
aliases: [/content/front-matter/]
---
-**Front matter** allows you to keep metadata attached to an instance of a [content type]---i.e., embedded inside a content file---and is one of the many features that gives Hugo its strength.
+## Overview
-{{< youtube Yh2xKRJGff4 >}}
+The front matter at the top of each content file is metadata that:
-## Front matter formats
+- Describes the content
+- Augments the content
+- Establishes relationships with other content
+- Controls the published structure of your site
+- Determines template selection
-Hugo supports four formats for front matter, each with their own identifying tokens.
+Provide front matter using a serialization format, one of [JSON], [TOML], or [YAML]. Hugo determines the front matter format by examining the delimiters that separate the front matter from the page content.
-TOML
-: identified by opening and closing `+++`.
+[json]: https://www.json.org/
+[toml]: https://toml.io/
+[yaml]: https://yaml.org/
+
+See examples of front matter delimiters by toggling between the serialization formats below.
+
+{{< code-toggle file=content/example.md fm=true >}}
+title = 'Example'
+date = 2024-02-02T04:14:54-08:00
+draft = false
+weight = 10
+[params]
+myparam = 42
+tags = ['red','blue']
+{{< /code-toggle >}}
-YAML
-: identified by opening and closing `---`.
+Front matter fields may be [scalar], [arrays], or [maps] containing [boolean], [integer], [float], or [string] values. Note that the TOML format also supports date/time values using unquoted strings.
-JSON
-: a single JSON object surrounded by '`{`' and '`}`', followed by a new line.
+[scalar]: /getting-started/glossary/#scalar
+[arrays]: /getting-started/glossary/#array
+[maps]: /getting-started/glossary/#map
+[boolean]: /getting-started/glossary/#boolean
+[integer]: /getting-started/glossary/#integer
+[float]: /getting-started/glossary/#float
+[string]: /getting-started/glossary/#string
-ORG
-: a group of Org mode keywords in the format '`#+KEY: VALUE`'. Any line that does not start with `#+` ends the front matter section.
- Array values can either be separated into multiple lines (`#+KEY: VALUE_1` and `#+KEY: VALUE_2`) or a whitespace separated list of strings (`#+KEY[]: VALUE_1 VALUE_2`).
+## Fields
-### Example
+The most common front matter fields are `date`, `draft`, `title`, and `weight`, but you can specify metadata using any of fields below.
-{{< code-toggle >}}
-title = "spf13-vim 3.0 release and new website"
-description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
-tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ]
-date = "2012-04-06"
-categories = [
- "Development",
- "VIM"
-]
-slug = "spf13-vim-3-0-release-and-new-website"
-{{< /code-toggle >}}
+{{% note %}}
+The field names below are reserved. For example, you cannot create a custom field named `type`. Create custom fields under the `params` key. See the [parameters] section for details.
-## Front matter variables
+[parameters]: #parameters
+{{% /note %}}
-### Predefined
+###### aliases
-There are a few predefined variables that Hugo is aware of. See [Page Variables][pagevars] for how to call many of these predefined variables in your templates.
+(`string array`) An array of one or more aliases, where each alias is a relative URL that will redirect the browser to the current location. Access these values from a template using the [`Aliases`] method on a `Page` object. See the [aliases] section for details.
-aliases
-: An array of one or more aliases (e.g., old published paths of renamed content) that will be created in the output directory structure . See [Aliases][aliases] for details.
+[`aliases`]: /methods/page/aliases/
+[aliases]: /content-management/urls/#aliases
-audio
-: An array of paths to audio files related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:audio`.
+###### build
-cascade
-: A map of front matter keys whose values are passed down to the page's descendants unless overwritten by self or a closer ancestor's cascade. See [Front Matter Cascade](#front-matter-cascade) for details.
+(`map`) A map of [build options].
-date
-: The datetime assigned to this page. This is usually fetched from the `date` field in front matter, but this behavior is configurable.
+[build options]: /content-management/build-options
-description
-: The description for the content.
+###### cascade {#cascade-field}
-draft
-: If `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command.
+(`map`) A map of front matter keys whose values are passed down to the page’s descendants unless overwritten by self or a closer ancestor’s cascade. See the [cascade] section for details.
-expiryDate
-: The datetime at which the content should no longer be published by Hugo; expired content will not be rendered unless the `--buildExpired` flag is passed to the `hugo` command.
+[cascade]: #cascade
-headless
-: If `true`, sets a leaf bundle to be [headless][headless-bundle].
+###### date
-images
-: An array of paths to images related to the page; used by [internal templates](/templates/internal) such as `_internal/twitter_cards.html`.
+(`string`) The date associated with the page, typically the creation date. Note that the TOML format also supports date/time values using unquoted strings. Access this value from a template using the [`Date`] method on a `Page` object.
-isCJKLanguage
-: If `true`, Hugo will explicitly treat the content as a CJK language; both `.Summary` and `.WordCount` work properly in CJK languages.
+[`date`]: /methods/page/date/
-keywords
-: The meta keywords for the content.
+###### description
-layout
-: The layout Hugo should select from the [lookup order][lookup] when rendering the content. If a `type` is not specified in the front matter, Hugo will look for the layout of the same name in the layout directory that corresponds with a content's section. See [Content Types][content type].
+(`string`) Conceptually different than the page `summary`, the description is typically rendered within a `meta` element within the `head` element of the published HTML file. Access this value from a template using the [`Description`] method on a `Page` object.
-lastmod
-: The datetime at which the content was last modified.
+[`description`]: /methods/page/description/
-linkTitle
-: Used for creating links to content; if set, Hugo defaults to using the `linkTitle` before the `title`.
+###### draft
-markup
-: **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown.
+(`bool`)
+If `true`, the page will not be rendered unless you pass the `--buildDrafts` flag to the `hugo` command. Access this value from a template using the [`Draft`] method on a `Page` object.
-outputs
-: Allows you to specify output formats specific to the content. See [output formats][outputs].
+[`draft`]: /methods/page/draft/
-publishDate
-: If in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`.
+###### expiryDate
-resources
-: Used for configuring page bundle resources. See [Page Resources][page-resources].
+(`string`) The page expiration date. On or after the expiration date, the page will not be rendered unless you pass the `--buildExpired` flag to the `hugo` command. Note that the TOML format also supports date/time values using unquoted strings. Access this value from a template using the [`ExpiryDate`] method on a `Page` object.
-series
-: An array of series this page belongs to, as a subset of the `series` [taxonomy](/content-management/taxonomies/); used by the `opengraph` [internal template](/templates/internal) to populate `og:see_also`.
+[`expirydate`]: /methods/page/expirydate/
-slug
-: Overrides the last segment of the URL path. Not applicable to section pages. See [URL Management](/content-management/urls/#slug) for details.
+###### headless
-summary
-: Text used when providing a summary of the article in the `.Summary` page variable; details available in the [content-summaries](/content-management/summaries/) section.
+(`bool`) Applicable to [leaf bundles], if `true` this value sets the `render` and `list` [build options] to `never`, creating a headless bundle of [page resources].
-title
-: The title for the content.
+[leaf bundles]: /content-management/page-bundles/#leaf-bundles
+[page resources]: /content-management/page-resources/
-type
-: The type of the content; this value will be automatically derived from the directory (i.e., the [section]) if not specified in front matter.
+###### isCJKLanguage
-url
-: Overrides the entire URL path. Applicable to regular pages and section pages. See [URL Management](/content-management/urls/#url) for details.
+(`bool`) Set to `true` if the content language is in the [CJK] family. This value determines how Hugo calculates word count, and affects the values returned by the [`WordCount`], [`FuzzyWordCount`], and [`Summary`] methods on a `Page` object.
-videos
-: An array of paths to videos related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:video`.
+[`fuzzywordcount`]: /methods/page/wordcount
+[`summary`]: /methods/page/wordcount
+[`wordcount`]: /methods/page/wordcount
+[cjk]: /getting-started/glossary/#cjk
-weight
-: used for [ordering your content in lists][ordering]. Lower weight gets higher precedence. So content with lower weight will come first. If set, weights should be non-zero, as 0 is interpreted as an *unset* weight.
+###### keywords
-{{% note %}}
-If neither `slug` nor `url` is present and [permalinks are not configured otherwise in your site configuration file](/content-management/urls/#permalinks), Hugo will use the file name of your content to create the output URL. See [Content Organization](/content-management/organization) for an explanation of paths in Hugo and [URL Management](/content-management/urls/) for ways to customize Hugo's default behaviors.
-{{% /note %}}
+(`string array`) An array of keywords, typically rendered within a `meta` element within the `head` element of the published HTML file, or used as a [taxonomy] to classify content. Access these values from a template using the [`Keywords`] method on a `Page` object.
-### User-defined
+[`keywords`]: /methods/page/keywords
+[taxonomy]: /getting-started/glossary/#taxonomy
-You can add fields to your front matter arbitrarily to meet your needs. These user-defined key-values are placed into a single `.Params` variable for use in your templates.
+
+
-The following fields can be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables] section provides more information on using Hugo's page- and site-level variables in your templates.
+
+
-{{< code-toggle >}}
-include_toc: true
-show_comments: false
-{{}}
+###### lastmod
+
+(`string`) The date that the page was last modified. Note that the TOML format also supports date/time values using unquoted strings. Access this value from a template using the [`Lastmod`] method on a `Page` object.
+
+[`lastmod`]: /methods/page/date/
+
+###### layout
+
+(`string`) Provide a template name to [target a specific template], overriding the default [template lookup order]. Set the value to the base file name of the template, excluding its extension. Access this value from a template using the [`Layout`] method on a `Page` object.
+
+[`layout`]: /methods/page/layout
+[template lookup order]: /templates/lookup-order
+[target a specific template]: templates/lookup-order/#target-a-template
+
+###### linkTitle
+
+(`string`) Typically a shorter version of the `title`. Access this value from a template using the [`LinkTitle`] method on a `Page` object.
+
+[`linktitle`]: /methods/page/linktitle/
+
+###### markup
+
+(`string`) A identifier corresponding to one of the supported [content formats]:
+
+Identifier|Content format
+:--|:--
+`adoc`|Asciidoc
+`html`|HTML
+`md`|Markdown
+`org`|Emacs Org Mode
+`pdc`|Pandoc
+`rst`|reStructuredText
+
+[content formats]: /content-management/formats
+
+###### menus
+
+(`string`,`string array`, or `map`) If set, Hugo adds the page to the given menu or menus. See the [menus] page for details.
+
+[menus]: /content-management/menus/#define-in-front-matter
+
+###### outputs
+
+(`string array`) The [output formats] to render.
+
+[output formats]: /templates/output-formats
+
+
+
+
+###### params
+
+(`map`) A map of custom [page parameters].
+
+[page parameters]: #parameters
+
+###### publishDate
+
+(`string`) The page publication date. Before the publication date, the page will not be rendered unless you pass the `--buildFuture` flag to the `hugo` command. Note that the TOML format also supports date/time values using unquoted strings. Access this value from a template using the [`PublishDate`] method on a `Page` object.
+
+[`publishdate`]: /methods/page/publishdate
+
+###### resources
+
+(`map array`) An array of maps to provide metadata for [page resources].
+
+[page-resources]: /content-management/page-resources/#page-resources-metadata
-## Front matter cascade
+###### sitemap
-Any node or section can pass down to descendants a set of front matter values as long as defined underneath the reserved `cascade` front matter key.
+(`map`) A map of sitemap options. See the [sitemap templates] page for details. Access these values from a template using the [`Sitemap`] method on a `Page` object.
+
+[sitemap templates]: /templates/sitemap-template/
+[`sitemap`]: /methods/page/sitemap
+
+###### slug
+
+(`string`) Overrides the last segment of the URL path. Not applicable to section pages. See the [URL management] page for details. Access this value from a template using the [`Slug`] method on a `Page` object.
+
+[`slug`]: /methods/page/slug
+[URL management]: /content-management/urls/#slug
+
+###### summary
+
+(`string`) Conceptually different than the page `description`, the summary either summarizes the content or serves a teaser to encourage readers to visit the page. Access this value from a template using the [`Summary`] method on a `Page` object.
+
+[`Summary`]: /methods/page/summary
+
+###### title
+
+(`string`) The page title. Access this value from a template using the [`Title`] method on a `Page` object.
+
+[`title`]: /methods/page/title
+
+###### translationKey
+
+(`string`) An arbitrary value used to relate two or mote translations of the same page, useful when the translated pages do not share a common path. Access this value from a template using the [`TranslationKey`] method on a `Page` object.
+
+[`translationkey`]: /methods/page/translationkey/
+
+###### type
+
+(`string`) The [content type], overriding the value derived from the top level section in which the page resides. Access this value from a template using the [`Type`] method on a `Page` object.
+
+[content type]: /getting-started/glossary/#content-type
+[`type`]: /methods/page/type
+
+###### url
+
+(`string`) Overrides the entire URL path. Applicable to regular pages and section pages. See the [URL management] page for details.
+
+###### weight
+(`int`) The page [weight], used to order the page within a [page collection]. Access this value from a template using the [`Weight`] method on a `Page` object.
+
+[page collection]: /getting-started/glossary/#page-collection
+[weight]: /getting-started/glossary/#weight
+[`weight`]: /methods/page/weight
+
+## Parameters
+
+Specify custom page parameters, including taxonomy terms, under the `params` key in front matter:
+
+{{< code-toggle file=content/example.md fm=true >}}
+title = 'Example'
+date = 2024-02-02T04:14:54-08:00
+draft = false
+weight = 10
+[params]
+myparam = 42
+tags = ['red','blue']
+{{< /code-toggle >}}
+
+Access these values from a template using the [`Params`] or [`Param`] method on a `Page` object.
+
+[`param`]: /methods/page/param
+[`params`]: /methods/page/params
+
+## Cascade
+
+Any [node] can pass down to its descendants a set of front matter values.
+
+[node]: /getting-started/glossary/#node
### Target specific pages
-The `cascade` block can be a slice with a optional `_target` keyword, allowing for multiple `cascade` values targeting different page sets.
+The `cascade` block can be an array with an optional `_target` keyword, allowing you to target different page sets while cascading values.
-{{< code-toggle >}}
-title ="Blog"
+{{< code-toggle file=content/_index.md fm=true >}}
+title ="Home"
[[cascade]]
+[cascade.params]
background = "yosemite.jpg"
[cascade._target]
-path="/blog/**"
+path="/articles/**"
lang="en"
kind="page"
[[cascade]]
+[cascade.params]
background = "goldenbridge.jpg"
[cascade._target]
kind="section"
{{}}
-Keywords available for `_target`:
+Use any combination of these keywords to target a set of pages:
-path
-: A [Glob](https://github.com/gobwas/glob) pattern matching the content path below /content. Expects Unix-styled slashes. Note that this is the virtual path, so it starts at the mount root. The matching supports double-asterisks so you can match for patterns like `/blog/*/**` to match anything from the third level and down.
+###### path {#cascade-path}
-kind
-: A Glob pattern matching the Page's Kind(s), e.g. "{home,section}".
+(`string`) A [Glob](https://github.com/gobwas/glob) pattern matching the content path below /content. Expects Unix-styled slashes. Note that this is the virtual path, so it starts at the mount root. The matching supports double-asterisks so you can match for patterns like `/blog/*/**` to match anything from the third level and down.
-lang
-: A Glob pattern matching the Page's language, e.g. "{en,sv}".
+###### kind {#cascade-kind}
+
+(`string`) A Glob pattern matching the Page's Kind(s), e.g. "{home,section}".
+
+###### lang {#cascade-lang}
+
+(`string`) A Glob pattern matching the Page's language, e.g. "{en,sv}".
+
+###### environment {#cascade-environment}
-environment
-: A Glob pattern matching the build environment, e.g. "{production,development}"
+(`string`) A Glob pattern matching the build environment, e.g. "{production,development}"
Any of the above can be omitted.
{{% note %}}
-When making a site that supports multiple languages, defining a `[[cascade]]` is recommended to be done in [Site Config](../../getting-started/configuration/#cascade) to prevent duplication.
+With a multilingual site it may be more efficient to define the `cascade` values in your site configuration to avoid duplicating the `cascade` values on the section page for each language.
-If you instead define a `[[cascade]]` in front matter for multiple languages, an `content/XX/foo/_index.md` file needs to be made on a per-language basis, with `XX` the glob pattern matching the Page's language. In this case, the **lang** keyword is ignored.
+With a multilingual site, if you choose to define the `cascade` values in front matter, you must create a [node] page for each language; the `lang` keyword is ignored.
+
+[node]: /getting-started/glossary/#node
{{% /note %}}
### Example
-In `content/blog/_index.md`
-
-{{< code-toggle >}}
-title: Blog
-cascade:
- banner: images/typewriter.jpg
+{{< code-toggle file=content/posts/_index.md fm=true >}}
+date = 2024-02-01T21:25:36-08:00
+title = 'Posts'
+[cascade]
+ [cascade.params]
+ banner = 'images/typewriter.jpg'
{{}}
-With the above example the Blog section page and its descendants will return `images/typewriter.jpg` when `.Params.banner` is invoked unless:
+With the above example the posts section page and its descendants will return `images/typewriter.jpg` when `.Params.banner` is invoked unless:
- Said descendant has its own `banner` value set
- Or a closer ancestor node has its own `cascade.banner` value set.
-## Order content through front matter
-
-You can assign content-specific `weight` in the front matter of your content. These values are especially useful for [ordering][ordering] in list views. You can use `weight` for ordering of content and the convention of [`_weight`][taxweight] for ordering content within a taxonomy. See [Ordering and Grouping Hugo Lists][lists] to see how `weight` can be used to organize your content in list views.
+## Emacs Org Mode
-## Override global markdown configuration
+If your [content format] is [Emacs Org Mode], you may provide front matter using Org Mode keywords. For example:
-It's possible to set some options for Markdown rendering in a content's front matter as an override to the [rendering options set in your project configuration][config].
+{{< code file=content/example.org lang=text >}}
+#+TITLE: Example
+#+DATE: 2024-02-02T04:14:54-08:00
+#+DRAFT: false
+#+MYPARAM: 42
+#+TAGS: red
+#+TAGS: blue
+#+WEIGHT: 10
+{{< /code >}}
-## Front matter format specs
+Note that you can also specify array elements on a single line:
-- [TOML Spec][toml]
-- [YAML Spec][yaml]
-- [JSON Spec][json]
+{{< code file=content/example.org lang=text >}}
+#+TAGS[]: red blue
+{{< /code >}}
-[variables]: /variables/
-[aliases]: /content-management/urls/#aliases
-[archetype]: /content-management/archetypes/
-[config]: /getting-started/configuration/
-[content type]: /content-management/types/
-[contentorg]: /content-management/organization/
-[headless-bundle]: /content-management/page-bundles/#headless-bundle
-[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf
-[lists]: /templates/lists/#sort-content
-[lookup]: /templates/lookup-order/
-[ordering]: /templates/lists/
-[outputs]: /templates/output-formats/
-[page-resources]: /content-management/page-resources/
-[pagevars]: /variables/page/
-[section]: /content-management/sections/
-[taxweight]: /content-management/taxonomies/
-[toml]: https://toml.io/
-[urls]: /content-management/urls/
-[variables]: /variables/
-[yaml]: https://yaml.org/spec/
+[content format]: /content-management/formats/
+[emacs org mode]: https://orgmode.org/
diff --git a/content/en/content-management/mathematics.md b/content/en/content-management/mathematics.md
index b4dca75b12d..69552763a81 100644
--- a/content/en/content-management/mathematics.md
+++ b/content/en/content-management/mathematics.md
@@ -152,8 +152,9 @@ If you set the `math` parameter to `false` in your site configuration, you must
{{< code-toggle file=content/math-examples.md fm=true >}}
title = 'Math examples'
-math = true
date = 2024-01-24T18:09:49-08:00
+[params]
+math = true
{{< /code-toggle >}}
## Inline delimiters
diff --git a/content/en/content-management/multilingual.md b/content/en/content-management/multilingual.md
index ea9f717870f..661302d8feb 100644
--- a/content/en/content-management/multilingual.md
+++ b/content/en/content-management/multilingual.md
@@ -309,7 +309,7 @@ To create a list of links to translated content, use a template similar to the f
diff --git a/content/en/content-management/page-bundles.md b/content/en/content-management/page-bundles.md
index 860fff2bbd9..74fc540243a 100644
--- a/content/en/content-management/page-bundles.md
+++ b/content/en/content-management/page-bundles.md
@@ -18,16 +18,16 @@ A Page Bundle can be one of:
- Leaf Bundle (leaf means it has no children)
- Branch Bundle (home page, section, taxonomy terms, taxonomy list)
-| | Leaf Bundle | Branch Bundle |
-|-------------------------------------|----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Usage | Collection of content and attachments for single pages | Collection of attachments for section pages (home page, section, taxonomy terms, taxonomy list) |
-| Index file name | `index.md` [^fn:1] | `_index.md` [^fn:1] |
-| Allowed Resources | Page and non-page (like images, PDF, etc.) types | Only non-page (like images, PDF, etc.) types |
-| Where can the Resources live? | At any directory level within the leaf bundle directory. | Only in the directory level **of** the branch bundle directory i.e. the directory containing the `_index.md` ([ref](https://discourse.gohugo.io/t/question-about-content-folder-structure/11822/4?u=kaushalmodi)). |
-| Layout type | [`single`](/templates/single-page-templates/) | [`list`](/templates/lists) |
-| Nesting | Does not allow nesting of more bundles under it | Allows nesting of leaf or branch bundles under it |
-| Example | `content/posts/my-post/index.md` | `content/posts/_index.md` |
-| Content from non-index page files...| Accessed only as page resources | Accessed only as regular pages |
+| | Leaf Bundle | Branch Bundle |
+|-------------------------------------|----------------------------------------------------------|-------------------------------------------------------------------------------------------------|
+| Usage | Collection of content and attachments for single pages | Collection of attachments for section pages (home page, section, taxonomy terms, taxonomy list) |
+| Index file name | `index.md` [^fn:1] | `_index.md` [^fn:1] |
+| Allowed Resources | Page and non-page (like images, PDF, etc.) types | Only non-page (like images, PDF, etc.) types |
+| Where can the Resources live? | At any directory level within the leaf bundle directory. | At any directory level within the branch bundle directory. |
+| Layout type | [`single`](/templates/single-page-templates/) | [`list`](/templates/lists) |
+| Nesting | Does not allow nesting of more bundles under it | Allows nesting of leaf or branch bundles under it |
+| Example | `content/posts/my-post/index.md` | `content/posts/_index.md` |
+| Content from non-index page files...| Accessed only as page resources | Accessed only as regular pages |
## Leaf bundles
diff --git a/content/en/content-management/shortcodes.md b/content/en/content-management/shortcodes.md
index bbc2b0cc83a..8488864e2d0 100644
--- a/content/en/content-management/shortcodes.md
+++ b/content/en/content-management/shortcodes.md
@@ -206,46 +206,23 @@ Rendered:
### `instagram`
-The `instagram` shortcode uses Facebook's **oEmbed Read** feature. The Facebook [developer documentation] states:
-
-- This permission or feature requires successful completion of the App Review process before your app can access live data. [Learn More]
-- This permission or feature is only available with business verification. You may also need to sign additional contracts before your app can access data. [Learn More Here]
-
-[developer documentation]: https://developers.facebook.com/docs/features-reference/oembed-read
-[Learn More]: https://developers.facebook.com/docs/app-review
-[Learn More Here]: https://developers.facebook.com/docs/development/release/business-verification
-
-You must obtain an Access Token to use the `instagram` shortcode.
-
-If your site configuration is private:
-
-{{< code-toggle file=hugo >}}
-[services.instagram]
-accessToken = 'xxx'
-{{< /code-toggle >}}
-
-If your site configuration is _not_ private, set the Access Token with an environment variable:
-
-```sh
-HUGO_SERVICES_INSTAGRAM_ACCESSTOKEN=xxx hugo --gc --minify
-```
-
-{{% note %}}
-If you are using a Client Access Token, you must combine the Access Token with your App ID using a pipe symbol (`APPID|ACCESSTOKEN`).
-{{% /note %}}
To display an Instagram post with this URL:
```text
-https://www.instagram.com/p/BWNjjyYFxVx/
+https://www.instagram.com/p/CxOWiQNP2MO/
```
Include this in your markdown:
```text
-{{}}
+{{}}
```
+Rendered:
+
+{{< instagram CxOWiQNP2MO >}}
+
### `param`
Gets a value from the current `Page's` parameters set in front matter, with a fallback to the site parameter value. It will log an `ERROR` if the parameter with the given key could not be found in either.
diff --git a/content/en/functions/data/GetCSV.md b/content/en/functions/data/GetCSV.md
index d61ea791d9a..ee9d302581a 100644
--- a/content/en/functions/data/GetCSV.md
+++ b/content/en/functions/data/GetCSV.md
@@ -15,6 +15,18 @@ action:
toc: true
---
+{{% deprecated-in 0.123.0 %}}
+Instead, use [`transform.Unmarshal`] with a [global], [page], or [remote] resource.
+
+See the [remote data example].
+
+[`transform.Unmarshal`]: /functions/transform/unmarshal/
+[global]: /getting-started/glossary/#global-resource
+[page]: /getting-started/glossary/#page-resource
+[remote data example]: /functions/resources/getremote/#remote-data
+[remote]: /getting-started/glossary/#remote-resource
+{{% /deprecated-in %}}
+
Given the following directory structure:
```text
diff --git a/content/en/functions/data/GetJSON.md b/content/en/functions/data/GetJSON.md
index 4db3c898804..d67badec38a 100644
--- a/content/en/functions/data/GetJSON.md
+++ b/content/en/functions/data/GetJSON.md
@@ -15,6 +15,18 @@ action:
toc: true
---
+{{% deprecated-in 0.123.0 %}}
+Instead, use [`transform.Unmarshal`] with a [global], [page], or [remote] resource.
+
+See the [remote data example].
+
+[`transform.Unmarshal`]: /functions/transform/unmarshal/
+[global]: /getting-started/glossary/#global-resource
+[page]: /getting-started/glossary/#page-resource
+[remote data example]: /functions/resources/getremote/#remote-data
+[remote]: /getting-started/glossary/#remote-resource
+{{% /deprecated-in %}}
+
Given the following directory structure:
```text
diff --git a/content/en/functions/diagrams/Goat.md b/content/en/functions/diagrams/Goat.md
index 2b31d9824d3..1d80bca38c2 100644
--- a/content/en/functions/diagrams/Goat.md
+++ b/content/en/functions/diagrams/Goat.md
@@ -14,7 +14,7 @@ toc: true
Useful in a code block [render hook], the `diagram.Goat` function converts ASCII art to an SVG diagram, returning a [GoAT] diagram object with the following methods:
[GoAT]: https://github.com/blampe/goat#readme
-[render hook]: https://gohugo.io/templates/render-hooks/
+[render hook]: /render-hooks
Inner
: (`template.HTML`) Returns the SVG child elements without a wrapping `svg` element, allowing you to create your own wrapper.
diff --git a/content/en/functions/fmt/Errorf.md b/content/en/functions/fmt/Errorf.md
index bbdd62c5307..0c966227464 100644
--- a/content/en/functions/fmt/Errorf.md
+++ b/content/en/functions/fmt/Errorf.md
@@ -8,6 +8,7 @@ action:
related:
- functions/fmt/Erroridf
- functions/fmt/Warnf
+ - functions/fmt/Warnidf
returnType: string
signatures: ['fmt.Errorf FORMAT [INPUT]']
aliases: [/functions/errorf]
diff --git a/content/en/functions/fmt/Erroridf.md b/content/en/functions/fmt/Erroridf.md
index 9884f493521..a8d53253a37 100644
--- a/content/en/functions/fmt/Erroridf.md
+++ b/content/en/functions/fmt/Erroridf.md
@@ -8,6 +8,7 @@ action:
related:
- functions/fmt/Errorf
- functions/fmt/Warnf
+ - functions/fmt/Warnidf
returnType: string
signatures: ['fmt.Erroridf ID FORMAT [INPUT]']
aliases: [/functions/erroridf]
@@ -15,7 +16,7 @@ aliases: [/functions/erroridf]
{{% include "functions/fmt/_common/fmt-layout.md" %}}
-The `erroridf` function evaluates the format string, then prints the result to the ERROR log and fails the build. Unlike the [`errorf`] function, you may suppress errors logged by the `erroridf` function by adding the message ID to the `ignoreErrors` array in your site configuration.
+The `erroridf` function evaluates the format string, then prints the result to the ERROR log and fails the build. Unlike the [`errorf`] function, you may suppress errors logged by the `erroridf` function by adding the message ID to the `ignoreLogs` array in your site configuration.
This template code:
@@ -28,13 +29,13 @@ Produces this console log:
```text
ERROR You should consider fixing this.
You can suppress this error by adding the following to your site configuration:
-ignoreErrors = ['error-42']
+ignoreLogs = ['error-42']
```
To suppress this message:
{{< code-toggle file=hugo >}}
-ignoreErrors = ["error-42"]
+ignoreLogs = ["error-42"]
{{< /code-toggle >}}
[`errorf`]: /functions/fmt/errorf
diff --git a/content/en/functions/fmt/Warnf.md b/content/en/functions/fmt/Warnf.md
index 0a90251d318..d619e94c492 100644
--- a/content/en/functions/fmt/Warnf.md
+++ b/content/en/functions/fmt/Warnf.md
@@ -8,6 +8,7 @@ action:
related:
- functions/fmt/Errorf
- functions/fmt/Erroridf
+ - functions/fmt/Warnidf
returnType: string
signatures: ['fmt.Warnf FORMAT [INPUT]']
aliases: [/functions/warnf]
diff --git a/content/en/functions/fmt/Warnidf.md b/content/en/functions/fmt/Warnidf.md
new file mode 100644
index 00000000000..5319fe9770d
--- /dev/null
+++ b/content/en/functions/fmt/Warnidf.md
@@ -0,0 +1,43 @@
+---
+title: fmt.Warnidf
+description: Log a suppressable WARNING from a template.
+categories: []
+keywords: []
+action:
+ aliases: [warnidf]
+ related:
+ - functions/fmt/Errorf
+ - functions/fmt/Erroridf
+ - functions/fmt/Warnf
+ returnType: string
+ signatures: ['fmt.Warnidf ID FORMAT [INPUT]']
+aliases: [/functions/warnidf]
+---
+
+{{< new-in 0.123.0 >}}
+
+{{% include "functions/fmt/_common/fmt-layout.md" %}}
+
+The `warnidf` function evaluates the format string, then prints the result to the WARNING log. Unlike the [`warnf`] function, you may suppress warnings logged by the `warnidf` function by adding the message ID to the `ignoreLogs` array in your site configuration.
+
+This template code:
+
+```go-html-template
+{{ warnidf "warning-42" "You should consider fixing this." }}
+```
+
+Produces this console log:
+
+```text
+WARN You should consider fixing this.
+You can suppress this warning by adding the following to your site configuration:
+ignoreLogs = ['warning-42']
+```
+
+To suppress this message:
+
+{{< code-toggle file=hugo >}}
+ignoreLogs = ["warning-42"]
+{{< /code-toggle >}}
+
+[`warnf`]: /functions/fmt/warnf
diff --git a/content/en/functions/transform/Markdownify.md b/content/en/functions/transform/Markdownify.md
index 8fb1e48ce38..1c204ab0fbf 100644
--- a/content/en/functions/transform/Markdownify.md
+++ b/content/en/functions/transform/Markdownify.md
@@ -26,6 +26,6 @@ To keep the wrapping `p` tags for a single paragraph, use the [`RenderString`] m
{{% 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.
-[markdown render hooks]: /templates/render-hooks/
+[markdown render hooks]: /render-hooks
[#9692]: https://github.com/gohugoio/hugo/issues/9692
{{% /note %}}
diff --git a/content/en/getting-started/configuration-markup.md b/content/en/getting-started/configuration-markup.md
index 607301d3afd..9bc1d4ed63a 100644
--- a/content/en/getting-started/configuration-markup.md
+++ b/content/en/getting-started/configuration-markup.md
@@ -56,9 +56,32 @@ 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
-Some settings explained:
+
+Extension|Documentation
+:--|:--
+cjk|[Goldmark Extensions: CJK]
+definitionList|[PHP Markdown Extra: Definition lists]
+footnote|[PHP Markdown Extra: Footnotes]
+linkify|[GitHub Flavored Markdown: Autolinks]
+passthrough|[Hugo Goldmark Extensions: Passthrough]
+strikethrough|[GitHub Flavored Markdown: Strikethrough]
+table|[GitHub Flavored Markdown: Tables]
+taskList|[GitHub Flavored Markdown: Task list items]
+typographer|[Goldmark Extensions: Typographer]
+
+[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: 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
+
+### Goldmark settings
hardWraps
: By default, Goldmark ignores newlines within a paragraph. Set to `true` to render newlines as ` ` elements.
@@ -212,7 +235,3 @@ endLevel
ordered
: If `true`, generates an ordered list instead of an unordered list.
-
-## Render hooks
-
-See [Markdown Render Hooks](/templates/render-hooks/).
diff --git a/content/en/getting-started/configuration.md b/content/en/getting-started/configuration.md
index 3ce0077ba59..5e7c8cfd7e2 100644
--- a/content/en/getting-started/configuration.md
+++ b/content/en/getting-started/configuration.md
@@ -234,10 +234,10 @@ See [Configure File Caches](#configure-file-caches).
###### 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 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 %}}
diff --git a/content/en/getting-started/glossary.md b/content/en/getting-started/glossary.md
index d4c1d0e26ca..c2546d5036a 100644
--- a/content/en/getting-started/glossary.md
+++ b/content/en/getting-started/glossary.md
@@ -22,6 +22,7 @@ weight: 60
[K](#kind)
[L](#layout)
[M](#map)
+[N](#node)
[O](#object)
[P](#page-bundle)
[R](#regular-page)
@@ -75,6 +76,10 @@ 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).
+
###### collection
An [array](#array), [slice](#slice), or [map](#map).
@@ -217,6 +222,10 @@ 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`.
+
###### object
A data structure with or without associated [methods](#method).
@@ -300,7 +309,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
diff --git a/content/en/methods/page/BundleType.md b/content/en/methods/page/BundleType.md
index 77d1d72eb33..5254757eeff 100644
--- a/content/en/methods/page/BundleType.md
+++ b/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/content/en/methods/page/File.md b/content/en/methods/page/File.md
index 44b752215ef..a1c9478c390 100644
--- a/content/en/methods/page/File.md
+++ b/content/en/methods/page/File.md
@@ -80,33 +80,33 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend
{{ end }}
```
-###### Lang
+###### LogicalName
-(`string`) The language associated with the given file.
+(`string`) The file name.
```go-html-template
{{ with .File }}
- {{ .Lang }}
+ {{ .LogicalName }}
{{ end }}
```
-###### LogicalName
+###### Path
-(`string`) The file name.
+(`string`) The file path, relative to the `content` directory.
```go-html-template
{{ with .File }}
- {{ .LogicalName }}
+ {{ .Path }}
{{ end }}
```
-###### Path
+###### Section
-(`string`) The file path, relative to the `content` directory.
+(`string`) The name of the top level section in which the file resides.
```go-html-template
{{ with .File }}
- {{ .Path }}
+ {{ .Section }}
{{ end }}
```
@@ -157,9 +157,9 @@ ContentBaseName|a|b|news
Dir|news/|news/b/|news/
Ext|md|md|md
Filename|/home/user/...|/home/user/...|/home/user/...
-Lang|en|en|en
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...
diff --git a/content/en/methods/page/Param.md b/content/en/methods/page/Param.md
index b2932d98102..daf09a5b4f0 100644
--- a/content/en/methods/page/Param.md
+++ b/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/content/en/methods/page/Params.md b/content/en/methods/page/Params.md
index 13416ada74f..43af7c21d30 100644
--- a/content/en/methods/page/Params.md
+++ b/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 >}}
diff --git a/content/en/methods/page/Path.md b/content/en/methods/page/Path.md
new file mode 100644
index 00000000000..34ac3854f3d
--- /dev/null
+++ b/content/en/methods/page/Path.md
@@ -0,0 +1,81 @@
+---
+title: Path
+description: Returns the canonical page path of the given page.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/File
+ - methods/page/RelPermalink
+ returnType: string
+ signatures: [PAGE.Path]
+---
+
+The `Path` method on a `Page` object returns the canonical page path of the given page, regardless of whether the page is backed by a file.
+
+```go-html-template
+{{ .Path }} → /posts/post-1
+```
+
+This value is neither a file path nor a relative URL. It is a canonical identifier for each page, independent of content format, language, and URL.
+
+{{% note %}}
+Beginning with the release of [v0.92.0] in January 2022, Hugo emitted a warning whenever the `Path` method was called. 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 canonical page 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 all 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.
+
+File path|Front matter slug|Value returned by .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`
+
+On a multilingual site, note that the return value is the same regardless of language:
+
+File path|Front matter slug|Value returned by .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`
+
+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 = /
+```
diff --git a/content/en/methods/site/LastChange.md b/content/en/methods/site/LastChange.md
index aceee691d02..6d4a7f95da1 100644
--- a/content/en/methods/site/LastChange.md
+++ b/content/en/methods/site/LastChange.md
@@ -9,10 +9,16 @@ 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
```
diff --git a/content/en/methods/site/Lastmod.md b/content/en/methods/site/Lastmod.md
new file mode 100644
index 00000000000..6d24b77c9ba
--- /dev/null
+++ b/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/content/en/methods/site/Sites.md b/content/en/methods/site/Sites.md
index f7bafd3ed2c..721c232c906 100644
--- a/content/en/methods/site/Sites.md
+++ b/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:
diff --git a/content/en/render-hooks/_index.md b/content/en/render-hooks/_index.md
new file mode 100644
index 00000000000..91c316a2e42
--- /dev/null
+++ b/content/en/render-hooks/_index.md
@@ -0,0 +1,17 @@
+---
+title: Render hooks
+linkTitle: Overview
+description: Create render hooks to override the rendering of markdown to HTML.
+categories: []
+keywords: []
+menu:
+ docs:
+ identifier: render-hooks-overview
+ 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/content/en/render-hooks/code-blocks.md b/content/en/render-hooks/code-blocks.md
new file mode 100755
index 00000000000..b52f8802c55
--- /dev/null
+++ b/content/en/render-hooks/code-blocks.md
@@ -0,0 +1,135 @@
+---
+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 page containing the code block.
+
+###### 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 .Page.Store.Get "hasMermaid" }}
+
+{{ end }}
+{{< /code >}}
+
+See the [diagrams] page for details.
+
+[diagrams]: /content-management/diagrams/#mermaid-diagrams
diff --git a/content/en/render-hooks/headings.md b/content/en/render-hooks/headings.md
new file mode 100755
index 00000000000..f0bf2b9dae2
--- /dev/null
+++ b/content/en/render-hooks/headings.md
@@ -0,0 +1,69 @@
+---
+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 page containing the heading.
+
+###### 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 >}}
diff --git a/content/en/render-hooks/images.md b/content/en/render-hooks/images.md
new file mode 100755
index 00000000000..33c4dcfd419
--- /dev/null
+++ b/content/en/render-hooks/images.md
@@ -0,0 +1,151 @@
+---
+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 page containing the image.
+
+###### 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 white space using the `{{‑ ‑}}` delimiter notation to prevent white space 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 v0.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]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/_markup/render-image.html
+
+{{< 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 provided that page resource duplication across languages is disabled. This is the default configuration for multilingual, single-host sites.
+{{% /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.
diff --git a/content/en/render-hooks/introduction.md b/content/en/render-hooks/introduction.md
new file mode 100755
index 00000000000..2119d4ba072
--- /dev/null
+++ b/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/content/en/render-hooks/links.md b/content/en/render-hooks/links.md
new file mode 100755
index 00000000000..941aff78541
--- /dev/null
+++ b/content/en/render-hooks/links.md
@@ -0,0 +1,121 @@
+---
+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 page containing the link.
+
+###### 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 white space using the `{{‑ ‑}}` delimiter notation to prevent white space 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 v0.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]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/_markup/render-link.html
+
+{{< 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 provided that page resource duplication across languages is disabled. This is the default configuration for multilingual, single-host sites.
+{{% /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 >}}
diff --git a/content/en/templates/introduction.md b/content/en/templates/introduction.md
index 7fb0ddecfb0..58bb2119e0c 100644
--- a/content/en/templates/introduction.md
+++ b/content/en/templates/introduction.md
@@ -522,7 +522,7 @@ The templating engine will strip the content within the HTML comment, but will f
## 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).
+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]).
## Use content (`Page`) parameters
@@ -533,8 +533,9 @@ An example of this is used in the Hugo docs. Most of the pages benefit from havi
Here is the example front matter:
{{< code-toggle file=content/example.md fm=true >}}
-title: Example
-notoc: true
+title = 'Example'
+[params]
+ notoc = true
{{< /code-toggle >}}
Here is an example of corresponding code that could be used inside a `toc.html` [partial template][partials]:
@@ -618,6 +619,7 @@ content/
title = 'Event 1'
date = 2021-12-06T10:37:16-08:00
draft = false
+[params]
start_date = 2021-12-05T09:00:00-08:00
end_date = 2021-12-05T11:00:00-08:00
{{< /code-toggle >}}
diff --git a/content/en/templates/output-formats.md b/content/en/templates/output-formats.md
index 0e95f3ffb78..ea662c34738 100644
--- a/content/en/templates/output-formats.md
+++ b/content/en/templates/output-formats.md
@@ -63,7 +63,7 @@ Given a media type and some additional configuration, you get an **Output Format
This is the full set of Hugo's built-in output formats:
-{{< datatable "config" "outputFormats" "name" "mediaType" "path" "baseName" "rel" "protocol" "isPlainText" "isHTML" "noUgly" "permalinkable" >}}
+{{< datatable "config" "outputFormats" "_key" "baseName" "isHTML" "isPlainText" "mediaType" "noUgly" "path" "permalinkable" "protocol" "rel" >}}
- A page can be output in as many output formats as you want, and you can have an infinite amount of output formats defined **as long as they resolve to a unique path on the file system**. In the above table, the best example of this is `amp` vs. `html`. `amp` has the value `amp` for `path` so it doesn't overwrite the `html` version; e.g. we can now have both `/index.html` and `/amp/index.html`.
- The `mediaType` must match a defined media type.
@@ -83,40 +83,56 @@ The above example is fictional, but if used for the homepage on a site with `bas
### Configure output formats
-The following is the full list of configuration options for output formats and their default values:
+Use these parameters when configuring an output format:
-mediaType
-: this must match the `Type` of a defined media type.
+baseName
+: (`string`) The base name of the published file. Default is `index`.
-path
-: sub path to save the output files.
+isHTML
+: (`bool`) If `true`, classifies the output format as HTML. Hugo uses this value to determine when to create alias redirects, when to inject the LiveReload script, etc. Default is `false`.
-baseName
-: the base file name for the list file names (homepage, etc.). **Default:** `index`.
+isPlainText
+: (`bool`) If `true`, Hugo parses templates for this output format with Go's [text/template] package instead of the [html/template] package. Default is `false`.
-rel
-: can be used to create `rel` values in `link` tags. **Default:** `alternate`.
+[html/template]: https://pkg.go.dev/html/template
+[text/template]: https://pkg.go.dev/text/template
-protocol
-: will replace the "http://" or "https://" in your `baseURL` for this output format.
+mediaType
+: (`string`) The [media type] of the published file. This must match a defined media type, either [built-in](#media-types) or custom.
-isPlainText
-: use Go's plain text templates parser for the templates. **Default:** `false`.
+[media type]: https://en.wikipedia.org/wiki/Media_type
-isHTML
-: used in situations only relevant for `HTML`-type formats; e.g., page aliases. **Default:** `false`.
+notAlternative
+: (`bool`) If `true`, excludes this output format from the values returned by the [`AlternativeOutputFormats`] method on a `Page` object. Default is `false`.
+
+[`AlternativeOutputFormats`]: /methods/page/alternativeoutputformats/
noUgly
-: used to turn off ugly URLs If `uglyURLs` is set to `true` in your site. **Default:** `false`.
+: (`bool`) If `true`, disables ugly URLs for this output format when `uglyURLs` is `true` in your site configuration. Default is `false`.
-notAlternative
-: enable if it doesn't make sense to include this format in an `AlternativeOutputFormats` format listing on `Page` (e.g., with `CSS`). Note that we use the term _alternative_ and not _alternate_ here, as it does not necessarily replace the other format. **Default:** `false`.
+path
+: (`string`) The path to the directory containing the published files, relative to the root of the publish directory.
permalinkable
-: make `.Permalink` and `.RelPermalink` return the rendering Output Format rather than main ([see below](#link-to-output-formats)). This is enabled by default for `HTML` and `AMP`. **Default:** `false`.
+: (`bool`) If `true`, the [`Permalink`] and [`RelPermalink`] methods on a `Page` object return the rendering output format rather than main ouptut format ([see below](#link-to-output-formats)). Enabled by default for the `html` and `amp` output formats. Default is `false`.
+
+[`Permalink`]: /methods/page/permalink/
+[`RelPermalink`]: /methods/page/relpermalink/
+
+protocol
+: (`string`) The protocol (scheme) of the URL for this output format. For example, `https://` or `webcal://`. Default is the scheme of the `baseURL` parameter in your site configuration, typically `https://`.
+
+rel
+: (`string`) If provided, you can assign this value to `rel` attributes in `link` elements when iterating over ouput formats in your templates. Default is `alternate`.
+
+root
+: (`bool`) If `true`, files will be published to the root of the publish directory. Default is `false`.
+
+ugly
+: (`bool`) If `true`, enables uglyURLs for this output format when `uglyURLs` is `false` in your site configuration. Default is `false`.
weight
-: Setting this to a non-zero value will be used as the first sort criteria.
+: (`int`) When set to a non-zero value, Hugo uses the `weight` as the first criteria when sorting output formats, falling back to the name of the output format. Lighter items float to the top, while heavier items sink to the bottom. Hugo renders output formats sequentially based on the sort order.
## Output formats for pages
@@ -172,7 +188,7 @@ Each `Page` has both an `.OutputFormats` (all formats, including the current) an
## Link to output formats
-`.Permalink` and `.RelPermalink` on `Page` will return the first output format defined for that page (usually `HTML` if nothing else is defined). This is regardless of the template file they are being called from.
+The `Permalink` and `RelPermalink` methods on a `Page` object return the first output format defined for that page (usually `HTML` if nothing else is defined). This is regardless of the template from which they are called.
__from `single.json.json`:__
```go-html-template
diff --git a/content/en/templates/render-hooks.md b/content/en/templates/render-hooks.md
deleted file mode 100644
index f91cb6b6ec6..00000000000
--- a/content/en/templates/render-hooks.md
+++ /dev/null
@@ -1,183 +0,0 @@
----
-title: Markdown render hooks
-linkTitle: Render hooks
-description: Render Hooks allow custom templates to override markdown rendering functionality.
-categories: [templates]
-keywords: [markdown]
-toc: true
-menu:
- docs:
- parent: templates
- weight: 200
-weight: 200
----
-
-Note that this is only supported with the [Goldmark](/getting-started/configuration-markup#goldmark) renderer.
-
-You can override certain parts of the default Markdown rendering to HTML by creating templates with base names `render-{kind}` in `layouts/_default/_markup`.
-
-You can also create type/section specific hooks in `layouts/[type/section]/_markup`, e.g.: `layouts/blog/_markup`.
-
-The hook kinds currently supported are:
-
-* `image`
-* `link`
-* `heading`
-* `codeblock`{{< new-in 0.93.0 >}}
-
-You can define [Output-Format-](/templates/output-formats) and [language-](/content-management/multilingual/)specific templates if needed. Your `layouts` folder may look like this:
-
-```text
-layouts/
-└── _default/
- └── _markup/
- ├── render-codeblock-bash.html
- ├── render-codeblock.html
- ├── render-heading.html
- ├── render-image.html
- ├── render-image.rss.xml
- └── render-link.html
-```
-
-Some use cases for the above:
-
-* Resolve link references using `.GetPage`. This would make links portable as you could translate `./my-post.md` (and similar constructs that would work on GitHub) into `/blog/2019/01/01/my-post/` etc.
-* Add `target=_blank` to external links.
-* Resolve and [process](/content-management/image-processing/) images.
-* Add [header links](https://remysharp.com/2014/08/08/automatic-permalinks-for-blog-posts).
-
-## Render hooks for headings, links and images
-
-### Context passed to `render-link` and `render-image`
-
-The `render-link` and `render-image` templates will receive this context:
-
-Page
-: The [Page](/variables/page/) being rendered.
-
-Destination
-: The URL.
-
-Title
-: The title attribute.
-
-Text
-: The rendered (HTML) link text.
-
-PlainText
-: The plain variant of the above.
-
-### Context passed to `render-heading`
-
-The `render-heading` template will receive this context:
-
-Page
-: The [Page](/variables/page/) being rendered.
-
-Level
-: The header level (1--6)
-
-Anchor
-: An auto-generated html id unique to the header within the page
-
-Text
-: The rendered (HTML) text.
-
-PlainText
-: The plain variant of the above.
-
-Attributes (map)
-: A map of attributes (e.g. `id`, `class`). Note that this will currently always be empty for links.
-
-The `render-image` templates will also receive:
-
-IsBlock {{< new-in 0.108.0 >}}
-: Returns true if this is a standalone image and the configuration option [markup.goldmark.parser.wrapStandAloneImageWithinParagraph](/getting-started/configuration-markup/#goldmark) is disabled.
-
-Ordinal {{< new-in 0.108.0 >}}
-: Zero-based ordinal for all the images in the current document.
-
-### Link with title markdown example
-
-```md
-[Text](https://www.gohugo.io "Title")
-```
-
-Here is a code example for how the render-link.html template could look:
-
-{{< code file=layouts/_default/_markup/render-link.html >}}
-{{ .Text | safeHTML }}
-{{< /code >}}
-
-### Image markdown example
-
-```md
-
-```
-
-Here is a code example for how the render-image.html template could look:
-
-{{< code file=layouts/_default/_markup/render-image.html >}}
-
-
-
-{{< /code >}}
-
-### Heading link example
-
-Given this template file
-
-{{< code file=layouts/_default/_markup/render-heading.html >}}
-{{ .Text | safeHTML }} ¶
-{{< /code >}}
-
-And this markdown
-
-```md
-### Section A
-```
-
-The rendered html will be
-
-```html
-
