--- /dev/null
- "^(\\s*`{3,}).*[\\s\\S]*?^\\1",
+{
+ "version": "0.2",
+ "allowCompoundWords": true,
+ "files": [
+ "**/*.md"
+ ],
+ "flagWords": [
+ "alot",
+ "hte",
+ "langauge",
+ "reccommend",
+ "seperate",
+ "teh"
+ ],
+ "ignorePaths": [
+ "**/emojis.md",
+ "**/commands/*",
+ "**/showcase/*",
+ "**/tools/*"
+ ],
+ "ignoreRegExpList": [
+ "# cspell: ignore fenced code blocks",
- "# cspell: ignore strings within single quotes",
- "'.+'",
++ "^(\\s*`{3,}).*[\\s\\S]*?^\\1$",
+ "# cspell: ignore words joined with dot",
+ "\\w+\\.\\w+",
+ "# cspell: ignore strings within backticks",
+ "`.+`",
- "antialiasing",
- "codeowners",
+ "# cspell: ignore strings within double quotes",
+ "\".+\"",
+ "# cspell: ignore strings within brackets",
+ "\\[.+\\]",
+ "# cspell: ignore strings within parentheses",
+ "\\(.+\\)",
+ "# cspell: ignore words that begin with a slash",
+ "/\\w+",
+ "# cspell: ignore everything within action delimiters",
+ "\\{\\{.+\\}\\}",
+ "# cspell: ignore everything after a right arrow",
+ "\\s+→\\s+.+"
+ ],
+ "language": "en",
+ "words": [
- "downscaled",
+ "composability",
+ "configurators",
+ "defang",
+ "deindent",
+ "downscale",
- "shortcode",
- "shortcodes",
+ "downscaling",
+ "exif",
+ "geolocalized",
+ "grayscale",
+ "marshal",
+ "marshaling",
+ "multihost",
++ "multiplatfom",
+ "performantly",
+ "preconfigured",
+ "prerendering",
+ "redirection",
+ "redirections",
- "subexpressions",
- "suppressable",
+ "subexpression",
- "transpiles",
++ "suppressible",
+ "templating",
+ "transpile",
- "unmarshals",
+ "unmarshal",
- "miesięcy",
+ "unmarshaling",
++ "unmarshals",
++ "# ----------------------------------------------------------------------",
++ "# cspell: ignore hugo terminology",
++ "# ----------------------------------------------------------------------",
++ "attrlink",
++ "canonify",
++ "codeowners",
++ "eturl",
++ "getenv",
++ "gohugo",
++ "gohugoio",
++ "keyvals",
++ "leftdelim",
++ "linkify",
++ "numworkermultiplier",
++ "rightdelim",
++ "shortcode",
++ "stringifier",
++ "struct",
++ "toclevels",
++ "zgotmplz",
+ "# ----------------------------------------------------------------------",
+ "# cspell: ignore foreign language words",
+ "# ----------------------------------------------------------------------",
+ "bezpieczeństwo",
++ "buch",
++ "descripción",
+ "dokumentation",
++ "erklärungen",
+ "libros",
++ "mercredi",
+ "miesiąc",
+ "miesiąc",
- "# cspell: ignore proper nouns",
++ "miesiąca",
++ "miesiące",
+ "miesięcy",
+ "misérables",
++ "mittwoch",
++ "muchos",
++ "novembre",
++ "otro",
++ "pocos",
++ "produkte",
+ "projekt",
++ "prywatność",
++ "referenz",
+ "régime",
+ "# ----------------------------------------------------------------------",
- "gohugoio",
++ "# cspell: ignore names",
+ "# ----------------------------------------------------------------------",
++ "Atishay",
++ "Cosette",
+ "Eliott",
++ "Furet",
+ "Gregor",
+ "Jaco",
++ "Lanczos",
++ "Ninke",
+ "Noll",
+ "Pastorius",
+ "Samsa",
++ "Stucki",
++ "Thénardier",
+ "# ----------------------------------------------------------------------",
+ "# cspell: ignore operating systems and software packages",
+ "# ----------------------------------------------------------------------",
+ "asciidoctor",
+ "brotli",
++ "cifs",
+ "corejs",
+ "disqus",
++ "docutils",
++ "dpkg",
+ "doas",
+ "eopkg",
+ "gitee",
- "KaTeX",
+ "goldmark",
- "MathJax",
++ "katex",
+ "kubuntu",
+ "lubuntu",
- "getenv",
- "gohugo",
++ "mathjax",
+ "nosql",
+ "pandoc",
+ "pkgin",
+ "rclone",
+ "xubuntu",
+ "# ----------------------------------------------------------------------",
+ "# cspell: ignore miscellaneous",
+ "# ----------------------------------------------------------------------",
++ "achristie",
++ "ddmaurier",
+ "dring",
- "stringifier",
- "struct",
+ "inor",
++ "jausten",
+ "jdoe",
++ "jsmith",
+ "milli",
+ "rgba",
+ "rsmith",
- "toclevels",
- "vals",
- "xfeff",
- "zgotmplz"
+ "tdewolff",
+ "tjones",
++ "wcag",
++ "xfeff"
+ ]
+}
--- /dev/null
- name = "CloudCannon"
- link = "https://cloudcannon.com/hugo-cms/"
- logo = "/images/sponsors/cloudcannon-white.svg"
- utm_campaign = "HugoSponsorship"
- utm_source = "sponsor"
- utm_content = "gohugo"
- bgcolor = "#034AD8"
+[[banners]]
+ name = "Linode"
+ link = "https://www.linode.com/"
+ logo = "images/sponsors/linode-logo.svg"
+ utm_campaign = "hugosponsor"
+ bgcolor = "#ffffff"
+
+[[banners]]
++ name = "Route4Me"
++ link = "https://route4me.com"
++ title = "Route Planning & Route Optimization Software"
++ utm_campaign = "hugosponsor"
++ bgcolor = "#334799"
++ link_attr = "style='color: #ffffff; font-weight: bold; text-decoration: none; text-align: center'"
+
+[[banners]]
+ name = "Your Company?"
+ link = "https://bep.is/en/hugo-sponsor-2023-01/"
+ utm_campaign = "hugosponsor"
+ show_on_hover = true
+ bgcolor = "#4e4f4f"
++ link_attr = "style='color: #ffffff; font-weight: bold; text-decoration: none; text-align: center'"
--- /dev/null
- {{- /* Last modified: 2023-09-04T09:23:04-07:00 */}}
++{{- /* Last modified: 2024-04-26T13:54:00-07:00 */}}
+
+{{- /*
+Copyright 2023 Veriphor LLC
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not
+use this file except in compliance with the License. You may obtain a copy of
+the License at
+
+https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+License for the specific language governing permissions and limitations under
+the License.
+*/}}
+
+{{- /*
+This render hook resolves internal destinations by looking for a matching:
+
+ 1. Content page
+ 2. Page resource (a file in the current page bundle)
+ 3. Section resource (a file in the current section)
+ 4. Global resource (a file in the assets directory)
+
+It skips the section resource lookup if the current page is a leaf bundle.
+
+External destinations are not modified.
+
+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:
+
+ [[module.mounts]]
+ source = 'assets'
+ target = 'assets'
+
+ [[module.mounts]]
+ source = 'static'
+ target = 'assets'
+
+By default, if this render hook is unable to resolve a destination, including a
+fragment if present, it passes the destination through without modification. To
+emit a warning or error, set the error level in your site configuration:
+
+ [params.render_hooks.link]
+ errorLevel = 'warning' # ignore (default), warning, or error (fails the build)
+
+When you set the error level to warning, and you are in a development
+environment, you can visually highlight broken internal links:
+
+ [params.render_hooks.link]
+ errorLevel = 'warning' # ignore (default), warning, or error (fails the build)
+ highlightBroken = true # true or false (default)
+
+This will add a "broken" class to anchor elements with invalid src attributes.
+Add a rule to your CSS targeting the broken links:
+
+ a.broken {
+ background: #ff0;
+ border: 2px solid #f00;
+ padding: 0.1em 0.2em;
+ }
+
+This render hook may be unable to resolve destinations created with the ref and
+relref shortcodes. Unless you set the error level to ignore you should not use
+either of these shortcodes in conjunction with this render hook.
+
+@context {string} Destination The link destination.
+@context {page} Page A reference to the page containing the link.
+@context {string} PlainText The link description as plain text.
+@context {string} Text The link description.
+@context {string} Title The link title.
+
+@returns {template.html}
+*/}}
+
+{{- /* Initialize. */}}
+{{- $renderHookName := "link" }}
+
+{{- /* Verify minimum required version. */}}
+{{- $minHugoVersion := "0.120.0" }}
+{{- if lt hugo.Version $minHugoVersion }}
+ {{- errorf "The %q render hook requires Hugo v%s or later." $renderHookName $minHugoVersion }}
+{{- end }}
+
+{{- /* Error level when unable to resolve destination: ignore, warning, or error. */}}
+{{- $errorLevel := or site.Params.render_hooks.link.errorLevel "ignore" | lower }}
+
+{{- /* If true, adds "broken" class to broken links. Applicable in development environment when errorLevel is warning. */}}
+{{- $highlightBrokenLinks := or site.Params.render_hooks.link.highlightBroken false }}
+
+{{- /* Validate error level. */}}
+{{- if not (in (slice "ignore" "warning" "error") $errorLevel) }}
+ {{- errorf "The %q render hook is misconfigured. The errorLevel %q is invalid. Please check your site configuration." $renderHookName $errorLevel }}
+{{- end }}
+
+{{- /* Determine content path for warning and error messages. */}}
+{{- $contentPath := "" }}
+{{- with .Page.File }}
+ {{- $contentPath = .Path }}
+{{- else }}
+ {{- $contentPath = .Path }}
+{{- end }}
+
+{{- /* Parse destination. */}}
+{{- $u := urls.Parse .Destination }}
+
+{{- /* Set common message. */}}
+{{- $msg := printf "The %q render hook was unable to resolve the destination %q in %s" $renderHookName $u.String $contentPath }}
+
+{{- /* Set attributes for anchor element. */}}
+{{- $attrs := dict "href" $u.String }}
+{{- if $u.IsAbs }}
+ {{- /* Destination is a remote resource. */}}
+ {{- $attrs = merge $attrs (dict "rel" "external") }}
+{{- else }}
+ {{- with $u.Path }}
- {{- with $p := or ($.Page.GetPage .) ($.Page.GetPage (strings.TrimRight "/" .)) }}
++ {{- with $p := or ($.PageInner.GetPage .) ($.PageInner.GetPage (strings.TrimRight "/" .)) }}
+ {{- /* Destination is a page. */}}
+ {{- $href := .RelPermalink }}
+ {{- with $u.RawQuery }}
+ {{- $href = printf "%s?%s" $href . }}
+ {{- end }}
+ {{- with $u.Fragment }}
+ {{- $ctx := dict
+ "contentPath" $contentPath
+ "errorLevel" $errorLevel
+ "page" $p
+ "parsedURL" $u
+ "renderHookName" $renderHookName
+ }}
+ {{- partial "inline/h-rh-l/validate-fragment.html" $ctx }}
+ {{- $href = printf "%s#%s" $href . }}
+ {{- end }}
+ {{- $attrs = dict "href" $href }}
+ {{- else }}
- {{- with $.Page.Resources.Get $u.Path }}
++ {{- with $.PageInner.Resources.Get $u.Path }}
+ {{- /* Destination is a page resource; drop query and fragment. */}}
+ {{- $attrs = dict "href" .RelPermalink }}
+ {{- else }}
+ {{- with (and (ne $.Page.BundleType "leaf") ($.Page.CurrentSection.Resources.Get $u.Path)) }}
+ {{- /* Destination is a section resource, and current page is not a leaf bundle. */}}
+ {{- $attrs = dict "href" .RelPermalink }}
+ {{- else }}
+ {{- with resources.Get $u.Path }}
+ {{- /* Destination is a global resource; drop query and fragment. */}}
+ {{- $attrs = dict "href" .RelPermalink }}
+ {{- else }}
+ {{- if eq $errorLevel "warning" }}
+ {{- warnf $msg }}
+ {{- if and $highlightBrokenLinks hugo.IsDevelopment }}
+ {{- $attrs = merge $attrs (dict "class" "broken") }}
+ {{- end }}
+ {{- else if eq $errorLevel "error" }}
+ {{- errorf $msg }}
+ {{- end }}
+ {{- end }}
+ {{- end }}
+ {{- end }}
+ {{- end }}
+ {{- else }}
+ {{- with $u.Fragment }}
+ {{- /* Destination is on the same page; prepend relative permalink. */}}
+ {{- $ctx := dict
+ "contentPath" $contentPath
+ "errorLevel" $errorLevel
+ "page" $.Page
+ "parsedURL" $u
+ "renderHookName" $renderHookName
+ }}
+ {{- partial "inline/h-rh-l/validate-fragment.html" $ctx }}
+ {{- $attrs = dict "href" (printf "%s#%s" $.Page.RelPermalink .) }}
+ {{- else }}
+ {{- if eq $errorLevel "warning" }}
+ {{- warnf $msg }}
+ {{- if and $highlightBrokenLinks hugo.IsDevelopment }}
+ {{- $attrs = merge $attrs (dict "class" "broken") }}
+ {{- end }}
+ {{- else if eq $errorLevel "error" }}
+ {{- errorf $msg }}
+ {{- end }}
+ {{- end }}
+ {{- end }}
+{{- end }}
- {{- with .Title }}
- {{- $attrs = merge $attrs (dict "title" .) }}
- {{- end -}}
++{{- $attrs = merge $attrs (dict "title" (.Title | transform.HTMLEscape)) }}
+
+{{- /* Render anchor element. */ -}}
+<a
+ {{- range $k, $v := $attrs }}
- {{- printf " %s=%q" $k $v | safeHTMLAttr }}
++ {{- if $v }}
++ {{- printf " %s=%q" $k $v | safeHTMLAttr }}
++ {{- end }}
+ {{- end -}}
+>{{ .Text | safeHTML }}</a>
+
+{{- define "partials/inline/h-rh-l/validate-fragment.html" }}
+ {{- /*
+ Validates the fragment portion of a link destination.
+
+ @context {string} contentPath The page containing the link.
+ @context {string} errorLevel The error level when unable to resolve destination; ignore (default), warning, or error.
+ @context {page} page The page corresponding to the link destination
+ @context {struct} parsedURL The link destination parsed by urls.Parse.
+ @context {string} renderHookName The name of the render hook.
+ */}}
+
+ {{- /* Initialize. */}}
+ {{- $contentPath := .contentPath }}
+ {{- $errorLevel := .errorLevel }}
+ {{- $p := .page }}
+ {{- $u := .parsedURL }}
+ {{- $renderHookName := .renderHookName }}
+
+ {{- /* Validate. */}}
+ {{- with $u.Fragment }}
+ {{- if $p.Fragments.Identifiers.Contains . }}
+ {{- if gt ($p.Fragments.Identifiers.Count .) 1 }}
+ {{- $msg := printf "The %q render hook detected duplicate heading IDs %q in %s" $renderHookName . $contentPath }}
+ {{- if eq $errorLevel "warning" }}
+ {{- warnf $msg }}
+ {{- else if eq $errorLevel "error" }}
+ {{- errorf $msg }}
+ {{- end }}
+ {{- end }}
+ {{- else }}
+ {{- /* Determine target path for warning and error message. */}}
+ {{- $targetPath := "" }}
+ {{- with $p.File }}
+ {{- $targetPath = .Path }}
+ {{- else }}
+ {{- $targetPath = .Path }}
+ {{- end }}
+ {{- /* Set common message. */}}
+ {{- $msg := printf "The %q render hook was unable to find heading ID %q in %s. See %s" $renderHookName . $targetPath $contentPath }}
+ {{- if eq $targetPath $contentPath }}
+ {{- $msg = printf "The %q render hook was unable to find heading ID %q in %s" $renderHookName . $targetPath }}
+ {{- end }}
+ {{- /* Throw warning or error. */}}
+ {{- if eq $errorLevel "warning" }}
+ {{- warnf $msg }}
+ {{- else if eq $errorLevel "error" }}
+ {{- errorf $msg }}
+ {{- end }}
+ {{- end }}
+ {{- end }}
+
+{{- end -}}
--- /dev/null
- <title>{{ .Site.Title }} – {{ .Title }}</title>
++{{- printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>" | safeHTML }}
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+ <channel>
- <description>Recent Hugo news from gohugo.io</description>
- <generator>Hugo -- gohugo.io</generator>{{ with .Site.LanguageCode }}
- <language>{{.}}</language>{{end}}{{ with .Site.Author.email }}
- <managingEditor>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</managingEditor>{{end}}{{ with .Site.Author.email }}
- <webMaster>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</webMaster>{{end}}{{ with .Site.Copyright }}
- <copyright>{{.}}</copyright>{{end}}{{ if not .Date.IsZero }}
- <lastBuildDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</lastBuildDate>{{ end }}
- <image>
- <url>{{ "img/hugo.png" | absURL }}</url>
- <title>GoHugo.io</title>
- <link>{{ .Permalink }}</link>
- </image>
- {{ with .OutputFormats.Get "RSS" }}
- {{ printf "<atom:link href=%q rel=\"self\" type=%q />" .Permalink .MediaType | safeHTML }}
- {{ end }}
- {{ range first 50 (where .Site.RegularPages "Type" "in" (slice "news" "showcase")) }}
- <item>
- <title>{{ .Section | title }}: {{ .Title }}</title>
- <link>{{ .Permalink }}</link>
- <pubDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</pubDate>
- {{ with .Site.Author.email }}<author>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</author>{{end}}
- <guid>{{ .Permalink }}</guid>
- <description>
- {{ $img := (.Resources.ByType "image").GetMatch "*featured*" }}
- {{ with $img }}
- {{ $img := .Resize "640x" }}
- {{ printf "<![CDATA[<img src=\"%s\" width=\"%d\" height=\"%d\"/>]]>" $img.Permalink $img.Width $img.Height | safeHTML }}
- {{ end }}
- {{ .Content | html }}
- </description>
- </item>
- {{ end }}
++ <title>Hugo News</title>
++ <description>Recent news about Hugo, a static site generator written in Go, optimized for speed and designed for flexibility.</description>
+ <link>{{ .Permalink }}</link>
- </rss>
++ <generator>Hugo {{ hugo.Version }}</generator>
++ <language>{{ or site.Language.LanguageCode site.Language.Lang }}</language>
++ {{- with site.Copyright }}
++ <copyright>{{ . }}</copyright>
++ {{- end }}
++ {{- with .OutputFormats.Get "RSS" }}
++ {{ printf "<atom:link href=%q rel=\"self\" type=%q />" .Permalink .MediaType | safeHTML }}
++ {{- end }}
++
++ {{- $news_items := slice }}
++
++ {{- /* Get releases from GitHub. */}}
++ {{- $u := "https://api.github.com/repos/gohugoio/hugo/releases" }}
++ {{- $releases := partial "utilities/get-remote-data.html" $u }}
++ {{- $releases = where $releases "draft" false }}
++ {{- $releases = where $releases "prerelease" false }}
++ {{- range $releases | first 20 }}
++ {{- $summary := printf
++ "Hugo %s was released on %s. See [release notes](%s) for details."
++ .tag_name
++ (.published_at | time.AsTime | time.Format "2 Jan 2006")
++ .html_url
++ }}
++ {{- $ctx := dict
++ "PublishDate" (.published_at | time.AsTime)
++ "Title" (printf "Release %s" .name)
++ "Permalink" .html_url
++ "Section" "news"
++ "Summary" ($summary | $.Page.RenderString)
++ }}
++ {{- $news_items = $news_items | append $ctx }}
++ {{- end }}
++
++ {{- /* Get content pages from news section. */}}
++ {{- range where site.RegularPages "Section" "news" }}
++ {{- $ctx := dict
++ "PublishDate" .PublishDate
++ "Title" .Title
++ "RelPermalink" .RelPermalink
++ "Section" "news"
++ "Summary" .Summary
++ "Params" (dict "description" .Description)
++ }}
++ {{- $news_items = $news_items | append $ctx }}
++ {{- end }}
++ {{- /* Sort, limit, and render lastBuildDate. */}}
++ {{- $limit := cond (gt site.Config.Services.RSS.Limit 1) site.Config.Services.RSS.Limit 999 }}
++ {{- $news_items = sort $news_items "PublishDate" "desc" | first $limit }}
++ <lastBuildDate>{{ (index $news_items 0).PublishDate.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</lastBuildDate>
++
++ {{- /* Render items. */}}
++ {{- range $news_items }}
++ <item>
++ <title>{{ .Title }}</title>
++ <link>{{ .Permalink }}</link>
++ <pubDate>{{ .PublishDate.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</pubDate>
++ <guid>{{ .Permalink }}</guid>
++ <description>{{ .Summary | transform.XMLEscape | safeHTML }}</description>
++ </item>
++ {{- end }}
+ </channel>
++</rss>
--- /dev/null
- {{ $releases := partial "inline/get-remote-data.html" $u }}
+{{ define "main" }}
+<div class="w-100 ph4 ph5-ns pb5 pb6-ns pt1 pt3-ns ">
+
+ <article class="cf pa3 pa4-m pa4-l nested-copy-line-height nested-img">
+ <h1 class="primary-color-dark">
+ {{ .Title }}
+ </h1>
+ <div class="nested-copy-line-height">
+ {{ .Content }}
+ </div>
+ </article>
+
+ <div class="flex flex-wrap">
+ {{ $interior_classes := $.Site.Params.flex_box_interior_classes }}
+ <section class="flex-ns flex-wrap justify-between w-100 w-80-nsTK v-top">
+
+ {{ $news_items := slice }}
+
+ {{/* Get releases from GitHub. */}}
+ {{ $u := "https://api.github.com/repos/gohugoio/hugo/releases" }}
-
- {{ define "partials/inline/get-remote-data.html" }}
- {{ $u := . }}
- {{ $r := "" }}
- {{ with $r = resources.GetRemote $u }}
- {{ with .Err }}
- {{ errorf "%s" . }}
- {{ end }}
- {{ else }}
- {{ errorf "Unable to get remote resource %q" $u }}
- {{ end }}
- {{ return ($r | transform.Unmarshal) }}
- {{ end }}
++ {{ $releases := partial "utilities/get-remote-data.html" $u }}
+ {{ $releases = where $releases "draft" false }}
+ {{ $releases = where $releases "prerelease" false }}
+ {{ range $releases | first 20 }}
+ {{ $ctx := dict
+ "Date" (.published_at | time.AsTime)
+ "Title" (printf "Release %s" .name)
+ "Permalink" .html_url
+ "Section" "news"
+ "Summary" ""
+ }}
+ {{ $news_items = $news_items | append $ctx }}
+ {{ end }}
+
+ {{/* Get content pages from news section. */}}
+ {{ range .Pages }}
+ {{ $ctx := dict
+ "Date" .Date
+ "Title" .Title
+ "RelPermalink" .RelPermalink
+ "Section" "news"
+ "Summary" .Summary
+ "Params" (dict "description" .Description)
+ }}
+ {{ $news_items = $news_items | append $ctx }}
+ {{ end }}
+
+ {{/* Sort by date (descending) and render. */}}
+ {{ range sort $news_items "Date" "desc" }}
+ {{ partial "boxes-section-summaries.html" (dict "context" . "classes" $interior_classes "fullcontent" false) }}
+ {{ end }}
+
+ </section>
+ </div>
+
+</div>
+{{ end }}
--- /dev/null
--- /dev/null
++{{- printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>" | safeHTML }}
++<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
++ <channel>
++ <title>Hugo News</title>
++ <description>Recent news about Hugo, a static site generator written in Go, optimized for speed and designed for flexibility.</description>
++ <link>{{ .Permalink }}</link>
++ <generator>Hugo {{ hugo.Version }}</generator>
++ <language>{{ or site.Language.LanguageCode site.Language.Lang }}</language>
++ {{- with site.Copyright }}
++ <copyright>{{ . }}</copyright>
++ {{- end }}
++ {{- with .OutputFormats.Get "RSS" }}
++ {{ printf "<atom:link href=%q rel=\"self\" type=%q />" .Permalink .MediaType | safeHTML }}
++ {{- end }}
++
++ {{- $news_items := slice }}
++
++ {{- /* Get releases from GitHub. */}}
++ {{- $u := "https://api.github.com/repos/gohugoio/hugo/releases" }}
++ {{- $releases := partial "utilities/get-remote-data.html" $u }}
++ {{- $releases = where $releases "draft" false }}
++ {{- $releases = where $releases "prerelease" false }}
++ {{- range $releases | first 20 }}
++ {{- $summary := printf
++ "Hugo %s was released on %s. See [release notes](%s) for details."
++ .tag_name
++ (.published_at | time.AsTime | time.Format "2 Jan 2006")
++ .html_url
++ }}
++ {{- $ctx := dict
++ "PublishDate" (.published_at | time.AsTime)
++ "Title" (printf "Release %s" .name)
++ "Permalink" .html_url
++ "Section" "news"
++ "Summary" ($summary | $.Page.RenderString)
++ }}
++ {{- $news_items = $news_items | append $ctx }}
++ {{- end }}
++
++ {{- /* Get content pages from news section. */}}
++ {{- range .Pages }}
++ {{- $ctx := dict
++ "PublishDate" .PublishDate
++ "Title" .Title
++ "RelPermalink" .RelPermalink
++ "Section" "news"
++ "Summary" .Summary
++ "Params" (dict "description" .Description)
++ }}
++ {{- $news_items = $news_items | append $ctx }}
++ {{- end }}
++ {{- /* Sort, limit, and render lastBuildDate. */}}
++ {{- $limit := cond (gt site.Config.Services.RSS.Limit 1) site.Config.Services.RSS.Limit 999 }}
++ {{- $news_items = sort $news_items "PublishDate" "desc" | first $limit }}
++ <lastBuildDate>{{ (index $news_items 0).PublishDate.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</lastBuildDate>
++
++ {{- /* Render items. */}}
++ {{- range $news_items }}
++ <item>
++ <title>{{ .Title }}</title>
++ <link>{{ .Permalink }}</link>
++ <pubDate>{{ .PublishDate.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</pubDate>
++ <guid>{{ .Permalink }}</guid>
++ <description>{{ .Summary | transform.XMLEscape | safeHTML }}</description>
++ </item>
++ {{- end }}
++ </channel>
++</rss>
--- /dev/null
- <img src="/images/GitHub-Mark-64px.png" alt="Github Logo" class="tc center">
+<div class="w-100 center pt5">
+ <div class="w-100 w-40-l tc center">
++ <img src="/images/Github.svg" alt="Github Logo" class="tc center">
+ </div>
+</div>
+
+<div class="flex-ns flex-wrap center pb4 center mw9">
+ <!-- LEFT -->
+ <div class="w-100 tc w-third-l">
+ <h3 class="f3 mv3 accent-color-light">We welcome all contributions</h3>
+ <ul class="list ma0 pa0">
+ <li class="mb3 f4">
+
+ <a href="https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md" class="link mid-gray dim">
+ Fork the repo and work on an issue {{ partial "svg/link-ext.svg" (dict "fill" "#333" "size" "14") }}
+ </a>
+ </li>
+ <li class="mb3 f4">
+ <a href="https://themes.gohugo.io/" class="link mid-gray dim">
+ Design a theme {{ partial "svg/link-ext.svg" (dict "fill" "#333" "size" "14") }}
+ </a>
+ </li>
+ </ul>
+
+ </div>
+
+
+ <div class="w-100 w-third-l tc">
+ <div class="w-60-l center">
+
+ <p class="f4">Hugo is open-source and completely free.</p>
+ <p class="f4">Our hundreds of contributors make Hugo great.</p>
+ </div>
+ </div>
+
+
+ <div class="w-100 tc w-third-l">
+ <h3 class="f3 mv3 accent-color-light">More ways to contribute</h3>
+ <ul class="list ma0 pa0">
+ <li class="mb3 f4">
+ <a href="https://gohugo.io/overview/introduction/" class="link mid-gray dim">
+ Help improve the docs {{ partial "svg/link-ext.svg" (dict "fill" "#333" "size" "14") }}
+ </a>
+ </li>
+
+ <li class="mb3 f4">
+
+ <a href="https://discourse.gohugo.io/" class="link mid-gray dim">
+ Help others in the forums {{ partial "svg/link-ext.svg" (dict "fill" "#333" "size" "14") }}
+ </a>
+ </li>
+ </ul>
+ </div>
+
+
+ <!-- RIGHT -->
+
+
+</div>
--- /dev/null
- {{ if hugo.IsProduction }}
- {{ $gtagID := printf "Sponsor %s %s" .name $gtag | title }}
- <a
- href="{{ $url }}"
- onclick="trackOutboundLink({{ printf "'%s', '%s'" $gtagID $url | safeJS }});"
- class="w-100 grow pa3{{ if .show_on_hover }}
- show-on-hover
- {{ end }}"
- style="">
- {{ with $logo }}{{ .Content | safeHTML }}{{ end }}
- </a>
+{{ $classes_box := "ba b--dark-gray bg-light-gray br3 flex flex-column flex-wrap items-center justify-center ph3 pv4 mb4 w-100 w-30-l " }}
+{{ $gtag := .gtag | default "unknown" }}
+{{ $classes_box := "ba b--dark-gray bg-light-gray br3 flex flex-column flex-wrap items-center justify-center ph3 pv4 mb4 w-100 w-30-l " }}
+{{ $gtag := .gtag | default "unknown" }}
+{{ $isFooter := (eq $gtag "footer") }}
+{{ $utmSource := cond $isFooter "hugofooter" "hugohome" }}
+{{ with .cx.Site.Data.sponsors }}
+ <style>
+ a.show-on-hover {
+ opacity: 0;
+ }
+ a.show-on-hover:hover {
+ opacity: 1;
+ }
+ </style>
+ <section
+ class="{{ $.classes_section | default "bg-primary-color-dark b--dark-gray bb bt ph5 pv4 w-100" }}">
+ <div class="center mw9">
+ <h3 class="b f3 mv0 light-gray">Hugo Sponsors</h3>
+ <div class="flex-ns flex-wrap center justify-between pt3">
+ {{ range .banners }}
+ <div
+ class="{{ $classes_box }} o-100"
+ style="background-color: {{ .bgcolor }};">
+ {{ $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 }}
- <a
- href="{{ $url }}"
- class="w-100 grow pa3{{ if .show_on_hover }}
- show-on-hover
- {{ end }}">
- {{ with $logo }}{{ .Content | safeHTML }}{{ end }}
- </a>
++ {{ $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 }}
++ {{ $classes = printf "%s f1" $classes }}
+ {{ end }}
++ <a
++ href="{{ $url }}"
++ title="{{ .title | default .name }}"
++ {{ if hugo.IsProduction }}
++ onclick="trackOutboundLink({{ printf "'%s', '%s'" $gtagID $url | safeJS }});"
++ {{ end }}
++ class="w-100 grow pa3 {{ $classes }}"
++ {{ with .link_attr }}{{ . | safeHTMLAttr }}{{ end }}>
++ {{ with $logo }}
++ {{ .Content | safeHTML }}
++ {{ else }}
++ {{ .name }}
++ {{ end }}
++ </a>
+ </div>
+ {{ end }}
+ </div>
+ </div>
+ </section>
+{{ end }}
--- /dev/null
--- /dev/null
++{{/*
++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 }}
--- /dev/null
--- /dev/null
++{{- /*
++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 -}}
--- /dev/null
- "autoorient" "brightness" "colorbalance" "colorize" "contrast" "gamma"
- "gaussianblur" "grayscale" "hue" "invert" "none" "opacity" "overlay"
+{{- /*
+Renders the given image using the given filter, if any.
+
+@param {string} src The path to the image which must be a remote, page, or global resource.
+@param {string} [filter] The filter to apply to the image (case-insensitive).
+@param {string} [filterArgs] A comma-delimited list of arguments to pass to the filter.
+@param {bool} [example=false] If true, renders a before/after example.
+@param {int} [exampleWidth=384] Image width, in pixels, when rendering a before/after example.
+
+@returns {template.HTML}
+
+@examples
+
+ {{< img src="zion-national-park.jpg" >}}
+
+ {{< img src="zion-national-park.jpg" alt="Zion National Park" >}}
+
+ {{< img
+ src="zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="grayscale"
+ >}}
+
+ {{< img
+ src="zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="process"
+ filterArgs="resize 400x webp"
+ >}}
+
+ {{< img
+ src="zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="colorize"
+ filterArgs="180,50,20"
+ >}}
+
+ {{< img
+ src="zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="grayscale"
+ example=true
+ >}}
+
+ {{< img
+ src="zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="grayscale"
+ example=true
+ exampleWidth=400
+ >}}
+
+ When using the text filter, provide the arguments in this order:
+
+ 0. The text
+ 1. The horizontal offset, in pixels, relative to the left of the image (default 20)
+ 2. The vertical offset, in pixels, relative to the top of the image (default 20)
+ 3. The font size in pixels (default 64)
+ 4. The line height (default 1.2)
+ 5. The font color (default #ffffff)
+
+ {{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Text"
+ filterArgs="Zion National Park,25,250,56"
+ example=true
+ >}}
+
+ When using the padding filter, provide all arguments in this order:
+
+ 0. Padding top
+ 1. Padding right
+ 2. Padding bottom
+ 3. Padding right
+ 4. Canvas color
+
+ {{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Padding"
+ filterArgs="20,50,20,50,#0705"
+ example=true
+ >}}
+
+*/}}
+
+{{- /* Initialize. */}}
+{{- $alt := "" }}
+{{- $src := "" }}
+{{- $filter := "" }}
+{{- $filterArgs := slice }}
+{{- $example := false }}
+{{- $exampleWidth := 384 }}
+
+{{- /* Default values to use with the text filter. */}}
+{{ $textFilterOpts := dict
+ "xOffset" 20
+ "yOffset" 20
+ "fontSize" 64
+ "lineHeight" 1.2
+ "fontColor" "#ffffff"
+ "fontPath" "https://github.com/google/fonts/raw/main/ofl/lato/Lato-Regular.ttf"
+}}
+
+{{- /* Get and validate parameters. */}}
+{{- with .Get "alt" }}
+ {{- $alt = .}}
+{{- end }}
+
+{{- with .Get "src" }}
+ {{- $src = . }}
+{{- else }}
+ {{- errorf "The %q shortcode requires a file parameter. See %s" .Name .Position }}
+{{- end }}
+
+{{- with .Get "filter" }}
+ {{- $filter = . | lower }}
+{{- end }}
+
+{{- $validFilters := slice
- {{- errorf "%s" }}
++ "autoorient" "brightness" "colorbalance" "colorize" "contrast" "dither"
++ "gamma" "gaussianblur" "grayscale" "hue" "invert" "none" "opacity" "overlay"
+ "padding" "pixelate" "process" "saturation" "sepia" "sigmoid" "text"
+ "unsharpmask"
+}}
+
+{{- with $filter }}
+ {{- if not (in $validFilters .) }}
+ {{- errorf "The filter passed to the %q shortcode is invalid. The filter must be one of %s. See %s" $.Name (delimit $validFilters ", " ", or ") $.Position }}
+ {{- end }}
+{{- end }}
+
+{{- with .Get "filterArgs" }}
+ {{- $filterArgs = split . "," }}
+ {{- $filterArgs = apply $filterArgs "trim" "." " " }}
+{{- end }}
+
+{{- if in (slice "false" false 0) (.Get "example") }}
+ {{- $example = false }}
+{{- else if in (slice "true" true 1) (.Get "example")}}
+ {{- $example = true }}
+{{- end }}
+
+{{- with .Get "exampleWidth" }}
+ {{- $exampleWidth = . | int }}
+{{- end }}
+
+{{- /* Get image. */}}
+{{- $ctx := dict "page" .Page "src" $src "name" .Name "position" .Position }}
+{{- $i := partial "inline/get-resource.html" $ctx }}
+
+{{- /* Resize if rendering before/after examples. */}}
+{{- if $example }}
+ {{- $i = $i.Resize (printf "%dx" $exampleWidth) }}
+{{- end }}
+
+{{- /* Create filter. */}}
+{{- $f := "" }}
+{{- $ctx := dict "filter" $filter "args" $filterArgs "name" .Name "position" .Position }}
+{{- if eq $filter "autoorient" }}
+ {{- $ctx = merge $ctx (dict "argsRequired" 0) }}
+ {{- template "validate-arg-count" $ctx }}
+ {{- $f = images.AutoOrient }}
+{{- else if eq $filter "brightness" }}
+ {{- $ctx = merge $ctx (dict "argsRequired" 1) }}
+ {{- template "validate-arg-count" $ctx }}
+ {{- $filterArgs = apply $filterArgs "float" "." }}
+ {{- $ctx = merge $ctx (dict "argName" "percentage" "argValue" (index $filterArgs 0) "min" -100 "max" 100) }}
+ {{- template "validate-arg-value" $ctx }}
+ {{- $f = images.Brightness (index $filterArgs 0) }}
+{{- else if eq $filter "colorbalance" }}
+ {{- $ctx = merge $ctx (dict "argsRequired" 3) }}
+ {{- template "validate-arg-count" $ctx }}
+ {{- $filterArgs = apply $filterArgs "float" "." }}
+ {{- $ctx = merge $ctx (dict "argName" "percentage red" "argValue" (index $filterArgs 0) "min" -100 "max" 500) }}
+ {{- template "validate-arg-value" $ctx }}
+ {{- $ctx = merge $ctx (dict "argName" "percentage green" "argValue" (index $filterArgs 1) "min" -100 "max" 500) }}
+ {{- template "validate-arg-value" $ctx }}
+ {{- $ctx = merge $ctx (dict "argName" "percentage blue" "argValue" (index $filterArgs 2) "min" -100 "max" 500) }}
+ {{- template "validate-arg-value" $ctx }}
+ {{- $f = images.ColorBalance (index $filterArgs 0) (index $filterArgs 1) (index $filterArgs 2) }}
+{{- else if eq $filter "colorize" }}
+ {{- $ctx = merge $ctx (dict "argsRequired" 3) }}
+ {{- template "validate-arg-count" $ctx }}
+ {{- $filterArgs = apply $filterArgs "float" "." }}
+ {{- $ctx = merge $ctx (dict "argName" "hue" "argValue" (index $filterArgs 0) "min" 0 "max" 360) }}
+ {{- template "validate-arg-value" $ctx }}
+ {{- $ctx = merge $ctx (dict "argName" "saturation" "argValue" (index $filterArgs 1) "min" 0 "max" 100) }}
+ {{- template "validate-arg-value" $ctx }}
+ {{- $ctx = merge $ctx (dict "argName" "percentage" "argValue" (index $filterArgs 2) "min" 0 "max" 100) }}
+ {{- template "validate-arg-value" $ctx }}
+ {{- $f = images.Colorize (index $filterArgs 0) (index $filterArgs 1) (index $filterArgs 2) }}
+{{- else if eq $filter "contrast" }}
+ {{- $ctx = merge $ctx (dict "argsRequired" 1) }}
+ {{- template "validate-arg-count" $ctx }}
+ {{- $filterArgs = apply $filterArgs "float" "." }}
+ {{- $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 }}
+ {{- $filterArgs = apply $filterArgs "float" "." }}
+ {{- $ctx = merge $ctx (dict "argName" "gamma" "argValue" (index $filterArgs 0) "min" 0 "max" 100) }}
+ {{- template "validate-arg-value" $ctx }}
+ {{- $f = images.Gamma (index $filterArgs 0) }}
+{{- else if eq $filter "gaussianblur" }}
+ {{- $ctx = merge $ctx (dict "argsRequired" 1) }}
+ {{- template "validate-arg-count" $ctx }}
+ {{- $filterArgs = apply $filterArgs "float" "." }}
+ {{- $ctx = merge $ctx (dict "argName" "sigma" "argValue" (index $filterArgs 0) "min" 0 "max" 1000) }}
+ {{- template "validate-arg-value" $ctx }}
+ {{- $f = images.GaussianBlur (index $filterArgs 0) }}
+{{- else if eq $filter "grayscale" }}
+ {{- $ctx = merge $ctx (dict "argsRequired" 0) }}
+ {{- template "validate-arg-count" $ctx }}
+ {{- $f = images.Grayscale }}
+{{- else if eq $filter "hue" }}
+ {{- $ctx = merge $ctx (dict "argsRequired" 1) }}
+ {{- template "validate-arg-count" $ctx }}
+ {{- $filterArgs = apply $filterArgs "float" "." }}
+ {{- $ctx = merge $ctx (dict "argName" "shift" "argValue" (index $filterArgs 0) "min" -180 "max" 180) }}
+ {{- template "validate-arg-value" $ctx }}
+ {{- $f = images.Hue (index $filterArgs 0) }}
+{{- else if eq $filter "invert" }}
+ {{- $ctx = merge $ctx (dict "argsRequired" 0) }}
+ {{- template "validate-arg-count" $ctx }}
+ {{- $f = images.Invert }}
+{{- else if eq $filter "opacity" }}
+ {{- $ctx = merge $ctx (dict "argsRequired" 1) }}
+ {{- template "validate-arg-count" $ctx }}
+ {{- $filterArgs = apply $filterArgs "float" "." }}
+ {{- $ctx = merge $ctx (dict "argName" "opacity" "argValue" (index $filterArgs 0) "min" 0 "max" 1) }}
+ {{- template "validate-arg-value" $ctx }}
+ {{- $f = images.Opacity (index $filterArgs 0) }}
+{{- else if eq $filter "overlay" }}
+ {{- $ctx = merge $ctx (dict "argsRequired" 3) }}
+ {{- template "validate-arg-count" $ctx }}
+ {{- $ctx := dict "src" (index $filterArgs 0) "name" .Name "position" .Position }}
+ {{- $overlayImg := partial "inline/get-resource.html" $ctx }}
+ {{- $f = images.Overlay $overlayImg (index $filterArgs 1 | float ) (index $filterArgs 2 | float) }}
+{{- else if eq $filter "padding" }}
+ {{- $ctx = merge $ctx (dict "argsRequired" 5) }}
+ {{- template "validate-arg-count" $ctx }}
+ {{- $f = images.Padding
+ (index $filterArgs 0 | int)
+ (index $filterArgs 1 | int)
+ (index $filterArgs 2 | int)
+ (index $filterArgs 3 | int)
+ (index $filterArgs 4)
+ }}
+{{- else if eq $filter "pixelate" }}
+ {{- $ctx = merge $ctx (dict "argsRequired" 1) }}
+ {{- template "validate-arg-count" $ctx }}
+ {{- $filterArgs = apply $filterArgs "float" "." }}
+ {{- $ctx = merge $ctx (dict "argName" "size" "argValue" (index $filterArgs 0) "min" 0 "max" 1000) }}
+ {{- template "validate-arg-value" $ctx }}
+ {{- $f = images.Pixelate (index $filterArgs 0) }}
+{{- else if eq $filter "process" }}
+ {{- $ctx = merge $ctx (dict "argsRequired" 1) }}
+ {{- template "validate-arg-count" $ctx }}
+ {{- $f = images.Process (index $filterArgs 0) }}
+{{- else if eq $filter "saturation" }}
+ {{- $ctx = merge $ctx (dict "argsRequired" 1) }}
+ {{- template "validate-arg-count" $ctx }}
+ {{- $filterArgs = apply $filterArgs "float" "." }}
+ {{- $ctx = merge $ctx (dict "argName" "percentage" "argValue" (index $filterArgs 0) "min" -100 "max" 500) }}
+ {{- template "validate-arg-value" $ctx }}
+ {{- $f = images.Saturation (index $filterArgs 0) }}
+{{- else if eq $filter "sepia" }}
+ {{- $ctx = merge $ctx (dict "argsRequired" 1) }}
+ {{- template "validate-arg-count" $ctx }}
+ {{- $filterArgs = apply $filterArgs "float" "." }}
+ {{- $ctx = merge $ctx (dict "argName" "percentage" "argValue" (index $filterArgs 0) "min" 0 "max" 100) }}
+ {{- template "validate-arg-value" $ctx }}
+ {{- $f = images.Sepia (index $filterArgs 0) }}
+{{- else if eq $filter "sigmoid" }}
+ {{- $ctx = merge $ctx (dict "argsRequired" 2) }}
+ {{- template "validate-arg-count" $ctx }}
+ {{- $filterArgs = apply $filterArgs "float" "." }}
+ {{- $ctx = merge $ctx (dict "argName" "midpoint" "argValue" (index $filterArgs 0) "min" 0 "max" 1) }}
+ {{- template "validate-arg-value" $ctx }}
+ {{- $ctx = merge $ctx (dict "argName" "factor" "argValue" (index $filterArgs 1) "min" -10 "max" 10) }}
+ {{- template "validate-arg-value" $ctx }}
+ {{- $f = images.Sigmoid (index $filterArgs 0) (index $filterArgs 1) }}
+{{- else if eq $filter "text" }}
+ {{- $ctx = merge $ctx (dict "argsRequired" 1) }}
+ {{- template "validate-arg-count" $ctx }}
+ {{- $ctx := dict "src" $textFilterOpts.fontPath "name" .Name "position" .Position }}
+ {{- $font := or (partial "inline/get-resource.html" $ctx) }}
+ {{- $fontSize := or (index $filterArgs 3 | int) $textFilterOpts.fontSize }}
+ {{- $lineHeight := math.Max (or (index $filterArgs 4 | float) $textFilterOpts.lineHeight) 1 }}
+ {{- $opts := dict
+ "x" (or (index $filterArgs 1 | int) $textFilterOpts.xOffset)
+ "y" (or (index $filterArgs 2 | int) $textFilterOpts.yOffset)
+ "size" $fontSize
+ "linespacing" (mul (sub $lineHeight 1) $fontSize)
+ "color" (or (index $filterArgs 5) $textFilterOpts.fontColor)
+ "font" $font
+ }}
+ {{- $f = images.Text (index $filterArgs 0) $opts }}
+{{- else if eq $filter "unsharpmask" }}
+ {{- $ctx = merge $ctx (dict "argsRequired" 3) }}
+ {{- template "validate-arg-count" $ctx }}
+ {{- $filterArgs = apply $filterArgs "float" "." }}
+ {{- $ctx = merge $ctx (dict "argName" "sigma" "argValue" (index $filterArgs 0) "min" 0 "max" 500) }}
+ {{- template "validate-arg-value" $ctx }}
+ {{- $ctx = merge $ctx (dict "argName" "amount" "argValue" (index $filterArgs 1) "min" 0 "max" 100) }}
+ {{- template "validate-arg-value" $ctx }}
+ {{- $ctx = merge $ctx (dict "argName" "threshold" "argValue" (index $filterArgs 2) "min" 0 "max" 1) }}
+ {{- template "validate-arg-value" $ctx }}
+ {{- $f = images.UnsharpMask (index $filterArgs 0) (index $filterArgs 1) (index $filterArgs 2) }}
+{{- end }}
+
+{{- /* Apply filter. */}}
+{{- $fi := $i }}
+{{- with $f }}
+ {{- $fi = $i.Filter . }}
+{{- end }}
+
+{{- /* Render. */}}
+{{- if $example }}
+ <p>Original</p>
+ <img class='di ba b--black-20' style="width: initial;" src="{{ $i.RelPermalink }}" alt="{{ $alt }}">
+ <p>Processed</p>
+ <img class='di ba b--black-20' style="width: initial;" src="{{ $fi.RelPermalink }}" alt="{{ $alt }}">
+{{- else -}}
+ <img class='di' style="width: initial;" src="{{ $fi.RelPermalink }}" alt="{{ $alt }}">
+{{- end }}
+
+{{- define "validate-arg-count" }}
+ {{- $msg := "When using the %q filter, the %q shortcode requires an args parameter with %d %s. See %s" }}
+ {{- if lt (len .args) .argsRequired }}
+ {{- $text := "values" }}
+ {{- if eq 1 .argsRequired }}
+ {{- $text = "value" }}
+ {{- end }}
+ {{- errorf $msg .filter .name .argsRequired $text .position }}
+ {{- end }}
+{{- end }}
+
+{{- define "validate-arg-value" }}
+ {{- $msg := "The %q argument passed to the %q shortcode is invalid. Expected a value in the range [%v,%v], but received %v. See %s" }}
+ {{- if or (lt .argValue .min) (gt .argValue .max) }}
+ {{- errorf $msg .argName .name .min .max .argValue .position }}
+ {{- end }}
+{{- end }}
+
+{{- define "partials/inline/get-resource.html" }}
+ {{- $r := "" }}
+ {{- $u := urls.Parse .src }}
+ {{- $msg := "The %q shortcode was unable to resolve %s. See %s" }}
+ {{- if $u.IsAbs }}
+ {{- with resources.GetRemote $u.String }}
+ {{- with .Err }}
++ {{- errorf "%s" . }}
+ {{- else }}
+ {{- /* This is a remote resource. */}}
+ {{- $r = . }}
+ {{- end }}
+ {{- else }}
+ {{- errorf $msg $.name $u.String $.position }}
+ {{- end }}
+ {{- else }}
+ {{- with .page.Resources.Get (strings.TrimPrefix "./" $u.Path) }}
+ {{- /* This is a page resource. */}}
+ {{- $r = . }}
+ {{- else }}
+ {{- with resources.Get $u.Path }}
+ {{- /* This is a global resource. */}}
+ {{- $r = . }}
+ {{- else }}
+ {{- errorf $msg $.name $u.Path $.position }}
+ {{- end }}
+ {{- end }}
+ {{- end }}
+ {{- return $r}}
+{{- end -}}
--- /dev/null
- <button class="bg-white hover:bg-gray-100 text-gray-800 font-semibold py-2 mr2 px-4 border border-gray-400 rounded shadow">
- <a href="{{ printf "https://github.com/gohugoio/hugo/releases/tag/v%s" $version }}">New in v{{ $version }}</a>
- </button>
+{{- /*
+Renders a "new in" button indicating the version in which a feature was added.
+
+When comparing the current version to the specified version, the "new in"
+button will be hidden if any of the following conditions is true:
+
+- The major version difference exceeds the majorVersionDiffThreshold
+- The minor version difference exceeds the minorVersionDiffThreshold
+
+@param {string} version The semantic version string, with or without a leading v.
+@returns {template.HTML}
+
+@example {{< new-in 0.100.0 >}}
+*/}}
+
+{{- /* Set defaults. */}}
+{{- $majorVersionDiffThreshold := 0 }}
+{{- $minorVersionDiffThreshold := 30 }}
+{{- $displayExpirationWarning := true }}
+
+{{- /* Render. */}}
+{{- with $version := .Get 0 | strings.TrimPrefix "v" }}
+ {{- $majorVersionDiff := sub (index (split hugo.Version ".") 0 | int) (index (split $version ".") 0 | int) }}
+ {{- $minorVersionDiff := sub (index (split hugo.Version ".") 1 | int) (index (split $version ".") 1 | int) }}
+ {{- if or (gt $majorVersionDiff $majorVersionDiffThreshold) (gt $minorVersionDiff $minorVersionDiffThreshold) }}
+ {{- if $displayExpirationWarning }}
+ {{- 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 }}
++ <a class="dib f5 fw6 ba bw1 b--gray ph2 mt1" href="{{ printf "https://github.com/gohugoio/hugo/releases/tag/v%s" $version }}">New in v{{ $version }}</a>
+ {{- end }}
+{{- else }}
+ {{- errorf "The %q shortcode requires a positional parameter (version). See %s" .Name .Position }}
+{{- end -}}
--- /dev/null
--- /dev/null
++<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 24 24"><path d="M12 0C5.374 0 0 5.373 0 12c0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23A11.5 11.5 0 0 1 12 5.803c1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576C20.566 21.797 24 17.3 24 12c0-6.627-5.373-12-12-12"/></svg>
--- /dev/null
- # github.com/gohugoio/gohugoioTheme v0.0.0-20240201183016-8e648a3b5342
++# github.com/gohugoio/gohugoioTheme v0.0.0-20240619093131-b595d5fb8c52
--- /dev/null
- name = 'About Hugo'
+[[docs]]
+identifier = 'about'
- weight = 40
++name = 'About'
+pageRef = '/about/'
+weight = 10
+
+[[docs]]
+name = 'Installation'
+weight = 20
+identifier = 'installation'
+pageRef = '/installation/'
+
+[[docs]]
+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 = 50
++weight = 50
+identifier = 'content-management'
+post = 'expanded'
+pageRef = '/content-management/'
+
+[[docs]]
+name = 'Templates'
- weight = 60
++weight = 60
+identifier = 'templates'
+pageRef = '/templates/'
+
+[[docs]]
+name = 'Functions'
- weight = 70
++weight = 70
+identifier = 'functions'
+pageRef = '/functions/'
+
+[[docs]]
+name = 'Methods'
- name = 'Quick reference'
- weight = 80
- identifier = 'quick-reference'
- pageRef = '/quick-reference/'
-
- [[docs]]
- name = 'Variables'
- weight = 85
- identifier = 'variables'
- pageRef = '/variables/'
++weight = 80
+identifier = 'methods'
+pageRef = '/methods/'
+
+[[docs]]
- weight = 90
++name = 'Render hooks'
++weight = 90
++identifier = 'render-hooks'
++pageRef = '/render-hooks/'
+
+[[docs]]
+name = 'Hugo Modules'
- weight = 100
++weight = 100
+identifier = 'modules'
+pageRef = '/hugo-modules/'
+
+[[docs]]
+name = 'Hugo Pipes'
- weight = 110
++weight = 110
+identifier = 'hugo-pipes'
+pageRef = '/hugo-pipes/'
+
+[[docs]]
+name = 'CLI'
- weight = 120
++weight = 120
+post = 'break'
+identifier = 'commands'
+pageRef = '/commands/'
+
+# Low level items
+
+[[docs]]
+name = 'Troubleshooting'
- weight = 130
++weight = 130
+identifier = 'troubleshooting'
+pageRef = '/troubleshooting/'
+
+[[docs]]
+name = 'Developer tools'
- weight = 140
++weight = 140
+identifier = 'developer-tools'
+pageRef = '/tools/'
+
+[[docs]]
+name = 'Hosting and deployment'
- weight = 150
++weight = 150
+identifier = 'hosting-and-deployment'
+pageRef = '/hosting-and-deployment/'
+
+[[docs]]
+name = 'Contribute'
++weight = 160
+post = 'break'
+identifier = 'contribute'
+pageRef = '/contribute/'
+
+######## QUICKLINKS
+
+[[quicklinks]]
+identifier = 'fundamentals'
+name = 'Fundamentals'
+pageRef = '/tags/fundamentals/'
+weight = 1
+
+######## GLOBAL ITEMS TO BE SHARED WITH THE HUGO SITES
+
+[[global]]
+name = 'News'
+weight = 1
+identifier = 'news'
+pageRef = '/news/'
+
+[[global]]
+name = 'Docs'
+weight = 5
+identifier = 'docs'
+url = '/documentation/'
+
+[[global]]
+name = 'Themes'
+weight = 10
+identifier = 'themes'
+url = 'https://themes.gohugo.io/'
+
+[[global]]
+name = 'Showcase'
+weight = 20
+identifier = 'showcase'
+pageRef = '/showcase/'
+
+# Anything with a weight > 100 gets an external icon
+
+[[global]]
+name = 'Community'
+weight = 150
+icon = true
+identifier = 'community'
+post = 'external'
+url = 'https://discourse.gohugo.io/'
+
+[[global]]
+name = 'GitHub'
+weight = 200
+identifier = 'github'
+post = 'external'
+url = 'https://github.com/gohugoio/hugo'
--- /dev/null
- 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.
+---
+title: The world’s fastest framework for building websites
+date: 2017-03-02T12:00:00-05:00
+features:
+ - heading: Blistering Speed
+ image_path: /images/icon-fast.svg
+ tagline: What's modern about waiting for your site to build?
+ copy: Hugo is the fastest tool of its kind. At <1 ms per page, the average site builds in less than a second.
+
+ - heading: Robust Content Management
+ image_path: /images/icon-content-management.svg
+ tagline: Flexibility rules. Hugo is a content strategist's dream.
+ copy: Hugo supports unlimited content types, taxonomies, menus, dynamic API-driven content, and more, all without plugins.
+
+ - 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.
+
+ - heading: Built-in Templates
+ image_path: /images/icon-built-in-templates.svg
+ tagline: Hugo has common patterns to get your work done quickly.
+ copy: Hugo ships with pre-made templates to make quick work of SEO, commenting, analytics and other functions. One line of code, and you're done.
+
+ - heading: Multilingual and i18n
+ image_path: /images/icon-multilingual2.svg
+ tagline: Polyglot baked in.
+ copy: Hugo provides full i18n support for multi-language sites with the same straightforward development experience Hugo users love in single-language sites.
+
+ - heading: Custom Outputs
+ image_path: /images/icon-custom-outputs.svg
+ tagline: HTML not enough?
+ copy: Hugo allows you to output your content in multiple formats, including JSON or AMP, and makes it easy to create your own.
+sections:
+ - heading: "300+ Themes"
+ cta: Check out the Hugo themes.
+ link: https://themes.gohugo.io/
+ color_classes: bg-accent-color white
+ image: /images/homepage-screenshot-hugo-themes.jpg
+ copy: "Hugo provides a robust theming system that is easy to implement but capable of producing even the most complicated websites."
+ - heading: "Capable Templating"
+ cta: Get Started.
+ link: templates/
+ color_classes: bg-primary-color-light black
+ image: /images/home-page-templating-example.png
+ copy: "Hugo's Go-based templating provides just the right amount of logic to build anything from the simple to complex."
+---
+
+Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again.
--- /dev/null
- linkTitle: Overview
- description: Hugo's features, roadmap, license, and motivation.
+---
+title: About Hugo
- identifier: about-hugo-overview
++linkTitle: In this section
++description: Learn about Hugo and its features, security model, and privacy protections.
+categories: []
+keywords: []
+menu:
+ docs:
- Hugo is not your average static site generator.
++ identifier: about-hugo-in-this-section
+ parent: about
+ weight: 10
+weight: 10
+aliases: [/about-hugo/,/docs/]
+---
+
++Learn about Hugo and its features, privacy protections, and security model.
--- /dev/null
- 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.
+---
- ## 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/
++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:
+ docs:
+ parent: about
+ weight: 30
+weight: 30
+toc: true
+---
+
- [sort content]: /templates/
- [supported formats]: /content-management/formats/
++## 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/
- [table of contents]: /content-management/toc/
- [taxonomies]: /content-management/taxonomies/
- [URLs]: /content-management/urls/
+[Syntax highlighting]: /content-management/syntax-highlighting/
++[Taxonomies]: /content-management/taxonomies/
++[Templates]: templates/introduction/
++[Themes]: https://themes.gohugo.io/
++[URL management]: /content-management/urls/
--- /dev/null
--- /dev/null
++---
++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 >}}
--- /dev/null
- keywords: [license,apache]
+---
+title: License
+description: Hugo is released under the Apache 2.0 license.
+categories: [about]
- weight: 70
- weight: 70
++keywords: [apache]
+menu:
+ docs:
+ parent: about
++ weight: 60
++weight: 60
+---
+
+## Apache License
+
+
+_Version 2.0, January 2004_
+_<http://www.apache.org/licenses/>_
+
+### Terms and Conditions for use, reproduction, and distribution
+
+#### 1. Definitions
+
+“License” shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+“Licensor” shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+“Legal Entity” shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, “control” means **(i)** the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or **(ii)** ownership of fifty percent (50%) or more of the outstanding shares, or **(iii)** beneficial ownership of such entity.
+
+“You” (or “Your”) shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+“Source” form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+“Object” form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+“Work” shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+“Derivative Works” shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+“Contribution” shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, “submitted” means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as “Not a Contribution.”
+
+“Contributor” shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+#### 2. Grant of Copyright License
+
+Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+#### 3. Grant of Patent License
+
+Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+#### 4. Redistribution
+
+You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+* **(a)** You must give any other recipients of the Work or Derivative Works a copy of this License; and
+* **(b)** You must cause any modified files to carry prominent notices stating that You changed the files; and
+* **(c)** You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+* **(d)** If the Work includes a “NOTICE” text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+#### 5. Submission of Contributions
+
+Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+#### 6. Trademarks
+
+This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+#### 7. Disclaimer of Warranty
+
+Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+#### 8. Limitation of Liability
+
+In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+#### 9. Accepting Warranty or Additional Liability
+
+While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
--- /dev/null
--- /dev/null
++---
++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: 40
++weight: 40
++toc: true
++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.
++
++ **Hugo is a static site generator. By using Hugo you are already standing on very solid ground. Static HTML files on disk are much easier to reason about compared to server and database driven web sites.**
++
++ But even static websites can integrate with external services, so from version `0.41`, Hugo provides a **privacy configuration** that covers the relevant built-in templates.
++
++ 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 [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
++
++Below are all privacy settings and their default value. These settings need to be put in your site configuration (e.g. `hugo.toml`).
++
++{{< code-toggle file=hugo >}}
++[privacy]
++[privacy.disqus]
++disable = false
++[privacy.googleAnalytics]
++disable = false
++respectDoNotTrack = false
++[privacy.instagram]
++disable = false
++simple = false
++[privacy.twitter]
++disable = false
++enableDNT = false
++simple = false
++[privacy.vimeo]
++disable = false
++enableDNT = false
++simple = false
++[privacy.youtube]
++disable = false
++privacyEnhanced = false
++{{< /code-toggle >}}
++
++## Disable all services
++
++An example privacy configuration that disables all the relevant services in Hugo. With this configuration, the other settings will not matter.
++
++{{< code-toggle file=hugo >}}
++[privacy]
++[privacy.disqus]
++disable = true
++[privacy.googleAnalytics]
++disable = true
++[privacy.instagram]
++disable = true
++[privacy.twitter]
++disable = true
++[privacy.vimeo]
++disable = true
++[privacy.youtube]
++disable = true
++{{< /code-toggle >}}
++
++## The privacy settings explained
++
++### GoogleAnalytics
++
++respectDoNotTrack
++: Enabling this will make the GA templates respect the "Do Not Track" HTTP header.
++
++### Instagram
++
++simple
++: If simple mode is enabled, a static and no-JS version of the Instagram image card will be built. Note that this only supports image cards and the image itself will be fetched from Instagram's servers.
++
++**Note:** If you use the _simple mode_ for Instagram and a site styled with Bootstrap 4, you may want to disable the inline styles provided by Hugo:
++
++{{< code-toggle file=hugo >}}
++[services]
++[services.instagram]
++disableInlineCSS = true
++{{< /code-toggle >}}
++
++### Twitter
++
++enableDNT
++: Enabling this for the twitter/tweet shortcode, the tweet and its embedded page on your site are not used for purposes that include personalized suggestions and personalized ads.
++
++simple
++: If simple mode is enabled, a static and no-JS version of a tweet will be built.
++
++**Note:** If you use the _simple mode_ for Twitter, you may want to disable the inline styles provided by Hugo:
++
++{{< code-toggle file=hugo >}}
++[services]
++[services.twitter]
++disableInlineCSS = true
++{{< /code-toggle >}}
++
++### YouTube
++
++privacyEnhanced
++: When you turn on privacy-enhanced mode, YouTube won’t store information about visitors on your website unless the user plays the embedded video.
++
++### Vimeo
++
++enableDNT
++: Enabling this for the vimeo shortcode, the Vimeo player will be blocked from tracking any session data, including all cookies and stats.
++
++simple
++: If simple mode is enabled, the video thumbnail is fetched from Vimeo's servers and it is overlaid with a play button. If the user clicks to play the video, it will open in a new tab directly on Vimeo's website.
--- /dev/null
--- /dev/null
++---
++title: Security model
++linkTitle: Security
++description: A summary of Hugo's security model.
++categories: [about]
++keywords: [security,privacy]
++menu:
++ docs:
++ parent: about
++ weight: 50
++weight: 50
++toc: true
++aliases: [/about/security-model/]
++---
++
++## Runtime security
++
++Hugo produces static output, so once built, the runtime is the browser (assuming the output is HTML) and any server (API) that you integrate with.
++
++But when developing and building your site, the runtime is the `hugo` executable. Securing a runtime can be [a real challenge](https://blog.logrocket.com/how-to-protect-your-node-js-applications-from-malicious-dependencies-5f2e60ea08f9/).
++
++**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.
++* User-defined components have read-only access to the filesystem.
++* 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
++
++Hugo has a built-in security policy that restricts access to [os/exec](https://pkg.go.dev/os/exec), remote communication and similar.
++
++The default configuration is listed below. Any build using features not in the allow list of the security policy will fail with a detailed message about what needs to be done. Most of these settings are allow lists (string or slice, [Regular Expressions](https://pkg.go.dev/regexp) or `none` which matches nothing).
++
++{{< code-toggle config=security />}}
++
++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
++```
++
++## Dependency security
++
++Hugo is built as a static binary using [Go Modules](https://github.com/golang/go/wiki/Modules) to manage its dependencies. Go Modules have several safeguards, one of them being the `go.sum` file. This is a database of the expected cryptographic checksums of all of your dependencies, including transitive dependencies.
++
++[Hugo Modules](/hugo-modules/) is a feature built on top of the functionality of Go Modules. Like Go Modules, a Hugo project using Hugo Modules will have a `go.sum` file. We recommend that you commit this file to your version control system. The Hugo build will fail if there is a checksum mismatch, which would be an indication of [dependency tampering](https://julienrenaux.fr/2019/12/20/github-actions-security-risk/).
++
++## Web application security
++
++These are the security threats as defined by [OWASP](https://en.wikipedia.org/wiki/OWASP).
++
++For HTML output, this is the core security model:
++
++<https://pkg.go.dev/html/template#hdr-Security_Model>
++
++In short:
++
++Template and configuration authors (you) are trusted, but the data you send in is not.
++This is why you sometimes need to use the _safe_ functions, such as `safeHTML`, to avoid escaping of data you know is safe.
++There is one exception to the above, as noted in the documentation: If you enable inline shortcodes, you also say that the shortcodes and data handling in content files are trusted, as those macros are treated as pure text.
++It may be worth adding that Hugo is a static site generator with no concept of dynamic user input.
++
++For content, the default Markdown renderer is [configured](/getting-started/configuration-markup) to remove or escape potentially unsafe content. This behavior can be reconfigured if you trust your content.
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo"
+slug: hugo
+url: /commands/hugo/
+---
+## hugo
+
+hugo builds your site
+
+### Synopsis
+
+hugo is the main command, used to build your Hugo site.
+
+Hugo is a Fast and Flexible Static Site Generator
+built with love by spf13 and friends in Go.
+
+Complete documentation is available at https://gohugo.io/.
+
+```
+hugo [flags]
+```
+
+### Options
+
+```
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ -D, --buildDrafts include content marked as draft
+ -E, --buildExpired include expired content
+ -F, --buildFuture include content with publishdate in the future
+ --cacheDir string filesystem path to cache directory
+ --cleanDestinationDir remove files from destination not found in static directories
+ --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")
+ -c, --contentDir string filesystem path to content directory
+ --debug debug output
+ -d, --destination string filesystem path to write files to
+ --disableKinds strings disable different kind of pages (home, RSS etc.)
+ --enableGitInfo add Git revision, date, author, and CODEOWNERS info to the pages
+ -e, --environment string build environment
+ --forceSyncStatic copy all files when static is changed.
+ --gc enable to run some cleanup tasks (remove unused cache files) after the build
+ -h, --help help for hugo
+ --ignoreCache ignores the cache directory
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ -l, --layoutDir string filesystem path to layout directory
+ --logLevel string log level (debug|info|warn|error)
+ --minify minify any supported output format (HTML, XML etc.)
+ --noBuildLock don't create .hugo_build.lock file
+ --noChmod don't sync permission mode of files
+ --noTimes don't sync modification time of files
+ --panicOnWarning panic on first WARNING log
+ --poll string set this to a poll interval, e.g --poll 700ms, to use a poll based approach to watch for file system changes
+ --printI18nWarnings print missing translations
+ --printMemoryUsage print memory usage to screen at intervals
+ --printPathWarnings print warnings on duplicate target paths etc.
+ --printUnusedTemplates print warnings on unused templates.
+ --quiet build in quiet mode
+ --renderSegments strings named segments to render (configured in the segments config)
++ -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
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+ --themesDir string filesystem path to themes directory
+ --trace file write trace to file (not useful in general)
+ -v, --verbose verbose output
+ -w, --watch watch filesystem for changes and recreate as needed
+```
+
+### SEE ALSO
+
+* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell
+* [hugo config](/commands/hugo_config/) - Print the site configuration
+* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats
+* [hugo deploy](/commands/hugo_deploy/) - Deploy your site to a Cloud provider.
+* [hugo env](/commands/hugo_env/) - Print Hugo version and environment info
+* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators.
+* [hugo import](/commands/hugo_import/) - Import your site from others.
+* [hugo list](/commands/hugo_list/) - Listing out various types of content
+* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
+* [hugo new](/commands/hugo_new/) - Create new content for your site
+* [hugo server](/commands/hugo_server/) - A high performance webserver
+* [hugo version](/commands/hugo_version/) - Print Hugo version and environment info
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo completion"
+slug: hugo_completion
+url: /commands/hugo_completion/
+---
+## hugo completion
+
+Generate the autocompletion script for the specified shell
+
+### Synopsis
+
+Generate the autocompletion script for hugo for the specified shell.
+See each sub-command's help for details on how to use the generated script.
+
+
+### Options
+
+```
+ -h, --help help for completion
+```
+
+### 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](/commands/hugo/) - hugo builds your site
+* [hugo completion bash](/commands/hugo_completion_bash/) - Generate the autocompletion script for bash
+* [hugo completion fish](/commands/hugo_completion_fish/) - Generate the autocompletion script for fish
+* [hugo completion powershell](/commands/hugo_completion_powershell/) - Generate the autocompletion script for powershell
+* [hugo completion zsh](/commands/hugo_completion_zsh/) - Generate the autocompletion script for zsh
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo completion bash"
+slug: hugo_completion_bash
+url: /commands/hugo_completion_bash/
+---
+## hugo completion bash
+
+Generate the autocompletion script for bash
+
+### Synopsis
+
+Generate the autocompletion script for the bash shell.
+
+This script depends on the 'bash-completion' package.
+If it is not installed already, you can install it via your OS's package manager.
+
+To load completions in your current shell session:
+
+ source <(hugo completion bash)
+
+To load completions for every new session, execute once:
+
+#### Linux:
+
+ hugo completion bash > /etc/bash_completion.d/hugo
+
+#### macOS:
+
+ hugo completion bash > $(brew --prefix)/etc/bash_completion.d/hugo
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+hugo completion bash
+```
+
+### Options
+
+```
+ -h, --help help for bash
+ --no-descriptions disable completion descriptions
+```
+
+### 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 completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo completion fish"
+slug: hugo_completion_fish
+url: /commands/hugo_completion_fish/
+---
+## hugo completion fish
+
+Generate the autocompletion script for fish
+
+### Synopsis
+
+Generate the autocompletion script for the fish shell.
+
+To load completions in your current shell session:
+
+ hugo completion fish | source
+
+To load completions for every new session, execute once:
+
+ hugo completion fish > ~/.config/fish/completions/hugo.fish
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+hugo completion fish [flags]
+```
+
+### Options
+
+```
+ -h, --help help for fish
+ --no-descriptions disable completion descriptions
+```
+
+### 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 completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo completion powershell"
+slug: hugo_completion_powershell
+url: /commands/hugo_completion_powershell/
+---
+## hugo completion powershell
+
+Generate the autocompletion script for powershell
+
+### Synopsis
+
+Generate the autocompletion script for powershell.
+
+To load completions in your current shell session:
+
+ hugo completion powershell | Out-String | Invoke-Expression
+
+To load completions for every new session, add the output of the above command
+to your powershell profile.
+
+
+```
+hugo completion powershell [flags]
+```
+
+### Options
+
+```
+ -h, --help help for powershell
+ --no-descriptions disable completion descriptions
+```
+
+### 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 completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo completion zsh"
+slug: hugo_completion_zsh
+url: /commands/hugo_completion_zsh/
+---
+## hugo completion zsh
+
+Generate the autocompletion script for zsh
+
+### Synopsis
+
+Generate the autocompletion script for the zsh shell.
+
+If shell completion is not already enabled in your environment you will need
+to enable it. You can execute the following once:
+
+ echo "autoload -U compinit; compinit" >> ~/.zshrc
+
+To load completions in your current shell session:
+
+ source <(hugo completion zsh)
+
+To load completions for every new session, execute once:
+
+#### Linux:
+
+ hugo completion zsh > "${fpath[1]}/_hugo"
+
+#### macOS:
+
+ hugo completion zsh > $(brew --prefix)/share/zsh/site-functions/_hugo
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+hugo completion zsh [flags]
+```
+
+### Options
+
+```
+ -h, --help help for zsh
+ --no-descriptions disable completion descriptions
+```
+
+### 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 completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo config"
+slug: hugo_config
+url: /commands/hugo_config/
+---
+## hugo config
+
+Print the site configuration
+
+### Synopsis
+
+Print the site configuration, both default and custom settings.
+
+```
+hugo config [command] [flags]
+```
+
+### Options
+
+```
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ -c, --contentDir string filesystem path to content directory
+ --format string preferred file format (toml, yaml or json) (default "toml")
+ -h, --help help for config
+ --lang string the language to display config for. Defaults to the first language defined.
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+```
+
+### 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](/commands/hugo/) - hugo builds your site
+* [hugo config mounts](/commands/hugo_config_mounts/) - Print the configured file mounts
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo config mounts"
+slug: hugo_config_mounts
+url: /commands/hugo_config_mounts/
+---
+## hugo config mounts
+
+Print the configured file mounts
+
+```
+hugo config mounts [flags] [args]
+```
+
+### Options
+
+```
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ -c, --contentDir string filesystem path to content directory
+ -h, --help help for mounts
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+```
+
+### 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 config](/commands/hugo_config/) - Print the site configuration
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo convert"
+slug: hugo_convert
+url: /commands/hugo_convert/
+---
+## hugo convert
+
+Convert your content to different formats
+
+### Synopsis
+
+Convert your content (e.g. front matter) to different formats.
+
+See convert's subcommands toJSON, toTOML and toYAML for more information.
+
+### Options
+
+```
+ -h, --help help for convert
+ -o, --output string filesystem path to write files to
+ --unsafe enable less safe operations, please backup first
+```
+
+### 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](/commands/hugo/) - hugo builds your site
+* [hugo convert toJSON](/commands/hugo_convert_tojson/) - Convert front matter to JSON
+* [hugo convert toTOML](/commands/hugo_convert_totoml/) - Convert front matter to TOML
+* [hugo convert toYAML](/commands/hugo_convert_toyaml/) - Convert front matter to YAML
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo convert toJSON"
+slug: hugo_convert_toJSON
+url: /commands/hugo_convert_tojson/
+---
+## hugo convert toJSON
+
+Convert front matter to JSON
+
+### Synopsis
+
+toJSON converts all front matter in the content directory
+to use JSON for the front matter.
+
+```
+hugo convert toJSON [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for toJSON
+```
+
+### 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)
+ -o, --output string filesystem path to write files to
+ --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
+ --unsafe enable less safe operations, please backup first
+ -v, --verbose verbose output
+```
+
+### SEE ALSO
+
+* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo convert toTOML"
+slug: hugo_convert_toTOML
+url: /commands/hugo_convert_totoml/
+---
+## hugo convert toTOML
+
+Convert front matter to TOML
+
+### Synopsis
+
+toTOML converts all front matter in the content directory
+to use TOML for the front matter.
+
+```
+hugo convert toTOML [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for toTOML
+```
+
+### 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)
+ -o, --output string filesystem path to write files to
+ --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
+ --unsafe enable less safe operations, please backup first
+ -v, --verbose verbose output
+```
+
+### SEE ALSO
+
+* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo convert toYAML"
+slug: hugo_convert_toYAML
+url: /commands/hugo_convert_toyaml/
+---
+## hugo convert toYAML
+
+Convert front matter to YAML
+
+### Synopsis
+
+toYAML converts all front matter in the content directory
+to use YAML for the front matter.
+
+```
+hugo convert toYAML [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for toYAML
+```
+
+### 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)
+ -o, --output string filesystem path to write files to
+ --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
+ --unsafe enable less safe operations, please backup first
+ -v, --verbose verbose output
+```
+
+### SEE ALSO
+
+* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo deploy"
+slug: hugo_deploy
+url: /commands/hugo_deploy/
+---
+## hugo deploy
+
+Deploy your site to a Cloud provider.
+
+### Synopsis
+
+Deploy your site to a Cloud provider.
+
+See https://gohugo.io/hosting-and-deployment/hugo-deploy/ for detailed
+documentation.
+
+
+```
+hugo deploy [flags] [args]
+```
+
+### Options
+
+```
+ --confirm ask for confirmation before making changes to the target
+ --dryRun dry run
+ --force force upload of all files
+ -h, --help help for deploy
+ --invalidateCDN invalidate the CDN cache listed in the deployment target (default true)
+ --maxDeletes int maximum # of files to delete, or -1 to disable (default 256)
+ --target string target deployment from deployments section in config file; defaults to the first one
+ --workers int number of workers to transfer files. defaults to 10 (default 10)
+```
+
+### 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](/commands/hugo/) - hugo builds your site
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo env"
+slug: hugo_env
+url: /commands/hugo_env/
+---
+## hugo env
+
+Print Hugo version and environment info
+
+### Synopsis
+
+Print Hugo version and environment info. This is useful in Hugo bug reports
+
+```
+hugo env [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for env
+```
+
+### 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](/commands/hugo/) - hugo builds your site
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo gen"
+slug: hugo_gen
+url: /commands/hugo_gen/
+---
+## hugo gen
+
+A collection of several useful generators.
+
+### Options
+
+```
+ -h, --help help for gen
+```
+
+### 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](/commands/hugo/) - hugo builds your site
+* [hugo gen chromastyles](/commands/hugo_gen_chromastyles/) - Generate CSS stylesheet for the Chroma code highlighter
+* [hugo gen doc](/commands/hugo_gen_doc/) - Generate Markdown documentation for the Hugo CLI.
+* [hugo gen man](/commands/hugo_gen_man/) - Generate man pages for the Hugo CLI
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo gen chromastyles"
+slug: hugo_gen_chromastyles
+url: /commands/hugo_gen_chromastyles/
+---
+## hugo gen chromastyles
+
+Generate CSS stylesheet for the Chroma code highlighter
+
+### Synopsis
+
+Generate CSS stylesheet for the Chroma code highlighter for a given style. This stylesheet is needed if markup.highlight.noClasses is disabled in config.
+
+See https://xyproto.github.io/splash/docs/all.html for a preview of the available styles
+
+```
+hugo gen chromastyles [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for chromastyles
+ --highlightStyle string foreground and background colors for highlighted lines, e.g. --highlightStyle "#fff000 bg:#000fff"
+ --lineNumbersInlineStyle string foreground and background colors for inline line numbers, e.g. --lineNumbersInlineStyle "#fff000 bg:#000fff"
+ --lineNumbersTableStyle string foreground and background colors for table line numbers, e.g. --lineNumbersTableStyle "#fff000 bg:#000fff"
+ --style string highlighter style (see https://xyproto.github.io/splash/docs/) (default "friendly")
+```
+
+### 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 gen](/commands/hugo_gen/) - A collection of several useful generators.
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo gen doc"
+slug: hugo_gen_doc
+url: /commands/hugo_gen_doc/
+---
+## hugo gen doc
+
+Generate Markdown documentation for the Hugo CLI.
+
+### Synopsis
+
+Generate Markdown documentation for the Hugo CLI.
+ This command is, mostly, used to create up-to-date documentation
+ of Hugo's command-line interface for https://gohugo.io/.
+
+ It creates one Markdown file per command with front matter suitable
+ for rendering in Hugo.
+
+```
+hugo gen doc [flags] [args]
+```
+
+### Options
+
+```
+ --dir string the directory to write the doc. (default "/tmp/hugodoc/")
+ -h, --help help for doc
+```
+
+### 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 gen](/commands/hugo_gen/) - A collection of several useful generators.
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo gen man"
+slug: hugo_gen_man
+url: /commands/hugo_gen_man/
+---
+## hugo gen man
+
+Generate man pages for the Hugo CLI
+
+### Synopsis
+
+This command automatically generates up-to-date man pages of Hugo's
+ command-line interface. By default, it creates the man page files
+ in the "man" directory under the current directory.
+
+```
+hugo gen man [flags] [args]
+```
+
+### Options
+
+```
+ --dir string the directory to write the man pages. (default "man/")
+ -h, --help help for man
+```
+
+### 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 gen](/commands/hugo_gen/) - A collection of several useful generators.
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo import"
+slug: hugo_import
+url: /commands/hugo_import/
+---
+## hugo import
+
+Import your site from others.
+
+### Synopsis
+
+Import your site from other web site generators like Jekyll.
+
+Import requires a subcommand, e.g. `hugo import jekyll jekyll_root_path target_path`.
+
+### Options
+
+```
+ -h, --help help for import
+```
+
+### 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](/commands/hugo/) - hugo builds your site
+* [hugo import jekyll](/commands/hugo_import_jekyll/) - hugo import from Jekyll
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo import jekyll"
+slug: hugo_import_jekyll
+url: /commands/hugo_import_jekyll/
+---
+## hugo import jekyll
+
+hugo import from Jekyll
+
+### Synopsis
+
+hugo import from Jekyll.
+
+Import from Jekyll requires two paths, e.g. `hugo import jekyll jekyll_root_path target_path`.
+
+```
+hugo import jekyll [flags] [args]
+```
+
+### Options
+
+```
+ --force allow import into non-empty target directory
+ -h, --help help for jekyll
+```
+
+### 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 import](/commands/hugo_import/) - Import your site from others.
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo list"
+slug: hugo_list
+url: /commands/hugo_list/
+---
+## hugo list
+
+Listing out various types of content
+
+### Synopsis
+
+Listing out various types of content.
+
+List requires a subcommand, e.g. hugo list drafts
+
+### Options
+
+```
+ -h, --help help for list
+```
+
+### 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
- * [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
++ -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](/commands/hugo/) - hugo builds your site
++* [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
+
--- /dev/null
- List all posts
+---
+title: "hugo list all"
+slug: hugo_list_all
+url: /commands/hugo_list_all/
+---
+## hugo list all
+
- List all of the posts in your content directory, include drafts, future and expired pages.
++List all content
+
+### Synopsis
+
- --renderToMemory render to memory (mostly useful when running the server)
++List all content including draft, future, and expired.
+
+```
+hugo list all [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for all
+```
+
+### 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
+
--- /dev/null
- List all drafts
+---
+title: "hugo list drafts"
+slug: hugo_list_drafts
+url: /commands/hugo_list_drafts/
+---
+## hugo list drafts
+
- List all of the drafts in your content directory.
++List draft content
+
+### Synopsis
+
- --renderToMemory render to memory (mostly useful when running the server)
++List draft content.
+
+```
+hugo list drafts [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for drafts
+```
+
+### 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
+
--- /dev/null
- List all posts already expired
+---
+title: "hugo list expired"
+slug: hugo_list_expired
+url: /commands/hugo_list_expired/
+---
+## hugo list expired
+
- List all of the posts in your content directory which has already expired.
++List expired content
+
+### Synopsis
+
- --renderToMemory render to memory (mostly useful when running the server)
++List content with a past expiration date.
+
+```
+hugo list expired [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for expired
+```
+
+### 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
+
--- /dev/null
- List all posts dated in the future
+---
+title: "hugo list future"
+slug: hugo_list_future
+url: /commands/hugo_list_future/
+---
+## hugo list future
+
- List all of the posts in your content directory which will be posted in the future.
++List future content
+
+### Synopsis
+
- --renderToMemory render to memory (mostly useful when running the server)
++List content with a future publication date.
+
+```
+hugo list future [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for future
+```
+
+### 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
+
--- /dev/null
--- /dev/null
++---
++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
++
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo mod"
+slug: hugo_mod
+url: /commands/hugo_mod/
+---
+## hugo mod
+
+Various Hugo Modules helpers.
+
+### Synopsis
+
+Various helpers to help manage the modules in your project's dependency graph.
+Most operations here requires a Go version installed on your system (>= Go 1.12) and the relevant VCS client (typically Git).
+This is not needed if you only operate on modules inside /themes or if you have vendored them via "hugo mod vendor".
+
+
+Note that Hugo will always start out by resolving the components defined in the site
+configuration, provided by a _vendor directory (if no --ignoreVendorPaths flag provided),
+Go Modules, or a folder inside the themes directory, in that order.
+
+See https://gohugo.io/hugo-modules/ for more information.
+
+
+
+### Options
+
+```
+ -h, --help help for mod
+```
+
+### 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](/commands/hugo/) - hugo builds your site
+* [hugo mod clean](/commands/hugo_mod_clean/) - Delete the Hugo Module cache for the current project.
+* [hugo mod get](/commands/hugo_mod_get/) - Resolves dependencies in your current Hugo Project.
+* [hugo mod graph](/commands/hugo_mod_graph/) - Print a module dependency graph.
+* [hugo mod init](/commands/hugo_mod_init/) - Initialize this project as a Hugo Module.
+* [hugo mod npm](/commands/hugo_mod_npm/) - Various npm helpers.
+* [hugo mod tidy](/commands/hugo_mod_tidy/) - Remove unused entries in go.mod and go.sum.
+* [hugo mod vendor](/commands/hugo_mod_vendor/) - Vendor all module dependencies into the _vendor directory.
+* [hugo mod verify](/commands/hugo_mod_verify/) - Verify dependencies.
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo mod clean"
+slug: hugo_mod_clean
+url: /commands/hugo_mod_clean/
+---
+## hugo mod clean
+
+Delete the Hugo Module cache for the current project.
+
+### Synopsis
+
+Delete the Hugo Module cache for the current project.
+
+```
+hugo mod clean [flags] [args]
+```
+
+### Options
+
+```
+ --all clean entire module cache
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ -c, --contentDir string filesystem path to content directory
+ -h, --help help for clean
+ --pattern string pattern matching module paths to clean (all if not set), e.g. "**hugo*"
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+```
+
+### 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 mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo mod get"
+slug: hugo_mod_get
+url: /commands/hugo_mod_get/
+---
+## hugo mod get
+
+Resolves dependencies in your current Hugo Project.
+
+### Synopsis
+
+
+Resolves dependencies in your current Hugo Project.
+
+Some examples:
+
+Install the latest version possible for a given module:
+
+ hugo mod get github.com/gohugoio/testshortcodes
+
+Install a specific version:
+
+ hugo mod get github.com/gohugoio/testshortcodes@v0.3.0
+
+Install the latest versions of all direct module dependencies:
+
+ hugo mod get
+ hugo mod get ./... (recursive)
+
+Install the latest versions of all module dependencies (direct and indirect):
+
+ hugo mod get -u
+ hugo mod get -u ./... (recursive)
+
+Run "go help get" for more information. All flags available for "go get" is also relevant here.
+
+Note that Hugo will always start out by resolving the components defined in the site
+configuration, provided by a _vendor directory (if no --ignoreVendorPaths flag provided),
+Go Modules, or a folder inside the themes directory, in that order.
+
+See https://gohugo.io/hugo-modules/ for more information.
+
+
+
+```
+hugo mod get [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for get
+```
+
+### 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 mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo mod graph"
+slug: hugo_mod_graph
+url: /commands/hugo_mod_graph/
+---
+## hugo mod graph
+
+Print a module dependency graph.
+
+### Synopsis
+
+Print a module dependency graph with information about module status (disabled, vendored).
+Note that for vendored modules, that is the version listed and not the one from go.mod.
+
+
+```
+hugo mod graph [flags] [args]
+```
+
+### Options
+
+```
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ --clean delete module cache for dependencies that fail verification
+ -c, --contentDir string filesystem path to content directory
+ -h, --help help for graph
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+```
+
+### 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 mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo mod init"
+slug: hugo_mod_init
+url: /commands/hugo_mod_init/
+---
+## hugo mod init
+
+Initialize this project as a Hugo Module.
+
+### Synopsis
+
+Initialize this project as a Hugo Module.
+ It will try to guess the module path, but you may help by passing it as an argument, e.g:
+
+ hugo mod init github.com/gohugoio/testshortcodes
+
+ Note that Hugo Modules supports multi-module projects, so you can initialize a Hugo Module
+ inside a subfolder on GitHub, as one example.
+
+
+```
+hugo mod init [flags] [args]
+```
+
+### Options
+
+```
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ -c, --contentDir string filesystem path to content directory
+ -h, --help help for init
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+```
+
+### 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 mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo mod npm"
+slug: hugo_mod_npm
+url: /commands/hugo_mod_npm/
+---
+## hugo mod npm
+
+Various npm helpers.
+
+### Synopsis
+
+Various npm (Node package manager) helpers.
+
+```
+hugo mod npm [command] [flags]
+```
+
+### Options
+
+```
+ -h, --help help for npm
+```
+
+### 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 mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
+* [hugo mod npm pack](/commands/hugo_mod_npm_pack/) - Experimental: Prepares and writes a composite package.json file for your project.
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo mod npm pack"
+slug: hugo_mod_npm_pack
+url: /commands/hugo_mod_npm_pack/
+---
+## hugo mod npm pack
+
+Experimental: Prepares and writes a composite package.json file for your project.
+
+### Synopsis
+
+Prepares and writes a composite package.json file for your project.
+
+On first run it creates a "package.hugo.json" in the project root if not already there. This file will be used as a template file
+with the base dependency set.
+
+This set will be merged with all "package.hugo.json" files found in the dependency tree, picking the version closest to the project.
+
+This command is marked as 'Experimental'. We think it's a great idea, so it's not likely to be
+removed from Hugo, but we need to test this out in "real life" to get a feel of it,
+so this may/will change in future versions of Hugo.
+
+
+```
+hugo mod npm pack [flags] [args]
+```
+
+### Options
+
+```
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ -c, --contentDir string filesystem path to content directory
+ -h, --help help for pack
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+```
+
+### 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 mod npm](/commands/hugo_mod_npm/) - Various npm helpers.
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo mod tidy"
+slug: hugo_mod_tidy
+url: /commands/hugo_mod_tidy/
+---
+## hugo mod tidy
+
+Remove unused entries in go.mod and go.sum.
+
+```
+hugo mod tidy [flags] [args]
+```
+
+### Options
+
+```
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ -c, --contentDir string filesystem path to content directory
+ -h, --help help for tidy
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+```
+
+### 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 mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo mod vendor"
+slug: hugo_mod_vendor
+url: /commands/hugo_mod_vendor/
+---
+## hugo mod vendor
+
+Vendor all module dependencies into the _vendor directory.
+
+### Synopsis
+
+Vendor all module dependencies into the _vendor directory.
+ If a module is vendored, that is where Hugo will look for it's dependencies.
+
+
+```
+hugo mod vendor [flags] [args]
+```
+
+### Options
+
+```
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ -c, --contentDir string filesystem path to content directory
+ -h, --help help for vendor
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+```
+
+### 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 mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo mod verify"
+slug: hugo_mod_verify
+url: /commands/hugo_mod_verify/
+---
+## hugo mod verify
+
+Verify dependencies.
+
+### Synopsis
+
+Verify checks that the dependencies of the current module, which are stored in a local downloaded source cache, have not been modified since being downloaded.
+
+```
+hugo mod verify [flags] [args]
+```
+
+### Options
+
+```
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ --clean delete module cache for dependencies that fail verification
+ -c, --contentDir string filesystem path to content directory
+ -h, --help help for verify
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+```
+
+### 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 mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo new"
+slug: hugo_new
+url: /commands/hugo_new/
+---
+## hugo new
+
+Create new content for your site
+
+### Synopsis
+
+Create a new content file and automatically set the date and title.
+It will guess which kind of file to create based on the path provided.
+
+You can also specify the kind with `-k KIND`.
+
+If archetypes are provided in your theme or site, they will be used.
+
+Ensure you run this within the root directory of your site.
+
+### Options
+
+```
+ -h, --help help for new
+```
+
+### 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](/commands/hugo/) - hugo builds your site
+* [hugo new content](/commands/hugo_new_content/) - Create new content for your site
+* [hugo new site](/commands/hugo_new_site/) - Create a new site (skeleton)
+* [hugo new theme](/commands/hugo_new_theme/) - Create a new theme (skeleton)
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo new content"
+slug: hugo_new_content
+url: /commands/hugo_new_content/
+---
+## hugo new content
+
+Create new content for your site
+
+### Synopsis
+
+Create a new content file and automatically set the date and title.
+It will guess which kind of file to create based on the path provided.
+
+You can also specify the kind with `-k KIND`.
+
+If archetypes are provided in your theme or site, they will be used.
+
+Ensure you run this within the root directory of your site.
+
+```
+hugo new content [path] [flags]
+```
+
+### Options
+
+```
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ -c, --contentDir string filesystem path to content directory
+ --editor string edit new content with this editor, if provided
+ -f, --force overwrite file if it already exists
+ -h, --help help for content
+ -k, --kind string content type to create
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+```
+
+### 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 new](/commands/hugo_new/) - Create new content for your site
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo new site"
+slug: hugo_new_site
+url: /commands/hugo_new_site/
+---
+## hugo new site
+
+Create a new site (skeleton)
+
+### Synopsis
+
+Create a new site in the provided directory.
+The new site will have the correct structure, but no content or theme yet.
+Use `hugo new [contentPath]` to create new content.
+
+```
+hugo new site [path] [flags]
+```
+
+### Options
+
+```
+ -f, --force init inside non-empty directory
+ --format string preferred file format (toml, yaml or json) (default "toml")
+ -h, --help help for site
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ --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 new](/commands/hugo_new/) - Create new content for your site
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo new theme"
+slug: hugo_new_theme
+url: /commands/hugo_new_theme/
+---
+## hugo new theme
+
+Create a new theme (skeleton)
+
+### Synopsis
+
+Create a new theme (skeleton) called [name] in ./themes.
+New theme is a skeleton. Please add content to the touched files. Add your
+name to the copyright line in the license and adjust the theme.toml file
+according to your needs.
+
+```
+hugo new theme [name] [flags]
+```
+
+### Options
+
+```
+ -h, --help help for theme
+```
+
+### 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 new](/commands/hugo_new/) - Create new content for your site
+
--- /dev/null
- --navigateToChanged navigate to changed content file on live browser reload
+---
+title: "hugo server"
+slug: hugo_server
+url: /commands/hugo_server/
+---
+## hugo server
+
+A high performance webserver
+
+### Synopsis
+
+Hugo provides its own webserver which builds and serves the site.
+While hugo server is high performance, it is a webserver with limited options.
+
+The `hugo server` command will by default write and serve files from disk, but
+you can render to memory by using the `--renderToMemory` flag. This can be
+faster in some cases, but it will consume more memory.
+
+By default hugo will also watch your files for any changes you make and
+automatically rebuild the site. It will then live reload any open browser pages
+and push the latest content to them. As most Hugo sites are built in a fraction
+of a second, you will be able to save and see your changes nearly instantly.
+
+```
+hugo server [command] [flags]
+```
+
+### Options
+
+```
+ --appendPort append port to baseURL (default true)
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --bind string interface to which the server will bind (default "127.0.0.1")
+ -D, --buildDrafts include content marked as draft
+ -E, --buildExpired include expired content
+ -F, --buildFuture include content with publishdate in the future
+ --cacheDir string filesystem path to cache directory
+ --cleanDestinationDir remove files from destination not found in static directories
+ -c, --contentDir string filesystem path to content directory
+ --disableBrowserError do not show build errors in the browser
+ --disableFastRender enables full re-renders on changes
+ --disableKinds strings disable different kind of pages (home, RSS etc.)
+ --disableLiveReload watch without enabling live browser reload on rebuild
+ --enableGitInfo add Git revision, date, author, and CODEOWNERS info to the pages
+ --forceSyncStatic copy all files when static is changed.
+ --gc enable to run some cleanup tasks (remove unused cache files) after the build
+ -h, --help help for server
+ --ignoreCache ignores the cache directory
+ -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.)
- --renderToMemory render to memory (mostly useful when running the server)
++ -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
+ --noTimes don't sync modification time of files
+ --panicOnWarning panic on first WARNING log
+ --poll string set this to a poll interval, e.g --poll 700ms, to use a poll based approach to watch for file system changes
+ -p, --port int port on which the server will listen (default 1313)
+ --pprof enable the pprof server (port 8080)
+ --printI18nWarnings print missing translations
+ --printMemoryUsage print memory usage to screen at intervals
+ --printPathWarnings print warnings on duplicate target paths etc.
+ --printUnusedTemplates print warnings on unused templates.
+ --renderSegments strings named segments to render (configured in the segments config)
+ --renderStaticToDisk serve static files from disk and dynamic files from memory
+ --templateMetrics display metrics about template executions
+ --templateMetricsHints calculate some improvement hints when combined with --templateMetrics
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+ --tlsAuto generate and use locally-trusted certificates.
+ --tlsCertFile string path to TLS certificate file
+ --tlsKeyFile string path to TLS key file
+ --trace file write trace to file (not useful in general)
+ -w, --watch watch filesystem for changes and recreate as needed (default true)
+```
+
+### 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](/commands/hugo/) - hugo builds your site
+* [hugo server trust](/commands/hugo_server_trust/) - Install the local CA in the system trust store.
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo server trust"
+slug: hugo_server_trust
+url: /commands/hugo_server_trust/
+---
+## hugo server trust
+
+Install the local CA in the system trust store.
+
+```
+hugo server trust [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for trust
+ --uninstall Uninstall the local CA (but do not delete it).
+```
+
+### 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 server](/commands/hugo_server/) - A high performance webserver
+
--- /dev/null
- --renderToMemory render to memory (mostly useful when running the server)
+---
+title: "hugo version"
+slug: hugo_version
+url: /commands/hugo_version/
+---
+## hugo version
+
+Print Hugo version and environment info
+
+### Synopsis
+
+Print Hugo version and environment info. This is useful in Hugo bug reports.
+
+```
+hugo version [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for version
+```
+
+### 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](/commands/hugo/) - hugo builds your site
+
--- /dev/null
- Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+---
+cascade:
+ _build:
+ list: never
+ publishResources: false
+ render: never
+---
+
+<!--
++Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+
+Include the rendered content using the "include" shortcode.
+-->
--- /dev/null
- linkTitle: Overview
+---
+title: Content management
- identifier: content-management-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-in-this-section
+ parent: content-management
+ weight: 10
+weight: 10
+aliases: [/content/,/content/organization]
+---
+
+A static site generator needs to extend beyond front matter and a couple of templates to be both scalable and *manageable*. Hugo was designed with not only developers in mind, but also content managers and authors.
--- /dev/null
- 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.
+---
+title: Archetypes
+description: An archetype is a template for new content.
+categories: [content management]
+keywords: [archetypes,generators,metadata,front matter]
+menu:
+ docs:
+ parent: content-management
+ weight: 140
+ quicklinks:
+weight: 140
+toc: true
+aliases: [/content/archetypes/]
+---
+
+## Overview
+
- Archetypes receive the following objects and values in [context]:
++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:
+
+{{< code-toggle file=archetypes/default.md fm=true >}}
+title = '{{ replace .File.ContentBaseName `-` ` ` | title }}'
+date = '{{ .Date }}'
+draft = true
+{{< /code-toggle >}}
+
+When you create new content, Hugo evaluates the [template actions] within the archetype. For example:
+
+```sh
+hugo new content posts/my-first-post.md
+```
+
+With the default archetype shown above, Hugo creates this content file:
+
+{{< code-toggle file=content/posts/my-first-post.md fm=true >}}
+title = 'My First Post'
+date = '2023-08-24T11:49:46-07:00'
+draft = true
+{{< /code-toggle >}}
+
+You can create an archetype for one or more [content types]. For example, use one archetype for posts, and use the default archetype for everything else:
+
+```text
+archetypes/
+├── default.md
+└── posts.md
+```
+
+## Lookup order
+
+Hugo looks for archetypes in the `archetypes` directory in the root of your project, falling back to the `archetypes` directory in themes or installed modules. An archetype for a specific content type takes precedence over the default archetype.
+
+For example, with this command:
+
+```sh
+hugo new content posts/my-first-post.md
+```
+
+The archetype lookup order is:
+
+1. archetypes/posts.md
+1. archetypes/default.md
+1. themes/my-theme/archetypes/posts.md
+1. themes/my-theme/archetypes/default.md
+
+If none of these exists, Hugo uses a built-in default archetype.
+
+## Functions and context
+
+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.
+
- - `.Date`
- - `.Type`
- - `.Site` (see [details](/variables/site/))
- - `.File` (see [details](/variables/file/))
++Archetypes receive the following [context]:
+
- As shown above, the default archetype passes `.File.ContentBaseName` as the argument to the `replace` function when populating the title in front matter.
++Date
++: (`string`) The current date and time, formatted in compliance with RFC3339.
+
++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
+
+Although typically used as a front matter template, you can also use an archetype to populate content.
+
+For example, in a documentation site you might have a section (content type) for functions. Every page within this section should follow the same format: a brief description, the function signature, examples, and notes. We can pre-populate the page to remind content authors of the standard format.
+
+{{< code file=archetypes/functions.md >}}
+---
+date: '{{ .Date }}'
+draft: true
+title: '{{ replace .File.ContentBaseName `-` ` ` | title }}'
+---
+
+A brief description of what the function does, using simple present tense in the third person singular form. For example:
+
+`someFunction` returns the string `s` repeated `n` times.
+
+## Signature
+
+```text
+func someFunction(s string, n int) string
+```
+
+## Examples
+
+One or more practical examples, each within a fenced code block.
+
+## Notes
+
+Additional information to clarify as needed.
+{{< /code >}}
+
+Although you can include [template actions] within the content body, remember that Hugo evaluates these once---at the time of content creation. In most cases, place template actions in a [template] where Hugo evaluates the actions every time you [build](/getting-started/glossary/#build) the site.
+
+## Leaf bundles
+
+You can also create archetypes for [leaf bundles](/getting-started/glossary/#leaf-bundle).
+
+For example, in a photography site you might have a section (content type) for galleries. Each gallery is leaf bundle with content and images.
+
+Create an archetype for galleries:
+
+```text
+archetypes/
+├── galleries/
+│ ├── images/
+│ │ └── .gitkeep
+│ └── index.md <-- same format as default.md
+└── default.md
+```
+
+Subdirectories within an archetype must contain at least one file. Without a file, Hugo will not create the subdirectory when you create new content. The name and size of the file are irrelevant. The example above includes a `.gitkeep` file, an empty file commonly used to preserve otherwise empty directories in a Git repository.
+
+To create a new gallery:
+
+```sh
+hugo new galleries/bryce-canyon
+```
+
+This produces:
+
+```text
+content/
+├── galleries/
+│ └── bryce-canyon/
+│ ├── images/
+│ │ └── .gitkeep
+│ └── index.md
+└── _index.md
+```
+
+## Use alternate archetype
+
+Use the `--kind` command line flag to specify an alternate archetype when creating content.
+
+For example, let's say your site has two sections: articles and tutorials. Create an archetype for each content type:
+
+```text
+archetypes/
+├── articles.md
+├── default.md
+└── tutorials.md
+```
+
+To create an article using the articles archetype:
+
+```sh
+hugo new content articles/something.md
+```
+
+To create an article using the tutorials archetype:
+
+```sh
+hugo new content --kind tutorials articles/something.md
+```
+
+[content formats]: /getting-started/glossary/#content-format
+[content types]: /getting-started/glossary/#content-type
+[context]: /getting-started/glossary/#context
+[front matter]: /getting-started/glossary/#front-matter
+[template actions]: /getting-started/glossary/#template-action
+[template]: /getting-started/glossary/#template
+[template function]: /getting-started/glossary/#function
--- /dev/null
- Build options are stored in a reserved front matter object named `_build` with these defaults:
+---
+title: Build options
+description: Build options help define how Hugo must treat a given page when building the site.
+categories: [content management,fundamentals]
+keywords: [build,content,front matter, page resources]
+menu:
+ docs:
+ parent: content-management
+ weight: 70
+weight: 70
+toc: true
+aliases: [/content/build-options/]
+---
+
- [_build]
++Build options are stored in a reserved front matter object named `build` with these defaults:
+
+{{< code-toggle file=content/example/index.md fm=true >}}
- [page bundles]: content-management/page-bundles
- [page resources]: /content-management/page-resources
- [`Permalink`]: /methods/resource/permalink
- [`RelPermalink`]: /methods/resource/relpermalink
- [`Publish`]: /methods/resource/publish
++[build]
+list = 'always'
+publishResources = true
+render = 'always'
+{{< /code-toggle >}}
+
+
+list
+: When to include the page within page collections. Specify one of:
+
+ - `always`
+ : Include the page in _all_ page collections. For example, `site.RegularPages`, `.Pages`, etc. This is the default value.
+
+ - `local`
+ : Include the page in _local_ page collections. For example, `.RegularPages`, `.Pages`, etc. Use this option to create fully navigable but headless content sections.
+
+ - `never`
+ : Do not include the page in _any_ page collection.
+
+publishResources
+: Applicable to [page bundles], determines whether to publish the associated [page resources]. Specify one of:
+
+ - `true`
+ : Always publish resources. This is the default value.
+
+ - `false`
+ : Only publish a resource when invoking its [`Permalink`], [`RelPermalink`], or [`Publish`] method within a template.
+
+render
+: When to render the page. Specify one of:
+
+ - `always`
+ : Always render the page to disk. This is the default value.
+
+ - `link`
+ : Do not render the page to disk, but assign `Permalink` and `RelPermalink` values.
+
+ - `never`
+ : Never render the page to disk, and exclude it from all page collections.
+
- [`.Page.GetPage`]: /methods/page/getpage
- [`.Site.GetPage`]: /methods/site/getpage
++[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.
+
- [_build]
++[`.Page.GetPage`]: /methods/page/getpage/
++[`.Site.GetPage`]: /methods/site/getpage/
+{{% /note %}}
+
+## Example -- headless page
+
+Create a unpublished page whose content and resources can be included in other pages.
+
+```text
+content/
+├── headless/
+│ ├── a.jpg
+│ ├── b.jpg
+│ └── index.md <-- leaf bundle
+└── _index.md <-- home page
+```
+
+Set the build options in front matter:
+
+{{< code-toggle file=content/headless/index.md fm=true >}}
+title = 'Headless page'
- [branch bundle]: /content-management/page-bundles
++[build]
+ list = 'never'
+ publishResources = false
+ render = 'never'
+{{< /code-toggle >}}
+
+To include the content and images on the home page:
+
+{{< code file=layouts/_default/home.html >}}
+{{ with .Site.GetPage "/headless" }}
+ {{ .Content }}
+ {{ range .Resources.ByType "image" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+{{< /code >}}
+
+The published site will have this structure:
+
+```text
+public/
+├── headless/
+│ ├── a.jpg
+│ └── b.jpg
+└── index.html
+```
+
+In the example above, note that:
+
+1. Hugo did not publish an HTML file for the page.
+2. Despite setting `publishResources` to `false` in front matter, Hugo published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior.
+
+## Example -- headless section
+
+Create a unpublished section whose content and resources can be included in other pages.
+
- [cascade._build]
++[branch bundle]: /content-management/page-bundles/
+
+```text
+content/
+├── headless/
+│ ├── note-1/
+│ │ ├── a.jpg
+│ │ ├── b.jpg
+│ │ └── index.md <-- leaf bundle
+│ ├── note-2/
+│ │ ├── c.jpg
+│ │ ├── d.jpg
+│ │ └── index.md <-- leaf bundle
+│ └── _index.md <-- branch bundle
+└── _index.md <-- home page
+```
+
+Set the build options in front matter, using the `cascade` keyword to "cascade" the values down to descendant pages.
+
+{{< code-toggle file=content/headless/_index.md fm=true >}}
+title = 'Headless section'
+[[cascade]]
- [_build]
++[cascade.build]
+ list = 'local'
+ publishResources = false
+ render = 'never'
+{{< /code-toggle >}}
+
+In the front matter above, note that we have set `list` to `local` to include the descendant pages in local page collections.
+
+To include the content and images on the home page:
+
+{{< code file=layouts/_default/home.html >}}
+{{ with .Site.GetPage "/headless" }}
+ {{ range .Pages }}
+ {{ .Content }}
+ {{ range .Resources.ByType "image" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+ {{ end }}
+{{ end }}
+{{< /code >}}
+
+The published site will have this structure:
+
+```text
+public/
+├── headless/
+│ ├── note-1/
+│ │ ├── a.jpg
+│ │ └── b.jpg
+│ └── note-2/
+│ ├── c.jpg
+│ └── d.jpg
+└── index.html
+```
+
+In the example above, note that:
+
+1. Hugo did not publish an HTML file for the page.
+2. Despite setting `publishResources` to `false` in front matter, Hugo correctly published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior.
+
+## Example -- list without publishing
+
+Publish a section page without publishing the descendant pages. For example, to create a glossary:
+
+```text
+content/
+├── glossary/
+│ ├── _index.md
+│ ├── bar.md
+│ ├── baz.md
+│ └── foo.md
+└── _index.md
+```
+
+Set the build options in front matter, using the `cascade` keyword to "cascade" the values down to descendant pages.
+
+{{< code-toggle file=content/glossary/_index.md fm=true >}}
+title = 'Glossary'
- [cascade._build]
++[build]
+render = 'always'
+[[cascade]]
- [_build]
++[cascade.build]
+ list = 'local'
+ publishResources = false
+ render = 'never'
+{{< /code-toggle >}}
+
+To render the glossary:
+
+{{< code file=layouts/glossary/list.html >}}
+<dl>
+ {{ range .Pages }}
+ <dt>{{ .Title }}</dt>
+ <dd>{{ .Content }}</dd>
+ {{ end }}
+</dl>
+{{< /code >}}
+
+The published site will have this structure:
+
+```text
+public/
+├── glossary/
+│ └── index.html
+└── index.html
+```
+
+## Example -- publish without listing
+
+Publish a section's descendant pages without publishing the section page itself.
+
+```text
+content/
+├── books/
+│ ├── _index.md
+│ ├── book-1.md
+│ └── book-2.md
+└── _index.md
+```
+
+Set the build options in front matter:
+
+{{< code-toggle file=content/books/_index.md fm=true >}}
+title = 'Books'
- [cascade._build]
++[build]
+render = 'never'
+list = 'never'
+{{< /code-toggle >}}
+
+The published site will have this structure:
+
+```html
+public/
+├── books/
+│ ├── book-1/
+│ │ └── index.html
+│ └── book-2/
+│ └── index.html
+└── index.html
+```
+
+## Example -- conditionally hide section
+
+Consider this example. A documentation site has a team of contributors with access to 20 custom shortcodes. Each shortcode takes several arguments, and requires documentation for the contributors to reference when using them.
+
+Instead of external documentation for the shortcodes, include an "internal" section that is hidden when building the production site.
+
+```text
+content/
+├── internal/
+│ ├── shortcodes/
+│ │ ├── _index.md
+│ │ ├── shortcode-1.md
+│ │ └── shortcode-2.md
+│ └── _index.md
+├── reference/
+│ ├── _index.md
+│ ├── reference-1.md
+│ └── reference-2.md
+├── tutorials/
+│ ├── _index.md
+│ ├── tutorial-1.md
+│ └── tutorial-2.md
+└── _index.md
+```
+
+Set the build options in front matter, using the `cascade` keyword to "cascade" the values down to descendant pages, and use the `target` keyword to target the production environment.
+
+{{< code-toggle file=content/internal/_index.md >}}
+title = 'Internal'
+[[cascade]]
++[cascade.build]
+render = 'never'
+list = 'never'
+[cascade._target]
+environment = 'production'
+{{< /code-toggle >}}
+
+The production site will have this structure:
+
+```html
+public/
+├── reference/
+│ ├── reference-1/
+│ │ └── index.html
+│ ├── reference-2/
+│ │ └── index.html
+│ └── index.html
+├── tutorials/
+│ ├── tutorial-1/
+│ │ └── index.html
+│ ├── tutorial-2/
+│ │ └── index.html
+│ └── index.html
+└── index.html
+```
--- /dev/null
- Disqus has its own [internal template](/templates/internal/#disqus) available, to render it add the following code where you want comments to appear:
+---
+title: Comments
+description: Hugo ships with an internal Disqus template, but this isn't the only commenting system that will work with your new Hugo website.
+categories: [content management]
+keywords: [sections,content,organization]
+menu:
+ docs:
+ parent: content-management
+ weight: 220
+weight: 220
+toc: true
+aliases: [/extras/comments/]
+---
+
+Hugo ships with support for [Disqus](https://disqus.com/), a third-party service that provides comment and community capabilities to websites via JavaScript.
+
+Your theme may already support Disqus, but if not, it is easy to add to your templates via [Hugo's built-in Disqus partial][disquspartial].
+
+## Add Disqus
+
+Hugo comes with all the code you need to load Disqus into your templates. Before adding Disqus to your site, you'll need to [set up an account][disqussetup].
+
+### Configure Disqus
+
+Disqus comments require you set a single value in your [site's configuration file][configuration] like so:
+
+{{< code-toggle file=hugo >}}
+[services.disqus]
+shortname = 'your-disqus-shortname'
+{{</ code-toggle >}}
+
+For many websites, this is enough configuration. However, you also have the option to set the following in the [front matter] of a single content file:
+
+* `disqus_identifier`
+* `disqus_title`
+* `disqus_url`
+
+### Render Hugo's built-in Disqus partial template
+
- 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)
++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" . }}
+```
+
+## Alternatives
+
- [disquspartial]: /templates/internal/#disqus
++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/
- [tweet]: https://twitter.com/spf13
++[disquspartial]: /templates/embedded/#disqus
+[disqussetup]: https://disqus.com/profile/signup/
+[forum]: https://discourse.gohugo.io
+[front matter]: /content-management/front-matter/
+[kaijuissue]: https://github.com/spf13/kaiju/issues/new
+[issotutorial]: https://stiobhart.net/2017-02-24-isso-comments/
+[partials]: /templates/partials/
+[MongoDB]: https://www.mongodb.com/
--- /dev/null
--- /dev/null
++---
++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" }}
++ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
++{{ 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.
++
++: <https://gohugo.io/shared/examples/data/books.json>
++
++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" }}
++ <h1>{{ .Title }}</h1>
++
++ {{ with .Resources.GetMatch "cover.*" }}
++ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="{{ .Params.alt }}">
++ {{ end }}
++
++ <p>Author: {{ .Params.author }}</p>
++
++ <p>
++ ISBN: {{ .Params.isbn }}<br>
++ Rating: {{ .Params.rating }}<br>
++ Review date: {{ .Date | time.Format ":date_long" }}
++ </p>
++
++ {{ with .GetTerms "tags" }}
++ <p>Tags:</p>
++ <ul>
++ {{ range . }}
++ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
++ {{ end }}
++ </ul>
++ {{ 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/
--- /dev/null
- 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.
+---
+title: Links and cross references
+description: Shortcodes for creating links to documents.
+categories: [content management]
+keywords: [cross references,references,anchors,urls]
+menu:
+ docs:
+ parent: content-management
+ weight: 170
+weight: 170
+toc: true
+aliases: [/extras/crossreferences/]
+---
+
+The `ref` and `relref` shortcodes display the absolute and relative permalinks to a document, respectively.
+
+## Use of `ref` and `relref`
+
- To generate a hyperlink using `ref` or `relref` in markdown:
++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
+.
+└── content
+ ├── about
+ | ├── _index.md
+ | └── credits.md
+ ├── pages
+ | ├── document1.md
+ | └── document2.md // has anchor #anchor
+ ├── products
+ | └── index.md
+ └── blog
+ └── my-post.md
+```
+
+The pages can be referenced as follows:
+
+```text
+{{</* ref "document2" */>}} // <- From pages/document1.md, relative path
+{{</* ref "document2#anchor" */>}}
+{{</* ref "document2.md" */>}}
+{{</* ref "document2.md#anchor" */>}}
+{{</* ref "#anchor" */>}} // <- From pages/document2.md
+{{</* ref "/blog/my-post" */>}} // <- From anywhere, absolute path
+{{</* ref "/blog/my-post.md" */>}}
+{{</* relref "document" */>}}
+{{</* relref "document.md" */>}}
+{{</* relref "#anchor" */>}}
+{{</* relref "/blog/my-post.md" */>}}
+```
+
+index.md can be reference either by its path or by its containing folder without the ending `/`. \_index.md can be referenced only by its containing folder:
+
+```text
+{{</* ref "/about" */>}} // <- References /about/_index.md
+{{</* ref "/about/_index" */>}} // Raises REF_NOT_FOUND error
+{{</* ref "/about/credits.md" */>}} // <- References /about/credits.md
+
+{{</* ref "/products" */>}} // <- References /products/index.md
+{{</* ref "/products/index" */>}} // <- References /products/index.md
+```
+
- ```go-html-template
++To generate a hyperlink using `ref` or `relref` in Markdown:
+
+```text
+[About]({{</* ref "/about" */>}} "About Us")
+```
+
+Hugo emits an error or warning if a document cannot be uniquely resolved. The error behavior is configurable; see below.
+
+### 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
+{{</* relref path="document.md" lang="ja" */>}}
+```
+
+### Get another output format
+
+To link to another Output Format of a document, use this syntax:
+
- ```md
++```text
+{{</* relref path="document.md" outputFormat="rss" */>}}
+```
+
+### Heading IDs
+
+When using Markdown document types, Hugo generates element IDs for every heading on a page. For example:
+
- ```go-html-template
++```text
+## Reference
+```
+
+produces this HTML:
+
+```html
+<h2 id="reference">Reference</h2>
+```
+
+Get the permalink to a heading by appending the ID to the path when using the `ref` or `relref` shortcodes:
+
- ```md
++```text
+{{</* ref "document.md#reference" */>}}
+{{</* relref "document.md#reference" */>}}
+```
+
+Generate a custom heading ID by including an attribute. For example:
+
- ```md
++```text
+## Reference A {#foo}
+## Reference B {id="bar"}
+```
+
+produces this HTML:
+
+```html
+<h2 id="foo">Reference A</h2>
+<h2 id="bar">Reference B</h2>
+```
+
+Hugo will generate unique element IDs if the same heading appears more than once on a page. For example:
+
++```text
+## Reference
+## Reference
+## Reference
+```
+
+produces this HTML:
+
+```html
+<h2 id="reference">Reference</h2>
+<h2 id="reference-1">Reference</h2>
+<h2 id="reference-2">Reference</h2>
+```
+
+## Ref and RelRef Configuration
+
+The behavior can be configured in `hugo.toml`:
+
+refLinksErrorLevel ("ERROR")
+: When using `ref` or `relref` to resolve page links and a link cannot resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`).
+
+refLinksNotFoundURL
+: URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is.
+
+[lists]: /templates/lists/
+[output formats]: /templates/output-formats/
+[shortcode]: /content-management/shortcodes/
--- /dev/null
--- /dev/null
++---
++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 >}}
++{{</* csv-to-table "pets.csv" */>}}
++{{< /code >}}
++
++{{< code file=layouts/shortcodes/csv-to-table.html >}}
++{{ with $file := .Get 0 }}
++ {{ with resources.Get $file }}
++ {{ with . | transform.Unmarshal }}
++ <table>
++ <thead>
++ <tr>
++ {{ range index . 0 }}
++ <th>{{ . }}</th>
++ {{ end }}
++ </tr>
++ </thead>
++ <tbody>
++ {{ range after 1 . }}
++ <tr>
++ {{ range . }}
++ <td>{{ . }}</td>
++ {{ end }}
++ </tr>
++ {{ end }}
++ </tbody>
++ </table>
++ {{ 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/
--- /dev/null
- description: Use fenced code blocks and markdown render hooks to display diagrams.
+---
+title: Diagrams
- weight: 50
- weight: 50
++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
- {{< new-in 0.93.0 >}}
++ weight: 260
++weight: 260
+toc: true
+---
- Hugo supports [GoAT](https://github.com/bep/goat) natively. This means that this code block:
+
+## GoAT diagrams (ASCII)
+
- 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 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
+ . . . .--- 1 .-- 1 / 1
+ / \ | | .---+ .-+ +
+ / \ .---+---. .--+--. | '--- 2 | '-- 2 / \ 2
+ + + | | | | ---+ ---+ +
+ / \ / \ .-+-. .-+-. .+. .+. | .--- 3 | .-- 3 \ / 3
+ / \ / \ | | | | | | | | '---+ '-+ +
+ 1 2 3 4 1 2 3 4 1 2 3 4 '--- 4 '-- 4 \ 4
+
+```
+````
+
+Will be rendered as:
+
+```goat
+
+ . . . .--- 1 .-- 1 / 1
+ / \ | | .---+ .-+ +
+ / \ .---+---. .--+--. | '--- 2 | '-- 2 / \ 2
+ + + | | | | ---+ ---+ +
+ / \ / \ .-+-. .-+-. .+. .+. | .--- 3 | .-- 3 \ / 3
+ / \ / \ | | | | | | | | '---+ '-+ +
+ 1 2 3 4 1 2 3 4 1 2 3 4 '--- 4 '-- 4 \ 4
+```
+
+## Mermaid diagrams
+
- ```go-html-template
++Hugo does not provide a built-in template for Mermaid diagrams. Create your own using a [code block render hook]:
+
- ```
++[code block render hook]: /render-hooks/code-blocks/
++
++{{< code file=layouts/_default/_markup/render-codeblock-mermaid.html >}}
+<pre class="mermaid">
+ {{- .Inner | safeHTML }}
+</pre>
+{{ .Page.Store.Set "hasMermaid" true }}
- 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):
++{{< /code >}}
+
- {{ if .Page.Store.Get "hasMermaid" }}
++And then include this snippet at the bottom of the content template:
+
+```go-html-template
++{{ if .Store.Get "hasMermaid" }}
+ <script type="module">
+ import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
+ mermaid.initialize({ startOnLoad: true });
+ </script>
+{{ end }}
+```
+
+With that you can use the `mermaid` language in Markdown code blocks:
+
+````text
+```mermaid
+sequenceDiagram
+ participant Alice
+ participant Bob
+ Alice->>John: Hello John, how are you?
+ loop Healthcheck
+ John->>John: Fight against hypochondria
+ end
+ Note right of John: Rational thoughts <br/>prevail!
+ John-->>Alice: Great!
+ John->>Bob: How about you?
+ Bob-->>John: Jolly good!
+```
+````
+
+## Goat ASCII diagram examples
+
+### Graphics
+
+```goat
+ .
+ 0 3 P * Eye / ^ /
+ *-------* +y \ +) \ / Reflection
+ 1 /| 2 /| ^ \ \ \ v
+ *-------* | | v0 \ v3 --------*--------
+ | |4 | |7 | *----\-----*
+ | *-----|-* +-----> +x / v X \ .-.<-------- o
+ |/ |/ / / o \ | / | Refraction / \
+ *-------* v / \ +-' / \
+ 5 6 +z v1 *------------------* v2 | o-----o
+ v
+
+```
+
+### Complex
+
+```goat
++-------------------+ ^ .---.
+| A Box |__.--.__ __.--> | .-. | |
+| | '--' v | * |<--- | |
++-------------------+ '-' | |
+ Round *---(-. |
+ .-----------------. .-------. .----------. .-------. | | |
+ | Mixed Rounded | | | / Diagonals \ | | | | | |
+ | & Square Corners | '--. .--' / \ |---+---| '-)-' .--------.
+ '--+------------+-' .--. | '-------+--------' | | | | / Search /
+ | | | | '---. | '-------' | '-+------'
+ |<---------->| | | | v Interior | ^
+ ' <---' '----' .-----------. ---. .--- v |
+ .------------------. Diag line | .-------. +---. \ / . |
+ | if (a > b) +---. .--->| | | | | Curved line \ / / \ |
+ | obj->fcn() | \ / | '-------' |<--' + / \ |
+ '------------------' '--' '--+--------' .--. .--. | .-. +Done?+-'
+ .---+-----. | ^ |\ | | /| .--+ | | \ /
+ | | | Join \|/ | | Curved | \| |/ | | \ | \ /
+ | | +----> o --o-- '-' Vertical '--' '--' '-- '--' + .---.
+ <--+---+-----' | /|\ | | 3 |
+ v not:line 'quotes' .-' '---'
+ .-. .---+--------. / A || B *bold* | ^
+ | | | Not a dot | <---+---<-- A dash--is not a line v |
+ '-' '---------+--' / Nor/is this. ---
+
+```
+
+### Process
+
+```goat
+ .
+ .---------. / \
+ | START | / \ .-+-------+-. ___________
+ '----+----' .-------. A / \ B | |COMPLEX| | / \ .-.
+ | | END |<-----+CHOICE +----->| | | +--->+ PREPARATION +--->| X |
+ v '-------' \ / | |PROCESS| | \___________/ '-'
+ .---------. \ / '-+---+---+-'
+ / INPUT / \ /
+ '-----+---' '
+ | ^
+ v |
+ .-----------. .-----+-----. .-.
+ | PROCESS +---------------->| PROCESS |<------+ X |
+ '-----------' '-----------' '-'
+```
+
+### File tree
+
+Created from <https://arthursonzogni.com/Diagon/#Tree>
+
+```goat { width=300 color="orange" }
+───Linux─┬─Android
+ ├─Debian─┬─Ubuntu─┬─Lubuntu
+ │ │ ├─Kubuntu
+ │ │ ├─Xubuntu
+ │ │ └─Xubuntu
+ │ └─Mint
+ ├─Centos
+ └─Fedora
+```
+
+### Sequence diagram
+
+<https://arthursonzogni.com/Diagon/#Sequence>
+
+```goat { class="w-40" }
+┌─────┐ ┌───┐
+│Alice│ │Bob│
+└──┬──┘ └─┬─┘
+ │ │
+ │ Hello Bob! │
+ │───────────>│
+ │ │
+ │Hello Alice!│
+ │<───────────│
+┌──┴──┐ ┌─┴─┐
+│Alice│ │Bob│
+└─────┘ └───┘
+
+```
+
+### Flowchart
+
+<https://arthursonzogni.com/Diagon/#Flowchart>
+
+```goat
+ _________________
+ ╱ ╲ ┌─────┐
+ ╱ DO YOU UNDERSTAND ╲____________________________________________________│GOOD!│
+ ╲ FLOW CHARTS? ╱yes └──┬──┘
+ ╲_________________╱ │
+ │no │
+ _________▽_________ ______________________ │
+ ╱ ╲ ╱ ╲ ┌────┐ │
+╱ OKAY, YOU SEE THE ╲________________╱ ... AND YOU CAN SEE ╲___│GOOD│ │
+╲ LINE LABELED 'YES'? ╱yes ╲ THE ONES LABELED 'NO'? ╱yes└──┬─┘ │
+ ╲___________________╱ ╲______________________╱ │ │
+ │no │no │ │
+ ________▽_________ _________▽__________ │ │
+ ╱ ╲ ┌───────────┐ ╱ ╲ │ │
+ ╱ BUT YOU SEE THE ╲___│WAIT, WHAT?│ ╱ BUT YOU JUST ╲___ │ │
+ ╲ ONES LABELED 'NO'? ╱yes└───────────┘ ╲ FOLLOWED THEM TWICE? ╱yes│ │ │
+ ╲__________________╱ ╲____________________╱ │ │ │
+ │no │no │ │ │
+ ┌───▽───┐ │ │ │ │
+ │LISTEN.│ └───────┬───────┘ │ │
+ └───┬───┘ ┌──────▽─────┐ │ │
+ ┌─────▽────┐ │(THAT WASN'T│ │ │
+ │I HATE YOU│ │A QUESTION) │ │ │
+ └──────────┘ └──────┬─────┘ │ │
+ ┌────▽───┐ │ │
+ │SCREW IT│ │ │
+ └────┬───┘ │ │
+ └─────┬─────┘ │
+ │ │
+ └─────┬─────┘
+ ┌───────▽──────┐
+ │LET'S GO DRING│
+ └───────┬──────┘
+ ┌─────────▽─────────┐
+ │HEY, I SHOULD TRY │
+ │INSTALLING FREEBSD!│
+ └───────────────────┘
+
+```
+
+### Table
+
+<https://arthursonzogni.com/Diagon/#Table>
+
+```goat { class="w-80 dark-blue" }
+┌────────────────────────────────────────────────┐
+│ │
+├────────────────────────────────────────────────┤
+│SYNTAX = { PRODUCTION } . │
+├────────────────────────────────────────────────┤
+│PRODUCTION = IDENTIFIER "=" EXPRESSION "." . │
+├────────────────────────────────────────────────┤
+│EXPRESSION = TERM { "|" TERM } . │
+├────────────────────────────────────────────────┤
+│TERM = FACTOR { FACTOR } . │
+├────────────────────────────────────────────────┤
+│FACTOR = IDENTIFIER │
+├────────────────────────────────────────────────┤
+│ | LITERAL │
+├────────────────────────────────────────────────┤
+│ | "[" EXPRESSION "]" │
+├────────────────────────────────────────────────┤
+│ | "(" EXPRESSION ")" │
+├────────────────────────────────────────────────┤
+│ | "{" EXPRESSION "}" . │
+├────────────────────────────────────────────────┤
+│IDENTIFIER = letter { letter } . │
+├────────────────────────────────────────────────┤
+│LITERAL = """" character { character } """" .│
+└────────────────────────────────────────────────┘
+```
--- /dev/null
- description: Both HTML and Markdown are supported content formats.
+---
+title: Content formats
- You can put any file type into your `/content` directories, but Hugo uses the `markup` front matter value if set or the file extension (see `Markup identifiers` in the table below) to determine if the markup needs to be processed, e.g.:
++description: Create your content using Markdown, HTML, Emacs Org Mode, AsciiDoc, Pandoc, or reStructuredText.
+categories: [content management]
+keywords: [markdown,asciidoc,pandoc,content format]
+menu:
+ docs:
+ parent: content-management
+ weight: 40
+weight: 40
+toc: true
+aliases: [/content/markdown-extras/,/content/supported-formats/,/doc/supported-formats/]
+---
+
- * Markdown converted to HTML
- * [Shortcodes](/content-management/shortcodes/) processed
- * Layout applied
++## Introduction
+
- ## List of content formats
++You may mix content formats throughout your site. For example:
+
- The current list of content formats in Hugo:
++```text
++content/
++└── posts/
++ ├── post-1.md
++ ├── post-2.adoc
++ ├── post-3.org
++ ├── post-4.pandoc
++ ├── post-5.rst
++ └── post-6.html
++```
+
- | Name | Markup identifiers | Comment |
- | ------------- | ------------- |-------------|
- | Goldmark | `markdown`, `goldmark` |Note that you can set the default handler of `md` and `markdown` to something else, see [Configure Markup](/getting-started/configuration-markup/).|
- |Emacs Org-Mode|`org`|See [go-org](https://github.com/niklasfasching/go-org).|
- |AsciiDoc|`asciidocext`, `adoc`, `ad`|Needs [Asciidoctor][ascii] installed.|
- |RST|`rst`|Needs [RST](https://docutils.sourceforge.io/rst.html) installed.|
- |Pandoc|`pandoc`, `pdc`|Needs [Pandoc](https://www.pandoc.org/) installed.|
- |HTML|`html`, `htm`|To be treated as a content file, with layout, shortcodes etc., it must have front matter. If not, it will be copied as-is.|
++Regardless of content format, all content must have [front matter], preferably including both `title` and `date`.
+
- The `markup identifier` is fetched from either the `markup` variable in front matter or from the file extension. For markup-related configuration, see [Configure Markup](/getting-started/configuration-markup/).
++Hugo selects the content renderer based on the `markup` identifier in front matter, falling back to the file extension. See the [classification](#classification) table below for a list of markup identifiers and recognized file extensions.
+
- ## External helpers
++## Formats
+
- Some of the formats in the table above need external helpers installed on your PC. For example, for AsciiDoc files,
- Hugo will try to call the `asciidoctor` command. This means that you will have to install the associated
- tool on your machine to be able to use these formats.
++### Markdown
+
- Hugo passes reasonable default arguments to these external helpers by default:
++Create your content in [Markdown] preceded by front matter.
+
- - `asciidoctor`: `--no-header-footer -`
- - `rst2html`: `--leave-comments --initial-header-level=2`
- - `pandoc`: `--mathjax`
++Markdown is Hugo's default content format. Hugo natively renders Markdown to HTML using [Goldmark]. Goldmark is fast and conforms to the [CommonMark] and [GitHub Flavored Markdown] specifications. You can [configure Goldmark] in your site configuration.
+
- {{% note %}}
- Because additional formats are external commands, generation performance will rely heavily on the performance of the external tool you are using. As this feature is still in its infancy, feedback is welcome.
- {{% /note %}}
++Hugo provides custom Markdown features including:
+
- ### Asciidoctor
++[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.
+
- The Asciidoctor community offers a wide set of tools for the AsciiDoc format that can be installed additionally to Hugo.
- [See the Asciidoctor docs for installation instructions](https://asciidoctor.org/docs/install-toolchain/). Make sure that also all
- optional extensions like `asciidoctor-diagram` or `asciidoctor-html5s` are installed if required.
++[Extensions]
++: Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more.
+
- {{% note %}}
- External `asciidoctor` command requires Hugo rendering to _disk_ to a specific destination directory. It is required to run Hugo with the command option `--destination`.
- {{% /note %}}
++[Mathematics]
++: Include mathematical equations and expressions in Markdown using LaTeX or TeX typesetting syntax.
+
- Some Asciidoctor parameters can be customized in Hugo. See [details].
++[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.
+
- [details]: /getting-started/configuration-markup/#asciidoc
++### HTML
+
- ## Learn markdown
++Create your content in [HTML] preceded by front matter. The content is typically what you would place within an HTML document's `body` or `main` element.
+
- Markdown syntax is simple enough to learn in a single sitting. The following are excellent resources to get you up and running:
++### Emacs Org Mode
+
- * [Daring Fireball: Markdown, John Gruber (Creator of Markdown)][fireball]
- * [Markdown Cheatsheet, Adam Pritchard][mdcheatsheet]
- * [Markdown Tutorial (Interactive), Garen Torikian][mdtutorial]
- * [The Markdown Guide, Matt Cone][mdguide]
++Create your content in the [Emacs Org Mode] format preceded by front matter. You can use Org Mode keywords for front matter. See [details](/content-management/front-matter/#emacs-org-mode)).
+
- [ascii]: https://asciidoctor.org/
- [config]: /getting-started/configuration/
- [developer tools]: /tools/
- [fireball]: https://daringfireball.net/projects/markdown/
- [gfmtasks]: https://guides.github.com/features/mastering-markdown/#syntax
- [helperssource]: https://github.com/gohugoio/hugo/blob/77c60a3440806067109347d04eb5368b65ea0fe8/helpers/general.go#L65
- [hl]: /content-management/syntax-highlighting/
- [hlsc]: /content-management/shortcodes/#highlight
- [hugocss]: /css/style.css
- [ietf]: https://tools.ietf.org/html/
- [mathjaxdocs]: https://docs.mathjax.org/en/latest/
- [mdcheatsheet]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
- [mdguide]: https://www.markdownguide.org/
- [mdtutorial]: https://www.markdowntutorial.com/
- [org]: https://orgmode.org/
- [pandoc]: https://www.pandoc.org/
- [rest]: https://docutils.sourceforge.io/rst.html
- [sc]: /content-management/shortcodes/
- [sct]: /templates/shortcode-templates/
++### AsciiDoc
+
++Create your content in the [AsciiDoc] format preceded by front matter. Hugo renders AsciiDoc content to HTML using the Asciidoctor executable. You must install Asciidoctor and its dependencies (Ruby) to use the AsciiDoc content format.
++
++You can [configure the AsciiDoc renderer] in your site configuration.
++
++In its default configuration, Hugo passes these CLI flags when calling the Asciidoctor executable:
++
++```text
++--no-header-footer
++```
++
++The CLI flags passed to the Asciidoctor executable depend on configuration. You may inspect the flags when building your site:
++
++```text
++hugo --logLevel info
++```
++
++### Pandoc
++
++Create your content in the [Pandoc] format preceded by front matter. Hugo renders Pandoc content to HTML using the Pandoc executable. You must install Pandoc to use the Pandoc content format.
++
++Hugo passes these CLI flags when calling the Pandoc executable:
++
++```text
++--mathjax
++```
++
++### reStructuredText
++
++Create your content in the [reStructuredText] format preceded by front matter. Hugo renders reStructuredText content to HTML using [Docutils], specifically rst2html. You must install Docutils and its dependencies (Python) to use the reStructuredText content format.
++
++Hugo passes these CLI flags when calling the rst2html executable:
++
++```text
++--leave-comments --initial-header-level=2
++```
++
++## Classification
++
++Content format|Media type|Identifier|File extensions
++:--|:--|:--|:--
++Markdown|`text/markdown`|`markdown`|`markdown`,`md`, `mdown`
++HTML|`text/html`|`html`|`htm`, `html`
++Emacs Org Mode|`text/org`|`org`|`org`
++AsciiDoc|`text/asciidoc`|`asciidoc`|`ad`, `adoc`, `asciidoc`
++Pandoc|`text/pandoc`|`pandoc`|`pandoc`, `pdc`
++reStructuredText|`text/rst`|`rst`|`rst`
++
++When converting content to HTML, Hugo uses:
++
++- Native renderers for Markdown, HTML, and Emacs Org mode
++- External renderers for AsciiDoc, Pandoc, and reStructuredText
++
++Native renderers are faster than external renderers.
++
++[AsciiDoc]: https://asciidoc.org/
++[Asciidoctor]: https://asciidoctor.org/
++[Attributes]: /content-management/markdown-attributes/
++[CommonMark]: https://spec.commonmark.org/current/
++[Docutils]: https://docutils.sourceforge.io/
++[Emacs Org Mode]: https://orgmode.org/
++[Extensions]: /getting-started/configuration-markup/#goldmark-extensions
++[GitHub Flavored Markdown]: https://github.github.com/gfm/
++[Goldmark]: https://github.com/yuin/goldmark
++[HTML]: https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/HTML_basics
++[Markdown]: https://daringfireball.net/projects/markdown/
++[Mathematics]: /content-management/mathematics/
++[Pandoc]: https://pandoc.org/
++[Render hooks]: https://gohugo.io/render-hooks/introduction/
++[configure Goldmark]: /getting-started/configuration-markup/#goldmark
++[configure the AsciiDoc renderer]: /getting-started/configuration-markup/#asciidoc
++[front matter]: /content-management/front-matter/
++[reStructuredText]: https://docutils.sourceforge.io/rst.html
--- /dev/null
- description: Hugo allows you to add front matter in yaml, toml, or json to your content files.
+---
+title: 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.
++description: Use front matter to add metadata to your content.
+categories: [content management]
+keywords: [front matter,yaml,toml,json,metadata,archetypes]
+menu:
+ docs:
+ parent: content-management
+ weight: 60
+weight: 60
+toc: true
+aliases: [/content/front-matter/]
+---
+
- {{< youtube Yh2xKRJGff4 >}}
++## Overview
+
- ## Front matter formats
++The front matter at the top of each content file is metadata that:
+
- Hugo supports four formats for front matter, each with their own identifying tokens.
++- Describes the content
++- Augments the content
++- Establishes relationships with other content
++- Controls the published structure of your site
++- Determines template selection
+
- TOML
- : identified by opening and closing `+++`.
++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.
+
- YAML
- : identified by opening and closing `---`.
++[json]: https://www.json.org/
++[toml]: https://toml.io/
++[yaml]: https://yaml.org/
+
- JSON
- : a single JSON object surrounded by '`{`' and '`}`', followed by a new line.
++See examples of front matter delimiters by toggling between the serialization formats below.
+
- 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`).
++{{< code-toggle file=content/example.md fm=true >}}
++title = 'Example'
++date = 2024-02-02T04:14:54-08:00
++draft = false
++weight = 10
++[params]
++author = 'John Smith'
++{{< /code-toggle >}}
+
- ### Example
++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.
+
- {{< 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 >}}
++[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
+
- ## Front matter variables
++## Fields
+
- ### Predefined
++The most common front matter fields are `date`, `draft`, `title`, and `weight`, but you can specify metadata using any of fields below.
+
- 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.
++{{% 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.
+
- 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.
++[parameters]: #parameters
++{{% /note %}}
+
- audio
- : An array of paths to audio files related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:audio`.
++###### aliases
+
- 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.
++(`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.
+
- date
- : The datetime assigned to this page. This is usually fetched from the `date` field in front matter, but this behavior is configurable.
++[`aliases`]: /methods/page/aliases/
++[aliases]: /content-management/urls/#aliases
+
- description
- : The description for the content.
++###### build
+
- draft
- : If `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command.
++(`map`) A map of [build options].
+
- 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.
++[build options]: /content-management/build-options/
+
- headless
- : If `true`, sets a leaf bundle to be [headless][headless-bundle].
++###### cascade {#cascade-field}
+
- images
- : An array of paths to images related to the page; used by [internal templates](/templates/internal) such as `_internal/twitter_cards.html`.
++(`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.
+
- isCJKLanguage
- : If `true`, Hugo will explicitly treat the content as a CJK language; both `.Summary` and `.WordCount` work properly in CJK languages.
++[cascade]: #cascade
+
- keywords
- : The meta keywords for the content.
++###### date
+
- 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`) 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.
+
- lastmod
- : The datetime at which the content was last modified.
++[`date`]: /methods/page/date/
+
- linkTitle
- : Used for creating links to content; if set, Hugo defaults to using the `linkTitle` before the `title`.
++###### description
+
- markup
- : **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown.
++(`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.
+
- outputs
- : Allows you to specify output formats specific to the content. See [output formats][outputs].
++[`description`]: /methods/page/description/
+
- publishDate
- : If in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`.
++###### draft
+
- resources
- : Used for configuring page bundle resources. See [Page Resources][page-resources].
++(`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.
+
- 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`.
++[`draft`]: /methods/page/draft/
+
- slug
- : Overrides the last segment of the URL path. Not applicable to section pages. See [URL Management](/content-management/urls/#slug) for details.
++###### expiryDate
+
- 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.
++(`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.
+
- title
- : The title for the content.
++[`expirydate`]: /methods/page/expirydate/
+
- 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.
++###### headless
+
- url
- : Overrides the entire URL path. Applicable to regular pages and section pages. See [URL Management](/content-management/urls/#url) for details.
++(`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].
+
- videos
- : An array of paths to videos related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:video`.
++[leaf bundles]: /content-management/page-bundles/#leaf-bundles
++[page resources]: /content-management/page-resources/
+
- 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.
++###### isCJKLanguage
+
- {{% 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 %}}
++(`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`], [`ReadingTime`], and [`Summary`] methods on a `Page` object.
+
- ### User-defined
++[`fuzzywordcount`]: /methods/page/wordcount/
++[`readingtime`]: /methods/page/readingtime/
++[`summary`]: /methods/page/summary/
++[`wordcount`]: /methods/page/wordcount/
++[cjk]: /getting-started/glossary/#cjk
+
- 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.
++###### keywords
+
- 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.
++(`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.
+
- {{< code-toggle >}}
- include_toc: true
- show_comments: false
- {{</ code-toggle >}}
++[`keywords`]: /methods/page/keywords/
++[taxonomy]: /getting-started/glossary/#taxonomy
+
- ## Front matter cascade
++<!-- Added in v0.123.0 but purposefully omitted from documentation. -->
++<!--
++kind
++: The kind of page, e.g. "page", "section", "home" etc. This is usually derived from the content path.
++-->
++
++<!-- Added in v0.123.0 but purposefully omitted from documentation. -->
++<!--
++lang
++: The language code for this page. This is usually derived from the module mount or filename.
++-->
++
++###### 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`) An identifier corresponding to one of the supported [content formats]. If not provided, Hugo determines the content renderer based on the file extension.
++
++[content formats]: /content-management/formats/#classification
++
++###### 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/
++
++<!-- Added in v0.123.0 but purposefully omitted from documentation. -->
++<!--
++path
++: The canonical page path.
++-->
++
++###### params
++
++{{< new-in 0.123.0 >}}
++
++(`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
++
++###### sitemap
++
++(`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
+
- 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.
++(`string`) Conceptually different than the page `description`, the summary either summarizes the content or serves as a teaser to encourage readers to visit the page. Access this value from a template using the [`Summary`] method on a `Page` object.
+
- The `cascade` block can be a slice with a optional `_target` keyword, allowing for multiple `cascade` values targeting different page sets.
++[`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 more 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
++
++{{< new-in 0.123.0 >}}
++
++Specify custom page parameters 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]
++author = 'John Smith'
++{{< /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/
++
++Hugo provides [embedded templates] to optionally insert meta data within the `head` element of your rendered pages. These embedded templates expect the following front matter parameters:
++
++Parameter|Data type|Used by these embedded templates
++:--|:--|:--
++`audio`|`[]string`|[`opengraph.html`]
++`images`|`[]string`|[`opengraph.html`], [`schema.html`], [`twitter_cards.html`]
++`videos`|`[]string`|[`opengraph.html`]
++
++The embedded templates will skip a parameter if not provided in front matter, but will throw an error if the data type is unexpected.
++
++[`opengraph.html`]: {{% eturl opengraph %}}
++[`schema.html`]: {{% eturl schema %}}
++[`twitter_cards.html`]: {{% eturl twitter_cards %}}
++[embedded templates]: /templates/embedded/
++
++## Taxonomies
++
++Classify content by adding taxonomy terms to front matter. For example, with this site configuration:
++
++{{< code-toggle file=hugo >}}
++[taxonomies]
++tag = 'tags'
++genre = 'genres'
++{{< /code-toggle >}}
++
++Add taxonomy terms as shown below:
++
++{{< code-toggle file=content/example.md fm=true >}}
++title = 'Example'
++date = 2024-02-02T04:14:54-08:00
++draft = false
++weight = 10
++tags = ['red','blue']
++genres = ['mystery','romance']
++[params]
++author = 'John Smith'
++{{< /code-toggle >}}
++
++You can add taxonomy terms to the front matter of any these [page kinds]:
++
++- `home`
++- `page`
++- `section`
++- `taxonomy`
++- `term`
++
++[page kinds]: /getting-started/glossary/#page-kind
++
++Access taxonomy terms from a template using the [`Params`] or [`GetTerms`] method on a `Page` object. For example:
++
++{{< code file=layouts/_default/single.html >}}
++{{ with .GetTerms "tags" }}
++ <p>Tags</p>
++ <ul>
++ {{ range . }}
++ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
++ {{ end }}
++ </ul>
++{{ end }}
++{{< /code >}}
++
++[`Params`]: /methods/page/params/
++[`GetTerms`]: /methods/page/getterms/
++
++## Cascade
++
++Any [node] can pass down to its descendants a set of front matter values.
++
++[node]: /getting-started/glossary/#node
+
+### Target specific pages
+
- {{< code-toggle >}}
- title ="Blog"
++The `cascade` block can be an array with an optional `_target` keyword, allowing you to target different page sets while cascading values.
+
- path="/blog/**"
++{{< code-toggle file=content/_index.md fm=true >}}
++title ="Home"
+[[cascade]]
++[cascade.params]
+background = "yosemite.jpg"
+[cascade._target]
- Keywords available for `_target`:
++path="/articles/**"
+lang="en"
+kind="page"
+[[cascade]]
++[cascade.params]
+background = "goldenbridge.jpg"
+[cascade._target]
+kind="section"
+{{</ code-toggle >}}
+
- 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.
++Use any combination of these keywords to target a set of pages:
+
- kind
- : A Glob pattern matching the Page's Kind(s), e.g. "{home,section}".
++###### path {#cascade-path}
+
- lang
- : A Glob pattern matching the Page's language, e.g. "{en,sv}".
++(`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.
+
- environment
- : A Glob pattern matching the build environment, e.g. "{production,development}"
++###### kind {#cascade-kind}
++
++(`string`) A Glob pattern matching the Page's Kind(s), e.g. "{home,section}".
++
++###### lang {#cascade-lang}
+
- 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.
++(`string`) A Glob pattern matching the Page's language, e.g. "{en,sv}".
++
++###### environment {#cascade-environment}
++
++(`string`) A Glob pattern matching the build environment, e.g. "{production,development}"
+
+Any of the above can be omitted.
+
+{{% note %}}
- 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 it may be more efficient to define the `cascade` values in your site configuration to avoid duplicating the `cascade` values on the section, taxonomy, or term page for each language.
+
- In `content/blog/_index.md`
-
- {{< code-toggle >}}
- title: Blog
- cascade:
- banner: images/typewriter.jpg
++With a multilingual site, if you choose to define the `cascade` values in front matter, you must create a section, taxonomy, or term page for each language; the `lang` keyword is ignored.
+{{% /note %}}
+
+### Example
+
- With the above example the Blog section page and its descendants will return `images/typewriter.jpg` when `.Params.banner` is invoked unless:
++{{< 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'
+{{</ code-toggle >}}
+
- ## Order content through front matter
++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.
+
- 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 [`<TAXONOMY>_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
++#+AUTHOR: John Smith
++#+GENRES: mystery
++#+GENRES: romance
++#+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]
-
- [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/
++{{< code file=content/example.org lang=text >}}
++#+TAGS[]: red blue
++{{< /code >}}
+
++[content format]: /content-management/formats/
++[emacs org mode]: https://orgmode.org/
--- /dev/null
- #### EXIF variables
+---
+title: Image processing
+description: Resize, crop, rotate, filter, and convert images.
+categories: [content management,fundamentals]
+keywords: [resources,images]
+menu:
+ docs:
+ parent: content-management
+ weight: 90
+toc: true
+weight: 90
+---
+
+## Image resources
+
+To process an image you must access the file as a page resource, global resource, or remote resource.
+
+### Page resource
+
+A page resource is a file within a [page bundle]. A page bundle is a directory with an `index.md` or `_index.md` file at its root.
+
+```text
+content/
+└── posts/
+ └── post-1/ <-- page bundle
+ ├── index.md
+ └── sunset.jpg <-- page resource
+```
+
+To access an image as a page resource:
+
+```go-html-template
+{{ $image := .Resources.Get "sunset.jpg" }}
+```
+
+### Global resource
+
+A global resource is a file within the `assets` directory, or within any directory [mounted] to the `assets` directory.
+
+```text
+assets/
+└── images/
+ └── sunset.jpg <-- global resource
+```
+
+To access an image as a global resource:
+
+```go-html-template
+{{ $image := resources.Get "images/sunset.jpg" }}
+```
+
+### Remote resource
+
+A remote resource is a file on a remote server, accessible via HTTP or HTTPS. To access an image as a remote resource:
+
+```go-html-template
+{{ $image := resources.GetRemote "https://gohugo.io/img/hugo-logo.png" }}
+```
+
+## Image rendering
+
+Once you have accessed an image as either a page resource or a global resource, render it in your templates using the `Permalink`, `RelPermalink`, `Width`, and `Height` properties.
+
+Example 1: Throws an error if the resource is not found.
+
+```go-html-template
+{{ $image := .Resources.GetMatch "sunset.jpg" }}
+<img src="{{ $image.RelPermalink }}" width="{{ $image.Width }}" height="{{ $image.Height }}">
+```
+
+Example 2: Skips image rendering if the resource is not found.
+
+```go-html-template
+{{ $image := .Resources.GetMatch "sunset.jpg" }}
+{{ with $image }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+{{ end }}
+```
+
+Example 3: A more concise way to skip image rendering if the resource is not found.
+
+```go-html-template
+{{ with .Resources.GetMatch "sunset.jpg" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+{{ end }}
+```
+
+Example 4: Skips rendering if there's problem accessing a remote resource.
+
+```go-html-template
+{{ $u := "https://gohugo.io/img/hugo-logo.png" }}
+{{ with resources.GetRemote $u }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get remote resource %q" $u }}
+{{ end }}
+```
+
+## Image processing methods
+
+The `image` resource implements the [`Process`], [`Resize`], [`Fit`], [`Fill`], [`Crop`], [`Filter`], [`Colors`] and [`Exif`] methods.
+
+{{% note %}}
+Metadata (EXIF, IPTC, XMP, etc.) is not preserved during image transformation. Use the `Exif` method with the _original_ image to extract EXIF metadata from JPEG or TIFF images.
+{{% /note %}}
+
+### Process
+
+{{< new-in 0.119.0 >}}
+
+{{% note %}}
+The `Process` method is also available as a filter, which is more effective if you need to apply multiple filters to an image. See [Process filter](/functions/images/process).
+{{% /note %}}
+
+Process processes the image with the given specification. The specification can contain an optional action, one of `resize`, `crop`, `fit` or `fill`. This means that you can use this method instead of [`Resize`], [`Fit`], [`Fill`], or [`Crop`].
+
+See [Options](#image-processing-options) for available options.
+
+You can also use this method apply image processing that does not need any scaling, e.g. format conversions:
+
+```go-html-template
+{{/* Convert the image from JPG to PNG. */}}
+{{ $png := $jpg.Process "png" }}
+```
+
+Some more examples:
+
+```go-html-template
+{{/* Rotate the image 90 degrees counter-clockwise. */}}
+{{ $image := $image.Process "r90" }}
+
+{{/* Scaling actions. */}}
+{{ $image := $image.Process "resize 600x" }}
+{{ $image := $image.Process "crop 600x400" }}
+{{ $image := $image.Process "fit 600x400" }}
+{{ $image := $image.Process "fill 600x400" }}
+```
+
+### Resize
+
+Resize an image to the given width and/or height.
+
+If you specify both width and height, the resulting image will be disproportionally scaled unless the original image has the same aspect ratio.
+
+```go-html-template
+{{/* Resize to a width of 600px and preserve aspect ratio */}}
+{{ $image := $image.Resize "600x" }}
+
+{{/* Resize to a height of 400px and preserve aspect ratio */}}
+{{ $image := $image.Resize "x400" }}
+
+{{/* Resize to a width of 600px and a height of 400px */}}
+{{ $image := $image.Resize "600x400" }}
+```
+
+### Fit
+
+Downscale an image to fit the given dimensions while maintaining aspect ratio. You must provide both width and height.
+
+```go-html-template
+{{ $image := $image.Fit "600x400" }}
+```
+
+### Fill
+
+Crop and resize an image to match the given dimensions. You must provide both width and height. Use the [`anchor`] option to change the crop box anchor point.
+
+```go-html-template
+{{ $image := $image.Fill "600x400" }}
+```
+
+### Crop
+
+Crop an image to match the given dimensions without resizing. You must provide both width and height. Use the [`anchor`] option to change the crop box anchor point.
+
+```go-html-template
+{{ $image := $image.Crop "600x400" }}
+```
+
+### Filter
+
+Apply one or more [filters] to an image.
+
+```go-html-template
+{{ $image := $image.Filter (images.GaussianBlur 6) (images.Pixelate 8) }}
+```
+
+Write this in a more functional style using pipes. Hugo applies the filters in the order given.
+
+```go-html-template
+{{ $image := $image | images.Filter (images.GaussianBlur 6) (images.Pixelate 8) }}
+```
+
+Sometimes it can be useful to create the filter chain once and then reuse it.
+
+```go-html-template
+{{ $filters := slice (images.GaussianBlur 6) (images.Pixelate 8) }}
+{{ $image1 := $image1.Filter $filters }}
+{{ $image2 := $image2.Filter $filters }}
+```
+
+### Colors
+
+{{< new-in 0.104.0 >}}
+
+`.Colors` returns a slice of hex strings with the dominant colors in the image using a simple histogram method.
+
+```go-html-template
+{{ $colors := $image.Colors }}
+```
+
+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 down image.
+
+### EXIF
+
+Provides an [EXIF] object containing image metadata.
+
+You may access EXIF data in JPEG and TIFF images. To prevent errors when processing images without EXIF data, wrap the access in a [`with`] statement.
+
+```go-html-template
+{{ with $image.Exif }}
+ Date: {{ .Date }}
+ Lat/Long: {{ .Lat }}/{{ .Long }}
+ Tags:
+ {{ range $k, $v := .Tags }}
+ TAG: {{ $k }}: {{ $v }}
+ {{ end }}
+{{ end }}
+```
+
+You may also access EXIF fields individually, using the [`lang.FormatNumber`] function to format the fields as needed.
+
+```go-html-template
+{{ with $image.Exif }}
+ <ul>
+ {{ with .Date }}<li>Date: {{ .Format "January 02, 2006" }}</li>{{ end }}
+ {{ with .Tags.ApertureValue }}<li>Aperture: {{ lang.FormatNumber 2 . }}</li>{{ end }}
+ {{ with .Tags.BrightnessValue }}<li>Brightness: {{ lang.FormatNumber 2 . }}</li>{{ end }}
+ {{ with .Tags.ExposureTime }}<li>Exposure Time: {{ . }}</li>{{ end }}
+ {{ with .Tags.FNumber }}<li>F Number: {{ . }}</li>{{ end }}
+ {{ with .Tags.FocalLength }}<li>Focal Length: {{ . }}</li>{{ end }}
+ {{ with .Tags.ISOSpeedRatings }}<li>ISO Speed Ratings: {{ . }}</li>{{ end }}
+ {{ with .Tags.LensModel }}<li>Lens Model: {{ . }}</li>{{ end }}
+ </ul>
+{{ end }}
+```
+
- .Date
- : Image creation date/time. Format with the [time.Format] function.
++#### EXIF methods
+
- .Lat
- : GPS latitude in degrees.
++Date
++: (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`]function.
+
- .Long
- : GPS longitude in degrees.
++[time.Format]: /functions/time/format/
+
- .Tags
- : A collection of the available EXIF tags for this image. You may include or exclude specific tags from this collection in the [site configuration](#exif-data).
++Lat
++: (`float64`) Returns the GPS latitude in degrees.
+
- [time.Format]: /functions/time/format
++Long
++: (`float64`) Returns the GPS longitude in degrees.
++
++Tags
++: (`exif.Tags`) Returns a collection of the available EXIF tags for this image. You may include or exclude specific tags from this collection in the [site configuration].
+
+## Image processing options
+
+The [`Resize`], [`Fit`], [`Fill`], and [`Crop`] methods accept a space-delimited, case-insensitive list of options. The order of the options within the list is irrelevant.
+
+### Dimensions
+
+With the [`Resize`] method you must specify width, height, or both. The [`Fit`], [`Fill`], and [`Crop`] methods require both width and height. All dimensions are in pixels.
+
+```go-html-template
+{{ $image := $image.Resize "600x" }}
+{{ $image := $image.Resize "x400" }}
+{{ $image := $image.Resize "600x400" }}
+{{ $image := $image.Fit "600x400" }}
+{{ $image := $image.Fill "600x400" }}
+{{ $image := $image.Crop "600x400" }}
+```
+
+### Rotation
+
+Rotates an image counter-clockwise by the given angle. Hugo performs rotation _before_ scaling. For example, if the original image is 600x400 and you wish to rotate the image 90 degrees counter-clockwise while scaling it by 50%:
+
+```go-html-template
+{{ $image = $image.Resize "200x r90" }}
+```
+
+In the example above, the width represents the desired width _after_ rotation.
+
+To rotate an image without scaling, use the dimensions of the original image:
+
+```go-html-template
+{{ with .Resources.GetMatch "sunset.jpg" }}
+ {{ with .Resize (printf "%dx%d r90" .Height .Width) }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+ {{ end }}
+{{ end }}
+```
+
+In the example above, on the second line, we have reversed width and height to reflect the desired dimensions _after_ rotation.
+
+### Anchor
+
+When using the [`Crop`] or [`Fill`] method, the _anchor_ determines the placement of the crop box. You may specify `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`.
+
+The default value is `Smart`, which uses [Smartcrop] image analysis to determine the optimal placement of the crop box. You may override the default value in the [site configuration].
+
+For example, if you have a 400x200 image with a bird in the upper left quadrant, you can create a 200x100 thumbnail containing the bird:
+
+```go-html-template
+{{ $image.Crop "200x100 TopLeft" }}
+```
+
+If you apply [rotation](#rotation) when using the [`Crop`] or [`Fill`] method, specify the anchor relative to the rotated image.
+
+### Target format
+
+By default, Hugo encodes the image in the source format. You may convert the image to another format by specifying `bmp`, `gif`, `jpeg`, `jpg`, `png`, `tif`, `tiff`, or `webp`.
+
+```go-html-template
+{{ $image.Resize "600x webp" }}
+```
+
+To convert an image without scaling, use the dimensions of the original image:
+
+```go-html-template
+{{ with .Resources.GetMatch "sunset.jpg" }}
+ {{ with .Resize (printf "%dx%d webp" .Width .Height) }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+ {{ end }}
+{{ end }}
+```
+
+### Quality
+
+Applicable to JPEG and WebP images, the `q` value determines the quality of the converted image. Higher values produce better quality images, while lower values produce smaller files. Set this value to a whole number between 1 and 100, inclusive.
+
+The default value is 75. You may override the default value in the [site configuration].
+
+```go-html-template
+{{ $image.Resize "600x webp q50" }}
+```
+
+### Hint
+
+Applicable to WebP images, this option corresponds to a set of predefined encoding parameters, and is equivalent to the `-preset` flag for the [`cwebp`] encoder.
+
+[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
+
+Value|Example
+:--|:--
+`drawing`|Hand or line drawing with high-contrast details
+`icon`|Small colorful image
+`photo`|Outdoor photograph with natural lighting
+`picture`|Indoor photograph such as a portrait
+`text`|Image that is primarily text
+
+The default value is `photo`. You may override the default value in the [site configuration].
+
+```go-html-template
+{{ $image.Resize "600x webp picture" }}
+```
+
+### Background color
+
+When converting an image from a format that supports transparency (e.g., PNG) to a format that does _not_ support transparency (e.g., JPEG), you may specify the background color of the resulting image.
+
+Use either a 3-digit or 6-digit hexadecimal color code (e.g., `#00f` or `#0000ff`).
+
+The default value is `#ffffff` (white). You may override the default value in the [site configuration].
+
+```go-html-template
+{{ $image.Resize "600x jpg #b31280" }}
+```
+
+### Resampling filter
+
+You may specify the resampling filter used when resizing an image. Commonly used resampling filters include:
+
+Filter|Description
+:--|:--
+`Box`|Simple and fast averaging filter appropriate for downscaling
+`Lanczos`|High-quality resampling filter for photographic images yielding sharp results
+`CatmullRom`|Sharp cubic filter that is faster than the Lanczos filter while providing similar results
+`MitchellNetravali`|Cubic filter that produces smoother results with less ringing artifacts than CatmullRom
+`Linear`|Bilinear resampling filter, produces smooth output, faster than cubic filters
+`NearestNeighbor`|Fastest resampling filter, no antialiasing
+
+The default value is `Box`. You may override the default value in the [site configuration].
+
+```go-html-template
+{{ $image.Resize "600x400 Lanczos" }}
+```
+
+See [github.com/disintegration/imaging] for the complete list of resampling filters. If you wish to improve image quality at the expense of performance, you may wish to experiment with the alternative filters.
+
+## Image processing examples
+
+_The photo of the sunset used in the examples below is Copyright [Bjørn Erik Pedersen](https://commons.wikimedia.org/wiki/User:Bep) (Creative Commons Attribution-Share Alike 4.0 International license)_
+
+{{< imgproc "sunset.jpg" "resize 300x" />}}
+
+{{< imgproc "sunset.jpg" "fill 90x120 left" />}}
+
+{{< imgproc "sunset.jpg" "fill 90x120 right" />}}
+
+{{< imgproc "sunset.jpg" "fit 90x90" />}}
+
+{{< imgproc "sunset.jpg" "crop 250x250 center" />}}
+
+{{< imgproc "sunset.jpg" "resize 300x q10" />}}
+
+This is the shortcode used to generate the examples above:
+
+{{< readfile file=layouts/shortcodes/imgproc.html highlight=go-html-template >}}
+
+Call the shortcode from your Markdown like this:
+
+```go-html-template
+{{</* imgproc "sunset.jpg" "resize 300x" /*/>}}
+```
+
+{{% note %}}
+Note the self-closing shortcode syntax above. You may call the `imgproc` shortcode with or without **inner content**.
+{{% /note %}}
+
+## Imaging configuration
+
+### Processing options
+
+Define an `imaging` section in your site configuration to set the default [image processing options](#image-processing-options).
+
+{{< code-toggle config=imaging />}}
+
+anchor
+: See image processing options: [anchor](#anchor).
+
+bgColor
+: See image processing options: [background color](#background-color).
+
+hint
+: See image processing options: [hint](#hint).
+
+quality
+: See image processing options: [quality](#quality).
+
+resampleFilter
+: See image processing options: [resampling filter](#resampling-filter).
+
+### EXIF data
+
+Define an `imaging.exif` section in your site configuration to control the availability of EXIF data.
+
+{{< code-toggle file=hugo >}}
+[imaging.exif]
+includeFields = ""
+excludeFields = ""
+disableDate = false
+disableLatLong = false
+{{< /code-toggle >}}
+
+disableDate
+: Hugo extracts the image creation date/time into `.Date`. Set this to `true` to disable. Default is `false`.
+
+disableLatLong
+: Hugo extracts the GPS latitude and longitude into `.Lat` and `.Long`. Set this to `true` to disable. Default is `false`.
+
+excludeFields
+: Regular expression matching the EXIF tags to exclude from the `.Tags` collection. Default is `""`.
+
+includeFields
+: Regular expression matching the EXIF tags to include in the `.Tags` collection. Default is `""`. To include all available tags, set this value to `".*"`.
+
+{{% note %}}
+To improve performance and decrease cache size, Hugo excludes the following tags: `ColorSpace`, `Contrast`, `Exif`, `Exposure[M|P|B]`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`.
+
+To control tag availability, change the `excludeFields` or `includeFields` settings as described above.
+{{% /note %}}
+
+## Smart cropping of images
+
+By default, Hugo uses the [Smartcrop] library when cropping images with the `Crop` or`Fill` methods. You can set the anchor point manually, but in most cases the `Smart` option will make a good choice.
+
+Examples using the sunset image from above:
+
+{{< imgproc "sunset.jpg" "fill 200x200 smart" />}}
+
+{{< imgproc "sunset.jpg" "crop 200x200 smart" />}}
+
+## Image processing performance consideration
+
+Hugo caches processed images in the `resources` directory. If you include this directory in source control, Hugo will not have to regenerate the images in a CI/CD workflow (e.g., GitHub Pages, GitLab Pages, Netlify, etc.). This results in faster builds.
+
+If you change image processing methods or options, or if you rename or remove images, the `resources` directory will contain unused images. To remove the unused images, perform garbage collection with:
+
+```sh
+hugo --gc
+```
+
- [page bundle]: /content-management/page-bundles
- [`lang.FormatNumber`]: /functions/lang/formatnumber
++
+[`anchor`]: /content-management/image-processing#anchor
+[mounted]: /hugo-modules/configuration#module-configuration-mounts
++[page bundle]: /content-management/page-bundles/
++[`lang.FormatNumber`]: /functions/lang/formatnumber/
+[filters]: /functions/images/filter/#image-filters
+[github.com/disintegration/imaging]: <https://github.com/disintegration/imaging#image-resizing>
+[Smartcrop]: <https://github.com/muesli/smartcrop#smartcrop>
+[Exif]: <https://en.wikipedia.org/wiki/Exif>
+[`Process`]: #process
+[`Colors`]: #colors
+[`Crop`]: #crop
+[`Exif`]: #exif
+[`Fill`]: #fill
+[`Filter`]: #filter
+[`Fit`]: #fit
+[`Resize`]: #resize
+[site configuration]: #processing-options
+[`with`]: /functions/go-template/with/
--- /dev/null
--- /dev/null
++---
++title: Markdown attributes
++description: Use Markdown attributes to add HTML attributes when rendering Markdown to HTML.
++categories: [content management]
++keywords: [goldmark,markdown]
++menu:
++ docs:
++ parent: content-management
++ weight: 240
++weight: 240
++toc: true
++---
++
++## Overview
++
++Hugo supports Markdown attributes on images and block elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables.
++
++For example:
++
++```text
++This is a paragraph.
++{class="foo bar" id="baz"}
++```
++
++With `class` and `id` you can use shorthand notation:
++
++```text
++This is a paragraph.
++{.foo .bar #baz}
++```
++
++Hugo renders both of these to:
++
++```html
++<p class="foo bar" id="baz">This is a paragraph.</p>
++```
++
++## Block elements
++
++Update your site configuration to enable Markdown attributes for block-level elements.
++
++{{< code-toggle file=hugo >}}
++[markup.goldmark.parser.attribute]
++title = true # default is true
++block = true # default is false
++{{< /code-toggle >}}
++
++
++## Standalone images
++
++By default, when the [Goldmark] Markdown renderer encounters a standalone image element (no other elements or text on the same line), it wraps the image element within a paragraph element per the [CommonMark specification].
++
++[CommonMark specification]: https://spec.commonmark.org/current/
++[Goldmark]: https://github.com/yuin/goldmark
++
++If you were to place an attribute list beneath an image element, Hugo would apply the attributes to the surrounding paragraph, not the image.
++
++To apply attributes to a standalone image element, you must disable the default wrapping behavior:
++
++{{< code-toggle file=hugo >}}
++[markup.goldmark.parser]
++wrapStandAloneImageWithinParagraph = false # default is true
++{{< /code-toggle >}}
++
++## Usage
++
++You may add [global HTML attributes], or HTML attributes specific to the current element type. Consistent with its content security model, Hugo removes HTML event attributes such as `onclick` and `onmouseover`.
++
++[global HTML attributes]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes
++
++The attribute list consists of one or more key-value pairs, separated by spaces or commas, wrapped by braces. You must quote string values that contain spaces. Unlike HTML, boolean attributes must have both key and value.
++
++For example:
++
++```text
++> This is a blockquote.
++{class="foo bar" hidden=hidden}
++```
++
++Hugo renders this to:
++
++```html
++<blockquote class="foo bar" hidden="hidden">
++ <p>This is a blockquote.</p>
++</blockquote>
++```
++
++In most cases, place the attribute list beneath the markup element. For headings and fenced code blocks, place the attribute list on the right.
++
++Element|Position of attribute list
++:--|:--
++blockquote | bottom
++fenced code block | right
++heading | right
++horizontal rule | bottom
++image | bottom
++list | bottom
++paragraph | bottom
++table | bottom
++
++For example:
++
++````text
++## Section 1 {class=foo}
++
++```bash {class=foo linenos=inline}
++declare a=1
++echo "${a}"
++```
++
++This is a paragraph.
++{class=foo}
++````
++
++As shown above, the attribute list for fenced code blocks is not limited to HTML attributes. You can also configure syntax highlighting by passing one or more of [these options](/functions/transform/highlight/#options).
--- /dev/null
- title: Mathematics in markdown
+---
- description: Include mathematical equations and expressions in your markdown using LaTeX or TeX typesetting syntax.
++title: Mathematics in Markdown
+linkTitle: Mathematics
- weight: 250
- weight: 250
++description: Include mathematical equations and expressions in your Markdown using LaTeX or TeX typesetting syntax.
+categories: [content management]
+keywords: [chemical,chemistry,latex,math,mathjax,tex,typesetting]
+menu:
+ docs:
+ parent: content-management
- Follow these instructions to include mathematical equations and expressions in your markdown using LaTeX or TeX typesetting syntax.
++ weight: 270
++weight: 270
+toc: true
+math: true
+---
+
+{{< new-in 0.122.0 >}}
+
+\[
+\begin{aligned}
+KL(\hat{y} || y) &= \sum_{c=1}^{M}\hat{y}_c \log{\frac{\hat{y}_c}{y_c}} \\
+JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y+\hat{y}}{2}))
+\end{aligned}
+\]
+
+## Overview
+
+Mathematical equations and expressions authored in [LaTeX] or [TeX] are common in academic and scientific publications. Your browser typically renders this mathematical markup using an open-source JavaScript display engine such as [MathJax] or [KaTeX].
+
+For example, this is the mathematical markup for the equations displayed at the top of this page:
+
+```text
+\[
+\begin{aligned}
+KL(\hat{y} || y) &= \sum_{c=1}^{M}\hat{y}_c \log{\frac{\hat{y}_c}{y_c}} \\
+JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y+\hat{y}}{2}))
+\end{aligned}
+\]
+```
+
+Equations and expressions can be displayed inline with other text, or as standalone blocks. Block presentation is also known as "display" mode.
+
+Whether an equation or expression appears inline, or as a block, depends on the delimiters that surround the mathematical markup. Delimiters are defined in pairs, where each pair consists of an opening and closing delimiter. The opening and closing delimiters may be the same, or different. Common delimiter pairs are shown in [Step 1].
+
+The approach described below avoids reliance on platform-specific features like shortcodes or code block render hooks. Instead, it utilizes a standardized markup format for mathematical equations and expressions, compatible with the rendering engines used by GitHub, GitLab, [Microsoft VS Code], [Obsidian], [Typora], and others.
+
+## Setup
+
- Enable and configure the Goldmark [passthrough extension] in your site configuration. The passthrough extension preserves raw markdown within delimited snippets of text, including the delimiters themselves.
++Follow these instructions to include mathematical equations and expressions in your Markdown using LaTeX or TeX typesetting syntax.
+
+###### Step 1
+
- Include mathematical equations and expressions in your markdown using LaTeX or TeX typesetting syntax.
++Enable and configure the Goldmark [passthrough extension] in your site configuration. The passthrough extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves.
+
+{{< code-toggle file=hugo copy=true >}}
+[markup.goldmark.extensions.passthrough]
+enable = true
+
+[markup.goldmark.extensions.passthrough.delimiters]
+block = [['\[', '\]'], ['$$', '$$']]
+inline = [['\(', '\)']]
+
+[params]
+math = true
+{{< /code-toggle >}}
+
+The configuration above enables mathematical rendering on every page unless you set the `math` parameter to `false` in front matter. To enable mathematical rendering as needed, set the `math` parameter to `false` in your site configuration, and set the `math` parameter to `true` in front matter. Use this parameter in your base template as shown in [Step 3].
+
+{{% note %}}
+The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration and JavaScript, you will need to double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting.
+
+See the [inline delimiters](#inline-delimiters) section for details.
+{{% /note %}}
+
+To disable passthrough of inline snippets, omit the `inline` key from the configuration:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.extensions.passthrough.delimiters]
+block = [['\[', '\]'], ['$$', '$$']]
+{{< /code-toggle >}}
+
+You can define your own opening and closing delimiters, provided they match the delimiters that you set in [Step 2].
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.extensions.passthrough.delimiters]
+block = [['@@', '@@']]
+inline = [['@', '@']]
+{{< /code-toggle >}}
+
+###### Step 2
+
+Create a partial template to load MathJax or KaTeX. The example below loads MathJax, or you can use KaTeX as described in the [engines](#engines) section.
+
+{{< code file=layouts/partials/math.html copy=true >}}
+<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>
+<script>
+ MathJax = {
+ tex: {
+ displayMath: [['\\[', '\\]'], ['$$', '$$']], // block
+ inlineMath: [['\\(', '\\)']] // inline
+ }
+ };
+</script>
+{{< /code >}}
+
+The delimiters above must match the delimiters in your site configuration.
+
+###### Step 3
+
+Conditionally call the partial template from the base template.
+
+{{< code file=layouts/_default/baseof.html >}}
+<head>
+ ...
+ {{ if .Param "math" }}
+ {{ partialCached "math.html" . }}
+ {{ end }}
+ ...
+</head>
+{{< /code >}}
+
+The example above loads the partial template if you have set the `math` parameter in front matter to `true`. If you have not set the `math` parameter in front matter, the conditional statement falls back to the `math` parameter in your site configuration.
+
+###### Step 4
+
- math = true
++Include mathematical equations and expressions in your Markdown using LaTeX or TeX typesetting syntax.
+
+{{< code file=content/math-examples.md copy=true >}}
+This is an inline \(a^*=x-b^*\) equation.
+
+These are block equations:
+
+\[a^*=x-b^*\]
+
+\[ a^*=x-b^* \]
+
+\[
+a^*=x-b^*
+\]
+
+These are block equations using alternate delimiters:
+
+$$a^*=x-b^*$$
+
+$$ a^*=x-b^* $$
+
+$$
+a^*=x-b^*
+$$
+{{< /code >}}
+
+If you set the `math` parameter to `false` in your site configuration, you must set the `math` parameter to `true` in front matter. For example:
+
+{{< code-toggle file=content/math-examples.md fm=true >}}
+title = 'Math examples'
+date = 2024-01-24T18:09:49-08:00
++[params]
++math = true
+{{< /code-toggle >}}
+
+## Inline delimiters
+
+The configuration, JavaScript, and examples above use the `\(...\)` delimiter pair for inline equations. The `$...$` delimiter pair is a common alternative, but using it may result in unintended formatting if you use the `$` symbol outside of math contexts.
+
+If you add the `$...$` delimiter pair to your configuration and JavaScript, you must double-escape the `$` when outside of math contexts, regardless of whether mathematical rendering is enabled on the page. For example:
+
+```text
+A \\$5 bill _saved_ is a \\$5 bill _earned_.
+```
+
+{{% note %}}
+If you use the `$...$` delimiter pair for inline equations, and occasionally use the `$` symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by [this KaTeX limitation](https://github.com/KaTeX/KaTeX/issues/437).
+{{% /note %}}
+
+## Engines
+
+MathJax and KaTeX are open-source JavaScript display engines. Both engines are fast, but at the time of this writing MathJax v3.2.2 is slightly faster than KaTeX v0.16.9.
+
+{{% note %}}
+If you use the `$...$` delimiter pair for inline equations, and occasionally use the `$` symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by [this KaTeX limitation](https://github.com/KaTeX/KaTeX/issues/437).
+
+See the [inline delimiters](#inline-delimiters) section for details.
+{{% /note %}}
+
+To use KaTeX instead of MathJax, replace the partial template from [Step 2] with this:
+
+{{< code file=layouts/partials/math.html copy=true >}}
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css" integrity="sha384-n8MVd4RsNIU0tAv4ct0nTaAbDJwPJzDEaqSD1odI+WdtXRGWt2kTvGFasHpSy3SV" crossorigin="anonymous">
+<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js" integrity="sha384-XjKyOOlGwcjNTAIQHIpgOno0Hl1YQqzUOEleOLALmuqehneUG+vnGctmUb0ZY0l8" crossorigin="anonymous"></script>
+<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/auto-render.min.js" integrity="sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCRWbxyPt0Koah1uHoK0o4+/RRE05" crossorigin="anonymous"></script>
+<script>
+ document.addEventListener("DOMContentLoaded", function() {
+ renderMathInElement(document.body, {
+ delimiters: [
+ {left: '\\[', right: '\\]', display: true}, // block
+ {left: '$$', right: '$$', display: true}, // block
+ {left: '\\(', right: '\\)', display: false}, // inline
+ ],
+ throwOnError : false
+ });
+ });
+</script>
+{{< /code >}}
+
+The delimiters above must match the delimiters in your site configuration.
+
+## Chemistry
+
+Both MathJax and KaTeX provide support for chemical equations. For example:
+
+```text
+$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$
+```
+
+$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$
+
+As shown in [Step 2] above, MathJax supports chemical equations without additional configuration. To add chemistry support to KaTeX, enable the mhchem extension as described in the KaTeX [documentation](https://katex.org/docs/libs).
+
+[KaTeX]: https://katex.org/
+[LaTeX]: https://www.latex-project.org/
+[MathJax]: https://www.mathjax.org/
+[Microsoft VS Code]: https://code.visualstudio.com/
+[Obsidian]: https://obsidian.md/
+[Step 1]: #step-1
+[Step 2]: #step-2
+[Step 3]: #step-3
+[TeX]: https://en.wikipedia.org/wiki/TeX
+[Typora]: https://typora.io/
+[passthrough extension]: https://github.com/gohugoio/hugo-goldmark-extensions
--- /dev/null
- To automatically define menu entries for each top-level section of your site, enable the section pages menu in your site configuration.
+---
+title: Menus
+description: Create menus by defining entries, localizing each entry, and rendering the resulting data structure.
+categories: [content management]
+keywords: [menus]
+menu:
+ docs:
+ parent: content-management
+ weight: 190
+weight: 190
+toc: true
+aliases: [/extras/menus/]
+---
+
+## Overview
+
+To create a menu for your site:
+
+1. Define the menu entries
+2. [Localize] each entry
+3. Render the menu with a [template]
+
+Create multiple menus, either flat or nested. For example, create a main menu for the header, and a separate menu for the footer.
+
+There are three ways to define menu entries:
+
+1. Automatically
+1. In front matter
+1. In site configuration
+
+{{% note %}}
+Although you can use these methods in combination when defining a menu, the menu will be easier to conceptualize and maintain if you use one method throughout the site.
+{{% /note %}}
+
+## Define automatically
+
- : (`string`) The file path of the target page, relative to the `content` directory. Omit language code and file extension. Required for *internal* links.
++To automatically define a menu entry for each top-level [section] of your site, enable the section pages menu in your site configuration.
+
+{{< code-toggle file=hugo >}}
+sectionPagesMenu = "main"
+{{< /code-toggle >}}
+
+This creates a menu structure that you can access with `site.Menus.main` in your templates. See [menu templates] for details.
+
+## Define in front matter
+
+To add a page to the "main" menu:
+
+{{< code-toggle file=content/about.md fm=true >}}
+title = 'About'
+menus = 'main'
+{{< /code-toggle >}}
+
+Access the entry with `site.Menus.main` in your templates. See [menu templates] for details.
+
+To add a page to the "main" and "footer" menus:
+
+{{< code-toggle file=content/contact.md fm=true >}}
+title = 'Contact'
+menus = ['main','footer']
+{{< /code-toggle >}}
+
+Access the entry with `site.Menus.main` and `site.Menus.footer` in your templates. See [menu templates] for details.
+
+{{% note %}}
+The configuration key in the examples above is `menus`. The `menu` (singular) configuration key is an alias for `menus`.
+{{% /note %}}
+
+### Properties {#properties-front-matter}
+
+Use these properties when defining menu entries in front matter:
+
+identifier
+: (`string`) Required when two or more menu entries have the same `name`, or when localizing the `name` using translation tables. Must start with a letter, followed by letters, digits, or underscores.
+
+name
+: (`string`) The text to display when rendering the menu entry.
+
+params
+: (`map`) User-defined properties for the menu entry.
+
+parent
+: (`string`) The `identifier` of the parent menu entry. If `identifier` is not defined, use `name`. Required for child entries in a nested menu.
+
+post
+: (`string`) The HTML to append when rendering the menu entry.
+
+pre
+: (`string`) The HTML to prepend when rendering the menu entry.
+
+title
+: (`string`) The HTML `title` attribute of the rendered menu entry.
+
+weight
+: (`int`) A non-zero integer indicating the entry's position relative the root of the menu, or to its parent for a child entry. Lighter entries float to the top, while heavier entries sink to the bottom.
+
+### Example {#example-front-matter}
+
+This front matter menu entry demonstrates some of the available properties:
+
+{{< code-toggle file=content/products/software.md fm=true >}}
+title = 'Software'
+[[menus.main]]
+parent = 'Products'
+weight = 20
+pre = '<i class="fa-solid fa-code"></i>'
+[menus.main.params]
+class = 'center'
+{{< /code-toggle >}}
+
+Access the entry with `site.Menus.main` in your templates. See [menu templates] for details.
+
+## Define in site configuration
+
+To define entries for the "main" menu:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+name = 'Home'
+pageRef = '/'
+weight = 10
+
+[[menus.main]]
+name = 'Products'
+pageRef = '/products'
+weight = 20
+
+[[menus.main]]
+name = 'Services'
+pageRef = '/services'
+weight = 30
+{{< /code-toggle >}}
+
+This creates a menu structure that you can access with `site.Menus.main` in your templates. See [menu templates] for details.
+
+To define entries for the "footer" menu:
+
+{{< code-toggle file=hugo >}}
+[[menus.footer]]
+name = 'Terms'
+pageRef = '/terms'
+weight = 10
+
+[[menus.footer]]
+name = 'Privacy'
+pageRef = '/privacy'
+weight = 20
+{{< /code-toggle >}}
+
+This creates a menu structure that you can access with `site.Menus.footer` in your templates. See [menu templates] for details.
+
+{{% note %}}
+The configuration key in the examples above is `menus`. The `menu` (singular) configuration key is an alias for `menus`.
+{{% /note %}}
+
+### Properties {#properties-site-configuration}
+
+{{% note %}}
+The [properties available to entries defined in front matter] are also available to entries defined in site configuration.
+
+[properties available to entries defined in front matter]: /content-management/menus/#properties-front-matter
+{{% /note %}}
+
+Each menu entry defined in site configuration requires two or more properties:
+
+- Specify `name` and `pageRef` for internal links
+- Specify `name` and `url` for external links
+
+pageRef
++: (`string`) The logical path of the target page, relative to the `content` directory. Omit language code and file extension. Required for *internal* links.
+
+Kind|pageRef
+:--|:--
+home|`/`
+page|`/books/book-1`
+section|`/books`
+taxonomy|`/tags`
+term|`/tags/foo`
+
+url
+: (`string`) Required for *external* links.
+
+### Example {#example-site-configuration}
+
+This nested menu demonstrates some of the available properties:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+name = 'Products'
+pageRef = '/products'
+weight = 10
+
+[[menus.main]]
+name = 'Hardware'
+pageRef = '/products/hardware'
+parent = 'Products'
+weight = 1
+
+[[menus.main]]
+name = 'Software'
+pageRef = '/products/software'
+parent = 'Products'
+weight = 2
+
+[[menus.main]]
+name = 'Services'
+pageRef = '/services'
+weight = 20
+
+[[menus.main]]
+name = 'Hugo'
+pre = '<i class="fa fa-heart"></i>'
+url = 'https://gohugo.io/'
+weight = 30
+[menus.main.params]
+rel = 'external'
+{{< /code-toggle >}}
+
+This creates a menu structure that you can access with `site.Menus.main` in your templates. See [menu templates] for details.
+
+## Localize
+
+Hugo provides two methods to localize your menu entries. See [multilingual].
+
+## Render
+
+See [menu templates].
+
+[localize]: /content-management/multilingual/#menus
+[menu templates]: /templates/menu-templates/
+[multilingual]: /content-management/multilingual/#menus
++[section]: /getting-started/glossary/#section
+[template]: /templates/menu-templates/
--- /dev/null
- description: Hugo supports the creation of websites with multiple languages side by side.
+---
+title: Multilingual mode
+linkTitle: Multilingual
- You should define the available languages in a `languages` section in your site configuration.
-
- Also See [Hugo Multilingual Part 1: Content translation].
-
++description: 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.
+categories: [content management]
+keywords: [multilingual,i18n,internationalization]
+menu:
+ docs:
+ parent: content-management
+ weight: 230
+weight: 230
+toc: true
+aliases: [/content/multilingual/,/tutorials/create-a-multilingual-site/]
+---
+
- : (`string`) The project's default language tag as defined by [RFC 5646]. Must be lower case, and must match one of the defined language keys. Default is `en`. Examples:
+## Configure languages
+
+This is the default language configuration:
+
+{{< code-toggle config=languages />}}
+
++In the above, `en` is the language key.
++
++{{% note %}}
++Each language key must conform to the syntax described in [RFC 5646]. You must use hyphens to separate subtags. For example:
++
++- `en`
++- `en-GB`
++- `pt-BR`
++
++[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
++{{% /note %}}
++
+This is an example of a site configuration for a multilingual project. Any key not defined in a `languages` object will fall back to the global value in the root of your site configuration.
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = true
+
+[languages.de]
+contentDir = 'content/de'
+disabled = false
+languageCode = 'de-DE'
+languageDirection = 'ltr'
+languageName = 'Deutsch'
+title = 'Projekt Dokumentation'
+weight = 1
+
+[languages.de.params]
+subtitle = 'Referenz, Tutorials und Erklärungen'
+
+[languages.en]
+contentDir = 'content/en'
+disabled = false
+languageCode = 'en-US'
+languageDirection = 'ltr'
+languageName = 'English'
+title = 'Project Documentation'
+weight = 2
+
+[languages.en.params]
+subtitle = 'Reference, Tutorials, and Explanations'
+{{< /code-toggle >}}
+
+defaultContentLanguage
- - `en-gb`
- - `pt-br`
++: (`string`) The project's default language key, conforming to the syntax described in [RFC 5646]. This value must match one of the defined language keys. Examples:
+
+- `en`
- : (`string`) The language tag as defined by [RFC 5646]. This value may include upper and lower case characters, hyphens, or underscores, and does not affect localization or URLs. Hugo uses this value to populate the `language` element in the [built-in RSS template], and the `lang` attribute of the `html` element in the [built-in alias template]. Examples:
++- `en-GB`
++- `pt-BR`
+
+defaultContentLanguageInSubdir
+: (`bool`) If `true`, Hugo renders the default language site in a subdirectory matching the `defaultContentLanguage`. Default is `false`.
+
+contentDir
+: (`string`) The content directory for this language. Omit if [translating by file name].
+
+disabled
+: (`bool`) If `true`, Hugo will not render content for this language. Default is `false`.
+
+languageCode
- : (`string`) The language title. When set, this overrides the site title for this language.
++: (`string`) The language tag as described in [RFC 5646]. This value does not affect localization or URLs. Hugo uses this value to populate the `language` element in the [built-in RSS template], and the `lang` attribute of the `html` element in the [built-in alias template]. Examples:
+
+- `en`
+- `en-GB`
+- `pt-BR`
+
+languageDirection
+: (`string`) The language direction, either left-to-right (`ltr`) or right-to-left (`rtl`). Use this value in your templates with the global [`dir`] HTML attribute.
+
+languageName
+: (`string`) The language name, typically used when rendering a language switcher.
+
+title
- [RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
++: (`string`) The site title for this langauge (optional).
+
+weight
+: (`int`) The language weight. When set to a non-zero value, this is the primary sort criteria for this language.
+
+[`dir`]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir
+[built-in RSS template]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/rss.xml
+[built-in alias template]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/alias.html
- From **Hugo 0.31** we support multiple languages in a multihost configuration. See [this issue](https://github.com/gohugoio/hugo/issues/4027) for details.
++[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
+[translating by file name]: #translation-by-file-name
+
+### Changes in Hugo 0.112.0
+
+{{< new-in 0.112.0 >}}
+
+In Hugo `v0.112.0` we consolidated all configuration options, and improved how the languages and their parameters are merged with the main configuration. But while testing this on Hugo sites out there, we received some error reports and reverted some of the changes in favor of deprecation warnings:
+
+1. `site.Language.Params` is deprecated. Use `site.Params` directly.
+1. Adding custom parameters to the top level language configuration is deprecated. Define custom parameters within `languages.xx.params`. See `color` in the example below.
+
+{{< code-toggle file=hugo >}}
+
+title = "My blog"
+languageCode = "en-us"
+
+[languages]
+[languages.sv]
+title = "Min blogg"
+languageCode = "sv"
+[languages.en.params]
+color = "blue"
+{{< /code-toggle >}}
+
+In the example above, all settings except `color` below `params` map to predefined configuration options in Hugo for the site and its language, and should be accessed via the documented accessors:
+
+```go-html-template
+{{ site.Title }}
+{{ site.LanguageCode }}
+{{ site.Params.color }}
+```
+
+### Disable a language
+
+To disable a language within a `languages` object in your site configuration:
+
+{{< code-toggle file=hugo >}}
+[languages.es]
+disabled = true
+{{< /code-toggle >}}
+
+To disable one or more languages in the root of your site configuration:
+
+{{< code-toggle file=hugo >}}
+disableLanguages = ["es", "fr"]
+{{< /code-toggle >}}
+
+To disable one or more languages using an environment variable:
+
+```sh
+HUGO_DISABLELANGUAGES="es fr" hugo
+```
+
+Note that you cannot disable the default content language.
+
+### Configure multilingual multihost
+
- This means that you can now configure a `baseURL` per `language`:
+
- [languages.fr]
- baseURL = "https://example.fr"
- languageName = "Français"
- weight = 1
- title = "En Français"
-
- [languages.en]
- baseURL = "https://example.org/"
- languageName = "English"
- weight = 2
- title = "In English"
++Hugo supports multiple languages in a multihost configuration. This means you can configure a `baseURL` per `language`.
+
+{{% note %}}
+If a `baseURL` is set on the `language` level, then all languages must have one and they must all be different.
+{{% /note %}}
+
+Example:
+
+{{< code-toggle file=hugo >}}
+[languages]
- <a href="{{ .RelPermalink }}">{{ .Lang }}: {{ .LinkTitle }}{{ if .IsPage }} ({{ i18n "wordCount" . }}){{ end }}</a>
++ [languages.en]
++ baseURL = 'https://en.example.org/'
++ languageName = 'English'
++ title = 'In English'
++ weight = 2
++ [languages.fr]
++ baseURL = 'https://fr.example.org'
++ languageName = 'Français'
++ title = 'En Français'
++ weight = 1
+{{</ code-toggle >}}
+
+With the above, the two sites will be generated into `public` with their own root:
+
+```text
+public
+├── en
+└── fr
+```
+
+**All URLs (i.e `.Permalink` etc.) will be generated from that root. So the English home page above will have its `.Permalink` set to `https://example.org/`.**
+
+When you run `hugo server` we will start multiple HTTP servers. You will typically see something like this in the console:
+
+```text
+Web Server is available at 127.0.0.1:1313 (bind address 127.0.0.1) fr
+Web Server is available at 127.0.0.1:1314 (bind address 127.0.0.1) en
+Press Ctrl+C to stop
+```
+
+Live reload and `--navigateToChanged` between the servers work as expected.
+
+## Translate your content
+
+There are two ways to manage your content translations. Both ensure each page is assigned a language and is linked to its counterpart translations.
+
+### Translation by file name
+
+Considering the following example:
+
+1. `/content/about.en.md`
+2. `/content/about.fr.md`
+
+The first file is assigned the English language and is linked to the second.
+The second file is assigned the French language and is linked to the first.
+
+Their language is __assigned__ according to the language code added as a __suffix to the file name__.
+
+By having the same **path and base file name**, the content pieces are __linked__ together as translated pages.
+
+{{% note %}}
+If a file has no language code, it will be assigned the default language.
+{{% /note %}}
+
+### Translation by content directory
+
+This system uses different content directories for each of the languages. Each language's content directory is set using the `contentDir` parameter.
+
+{{< code-toggle file=hugo >}}
+languages:
+ en:
+ weight: 10
+ languageName: "English"
+ contentDir: "content/english"
+ fr:
+ weight: 20
+ languageName: "Français"
+ contentDir: "content/french"
+{{< /code-toggle >}}
+
+The value of `contentDir` can be any valid path -- even absolute path references. The only restriction is that the content directories cannot overlap.
+
+Considering the following example in conjunction with the configuration above:
+
+1. `/content/english/about.md`
+2. `/content/french/about.md`
+
+The first file is assigned the English language and is linked to the second.
+The second file is assigned the French language and is linked to the first.
+
+Their language is __assigned__ according to the content directory they are __placed__ in.
+
+By having the same **path and basename** (relative to their language content directory), the content pieces are __linked__ together as translated pages.
+
+### Bypassing default linking
+
+Any pages sharing the same `translationKey` set in front matter will be linked as translated pages regardless of basename or location.
+
+Considering the following example:
+
+1. `/content/about-us.en.md`
+2. `/content/om.nn.md`
+3. `/content/presentation/a-propos.fr.md`
+
+{{< code-toggle >}}
+translationKey: "about"
+{{< /code-toggle >}}
+
+By setting the `translationKey` front matter parameter to `about` in all three pages, they will be __linked__ as translated pages.
+
+### Localizing permalinks
+
+Because paths and file names are used to handle linking, all translated pages will share the same URL (apart from the language subdirectory).
+
+To localize URLs:
+
+- For a regular page, set either [`slug`] or [`url`] in front matter
+- For a section page, set [`url`] in front matter
+
+[`slug`]: /content-management/urls/#slug
+[`url`]: /content-management/urls/#url
+
+For example, a French translation can have its own localized slug.
+
+{{< code-toggle file=content/about.fr.md fm=true >}}
+title: A Propos
+slug: "a-propos"
+{{< /code-toggle >}}
+
+At render, Hugo will build both `/about/` and `/fr/a-propos/` without affecting the translation link.
+
+### Page bundles
+
+To avoid the burden of having to duplicate files, each Page Bundle inherits the resources of its linked translated pages' bundles except for the content files (Markdown files, HTML files etc...).
+
+Therefore, from within a template, the page will have access to the files from all linked pages' bundles.
+
+If, across the linked bundles, two or more files share the same basename, only one will be included and chosen as follows:
+
+* File from current language bundle, if present.
+* First file found across bundles by order of language `Weight`.
+
+{{% note %}}
+Page Bundle resources follow the same language assignment logic as content files, both by file name (`image.jpg`, `image.fr.jpg`) and by directory (`english/about/header.jpg`, `french/about/header.jpg`).
+{{%/ note %}}
+
+## Reference translated content
+
+To create a list of links to translated content, use a template similar to the following:
+
+{{< code file=layouts/partials/i18nlist.html >}}
+{{ if .IsTranslated }}
+<h4>{{ i18n "translations" }}</h4>
+<ul>
+ {{ range .Translations }}
+ <li>
- Hugo uses [go-i18n] to support string translations. [See the project's source repository][go-i18n-source] to find tools that will help you manage your translation workflows.
-
- Translations are collected from the `themes/<THEME>/i18n/` folder (built into the theme), as well as translations present in `i18n/` at the root of your project. In the `i18n`, the translations will be merged and take precedence over what is in the theme folder. Language files should be named according to [RFC 5646] with names such as `en-US.toml`, `fr.toml`, etc.
-
- Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7](https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7) are also supported. You may omit the `art-x-` prefix for brevity. For example:
-
- ```text
- art-x-hugolang
- hugolang
- ```
-
- Private use subtags must not exceed 8 alphanumeric characters.
-
- ### Query basic translation
-
- From within your templates, use the [`i18n`] function like this:
-
- [`i18n`]: /functions/lang/translate
-
- ```go-html-template
- {{ i18n "home" }}
- ```
-
- The function will search for the `"home"` id:
-
- {{< code-toggle file=i18n/en-US >}}
- [home]
- other = "Home"
- {{< /code-toggle >}}
-
- The result will be
++ <a href="{{ .RelPermalink }}">{{ .Language.Lang }}: {{ .LinkTitle }}{{ if .IsPage }} ({{ i18n "wordCount" . }}){{ end }}</a>
+ </li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
+The above can be put in a `partial` (i.e., inside `layouts/partials/`) and included in any template, whether a [single content page][contenttemplate] or the [homepage]. It will not print anything if there are no translations for a given page.
+
+The above also uses the [`i18n` function][i18func] described in the next section.
+
+### List all available languages
+
+`.AllTranslations` on a `Page` can be used to list all translations, including the page itself. On the home page it can be used to build a language navigator:
+
+{{< code file=layouts/partials/allLanguages.html >}}
+<ul>
+{{ range $.Site.Home.AllTranslations }}
+<li><a href="{{ .RelPermalink }}">{{ .Language.LanguageName }}</a></li>
+{{ end }}
+</ul>
+{{< /code >}}
+
+## Translation of strings
+
- ```text
- Home
- ```
-
- ### Query a flexible translation with variables
-
- Often you will want to use the page variables in the translation strings. To do so, pass the `.` context when calling `i18n`:
-
- ```go-html-template
- {{ i18n "wordCount" . }}
- ```
-
- The function will pass the `.` context to the `"wordCount"` id:
-
- {{< code-toggle file=i18n/en-US >}}
- [wordCount]
- other = "This article has {{ .WordCount }} words."
- {{< /code-toggle >}}
-
- Assume `.WordCount` in the context has value is 101. The result will be:
-
- ```text
- This article has 101 words.
- ```
-
- ### Query a singular/plural translation
-
- To enable pluralization when translating, pass a map with a numeric `.Count` property to the `i18n` function. The example below uses `.ReadingTime` variable which has a built-in `.Count` property.
-
- ```go-html-template
- {{ i18n "readingTime" .ReadingTime }}
- ```
-
- The function will read `.Count` from `.ReadingTime` and evaluate whether the number is singular (`one`) or plural (`other`). After that, it will pass to `readingTime` id in `i18n/en-US.toml` file:
-
- {{< code-toggle file=i18n/en-US >}}
- [readingTime]
- one = "One minute to read"
- other = "{{ .Count }} minutes to read"
- {{< /code-toggle >}}
-
- Assuming `.ReadingTime.Count` in the context has value is 525600. The result will be:
-
- ```text
- 525600 minutes to read
- ```
-
- If `.ReadingTime.Count` in the context has value is 1. The result is:
-
- ```text
- One minute to read
- ```
-
- In case you need to pass a custom data: (`(dict "Count" numeric_value_only)` is minimum requirement)
-
- ```go-html-template
- {{ i18n "readingTime" (dict "Count" 25 "FirstArgument" true "SecondArgument" false "Etc" "so on, so far") }}
- ```
++See the [`lang.Translate`] template function.
+
- If there is more than one language defined, the `LanguagePrefix` variable will equal `/en` (or whatever your `CurrentLanguage` is). If not enabled, it will be an empty string (and is therefore harmless for single-language Hugo websites).
++[`lang.Translate`]: /functions/lang/translate
+
+## Localization
+
+The following localization examples assume your site's primary language is English, with translations to French and German.
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'en'
+
+[languages]
+[languages.en]
+contentDir = 'content/en'
+languageName = 'English'
+weight = 1
+[languages.fr]
+contentDir = 'content/fr'
+languageName = 'Français'
+weight = 2
+[languages.de]
+contentDir = 'content/de'
+languageName = 'Deutsch'
+weight = 3
+
+{{< /code-toggle >}}
+
+### Dates
+
+With this front matter:
+
+{{< code-toggle >}}
+date = 2021-11-03T12:34:56+01:00
+{{< /code-toggle >}}
+
+And this template code:
+
+```go-html-template
+{{ .Date | time.Format ":date_full" }}
+```
+
+The rendered page displays:
+
+Language|Value
+:--|:--
+English|Wednesday, November 3, 2021
+Français|mercredi 3 novembre 2021
+Deutsch|Mittwoch, 3. November 2021
+
+See [`time.Format`] for details.
+
+### Currency
+
+With this template code:
+
+```go-html-template
+{{ 512.5032 | lang.FormatCurrency 2 "USD" }}
+```
+
+The rendered page displays:
+
+Language|Value
+:--|:--
+English|$512.50
+Français|512,50 $US
+Deutsch|512,50 $
+
+See [lang.FormatCurrency] and [lang.FormatAccounting] for details.
+
+### Numbers
+
+With this template code:
+
+```go-html-template
+{{ 512.5032 | lang.FormatNumber 2 }}
+```
+
+The rendered page displays:
+
+Language|Value
+:--|:--
+English|512.50
+Français|512,50
+Deutsch|512,50
+
+See [lang.FormatNumber] and [lang.FormatNumberCustom] for details.
+
+### Percentages
+
+With this template code:
+
+```go-html-template
+{{ 512.5032 | lang.FormatPercent 2 }}
+```
+
+The rendered page displays:
+
+Language|Value
+:--|:--
+English|512.50%
+Français|512,50 %
+Deutsch|512,50 %
+
+See [lang.FormatPercent] for details.
+
+## Menus
+
+Localization of menu entries depends on how you define them:
+
+- When you define menu entries [automatically] using the section pages menu, you must use translation tables to localize each entry.
+- When you define menu entries [in front matter], they are already localized based on the front matter itself. If the front matter values are insufficient, use translation tables to localize each entry.
+- When you define menu entries [in site configuration], you must create language-specific menu entries under each language key. If the names of the menu entries are insufficient, use translation tables to localize each entry.
+
+### Create language-specific menu entries
+
+#### Method 1 -- Use a single configuration file
+
+For a simple menu with a small number of entries, use a single configuration file. For example:
+
+{{< code-toggle file=hugo >}}
+[languages.de]
+languageCode = 'de-DE'
+languageName = 'Deutsch'
+weight = 1
+
+[[languages.de.menus.main]]
+name = 'Produkte'
+pageRef = '/products'
+weight = 10
+
+[[languages.de.menus.main]]
+name = 'Leistungen'
+pageRef = '/services'
+weight = 20
+
+[languages.en]
+languageCode = 'en-US'
+languageName = 'English'
+weight = 2
+
+[[languages.en.menus.main]]
+name = 'Products'
+pageRef = '/products'
+weight = 10
+
+[[languages.en.menus.main]]
+name = 'Services'
+pageRef = '/services'
+weight = 20
+{{< /code-toggle >}}
+
+#### Method 2 -- Use a configuration directory
+
+With a more complex menu structure, create a [configuration directory] and split the menu entries into multiple files, one file per language. For example:
+
+```text
+config/
+└── _default/
+ ├── menus.de.toml
+ ├── menus.en.toml
+ └── hugo.toml
+```
+
+{{< code-toggle file=config/_default/menus.de >}}
+[[main]]
+name = 'Produkte'
+pageRef = '/products'
+weight = 10
+[[main]]
+name = 'Leistungen'
+pageRef = '/services'
+weight = 20
+{{< /code-toggle >}}
+
+{{< code-toggle file=config/_default/menus.en >}}
+[[main]]
+name = 'Products'
+pageRef = '/products'
+weight = 10
+[[main]]
+name = 'Services'
+pageRef = '/services'
+weight = 20
+{{< /code-toggle >}}
+
+[configuration directory]: /getting-started/configuration/#configuration-directory
+
+### Use translation tables
+
+When rendering the text that appears in menu each entry, the [example menu template] does this:
+
+```go-html-template
+{{ or (T .Identifier) .Name | safeHTML }}
+```
+
+It queries the translation table for the current language using the menu entry's `identifier` and returns the translated string. If the translation table does not exist, or if the `identifier` key is not present in the translation table, it falls back to `name`.
+
+The `identifier` depends on how you define menu entries:
+
+- If you define the menu entry [automatically] using the section pages menu, the `identifier` is the page's `.Section`.
+- If you define the menu entry [in site configuration] or [in front matter], set the `identifier` property to the desired value.
+
+For example, if you define menu entries in site configuration:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+ identifier = 'products'
+ name = 'Products'
+ pageRef = '/products'
+ weight = 10
+[[menus.main]]
+ identifier = 'services'
+ name = 'Services'
+ pageRef = '/services'
+ weight = 20
+{{< / code-toggle >}}
+
+Create corresponding entries in the translation tables:
+
+{{< code-toggle file=i18n/de >}}
+products = 'Produkte'
+services = 'Leistungen'
+{{< / code-toggle >}}
+
+[example menu template]: /templates/menu-templates/#example
+[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
+
+## Missing translations
+
+If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown.
+
+While translating a Hugo website, it can be handy to have a visual indicator of missing translations. The [`enableMissingTranslationPlaceholders` configuration option][config] will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation.
+
+{{% note %}}
+Hugo will generate your website with these missing translation placeholders. It might not be suitable for production environments.
+{{% /note %}}
+
+For merging of content from other languages (i.e. missing content translations), see [lang.Merge].
+
+To track down missing translation strings, run Hugo with the `--printI18nWarnings` flag:
+
+```sh
+hugo --printI18nWarnings | grep i18n
+i18n|MISSING_TRANSLATION|en|wordCount
+```
+
+## Multilingual themes support
+
+To support Multilingual mode in your themes, some considerations must be taken for the URLs in the templates. If there is more than one language, URLs must meet the following criteria:
+
+* Come from the built-in `.Permalink` or `.RelPermalink`
+* Be constructed with the [`relLangURL`] or [`absLangURL`] template function, or be prefixed with `{{ .LanguagePrefix }}`
+
- [`abslangurl`]: /functions/urls/abslangurl
++If there is more than one language defined, the `LanguagePrefix` method will return `/en` (or whatever the current language is). If not enabled, it will be an empty string (and is therefore harmless for single-language Hugo websites).
+
+## Generate multilingual content with `hugo new content`
+
+If you organize content with translations in the same directory:
+
+```sh
+hugo new content post/test.en.md
+hugo new content post/test.de.md
+```
+
+If you organize content with translations in different directories:
+
+```sh
+hugo new content content/en/post/test.md
+hugo new content content/de/post/test.md
+```
+
- [i18func]: /functions/lang/translate
- [lang.FormatAccounting]: /functions/lang/formataccounting
- [lang.FormatCurrency]: /functions/lang/formatcurrency
- [lang.FormatNumber]: /functions/lang/formatnumber
- [lang.FormatNumberCustom]: /functions/lang/formatnumbercustom
- [lang.FormatPercent]: /functions/lang/formatpercent
++[`abslangurl`]: /functions/urls/abslangurl/
+[config]: /getting-started/configuration/
+[contenttemplate]: /templates/single-page-templates/
+[go-i18n-source]: https://github.com/nicksnyder/go-i18n
+[go-i18n]: https://github.com/nicksnyder/go-i18n
+[homepage]: /templates/homepage/
+[Hugo Multilingual Part 1: Content translation]: https://regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/
- [`rellangurl`]: /functions/urls/rellangurl
- [RFC 5646]: https://tools.ietf.org/html/rfc5646
++[i18func]: /functions/lang/translate/
++[lang.FormatAccounting]: /functions/lang/formataccounting/
++[lang.FormatCurrency]: /functions/lang/formatcurrency/
++[lang.FormatNumber]: /functions/lang/formatnumber/
++[lang.FormatNumberCustom]: /functions/lang/formatnumbercustom/
++[lang.FormatPercent]: /functions/lang/formatpercent/
+[lang.Merge]: /functions/lang/merge/
+[menus]: /content-management/menus/
+[OS environment]: /getting-started/configuration/#configure-with-environment-variables
- [`time.Format`]: /functions/time/format
++[`rellangurl`]: /functions/urls/rellangurl/
+[single page templates]: /templates/single-page-templates/
++[`time.Format`]: /functions/time/format/
--- /dev/null
- {{< imgproc "1-featured-content-bundles.png" "resize 300x" >}}
- The illustration shows three bundles. Note that the home page bundle cannot contain other content pages, although other files (images etc.) are allowed.
- {{< /imgproc >}}
+---
+title: Content organization
+linkTitle: Organization
+description: Hugo assumes that the same structure that works to organize your source content is used to organize the rendered site.
+categories: [content management,fundamentals]
+keywords: [sections,content,organization,bundle,resources]
+menu:
+ docs:
+ parent: content-management
+ weight: 20
+weight: 20
+toc: true
+aliases: [/content/sections/]
+---
+
+## Page bundles
+
+Hugo `0.32` announced page-relative images and other resources packaged into `Page Bundles`.
+
+These terms are connected, and you also need to read about [Page Resources](/content-management/page-resources) and [Image Processing](/content-management/image-processing) to get the full picture.
+
- {{% note %}}
- The bundle documentation is a **work in progress**. We will publish more comprehensive docs about this soon.
- {{% /note %}}
++```text
++content/
++├── blog/
++│ ├── hugo-is-cool/
++│ │ ├── images/
++│ │ │ ├── funnier-cat.jpg
++│ │ │ └── funny-cat.jpg
++│ │ ├── cats-info.md
++│ │ └── index.md
++│ ├── posts/
++│ │ ├── post1.md
++│ │ └── post2.md
++│ ├── 1-landscape.jpg
++│ ├── 2-sunset.jpg
++│ ├── _index.md
++│ ├── content-1.md
++│ └── content-2.md
++├── 1-logo.png
++└── _index.md
++```
+
- The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseURL = "https://example.org"` in your [site's configuration file][config].
++The file tree above shows three bundles. Note that the home page bundle cannot contain other content pages, although other files (images etc.) are allowed.
+
+## Organization of content source
+
+In Hugo, your content should be organized in a manner that reflects the rendered website.
+
+While Hugo supports content nested at any level, the top levels (i.e. `content/<DIRECTORIES>`) are special in Hugo and are considered the content type used to determine layouts etc. To read more about sections, including how to nest them, see [sections].
+
+Without any additional configuration, the following will automatically work:
+
+```txt
+.
+└── content
+ └── about
+ | └── index.md // <- https://example.org/about/
+ ├── posts
+ | ├── firstpost.md // <- https://example.org/posts/firstpost/
+ | ├── happy
+ | | └── ness.md // <- https://example.org/posts/happy/ness/
+ | └── secondpost.md // <- https://example.org/posts/secondpost/
+ └── quote
+ ├── first.md // <- https://example.org/quote/first/
+ └── second.md // <- https://example.org/quote/second/
+```
+
+## Path breakdown in Hugo
+
- . filepath
++The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseURL = "https://example.org/"` in your [site's configuration file][config].
+
+### Index pages: `_index.md`
+
+`_index.md` has a special role in Hugo. It allows you to add front matter and content to your [list templates][lists]. These templates include those for [section templates], [taxonomy templates], [taxonomy terms templates], and your [homepage template].
+
+{{% note %}}
+**Tip:** You can get a reference to the content and metadata in `_index.md` using the [`.Site.GetPage` function](/methods/page/getpage).
+{{% /note %}}
+
+You can create one `_index.md` for your homepage and one in each of your content sections, taxonomies, and taxonomy terms. The following shows typical placement of an `_index.md` that would contain content and front matter for a `posts` section list page on a Hugo website:
+
+```txt
+. url
+. ⊢--^-⊣
+. path slug
+. ⊢--^-⊣⊢---^---⊣
- [getpage]: /methods/page/getpage
++. file path
+. ⊢------^------⊣
+content/posts/_index.md
+```
+
+At build, this will output to the following destination with the associated values:
+
+```txt
+
+ url ("/posts/")
+ ⊢-^-⊣
+ baseurl section ("posts")
+⊢--------^---------⊣⊢-^-⊣
+ permalink
+⊢----------^-------------⊣
+https://example.org/posts/index.html
+```
+
+The [sections] can be nested as deeply as you want. The important thing to understand is that to make the section tree fully navigational, at least the lower-most section must include a content file. (i.e. `_index.md`).
+
+### Single pages in sections
+
+Single content files in each of your sections will be rendered as [single page templates][singles]. Here is an example of a single `post` within `posts`:
+
+```txt
+ path ("posts/my-first-hugo-post.md")
+. ⊢-----------^------------⊣
+. section slug
+. ⊢-^-⊣⊢--------^----------⊣
+content/posts/my-first-hugo-post.md
+```
+
+When Hugo builds your site, the content will be output to the following destination:
+
+```txt
+
+ url ("/posts/my-first-hugo-post/")
+ ⊢------------^----------⊣
+ baseurl section slug
+⊢--------^--------⊣⊢-^--⊣⊢-------^---------⊣
+ permalink
+⊢--------------------^---------------------⊣
+https://example.org/posts/my-first-hugo-post/index.html
+```
+
+## Paths explained
+
+The following concepts provide more insight into the relationship between your project's organization and the default Hugo behavior when building output for the website.
+
+### `section`
+
+A default content type is determined by the section in which a content item is stored. `section` is determined by the location within the project's `content` directory. `section` *cannot* be specified or overridden in front matter.
+
+### `slug`
+
+The `slug` is the last segment of the URL path, defined by the file name and optionally overridden by a `slug` value in front matter. See [URL Management](/content-management/urls/#slug) for details.
+
+### `path`
+
+A content's `path` is determined by the section's path to the file. The file `path`
+
+* is based on the path to the content's location AND
+* does not include the slug
+
+### `url`
+
+The `url` is the entire URL path, defined by the file path and optionally overridden by a `url` value in front matter. See [URL Management](/content-management/urls/#slug) for details.
+
+[config]: /getting-started/configuration/
+[formats]: /content-management/formats/
+[front matter]: /content-management/front-matter/
++[getpage]: /methods/page/getpage/
+[homepage template]: /templates/homepage/
+[homepage]: /templates/homepage/
+[lists]: /templates/lists/
+[pretty]: /content-management/urls/#appearance
+[section templates]: /templates/section-templates/
+[sections]: /content-management/sections/
+[singles]: /templates/single-page-templates/
+[taxonomy templates]: /templates/taxonomy-templates/
+[taxonomy terms templates]: /templates/taxonomy-templates/
+[types]: /content-management/types/
+[urls]: /content-management/urls/
--- /dev/null
- description: Content organization using Page Bundles
+---
+title: Page bundles
- Page Bundles are a way to group [Page Resources](/content-management/page-resources/).
++description: Use page bundles to logically associate one or more resources with content.
+categories: [content management]
+keywords: [page,bundle,leaf,branch]
+menu :
+ docs:
+ parent: content-management
+ weight: 30
+weight: 30
+toc: true
+---
+
- A Page Bundle can be one of:
++## Introduction
+
- - Leaf Bundle (leaf means it has no children)
- - Branch Bundle (home page, section, taxonomy terms, taxonomy list)
++A page bundle is a directory that encapsulates both content and associated resources.
+
- | | 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 |
++By way of example, this site has an "about" page and a "privacy" page:
+
- ## Leaf bundles
++```text
++content/
++├── about/
++│ ├── index.md
++│ └── welcome.jpg
++└── privacy.md
++```
+
- A _Leaf Bundle_ is a directory at any hierarchy within the `content/`
- directory, that contains an **`index.md`** file.
++The "about" page is a page bundle. It logically associates a resource with content by bundling them together. Resources within a page bundle are [page resources], accessible with the [`Resources`] method on the `Page` object.
++
++Page bundles are either _leaf bundles_ or _branch bundles_.
++
++leaf bundle
++: A _leaf bundle_ is a directory that contains an index.md file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants.
++
++branch bundle
++: A _branch bundle_ is a directory that contains an _index.md file and zero or more resources. 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.
++
++{{% note %}}
++In the definitions above and the examples below, the extension of the index file depends on the [content format]. For example, use index.md for Markdown content, index.html for HTML content, index.adoc for AsciiDoc content, etc.
++
++[content format]: /getting-started/glossary/#content-format
++{{% /note %}}
+
- ### Examples of leaf bundle organization {#examples-of-leaf-bundle-organization}
++## Comparison
+
- │ ├── index.md
++Page bundle characteristics vary by bundle type.
++
++| | Leaf bundle | Branch bundle |
++|---------------------|---------------------------------------------------------|---------------------------------------------------------|
++| Index file | index.md | _index.md |
++| Example | content/about/index.md | content/posts/_index.md |
++| [Page kinds] | `page` | `home`, `section`, `taxonomy`, or `term` |
++| Layout type | [single] | [list] |
++| Descendant pages | None | Zero or more |
++| Resource location | Adjacent to the index file or in a nested subdirectory | Same as a leaf bundles, but excludes descendant bundles |
++| [Resource types] | `page`, `image`, `video`, etc. | all but `page` |
++
++Files with [resource type] `page` include content written in Markdown, HTML, AsciiDoc, Pandoc, reStructuredText, and Emacs Org Mode. In a leaf bundle, excluding the index file, these files are only accessible as page resources. In a branch bundle, these files are only accessible as content pages.
++
++## Leaf bundles
++
++A _leaf bundle_ is a directory that contains an index.md file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants.
+
+```text
+content/
+├── about
- │ │ ├── content1.md
- │ │ ├── content2.md
- │ │ ├── image1.jpg
- │ │ ├── image2.png
++│ └── index.md
+├── posts
+│ ├── my-post
- │
++│ │ ├── content-1.md
++│ │ ├── content-2.md
++│ │ ├── image-1.jpg
++│ │ ├── image-2.png
+│ │ └── index.md
+│ └── my-other-post
+│ └── index.md
- ├── ..
+└── another-section
- ├── ..
++ ├── foo.md
+ └── not-a-leaf-bundle
- In the above example `content/` directory, there are four leaf
- bundles:
++ ├── bar.md
+ └── another-leaf-bundle
+ └── index.md
+```
+
- : This leaf bundle is at the root level (directly under
- `content` directory) and has only the `index.md`.
++There are four leaf bundles in the example above:
+
+about
- : This leaf bundle has the `index.md`, two other content
- Markdown files and two image files.
++: This leaf bundle does not contain any page resources.
+
+my-post
- - image1, image2:
- These images are page resources of `my-post`
- and only available in `my-post/index.md` resources.
++: This leaf bundle contains an index file, two resources of [resource type] `page`, and two resources of resource type `image`.
+
- - content1, content2:
- These content files are page resources of `my-post`
- and only available in `my-post/index.md` resources.
- They will **not** be rendered as individual pages.
++- content-1, content-2
+
- : This leaf bundle has only the `index.md`.
++ These are resources of resource type `page`, accessible via the [`Resources`] method on the `Page` object. Hugo will not render these as individual pages.
++
++- image-1, image-2
++
++ These are resources of resource type `image`, accessible via the `Resources` method on the `Page` object
+
+my-other-post
- : This leaf bundle is nested under couple of
- directories. This bundle also has only the `index.md`.
++: This leaf bundle does not contain any page resources.
+
+another-leaf-bundle
- The hierarchy depth at which a leaf bundle is created does not matter,
- as long as it is not inside another **leaf** bundle.
++: This leaf bundle does not contain any page resources.
+
+{{% note %}}
- ### Headless bundle
-
- A headless bundle is a bundle that is configured to not get published
- anywhere:
-
- - It will have no `Permalink` and no rendered HTML in `public/`.
- - It will not be part of `.Site.RegularPages`, etc.
-
- But you can get it by `.Site.GetPage`. Here is an example:
-
- ```go-html-template
- {{ $headless := .Site.GetPage "/some-headless-bundle" }}
- {{ $reusablePages := $headless.Resources.Match "author*" }}
- <h2>Authors</h2>
- {{ range $reusablePages }}
- <h3>{{ .Title }}</h3>
- {{ .Content }}
- {{ end }}
- ```
-
- _In this example, we are assuming the `some-headless-bundle` to be a headless
- bundle containing one or more **page** resources whose `.Name` matches
- `"author*"`._
-
- Explanation of the above example:
-
- 1. Get the `some-headless-bundle` Page "object".
- 2. Collect a _slice_ of resources in this _Page Bundle_ that matches
- `"author*"` using `.Resources.Match`.
- 3. Loop through that _slice_ of nested pages, and output their `.Title` and
- `.Content`.
-
- ---
-
- A leaf bundle can be made headless by adding below in the front matter
- (in the `index.md`):
-
- {{< code-toggle file=content/headless/index.md fm=true >}}
- headless = true
- {{< /code-toggle >}}
-
- There are many use cases of such headless page bundles:
-
- - Shared media galleries
- - Reusable page content "snippets"
-
++Create leaf bundles at any depth within the content directory, but a leaf bundle may not contain another bundle. Leaf bundles do not have descendants.
+{{% /note %}}
+
- A _Branch Bundle_ is any directory at any hierarchy within the
- `content/` directory, that contains at least an **`_index.md`** file.
-
- This `_index.md` can also be directly under the `content/` directory.
-
- {{% note %}}
- Here `md` (markdown) is used just as an example. You can use any file
- type as a content resource as long as it is a content type recognized by Hugo.
- {{% /note %}}
-
- ### Examples of branch bundle organization
+## Branch bundles
+
- ├── branch-bundle-1
- │ ├── branch-content1.md
- │ ├── branch-content2.md
- │ ├── image1.jpg
- │ ├── image2.png
++A _branch bundle_ is a directory that contains an _index.md file and zero or more resources. 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.
+
+```text
+content/
- └── branch-bundle-2
- ├── _index.md
- └── a-leaf-bundle
- └── index.md
++├── branch-bundle-1/
++│ ├── _index.md
++│ ├── content-1.md
++│ ├── content-2.md
++│ ├── image-1.jpg
++│ └── image-2.png
++├── branch-bundle-2/
++│ ├── a-leaf-bundle/
++│ │ └── index.md
+│ └── _index.md
- In the above example `content/` directory, there are two branch
- bundles (and a leaf bundle):
++└── _index.md
+```
+
- : This branch bundle has the `_index.md`, two
- other content Markdown files and two image files.
++There are three branch bundles in the example above:
++
++home page
++: This branch bundle contains an index file, two descendant branch bundles, and no resources.
+
+branch-bundle-1
- : This branch bundle has the `_index.md` and a
- nested leaf bundle.
++: This branch bundle contains an index file, two resources of [resource type] `page`, and two resources of resource type `image`.
+
+branch-bundle-2
- The hierarchy depth at which a branch bundle is created does not
- matter.
++: This branch bundle contains an index file and a leaf bundle.
+
+{{% note %}}
- [^fn:1]: The `.md` extension is just an example. The extension can be `.html`, `.json` or any valid MIME type.
++Create branch bundles at any depth within the content directory, but a leaf bundle may not contain another bundle. Leaf bundles do not have descendants.
+{{% /note %}}
+
++
++## Headless bundles
++
++Use [build options] in front matter to create an unpublished leaf or branch bundle whose content and resources you can include in other pages.
++
++[`Resources`]: /methods/page/resources/
++[build options]: content-management/build-options/
++[list]: /templates/lists/
++[page kinds]: /getting-started/glossary/#page-kind
++[page resources]: /content-management/page-resources/
++[resource type]: /getting-started/glossary/#resource-type
++[resource types]: /getting-started/glossary/#resource-type
++[single]: /templates/single-page-templates/
--- /dev/null
- ## Page resources metadata
+---
+title: Page resources
+description: Page resources -- images, other pages, documents, etc. -- have page-relative URLs and their own metadata.
+categories: [content management]
+keywords: [bundle,content,resources]
+menu:
+ docs:
+ parent: content-management
+ weight: 80
+weight: 80
+toc: true
+---
++
+Page resources are only accessible from [page bundles](/content-management/page-bundles), those directories with `index.md` or
+`_index.md` files at their root. Page resources are only available to the
+page with which they are bundled.
+
+In this example, `first-post` is a page bundle with access to 10 page resources including audio, data, documents, images, and video. Although `second-post` is also a page bundle, it has no page resources and is unable to directly access the page resources associated with `first-post`.
+
+```text
+content
+└── post
+ ├── first-post
+ │ ├── images
+ │ │ ├── a.jpg
+ │ │ ├── b.jpg
+ │ │ └── c.jpg
+ │ ├── index.md (root of page bundle)
+ │ ├── latest.html
+ │ ├── manual.json
+ │ ├── notice.md
+ │ ├── office.mp3
+ │ ├── pocket.mp4
+ │ ├── rating.pdf
+ │ └── safety.txt
+ └── second-post
+ └── index.md (root of page bundle)
+```
+
+## Properties
+
+ResourceType
+: The main type of the resource's [Media Type](/templates/output-formats/#media-types). For example, a file of MIME type `image/jpeg` has the ResourceType `image`. A `Page` will have `ResourceType` with value `page`.
+
+Name
+: Default value is the file name (relative to the owning page). Can be set in front matter.
+
+Title
+: Default value is the same as `.Name`. Can be set in front matter.
+
+Permalink
+: The absolute URL to the resource. Resources of type `page` will have no value.
+
+RelPermalink
+: The relative URL to the resource. Resources of type `page` will have no value.
+
+Content
+: The content of the resource itself. For most resources, this returns a string
+with the contents of the file. Use this to create inline resources.
+
+```go-html-template
+{{ with .Resources.GetMatch "script.js" }}
+ <script>{{ .Content | safeJS }}</script>
+{{ end }}
+
+{{ with .Resources.GetMatch "style.css" }}
+ <style>{{ .Content | safeCSS }}</style>
+{{ end }}
+
+{{ with .Resources.GetMatch "img.png" }}
+ <img src="data:{{ .MediaType.Type }};base64,{{ .Content | base64Encode }}">
+{{ end }}
+```
+
+MediaType.Type
+: The media type (formerly known as a MIME type) of the resource (e.g., `image/jpeg`).
+
+MediaType.MainType
+: The main type of the resource's media type (e.g., `image`).
+
+MediaType.SubType
+: The subtype of the resource's type (e.g., `jpeg`). This may or may not correspond to the file suffix.
+
+MediaType.Suffixes
+: A slice of possible file suffixes for the resource's media type (e.g., `[jpg jpeg jpe jif jfif]`).
+
+## Methods
+
+ByType
+: Returns the page resources of the given type.
+
+```go-html-template
+{{ .Resources.ByType "image" }}
+```
+Match
+: Returns all the page resources (as a slice) whose `Name` matches the given Glob pattern ([examples](https://github.com/gobwas/glob/blob/master/readme.md)). The matching is case-insensitive.
+
+```go-html-template
+{{ .Resources.Match "images/*" }}
+```
+
+GetMatch
+: Same as `Match` but will return the first match.
+
+### Pattern matching
+
+```go
+// Using Match/GetMatch to find this images/sunset.jpg ?
+.Resources.Match "images/sun*" ✅
+.Resources.Match "**/sunset.jpg" ✅
+.Resources.Match "images/*.jpg" ✅
+.Resources.Match "**.jpg" ✅
+.Resources.Match "*" 🚫
+.Resources.Match "sunset.jpg" 🚫
+.Resources.Match "*sunset.jpg" 🚫
+```
+
- : A map of custom key/values.
++## Metadata
+
+The page resources' metadata is managed from the corresponding page's front matter with an array/table parameter named `resources`. You can batch assign values using [wildcards](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm).
+
+{{% note %}}
+Resources of type `page` get `Title` etc. from their own front matter.
+{{% /note %}}
+
+name
+: Sets the value returned in `Name`.
+
+{{% note %}}
+The methods `Match`, `Get` and `GetMatch` use `Name` to match the resources.
+{{% /note %}}
+
+title
+: Sets the value returned in `Title`
+
+params
++: A map of custom key-value pairs.
+
+### Resources metadata example
+
+{{< code-toggle >}}
+title: Application
+date : 2018-01-25
+resources :
+- src : "images/sunset.jpg"
+ name : "header"
+- src : "documents/photo_specs.pdf"
+ title : "Photo Specifications"
+ params:
+ icon : "photo"
+- src : "documents/guide.pdf"
+ title : "Instruction Guide"
+- src : "documents/checklist.pdf"
+ title : "Document Checklist"
+- src : "documents/payment.docx"
+ title : "Proof of Payment"
+- src : "**.pdf"
+ name : "pdf-file-:counter"
+ params :
+ icon : "pdf"
+- src : "**.docx"
+ params :
+ icon : "word"
+{{</ code-toggle >}}
+
+From the example above:
+
+- `sunset.jpg` will receive a new `Name` and can now be found with `.GetMatch "header"`.
+- `documents/photo_specs.pdf` will get the `photo` icon.
+- `documents/checklist.pdf`, `documents/guide.pdf` and `documents/payment.docx` will get `Title` as set by `title`.
+- Every `PDF` in the bundle except `documents/photo_specs.pdf` will get the `pdf` icon.
+- All `PDF` files will get a new `Name`. The `name` parameter contains a special placeholder [`:counter`](#the-counter-placeholder-in-name-and-title), so the `Name` will be `pdf-file-1`, `pdf-file-2`, `pdf-file-3`.
+- Every docx in the bundle will receive the `word` icon.
+
+{{% note %}}
+The __order matters__ --- Only the **first set** values of the `title`, `name` and `params`-**keys** will be used. Consecutive parameters will be set only for the ones not already set. In the above example, `.Params.icon` is first set to `"photo"` in `src = "documents/photo_specs.pdf"`. So that would not get overridden to `"pdf"` by the later set `src = "**.pdf"` rule.
+{{% /note %}}
+
+### The `:counter` placeholder in `name` and `title`
+
+The `:counter` is a special placeholder recognized in `name` and `title` parameters `resources`.
+
+The counter starts at 1 the first time they are used in either `name` or `title`.
+
+For example, if a bundle has the resources `photo_specs.pdf`, `other_specs.pdf`, `guide.pdf` and `checklist.pdf`, and the front matter has specified the `resources` as:
+
+{{< code-toggle file=content/inspections/engine/index.md fm=true >}}
+title = 'Engine inspections'
+[[resources]]
+ src = "*specs.pdf"
+ title = "Specification #:counter"
+[[resources]]
+ src = "**.pdf"
+ name = "pdf-file-:counter"
+{{</ code-toggle >}}
+
+the `Name` and `Title` will be assigned to the resource files as follows:
+
+| Resource file | `Name` | `Title` |
+|-------------------|-------------------|-----------------------|
+| checklist.pdf | `"pdf-file-1.pdf` | `"checklist.pdf"` |
+| guide.pdf | `"pdf-file-2.pdf` | `"guide.pdf"` |
+| other\_specs.pdf | `"pdf-file-3.pdf` | `"Specification #1"` |
+| photo\_specs.pdf | `"pdf-file-4.pdf` | `"Specification #2"` |
++
++## Multilingual
++
++{{< new-in 0.123.0 >}}
++
++By default, with a multilingual single-host site, Hugo does not duplicate shared page resources when building the site.
++
++{{% note %}}
++This behavior is limited to Markdown content. Shared page resources for other [content formats] are copied into each language bundle.
++
++[content formats]: /content-management/formats/
++{{% /note %}}
++
++Consider this site configuration:
++
++{{< code-toggle file=hugo >}}
++defaultContentLanguage = 'de'
++defaultContentLanguageInSubdir = true
++
++[languages.de]
++languageCode = 'de-DE'
++languageName = 'Deutsch'
++weight = 1
++
++[languages.en]
++languageCode = 'en-US'
++languageName = 'English'
++weight = 2
++{{< /code-toggle >}}
++
++And this content:
++
++```text
++content/
++└── my-bundle/
++ ├── a.jpg <-- shared page resource
++ ├── b.jpg <-- shared page resource
++ ├── c.de.jpg
++ ├── c.en.jpg
++ ├── index.de.md
++ └── index.en.md
++```
++
++With v0.122.0 and earlier, Hugo duplicated the shared page resources, creating copies for each language:
++
++```text
++public/
++├── de/
++│ ├── my-bundle/
++│ │ ├── a.jpg <-- shared page resource
++│ │ ├── b.jpg <-- shared page resource
++│ │ ├── c.de.jpg
++│ │ └── index.html
++│ └── index.html
++├── en/
++│ ├── my-bundle/
++│ │ ├── a.jpg <-- shared page resource (duplicate)
++│ │ ├── b.jpg <-- shared page resource (duplicate)
++│ │ ├── c.en.jpg
++│ │ └── index.html
++│ └── index.html
++└── index.html
++
++```
++
++With v0.123.0 and later, Hugo places the shared resources in the page bundle for the default content language:
++
++```text
++public/
++├── de/
++│ ├── my-bundle/
++│ │ ├── a.jpg <-- shared page resource
++│ │ ├── b.jpg <-- shared page resource
++│ │ ├── c.de.jpg
++│ │ └── index.html
++│ └── index.html
++├── en/
++│ ├── my-bundle/
++│ │ ├── c.en.jpg
++│ │ └── index.html
++│ └── index.html
++└── index.html
++```
++
++This approach reduces build times, storage requirements, bandwidth consumption, and deployment times, ultimately reducing cost.
++
++{{% note %}}
++To resolve Markdown link and image destinations to the correct location, you must use link and image render hooks that capture the page resource with the [`Resources.Get`] method, and then invoke its [`RelPermalink`] method.
++
++By default, with multilingual single-host sites, Hugo enables its [embedded link render hook] and [embedded image render hook] to resolve Markdown link and image destinations.
++
++You may override the embedded render hooks as needed, provided they capture the resource as described above.
++
++[embedded link render hook]: /render-hooks/links/#default
++[embedded image render hook]: /render-hooks/images/#default
++[`Resources.Get`]: /methods/page/resources/#get
++[`RelPermalink`]: /methods/resource/relpermalink/
++{{% /note %}}
++
++Although duplicating shared page resources is inefficient, you can enable this feature in your site configuration if desired:
++
++{{< code-toggle file=hugo >}}
++[markup.goldmark]
++duplicateResourceFiles = true
++{{< /code-toggle >}}
--- /dev/null
- : (`int`) A percentage (0-100) used to remove common keywords from the index. As an example, setting this to `50` will remove all keywords that are used in more than 50% of the documents in the index. Default is `0`.
+---
+title: Related content
+description: List related content in "See Also" sections.
+categories: [content management]
+keywords: [content]
+menu:
+ docs:
+ parent: content-management
+ weight: 110
+weight: 110
+toc: true
+aliases: [/content/related/,/related/]
+---
+
+Hugo uses a set of factors to identify a page's related content based on front matter parameters. This can be tuned to the desired set of indices and parameters or left to Hugo's default [Related Content configuration](#configure-related-content).
+
+## List related content
+
+To list up to 5 related pages (which share the same _date_ or _keyword_ parameters) is as simple as including something similar to this partial in your single page template:
+
+{{< code file=layouts/partials/related.html >}}
+{{ $related := .Site.RegularPages.Related . | first 5 }}
+{{ with $related }}
+<h3>See Also</h3>
+<ul>
+ {{ range . }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
+The `Related` method takes one argument which may be a `Page` or a options map. The options map have these options:
+
+indices
+: (`slice`) The indices to search within.
+
+document
+: (`page`) The page for which to find related content. Required when specifying an options map.
+
+namedSlices
+: (`slice`) The keywords to search for, expressed as a slice of `KeyValues` using the [`keyVals`] function.
+
+fragments
+: (`slice`) A list of special keywords that is used for indices configured as type "fragments". This will match the [fragment] identifiers of the documents.
+
+[fragment]: /getting-started/glossary/#fragment
+[`keyVals`]: /functions/collections/keyvals/
+
+A fictional example using all of the above options:
+
+```go-html-template
+{{ $page := . }}
+{{ $opts := dict
+ "indices" (slice "tags" "keywords")
+ "document" $page
+ "namedSlices" (slice (keyVals "tags" "hugo" "rocks") (keyVals "date" $page.Date))
+ "fragments" (slice "heading-1" "heading-2")
+}}
+```
+
+{{% note %}}
+We improved and simplified this feature in Hugo 0.111.0. Before this we had 3 different methods: `Related`, `RelatedTo` and `RelatedIndices`. Now we have only one method: `Related`. The old methods are still available but deprecated. Also see [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation of more advanced usage of this feature.
+{{% /note %}}
+
+## Index content headings in related content
+
+{{< new-in 0.111.0 >}}
+
+Hugo can index the headings in your content and use this to find related content. You can enable this by adding a index of type `fragments` to your `related` configuration:
+
+{{< code-toggle file=hugo >}}
+[related]
+threshold = 20
+includeNewer = true
+toLower = false
+[[related.indices]]
+name = "fragmentrefs"
+type = "fragments"
+applyFilter = true
+weight = 80
+{{< /code-toggle >}}
+
+* The `name` maps to a optional front matter slice attribute that can be used to link from the page level down to the fragment/heading level.
+* If `applyFilter`is enabled, the `.HeadingsFiltered` on each page in the result will reflect the filtered headings. This is useful if you want to show the headings in the related content listing:
+
+```go-html-template
+{{ $related := .Site.RegularPages.Related . | first 5 }}
+{{ with $related }}
+ <h2>See Also</h2>
+ <ul>
+ {{ range $i, $p := . }}
+ <li>
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+ {{ with .HeadingsFiltered }}
+ <ul>
+ {{ range . }}
+ {{ $link := printf "%s#%s" $p.RelPermalink .ID | safeURL }}
+ <li>
+ <a href="{{ $link }}">{{ .Title }}</a>
+ </li>
+ {{ end }}
+ </ul>
+ {{ end }}
+ </li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+## Configure related content
+
+Hugo provides a sensible default configuration of Related Content, but you can fine-tune this in your configuration, on the global or language level if needed.
+
+### Default configuration
+
+Without any `related` configuration set on the project, Hugo's Related Content methods will use the following.
+
+{{< code-toggle config=related />}}
+
+Custom configuration should be set using the same syntax.
+
+{{% note %}}
+If you add a `related` configuration section, you need to add a complete configuration. It is not possible to just set, say, `includeNewer` and use the rest from the Hugo defaults.
+{{% /note %}}
+
+### Top level configuration options
+
+threshold
+: (`int`) A value between 0-100. Lower value will give more, but maybe not so relevant, matches.
+
+includeNewer
+: (`bool`) Set to `true` to include **pages newer than the current page** in the related content listing. This will mean that the output for older posts may change as new related content gets added.
+
+toLower
+: (`bool`) Set to `true` to lower case keywords in both the indexes and the queries. This may give more accurate results at a slight performance penalty. Note that this can also be set per index.
+
+### Configuration options per index
+
+name
+: (`string`) The index name. This value maps directly to a page parameter. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects.
+
+type {{< new-in 0.111.0 >}}
+: (`string`) One of `basic`(default) or `fragments`.
+
+applyFilter {{< new-in 0.111.0 >}}
+: (`string`) Apply a `type` specific filter to the result of a search. This is currently only used for the `fragments` type.
+
+weight
+: (`int`) An integer weight that indicates _how important_ this parameter is relative to the other parameters. It can be `0`, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best.
+
+cardinalityThreshold {{< new-in 0.111.0 >}}
++: (`int`) If between 1 and 100, this is a percentage. All keywords that are used in more than this percentage of documents are removed. For example, setting this to `60` will remove all keywords that are used in more than 60% of the documents in the index. If `0`, no keyword is removed from the index. Default is `0`.
+
+pattern
+: (`string`) This is currently only relevant for dates. When listing related content, we may want to list content that is also close in time. Setting "2006" (default value for date indexes) as the pattern for a date index will add weight to pages published in the same year. For busier blogs, "200601" (year and month) may be a better default.
+
+toLower
+: (`bool`) See above.
+
+## Performance considerations
+
+**Fast is Hugo's middle name** and we would not have released this feature had it not been blistering fast.
+
+This feature has been in the back log and requested by many for a long time. The development got this recent kick start from this Twitter thread:
+
+{{< tweet user="scott_lowe" id="898398437527363585" >}}
+
+Scott S. Lowe removed the "Related Content" section built using the `intersect` template function on tags, and the build time dropped from 30 seconds to less than 2 seconds on his 1700 content page sized blog.
+
+He should now be able to add an improved version of that "Related Content" section without giving up the fast live-reloads. But it's worth noting that:
+
+* If you don't use any of the `Related` methods, you will not use the Relate Content feature, and performance will be the same as before.
+* Calling `.RegularPages.Related` etc. will create one inverted index, also sometimes named posting list, that will be reused for any lookups in that same page collection. Doing that in addition to, as an example, calling `.Pages.Related` will work as expected, but will create one additional inverted index. This should still be very fast, but worth having in mind, especially for bigger sites.
+
+{{% note %}}
+We currently do not index **Page content**. We thought we would release something that will make most people happy before we start solving [Sherlock's last case](https://github.com/joearms/sherlock).
+{{% /note %}}
--- /dev/null
- 1. The list page for the products section, by default, includes product-1 and product-2, but not their descendant pages. To include descendant pages, use the `.RegularPagesRecursive` collection instead of the `.Pages` collection in the list template. See [details](/variables/page/#page-collections).
+---
+title: Sections
+description: Organize content into sections.
+
+categories: [content management]
+keywords: [lists,sections,content types,organization]
+menu:
+ docs:
+ parent: content-management
+ weight: 120
+weight: 120
+toc: true
+aliases: [/content/sections/]
+---
+
+## Overview
+
+A section is a top-level content directory, or any content directory with an _index.md file. A content directory with an _index.md file is also known as a [branch bundle](/getting-started/glossary/#branch-bundle). Section templates receive one or more page [collections](/getting-started/glossary/#collection) in [context](/getting-started/glossary/#context).
+
+{{% note %}}
+Although top-level directories without _index.md files are sections, we recommend creating _index.md files in _all_ sections.
+{{% /note %}}
+
+A typical site consists of one or more sections. For example:
+
+```text
+content/
+├── articles/ <-- section (top-level directory)
+│ ├── 2022/
+│ │ ├── article-1/
+│ │ │ ├── cover.jpg
+│ │ │ └── index.md
+│ │ └── article-2.md
+│ └── 2023/
+│ ├── article-3.md
+│ └── article-4.md
+├── products/ <-- section (top-level directory)
+│ ├── product-1/ <-- section (has _index.md file)
+│ │ ├── benefits/ <-- section (has _index.md file)
+│ │ │ ├── _index.md
+│ │ │ ├── benefit-1.md
+│ │ │ └── benefit-2.md
+│ │ ├── features/ <-- section (has _index.md file)
+│ │ │ ├── _index.md
+│ │ │ ├── feature-1.md
+│ │ │ └── feature-2.md
+│ │ └── _index.md
+│ └── product-2/ <-- section (has _index.md file)
+│ ├── benefits/ <-- section (has _index.md file)
+│ │ ├── _index.md
+│ │ ├── benefit-1.md
+│ │ └── benefit-2.md
+│ ├── features/ <-- section (has _index.md file)
+│ │ ├── _index.md
+│ │ ├── feature-1.md
+│ │ └── feature-2.md
+│ └── _index.md
+├── _index.md
+└── about.md
+```
+
+The example above has two top-level sections: articles and products. None of the directories under articles are sections, while all of the directories under products are sections. A section within a section is a known as a nested section or subsection.
+
+## Explanation
+
+Sections and non-sections behave differently.
+
+||Sections|Non-sections
+:--|:-:|:-:
+Directory names become URL segments|:heavy_check_mark:|:heavy_check_mark:
+Have logical ancestors and descendants|:heavy_check_mark:|:x:
+Have list pages|:heavy_check_mark:|:x:
+
+With the file structure from the [example above](#overview):
+
+1. The list page for the articles section includes all articles, regardless of directory structure; none of the subdirectories are sections.
+
+1. The articles/2022 and articles/2023 directories do not have list pages; they are not sections.
+
++1. The list page for the products section, by default, includes product-1 and product-2, but not their descendant pages. To include descendant pages, use the `RegularPagesRecursive` method instead of the `Pages` method in the list template.
++
++[`Pages`]: /methods/page/pages/
++[`RegularPagesRecursive`]: /methods/page/regularpagesrecursive/
+
+1. All directories in the products section have list pages; each directory is a section.
+
+## Template selection
+
+Hugo has a defined [lookup order] to determine which template to use when rendering a page. The [lookup rules] consider the top-level section name; subsection names are not considered when selecting a template.
+
+With the file structure from the [example above](#overview):
+
+Content directory|List page template
+:--|:--
+content/products|layouts/products/list.html
+content/products/product-1|layouts/products/list.html
+content/products/product-1/benefits|layouts/products/list.html
+
+Content directory|Single page template
+:--|:--
+content/products|layouts/products/single.html
+content/products/product-1|layouts/products/single.html
+content/products/product-1/benefits|layouts/products/single.html
+
+If you need to use a different template for a subsection, specify `type` and/or `layout` in front matter.
+
+[lookup rules]: /templates/lookup-order/#lookup-rules
+[lookup order]: /templates/lookup-order/
+
+## Ancestors and descendants
+
+A section has one or more ancestors (including the home page), and zero or more descendants. With the file structure from the [example above](#overview):
+
+```text
+content/products/product-1/benefits/benefit-1.md
+```
+
+The content file (benefit-1.md) has four ancestors: benefits, product-1, products, and the home page. This logical relationship allows us to use the `.Parent` and `.Ancestors` methods to traverse the site structure.
+
+For example, use the `.Ancestors` method to render breadcrumb navigation.
+
+{{< code file=layouts/partials/breadcrumb.html >}}
+<nav aria-label="breadcrumb" class="breadcrumb">
+ <ol>
+ {{ range .Ancestors.Reverse }}
+ <li>
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+ </li>
+ {{ end }}
+ <li class="active">
+ <a aria-current="page" href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+ </li>
+ </ol>
+</nav>
+{{< /code >}}
+
+With this CSS:
+
+```css
+.breadcrumb ol {
+ padding-left: 0;
+}
+
+.breadcrumb li {
+ display: inline;
+}
+
+.breadcrumb li:not(:last-child)::after {
+ content: "»";
+}
+```
+
+Hugo renders this, where each breadcrumb is a link to the corresponding page:
+
+```text
+Home » Products » Product 1 » Benefits » Benefit 1
+```
+
+[archetype]: /content-management/archetypes/
+[content type]: /content-management/types/
+[directory structure]: /getting-started/directory-structure/
+[section templates]: /templates/section-templates/
+[leaf bundles]: /content-management/page-bundles/#leaf-bundles
+[branch bundles]: /content-management/page-bundles/#branch-bundles
--- /dev/null
- In your content files, a shortcode can be called by calling `{{%/* shortcodename parameters */%}}`. Shortcode parameters are space delimited, and parameters with internal spaces can be quoted.
+---
+title: Shortcodes
+description: Shortcodes are simple snippets inside your content files calling built-in or custom templates.
+categories: [content management]
+keywords: [markdown,content,shortcodes]
+menu:
+ docs:
+ parent: content-management
+ weight: 100
+weight: 100
+toc: true
+aliases: [/extras/shortcodes/]
+testparam: "Hugo Rocks!"
+---
+
+## What a shortcode is
+
+Hugo loves Markdown because of its simple content format, but there are times when Markdown falls short. Often, content authors are forced to add raw HTML (e.g., video `<iframe>`'s) to Markdown content. We think this contradicts the beautiful simplicity of Markdown's syntax.
+
+Hugo created **shortcodes** to circumvent these limitations.
+
+A shortcode is a simple snippet inside a content file that Hugo will render using a predefined template. Note that shortcodes will not work in template files. If you need the type of drop-in functionality that shortcodes provide but in a template, you most likely want a [partial template][partials] instead.
+
+In addition to cleaner Markdown, shortcodes can be updated any time to reflect new classes, techniques, or standards. At the point of site generation, Hugo shortcodes will easily merge in your changes. You avoid a possibly complicated search and replace operation.
+
+## Use shortcodes
+
+{{< youtube 2xkNJL4gJ9E >}}
+
- The first word in the shortcode declaration is always the name of the shortcode. Parameters follow the name. Depending upon how the shortcode is defined, the parameters may be named, positional, or both, although you can't mix parameter types in a single call. The format for named parameters models that of HTML with the format `name="value"`.
++In your content files, a shortcode can be called by calling `{{%/* shortcodename arguments */%}}`. Shortcode arguments are space delimited, and arguments with internal spaces must be quoted.
+
- ### Shortcodes with raw string parameters
++The first word in the shortcode declaration is always the name of the shortcode. Arguments follow the name. Depending upon how the shortcode is defined, the arguments may be named, positional, or both, although you can't mix argument types in a single call. The format for named arguments models that of HTML with the format `name="value"`.
+
+Some shortcodes use or require closing shortcodes. Again like HTML, the opening and closing shortcodes match (name only) with the closing declaration, which is prepended with a slash.
+
+Here are two examples of paired shortcodes:
+
+```go-html-template
+{{%/* mdshortcode */%}}Stuff to `process` in the *center*.{{%/* /mdshortcode */%}}
+```
+
+```go-html-template
+{{</* highlight go */>}} A bunch of code here {{</* /highlight */>}}
+```
+
+The examples above use two different delimiters, the difference being the `%` character in the first and the `<>` characters in the second.
+
- You can pass multiple lines as parameters to a shortcode by using raw string literals:
++### Shortcodes with raw string arguments
+
- ### Shortcodes with markdown
++You can pass multiple lines as arguments to a shortcode by using raw string literals:
+
+```go-html-template
+{{</* myshortcode `This is some <b>HTML</b>,
+and a new line with a "quoted string".` */>}}
+```
+
- ### Shortcodes without markdown
++### Shortcodes with Markdown
+
+Shortcodes using the `%` as the outer-most delimiter will be fully rendered when sent to the content renderer. This means that the rendered output from a shortcode can be part of the page's table of contents, footnotes, etc.
+
- You can call shortcodes within other shortcodes by creating your own templates that leverage the `.Parent` variable. `.Parent` allows you to check the context in which the shortcode is being called. See [Shortcode templates][sctemps].
++### Shortcodes without Markdown
+
+The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without Markdown include internal HTML:
+
+```go-html-template
+{{</* myshortcode */>}}<p>Hello <strong>World!</strong></p>{{</* /myshortcode */>}}
+```
+
+### Nested shortcodes
+
- ## Use Hugo's built-in shortcodes
++You can call shortcodes within other shortcodes by creating your own templates that leverage the `.Parent` method. `.Parent` allows you to check the context in which the shortcode is being called. See [Shortcode templates][sctemps].
+
- Hugo ships with a set of predefined shortcodes that represent very common usage. These shortcodes are provided for author convenience and to keep your Markdown content clean.
++## Embedded shortcodes
+
- ### `figure`
++Use these embedded shortcodes as needed.
+
- `figure` is an extension of the image syntax in Markdown, which does not provide a shorthand for the more semantic [HTML5 `<figure>` element][figureelement].
++### figure
+
- The `figure` shortcode can use the following named parameters:
++{{% note %}}
++To override Hugo's embedded `figure` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
++
++[source code]: {{% eturl figure %}}
++{{% /note %}}
+
- : Optional `target` attribute for the URL if `link` parameter is set.
++The `figure` shortcode can use the following named arguments:
+
+src
+: URL of the image to be displayed.
+
+link
+: If the image needs to be hyperlinked, URL of the destination.
+
+target
- : Optional `rel` attribute for the URL if `link` parameter is set.
++: Optional `target` attribute for the URL if `link` argument is set.
+
+rel
- #### Example `figure` input
++: Optional `rel` attribute for the URL if `link` argument is set.
+
+alt
+: Alternate text for the image if the image cannot be displayed.
+
+title
+: Image title.
+
+caption
+: Image caption. Markdown within the value of `caption` will be rendered.
+
+class
+: `class` attribute of the HTML `figure` tag.
+
+height
+: `height` attribute of the image.
+
+width
+: `width` attribute of the image.
+
+loading
+: `loading` attribute of the image.
+
+attr
+: Image attribution text. Markdown within the value of `attr` will be rendered.
+
+attrlink
+: If the attribution text needs to be hyperlinked, URL of the destination.
+
- {{< code file=figure-input-example.md >}}
++Example usage:
+
- {{< /code >}}
++```text
+{{</* figure src="elephant.jpg" title="An elephant at sunset" */>}}
- #### Example `figure` output
++```
+
- ### `gist`
++Rendered:
+
+```html
+<figure>
+ <img src="elephant.jpg">
+ <figcaption><h4>An elephant at sunset</h4></figcaption>
+</figure>
+```
+
- Include this in your markdown:
++### gist
++
++{{% note %}}
++To override Hugo's embedded `gist` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
++
++[source code]: {{% eturl gist %}}
++{{% /note %}}
+
+To display a GitHub [gist] with this URL:
+
+[gist]: https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists
+
+```text
+https://gist.github.com/user/50a7482715eac222e230d1e64dd9a89b
+```
+
- ### `highlight`
++Include this in your Markdown:
+
+```text
+{{</* gist user 50a7482715eac222e230d1e64dd9a89b */>}}
+```
+
+This will display all files in the gist alphabetically by file name.
+
+{{< gist jmooring 23932424365401ffa5e9d9810102a477 >}}
+
+To display a specific file within the gist:
+
+```text
+{{</* gist user 23932424365401ffa5e9d9810102a477 list.html */>}}
+```
+
+Rendered:
+
+{{< gist jmooring 23932424365401ffa5e9d9810102a477 list.html >}}
+
- ### `instagram`
++### highlight
++
++{{% note %}}
++To override Hugo's embedded `highlight` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
++
++[source code]: {{% eturl highlight %}}
++{{% /note %}}
+
+To display a highlighted code sample:
+
+```text
+{{</* highlight go-html-template */>}}
+{{ range .Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+{{</* /highlight */>}}
+```
+
+Rendered:
+
+{{< highlight go-html-template >}}
+{{ range .Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+{{< /highlight >}}
+
+To specify one or more [highlighting options], include a quotation-encapsulated, comma-separated list:
+
+[highlighting options]: /functions/transform/highlight/
+
+```text
+{{</* highlight go-html-template "lineNos=inline, lineNoStart=42" */>}}
+{{ range .Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+{{</* /highlight */>}}
+```
+
+Rendered:
+
+{{< highlight go-html-template "lineNos=inline, lineNoStart=42" >}}
+{{ range .Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+{{< /highlight >}}
+
- The `instagram` shortcode uses Facebook's **oEmbed Read** feature. The Facebook [developer documentation] states:
++### instagram
+
- - 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]
++{{% note %}}
++To override Hugo's embedded `instagram` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
++
++[source code]: {{% eturl instagram %}}
++{{% /note %}}
+
- [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
++To display an Instagram post with this URL:
+
- You must obtain an Access Token to use the `instagram` shortcode.
++```text
++https://www.instagram.com/p/CxOWiQNP2MO/
++```
+
- If your site configuration is private:
++Include this in your Markdown:
+
- {{< code-toggle file=hugo >}}
- [services.instagram]
- accessToken = 'xxx'
- {{< /code-toggle >}}
++```text
++{{</* instagram CxOWiQNP2MO */>}}
++```
+
- If your site configuration is _not_ private, set the Access Token with an environment variable:
++Rendered:
+
- ```sh
- HUGO_SERVICES_INSTAGRAM_ACCESSTOKEN=xxx hugo --gc --minify
- ```
++{{< instagram CxOWiQNP2MO >}}
+
- If you are using a Client Access Token, you must combine the Access Token with your App ID using a pipe symbol (`APPID|ACCESSTOKEN`).
++### param
+
+{{% note %}}
- To display an Instagram post with this URL:
++To override Hugo's embedded `param` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
++
++[source code]: {{% eturl param %}}
+{{% /note %}}
+
- https://www.instagram.com/p/BWNjjyYFxVx/
++The `param` shortcode renders a parameter from the page's front matter, falling back to a site parameter of the same name. The shortcode throws an error if the parameter does not exist.
++
++Example usage:
+
+```text
- Include this in your markdown:
++{{</* param testparam */>}}
+```
+
- {{</* instagram BWNjjyYFxVx */>}}
++Access nested values by [chaining] the [identifiers]:
++
++[chaining]: /getting-started/glossary/#chain
++[identifiers]: /getting-started/glossary/#identifier
+
+```text
- ### `param`
++{{</* param my.nested.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.
++### ref
+
- ```sh
- {{</* param testparam */>}}
- ```
++{{% note %}}
++To override Hugo's embedded `ref` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
+
- Since `testparam` is a parameter defined in front matter of this page with the value `Hugo Rocks!`, the above will print:
++Always use the `{{%/* */%}}` notation when calling this shortcode.
+
- {{< param testparam >}}
++[source code]: {{% eturl ref %}}
++{{% /note %}}
+
- To access deeply nested parameters, use "dot syntax", e.g:
++The `ref` shortcode returns the permalink of the given page reference.
+
- ```sh
- {{</* param "my.nested.param" */>}}
++Example usage:
+
- ### `ref` and `relref`
++```text
++[Post 1]({{%/* ref "/posts/post-1" */%}})
++[Post 1]({{%/* ref "/posts/post-1.md" */%}})
++[Post 1]({{%/* ref "/posts/post-1#foo" */%}})
++[Post 1]({{%/* ref "/posts/post-1.md#foo" */%}})
+```
+
- These shortcodes will look up the pages by their relative path (e.g., `blog/post.md`) or their logical name (`post.md`) and return the permalink (`ref`) or relative permalink (`relref`) for the found page.
++Rendered:
+
- `ref` and `relref` also make it possible to make fragmentary links that work for the header links generated by Hugo.
++```html
++<a href="http://example.org/posts/post-1/">Post 1</a>
++<a href="http://example.org/posts/post-1/">Post 1</a>
++<a href="http://example.org/posts/post-1/#foo">Post 1</a>
++<a href="http://example.org/posts/post-1/#foo">Post 1</a>
++```
+
- Read a more extensive description of `ref` and `relref` in the [cross references](/content-management/cross-references/) documentation.
++### relref
+
+{{% note %}}
- `ref` and `relref` take exactly one required parameter of _reference_, quoted and in position `0`.
++To override Hugo's embedded `relref` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
++
++Always use the `{{%/* */%}}` notation when calling this shortcode.
++
++[source code]: {{% eturl relref %}}
+{{% /note %}}
+
- #### Example `ref` and `relref` input
++The `relref` shortcode returns the permalink of the given page reference.
+
- ```go-html-template
- [Neat]({{</* ref "blog/neat.md" */>}})
- [Who]({{</* relref "about.md#who" */>}})
++Example usage:
+
- #### Example `ref` and `relref` output
-
- Assuming that standard Hugo pretty URLs are turned on.
++```text
++[Post 1]({{%/* relref "/posts/post-1" */%}})
++[Post 1]({{%/* relref "/posts/post-1.md" */%}})
++[Post 1]({{%/* relref "/posts/post-1#foo" */%}})
++[Post 1]({{%/* relref "/posts/post-1.md#foo" */%}})
+```
+
- <a href="https://example.org/blog/neat">Neat</a>
- <a href="/about/#who">Who</a>
++Rendered:
+
+```html
- ### `tweet`
++<a href="/posts/post-1/">Post 1</a>
++<a href="/posts/post-1/">Post 1</a>
++<a href="/posts/post-1/#foo">Post 1</a>
++<a href="/posts/post-1/#foo">Post 1</a>
+```
+
- https://twitter.com/SanDiegoZoo/status/1453110110599868418
++### twitter
++
++{{% note %}}
++To override Hugo's embedded `twitter` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
++
++You may call the `twitter` shortcode by using its `tweet` alias.
++
++[source code]: {{% eturl twitter %}}
++{{% /note %}}
+
+To display a Twitter post with this URL:
+
+```txt
- Include this in your markdown:
++https://x.com/SanDiegoZoo/status/1453110110599868418
+```
+
- {{</* tweet user="SanDiegoZoo" id="1453110110599868418" */>}}
++Include this in your Markdown:
+
+```text
- {{< tweet user="SanDiegoZoo" id="1453110110599868418" >}}
++{{</* twitter user="SanDiegoZoo" id="1453110110599868418" */>}}
+```
+
+Rendered:
+
- ### `vimeo`
++{{< twitter user="SanDiegoZoo" id="1453110110599868418" >}}
+
- Include this in your markdown:
++### vimeo
++
++{{% note %}}
++To override Hugo's embedded `vimeo` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
++
++[source code]: {{% eturl vimeo %}}
++{{% /note %}}
+
+To display a Vimeo video with this URL:
+
+```text
+https://vimeo.com/channels/staffpicks/55073825
+```
+
- If you want to further customize the visual styling of the YouTube or Vimeo output, add a `class` named parameter when calling the shortcode. The new `class` will be added to the `<div>` that wraps the `<iframe>` *and* will remove the inline styles. Note that you will need to call the `id` as a named parameter as well. You can also give the vimeo video a descriptive title with `title`.
++Include this in your Markdown:
+
+```text
+{{</* vimeo 55073825 */>}}
+```
+
+Rendered:
+
+{{< vimeo 55073825 >}}
+
+{{% note %}}
- ### `youtube`
++If you want to further customize the visual styling, add a `class` argument when calling the shortcode. The new `class` will be added to the `<div>` that wraps the `<iframe>` *and* will remove the inline styles. Note that you will need to call the `id` as a named argument as well. You can also give the vimeo video a descriptive title with `title`.
+
+```go
+{{</* vimeo id="146022717" class="my-vimeo-wrapper-class" title="My vimeo video" */>}}
+```
+{{% /note %}}
+
- The `youtube` shortcode embeds a responsive video player for [YouTube videos]. Only the ID of the video is required, e.g.:
++### youtube
+
- ```txt
- https://www.youtube.com/watch?v=w7Ft2ymGmfc
++{{% note %}}
++To override Hugo's embedded `youtube` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
+
- #### Example `youtube` input
++[source code]: {{% eturl youtube %}}
++{{% /note %}}
++
++To display a YouTube video with this URL:
++
++```text
++https://www.youtube.com/watch?v=0RKpf3rK57I
+```
+
- Copy the YouTube video ID that follows `v=` in the video's URL and pass it to the `youtube` shortcode:
++Include this in your Markdown:
+
- {{< code file=example-youtube-input.md >}}
- {{</* youtube w7Ft2ymGmfc */>}}
- {{< /code >}}
++```text
++{{</* youtube 0RKpf3rK57I */>}}
++```
+
- Furthermore, you can automatically start playback of the embedded video by setting the `autoplay` parameter to `true`. Remember that you can't mix named and unnamed parameters, so you'll need to assign the yet unnamed video ID to the parameter `id`:
++Rendered:
+
- {{< code file=example-youtube-input-with-autoplay.md >}}
- {{</* youtube id="w7Ft2ymGmfc" autoplay="true" */>}}
- {{< /code >}}
++{{< youtube 0RKpf3rK57I >}}
+
- For [accessibility reasons](https://dequeuniversity.com/tips/provide-iframe-titles), it's best to provide a title for your YouTube video. You can do this using the shortcode by providing a `title` parameter. If no title is provided, a default of "YouTube Video" will be used.
++The youtube shortcode accepts these named arguments:
+
- {{< code file=example-youtube-input-with-title.md >}}
- {{</* youtube id="w7Ft2ymGmfc" title="A New Hugo Site in Under Two Minutes" */>}}
- {{< /code >}}
++id
++: (`string`) The video `id`. Optional if the `id` is provided as a positional argument as shown in the example above.
+
- #### Example `youtube` output
++allowFullScreen
++{{< new-in 0.125.0 >}}
++: (`bool`) Whether the `iframe` element can activate full screen mode. Default is `true`.
+
- Using the preceding `youtube` example, the following HTML will be added to your rendered website's markup:
++autoplay
++ {{< new-in 0.125.0 >}}
++: (`bool`) Whether to automatically play the video. Forces `mute` to `true`. Default is `false`.
+
- {{< code file=example-youtube-output.html >}}
- {{< youtube id="w7Ft2ymGmfc" autoplay="true" >}}
- {{< /code >}}
++class
++: (`string`) The `class` attribute of the wrapping `div` element. When specified, removes the `style` attributes from the `iframe` element and its wrapping `div` element.
+
- #### Example `youtube` display
++controls
++{{< new-in 0.125.0 >}}
++: (`bool`) Whether to display the video controls. Default is `true`.
+
- Using the preceding `youtube` example (without `autoplay="true"`), the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your style sheets and surrounding markup. The video is also include in the [Quick Start of the Hugo documentation][quickstart].
++end
++{{< new-in 0.125.0 >}}
++: (`int`) The time, measured in seconds from the start of the video, when the player should stop playing the video.
+
- {{< youtube w7Ft2ymGmfc >}}
++loading
++{{< new-in 0.125.0 >}}
++: (`string`) The loading attribute of the `iframe` element, either `eager` or `lazy`. Default is `eager`.
+
- To learn how to configure your Hugo site to meet the new EU privacy regulation, see [Hugo and the GDPR].
++loop
++{{< new-in 0.125.0 >}}
++: (`bool`) Whether to indefinitely repeat the video. Ignores the `start` and `end` arguments after the first play. Default is `false`.
++
++mute
++{{< new-in 0.125.0 >}}
++: (`bool`) Whether to mute the video. Always `true` when `autoplay` is `true`. Default is `false`.
++
++start
++{{< new-in 0.125.0 >}}
++: (`int`) The time, measured in seconds from the start of the video, when the player should start playing the video.
++
++title
++: (`string`) The `title` attribute of the `iframe` element. Defaults to "YouTube video".
++
++Example using some of the above:
++
++```text
++{{</* youtube id=0RKpf3rK57I start=30 end=60 loading=lazy */>}}
++```
+
+## Privacy configuration
+
- [`figure` shortcode]: #figure
- [contentmanagementsection]: /content-management/formats/
- [examplegist]: https://gist.github.com/spf13/7896402
- [figureelement]: https://html5doctor.com/the-figure-figcaption-elements/
- [Hugo and the GDPR]: /about/hugo-and-gdpr/
- [Instagram]: https://www.instagram.com/
- [pagevariables]: /variables/page/
++To learn how to configure your Hugo site to meet the new EU privacy regulation, see [privacy protections].
+
+## Create custom shortcodes
+
+To learn more about creating custom shortcodes, see the [shortcode template documentation].
+
- [scvars]: /variables/shortcode/
++[privacy protections]: /about/privacy/
+[partials]: /templates/partials/
+[quickstart]: /getting-started/quick-start/
+[sctemps]: /templates/shortcode-templates/
- [templatessection]: /templates/
+[shortcode template documentation]: /templates/shortcode-templates/
- [YouTube Input shortcode]: #youtube
+[Vimeo]: https://vimeo.com/
+[YouTube Videos]: https://www.youtube.com/
--- /dev/null
- description: Hugo generates summaries of your content.
+---
+title: Content summaries
+linkTitle: Summaries
- With the use of the `.Summary` [page variable][pagevariables], Hugo generates summaries of content to use as a short version in summary views.
++description: Create and render content summaries.
+categories: [content management]
+keywords: [summaries,abstracts,read more]
+menu:
+ docs:
+ parent: content-management
+ weight: 160
+weight: 160
+toc: true
+aliases: [/content/summaries/,/content-management/content-summaries/]
+---
+
++<!-- Do not remove the manual summary divider below. -->
++<!-- If you do, you will break its first literal usage on this page. -->
+<!--more-->
+
- ## Summary splitting options
++You can define a content summary manually, in front matter, or automatically. A manual content summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary.
+
- * Automatic Summary Split
- * Manual Summary Split
- * Front Matter Summary
++Review the [comparison table](#comparison) below to understand the characteristics of each summary type.
+
- It is natural to accompany the summary with links to the original content, and a common design pattern is to see this link in the form of a "Read More ..." button. See the `.RelPermalink`, `.Permalink`, and `.Truncated` [page variables][pagevariables].
++## Manual summary
+
- ### Automatic summary splitting
++Use a `<!--more-->` divider to indicate the end of the content summary. Hugo will not render the summary divider itself.
+
- By default, Hugo automatically takes the first 70 words of your content as its summary and stores it into the `.Summary` page variable for use in your templates. You may customize the summary length by setting `summaryLength` in your [site configuration](/getting-started/configuration/).
++{{< code file=content/sample.md >}}
+++++
++title: 'Example'
++date: 2024-05-26T09:10:33-07:00
+++++
+
- {{% note %}}
- You can customize how HTML tags in the summary are loaded using functions such as `plainify` and `safeHTML`.
- {{% /note %}}
++Thénardier was not mistaken. The man was sitting there, and letting
++Cosette get somewhat rested.
+
- {{% note %}}
- The Hugo-defined summaries are set to use word count calculated by splitting the text by one or more consecutive whitespace characters. If you are creating content in a `CJK` language and want to use Hugo's automatic summary splitting, set `hasCJKLanguage` to `true` in your [site configuration](/getting-started/configuration/).
- {{% /note %}}
++<!--more-->
+
- ### Manual summary splitting
++The inn-keeper walked round the brushwood and presented himself
++abruptly to the eyes of those whom he was in search of.
++{{< /code >}}
+
- Alternatively, you may add the `<!--more-->` summary divider where you want to split the article.
++When using the Emacs Org Mode [content format], use a `# more` divider to indicate the end of the content summary.
+
- For [Org mode content][org], use `# more` where you want to split the article.
++[content format]: /content-management/formats/
+
- Content that comes before the summary divider will be used as that content's summary and stored in the `.Summary` page variable with all HTML formatting intact.
++## Front matter summary
+
- {{% note %}}
- The concept of a *summary divider* is not unique to Hugo. It is also called the "more tag" or "excerpt separator" in other literature.
- {{% /note %}}
++Use front matter to define a summary independent of content.
+
- Pros
- : Freedom, precision, and improved rendering. All HTML tags and formatting are preserved.
++{{< code file=content/sample.md >}}
+++++
++title: 'Example'
++date: 2024-05-26T09:10:33-07:00
++summary: 'Learn more about _Les Misérables_ by Victor Hugo.'
+++++
+
- Cons
- : Extra work for content authors, since they need to remember to type `<!--more-->` (or `# more` for [org content][org]) in each content file. This can be automated by adding the summary divider below the front matter of an [archetype](/content-management/archetypes/).
++Thénardier was not mistaken. The man was sitting there, and letting
++Cosette get somewhat rested. The inn-keeper walked round the
++brushwood and presented himself abruptly to the eyes of those whom
++he was in search of.
++{{< /code >}}
+
- {{% note %}}
- Be careful to enter `<!--more-->` exactly; i.e., all lowercase and with no whitespace.
- {{% /note %}}
++## Automatic summary
+
- ### Front matter summary
++If you have not defined the summary manually or in front matter, Hugo automatically defines the summary based on the [`summaryLength`] in your site configuration.
+
- You might want your summary to be something other than the text that starts the article. In this case you can provide a separate summary in the `summary` variable of the article front matter.
++[`summaryLength`]: /getting-started/configuration/#summarylength
+
- Pros
- : Complete freedom of text independent of the content of the article. Markup can be used within the summary.
++{{< code file=content/sample.md >}}
+++++
++title: 'Example'
++date: 2024-05-26T09:10:33-07:00
+++++
++
++Thénardier was not mistaken. The man was sitting there, and letting
++Cosette get somewhat rested. The inn-keeper walked round the
++brushwood and presented himself abruptly to the eyes of those whom
++he was in search of.
++{{< /code >}}
+
- Cons
- : Extra work for content authors as they need to write an entirely separate piece of text as the summary of the article.
++For example, with a `summaryLength` of 10, the automatic summary will be:
+
- ## Summary selection order
++```text
++Thénardier was not mistaken. The man was sitting there, and letting
++Cosette get somewhat rested.
++```
+
- Because there are multiple ways in which a summary can be specified it is useful to understand the order of selection Hugo follows when deciding on the text to be returned by `.Summary`. It is as follows:
++Note that the `summaryLength` is an approximate number of words.
+
- 1. If there is a `<!--more-->` summary divider present in the article, the text up to the divider will be provided as per the manual summary split method
- 2. If there is a `summary` variable in the article front matter the value of the variable will be provided as per the front matter summary method
- 3. The text at the start of the article will be provided as per the automatic summary split method
++## Comparison
+
- {{% note %}}
- Hugo uses the _first_ of the above steps that returns text. So if, for example, your article has both `summary` variable in its front matter and a `<!--more-->` summary divider Hugo will use the manual summary split method.
- {{% /note %}}
++Each summary type has different characteristics:
+
- ## Example: first 10 articles with summaries
++Type|Precedence|Renders markdown|Renders shortcodes|Strips HTML tags|Wraps single lines with `<p>`
++:--|:-:|:-:|:-:|:-:|:-:
++Manual|1|:heavy_check_mark:|:heavy_check_mark:|:x:|:heavy_check_mark:
++Front matter|2|:heavy_check_mark:|:x:|:x:|:x:
++Automatic|3|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:x:
+
- You can show content summaries with the following code. You could use the following snippet, for example, in a [section template].
++## Rendering
+
- {{< code file=page-list-with-summaries.html >}}
- {{ range first 10 .Pages }}
- <article>
- <!-- this <div> includes the title summary -->
- <div>
- <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
- {{ .Summary }}
- </div>
++Render the summary in a template by calling the [`Summary`] method on a `Page` object.
+
- <!-- This <div> includes a read more link, but only if the summary is truncated... -->
- <div>
- <a href="{{ .RelPermalink }}">Read More…</a>
- </div>
++[`Summary`]: /methods/page/summary
++
++```go-html-template
++{{ range site.RegularPages }}
++ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
++ <div class="summary">
++ {{ .Summary }}
+ {{ if .Truncated }}
- </article>
++ <a href="{{ .RelPermalink }}">More ...</a>
+ {{ end }}
- {{< /code >}}
-
- Note how the `.Truncated` boolean variable value may be used to hide the "Read More..." link when the content is not truncated; i.e., when the summary contains the entire article.
-
- [org]: /content-management/formats/
- [pagevariables]: /variables/page/
- [section template]: /templates/section-templates/
++ </div>
+{{ end }}
++```
--- /dev/null
- weight: 240
- weight: 240
+---
+title: Syntax highlighting
+description: Hugo comes with really fast syntax highlighting from Chroma.
+categories: [content management]
+keywords: [highlighting,chroma,code blocks,syntax]
+menu:
+ docs:
+ parent: content-management
- If you run with `markup.highlight.noClasses=false` in your site configuration, you need a style sheet.
++ weight: 250
++weight: 250
+toc: true
+aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/]
+---
+
+Hugo uses [Chroma](https://github.com/alecthomas/chroma) as its code highlighter; it is built in Go and is really, really fast.
+
+## Configure syntax highlighter
+
+See [Configure Highlight](/getting-started/configuration-markup#highlight).
+
+## Generate syntax highlighter CSS
+
- Highlighting is carried out via the built-in [`highlight` shortcode](/content-management/shortcodes/#highlight). It takes exactly one required parameter for the programming language to be highlighted and requires a closing shortcode.
++If you run with `markup.highlight.noClasses=false` in your site configuration, you need a style sheet. The style sheet will override the style specified in [`markup.highlight.style`](/functions/transform/highlight/#options).
+
+You can generate one with Hugo:
+
+```sh
+hugo gen chromastyles --style=monokai > syntax.css
+```
+
+Run `hugo gen chromastyles -h` for more options. See https://xyproto.github.io/splash/docs/ for a gallery of available styles.
+
+## Highlight shortcode
+
++Highlighting is carried out via the built-in [`highlight` shortcode](/content-management/shortcodes/#highlight). It takes exactly one required argument for the programming language to be highlighted and requires a closing tag.
+
+Options:
+
+* `linenos`: configure line numbers. Valid values are `true`, `false`, `table`, or `inline`. `false` will turn off line numbers if it's configured to be on in site configuration. `table` will give copy-and-paste friendly code blocks.
+* `hl_lines`: lists a set of line numbers or line number ranges to be highlighted.
+* `linenostart=199`: starts the line number count from 199.
+* `anchorlinenos`: Configure anchors on line numbers. Valid values are `true` or `false`;
+* `lineanchors`: Configure a prefix for the anchors on line numbers. Will be suffixed with `-`, so linking to the line number 1 with the option `lineanchors=prefix` adds the anchor `prefix-1` to the page.
+* `hl_inline` Highlight inside a `<code>` (inline HTML element) tag. Valid values are `true` or `false`. The `code` tag will get a class with name `code-inline`. {{< new-in 0.101.0 >}}
+
+### Example: highlight shortcode
+
+```go-html-template
+{{</* highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" */>}}
+// ... code
+{{</* / highlight */>}}
+```
+
+Gives this:
+
+{{< highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" >}}
+// GetTitleFunc returns a func that can be used to transform a string to
+// title case.
+//
+// The supported styles are
+//
+// - "Go" (strings.Title)
+// - "AP" (see https://www.apstylebook.com/)
+// - "Chicago" (see https://www.chicagomanualofstyle.org/home.html)
+//
+// If an unknown or empty style is provided, AP style is what you get.
+func GetTitleFunc(style string) func(s string) string {
+ switch strings.ToLower(style) {
+ case "go":
+ return strings.Title
+ case "chicago":
+ return transform.NewTitleConverter(transform.ChicagoStyle)
+ default:
+ return transform.NewTitleConverter(transform.APStyle)
+ }
+}
+{{< / highlight >}}
+
+## Highlight Hugo/Go template code
+
+For highlighting Hugo/Go template code on your page, add `/*` after the opening double curly braces and `*/` before closing curly braces.
+
+``` go
+{{</*/* myshortcode */*/>}}
+```
+
+Gives this:
+
+``` go
+{{</* myshortcode */>}}
+```
+
+## Highlight template function
+
+See [Highlight](/functions/transform/highlight/).
+
+## Highlighting in code fences
+
+Highlighting in code fences is enabled by default.
+
+````txt
+```go {linenos=table,hl_lines=[8,"15-17"],linenostart=199}
+// ... code
+```
+````
+
+Gives this:
+
+```go {linenos=table,hl_lines=[8,"15-17"],linenostart=199}
+// GetTitleFunc returns a func that can be used to transform a string to
+// title case.
+//
+// The supported styles are
+//
+// - "Go" (strings.Title)
+// - "AP" (see https://www.apstylebook.com/)
+// - "Chicago" (see https://www.chicagomanualofstyle.org/home.html)
+//
+// If an unknown or empty style is provided, AP style is what you get.
+func GetTitleFunc(style string) func(s string) string {
+ switch strings.ToLower(style) {
+ case "go":
+ return strings.Title
+ case "chicago":
+ return transform.NewTitleConverter(transform.ChicagoStyle)
+ default:
+ return transform.NewTitleConverter(transform.APStyle)
+ }
+}
+```
+
+The options are the same as in the [highlighting shortcode](/content-management/syntax-highlighting/#highlight-shortcode), including `linenos=false`, but note the slightly different Markdown attribute syntax.
+
+## List of Chroma highlighting languages
+
+The full list of Chroma lexers and their aliases (which is the identifier used in the `highlight` template func or when doing highlighting in code fences):
+
+{{< chroma-lexers >}}
--- /dev/null
- ## Add taxonomies to content
+---
+title: Taxonomies
+description: Hugo includes support for user-defined taxonomies.
+categories: [content management]
+keywords: [taxonomies,metadata,front matter,terms]
+menu:
+ docs:
+ parent: content-management
+ weight: 150
+weight: 150
+toc: true
+aliases: [/taxonomies/overview/,/taxonomies/usage/,/indexes/overview/,/doc/indexes/,/extras/indexes]
+---
+
+## What is a taxonomy?
+
+Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications of logical relationships between content.
+
+### Definitions
+
+Taxonomy
+: a categorization that can be used to classify content
+
+Term
+: a key within the taxonomy
+
+Value
+: a piece of content assigned to a term
+
+## Example taxonomy: movie website
+
+Let's assume you are making a website about movies. You may want to include the following taxonomies:
+
+* Actors
+* Directors
+* Studios
+* Genre
+* Year
+* Awards
+
+Then, in each of the movies, you would specify terms for each of these taxonomies (i.e., in the [front matter] of each of your movie content files). From these terms, Hugo would automatically create pages for each Actor, Director, Studio, Genre, Year, and Award, with each listing all of the Movies that matched that specific Actor, Director, Studio, Genre, Year, and Award.
+
+### Movie taxonomy organization
+
+To continue with the example of a movie site, the following demonstrates content relationships from the perspective of the taxonomy:
+
+```txt
+Actor <- Taxonomy
+ Bruce Willis <- Term
+ The Sixth Sense <- Value
+ Unbreakable <- Value
+ Moonrise Kingdom <- Value
+ Samuel L. Jackson <- Term
+ Unbreakable <- Value
+ The Avengers <- Value
+ xXx <- Value
+```
+
+From the perspective of the content, the relationships would appear differently, although the data and labels used are the same:
+
+```txt
+Unbreakable <- Value
+ Actors <- Taxonomy
+ Bruce Willis <- Term
+ Samuel L. Jackson <- Term
+ Director <- Taxonomy
+ M. Night Shyamalan <- Term
+ ...
+Moonrise Kingdom <- Value
+ Actors <- Taxonomy
+ Bruce Willis <- Term
+ Bill Murray <- Term
+ Director <- Taxonomy
+ Wes Anderson <- Term
+ ...
+```
+
+## Default taxonomies
+
+Hugo natively supports taxonomies.
+
+Without adding a single line to your [site configuration] file, Hugo will automatically create taxonomies for `tags` and `categories`. That would be the same as manually [configuring your taxonomies](#configure-taxonomies) as below:
+
+{{< code-toggle config=taxonomies />}}
+
+If you do not want Hugo to create any taxonomies, set `disableKinds` in your [site configuration] to the following:
+
+{{< code-toggle file=hugo >}}
+disableKinds = ["taxonomy","term"]
+{{</ code-toggle >}}
+
+{{% include "content-management/_common/page-kinds.md" %}}
+
+### Default destinations
+
+When taxonomies are used---and [taxonomy templates] are provided---Hugo will automatically create both a page listing all the taxonomy's terms and individual pages with lists of content associated with each term. For example, a `categories` taxonomy declared in your configuration and used in your content front matter will create the following pages:
+
+* A single page at `example.com/categories/` that lists all the [terms within the taxonomy]
+* [Individual taxonomy list pages][taxonomy templates] (e.g., `/categories/development/`) for each of the terms that shows a listing of all pages marked as part of that taxonomy within any content file's [front matter]
+
+## Configure taxonomies
+
+Custom taxonomies other than the [defaults](#default-taxonomies) must be defined in your [site configuration] before they can be used throughout the site. You need to provide both the plural and singular labels for each taxonomy. For example, `singular key = "plural value"` for TOML and `singular key: "plural value"` for YAML.
+
+### Example: adding a custom taxonomy named "series"
+
+{{% note %}}
+While adding custom taxonomies, you need to put in the default taxonomies too, _if you want to keep them_.
+{{% /note %}}
+
+{{< code-toggle file=hugo >}}
+[taxonomies]
+ tag = "tags"
+ category = "categories"
+ series = "series"
+{{</ code-toggle >}}
+
+### Example: removing default taxonomies
+
+If you want to have just the default `tags` taxonomy, and remove the `categories` taxonomy for your site, you can do so by modifying the `taxonomies` value in your [site configuration].
+
+{{< code-toggle file=hugo >}}
+[taxonomies]
+ tag = "tags"
+{{</ code-toggle >}}
+
+If you want to disable all taxonomies altogether, see the use of `disableKinds` in [Hugo Taxonomy Defaults](#default-taxonomies).
+
+{{% note %}}
+You can add content and front matter to your taxonomy list and taxonomy terms pages. See [Content Organization](/content-management/organization/) for more information on how to add an `_index.md` for this purpose.
+{{% /note %}}
+
- Once a taxonomy is defined at the site level, any piece of content can be assigned to it, regardless of [content type] or [content section].
-
- Assigning content to a taxonomy is done in the [front matter]. Simply create a variable with the *plural* name of the taxonomy and assign all terms you want to apply to the instance of the content type.
-
- {{% note %}}
- If you would like the ability to quickly generate content files with preconfigured taxonomies or terms, read the docs on [Hugo archetypes](/content-management/archetypes/).
- {{% /note %}}
-
- ### Example: front matter with taxonomies
++## Assign terms to content
+
- title = "Hugo: A fast and flexible static site generator"
- tags = [ "Development", "Go", "fast", "Blogging" ]
- categories = [ "Development" ]
- series = [ "Go Web Dev" ]
- slug = "hugo"
- project_url = "https://github.com/gohugoio/hugo"
- {{</ code-toggle >}}
++To assign one or more terms to a page, create a front matter field using the plural name of the taxonomy, then add terms to the corresponding array. For example:
+
+{{< code-toggle file=content/example.md fm=true >}}
- [taxonomy list templates]: /templates/taxonomy-templates/#taxonomy-list-templates
++title = 'Example'
++tags = ['Tag A','Tag B']
++categories = ['Category A','Category B']
++{{< /code-toggle >}}
+
+## Order taxonomies
+
+A content file can assign weight for each of its associate taxonomies. Taxonomic weight can be used for sorting or ordering content in [taxonomy list templates] and is declared in a content file's [front matter]. The convention for declaring taxonomic weight is `taxonomyname_weight`.
+
+The following show a piece of content that has a weight of 22, which can be used for ordering purposes when rendering the pages assigned to the "a", "b" and "c" values of the `tags` taxonomy. It has also been assigned the weight of 44 when rendering the "d" category page.
+
+### Example: taxonomic `weight`
+
+{{< code-toggle >}}
+title = "foo"
+tags = [ "a", "b", "c" ]
+tags_weight = 22
+categories = ["d"]
+categories_weight = 44
+{{</ code-toggle >}}
+
+By using taxonomic weight, the same piece of content can appear in different positions in different taxonomies.
+
+## Add custom metadata to a taxonomy or term
+
+If you need to add custom metadata to your taxonomy terms, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in its front matter. Continuing with our 'Actors' example, let's say you want to add a Wikipedia page link to each actor. Your terms pages would be something like this:
+
+{{< code-toggle file=content/actors/bruce-willis/_index.md fm=true >}}
+title: "Bruce Willis"
+wikipedia: "https://en.wikipedia.org/wiki/Bruce_Willis"
+{{< /code-toggle >}}
+
+[content section]: /content-management/sections/
+[content type]: /content-management/types/
+[documentation on archetypes]: /content-management/archetypes/
+[front matter]: /content-management/front-matter/
- [terms within the taxonomy]: /templates/taxonomy-templates/#taxonomy-terms-templates
++[taxonomy list templates]: /templates/taxonomy-templates/#taxonomy-templates
+[taxonomy templates]: /templates/taxonomy-templates/
++[terms within the taxonomy]: /templates/taxonomy-templates/#term-templates
+[site configuration]: /getting-started/configuration/
--- /dev/null
- In your site configuration, define a URL pattern for each top-level section. Each URL pattern can target a given language and/or [page kind].
+---
+title: URL management
+description: Control the structure and appearance of URLs through front matter entries and settings in your site configuration.
+categories: [content management]
+keywords: [aliases,redirects,permalinks,urls]
+menu:
+ docs:
+ parent: content-management
+ weight: 180
+weight: 180
+toc: true
+aliases: [/extras/permalinks/,/extras/aliases/,/extras/urls/,/doc/redirects/,/doc/alias/,/doc/aliases/]
+---
+
+## Overview
+
+By default, when Hugo renders a page, the resulting URL matches the file path within the `content` directory. For example:
+
+```text
+content/posts/post-1.md → https://example.org/posts/post-1/
+```
+
+You can change the structure and appearance of URLs with front matter values and site configuration options.
+
+## Front matter
+
+### `slug`
+
+Set the `slug` in front matter to override the last segment of the path. The `slug` value does not affect section pages.
+
+{{< code-toggle file=content/posts/post-1.md fm=true >}}
+title = 'My First Post'
+slug = 'my-first-post'
+{{< /code-toggle >}}
+
+The resulting URL will be:
+
+```text
+https://example.org/posts/my-first-post/
+```
+
+### `url`
+
+Set the `url` in front matter to override the entire path. Use this with either regular pages or section pages.
+
+With this front matter:
+
+{{< code-toggle file=content/posts/post-1.md fm=true >}}
+title = 'My First Article'
+url = '/articles/my-first-article'
+{{< /code-toggle >}}
+
+The resulting URL will be:
+
+```text
+https://example.org/articles/my-first-article/
+```
+
+If you include a file extension:
+
+{{< code-toggle file=content/posts/post-1.md fm=true >}}
+title = 'My First Article'
+url = '/articles/my-first-article.html'
+{{< /code-toggle >}}
+
+The resulting URL will be:
+
+```text
+https://example.org/articles/my-first-article.html
+```
+
+In a monolingual site, a `url` value with or without a leading slash is relative to the `baseURL`.
+
+In a multilingual site:
+
+- A `url` value with a leading slash is relative to the `baseURL`.
+- A `url` value without a leading slash is relative to the `baseURL` plus the language prefix.
+
+Site type|Front matter `url`|Resulting URL
+:--|:--|:--
+monolingual|`/about`|`https://example.org/about/`
+monolingual|`about`|`https://example.org/about/`
+multilingual|`/about`|`https://example.org/about/`
+multilingual|`about`|`https://example.org/de/about/`
+
+If you set both `slug` and `url` in front matter, the `url` value takes precedence.
+
+## Site configuration
+
+### Permalinks
+
- [page kind]: /templates/section-templates/#page-kinds
-
++In your site configuration, define a URL pattern for each top-level section. Each URL pattern can target a given language and/or page kind.
+
+Front matter `url` values override the URL patterns defined in the `permalinks` section of your site configuration.
+
- Use these tokens when defining the URL pattern. The `date` field in front matter determines the value of time-related tokens.
+#### Monolingual examples {#permalinks-monolingual-examples}
+
+With this content structure:
+
+```text
+content/
+├── posts/
+│ ├── bash-in-slow-motion.md
+│ └── tls-in-a-nutshell.md
+├── tutorials/
+│ ├── git-for-beginners.md
+│ └── javascript-bundling-with-hugo.md
+└── _index.md
+```
+
+Render tutorials under "training", and render the posts under "articles" with a date-base hierarchy:
+
+{{< code-toggle file=hugo >}}
+[permalinks.page]
+posts = '/articles/:year/:month/:slug/'
+tutorials = '/training/:slug/'
+[permalinks.section]
+posts = '/articles/'
+tutorials = '/training/'
+{{< /code-toggle >}}
+
+The structure of the published site will be:
+
+```text
+public/
+├── articles/
+│ ├── 2023/
+│ │ ├── 04/
+│ │ │ └── bash-in-slow-motion/
+│ │ │ └── index.html
+│ │ └── 06/
+│ │ └── tls-in-a-nutshell/
+│ │ └── index.html
+│ └── index.html
+├── training/
+│ ├── git-for-beginners/
+│ │ └── index.html
+│ ├── javascript-bundling-with-hugo/
+│ │ └── index.html
+│ └── index.html
+└── index.html
+```
+
+To create a date-based hierarchy for regular pages in the content root:
+
+{{< code-toggle file=hugo >}}
+[permalinks.page]
+"/" = "/:year/:month/:slug/"
+{{< /code-toggle >}}
+
+Use the same approach with taxonomy terms. For example, to omit the taxonomy segment of the URL:
+
+{{< code-toggle file=hugo >}}
+[permalinks.term]
+'tags' = '/:slug/'
+{{< /code-toggle >}}
+
+#### Multilingual example {#permalinks-multilingual-example}
+
+Use the `permalinks` configuration as a component of your localization strategy.
+
+With this content structure:
+
+```text
+content/
+├── en/
+│ ├── books/
+│ │ ├── les-miserables.md
+│ │ └── the-hunchback-of-notre-dame.md
+│ └── _index.md
+└── es/
+ ├── books/
+ │ ├── les-miserables.md
+ │ └── the-hunchback-of-notre-dame.md
+ └── _index.md
+```
+
+And this site configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'en'
+defaultContentLanguageInSubdir = true
+
+[languages.en]
+contentDir = 'content/en'
+languageCode = 'en-US'
+languageDirection = 'ltr'
+languageName = 'English'
+weight = 1
+
+[languages.en.permalinks.page]
+books = "/books/:slug/"
+
+[languages.en.permalinks.section]
+books = "/books/"
+
+[languages.es]
+contentDir = 'content/es'
+languageCode = 'es-ES'
+languageDirection = 'ltr'
+languageName = 'Español'
+weight = 2
+
+[languages.es.permalinks.page]
+books = "/libros/:slug/"
+
+[languages.es.permalinks.section]
+books = "/libros/"
+{{< /code-toggle >}}
+
+The structure of the published site will be:
+
+```text
+public/
+├── en/
+│ ├── books/
+│ │ ├── les-miserables/
+│ │ │ └── index.html
+│ │ ├── the-hunchback-of-notre-dame/
+│ │ │ └── index.html
+│ │ └── index.html
+│ └── index.html
+├── es/
+│ ├── libros/
+│ │ ├── les-miserables/
+│ │ │ └── index.html
+│ │ ├── the-hunchback-of-notre-dame/
+│ │ │ └── index.html
+│ │ └── index.html
+│ └── index.html
+└── index.html
+````
+
+#### Tokens
+
- : the 4-digit year
++Use these tokens when defining the URL pattern.
+
+`:year`
- : the 2-digit month
++: The 4-digit year as defined in the front matter `date` field.
+
+`:month`
- : the name of the month
++: The 2-digit month as defined in the front matter `date` field.
+
+`:monthname`
- : the 2-digit day
++: The name of the month as defined in the front matter `date` field.
+
+`:day`
- : the 1-digit day of the week (Sunday = 0)
++: The 2-digit day as defined in the front matter `date` field.
+
+`:weekday`
- : the name of the day of the week
++: The 1-digit day of the week as defined in the front matter `date` field (Sunday = 0).
+
+`:weekdayname`
- : the 1- to 3-digit day of the year
++: The name of the day of the week as defined in the front matter `date` field.
+
+`:yearday`
- : the content's section
++: The 1- to 3-digit day of the year as defined in the front matter `date` field.
+
+`:section`
- : the content's sections hierarchy. You can use a selection of the sections using _slice syntax_: `:sections[1:]` includes all but the first, `:sections[:last]` includes all but the last, `:sections[last]` includes only the last, `:sections[1:2]` includes section 2 and 3. Note that this slice access will not throw any out-of-bounds errors, so you don't have to be exact.
++: The content's section.
+
+`:sections`
- : the content's title
++: The content's sections hierarchy. You can use a selection of the sections using _slice syntax_: `:sections[1:]` includes all but the first, `:sections[:last]` includes all but the last, `:sections[last]` includes only the last, `:sections[1:2]` includes section 2 and 3. Note that this slice access will not throw any out-of-bounds errors, so you don't have to be exact.
+
+`:title`
- : the content's slug (or title if no slug is provided in the front matter)
-
- `:slugorfilename`
- : the content's slug (or file name if no slug is provided in the front matter)
++: The title as defined in front matter, else the automatic title. Hugo generates titles automatically for section, taxonomy, and term pages that are not backed by a file.
+
+`:slug`
- : the content's file name (without extension)
++: The slug as defined in front matter, else the title as defined in front matter, else the automatic title. Hugo generates titles automatically for section, taxonomy, and term pages that are not backed by a file.
+
+`:filename`
- This is a legacy configuration option, superseded by template functions and markdown render hooks, and will likely be [removed in a future release].
++: The content's file name without extension, applicable to the `page` page kind.
++
++`:slugorfilename`
++: The slug as defined in front matter, else the content's file name without extension, applicable to the `page` page kind.
+
+For time-related values, you can also use the layout string components defined in Go's [time package]. For example:
+
+[time package]: https://pkg.go.dev/time#pkg-constants
+
+{{< code-toggle file=hugo >}}
+permalinks:
+ posts: /:06/:1/:2/:title/
+{{< /code-toggle >}}
+
+### Appearance
+
+The appearance of a URL is either ugly or pretty.
+
+Type|Path|URL
+:--|:--|:--
+ugly|content/about.md|`https://example.org/about.html`
+pretty|content/about.md|`https://example.org/about/`
+
+By default, Hugo produces pretty URLs. To generate ugly URLs, change your site configuration:
+
+{{< code-toggle file=hugo >}}
+uglyURLs = true
+{{< /code-toggle >}}
+
+### Post-processing
+
+Hugo provides two mutually exclusive configuration options to alter URLs _after_ it renders a page.
+
+#### Canonical URLs
+
+{{% note %}}
- Create a new template (`layouts/alias.html`) to customize the content of the alias files. The template receives the following context:
++This is a legacy configuration option, superseded by template functions and Markdown render hooks, and will likely be [removed in a future release].
+
+[removed in a future release]: https://github.com/gohugoio/hugo/issues/4733
+{{% /note %}}
+
+If enabled, Hugo performs a search and replace _after_ it renders the page. It searches for site-relative URLs (those with a leading slash) associated with `action`, `href`, `src`, `srcset`, and `url` attributes. It then prepends the `baseURL` to create absolute URLs.
+
+```html
+<a href="/about"> → <a href="https://example.org/about/">
+<img src="/a.gif"> → <img src="https://example.org/a.gif">
+```
+
+This is an imperfect, brute force approach that can affect content as well as HTML attributes. As noted above, this is a legacy configuration option that will likely be removed in a future release.
+
+To enable:
+
+{{< code-toggle file=hugo >}}
+canonifyURLs = true
+{{< /code-toggle >}}
+
+#### Relative URLs
+
+{{% note %}}
+Do not enable this option unless you are creating a serverless site, navigable via the file system.
+{{% /note %}}
+
+If enabled, Hugo performs a search and replace _after_ it renders the page. It searches for site-relative URLs (those with a leading slash) associated with `action`, `href`, `src`, `srcset`, and `url` attributes. It then transforms the URL to be relative to the current page.
+
+For example, when rendering `content/posts/post-1`:
+
+```html
+<a href="/about"> → <a href="../../about">
+<img src="/a.gif"> → <img src="../../a.gif">
+```
+
+This is an imperfect, brute force approach that can affect content as well as HTML attributes. As noted above, do not enable this option unless you are creating a serverless site.
+
+To enable:
+
+{{< code-toggle file=hugo >}}
+relativeURLs = true
+{{< /code-toggle >}}
+
+## Aliases
+
+Create redirects from old URLs to new URLs with aliases:
+
+- An alias with a leading slash is relative to the `baseURL`
+- An alias without a leading slash is relative to the current directory
+
+### Examples {#alias-examples}
+
+Change the file name of an existing page, and create an alias from the previous URL to the new URL:
+
+{{< code-toggle file=content/posts/new-file-name.md >}}
+aliases = ['/posts/previous-file-name']
+{{< /code-toggle >}}
+
+Each of these directory-relative aliases is equivalent to the site-relative alias above:
+
+- `previous-file-name`
+- `./previous-file-name`
+- `../posts/previous-file-name`
+
+You can create more than one alias to the current page:
+
+{{< code-toggle file=content/posts/new-file-name.md >}}
+aliases = ['previous-file-name','original-file-name']
+{{< /code-toggle >}}
+
+In a multilingual site, use a directory-relative alias, or include the language prefix with a site-relative alias:
+
+{{< code-toggle file=content/posts/new-file-name.de.md >}}
+aliases = ['/de/posts/previous-file-name']
+{{< /code-toggle >}}
+
+### How aliases work
+
+Using the first example above, Hugo generates the following site structure:
+
+```text
+public/
+├── posts/
+│ ├── new-file-name/
+│ │ └── index.html
+│ ├── previous-file-name/
+│ │ └── index.html
+│ └── index.html
+└── index.html
+```
+
+The alias from the previous URL to the new URL is a client-side redirect:
+
+{{< code file=posts/previous-file-name/index.html >}}
+<!DOCTYPE html>
+<html lang="en-us">
+ <head>
+ <title>https://example.org/posts/new-file-name/</title>
+ <link rel="canonical" href="https://example.org/posts/new-file-name/">
+ <meta name="robots" content="noindex">
+ <meta charset="utf-8">
+ <meta http-equiv="refresh" content="0; url=https://example.org/posts/new-file-name/">
+ </head>
+</html>
+{{< /code >}}
+
+Collectively, the elements in the `head` section:
+
+- Tell search engines that the new URL is canonical
+- Tell search engines not to index the previous URL
+- Tell the browser to redirect to the new URL
+
+Hugo renders alias files before rendering pages. A new page with the previous file name will overwrite the alias, as expected.
+
+### Customize
+
- : the link to the page being aliased
++To override Hugo's embedded `alias` template, copy the [source code] to a file with the same name in the layouts directory. The template receives the following context:
+
+Permalink
- : the Page data for the page being aliased
++: The link to the page being aliased.
+
+Page
++: The Page data for the page being aliased.
++
++[source code]: {{% eturl alias %}}
--- /dev/null
- linkTitle: Overview
+---
+title: Contribute to the Hugo project
- identifier: contribute-overview
++linkTitle: In this section
+description: Contribute to Hugo development, documentation, and themes.
+categories: []
+keywords: []
+menu:
+ docs:
++ identifier: contribute-in-this-section
+ parent: contribute
+ weight: 10
+weight: 10
+aliases: [/tutorials/how-to-contribute-to-hugo/,/community/contributing/]
+---
+
+Hugo relies heavily on the enthusiasm and participation of the open-source community. We need your support.
--- /dev/null
-
-
+---
+title: Development
+description: Contribute to the development of Hugo.
+categories: [contribute]
+keywords: [development]
+menu:
+ docs:
+ parent: contribute
+ weight: 20
+weight: 20
+toc: true
+---
+
+## Introduction
+
+You can contribute to the Hugo project by:
+
+- Answering questions on the [forum]
+- Improving the [documentation]
+- Monitoring the [issue queue]
+- Creating or improving [themes]
+- Squashing [bugs]
+
+Please submit documentation issues and pull requests to the [documentation repository].
+
+If you have an idea for an enhancement or new feature, create a new topic on the [forum] in the "Feature" category. This will help you to:
+
+- Determine if the capability already exists
+- Measure interest
+- Refine the concept
+
+If there is sufficient interest, [create a proposal]. Do not submit a pull request until the project lead accepts the proposal.
+
+For a complete guide to contributing to Hugo, see the [Contribution Guide].
+
+[bugs]: https://github.com/gohugoio/hugo/issues?q=is%3Aopen+is%3Aissue+label%3ABug
+[contributing]: CONTRIBUTING.md
+[create a proposal]: https://github.com/gohugoio/hugo/issues/new?labels=Proposal%2C+NeedsTriage&template=feature_request.md
+[documentation repository]: https://github.com/gohugoio/hugoDocs
+[documentation]: https://gohugo.io/documentation
+[forum]: https://discourse.gohugo.io
+[issue queue]: https://github.com/gohugoio/hugo/issues
+[themes]: https://themes.gohugo.io/
+[contribution guide]: https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md
+
+## Prerequisites
+
+To build the extended edition of Hugo from source you must:
+
+1. Install [Git]
+1. Install [Go] version 1.20 or later
+1. Install a C compiler, either [GCC] or [Clang]
+1. Update your `PATH` environment variable as described in the [Go documentation]
+
+[Clang]: https://clang.llvm.org/
+[GCC]: https://gcc.gnu.org/
+[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+[Go documentation]: https://go.dev/doc/code#Command
+[Go]: https://go.dev/doc/install
+
+{{% note %}}
+See these [detailed instructions](https://discourse.gohugo.io/t/41370) to install GCC on Windows.
+{{% /note %}}
+
+## GitHub workflow
+
+{{% note %}}
+This section assumes that you have a working knowledge of Go, Git and GitHub, and are comfortable working on the command line.
+{{% /note %}}
+
+Use this workflow to create and submit pull requests.
+
+Step 1
+: Fork the [project repository].
+
+[project repository]: https://github.com/gohugoio/hugo/
+
+Step 2
+: Clone your fork.
+
+Step 3
+: Create a new branch with a descriptive name that includes the corresponding issue number.
+
+For a new feature:
+
+```sh
+git checkout -b feat/implement-some-feature-99999
+```
+
+For a bug fix:
+
+```sh
+git checkout -b fix/fix-some-bug-99999
+```
+
+Step 4
+: Make changes.
+
+Step 5
+: Compile and install:
+
+```text
+CGO_ENABLED=1 go install -tags extended
+```
+
+Step 6
+: Test your changes:
+
+```text
+go test ./...
+```
+
+Step 7
+: Commit your changes with a descriptive commit message:
+
+- Provide a summary on the first line, typically 50 characters or less, followed by a blank line.
+- Optionally, provide a detailed description where each line is 80 characters or less, followed by a blank line.
+- Add one or more "Fixes" or "Closes" keywords, each on its own line, referencing the [issues] addressed by this change.
+
+[issues]: https://github.com/gohugoio/hugo/issues
+
+For example:
+
+```sh
+git commit -m "tpl/strings: Create wrap function
+
+The strings.Wrap function wraps a string into one or more lines,
+splitting the string after the given number of characters, but not
+splitting in the middle of a word.
+
+Fixes #99998
+Closes #99999"
+```
+
+See the [commit message guidelines] for details.
+
+[commit message guidelines]: https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md#git-commit-message-guidelines
+
+Step 8
+: Push the new branch to your fork of the documentation repository.
+
+Step 9
+: Visit the [project repository] and create a pull request (PR).
+
+Step 10
+: A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR.
++
++## Building from source
++
++You can build, install, and test Hugo at any point in its development history. The examples below build and install the extended version of Hugo.
++
++To build and install the latest release:
++
++```sh
++CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@latest
++```
++
++To build and install a specific release:
++
++```sh
++CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@v0.126.0
++```
++
++To build and install at the latest commit on the master branch:
++
++```sh
++CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@master
++```
++
++To build and install at a specific commit:
++
++```sh
++CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@0851c17
++```
--- /dev/null
- Please follow these markdown guidelines:
+---
+title: Documentation
+description: Help us to improve the documentation by identifying issues and suggesting changes.
+categories: [contribute]
+keywords: [documentation]
+menu:
+ docs:
+ parent: contribute
+ weight: 30
+weight: 30
+toc: true
+aliases: [/contribute/docs/]
+---
+
+## Introduction
+
+We welcome corrections and improvements to the documentation. Please note that the documentation resides in its own repository, separate from the project repository.
+
+For corrections and improvements to the current documentation, please submit issues and pull requests to the [documentation repository].
+
+For documentation related to a new feature, please include the documentation changes when you submit a pull request to the [project repository].
+
+## Guidelines
+
+### Markdown
+
- - Do not mix [raw HTML] within markdown
++Please follow these guidelines:
+
+- Use [ATX] headings, not [setext] headings, levels 2 through 4
+- Use [fenced code blocks], not [indented code blocks]
+- Use hyphens, not asterisks, with unordered [list items]
+- Use the [note shortcode] instead of blockquotes
- - Avoid markdown in headings and page titles
++- Do not mix [raw HTML] within Markdown
+- Do not use bold text instead of a heading or description term (`dt`)
+- Remove consecutive blank lines (maximum of two)
+- Remove trailing spaces
+
+### Style
+
+Although we do not strictly adhere to the [Microsoft Writing Style Guide], it is an excellent resource for questions related to style, grammar, and voice.
+
+#### Terminology
+
+Please link to the [glossary of terms] when necessary, and use the terms consistently throughout the documentation. Of special note:
+
+- The term "front matter" is two words unless you are referring to the configuration key
++- The term "standalone" is one word, not hyphenated
+- Use the word "map" instead of "dictionary"
+- Use the word "flag" instead of "option" when referring to a command line flag
++- Capitalize the word "Markdown"
++- Hyphenate the term "open-source" when used an adjective.
+
+#### Page titles and headings
+
+Please follow these guidelines for page titles and headings:
+
+- Use sentence-style capitalization
- #### Level 6 markdown headings
++- Avoid formatted strings in headings and page titles
+- Shorter is better
+
+#### Use active voice with present tense
+
+In software documentation, passive voice is unavoidable in some cases. Please use active voice when possible.
+
+No → With Hugo you can build a static site.\
+Yes → Build a static site with Hugo.
+
+No → This will cause Hugo to generate HTML files in the public directory.\
+Yes → Hugo generates HTML files in the public directory.
+
+#### Use second person instead of third person
+
+No → Users should exercise caution when deleting files.\
+Better → You must be cautious when deleting files.\
+Best → Be cautious when deleting files.
+
+#### Avoid adverbs when possible
+
+No → Hugo is extremely fast.\
+Yes → Hugo is fast.
+
+{{% note %}}
+"It's an adverb, Sam. It's a lazy tool of a weak mind." (Outbreak, 1995).
+{{% /note %}}
+
+#### Miscellaneous
+
+Other guidelines to consider:
+
+- Do not place list items directly under a heading; include an introductory sentence or phrase before the list.
+- Avoid use of **bold** text. Use the [note shortcode] to draw attention to important content.
+- Do not place description terms (`dt`) within backticks unless required for syntactic clarity.
+- Do not use Hugo's `ref` or `relref` shortcodes. We use a link render hook to resolve and validate link destinations, including fragments.
+- Shorter is better. If there is more than one way to do something, describe the current best practice. For example, avoid phrases such as "you can also do..." and "in older versions you had to..."
+- When including code samples, use short snippets that demonstrate the concept.
+- The Hugo user community is global; use [basic english](https://simple.wikipedia.org/wiki/Basic_English) when possible.
+
- Level 6 markdown headings are styled as `dt` elements. This was implemented to support a [glossary] with linkable terms.
++#### Level 6 headings
+
- [glossary]: /getting-started/glossary
++Level 6 headings are styled as `dt` elements. This was implemented to support a [glossary] with linkable terms.
+
- ### deprecated-in
-
- Use the “deprecated-in” shortcode to indicate that a feature is deprecated:
-
- ```text
- {{%/* deprecated-in 0.120.0 */%}}
- Use [`hugo.IsServer`] instead.
-
- [`hugo.IsServer`]: /functions/hugo/isserver
- {{%/* /deprecated-in */%}}
- ```
-
- Rendered:
-
- {{% deprecated-in 0.120.0 %}}
- Use [`hugo.IsServer`] instead.
-
- [`hugo.IsServer`]: /functions/hugo/isserver
- {{% /deprecated-in %}}
-
++[glossary]: /getting-started/glossary/
+
+## Code examples
+
+Indent code by two spaces. With examples of template code, include a space after opening action delimiters, and include a space before closing action delimiters.
+
+### Fenced code blocks
+
+Always include the language code when using a fenced code block:
+
+````text
+```go-html-template
+{{ if eq $foo "bar" }}
+ {{ print "foo is bar" }}
+{{ end }}
+```
+````
+
+Rendered:
+
+```go-html-template
+{{ if eq $foo "bar" }}
+ {{ print "foo is bar" }}
+{{ end }}
+```
+
+### Shortcode calls
+
+Use this syntax to include shortcodes calls within your code examples:
+
+```text
+{{</*/* foo */*/>}}
+{{%/*/* foo */*/%}}
+```
+
+Rendered:
+
+```text
+{{</* foo */>}}
+{{%/* foo */%}}
+```
+
+### Site configuration
+
+Use the [code-toggle shortcode] to include site configuration examples:
+
+```text
+{{</* code-toggle file=hugo */>}}
+baseURL = 'https://example.org/'
+languageCode = 'en-US'
+title = 'My Site'
+{{</* /code-toggle */>}}
+```
+
+Rendered:
+
+{{< code-toggle file=hugo >}}
+baseURL = 'https://example.org/'
+languageCode = 'en-US'
+title = 'My Site'
+{{< /code-toggle >}}
+
+### Front matter
+
+Use the [code-toggle shortcode] to include front matter examples:
+
+```text
+{{</* code-toggle file=content/posts/my-first-post.md fm=true */>}}
+title = 'My first post'
+date = 2023-11-09T12:56:07-08:00
+draft = false
+{{</* /code-toggle */>}}
+```
+
+Rendered:
+
+{{< code-toggle file=content/posts/my-first-post.md fm=true >}}
+title = 'My first post'
+date = 2023-11-09T12:56:07-08:00
+draft = false
+{{< /code-toggle >}}
+
+### Other code examples
+
+Use the [code shortcode] for other code examples that require a file name:
+
+```text
+{{</* code file=layouts/_default/single.html */>}}
+{{ range .Site.RegularPages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+{{</* /code */>}}
+```
+
+Rendered:
+
+{{< code file=layouts/_default/single.html >}}
+{{ range .Site.RegularPages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+{{< /code >}}
+
+## Shortcodes
+
+These shortcodes are commonly used throughout the documentation. Other shortcodes are available for specialized use.
+
- : (`string`) The code language. If you do not provide a `lang` argument, the code language is determined by the file extension. If the file extension is "html", sets the code language to `go-html-template`. Default is `text`.
+### code
+
+Use the "code" shortcode for other code examples that require a file name. See the [code examples] above. This shortcode takes these arguments:
+
+copy
+: (`bool`) Whether to display a copy-to-clipboard button. Default is `false`.
+
+file
+: (`string`) The file name to display.
+
+lang
- {{</* new-in 0.120.0 */>}}
++: (`string`) The code language. If you do not provide a `lang` argument, the code language is determined by the file extension. If the file extension is `html`, sets the code language to `go-html-template`. Default is `text`.
+
+### code-toggle
+
+Use the "code-toggle" shortcode to display examples of site configuration, front matter, or data files. See the [code examples] above. This shortcode takes these arguments:
+
+copy
+: (`bool`) Whether to display a copy-to-clipboard button. Default is `false`.
+
+file
+: (`string`) The file name to display. Omit the file extension for site configuration examples.
+
+fm
+: (`bool`) Whether the example is front matter. Default is `false`.
+
++
++### deprecated-in
++
++Use the “deprecated-in” shortcode to indicate that a feature is deprecated:
++
++```text
++{{%/* deprecated-in 0.127.0 */%}}
++Use [`hugo.IsServer`] instead.
++
++[`hugo.IsServer`]: /functions/hugo/isserver/
++{{%/* /deprecated-in */%}}
++```
++
++Rendered:
++
++{{% deprecated-in 0.127.0 %}}
++Use [`hugo.IsServer`] instead.
++
++[`hugo.IsServer`]: /functions/hugo/isserver/
++{{% /deprecated-in %}}
++
++### eturl
++
++Use the embedded template URL (eturl) shortcode to insert an absolute URL to the source code for an embedded template. The shortcode takes a single argument, the base file name of the template (omit the file extension).
++
++```text
++This is a link to the [embedded alias template].
++
++[embedded alias template]: {{%/* eturl alias */%}}
++```
++
++Rendered:
++
++This is a link to the [embedded alias template].
++
++[embedded alias template]: {{% eturl alias %}}
++
+### new-in
+
+Use the "new-in" shortcode to indicate a new feature:
+
+```text
- {{< new-in 0.120.0 >}}
++{{</* new-in 0.127.0 */>}}
+```
+
+Rendered:
+
- The "new in" label will be hidden if the specified version is older than a predefined threshold, based on differences in major and minor versions. See [details](https://github.com/gohugoio/hugoDocs/blob/master/layouts/shortcodes/new-in.html).
++{{< new-in 0.127.0 >}}
+
+### note
+
+Use the "note" shortcode with `{{%/* */%}}` delimiters to call attention to important content:
+
+```text
+{{%/* note */%}}
+Use the [`math.Mod`] function to control...
+
+[`math.Mod`]: /functions/math/mod/
+{{%/* /note */%}}
+```
+
+Rendered:
+
+{{% note %}}
+Use the [`math.Mod`] function to control...
+
+[`math.Mod`]: /functions/math/mod/
+{{% /note %}}
+
+## New features
+
+Use the "new-in" shortcode to indicate a new feature:
+
+{{< code file=content/something/foo.md lang=text >}}
+{{</* new-in 0.120.0 */>}}
+{{< /code >}}
+
- [`hugo.IsServer`]: /functions/hugo/isserver
++The "new in" label will be hidden if the specified version is older than a predefined threshold, based on differences in major and minor versions. See [details](https://github.com/gohugoio/hugoDocs/blob/master/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/new-in.html).
+
+## Deprecated features
+
+Use the "deprecated-in" shortcode to indicate that a feature is deprecated:
+
+{{< code file=content/something/foo.md >}}
+{{%/* deprecated-in 0.120.0 */%}}
+Use [`hugo.IsServer`] instead.
+
++[`hugo.IsServer`]: /functions/hugo/isserver/
+{{%/* /deprecated-in */%}}
+{{< /code >}}
+
+When deprecating a function or method, add this to front matter:
+
+{{< code-toggle file=content/something/foo.md fm=true >}}
+expiryDate: 2024-10-30
+{{< /code-toggle >}}
+
+Set the `expiryDate` to one year from the date of deprecation, and add a brief front matter comment to explain the setting.
+
+## GitHub workflow
+
+{{% note %}}
+This section assumes that you have a working knowledge of Git and GitHub, and are comfortable working on the command line.
+{{% /note %}}
+
+Use this workflow to create and submit pull requests.
+
+Step 1
+: Fork the [documentation repository].
+
+Step 2
+: Clone your fork.
+
+Step 3
+: Create a new branch with a descriptive name that includes the corresponding issue number, if any:
+
+```sh
+git checkout -b restructure-foo-page-99999
+```
+
+Step 4
+: Make changes.
+
+Step 5
+: Build the site locally to preview your changes.
+
+Step 6
+: Commit your changes with a descriptive commit message:
+
+- Provide a summary on the first line, typically 50 characters or less, followed by a blank line.
+- Optionally, provide a detailed description where each line is 80 characters or less, followed by a blank line.
+- Optionally, add one or more "Fixes" or "Closes" keywords, each on its own line, referencing the [issues] addressed by this change.
+
+For example:
+
+```sh
+git commit -m "Restructure the taxonomy page
+
+This restructures the taxonomy page by splitting topics into logical
+sections, each with one or more examples.
+
+Fixes #9999
+Closes #9998"
+```
+
+Step 7
+: Push the new branch to your fork of the documentation repository.
+
+Step 8
+: Visit the [documentation repository] and create a pull request (PR).
+
+Step 9
+: A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR.
+
+[ATX]: https://spec.commonmark.org/0.30/#atx-headings
+[Microsoft Writing Style Guide]: https://learn.microsoft.com/en-us/style-guide/welcome/
+[basic english]: https://simple.wikipedia.org/wiki/Basic_English
+[code examples]: #code-examples
+[code shortcode]: #code
+[code-toggle shortcode]: #code-toggle
+[documentation repository]: https://github.com/gohugoio/hugoDocs/
+[fenced code blocks]: https://spec.commonmark.org/0.30/#fenced-code-blocks
+[glossary of terms]: /getting-started/glossary/
+[indented code blocks]: https://spec.commonmark.org/0.30/#indented-code-blocks
+[issues]: https://github.com/gohugoio/hugoDocs/issues
+[list items]: https://spec.commonmark.org/0.30/#list-items
+[note shortcode]: #note
+[project repository]: https://github.com/gohugoio/hugo
+[raw HTML]: https://spec.commonmark.org/0.30/#raw-html
+[setext]: https://spec.commonmark.org/0.30/#setext-heading
--- /dev/null
- Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+---
+cascade:
+ _build:
+ list: never
+ publishResources: false
+ render: never
+---
+
+<!--
++Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+
+Include the rendered content using the "include" shortcode.
+-->
--- /dev/null
--- /dev/null
++---
++# Do not remove front matter.
++---
++
++Hugo uses Go's [text/template] and [html/template] packages.
++
++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.
++
++By default, Hugo uses the html/template package when rendering HTML files.
++
++To generate HTML output that is safe against code injection, the html/template package escapes strings in certain contexts.
++
++[text/template]: https://pkg.go.dev/text/template
++[html/template]: https://pkg.go.dev/html/template
--- /dev/null
- linkTitle: Overview
+---
+title: Functions
- identifier: functions-overview
++linkTitle: In this section
+description: A list of Hugo template functions including examples.
+categories: []
+keywords: []
+menu:
+ docs:
++ identifier: functions-in-this-section
+ parent: functions
+ weight: 10
+weight: 10
+showSectionMenu: true
+aliases: [/layout/functions/,/templates/functions]
+---
+
+Use these functions within your templates and archetypes.
--- /dev/null
- [`first`]: /functions/collections/first
- [list/section page]: /templates/section-templates
+---
+title: collections.After
+description: Slices an array to the items after the Nth item.
+categories: []
+keywords: []
+action:
+ aliases: [after]
+ related:
+ - functions/collections/First
+ - functions/collections/Last
+ returnType: any
+ signatures: [collections.After INDEX COLLECTION]
+aliases: [/functions/after]
+---
+
+The following shows `after` being used in conjunction with the [`slice`]function:
+
+```go-html-template
+{{ $data := slice "one" "two" "three" "four" }}
+<ul>
+ {{ range after 2 $data }}
+ <li>{{ . }}</li>
+ {{ end }}
+</ul>
+```
+
+The template above is rendered to:
+
+```html
+<ul>
+ <li>three</li>
+ <li>four</li>
+</ul>
+```
+
+## Example of `after` with `first`: 2nd–4th most recent articles
+
+You can use `after` in combination with the [`first`] function and Hugo's [powerful sorting methods][lists]. Let's assume you have a list page at `example.com/articles`. You have 10 articles, but you want your templating for the [list/section page] to show only two rows:
+
+1. The top row is titled "Featured" and shows only the most recently published article (i.e. by `publishdate` in the content files' front matter).
+2. The second row is titled "Recent Articles" and shows only the 2nd- to 4th-most recently published articles.
+
+{{< code file=layouts/section/articles.html >}}
+{{ define "main" }}
+ <section class="row featured-article">
+ <h2>Featured Article</h2>
+ {{ range first 1 .Pages.ByPublishDate.Reverse }}
+ <header>
+ <h3><a href="{{ .RelPermalink }}">{{ .Title }}</a></h3>
+ </header>
+ <p>{{ .Description }}</p>
+ {{ end }}
+ </section>
+ <div class="row recent-articles">
+ <h2>Recent Articles</h2>
+ {{ range first 3 (after 1 .Pages.ByPublishDate.Reverse) }}
+ <section class="recent-article">
+ <header>
+ <h3><a href="{{ .RelPermalink }}">{{ .Title }}</a></h3>
+ </header>
+ <p>{{ .Description }}</p>
+ </section>
+ {{ end }}
+ </div>
+{{ end }}
+{{< /code >}}
+
++[`first`]: /functions/collections/first/
++[list/section page]: /templates/section-templates/
+[lists]: /templates/lists/#sort-content
+[`slice`]: /functions/collections/slice/
--- /dev/null
- [`where`]: /functions/collections/where
+---
+title: collections.Complement
+description: Returns the elements of the last collection that are not in any of the others.
+categories: []
+keywords: []
+action:
+ aliases: [complement]
+ related:
+ - functions/collections/Intersect
+ - functions/collections/SymDiff
+ - functions/collections/Union
+ returnType: any
+ signatures: ['collections.Complement COLLECTION [COLLECTION...]']
+aliases: [/functions/complement]
+---
+
+To find the elements within `$c3` that do not exist in `$c1` or `$c2`:
+
+```go-html-template
+{{ $c1 := slice 3 }}
+{{ $c2 := slice 4 5 }}
+{{ $c3 := slice 1 2 3 4 5 }}
+
+{{ complement $c1 $c2 $c3 }} → [1 2]
+```
+
+{{% note %}}
+Make your code simpler to understand by using a [chained pipeline]:
+
+[chained pipeline]: https://pkg.go.dev/text/template#hdr-Pipelines
+{{% /note %}}
+
+```go-html-template
+{{ $c3 | complement $c1 $c2 }} → [1 2]
+```
+
+You can also use the `complement` function with page collections. Let's say your site has five content types:
+
+```text
+content/
+├── blog/
+├── books/
+├── faqs/
+├── films/
+└── songs/
+```
+
+To list everything except blog articles (`blog`) and frequently asked questions (`faqs`):
+
+```go-html-template
+{{ $blog := where site.RegularPages "Type" "blog" }}
+{{ $faqs := where site.RegularPages "Type" "faqs" }}
+{{ range site.RegularPages | complement $blog $faqs }}
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+{{ end }}
+```
+
+{{% note %}}
+Although the example above demonstrates the `complement` function, you could use the [`where`] function as well:
+
++[`where`]: /functions/collections/where/
+{{% /note %}}
+
+```go-html-template
+{{ range where site.RegularPages "Type" "not in" (slice "blog" "faqs") }}
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+{{ end }}
+```
+
+In this example we use the `complement` function to remove [stop words] from a sentence:
+
+```go-html-template
+{{ $text := "The quick brown fox jumps over the lazy dog" }}
+{{ $stopWords := slice "a" "an" "in" "over" "the" "under" }}
+{{ $filtered := split $text " " | complement $stopWords }}
+
+{{ delimit $filtered " " }} → The quick brown fox jumps lazy dog
+```
+
+[stop words]: https://en.wikipedia.org/wiki/Stop_word
--- /dev/null
- description: Creates a map from a list of key and value pairs.
+---
+title: collections.Dictionary
- signatures: ['collections.Dictionary KEY VALUE [VALUE...]']
++description: Returns a map composed of the given key-value pairs.
+categories: []
+keywords: []
+action:
+ aliases: [dict]
+ related:
+ - functions/collections/Slice
+ returnType: mapany
-
- ## Pass values to a partial template
-
- The partial below creates an SVG and expects `fill`, `height` and `width` from the caller:
-
- ### Partial definition
-
- {{< code file=layouts/partials/svgs/external-links.svg >}}
- <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
- fill="{{ .fill }}" width="{{ .width }}" height="{{ .height }}" viewBox="0 0 32 32" aria-label="External Link">
- <path d="M25.152 16.576v5.696q0 2.144-1.504 3.648t-3.648 1.504h-14.848q-2.144 0-3.648-1.504t-1.504-3.648v-14.848q0-2.112 1.504-3.616t3.648-1.536h12.576q0.224 0 0.384 0.16t0.16 0.416v1.152q0 0.256-0.16 0.416t-0.384 0.16h-12.576q-1.184 0-2.016 0.832t-0.864 2.016v14.848q0 1.184 0.864 2.016t2.016 0.864h14.848q1.184 0 2.016-0.864t0.832-2.016v-5.696q0-0.256 0.16-0.416t0.416-0.16h1.152q0.256 0 0.416 0.16t0.16 0.416zM32 1.152v9.12q0 0.48-0.352 0.8t-0.8 0.352-0.8-0.352l-3.136-3.136-11.648 11.648q-0.16 0.192-0.416 0.192t-0.384-0.192l-2.048-2.048q-0.192-0.16-0.192-0.384t0.192-0.416l11.648-11.648-3.136-3.136q-0.352-0.352-0.352-0.8t0.352-0.8 0.8-0.352h9.12q0.48 0 0.8 0.352t0.352 0.8z"></path>
- </svg>
- {{< /code >}}
-
- ### Partial call
-
- The `fill`, `height` and `width` values can be stored in one object with `dict` and passed to the partial:
-
- {{< code file=layouts/_default/list.html >}}
- {{ partial "svgs/external-links.svg" (dict "fill" "#01589B" "width" 10 "height" 20 ) }}
- {{< /code >}}
-
- [partials]: /templates/partials/
++ signatures: ['collections.Dictionary [VALUE...]']
+aliases: [/functions/dict]
+---
+
++Specify the key-value pairs as individual arguments:
++
+```go-html-template
+{{ $m := dict "a" 1 "b" 2 }}
+```
+
+The above produces this data structure:
+
+```json
+{
+ "a": 1,
+ "b": 2
+}
+```
+
++To create an empty map:
++
++```go-html-template
++{{ $m := dict }}
++```
++
+
+Note that the `key` can be either a `string` or a `string slice`. The latter is useful to create a deeply nested structure, e.g.:
+
+```go-html-template
+{{ $m := dict (slice "a" "b" "c") "value" }}
+```
+
+The above produces this data structure:
+
+```json
+{
+ "a": {
+ "b": {
+ "c": "value"
+ }
+ }
+}
+```
--- /dev/null
- [`where`]: /functions/collections/where
+---
+title: collections.First
+description: Returns the given collection, limited to the first N elements.
+categories: []
+keywords: []
+action:
+ aliases: [first]
+ related:
+ - functions/collections/After
+ - functions/collections/Last
+ - methods/pages/Limit
+ returnType: any
+ signatures: [collections.First N COLLECTION]
+aliases: [/functions/first]
+---
+
+```go-html-template
+{{ range first 5 .Pages }}
+ {{ .Render "summary" }}
+{{ end }}
+```
+
+Set `N` to zero to return an empty collection.
+
+```go-html-template
+{{ $emptyPageCollection := first 0 .Pages}}
+```
+
+Use `first` and [`where`] together.
+
+```go-html-template
+{{ range where .Pages "Section" "articles" | first 5 }}
+ {{ .Render "summary" }}
+{{ end }}
+```
+
++[`where`]: /functions/collections/where/
--- /dev/null
- description: Looks up the index(es) or key(s) of the data structure passed into it.
+---
+title: collections.Index
- - collections.Index COLLECTION INDEXES
- - collections.Index COLLECTION KEYS
++description: Returns the object, element, or value associated with the given key or keys.
+categories: []
+keywords: []
+action:
+ aliases: [index]
+ related: []
+ returnType: any
+ signatures:
- The `index` functions returns the result of indexing its first argument by the following arguments. Each indexed item must be a map or a slice, e.g.:
++ - collections.Index COLLECTION KEY...
+aliases: [/functions/index,/functions/index-function]
+---
+
- {{ $slice := slice "a" "b" "c" }}
- {{ index $slice 0 }} → a
- {{ index $slice 1 }} → b
++Each indexed item must be a map or a slice:
+
+```go-html-template
- {{ $map := dict "a" 100 "b" 200 }}
- {{ index $map "b" }} → 200
++{{ $s := slice "a" "b" "c" }}
++{{ index $s 0 }} → a
++{{ index $s 1 }} → b
+
- The function takes multiple indices as arguments, and this can be used to get nested values, e.g.:
++{{ $m := dict "a" 100 "b" 200 }}
++{{ index $m "b" }} → 200
+```
+
- {{ $map := dict "a" 100 "b" 200 "c" (slice 10 20 30) }}
- {{ index $map "c" 1 }} → 20
- {{ $map := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }}
- {{ index $map "c" "e" }} → 20
- ```
-
- You may write multiple indices as a slice:
-
- ```go-html-template
- {{ $map := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }}
- {{ $slice := slice "c" "e" }}
- {{ index $map $slice }} → 20
- ```
-
- ## Example: load data from a path based on front matter parameters
++Use two or more keys to access a nested value:
+
+```go-html-template
- Assume you want to add a `location = ""` field to your front matter for every article written in `content/vacations/`. You want to use this field to populate information about the location at the bottom of the article in your `single.html` template. You also have a directory in `data/locations/` that looks like the following:
-
- ```text
- data/
- └── locations/
- ├── abilene.toml
- ├── chicago.toml
- ├── oslo.toml
- └── provo.toml
++{{ $m := dict "a" 100 "b" 200 "c" (slice 10 20 30) }}
++{{ index $m "c" 1 }} → 20
+
- Here is an example:
-
- {{< code-toggle file=data/locations/oslo >}}
- website = "https://www.oslo.kommune.no"
- pop_city = 658390
- pop_metro = 1717900
- {{< /code-toggle >}}
-
- The example we will use will be an article on Oslo, whose front matter should be set to exactly the same name as the corresponding file name in `data/locations/`:
-
- {{< code-toggle file=content/articles/oslo.md fm=true >}}
- title = "My Norwegian Vacation"
- location = "oslo"
- {{< /code-toggle >}}
-
- The content of `oslo.toml` can be accessed from your template using the following node path: `.Site.Data.locations.oslo`. However, the specific file you need is going to change according to the front matter.
-
- This is where the `index` function is needed. `index` takes 2 arguments in this use case:
-
- 1. The node path
- 2. A string corresponding to the desired data; e.g.—
++{{ $m := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }}
++{{ index $m "c" "e" }} → 20
+```
+
- {{ index .Site.Data.locations "oslo" }}
++You may also use a slice of keys to access a nested value:
+
+```go-html-template
- The variable for `.Params.location` is a string and can therefore replace `oslo` in the example above:
++{{ $m := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }}
++{{ $s := slice "c" "e" }}
++{{ index $m $s }} → 20
+```
+
- {{ index .Site.Data.locations .Params.location }}
- => map[website:https://www.oslo.kommune.no pop_city:658390 pop_metro:1717900]
- ```
++Use the `collections.Index` function to access a nested value when the key is variable. For example, these are equivalent:
+
+```go-html-template
- Now the call will return the specific file according to the location specified in the content's front matter, but you will likely want to write specific properties to the template. You can do this by continuing down the node path via dot notation (`.`):
-
- ```go-html-template
- {{ (index .Site.Data.locations .Params.location).pop_city }}
- => 658390
++{{ .Site.Params.foo }}
+
++{{ $k := "foo" }}
++{{ index .Site.Params $k }}
+```
--- /dev/null
- signatures: [collections.KeyVals KEY VALUES...]
+---
+title: collections.KeyVals
+description: Returns a KeyVals struct.
+categories: []
+keywords: []
+action:
+ aliases: [keyVals]
+ related:
+ - methods/pages/Related
+ returnType: types.KeyValues
- The primary application for this function is the definition of the `namedSlices` parameter in the options map passed to the [`Related`] method on the `Pages` object.
++ signatures: [collections.KeyVals KEY VALUE...]
+aliases: [/functions/keyvals]
+---
+
- [`Related`]: /methods/pages/related
++The primary application for this function is the definition of the `namedSlices` value in the options map passed to the [`Related`] method on the `Pages` object.
+
++[`Related`]: /methods/pages/related/
+
+See [related content](/content-management/related).
+
+```go-html-template
+{{ $kv := keyVals "foo" "a" "b" "c" }}
+```
+
+The resulting data structure is:
+
+```json
+{
+ "Key": "foo",
+ "Values": [
+ "a",
+ "b",
+ "c"
+ ]
+}
+```
+
+To extract the key and values:
+
+```go-html-template
+{{ $kv.Key }} → foo
+{{ $kv.Values }} → [a b c]
+```
--- /dev/null
- [`Scratch`]: /methods/page/scratch
- [`Store`]: /methods/page/store
+---
+title: collections.NewScratch
+description: Returns a locally scoped "scratch pad" to store and manipulate data.
+categories: []
+keywords: []
+action:
+ aliases: [newScratch]
+ related:
+ - methods/page/scratch
+ - methods/page/store
+ - methods/shortcode/scratch
+ returnType: maps.Scratch
+ signatures: [collections.NewScratch ]
+---
+
+The `collections.NewScratch` function creates a locally scoped [scratch pad] to store and manipulate data. To create a scratch pad that is attached to a `Page` object, use the [`Scratch`] or [`Store`] method.
+
++[`Scratch`]: /methods/page/scratch/
++[`Store`]: /methods/page/store/
+[scratch pad]: /getting-started/glossary/#scratch-pad
+
+## Methods
+
+###### Set
+
+Sets the value of a given key.
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.Set "greeting" "Hello" }}
+```
+
+###### Get
+
+Gets the value of a given key.
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.Set "greeting" "Hello" }}
+{{ $s.Get "greeting" }} → Hello
+```
+
+###### Add
+
+Adds a given value to existing value(s) of the given key.
+
+For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list.
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.Set "greeting" "Hello" }}
+{{ $s.Add "greeting" "Welcome" }}
+{{ $s.Get "greeting" }} → HelloWelcome
+```
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.Set "total" 3 }}
+{{ $s.Add "total" 7 }}
+{{ $s.Get "total" }} → 10
+```
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.Set "greetings" (slice "Hello") }}
+{{ $s.Add "greetings" (slice "Welcome" "Cheers") }}
+{{ $s.Get "greetings" }} → [Hello Welcome Cheers]
+```
+
+###### SetInMap
+
+Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`.
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.SetInMap "greetings" "english" "Hello" }}
+{{ $s.SetInMap "greetings" "french" "Bonjour" }}
+{{ $s.Get "greetings" }} → map[english:Hello french:Bonjour]
+```
+
+###### DeleteInMap
+
+Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.SetInMap "greetings" "english" "Hello" }}
+{{ $s.SetInMap "greetings" "french" "Bonjour" }}
+{{ $s.DeleteInMap "greetings" "english" }}
+{{ $s.Get "greetings" }} → map[french:Bonjour]
+```
+
+###### GetSortedMapValues
+
+Returns an array of values from `key` sorted by `mapKey`.
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.SetInMap "greetings" "english" "Hello" }}
+{{ $s.SetInMap "greetings" "french" "Bonjour" }}
+{{ $s.GetSortedMapValues "greetings" }} → [Hello Bonjour]
+```
+
+###### Delete
+
+Removes the given key.
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.Set "greeting" "Hello" }}
+{{ $s.Delete "greeting" }}
+```
+
+###### Values
+
+Returns the raw backing map. Do not use with `Scratch` or `Store` methods on a `Page` object due to concurrency issues.
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.SetInMap "greetings" "english" "Hello" }}
+{{ $s.SetInMap "greetings" "french" "Bonjour" }}
+
+{{ $map := $s.Values }}
+```
--- /dev/null
- description: Takes a set or slice of key-value pairs and returns a query string to be appended to URLs.
+---
+title: collections.Querify
- - collections.Querify VALUE [VALUE...]
- - collections.Querify COLLECTION
++description: Returns a URL query string composed of the given key-value pairs.
+categories: []
+keywords: []
+action:
+ aliases: [querify]
+ related:
+ - functions/go-template/urlquery.md
+ returnType: string
+ signatures:
- `querify` takes a set or slice of key-value pairs and returns a [query string](https://en.wikipedia.org/wiki/Query_string) that can be appended to a URL.
++ - collections.Querify [VALUE...]
+aliases: [/functions/querify]
+---
+
- The following examples create a link to a search results page on Google.
++Specify the key-value pairs as individual arguments, or as a slice. The following are equivalent:
+
- <a href="https://www.google.com?{{ (querify "q" "test" "page" 3) | safeURL }}">Search</a>
+
+```go-html-template
- {{ $qs := slice "q" "test" "page" 3 }}
- <a href="https://www.google.com?{{ (querify $qs) | safeURL }}">Search</a>
++{{ collections.Querify "a" 1 "b" 2 }}
++{{ collections.Querify (slice "a" 1 "b" 2) }}
++```
++
++To append a query string to a URL:
++
++```go-html-template
++{{ $qs := collections.Querify "a" 1 "b" 2 }}
++{{ $href := printf "https://example.org?%s" $qs }}
+
- Both of these examples render the following HTML:
++<a href="{{ $href }}">Link</a>
+```
+
- <a href="https://www.google.com?page=3&q=test">Search</a>
++Hugo renders this to:
+
+```html
++<a href="https://example.org?a=1&b=2">Link</a>
+```
--- /dev/null
- description: Creates a slice of all passed arguments.
+---
+title: collections.Slice
- signatures: [collections.Slice ITEM...]
++description: Returns a slice composed of the given values.
+categories: []
+keywords: []
+action:
+ aliases: [slice]
+ related:
+ - functions/collections/Dictionary
+ returnType: any
++ signatures: ['collections.Slice [VALUE...]']
+aliases: [/functions/slice]
+---
+
+```go-html-template
+{{ $s := slice "a" "b" "c" }}
+{{ $s }} → [a b c]
+```
++
++To create an empty slice:
++
++```go-html-template
++{{ $s := slice }}
++```
--- /dev/null
- [sorting and grouping methods]: /methods/pages
+---
+title: collections.Sort
+description: Sorts slices, maps, and page collections.
+categories: []
+keywords: []
+action:
+ aliases: [sort]
+ related:
+ - functions/collections/Reverse
+ - functions/collections/Shuffle
+ - functions/collections/Uniq
+ returnType: any
+ signatures: ['collections.Sort COLLECTION [KEY] [ORDER]']
+toc: true
+aliases: [/functions/sort]
+---
+
+The `KEY` is optional when sorting slices in ascending order, otherwise it is required. When sorting slices, use the literal `value` in place of the `KEY`. See examples below.
+
+The `ORDER` may be either `asc` (ascending) or `desc` (descending). The default sort order is ascending.
+
+## Sort a slice
+
+The examples below assume this site configuration:
+
+{{< code-toggle file=hugo >}}
+[params]
+grades = ['b','a','c']
+{{< /code-toggle >}}
+
+### Ascending order {#slice-ascending-order}
+
+Sort slice elements in ascending order using either of these constructs:
+
+```go-html-template
+{{ sort site.Params.grades }} → [a b c]
+{{ sort site.Params.grades "value" "asc" }} → [a b c]
+```
+
+In the examples above, `value` is the `KEY` representing the value of the slice element.
+
+### Descending order {#slice-descending-order}
+
+Sort slice elements in descending order:
+
+```go-html-template
+{{ sort site.Params.grades "value" "desc" }} → [c b a]
+```
+
+In the example above, `value` is the `KEY` representing the value of the slice element.
+
+## Sort a map
+
+The examples below assume this site configuration:
+
+{{< code-toggle file=hugo >}}
+[params.authors.a]
+firstName = "Marius"
+lastName = "Pontmercy"
+[params.authors.b]
+firstName = "Victor"
+lastName = "Hugo"
+[params.authors.c]
+firstName = "Jean"
+lastName = "Valjean"
+{{< /code-toggle >}}
+
+{{% note %}}
+When sorting maps, the `KEY` argument must be lowercase.
+{{% /note %}}
+
+### Ascending order {#map-ascending-order}
+
+Sort map objects in ascending order using either of these constructs:
+
+```go-html-template
+{{ range sort site.Params.authors "firstname" }}
+ {{ .firstName }}
+{{ end }}
+
+{{ range sort site.Params.authors "firstname" "asc" }}
+ {{ .firstName }}
+{{ end }}
+```
+
+These produce:
+
+```text
+Jean Marius Victor
+```
+
+### Descending order {#map-descending-order}
+
+Sort map objects in descending order:
+
+```go-html-template
+{{ range sort site.Params.authors "firstname" "desc" }}
+ {{ .firstName }}
+{{ end }}
+```
+
+This produces:
+
+```text
+Victor Marius Jean
+```
+
+### First level key removal
+
+Hugo removes the first level keys when sorting a map.
+
+Original map:
+
+```json
+{
+ "felix": {
+ "breed": "malicious",
+ "type": "cat"
+ },
+ "spot": {
+ "breed": "boxer",
+ "type": "dog"
+ }
+}
+```
+
+After sorting:
+
+```json
+[
+ {
+ "breed": "malicious",
+ "type": "cat"
+ },
+ {
+ "breed": "boxer",
+ "type": "dog"
+ }
+]
+```
+
+## Sort a page collection
+
+{{% note %}}
+Although you can use the `sort` function to sort a page collection, Hugo provides [sorting and grouping methods] as well.
+
++[sorting and grouping methods]: /methods/pages/
+{{% /note %}}
+
+In this contrived example, sort the site's regular pages by `.Type` in descending order:
+
+```go-html-template
+{{ range sort site.RegularPages "Type" "desc" }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
--- /dev/null
- The `where` function returns the given collection, removing elements that do not satisfy the comparison condition. The comparison condition is comprised of the `KEY`, `OPERATOR`, and `VALUE` arguments:
+---
+title: collections.Where
+description: Returns the given collection, removing elements that do not satisfy the comparison condition.
+categories: []
+keywords: []
+action:
+ aliases: [where]
+ related: []
+ returnType: any
+ signatures: ['collections.Where COLLECTION KEY [OPERATOR] VALUE']
+toc: true
+aliases: [/functions/where]
+---
+
- [`date`]: /methods/page/date
- [`publishdate`]: /methods/page/publishdate
- [`lastmod`]: /methods/page/lastmod
- [`expirydate`]: /methods/page/expirydate
++The `where` function returns the given collection, removing elements that do not satisfy the comparison condition. The comparison condition is composed of the `KEY`, `OPERATOR`, and `VALUE` arguments:
+
+```text
+collections.Where COLLECTION KEY [OPERATOR] VALUE
+ --------------------
+ comparison condition
+```
+
+Hugo will test for equality if you do not provide an `OPERATOR` argument. For example:
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Section" "books" }}
+{{ $books := where .Site.Data.books "genres" "suspense" }}
+```
+
+## Arguments
+
+The where function takes three or four arguments. The `OPERATOR` argument is optional.
+
+COLLECTION
+: (`any`) A [page collection] or a [slice] of [maps].
+
+[maps]: /getting-started/glossary/#map
+[page collection]: /getting-started/glossary/#page-collection
+[slice]: /getting-started/glossary/#slice
+
+KEY
+: (`string`) The key of the page or map value to compare with `VALUE`. With page collections, commonly used comparison keys are `Section`, `Type`, and `Params`. To compare with a member of the page `Params` map, [chain] the subkey as shown below:
+
+```go-html-template
+{{ $result := where .Site.RegularPages "Params.foo" "bar" }}
+```
+
+[chain]: /getting-started/glossary/#chain
+
+OPERATOR
+: (`string`) The logical comparison [operator](#operators).
+
+VALUE
+: (`any`) The value with which to compare. The values to compare must have comparable data types. For example:
+
+Comparison|Result
+:--|:--
+`"123" "eq" "123"`|`true`
+`"123" "eq" 123`|`false`
+`false "eq" "false"`|`false`
+`false "eq" false`|`true`
+
+When one or both of the values to compare is a slice, use the `in`, `not in`, or `intersect` operators as described below.
+
+## Operators
+
+Use any of the following logical operators:
+
+`=`, `==`, `eq`
+: (`bool`) Reports whether the given field value is equal to `VALUE`.
+
+`!=`, `<>`, `ne`
+: (`bool`) Reports whether the given field value is not equal to `VALUE`.
+
+`>=`, `ge`
+: (`bool`) Reports whether the given field value is greater than or equal to `VALUE`.
+
+`>`, `gt`
+: `true` Reports whether the given field value is greater than `VALUE`.
+
+`<=`, `le`
+: (`bool`) Reports whether the given field value is less than or equal to `VALUE`.
+
+`<`, `lt`
+: (`bool`) Reports whether the given field value is less than `VALUE`.
+
+`in`
+: (`bool`) Reports whether the given field value is a member of `VALUE`. Compare string to slice, or string to string. See [details](/functions/collections/in).
+
+`not in`
+: (`bool`) Reports whether the given field value is not a member of `VALUE`. Compare string to slice, or string to string. See [details](/functions/collections/in).
+
+`intersect`
+: (`bool`) Reports whether the given field value (a slice) contains one or more elements in common with `VALUE`. See [details](/functions/collections/intersect).
+
+`like` {{< new-in 0.116.0 >}}
+: (`bool`) Reports whether the given field value matches the regular expression specified in `VALUE`. Use the `like` operator to compare `string` values. The `like` operator returns `false` when comparing other data types to the regular expression.
+
+{{% note %}}
+The examples below perform comparisons within a page collection, but the same comparisons are applicable to a slice of maps.
+{{% /note %}}
+
+## String comparison
+
+Compare the value of the given field to a [`string`]:
+
+[`string`]: /getting-started/glossary/#string
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Section" "eq" "books" }}
+{{ $pages := where .Site.RegularPages "Section" "ne" "books" }}
+```
+
+## Numeric comparison
+
+Compare the value of the given field to an [`int`] or [`float`]:
+
+[`int`]: /getting-started/glossary/#int
+[`float`]: /getting-started/glossary/#float
+
+```go-html-template
+{{ $books := where site.RegularPages "Section" "eq" "books" }}
+
+{{ $pages := where $books "Params.price" "eq" 42 }}
+{{ $pages := where $books "Params.price" "ne" 42.67 }}
+{{ $pages := where $books "Params.price" "ge" 42 }}
+{{ $pages := where $books "Params.price" "gt" 42.67 }}
+{{ $pages := where $books "Params.price" "le" 42 }}
+{{ $pages := where $books "Params.price" "lt" 42.67 }}
+```
+
+## Boolean comparison
+
+Compare the value of the given field to a [`bool`]:
+
+[`bool`]: /getting-started/glossary/#bool
+
+```go-html-template
+{{ $books := where site.RegularPages "Section" "eq" "books" }}
+
+{{ $pages := where $books "Params.fiction" "eq" true }}
+{{ $pages := where $books "Params.fiction" "eq" false }}
+{{ $pages := where $books "Params.fiction" "ne" true }}
+{{ $pages := where $books "Params.fiction" "ne" false }}
+```
+
+## Member comparison
+
+Compare a [`scalar`] to a [`slice`].
+
+[`scalar`]: /getting-started/glossary/#scalar
+[`slice`]: /getting-started/glossary/#slice
+
+For example, to return a collection of pages where the `color` page parameter is either "red" or "yellow":
+
+```go-html-template
+{{ $fruit := where site.RegularPages "Section" "eq" "fruit" }}
+
+{{ $colors := slice "red" "yellow" }}
+{{ $pages := where $fruit "Params.color" "in" $colors }}
+```
+
+To return a collection of pages where the "color" page parameter is neither "red" nor "yellow":
+
+```go-html-template
+{{ $fruit := where site.RegularPages "Section" "eq" "fruit" }}
+
+{{ $colors := slice "red" "yellow" }}
+{{ $pages := where $fruit "Params.color" "not in" $colors }}
+```
+
+## Intersection comparison
+
+Compare a [`slice`] to a [`slice`], returning collection elements with common values. This is frequently used when comparing taxonomy terms.
+
+For example, to return a collection of pages where any of the terms in the "genres" taxonomy are "suspense" or "romance":
+
+```go-html-template
+{{ $books := where site.RegularPages "Section" "eq" "books" }}
+
+{{ $genres := slice "suspense" "romance" }}
+{{ $pages := where $books "Params.genres" "intersect" $genres }}
+```
+
+## Regular expression comparison
+
+{{< new-in 0.116.0 >}}
+
+To return a collection of pages where the "author" page parameter begins with either "victor" or "Victor":
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Params.author" "like" `(?i)^victor` }}
+```
+
+{{% include "functions/_common/regular-expressions.md" %}}
+
+{{% note %}}
+Use the `like` operator to compare string values. Comparing other data types will result in an empty collection.
+{{% /note %}}
+
+## Date comparison
+
+### Predefined dates
+
+There are four predefined front matter dates: [`date`], [`publishDate`], [`lastmod`], and [`expiryDate`]. Regardless of the front matter data format (TOML, YAML, or JSON) these are [`time.Time`] values, allowing precise comparisons.
+
- When working with YAML or JSON, or quoted TOML values, custom dates are strings; you cannot compare them with `time.Time` values. String comparisons may be possible if the custom date layout is consistent from one page to the next. However, to be safe, filter the pages by ranging through the collection:
++[`date`]: /methods/page/date/
++[`publishdate`]: /methods/page/publishdate/
++[`lastmod`]: /methods/page/lastmod/
++[`expirydate`]: /methods/page/expirydate/
+[`time.Time`]: https://pkg.go.dev/time#Time
+
+For example, to return a collection of pages that were created before the current year:
+
+```go-html-template
+{{ $startOfYear := time.AsTime (printf "%d-01-01" now.Year) }}
+{{ $pages := where .Site.RegularPages "Date" "lt" $startOfYear }}
+```
+
+### Custom dates
+
+With custom front matter dates, the comparison depends on the front matter data format (TOML, YAML, or JSON).
+
+{{% note %}}
+Using TOML for pages with custom front matter dates enables precise date comparisons.
+{{% /note %}}
+
+With TOML, date values are first-class citizens. TOML has a date data type while JSON and YAML do not. If you quote a TOML date, it is a string. If you do not quote a TOML date value, it is [`time.Time`] value, enabling precise comparisons.
+
+In the TOML example below, note that the event date is not quoted.
+
+{{< code file="content/events/2024-user-conference.md" >}}
++++
+title = '2024 User Conference"
+eventDate = 2024-04-01
++++
+{{< /code >}}
+
+To return a collection of future events:
+
+```go-html-template
+{{ $events := where .Site.RegularPages "Type" "events" }}
+{{ $futureEvents := where $events "Params.eventDate" "gt" now }}
+```
+
- [`MainSections`]: /methods/site/mainsections
++When working with YAML or JSON, or quoted TOML values, custom dates are strings; you cannot compare them with `time.Time` values. String comparisons may be possible if the custom date layout is consistent from one page to the next. To be safe, filter the pages by ranging through the collection:
+
+```go-html-template
+{{ $events := where .Site.RegularPages "Type" "events" }}
+{{ $futureEvents := slice }}
+{{ range $events }}
+ {{ if gt (time.AsTime .Params.eventDate) now }}
+ {{ $futureEvents = $futureEvents | append . }}
+ {{ end }}
+{{ end }}
+```
+
+## Nil comparison
+
+To return a collection of pages where the "color" parameter is present in front matter, compare to `nil`:
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Params.color" "ne" nil }}
+```
+
+To return a collection of pages where the "color" parameter is not present in front matter, compare to `nil`:
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Params.color" "eq" nil }}
+```
+
+In both examples above, note that `nil` is not quoted.
+
+## Nested comparison
+
+These are equivalent:
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Type" "tutorials" }}
+{{ $pages = where $pages "Params.level" "eq" "beginner" }}
+```
+
+```go-html-template
+{{ $pages := where (where .Site.RegularPages "Type" "tutorials") "Params.level" "eq" "beginner" }}
+```
+
+## Portable section comparison
+
+Useful for theme authors, avoid hardcoding section names by using the `where` function with the [`MainSections`] method on a `Site` object.
+
- [`collections.Complement`]: /functions/collections/complement
++[`MainSections`]: /methods/site/mainsections/
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Section" "in" .Site.MainSections }}
+```
+
+With this construct, a theme author can instruct users to specify their main sections in the site configuration:
+
+{{< code-toggle file=hugo >}}
+[params]
+mainSections = ['blog','galleries']
+{{< /code-toggle >}}
+
+If `params.mainSections` is not defined in the site configuration, the `MainSections` method returns a slice with one element---the top level section with the most pages.
+
+## Boolean/undefined comparison
+
+Consider this site content:
+
+```text
+content/
+├── posts/
+│ ├── _index.md
+│ ├── post-1.md <-- front matter: exclude = false
+│ ├── post-2.md <-- front matter: exclude = true
+│ └── post-3.md <-- front matter: exclude not defined
+└── _index.md
+```
+
+The first two pages have an "exclude" field in front matter, but the last page does not. When testing for _equality_, the third page is _excluded_ from the result. When testing for _inequality_, the third page is _included_ in the result.
+
+### Equality test
+
+This template:
+
+```go-html-template
+<ul>
+ {{ range where .Site.RegularPages "Params.exclude" "eq" false }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li><a href="/posts/post-1/">Post 1</a></li>
+</ul>
+```
+
+This template:
+
+```go-html-template
+<ul>
+ {{ range where .Site.RegularPages "Params.exclude" "eq" true }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li><a href="/posts/post-2/">Post 2</a></li>
+</ul>
+```
+
+### Inequality test
+
+This template:
+
+```go-html-template
+<ul>
+ {{ range where .Site.RegularPages "Params.exclude" "ne" false }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li><a href="/posts/post-2/">Post 2</a></li>
+ <li><a href="/posts/post-3/">Post 3</a></li>
+</ul>
+```
+
+This template:
+
+```go-html-template
+<ul>
+ {{ range where .Site.RegularPages "Params.exclude" "ne" true }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li><a href="/posts/post-1/">Post 1</a></li>
+ <li><a href="/posts/post-3/">Post 3</a></li>
+</ul>
+```
+
+To exclude a page with an undefined field from a boolean _inequality_ test:
+
+1. Create a collection using a boolean comparison
+2. Create a collection using a nil comparison
+3. Subtract the second collection from the first collection using the [`collections.Complement`] function.
+
++[`collections.Complement`]: /functions/collections/complement/
+
+This template:
+
+```go-html-template
+{{ $p1 := where .Site.RegularPages "Params.exclude" "ne" true }}
+{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }}
+<ul>
+ {{ range $p1 | complement $p2 }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li><a href="/posts/post-1/">Post 1</a></li>
+</ul>
+```
+
+This template:
+
+```go-html-template
+{{ $p1 := where .Site.RegularPages "Params.exclude" "ne" false }}
+{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }}
+<ul>
+ {{ range $p1 | complement $p2 }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li><a href="/posts/post-1/">Post 2</a></li>
+</ul>
+```
--- /dev/null
- [`or`]: /functions/go-template/or
+---
+title: compare.Default
+description: Returns the second argument if set, else the first argument.
+keywords: []
+action:
+ aliases: [default]
+ related:
+ - functions/compare/Conditional
+ - functions/go-template/Or
+ returnType: any
+ signatures: [compare.Default DEFAULT INPUT]
+aliases: [/functions/default]
+---
+
+The `default` function returns the second argument if set, else the first argument.
+
+{{% note %}}
+When the second argument is the boolean `false` value, the `default` function returns `false`. All _other_ falsy values are considered unset.
+
+{{% include "functions/go-template/_common/truthy-falsy.md" %}}
+
+To set a default value based on truthiness, use the [`or`] operator instead.
+
++[`or`]: /functions/go-template/or/
+{{% /note %}}
+
+The `default` function returns the second argument if set:
+
+```go-html-template
+{{ default 42 1 }} → 1
+{{ default 42 "foo" }} → foo
+{{ default 42 (dict "k" "v") }} → map[k:v]
+{{ default 42 (slice "a" "b") }} → [a b]
+{{ default 42 true }} → true
+
+<!-- As noted above, the boolean "false" is considered set -->
+{{ default 42 false }} → false
+```
+
+The `default` function returns the first argument if the second argument is not set:
+
+```go-html-template
+{{ default 42 0 }} → 42
+{{ default 42 "" }} → 42
+{{ default 42 dict }} → 42
+{{ default 42 slice }} → 42
+{{ default 42 <nil> }} → 42
+```
--- /dev/null
+---
+title: compare.Eq
+description: Returns the boolean truth of arg1 == arg2 || arg1 == arg3.
+categories: []
+keywords: []
+action:
+ aliases: [eq]
+ related:
+ - functions/compare/Ge
+ - functions/compare/Gt
+ - functions/compare/Le
+ - functions/compare/Lt
+ - functions/compare/Ne
+ returnType: bool
+ signatures: ['compare.Eq ARG1 ARG2 [ARG...]']
+aliases: [/functions/eq]
+---
+
+```go-html-template
+{{ eq 1 1 }} → true
+{{ eq 1 2 }} → false
+
+{{ eq 1 1 1 }} → true
+{{ eq 1 1 2 }} → true
+{{ eq 1 2 1 }} → true
+{{ eq 1 2 2 }} → false
+```
++
++You can also use the `compare.Eq` function to compare strings, boolean values, dates, slices, maps, and pages.
--- /dev/null
+---
+title: compare.Ge
+description: Returns the boolean truth of arg1 >= arg2 && arg1 >= arg3.
+categories: []
+keywords: []
+action:
+ aliases: [ge]
+ related:
+ - functions/compare/Eq
+ - functions/compare/Gt
+ - functions/compare/Le
+ - functions/compare/Lt
+ - functions/compare/Ne
+ returnType: bool
+ signatures: ['compare.Ge ARG1 ARG2 [ARG...]']
+aliases: [/functions/ge]
+---
+
+```go-html-template
+{{ ge 1 1 }} → true
+{{ ge 1 2 }} → false
+{{ ge 2 1 }} → true
+
+{{ ge 1 1 1 }} → true
+{{ ge 1 1 2 }} → false
+{{ ge 1 2 1 }} → false
+{{ ge 1 2 2 }} → false
+
+{{ ge 2 1 1 }} → true
+{{ ge 2 1 2 }} → true
+{{ ge 2 2 1 }} → true
+```
++
++Use the `compare.Ge` function to compare other data types as well:
++
++```go-html-template
++{{ ge "ab" "a" }} → true
++{{ ge time.Now (time.AsTime "1964-12-30") }} → true
++{{ ge true false }} → true
++```
--- /dev/null
+---
+title: compare.Gt
+description: Returns the boolean truth of arg1 > arg2 && arg1 > arg3.
+categories: []
+keywords: []
+action:
+ aliases: [gt]
+ related:
+ - functions/compare/Eq
+ - functions/compare/Ge
+ - functions/compare/Le
+ - functions/compare/Lt
+ - functions/compare/Ne
+ returnType: bool
+ signatures: ['compare.Gt ARG1 ARG2 [ARG...]']
+aliases: [/functions/gt]
+---
+
+```go-html-template
+{{ gt 1 1 }} → false
+{{ gt 1 2 }} → false
+{{ gt 2 1 }} → true
+
+{{ gt 1 1 1 }} → false
+{{ gt 1 1 2 }} → false
+{{ gt 1 2 1 }} → false
+{{ gt 1 2 2 }} → false
+
+{{ gt 2 1 1 }} → true
+{{ gt 2 1 2 }} → false
+{{ gt 2 2 1 }} → false
+```
++
++Use the `compare.Gt` function to compare other data types as well:
++
++```go-html-template
++{{ gt "ab" "a" }} → true
++{{ gt time.Now (time.AsTime "1964-12-30") }} → true
++{{ gt true false }} → true
++```
--- /dev/null
+---
+title: compare.Le
+description: Returns the boolean truth of arg1 <= arg2 && arg1 <= arg3.
+categories: []
+keywords: []
+action:
+ aliases: [le]
+ related:
+ - functions/compare/Eq
+ - functions/compare/Ge
+ - functions/compare/Gt
+ - functions/compare/Lt
+ - functions/compare/Ne
+ returnType: bool
+ signatures: ['compare.Le ARG1 ARG2 [ARG...]']
+aliases: [/functions/le]
+---
+
+```go-html-template
+{{ le 1 1 }} → true
+{{ le 1 2 }} → true
+{{ le 2 1 }} → false
+
+{{ le 1 1 1 }} → true
+{{ le 1 1 2 }} → true
+{{ le 1 2 1 }} → true
+{{ le 1 2 2 }} → true
+
+{{ le 2 1 1 }} → false
+{{ le 2 1 2 }} → false
+{{ le 2 2 1 }} → false
+```
++
++Use the `compare.Le` function to compare other data types as well:
++
++```go-html-template
++{{ le "ab" "a" }} → false
++{{ le time.Now (time.AsTime "1964-12-30") }} → false
++{{ le true false }} → false
++```
--- /dev/null
+---
+title: compare.Lt
+description: Returns the boolean truth of arg1 < arg2 && arg1 < arg3.
+categories: []
+keywords: []
+action:
+ aliases: [lt]
+ related:
+ - functions/compare/Eq
+ - functions/compare/Ge
+ - functions/compare/Gt
+ - functions/compare/Le
+ - functions/compare/Ne
+ returnType: bool
+ signatures: ['compare.Lt ARG1 ARG2 [ARG...]']
+aliases: [/functions/lt]
+---
+
+```go-html-template
+{{ lt 1 1 }} → false
+{{ lt 1 2 }} → true
+{{ lt 2 1 }} → false
+
+{{ lt 1 1 1 }} → false
+{{ lt 1 1 2 }} → false
+{{ lt 1 2 1 }} → false
+{{ lt 1 2 2 }} → true
+
+{{ lt 2 1 1 }} → false
+{{ lt 2 1 2 }} → false
+{{ lt 2 2 1 }} → false
+```
++
++Use the `compare.Lt` function to compare other data types as well:
++
++```go-html-template
++{{ lt "ab" "a" }} → false
++{{ lt time.Now (time.AsTime "1964-12-30") }} → false
++{{ lt true false }} → false
++```
--- /dev/null
+---
+title: compare.Ne
+description: Returns the boolean truth of arg1 != arg2 && arg1 != arg3.
+categories: []
+keywords: []
+action:
+ aliases: [ne]
+ related:
+ - functions/compare/Eq
+ - functions/compare/Ge
+ - functions/compare/Gt
+ - functions/compare/Le
+ - functions/compare/Lt
+ returnType: bool
+ signatures: ['compare.Ne ARG1 ARG2 [ARG...]']
+aliases: [/functions/ne]
+---
+
+```go-html-template
+{{ ne 1 1 }} → false
+{{ ne 1 2 }} → true
+
+{{ ne 1 1 1 }} → false
+{{ ne 1 1 2 }} → false
+{{ ne 1 2 1 }} → false
+{{ ne 1 2 2 }} → true
+```
++
++You can also use the `compare.Ne` function to compare strings, boolean values, dates, slices, maps, and pages.
--- /dev/null
- When working with local data, the filepath is relative to the working directory.
+---
+title: data.GetCSV
+description: Returns an array of arrays from a local or remote CSV file, or an error if the file does not exist.
+categories: []
+keywords: []
+action:
+ aliases: [getCSV]
+ related:
+ - functions/data/GetJSON
+ - functions/resources/Get
+ - functions/resources/GetRemote
+ - methods/page/Resources
+ returnType: '[][]string'
+ signatures: ['data.GetCSV SEPARATOR INPUT... [OPTIONS]']
+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
+my-project/
+└── other-files/
+ └── pets.csv
+```
+
+Access the data with either of the following:
+
+```go-html-template
+{{ $data := getCSV "," "other-files/pets.csv" }}
+{{ $data := getCSV "," "other-files/" "pets.csv" }}
+```
+
+{{% note %}}
- {{ $data := "" }}
++When working with local data, the file path is relative to the working directory.
+
+You must not place CSV files in the project's data directory.
+{{% /note %}}
+
+Access remote data with either of the following:
+
+```go-html-template
+{{ $data := getCSV "," "https://example.org/pets.csv" }}
+{{ $data := getCSV "," "https://example.org/" "pets.csv" }}
+```
+
+The resulting data structure is an array of arrays:
+
+```json
+[
+ ["name","type","breed","age"],
+ ["Spot","dog","Collie","3"],
+ ["Felix","cat","Malicious","7"]
+]
+```
+
+## Options
+
+Add headers to the request by providing an options map:
+
+```go-html-template
+{{ $opts := dict "Authorization" "Bearer abcd" }}
+{{ $data := getCSV "," "https://example.org/pets.csv" $opts }}
+```
+
+Add multiple headers using a slice:
+
+```go-html-template
+{{ $opts := dict "X-List" (slice "a" "b" "c") }}
+{{ $data := getCSV "," "https://example.org/pets.csv" $opts }}
+```
+
+## Global resource alternative
+
+Consider using the [`resources.Get`] function with [`transform.Unmarshal`] when accessing a global resource.
+
+```text
+my-project/
+└── assets/
+ └── data/
+ └── pets.csv
+```
+
+```go-html-template
- {{ $data := "" }}
++{{ $data := dict }}
+{{ $p := "data/pets.csv" }}
+{{ with resources.Get $p }}
+ {{ $opts := dict "delimiter" "," }}
+ {{ $data = . | transform.Unmarshal $opts }}
+{{ else }}
+ {{ errorf "Unable to get resource %q" $p }}
+{{ end }}
+```
+
+## Page resource alternative
+
+Consider using the [`Resources.Get`] method with [`transform.Unmarshal`] when accessing a page resource.
+
+```text
+my-project/
+└── content/
+ └── posts/
+ └── my-pets/
+ ├── index.md
+ └── pets.csv
+```
+
+```go-html-template
- {{ $data := "" }}
++{{ $data := dict }}
+{{ $p := "pets.csv" }}
+{{ with .Resources.Get $p }}
+ {{ $opts := dict "delimiter" "," }}
+ {{ $data = . | transform.Unmarshal $opts }}
+{{ else }}
+ {{ errorf "Unable to get resource %q" $p }}
+{{ end }}
+```
+
+## Remote resource alternative
+
+Consider using the [`resources.GetRemote`] function with [`transform.Unmarshal`] when accessing a remote resource to improve error handling and cache control.
+
+```go-html-template
- [`Resources.Get`]: methods/page/Resources
- [`resources.GetRemote`]: /functions/resources/getremote
- [`resources.Get`]: /functions/resources/get
- [`transform.Unmarshal`]: /functions/transform/unmarshal
++{{ $data := dict }}
+{{ $u := "https://example.org/pets.csv" }}
+{{ with resources.GetRemote $u }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else }}
+ {{ $opts := dict "delimiter" "," }}
+ {{ $data = . | transform.Unmarshal $opts }}
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get remote resource %q" $u }}
+{{ end }}
+```
+
++[`Resources.Get`]: /methods/page/resources/
++[`resources.GetRemote`]: /functions/resources/getremote/
++[`resources.Get`]: /functions/resources/get/
++[`transform.Unmarshal`]: /functions/transform/unmarshal/
--- /dev/null
- When working with local data, the filepath is relative to the working directory.
+---
+title: data.GetJSON
+description: Returns a JSON object from a local or remote JSON file, or an error if the file does not exist.
+categories: []
+keywords: []
+action:
+ aliases: [getJSON]
+ related:
+ - functions/data/GetCSV
+ - functions/resources/Get
+ - functions/resources/GetRemote
+ - methods/page/Resources
+ returnType: any
+ signatures: ['data.GetJSON INPUT... [OPTIONS]']
+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
+my-project/
+└── other-files/
+ └── books.json
+```
+
+Access the data with either of the following:
+
+```go-html-template
+{{ $data := getJSON "other-files/books.json" }}
+{{ $data := getJSON "other-files/" "books.json" }}
+```
+
+{{% note %}}
- {{ $data := "" }}
++When working with local data, the file path is relative to the working directory.
+{{% /note %}}
+
+Access remote data with either of the following:
+
+```go-html-template
+{{ $data := getJSON "https://example.org/books.json" }}
+{{ $data := getJSON "https://example.org/" "books.json" }}
+```
+
+The resulting data structure is a JSON object:
+
+```json
+[
+ {
+ "author": "Victor Hugo",
+ "rating": 5,
+ "title": "Les Misérables"
+ },
+ {
+ "author": "Victor Hugo",
+ "rating": 4,
+ "title": "The Hunchback of Notre Dame"
+ }
+]
+```
+
+## Options
+
+Add headers to the request by providing an options map:
+
+```go-html-template
+{{ $opts := dict "Authorization" "Bearer abcd" }}
+{{ $data := getJSON "https://example.org/books.json" $opts }}
+```
+
+Add multiple headers using a slice:
+
+```go-html-template
+{{ $opts := dict "X-List" (slice "a" "b" "c") }}
+{{ $data := getJSON "https://example.org/books.json" $opts }}
+```
+
+## Global resource alternative
+
+Consider using the [`resources.Get`] function with [`transform.Unmarshal`] when accessing a global resource.
+
+```text
+my-project/
+└── assets/
+ └── data/
+ └── books.json
+```
+
+```go-html-template
- {{ $data := "" }}
++{{ $data := dict }}
+{{ $p := "data/books.json" }}
+{{ with resources.Get $p }}
+ {{ $data = . | transform.Unmarshal }}
+{{ else }}
+ {{ errorf "Unable to get resource %q" $p }}
+{{ end }}
+```
+
+## Page resource alternative
+
+Consider using the [`Resources.Get`] method with [`transform.Unmarshal`] when accessing a page resource.
+
+```text
+my-project/
+└── content/
+ └── posts/
+ └── reading-list/
+ ├── books.json
+ └── index.md
+```
+
+```go-html-template
- {{ $data := "" }}
++{{ $data := dict }}
+{{ $p := "books.json" }}
+{{ with .Resources.Get $p }}
+ {{ $data = . | transform.Unmarshal }}
+{{ else }}
+ {{ errorf "Unable to get resource %q" $p }}
+{{ end }}
+```
+
+## Remote resource alternative
+
+Consider using the [`resources.GetRemote`] function with [`transform.Unmarshal`] when accessing a remote resource to improve error handling and cache control.
+
+```go-html-template
- [`Resources.Get`]: methods/page/Resources
- [`resources.GetRemote`]: /functions/resources/getremote
- [`resources.Get`]: /functions/resources/get
- [`transform.Unmarshal`]: /functions/transform/unmarshal
++{{ $data := dict }}
+{{ $u := "https://example.org/books.json" }}
+{{ with resources.GetRemote $u }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else }}
+ {{ $data = . | transform.Unmarshal }}
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get remote resource %q" $u }}
+{{ end }}
+```
+
++[`Resources.Get`]: /methods/page/resources/
++[`resources.GetRemote`]: /functions/resources/getremote/
++[`resources.Get`]: /functions/resources/get/
++[`transform.Unmarshal`]: /functions/transform/unmarshal/
--- /dev/null
- {{ $data := "" }}
- {{ $p := "data/books.json" }}
- {{ with resources.Get $p }}
- {{ $opts := dict "delimiter" "," }}
- {{ $data = . | transform.Unmarshal $opts }}
- {{ else }}
- {{ errorf "Unable to get resource %q" $p }}
- {{ end }}
+---
+title: debug.Dump
+description: Returns an object dump as a string.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related: []
+ returnType: string
+ signatures: [debug.Dump VALUE]
+---
+
+```go-html-template
- ```go-html-template
- <pre>{{ debug.Dump $data }}</pre>
- ```
-
- ```text
- []interface {}{
- map[string]interface {}{
++<pre>{{ debug.Dump site.Data.books }}</pre>
+```
+
- "rating": 5.0,
- "title": "Les Misérables",
++```json
++[
++ {
+ "author": "Victor Hugo",
- map[string]interface {}{
++ "rating": 4,
++ "title": "The Hunchback of Notre Dame"
+ },
- "rating": 4.0,
- "title": "The Hunchback of Notre Dame",
- },
- }
++ {
+ "author": "Victor Hugo",
++ "rating": 5,
++ "title": "Les Misérables"
++ }
++]
+```
+
+{{% note %}}
+Output from this function may change from one release to the next. Use for debugging only.
+{{% /note %}}
--- /dev/null
- INFO timer: name TestSqrt total 12.429355ms
+---
+title: debug.Timer
+description: Creates a named timer that reports elapsed time to the console.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related: []
+ returnType: debug.Timer
+ signatures: [debug.Timer NAME]
+---
+
+{{< new-in 0.120.0 >}}
+
+Use the `debug.Timer` function to determine execution time for a block of code, useful for finding performance bottle necks in templates.
+
+The timer starts when you instantiate it, and stops when you call its `Stop` method.
+
+```go-html-template
+{{ $t := debug.Timer "TestSqrt" }}
+{{ range seq 2000 }}
+ {{ $f := math.Sqrt . }}
+{{ end }}
+{{ $t.Stop }}
+```
+
+Use the `--logLevel info` command line flag when you build the site.
+
+```sh
+hugo --logLevel info
+```
+
+The results are displayed in the console at the end of the build. You can have as many timers as you want and if you don't stop them, they will be stopped at the end of build.
+
+```text
++INFO timer: name TestSqrt count 1002 duration 2.496017496s average 2.491035ms median 2.282291ms
+```
--- /dev/null
- 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:
+---
+title: diagrams.Goat
+description: Converts ASCII art to an SVG diagram, returning a GoAT diagram object.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related: []
+ returnType: diagrams.goatDiagram
+ signatures: ['diagrams.Goat INPUT']
+toc: true
+---
+
- [render hook]: https://gohugo.io/templates/render-hooks/
++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
- Hugo natively supports [GoAT] diagrams.
++[code block render hook]: /render-hooks/code-blocks/
+
+Inner
+: (`template.HTML`) Returns the SVG child elements without a wrapping `svg` element, allowing you to create your own wrapper.
+
+Wrapped
+: (`template.HTML`) Returns the SVG child elements wrapped in an `svg` element.
+
+Width
+: (`int`) Returns the width of the rendered diagram, in pixels.
+
+Height
+: (`int`) Returns the height of the rendered diagram, in pixels.
+
+## GoAT Diagrams
+
- This markdown:
++Hugo natively supports [GoAT](https://github.com/bep/goat) diagrams with an [embedded code block render hook].
+
- To customize rendering, override Hugo's [built-in code block render hook] for GoAT diagrams.
-
- [built-in code block render hook]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/_markup/render-codeblock-goat.html
++[embedded code block render hook]: {{% eturl render-codeblock-goat %}}
++
++This Markdown:
+
+````
+```goat
+.---. .-. .-. .-. .---.
+| A +--->| 1 |<--->| 2 |<--->| 3 |<---+ B |
+'---' '-' '+' '+' '---'
+```
+````
+
+Is rendered to:
+
+```html
+<div class="goat svg-container">
+ <svg xmlns="http://www.w3.org/2000/svg" font-family="Menlo,Lucida Console,monospace" viewBox="0 0 352 57">
+ ...
+ </svg>
+</div>
+```
+
+Which appears in your browser as:
+
+```goat {class="mw6-ns"}
+.---. .-. .-. .-. .---.
+| A +--->| 1 |<--->| 2 |<--->| 3 |<---+ B |
+'---' '-' '+' '+' '---'
+```
+
- This markdown:
++To customize rendering, override Hugo's [embedded code block render hook] for GoAT diagrams.
+
+## Code block render hook
+
+By way of example, let's create a code block render hook to render GoAT diagrams as `figure` elements with an optional caption.
+
+{{< code file=layouts/_default/_markup/render-codeblock-goat.html >}}
+{{ $caption := or .Attributes.caption "" }}
+{{ $class := or .Attributes.class "diagram" }}
+{{ $id := or .Attributes.id (printf "diagram-%d" (add 1 .Ordinal)) }}
+
+<figure id="{{ $id }}">
+ {{ with diagrams.Goat (trim .Inner "\n\r") }}
+ <svg class="{{ $class }}" width="{{ .Width }}" height="{{ .Height }}" xmlns="http://www.w3.org/2000/svg" version="1.1">
+ {{ .Inner }}
+ </svg>
+ {{ end }}
+ <figcaption>{{ $caption }}</figcaption>
+</figure>
+{{< /code >}}
+
++This Markdown:
+
+{{< code file=content/example.md lang=text >}}
+```goat {class="foo" caption="Diagram 1: Example"}
+.---. .-. .-. .-. .---.
+| A +--->| 1 |<--->| 2 |<--->| 3 |<---+ B |
+'---' '-' '+' '+' '---'
+```
+{{< /code >}}
+
+Is rendered to:
+
+```html
+<figure id="diagram-1">
+ <svg class="foo" width="272" height="57" xmlns="http://www.w3.org/2000/svg" version="1.1">
+ ...
+ </svg>
+ <figcaption>Diagram 1: Example</figcaption>
+</figure>
+```
+
+Use CSS to style the SVG as needed:
+
+```css
+svg.foo {
+ font-family: "Segoe UI","Noto Sans",Helvetica,Arial,sans-serif
+}
+```
--- /dev/null
- {{ errorf "The %q shortcode requires a src parameter. See %s" .Name .Position }}
+---
+title: fmt.Errorf
+description: Log an ERROR from a template.
+categories: []
+keywords: []
+action:
+ aliases: [errorf]
+ related:
+ - functions/fmt/Erroridf
+ - functions/fmt/Warnf
++ - functions/fmt/Warnidf
+ returnType: string
+ signatures: ['fmt.Errorf FORMAT [INPUT]']
+aliases: [/functions/errorf]
+---
+
+{{% include "functions/fmt/_common/fmt-layout.md" %}}
+
+The `errorf` function evaluates the format string, then prints the result to the ERROR log and fails the build.
+
+```go-html-template
- [`erroridf`]: /functions/fmt/erroridf
++{{ errorf "The %q shortcode requires a src argument. See %s" .Name .Position }}
+```
+
+Use the [`erroridf`] function to allow optional suppression of specific errors.
+
++[`erroridf`]: /functions/fmt/erroridf/
--- /dev/null
- description: Log a suppressable ERROR from a template.
+---
+title: fmt.Erroridf
- 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.
++description: Log a suppressible ERROR from a template.
+categories: []
+keywords: []
+action:
+ aliases: [erroridf]
+ related:
+ - functions/fmt/Errorf
+ - functions/fmt/Warnf
++ - functions/fmt/Warnidf
+ returnType: string
+ signatures: ['fmt.Erroridf ID FORMAT [INPUT]']
+aliases: [/functions/erroridf]
+---
+
+{{% include "functions/fmt/_common/fmt-layout.md" %}}
+
- ignoreErrors = ['error-42']
++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:
+
+```go-html-template
+{{ erroridf "error-42" "You should consider fixing this." }}
+```
+
+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 >}}
- [`errorf`]: /functions/fmt/errorf
++ignoreLogs = ["error-42"]
+{{< /code-toggle >}}
+
++[`errorf`]: /functions/fmt/errorf/
--- /dev/null
- [`math.Counter`]: /functions/math/counter
+---
+title: fmt.Warnf
+description: Log a WARNING from a template.
+categories: []
+keywords: []
+action:
+ aliases: [warnf]
+ related:
+ - functions/fmt/Errorf
+ - functions/fmt/Erroridf
++ - functions/fmt/Warnidf
+ returnType: string
+ signatures: ['fmt.Warnf FORMAT [INPUT]']
+aliases: [/functions/warnf]
+---
+
+{{% include "functions/fmt/_common/fmt-layout.md" %}}
+
+The `warnf` function evaluates the format string, then prints the result to the WARNING log. Hugo prints each unique message once to avoid flooding the log with duplicate warnings.
+
+```go-html-template
+{{ warnf "The %q shortcode was unable to find %s. See %s" .Name $file .Position }}
+```
+
++Use the [`warnidf`] function to allow optional suppression of specific warnings.
++
+To prevent suppression of duplicate messages when using `warnf` for debugging, make each message unique with the [`math.Counter`] function. For example:
+
+
+```go-html-template
+{{ range site.RegularPages }}
+ {{ .Section | warnf "%#[2]v [%[1]d]" math.Counter }}
+{{ end }}
+```
+
++[`math.Counter`]: /functions/math/counter/
++
++[`warnidf`]: /functions/fmt/warnidf/
--- /dev/null
--- /dev/null
++---
++title: fmt.Warnidf
++description: Log a suppressible 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/
--- /dev/null
- Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+---
+cascade:
+ _build:
+ list: never
+ publishResources: false
+ render: never
+---
+
+<!--
++Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+
+Include the rendered content using the "include" shortcode.
+-->
--- /dev/null
- Hugo almost always passes a `Page` as the data context into the top level template (e.g., `single.html`). The one exception is the multihost sitemap template. This means that you can access the current page with the `.` variable in the template.
+---
+title: page
+description: Provides global access to a Page object.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/global/site
+ returnType:
+ signatures: [page]
+toc: true
+aliases: [/functions/page]
+---
+
+{{< new-in 0.111.0 >}}
+
+At the top level of a template that receives a `Page` object in context, these are equivalent:
+
+```go-html-template
+{{ .Params.foo }}
+{{ .Page.Params.foo }}
+{{ page.Params.foo }}
+```
+
+When a `Page` object is not in context, you can use the global `page` function:
+
+```go-html-template
+{{ page.Params.foo }}
+```
+
+{{% note %}}
+Do not use the global `page` function in shortcodes, partials called by shortcodes, or cached partials. See [warnings](#warnings) below.
+{{% /note %}}
+
+## Explanation
+
- [`Summary`]: /methods/page/summary
- [`partialCached`]: /functions/partials/includecached
++Hugo almost always passes a `Page` as the data context into the top level template (e.g., `single.html`). The one exception is the multihost sitemap template. This means that you can access the current page with the `.` in the template.
+
+But when you are deeply nested inside of a [content view], [partial], or [render hook], it is not always practical or possible to access the `Page` object.
+
+Use the global `page` function to access the `Page` object from anywhere in any template.
+
+## Warnings
+
+### Be aware of top-level context
+
+The global `page` function accesses the `Page` object passed into the top-level template.
+
+With this content structure:
+
+```text
+content/
+├── posts/
+│ ├── post-1.md
+│ ├── post-2.md
+│ └── post-3.md
+└── _index.md <-- title is "My Home Page"
+```
+
+And this code in the home page template:
+
+```go-html-template
+{{ range site.Sections }}
+ {{ range .Pages }}
+ {{ page.Title }}
+ {{ end }}
+{{ end }}
+```
+
+The rendered output will be:
+
+```text
+My Home Page
+My Home Page
+My Home Page
+```
+
+In the example above, the global `page` function accesses the `Page` object passed into the home page template; it does not access the `Page` object of the iterated pages.
+
+### Be aware of caching
+
+Do not use the global `page` function in:
+
+- Shortcodes
+- Partials called by shortcodes
+- Partials cached by the [`partialCached`] function
+
+Hugo caches rendered shortcodes. If you use the global `page` function within a shortcode, and the page content is rendered in two or more templates, the cached shortcode may be incorrect.
+
+Consider this section template:
+
+```go-html-template
+{{ range .Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ .Summary }}
+{{ end }}
+```
+
+When you call the [`Summary`] method, Hugo renders the page content including shortcodes. In this case, within a shortcode, the global `page` function accesses the `Page` object of the section page, not the content page.
+
+If Hugo renders the section page before a content page, the cached rendered shortcode will be incorrect. You cannot control the rendering sequence due to concurrency.
+
++[`Summary`]: /methods/page/summary/
++[`partialCached`]: /functions/partials/includecached/
+[content view]: /getting-started/glossary/#content-view
+[partial]: /getting-started/glossary/#partial
+[render hook]: /getting-started/glossary/#render-hook
+[shortcode]: getting-started/glossary/#shortcode
--- /dev/null
- At the top level of a template that receives the `Site` object in context, these are equivalent:
+---
+title: site
+description: Provides global access to the current Site object.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/global/page
+ returnType:
+ signatures: [site]
+aliases: [/functions/site]
+---
+
- {{ .Site.Params.foo }}
++Use the `site` function to return the `Site` object regardless of current context.
+
+```go-html-template
- When the `Site` object is not in context, use the global `site` function:
+{{ site.Params.foo }}
+```
+
- {{ site.Params.foo }}
++When the `Site` object is in context you can use the `Site` property:
+
+```go-html-template
++<!-- current context -->
++{{ .Site.Params.foo }}
++<!-- template context -->
++{{ $.Site.Params.foo }}
+```
+
+{{% note %}}
+To simplify your templates, use the global `site` function regardless of whether the `Site` object is in context.
+{{% /note %}}
--- /dev/null
- Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+---
+cascade:
+ _build:
+ list: never
+ publishResources: false
+ render: never
+---
+
+<!--
++Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+
+Include the rendered content using the "include" shortcode.
+-->
--- /dev/null
- [`block`]: /functions/go-template/block
- [`template`]: /functions/go-template/block
+---
+title: define
+description: Defines a template.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/go-template/block
+ - functions/go-template/end
+ - functions/go-template/template
+ - functions/partials/Include
+ - functions/partials/IncludeCached
+ returnType:
+ signatures: [define NAME]
+---
+
+Use with the [`block`] statement:
+
+```go-html-template
+{{ block "main" . }}
+ {{ print "default value if 'main' template is empty" }}
+{{ end }}
+
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+{{ end }}
+```
+
+Use with the [`partial`] function:
+
+```go-html-template
+{{ partial "inline/foo.html" (dict "answer" 42) }}
+
+{{ define "partials/inline/foo.html" }}
+ {{ printf "The answer is %v." .answer }}
+{{ end }}
+```
+
+Use with the [`template`] function:
+
+```go-html-template
+{{ template "foo" (dict "answer" 42) }}
+
+{{ define "foo" }}
+ {{ printf "The answer is %v." .answer }}
+{{ end }}
+```
+
++[`block`]: /functions/go-template/block/
++[`template`]: /functions/go-template/block/
+[`partial`]: /functions/partials/include/
+
+{{% include "functions/go-template/_common/text-template.md" %}}
--- /dev/null
- [`if`]: /functions/go-template/if
- [`with`]: /functions/go-template/with
- [`range`]: /functions/go-template/range
+---
+title: else
+description: Begins an alternate block for if, with, and range statements.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/go-template/if
+ - functions/go-template/range
+ - functions/go-template/with
+ - functions/go-template/end
+ returnType:
+ signatures: [else VALUE]
+---
+
+Use with the [`if`] statement:
+
+```go-html-template
+{{ $var := "foo" }}
+{{ if $var }}
+ {{ $var }} → foo
+{{ else }}
+ {{ print "var is falsy" }}
+{{ end }}
+```
+
+Use with the [`with`] statement:
+
+```go-html-template
+{{ $var := "foo" }}
+{{ with $var }}
+ {{ . }} → foo
+{{ else }}
+ {{ print "var is falsy" }}
+{{ end }}
+```
+
+Use with the [`range`] statement:
+
+```go-html-template
+{{ $var := slice 1 2 3 }}
+{{ range $var }}
+ {{ . }} → 1 2 3
+{{ else }}
+ {{ print "var is falsy" }}
+{{ end }}
+```
+
+Use `else if` to check multiple conditions.
+
+```go-html-template
+{{ $var := 12 }}
+{{ 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 }}
+```
+
+{{% include "functions/go-template/_common/text-template.md" %}}
+
++[`if`]: /functions/go-template/if/
++[`with`]: /functions/go-template/with/
++[`range`]: /functions/go-template/range/
--- /dev/null
- [`block`]: /functions/go-template/block
- [`define`]: /functions/go-template/define
- [`if`]: /functions/go-template/if
- [`range`]: /functions/go-template/range
- [`with`]: /functions/go-template/with
+---
+title: end
+description: Terminates if, with, range, block, and define statements.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/go-template/block
+ - functions/go-template/define
+ - functions/go-template/if
+ - functions/go-template/range
+ - functions/go-template/with
+ returnType:
+ signatures: [end]
+---
+
+Use with the [`if`] statement:
+
+```go-html-template
+{{ $var := "foo" }}
+{{ if $var }}
+ {{ $var }} → foo
+{{ end }}
+```
+
+Use with the [`with`] statement:
+
+```go-html-template
+{{ $var := "foo" }}
+{{ with $var }}
+ {{ . }} → foo
+{{ end }}
+```
+
+Use with the [`range`] statement:
+
+```go-html-template
+{{ $var := slice 1 2 3 }}
+{{ range $var }}
+ {{ . }} → 1 2 3
+{{ end }}
+```
+
+Use with the [`block`] statement:
+
+```go-html-template
+{{ block "main" . }}{{ end }}
+```
+
+Use with the [`define`] statement:
+
+```go-html-template
+{{ define "main" }}
+ {{ print "this is the main section" }}
+{{ end }}
+```
+
+{{% include "functions/go-template/_common/text-template.md" %}}
+
++[`block`]: /functions/go-template/block/
++[`define`]: /functions/go-template/define/
++[`if`]: /functions/go-template/if/
++[`range`]: /functions/go-template/range/
++[`with`]: /functions/go-template/with/
--- /dev/null
- [`else`]: /functions/go-template/else
+---
+title: if
+description: Executes the block if the expression is truthy.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/go-template/with
+ - functions/go-template/else
+ - functions/go-template/end
+ - functions/collections/IsSet
+ returnType:
+ signatures: [if EXPR]
+---
+
+{{% include "functions/go-template/_common/truthy-falsy.md" %}}
+
+```go-html-template
+{{ $var := "foo" }}
+{{ if $var }}
+ {{ $var }} → foo
+{{ end }}
+```
+
+Use with the [`else`] statement:
+
+```go-html-template
+{{ $var := "foo" }}
+{{ if $var }}
+ {{ $var }} → foo
+{{ else }}
+ {{ print "var is falsy" }}
+{{ end }}
+```
+
+Use `else if` to check multiple conditions.
+
+```go-html-template
+{{ $var := 12 }}
+{{ 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 }}
+```
+
+{{% include "functions/go-template/_common/text-template.md" %}}
+
++[`else`]: /functions/go-template/else/
--- /dev/null
- [`seq`]: functions/collections/seq/
+---
+title: range
+description: Iterates over a non-empty collection, binds context (the dot) to successive elements, and executes the block.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/go-template/break
+ - functions/go-template/continue
+ - functions/go-template/else
+ - functions/go-template/end
+ returnType:
+ signatures: [range COLLECTION]
+aliases: [/functions/range]
+toc: true
+---
+
+{{% include "functions/go-template/_common/truthy-falsy.md" %}}
+
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $s }}
+ {{ . }} → foo bar baz
+{{ end }}
+```
+
+Use with the [`else`] statement:
+
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $s }}
+ <p>{{ . }}</p>
+{{ else }}
+ <p>The collection is empty</p>
+{{ end }}
+```
+
+Within a range block:
+
+- Use the [`continue`] statement to stop the innermost iteration and continue to the next iteration
+- Use the [`break`] statement to stop the innermost iteration and bypass all remaining iterations
+
+## Understanding context
+
+At the top of a page template, the [context] (the dot) is a `Page` object. Within the `range` block, the context is bound to each successive element.
+
+With this contrived example that uses the [`seq`] function to generate a slice of integers:
+
+```go-html-template
+{{ range seq 3 }}
+ {{ .Title }}
+{{ end }}
+```
+
+Hugo will throw an error:
+
+ can't evaluate field Title in type int
+
+The error occurs because we are trying to use the `.Title` method on an integer instead of a `Page` object. Within the `range` block, if we want to render the page title, we need to get the context passed into the template.
+
+{{% note %}}
+Use the `$` to get the context passed into the template.
+{{% /note %}}
+
+This template will render the page title three times:
+
+```go-html-template
+{{ range seq 3 }}
+ {{ $.Title }}
+{{ end }}
+```
+
+{{% note %}}
+Gaining a thorough understanding of context is critical for anyone writing template code.
+{{% /note %}}
+
- [`else`]: /functions/go-template/else
- [`break`]: /functions/go-template/break
- [`continue`]: /functions/go-template/continue
++[`seq`]: /functions/collections/seq/
+[context]: /getting-started/glossary/#context
+
+## Array or slice of scalars
+
+This template code:
+
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $s }}
+ <p>{{ . }}</p>
+{{ end }}
+```
+
+Is rendered to:
+
+```html
+<p>foo</p>
+<p>bar</p>
+<p>baz</p>
+```
+
+This template code:
+
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $v := $s }}
+ <p>{{ $v }}</p>
+{{ end }}
+```
+
+Is rendered to:
+
+```html
+<p>foo</p>
+<p>bar</p>
+<p>baz</p>
+```
+
+This template code:
+
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $k, $v := $s }}
+ <p>{{ $k }}: {{ $v }}</p>
+{{ end }}
+```
+
+Is rendered to:
+
+```html
+<p>0: foo</p>
+<p>1: bar</p>
+<p>2: baz</p>
+```
+
+## Array or slice of maps
+
+This template code:
+
+```go-html-template
+{{ $m := slice
+ (dict "name" "John" "age" 30)
+ (dict "name" "Will" "age" 28)
+ (dict "name" "Joey" "age" 24)
+}}
+{{ range $m }}
+ <p>{{ .name }} is {{ .age }}</p>
+{{ end }}
+```
+
+Is rendered to:
+
+```html
+<p>John is 30</p>
+<p>Will is 28</p>
+<p>Joey is 24</p>
+```
+
+## Array or slice of pages
+
+This template code:
+
+```go-html-template
+{{ range where site.RegularPages "Type" "articles" }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+Is rendered to:
+
+```html
+<h2><a href="/articles/article-3/">Article 3</a></h2>
+<h2><a href="/articles/article-2/">Article 2</a></h2>
+<h2><a href="/articles/article-1/">Article 1</a></h2>
+```
+
+## Maps
+
+This template code:
+
+```go-html-template
+{{ $m := dict "name" "John" "age" 30 }}
+{{ range $k, $v := $m }}
+ <p>key = {{ $k }} value = {{ $v }}</p>
+{{ end }}
+```
+
+Is rendered to:
+
+```go-html-template
+<p>key = age value = 30</p>
+<p>key = name value = John</p>
+```
+
+Unlike ranging over an array or slice, Hugo sorts by key when ranging over a map.
+
+{{% include "functions/go-template/_common/text-template.md" %}}
+
++[`else`]: /functions/go-template/else/
++[`break`]: /functions/go-template/break/
++[`continue`]: /functions/go-template/continue/
--- /dev/null
- Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks
+---
+title: return
+description: Used within partial templates, terminates template execution and returns the given value, if any.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/partials/Include
+ - functions/partials/IncludeCached
+ returnType: any
+ signatures: ['return [VALUE]']
+toc: true
+---
+
+The `return` statement is a custom addition to Go's [text/template] package. Used within partial templates, the `return` statement terminates template execution and returns the given value, if any.
+
+The returned value may be of any data type including, but not limited to, [`bool`], [`float`], [`int`], [`map`], [`resource`], [`slice`], and [`string`].
+
+A `return` statement without a value returns an empty string of type `template.HTML`.
+
+[`bool`]: /getting-started/glossary/#bool
+[`float`]: /getting-started/glossary/#float
+[`int`]: /getting-started/glossary/#int
+[`map`]: /getting-started/glossary/#map
+[`resource`]: /getting-started/glossary/#resource
+[`slice`]: /getting-started/glossary/#slice
+[`string`]: /getting-started/glossary/#string
+[text/template]: https://pkg.go.dev/text/template
+
+{{% note %}}
+Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks. See [usage](#usage) notes below.
+{{% /note %}}
+
+## Example
+
+By way of example, let's create a partial template that _renders_ HTML, describing whether the given number is odd or even:
+
+{{< code file="layouts/partials/odd-or-even.html" >}}
+{{ if math.ModBool . 2 }}
+ <p>{{ . }} is even</p>
+{{ else }}
+ <p>{{ . }} is odd</p>
+{{ end }}
+{{< /code >}}
+
+When called, the partial renders HTML:
+
+```go-html-template
+{{ partial "odd-or-even.html" 42 }} → <p>42 is even</p>
+```
+
+Instead of rendering HTML, let's create a partial that _returns_ a boolean value, reporting whether the given number is even:
+
+{{< code file="layouts/partials/is-even.html" >}}
+{{ return math.ModBool . 2 }}
+{{< /code >}}
+
+With this template:
+
+```go-html-template
+{{ $number := 42 }}
+{{ if partial "is-even.html" $number }}
+ <p>{{ $number }} is even</p>
+{{ else }}
+ <p>{{ $number }} is odd</p>
+{{ end }}
+```
+
+Hugo renders:
+
+```html
+<p>42 is even</p>
+```
+
+See additional examples in the [partial templates] section.
+
+[partial templates]: /templates/partials/#returning-a-value-from-a-partial
+
+## Usage
+
+{{% note %}}
++Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks.
+{{% /note %}}
+
+A partial that returns a value must contain only one `return` statement, placed at the end of the template.
+
+For example:
+
+{{< code file="layouts/partials/is-even.html" >}}
+{{ $result := false }}
+{{ if math.ModBool . 2 }}
+ {{ $result = "even" }}
+{{ else }}
+ {{ $result = "odd" }}
+{{ end }}
+{{ return $result }}
+{{< /code >}}
+
+{{% note %}}
+The construct below is incorrect; it contains more than one `return` statement.
+{{% /note %}}
+
+{{< code file="layouts/partials/do-not-do-this.html" >}}
+{{ if math.ModBool . 2 }}
+ {{ return "even" }}
+{{ else }}
+ {{ return "odd" }}
+{{ end }}
+{{< /code >}}
--- /dev/null
- Use the `template` function to execute [internal templates]. For example:
+---
+title: template
+description: Executes the given template, optionally passing context.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/go-template/define
+ - functions/partials/Include
+ - functions/partials/IncludeCached
+ returnType:
+ signatures: ['template NAME [CONTEXT]']
+---
+
- [internal templates]: /templates/internal
++Use the `template` function to execute [embedded templates]. For example:
+
+```go-html-template
+{{ range (.Paginate .Pages).Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+{{ template "_internal/pagination.html" . }}
+```
+
+You can also use the `template` function to execute a defined template:
+
+```go-html-template
+{{ template "foo" (dict "answer" 42) }}
+
+{{ define "foo" }}
+ {{ printf "The answer is %v." .answer }}
+{{ end }}
+```
+
+The example above can be rewritten using an [inline partial] template:
+
+```go-html-template
+{{ partial "inline/foo.html" (dict "answer" 42) }}
+
+{{ define "partials/inline/foo.html" }}
+ {{ printf "The answer is %v." .answer }}
+{{ end }}
+```
+
+{{% include "functions/go-template/_common/text-template.md" %}}
+
+[`partial`]: /functions/partials/include/
+[inline partial]: /templates/partials/#inline-partials
++[embedded templates]: /templates/embedded/
--- /dev/null
- [`else`]: /functions/go-template/else
+---
+title: with
+description: Binds context (the dot) to the expression and executes the block if expression is truthy.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/go-template/if
+ - functions/go-template/else
+ - functions/go-template/end
+ - functions/collections/IsSet
+ returnType:
+ signatures: [with EXPR]
+aliases: [/functions/with]
+toc: true
+---
+
+{{% include "functions/go-template/_common/truthy-falsy.md" %}}
+
+```go-html-template
+{{ $var := "foo" }}
+{{ with $var }}
+ {{ . }} → foo
+{{ end }}
+```
+
+Use with the [`else`] statement:
+
+```go-html-template
+{{ $var := "foo" }}
+{{ with $var }}
+ {{ . }} → foo
+{{ else }}
+ {{ print "var is falsy" }}
+{{ end }}
+```
+
+Initialize a variable, scoped to the current block:
+
+```go-html-template
+{{ with $var := 42 }}
+ {{ . }} → 42
+ {{ $var }} → 42
+{{ end }}
+{{ $var }} → undefined
+```
+
+## Understanding context
+
+At the top of a page template, the [context] (the dot) is a `Page` object. Inside of the `with` block, the context is bound to the value passed to the `with` statement.
+
+With this contrived example:
+
+```go-html-template
+{{ with 42 }}
+ {{ .Title }}
+{{ end }}
+```
+
+Hugo will throw an error:
+
+ can't evaluate field Title in type int
+
+The error occurs because we are trying to use the `.Title` method on an integer instead of a `Page` object. Inside of the `with` block, if we want to render the page title, we need to get the context passed into the template.
+
+{{% note %}}
+Use the `$` to get the context passed into the template.
+{{% /note %}}
+
+This template will render the page title as desired:
+
+```go-html-template
+{{ with 42 }}
+ {{ $.Title }}
+{{ end }}
+```
+
+{{% note %}}
+Gaining a thorough understanding of context is critical for anyone writing template code.
+{{% /note %}}
+
+[context]: /getting-started/glossary/#context
+
+{{% include "functions/go-template/_common/text-template.md" %}}
+
++[`else`]: /functions/go-template/else/
--- /dev/null
- {{ hugo.Generator }} → <meta name="generator" content="Hugo 0.122.0">
+---
+title: hugo.Generator
+description: Renders an HTML meta element identifying the software that generated the site.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related: []
+ returnType: template.HTML
+ signatures: [hugo.Generator]
+---
+
+```go-html-template
++{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.126.0">
+```
--- /dev/null
--- /dev/null
++---
++title: hugo.IsMultihost
++description: Reports whether each configured language has a unique base URL.
++categories: []
++keywords: []
++action:
++ aliases: []
++ related:
++ - /functions/hugo/IsMultilingual
++ returnType: bool
++ signatures: [hugo.IsMultihost]
++---
++
++{{< new-in v0.124.0 >}}
++
++Site configuration:
++
++{{< code-toggle file=hugo >}}
++defaultContentLanguage = 'de'
++defaultContentLanguageInSubdir = true
++[languages]
++ [languages.de]
++ baseURL = 'https://de.example.org/'
++ languageCode = 'de-DE'
++ languageName = 'Deutsch'
++ title = 'Projekt Dokumentation'
++ weight = 1
++ [languages.en]
++ baseURL = 'https://en.example.org/'
++ languageCode = 'en-US'
++ languageName = 'English'
++ title = 'Project Documentation'
++ weight = 2
++{{< /code-toggle >}}
++
++Template:
++
++```go-html-template
++{{ hugo.IsMultihost }} → true
++```
--- /dev/null
--- /dev/null
++---
++title: hugo.IsMultilingual
++description: Reports whether there are two or more configured languages.
++categories: []
++keywords: []
++action:
++ related:
++ - /functions/hugo/IsMultihost
++ returnType: bool
++ signatures: [hugo.IsMultilingual]
++---
++
++{{< new-in v0.124.0 >}}
++
++Site configuration:
++
++{{< code-toggle file=hugo >}}
++defaultContentLanguage = 'de'
++defaultContentLanguageInSubdir = true
++[languages]
++ [languages.de]
++ languageCode = 'de-DE'
++ languageName = 'Deutsch'
++ title = 'Projekt Dokumentation'
++ weight = 1
++ [languages.en]
++ languageCode = 'en-US'
++ languageName = 'English'
++ title = 'Project Documentation'
++ weight = 2
++{{< /code-toggle >}}
++
++Template:
++
++```go-html-template
++{{ hugo.IsMultilingual }} → true
++```
--- /dev/null
- {{ hugo.Version }} → 0.122.0
+---
+title: hugo.Version
+description: Returns the current version of the Hugo binary.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related: []
+ returnType: hugo.VersionString
+ signatures: [hugo.Version]
+---
+
+```go-html-template
++{{ hugo.Version }} → 0.126.0
+```
--- /dev/null
+---
+title: hugo.WorkingDir
+description: Returns the project working directory.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related: []
+ returnType: string
+ signatures: [hugo.WorkingDir]
+---
+
+```go-html-template
+{{ hugo.WorkingDir }} → /home/user/projects/my-hugo-site
+```
++
++{{< new-in 0.112.0 >}}
--- /dev/null
- [`Width`]: /methods/resource/width
- [`Height`]: /methods/resource/height
+---
+title: images.Config
+description: Returns an image.Config structure from the image at the specified path, relative to the working directory.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related: []
+ returnType: image.Config
+ signatures: [images.Config PATH]
+aliases: [/functions/imageconfig]
+---
+
+See [image processing] for an overview of Hugo's image pipeline.
+
+[image processing]: /content-management/image-processing/
+
+```go-html-template
+{{ $ic := images.Config "/static/images/a.jpg" }}
+
+{{ $ic.Width }} → 600 (int)
+{{ $ic.Height }} → 400 (int)
+```
+
+Supported image formats include GIF, JPEG, PNG, TIFF, and WebP.
+
+{{% note %}}
+This is a legacy function, superseded by the [`Width`] and [`Height`] methods for [global], [page], and [remote] resources. See the [image processing] section for details.
+
- [image processing]: /content-management/image-processing
++[`Width`]: /methods/resource/width/
++[`Height`]: /methods/resource/height/
+[global]: /getting-started/glossary/#global-resource
++[image processing]: /content-management/image-processing/
+[page]: /getting-started/glossary/#page-resource
+[remote]: /getting-started/glossary/#remote-resource
+{{% /note %}}
--- /dev/null
- : (`float`) The strength at which to apply the dithering matrix, typically a value in the range [0, 1]. A value of `1.0` applies the dithering matrix at 100% strength (no modifification of the dither matrix). The `strength` is inversely proportional to contrast; reducing the strength increases the contrast. Setting `strength` to a value such as `0.8` can be useful to reduce noise in the dithered image. Default is `1.0`.
+---
+title: images.Dither
+description: Returns an image filter that dithers an image.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/images/Filter
+ - functions/images/Process
+ - methods/resource/Colors
+ - methods/resource/Filter
+ returnType: images.filter
+ signatures: ['images.Dither [OPTIONS]']
+toc: true
+---
+
++{{< new-in 0.123.0 >}}
++
+## Options
+
+colors
+: (`string array`) A slice of two or more colors that make up the dithering palette, each expressed as an RGB or RGBA [hexadecimal] value, with or without a leading hash mark. The default values are opaque black (`000000ff`) and opaque white (`ffffffff`).
+
+[hexadecimal]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
+
+method
+: (`string`) The dithering method. See the [dithering methods](#dithering-methods) section below for a list of the available methods. Default is `FloydSteinberg`.
+
+serpentine
+: (`bool`) Applicable to error diffusion dithering methods, serpentine controls whether the error diffusion matrix is applied in a serpentine manner, meaning that it goes right-to-left every other line. This greatly reduces line-type artifacts. Default is `true`.
+
+strength
++: (`float`) The strength at which to apply the dithering matrix, typically a value in the range [0, 1]. A value of `1.0` applies the dithering matrix at 100% strength (no modification of the dither matrix). The `strength` is inversely proportional to contrast; reducing the strength increases the contrast. Setting `strength` to a value such as `0.8` can be useful to reduce noise in the dithered image. Default is `1.0`.
+
+## Usage
+
+Create the options map:
+
+```go-html-template
+{{ $opts := dict
+ "colors" (slice "222222" "808080" "dddddd")
+ "method" "ClusteredDot4x4"
+ "strength" 0.85
+}}
+```
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.Dither $opts }}
+```
+
+Or create the filter using the default settings:
+
+```go-html-template
+{{ $filter := images.Dither }}
+```
+
+{{% include "functions/images/_common/apply-image-filter.md" %}}
+
+## Dithering methods
+
+See the [Go documentation] for descriptions of each of the dithering methods below.
+
+[Go documentation]: https://pkg.go.dev/github.com/makeworld-the-better-one/dither/v2#pkg-variables
+
+Error diffusion dithering methods:
+
+- Atkinson
+- Burkes
+- FalseFloydSteinberg
+- FloydSteinberg
+- JarvisJudiceNinke
+- Sierra
+- Sierra2
+- Sierra2_4A
+- Sierra3
+- SierraLite
+- Simple2D
+- StevenPigeon
+- Stucki
+- TwoRowSierra
+
+Ordered dithering methods:
+
+- ClusteredDot4x4
+- ClusteredDot6x6
+- ClusteredDot6x6_2
+- ClusteredDot6x6_3
+- ClusteredDot8x8
+- ClusteredDotDiagonal16x16
+- ClusteredDotDiagonal6x6
+- ClusteredDotDiagonal8x8
+- ClusteredDotDiagonal8x8_2
+- ClusteredDotDiagonal8x8_3
+- ClusteredDotHorizontalLine
+- ClusteredDotSpiral5x5
+- ClusteredDotVerticalLine
+- Horizontal3x5
+- Vertical5x3
+
+## Example
+
+This example uses the default dithering options.
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Dither"
+ filterArgs=""
+ example=true
+>}}
+
+## Recommendations
+
+Regardless of dithering method, do both of the following to obtain the best results:
+
+1. Scale the image _before_ dithering
+2. Output the image to a lossless format such as GIF or PNG
+
+The example below does both of these, and it sets the dithering palette to the three most dominant colors in the image.
+
+
+```go-html-template
+{{ with resources.Get "original.jpg" }}
+ {{ $opts := dict
+ "method" "ClusteredDotSpiral5x5"
+ "colors" (first 3 .Colors)
+ }}
+ {{ $filters := slice
+ (images.Process "resize 800x")
+ (images.Dither $opts)
+ (images.Process "png")
+ }}
+ {{ with . | images.Filter $filters }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+For best results, if the dithering palette is grayscale, convert the image to grayscale before dithering.
+
+```go-html-template
+{{ $opts := dict "colors" (slice "222" "808080" "ddd") }}
+{{ $filters := slice
+ (images.Process "resize 800x")
+ (images.Grayscale)
+ (images.Dither $opts)
+ (images.Process "png")
+}}
+{{ with images.Filter $filters . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+The example above:
+
+1. Resizes the image to be 800 px wide
+2. Converts the image to grayscale
+3. Dithers the image using the default (`FloydSteinberg`) dithering method with a grayscale palette
+4. Converts the image to the PNG format
--- /dev/null
- [`Filter`]: /methods/resource/filter
+---
+title: images.Filter
+description: Applies one or more image filters to the given image resource.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - methods/resource/Filter
+ returnType: images.ImageResource
+ signatures: [images.Filter FILTERS... IMAGE]
+toc: true
+---
+
+Apply one or more [image filters](#image-filters) to the given image.
+
+To apply a single filter:
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with images.Filter images.Grayscale . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+To apply two or more filters, executing from left to right:
+
+```go-html-template
+{{ $filters := slice
+ images.Grayscale
+ (images.GaussianBlur 8)
+}}
+{{ with resources.Get "images/original.jpg" }}
+ {{ with images.Filter $filters . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+You can also apply image filters using the [`Filter`] method on a `Resource` object.
+
++[`Filter`]: /methods/resource/filter/
+
+## Example
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with images.Filter images.Grayscale . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Grayscale"
+ filterArgs=""
+ example=true
+>}}
+
+## Image filters
+
+Use any of these filters with the `images.Filter` function, or with the `Filter` method on a `Resource` object.
+
+{{< list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude >}}
--- /dev/null
- [`Colors`]: /methods/resource/colors
+---
+title: images.Padding
+description: Returns an image filter that resizes the image canvas without resizing the image.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/images/Filter
+ - methods/resource/Filter
+ returnType: images.filter
+ signatures: ['images.Padding V1 [V2] [V3] [V4] [COLOR]']
+toc: true
+---
+
+{{< new-in 0.120.0 >}}
+
+The last argument is the canvas color, expressed as an RGB or RGBA [hexadecimal color]. The default value is `ffffffff` (opaque white). The preceding arguments are the padding values, in pixels, using the CSS [shorthand property] syntax. Negative padding values will crop the image.
+
+[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
+[shorthand property]: https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box
+
+## Usage
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.Padding 20 40 "#976941" }}
+```
+
+{{% include "functions/images/_common/apply-image-filter.md" %}}
+
+Combine with the [`Colors`] method to create a border with one of the image's most dominant colors:
+
++[`Colors`]: /methods/resource/colors/
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ $filter := images.Padding 20 40 (index .Colors 2) }}
+ {{ with . | images.Filter $filter }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+## Example
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Padding"
+ filterArgs="20,40,20,40,#976941"
+ example=true
+>}}
+
+## Other recipes
+
+This example resizes an image to 300px wide, converts it to the WebP format, adds 20px vertical padding and 50px horizontal padding, then sets the canvas color to dark green with 33% opacity.
+
+Conversion to WebP is required to support transparency. PNG and WebP images have an alpha channel; JPEG and GIF do not.
+
+```go-html-template
+{{ $img := resources.Get "images/a.jpg" }}
+{{ $filters := slice
+ (images.Process "resize 300x webp")
+ (images.Padding 20 50 "#0705")
+}}
+{{ $img = $img.Filter $filters }}
+```
+
+To add a 2px gray border to an image:
+
+```go-html-template
+{{ $img = $img.Filter (images.Padding 2 "#777") }}
+```
--- /dev/null
- [`Process`]: /methods/resource/process
+---
+title: images.Process
+description: Returns an image filter that processes the given image using the given specification.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/images/Filter
+ - methods/resource/Filter
+ - methods/resource/Process
+ returnType: images.filter
+ signatures: [images.Process SPEC]
+toc: true
+---
+
+{{< new-in 0.119.0 >}}
+
+This filter has the same options as the [`Process`] method on a `Resource` object, but using it as a filter may be more effective if you need to apply multiple filters to an image.
+
++[`Process`]: /methods/resource/process/
+
+The process specification is a space-delimited, case-insensitive list of one or more of the following in any sequence:
+
+action
+: Specify zero or one of `crop`, `fill`, `fit`, or `resize`. If you specify an action you must also provide dimensions. See [details](content-management/image-processing/#image-processing-methods).
+
+```go-html-template
+{{ $filter := images.Process "resize 300x" }}
+```
+
+dimensions
+: Required if you specify an action. Provide width _or_ height when using `resize`, else provide both width _and_ height. See [details](/content-management/image-processing/#dimensions).
+
+```go-html-template
+{{ $filter := images.Process "crop 200x200" }}
+```
+
+anchor
+: Use with the `crop` or `fill` action. Specify zero or one of `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. Default is `Smart`. See [details](/content-management/image-processing/#anchor).
+
+```go-html-template
+{{ $filter := images.Process "crop 200x200 center" }}
+```
+
+rotation
+: Typically specify zero or one of `r90`, `r180`, or `r270`. Also supports arbitrary rotation angles. See [details](/content-management/image-processing/#rotation).
+
+```go-html-template
+{{ $filter := images.Process "r90" }}
+{{ $filter := images.Process "crop 200x200 center r90" }}
+```
+
+target format
+: Specify zero or one of `gif`, `jpeg`, `png`, `tiff`, or `webp`. See [details](/content-management/image-processing/#target-format).
+
+```go-html-template
+{{ $filter := images.Process "webp" }}
+{{ $filter := images.Process "crop 200x200 center r90 webp" }}
+```
+
+quality
+: Applicable to JPEG and WebP images. Optionally specify `qN` where `N` is an integer in the range [0, 100]. Default is `75`. See [details](/content-management/image-processing/#quality).
+
+```go-html-template
+{{ $filter := images.Process "q50" }}
+{{ $filter := images.Process "crop 200x200 center r90 webp q50" }}
+```
+
+hint
+: Applicable to WebP images and equivalent to the `-preset` flag for the [`cwebp`] encoder. Specify zero or one of `drawing`, `icon`, `photo`, `picture`, or `text`. Default is `photo`. See [details](/content-management/image-processing/#hint).
+
+[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
+
+
+```go-html-template
+{{ $filter := images.Process "webp" "icon" }}
+{{ $filter := images.Process "crop 200x200 center r90 webp q50 icon" }}
+```
+
+background color
+: When converting a PNG or WebP with transparency to a format that does not support transparency, optionally specify a background color using a 3-digit or a 6-digit hexadecimal color code. Default is `#ffffff` (white). See [details](/content-management/image-processing/#background-color).
+
+```go-html-template
+{{ $filter := images.Process "jpeg #000" }}
+{{ $filter := images.Process "crop 200x200 center r90 q50 jpeg #000" }}
+```
+
+resampling filter
+: Typically specify zero or one of `Box`, `Lanczos`, `CatmullRom`, `MitchellNetravali`, `Linear`, or `NearestNeighbor`. Other resampling filters are available. See [details](/content-management/image-processing/#resampling-filter).
+
+```go-html-template
+{{ $filter := images.Process "resize 300x lanczos" }}
+{{ $filter := images.Process "resize 300x r90 q50 jpeg #000 lanczos" }}
+```
+
+## Usage
+
+Create a filter:
+
+```go-html-template
+{{ $filter := images.Process "resize 256x q40 webp" }}
+```
+
+{{% include "functions/images/_common/apply-image-filter.md" %}}
+
+## Example
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Process"
+ filterArgs="resize 256x q40 webp"
+ example=true
+>}}
--- /dev/null
- The sigma parameter is used in a gaussian function and affects the radius of effect. Sigma must be positive. The sharpen radius is approximately 3 times the sigma value.
+---
+title: images.UnsharpMask
+description: Returns an image filter that sharpens an image.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/images/Filter
+ - methods/resource/Filter
+ returnType: images.filter
+ signatures: [images.UnsharpMask SIGMA AMOUNT THRESHOLD]
+toc: true
+---
+
- The amount parameter controls how much darker and how much lighter the edge borders become. Typically between 0.5 and 1.5.
++The sigma argument is used in a gaussian function and affects the radius of effect. Sigma must be positive. The sharpen radius is approximately 3 times the sigma value.
+
- The threshold parameter controls the minimum brightness change that will be sharpened. Typically between 0 and 0.05.
++The amount argument controls how much darker and how much lighter the edge borders become. Typically between 0.5 and 1.5.
+
++The threshold argument controls the minimum brightness change that will be sharpened. Typically between 0 and 0.05.
+
+## Usage
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.UnsharpMask 10 0.4 0.03 }}
+```
+
+{{% include "functions/images/_common/apply-image-filter.md" %}}
+
+## Example
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="UnsharpMask"
+ filterArgs="10,0.4,0.03"
+ example=true
+>}}
--- /dev/null
- Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+---
+cascade:
+ _build:
+ list: never
+ publishResources: false
+ render: never
+---
+
+<!--
++Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+
+Include the rendered content using the "include" shortcode.
+-->
--- /dev/null
- [`images.Filter`]: /functions/images/filter
+---
+# Do not remove front matter.
+---
+
+Apply the filter using the [`images.Filter`] function:
+
- [`Filter`]: methods/resource/filter
++[`images.Filter`]: /functions/images/filter/
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with . | images.Filter $filter }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+You can also apply the filter using the [`Filter`] method on a `Resource` object:
+
++[`Filter`]: /methods/resource/filter/
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Filter $filter }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
--- /dev/null
-
- See also the `.Data.Singular` [taxonomy variable](/variables/taxonomy/) for singularizing taxonomy names.
+---
+title: inflect.Singularize
+description: Singularizes the given word according to a set of common English singularization rules.
+categories: []
+keywords: []
+action:
+ aliases: [singularize]
+ related:
+ - functions/inflect/Humanize
+ - functions/inflect/Pluralize
+ returnType: string
+ signatures: [inflect.Singularize INPUT]
+aliases: [/functions/singularize]
+---
+
+```go-html-template
+{{ "cats" | singularize }} → cat
+```
--- /dev/null
- : (`string`) Which library to use to automatically import its JSX helper functions from. This only works if `JSX` is set to `automatic`. The specified library needs to be installed through NPM and expose certain exports. See https://esbuild.github.io/api/#jsx-import-source
+---
+title: js.Build
+description: Bundles, transpiles, tree shakes, and minifies JavaScript resources.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/resources/Babel
+ - functions/resources/Fingerprint
+ - functions/resources/Minify
+ returnType: resource.Resource
+ signatures: ['js.Build [OPTIONS] RESOURCE']
+toc: true
+---
+
+The `js.Build` function uses the [evanw/esbuild] package to:
+
+- Bundle
+- Transpile (TypeScript and JSX)
+- Tree shake
+- Minify
+- Create source maps
+
+[evanw/esbuild]: https://github.com/evanw/esbuild
+
+```go-html-template
+{{ with resources.Get "js/main.js" }}
+ {{ if hugo.IsDevelopment }}
+ {{ with . | js.Build }}
+ <script src="{{ .RelPermalink }}"></script>
+ {{ end }}
+ {{ else }}
+ {{ $opts := dict "minify" true }}
+ {{ with . | js.Build $opts | fingerprint }}
+ <script src="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"></script>
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+## Options
+
+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
+: (`map` or `slice`) Params that can be imported as JSON in your JS files, e.g.
+
+```go-html-template
+{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }}
+```
+And then in your JS file:
+
+```js
+import * as params from '@params';
+```
+
+Note that this is meant for small data sets, e.g. configuration settings. For larger data, please put/mount the files into `/assets` and import them directly.
+
+minify
+: (`bool`)Let `js.Build` handle the minification.
+
+inject
+: (`slice`) This option allows you to automatically replace a global variable with an import from another file. The path names must be relative to `assets`. See https://esbuild.github.io/api/#inject
+
+shims
+: (`map`) This option allows swapping out a component with another. A common use case is to load dependencies like React from a CDN (with _shims_) when in production, but running with the full bundled `node_modules` dependency during development:
+
+```go-html-template
+{{ $shims := dict "react" "js/shims/react.js" "react-dom" "js/shims/react-dom.js" }}
+{{ $js = $js | js.Build dict "shims" $shims }}
+```
+
+The _shim_ files may look like these:
+
+```js
+// js/shims/react.js
+module.exports = window.React;
+```
+
+```js
+// js/shims/react-dom.js
+module.exports = window.ReactDOM;
+```
+
+With the above, these imports should work in both scenarios:
+
+```js
+import * as React from 'react'
+import * as ReactDOM from 'react-dom';
+```
+
+target
+: (`string`) The language target. One of: `es5`, `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020` or `esnext`. Default is `esnext`.
+
+externals
+: (`slice`) External dependencies. Use this to trim dependencies you know will never be executed. See https://esbuild.github.io/api/#external
+
+defines
+: (`map`) Allow to define a set of string replacement to be performed when building. Should be a map where each key is to be replaced by its value.
+
+```go-html-template
+{{ $defines := dict "process.env.NODE_ENV" `"development"` }}
+```
+
+format
+: (`string`) The output format. One of: `iife`, `cjs`, `esm`. Default is `iife`, a self-executing function, suitable for inclusion as a `<script>` tag.
+
+sourceMap
+: (`string`) Whether to generate `inline` or `external` source maps from esbuild. External source maps will be written to the target with the output file name + ".map". Input source maps can be read from js.Build and node modules and combined into the output source maps. By default, source maps are not created.
+
+JSX {{< new-in 0.124.0 >}}
+: (`string`) How to handle/transform JSX syntax. One of: `transform`, `preserve`, `automatic`. Default is `transform`. Notably, the `automatic` transform was introduced in React 17+ and will cause the necessary JSX helper functions to be imported automatically. See https://esbuild.github.io/api/#jsx
+
+JSXImportSource {{< new-in 0.124.0 >}}
++: (`string`) Which library to use to automatically import its JSX helper functions from. This only works if `JSX` is set to `automatic`. The specified library needs to be installed through npm and expose certain exports. See https://esbuild.github.io/api/#jsx-import-source
+
+The combination of `JSX` and `JSXImportSource` is helpful if you want to use a non-React JSX library like Preact, e.g.:
+
+```go-html-template
+{{ $js := resources.Get "js/main.jsx" | js.Build (dict "JSX" "automatic" "JSXImportSource" "preact") }}
+```
+
+With the above, you can use Preact components and JSX without having to manually import `h` and `Fragment` every time:
+
+```jsx
+import { render } from 'preact';
+
+const App = () => <>Hello world!</>;
+
+const container = document.getElementById('app');
+if (container) render(<App />, container);
+```
+
+### Import JS code from /assets
+
+`js.Build` has full support for the virtual union file system in [Hugo Modules](/hugo-modules/). You can see some simple examples in this [test project](https://github.com/gohugoio/hugoTestProjectJSModImports), but in short this means that you can do this:
+
+```js
+import { hello } from 'my/module';
+```
+
+And it will resolve to the top-most `index.{js,ts,tsx,jsx}` inside `assets/my/module` in the layered file system.
+
+```js
+import { hello3 } from 'my/module/hello3';
+```
+
+Will resolve to `hello3.{js,ts,tsx,jsx}` inside `assets/my/module`.
+
+Any imports starting with `.` is resolved relative to the current file:
+
+```js
+import { hello4 } from './lib';
+```
+
+For other files (e.g. `JSON`, `CSS`) you need to use the relative path including any extension, e.g:
+
+```js
+import * as data from 'my/module/data.json';
+```
+
+Any imports in a file outside `/assets` or that does not resolve to a component inside `/assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`.
+
+Also note the new `params` option that can be passed from template to your JS files, e.g.:
+
+```go-html-template
+{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }}
+```
+And then in your JS file:
+
+```js
+import * as params from '@params';
+```
+
+Hugo will, by default, generate a `assets/jsconfig.json` file that maps the imports. This is useful for navigation/intellisense help inside code editors, but if you don't need/want it, you can [turn it off](/getting-started/configuration/#configure-build).
+
+## Node.js dependencies
+
+Use the `js.Build` function to include Node.js dependencies.
+
+Any imports in a file outside `/assets` or that does not resolve to a component inside `/assets` will be resolved by [esbuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`.
+
+The start directory for resolving npm packages (aka. packages that live inside a `node_modules` folder) is always the main project folder.
+
+{{% note %}}
+If you're developing a theme/component that is supposed to be imported and depends on dependencies inside `package.json`, we recommend reading about [hugo mod npm pack](/commands/hugo_mod_npm_pack/), a tool to consolidate all the npm dependencies in a project.
+{{% /note %}}
+
+## Examples
+
+```go-html-template
+{{ $built := resources.Get "js/index.js" | js.Build "main.js" }}
+```
+
+Or with options:
+
+```go-html-template
+{{ $externals := slice "react" "react-dom" }}
+{{ $defines := dict "process.env.NODE_ENV" `"development"` }}
+
+{{ $opts := dict "targetPath" "main.js" "externals" $externals "defines" $defines }}
+{{ $built := resources.Get "scripts/main.js" | js.Build $opts }}
+<script src="{{ $built.RelPermalink }}" defer></script>
+```
--- /dev/null
- [`lang.FormatNumber`]: /functions/lang/formatnumber
+---
+title: lang.FormatNumberCustom
+description: Returns a numeric representation of a number with the given precision using negative, decimal, and grouping options.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/lang/FormatAccounting
+ - functions/lang/FormatCurrency
+ - functions/lang/FormatNumber
+ - functions/lang/FormatPercent
+ returnType: string
+ signatures: ['lang.FormatNumberCustom PRECISION NUMBER [OPTIONS...]']
+aliases: ['/functions/numfmt/']
+---
+
+This function formats a number with the given precision. The first options parameter is a space-delimited string of characters to represent negativity, the decimal point, and grouping. The default value is `- . ,`. The second options parameter defines an alternate delimiting character.
+
+Note that numbers are rounded up at 5 or greater. So, with precision set to 0, 1.5 becomes 2, and 1.4 becomes 1.
+
+For a simpler function that adapts to the current language, see [`lang.FormatNumber`].
+
+```go-html-template
+{{ lang.FormatNumberCustom 2 12345.6789 }} → 12,345.68
+{{ lang.FormatNumberCustom 2 12345.6789 "- , ." }} → 12.345,68
+{{ lang.FormatNumberCustom 6 -12345.6789 "- ." }} → -12345.678900
+{{ lang.FormatNumberCustom 0 -12345.6789 "- . ," }} → -12,346
+{{ lang.FormatNumberCustom 0 -12345.6789 "-|.| " "|" }} → -12 346
+```
+
+{{% include "functions/_common/locales.md" %}}
+
++[`lang.FormatNumber`]: /functions/lang/formatnumber/
--- /dev/null
- [`warnf`]: /functions/fmt/warnf
- [`resources.FromString`]: /functions/resources/fromstring
+---
+title: math.Counter
+description: Increments and returns a global counter.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related: []
+ returnType: uint64
+ signatures: [math.Counter]
+---
+
+The counter is global for both monolingual and multilingual sites, and its initial value for each build is 1.
+
+```go-html-template
+{{ warnf "single.html called %d times" math.Counter }}
+```
+
+```sh
+WARN single.html called 1 times
+WARN single.html called 2 times
+WARN single.html called 3 times
+```
+
+Use this function to:
+
+- Create unique warnings as shown above; the [`warnf`] function suppresses duplicate messages
+- Create unique target paths for the `resources.FromString` function where the target path is also the cache key
+
++[`warnf`]: /functions/fmt/warnf/
++[`resources.FromString`]: /functions/resources/fromstring/
+
+{{% note %}}
+Due to concurrency, the value returned in a given template for a given page will vary from one build to the next. You cannot use this function to assign a static id to each page.
+{{% /note %}}
--- /dev/null
- [security policy]: /about/security-model/#security-policy
+---
+title: os.Getenv
+description: Returns the value of an environment variable, or an empty string if the environment variable is not set.
+categories: []
+keywords: []
+action:
+ aliases: [getenv]
+ related:
+ - functions/os/FileExists
+ - functions/os/ReadDir
+ - functions/os/ReadFile
+ - functions/os/Stat
+ returnType: string
+ signatures: [os.Getenv VARIABLE]
+aliases: [/functions/getenv]
+toc: true
+---
+
+## Security
+
+By default, when using the `os.Getenv` function Hugo allows access to:
+
+- The `CI` environment variable
+- Any environment variable beginning with `HUGO_`
+
+To access other environment variables, adjust your site configuration. For example, to allow access to the `HOME` and `USER` environment variables:
+
+{{< code-toggle file=hugo >}}
+[security.funcs]
+getenv = ['^HUGO_', '^CI$', '^USER$', '^HOME$']
+{{< /code-toggle >}}
+
+Read more about Hugo's [security policy].
+
++[security policy]: /about/security/#security-policy
+
+## Examples
+
+```go-html-template
+{{ getenv "HOME" }} → /home/victor
+{{ getenv "USER" }} → victor
+```
+
+You can pass values when building your site:
+
+```sh
+MY_VAR1=foo MY_VAR2=bar hugo
+
+OR
+
+export MY_VAR1=foo
+export MY_VAR2=bar
+hugo
+```
+
+And then retrieve the values within a template:
+
+```go-html-template
+{{ getenv "MY_VAR1" }} → foo
+{{ getenv "MY_VAR2" }} → bar
+```
--- /dev/null
- [`return`]: /functions/go-template/return
+---
+title: partials.Include
+description: Executes the given partial template, optionally passing context. If the partial template contains a return statement, returns the given value, else returns the rendered output.
+categories: []
+keywords: []
+action:
+ aliases: [partial]
+ related:
+ - functions/go-template/return
+ - functions/partials/IncludeCached
+ - functions/go-template/template
+ - methods/page/Render
+ returnType: any
+ signatures: ['partials.Include NAME [CONTEXT]']
+aliases: [/functions/partial]
+---
+
+Without a [`return`] statement, the `partial` function returns a string of type `template.HTML`. With a `return` statement, the `partial` function can return any data type.
+
- You can pass anything in context: a page, a page collection, a scalar value, a slice, or a map. For example:
++[`return`]: /functions/go-template/return/
+
+In this example we have three partial templates:
+
+```text
+layouts/
+└── partials/
+ ├── average.html
+ ├── breadcrumbs.html
+ └── footer.html
+```
+
+The "average" partial returns the average of one or more numbers. We pass the numbers in context:
+
+```go-html-template
+{{ $numbers := slice 1 6 7 42 }}
+{{ $average := partial "average.html" $numbers }}
+```
+
+The "breadcrumbs" partial renders [breadcrumb navigation], and needs to receive the current page in context:
+
+```go-html-template
+{{ partial "breadcrumbs.html" . }}
+```
+
+The "footer" partial renders the site footer. In this contrived example, the footer does not need access to the current page, so we can omit context:
+
+```go-html-template
+{{ partial "breadcrumbs.html" }}
+```
+
- {{ $student := dict
++You can pass anything in context: a page, a page collection, a scalar value, a slice, or a map. In this example we pass the current page and three scalar values:
+
+```go-html-template
- {{ partial "render-student-info.html" $student }}
++{{ $ctx := dict
++ "page" .
+ "name" "John Doe"
+ "major" "Finance"
+ "gpa" 4.0
+}}
- <p>{{ .name }} is majoring in {{ .major }}. Their grade point average is {{ .gpa }}.</p>
++{{ partial "render-student-info.html" $ctx }}
+```
+
+Then, within the partial template:
+
+```go-html-template
- [`return`]: /functions/go-template/return
++<p>{{ .name }} is majoring in {{ .major }}.</p>
++<p>Their grade point average is {{ .gpa }}.</p>
++<p>See <a href="{{ .page.RelPermalink }}">details.</a></p>
+```
+
+To return a value from a partial template, it must contain only one `return` statement, placed at the end of the template:
+
+```go-html-template
+{{ $result := "" }}
+{{ if math.ModBool . 2 }}
+ {{ $result = "even" }}
+{{ else }}
+ {{ $result = "odd" }}
+{{ end }}
+{{ return $result }}
+```
+
+See [details][`return`].
+
- [details]: /functions/go-template/return
++[`return`]: /functions/go-template/return/
+
+[breadcrumb navigation]: /content-management/sections/#ancestors-and-descendants
++[details]: /functions/go-template/return/
--- /dev/null
- [`return`]: /functions/go-template/return
+---
+title: partials.IncludeCached
+description: Executes the given template and caches the result, optionally passing context. If the partial template contains a return statement, returns the given value, else returns the rendered output.
+categories: []
+keywords: []
+action:
+ aliases: [partialCached]
+ related:
+ - functions/go-template/return
+ - functions/partials/Include
+ - functions/go-template/template
+ - methods/page/Render
+ returnType: any
+ signatures: ['partials.IncludeCached LAYOUT CONTEXT [VARIANT...]']
+signatures:
+ - partials.IncludeCached NAME CONTEXT [VARIANT...]
+ - partialCached NAME CONTEXT [VARIANT...]
+aliases: [/functions/partialcached]
+---
+
+Without a [`return`] statement, the `partialCached` function returns a string of type `template.HTML`. With a `return` statement, the `partialCached` function can return any data type.
+
+The `partialCached` function can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation.
+
+{{% note %}}
+Each Site (or language) has its own `partialCached` cache, so each site will execute a partial once.
+
+Hugo renders pages in parallel, and will render the partial more than once with concurrent calls to the `partialCached` function. After Hugo caches the rendered partial, new pages entering the build pipeline will use the cached result.
+{{% /note %}}
+
+Here is the simplest usage:
+
+```go-html-template
+{{ partialCached "footer.html" . }}
+```
+
+Pass additional arguments to `partialCached` to create variants of the cached partial. For example, if you have a complex partial that should be identical when rendered for pages within the same section, use a variant based on section so that the partial is only rendered once per section:
+
+{{< code file=partial-cached-example.html >}}
+{{ partialCached "footer.html" . .Section }}
+{{< /code >}}
+
+Pass additional arguments, of any data type, as needed to create unique variants:
+
+```go-html-template
+{{ partialCached "footer.html" . .Params.country .Params.province }}
+```
+
+The variant arguments are not available to the underlying partial template; they are only used to create unique cache keys.
+
+To return a value from a partial template, it must contain only one `return` statement, placed at the end of the template:
+
+```go-html-template
+{{ $result := "" }}
+{{ if math.ModBool . 2 }}
+ {{ $result = "even" }}
+{{ else }}
+ {{ $result = "odd" }}
+{{ end }}
+{{ return $result }}
+```
+
+See [details][`return`].
+
++[`return`]: /functions/go-template/return/
--- /dev/null
- [`Resources.ByType`]: /methods/page/resources
+---
+title: resources.ByType
+description: Returns a collection of global resources of the given media type, or nil if none found.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/resources/Get
+ - functions/resources/GetMatch
+ - functions/resources/GetRemote
+ - functions/resources/Match
+ - methods/page/Resources
+ returnType: resource.Resources
+ signatures: [resources.ByType MEDIATYPE]
+---
+
+The [media type] is typically one of `image`, `text`, `audio`, `video`, or `application`.
+
+```go-html-template
+{{ range resources.ByType "image" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+{{% note %}}
+This function operates on global resources. A global resource is a file within the assets directory, or within any directory mounted to the assets directory.
+
+For page resources, use the [`Resources.ByType`] method on the Page object.
+
++[`Resources.ByType`]: /methods/page/resources/
+{{% /note %}}
+
+[media type]: https://en.wikipedia.org/wiki/Media_type
--- /dev/null
- [`publish`]: /methods/resource/publish
- [`permalink`]: /methods/resource/permalink
- [`relpermalink`]: /methods/resource/relpermalink
+---
+title: resources.Concat
+description: Returns a concatenated slice of resources.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related: []
+ returnType: resource.Resource
+ signatures: ['resources.Concat TARGETPATH [RESOURCE...]']
+---
+
+The `resources.Concat` function returns a concatenated slice of resources, caching the result using the target path as its cache key. Each resource must have the same [media type].
+
+Hugo publishes the resource to the target path when you call its [`Publish`], [`Permalink`], or [`RelPermalink`] methods.
+
+[media type]: https://en.wikipedia.org/wiki/Media_type
++[`publish`]: /methods/resource/publish/
++[`permalink`]: /methods/resource/permalink/
++[`relpermalink`]: /methods/resource/relpermalink/
+
+```go-html-template
+{{ $plugins := resources.Get "js/plugins.js" }}
+{{ $global := resources.Get "js/global.js" }}
+{{ $js := slice $plugins $global | resources.Concat "js/bundle.js" }}
+```
--- /dev/null
- The target path must be different than the source path, as shown in the example above.
-
+---
+title: resources.Copy
+description: Copies the given resource to the target path.
+categories: []
+action:
+ aliases: []
+ related: []
+ returnType: resource.Resource
+ signatures: [resources.Copy TARGETPATH RESOURCE]
+---
+
+{{< new-in 0.100.0 >}}
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ with resources.Copy "img/new-image-name.jpg" . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+The relative URL of the new published resource will be:
+
+```text
+/img/new-image-name.jpg
+```
+
+{{% note %}}
+Use the `resources.Copy` function with global, page, and remote resources.
+{{% /note %}}
--- /dev/null
- [`publish`]: /methods/resource/publish
- [`permalink`]: /methods/resource/permalink
- [`relpermalink`]: /methods/resource/relpermalink
+---
+title: resources.ExecuteAsTemplate
+description: Returns a resource created from a Go template, parsed and executed with the given context.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/resources/FromString
+ returnType: resource.Resource
+ signatures: [resources.ExecuteAsTemplate TARGETPATH CONTEXT RESOURCE]
+---
+
+The `resources.ExecuteAsTemplate` function returns a resource created from a Go template, parsed and executed with the given context, caching the result using the target path as its cache key.
+
+Hugo publishes the resource to the target path when you call its [`Publish`], [`Permalink`], or [`RelPermalink`] methods.
+
++[`publish`]: /methods/resource/publish/
++[`permalink`]: /methods/resource/permalink/
++[`relpermalink`]: /methods/resource/relpermalink/
+
+Let's say you have a CSS file that you wish to populate with values from your site configuration:
+
+{{< code file=assets/css/template.css lang=go-html-template >}}
+body {
+ background-color: {{ site.Params.style.bg_color }};
+ color: {{ site.Params.style.text_color }};
+}
+{{< /code >}}
+
+And your site configuration contains:
+
+{{< code-toggle file=hugo >}}
+[params.style]
+bg_color = '#fefefe'
+text_color = '#222'
+{{< /code-toggle >}}
+
+Place this in your baseof.html template:
+
+```go-html-template
+{{ with resources.Get "css/template.css" }}
+ {{ with resources.ExecuteAsTemplate "css/main.css" $ . }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ end }}
+{{ end }}
+```
+
+The example above:
+
+1. Captures the template as a resource
+2. Executes the resource as a template, passing the current page in context
+3. Publishes the resource to css/main.css
+
+The result is:
+
+{{< code file=public/css/main.css >}}
+body {
+ background-color: #fefefe;
+ color: #222;
+}
+{{< /code >}}
--- /dev/null
- [`publish`]: /methods/resource/publish
- [`permalink`]: /methods/resource/permalink
- [`relpermalink`]: /methods/resource/relpermalink
+---
+title: resources.FromString
+description: Returns a resource created from a string.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/resources/ExecuteAsTemplate
+ returnType: resource.Resource
+ signatures: [resources.FromString TARGETPATH STRING]
+---
+
+The `resources.FromString` function returns a resource created from a string, caching the result using the target path as its cache key.
+
+Hugo publishes the resource to the target path when you call its [`Publish`], [`Permalink`], or [`RelPermalink`] methods.
+
- "build_date": "2023-10-03T10:50:40-07:00",
- "hugo_version": "0.122.0",
- "last_modified": "2023-10-02T15:21:27-07:00"
++[`publish`]: /methods/resource/publish/
++[`permalink`]: /methods/resource/permalink/
++[`relpermalink`]: /methods/resource/relpermalink/
+
+Let's say you need to publish a file named "site.json" in the root of your public directory, containing the build date, the Hugo version used to build the site, and the date that the content was last modified. For example:
+
+```json
+{
- "last_modified" (site.LastChange.Format $rfc3339)
++ "build_date": "2024-02-19T12:27:05-08:00",
++ "hugo_version": "0.126.0",
++ "last_modified": "2024-02-19T12:01:42-08:00"
+}
+```
+
+Place this in your baseof.html template:
+
+```go-html-template
+{{ if .IsHome }}
+ {{ $rfc3339 := "2006-01-02T15:04:05Z07:00" }}
+ {{ $m := dict
+ "hugo_version" hugo.Version
+ "build_date" (now.Format $rfc3339)
- 1. Creates a map with the relevant key/value pairs using the [`dict`] function
++ "last_modified" (site.Lastmod.Format $rfc3339)
+ }}
+ {{ $json := jsonify $m }}
+ {{ $r := resources.FromString "site.json" $json }}
+ {{ $r.Publish }}
+{{ end }}
+```
+
+The example above:
+
- "last_modified" (site.LastChange.Format $rfc3339)
++1. Creates a map with the relevant key-value pairs using the [`dict`] function
+2. Encodes the map as a JSON string using the [`jsonify`] function
+3. Creates a resource from the JSON string using the `resources.FromString` function
+4. Publishes the file to the root of the public directory using the resource's `.Publish` method
+
+Combine `resources.FromString` with [`resources.ExecuteAsTemplate`] if your string contains template actions. Rewriting the example above:
+
+```go-html-template
+{{ if .IsHome }}
+ {{ $string := `
+ {{ $rfc3339 := "2006-01-02T15:04:05Z07:00" }}
+ {{ $m := dict
+ "hugo_version" hugo.Version
+ "build_date" (now.Format $rfc3339)
- [`dict`]: /functions/collections/dictionary
- [`jsonify`]: /functions/encoding/jsonify
- [`resources.ExecuteAsTemplate`]: /functions/resources/executeastemplate
++ "last_modified" (site.Lastmod.Format $rfc3339)
+ }}
+ {{ $json := jsonify $m }}
+ `
+ }}
+ {{ $r := resources.FromString "" $string }}
+ {{ $r = $r | resources.ExecuteAsTemplate "site.json" . }}
+ {{ $r.Publish }}
+{{ end }}
+```
+
++[`dict`]: /functions/collections/dictionary/
++[`jsonify`]: /functions/encoding/jsonify/
++[`resources.ExecuteAsTemplate`]: /functions/resources/executeastemplate/
--- /dev/null
- [`Resources.Get`]: /methods/page/resources
+---
+title: resources.Get
+description: Returns a global resource from the given path, or nil if none found.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/resources/ByType
+ - functions/resources/GetMatch
+ - functions/resources/GetRemote
+ - functions/resources/Match
+ - methods/page/Resources
+ returnType: resource.Resource
+ signatures: [resources.Get PATH]
+---
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+{{% note %}}
+This function operates on global resources. A global resource is a file within the assets directory, or within any directory mounted to the assets directory.
+
+For page resources, use the [`Resources.Get`] method on the Page object.
+
++[`Resources.Get`]: /methods/page/resources/
+{{% /note %}}
--- /dev/null
- [`Resources.GetMatch`]: /methods/page/resources
+---
+title: resources.GetMatch
+description: Returns the first global resource from paths matching the given glob pattern, or nil if none found.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/resources/ByType
+ - functions/resources/Get
+ - functions/resources/GetRemote
+ - functions/resources/Match
+ - methods/page/Resources
+ returnType: resource.Resource
+ signatures: [resources.GetMatch PATTERN]
+---
+
+```go-html-template
+{{ with resources.GetMatch "images/*.jpg" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+{{% note %}}
+This function operates on global resources. A global resource is a file within the assets directory, or within any directory mounted to the assets directory.
+
+For page resources, use the [`Resources.GetMatch`] method on the Page object.
+
++[`Resources.GetMatch`]: /methods/page/resources/
+{{% /note %}}
+
+Hugo determines a match using a case-insensitive [glob pattern].
+
+{{% include "functions/_common/glob-patterns.md" %}}
+
+[glob pattern]: https://github.com/gobwas/glob#example
--- /dev/null
- [`transform.Unmarshal`]: /functions/transform/unmarshal
+---
+title: resources.GetRemote
+description: Returns a remote resource from the given URL, or nil if none found.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/data/GetCSV
+ - functions/data/GetJSON
+ - functions/resources/ByType
+ - functions/resources/Get
+ - functions/resources/GetMatch
+ - functions/resources/Match
+ - methods/page/Resources
+ returnType: resource.Resource
+ signatures: ['resources.GetRemote URL [OPTIONS]']
+toc: true
+---
+
+```go-html-template
+{{ $url := "https://example.org/images/a.jpg" }}
+{{ with resources.GetRemote $url }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+{{ end }}
+```
+
+## Options
+
+The `resources.GetRemote` function takes an optional map of options.
+
+```go-html-template
+{{ $url := "https://example.org/api" }}
+{{ $opts := dict
+ "headers" (dict "Authorization" "Bearer abcd")
+}}
+{{ $resource := resources.GetRemote $url $opts }}
+```
+
+If you need multiple values for the same header key, use a slice:
+
+```go-html-template
+{{ $url := "https://example.org/api" }}
+{{ $opts := dict
+ "headers" (dict "X-List" (slice "a" "b" "c"))
+}}
+{{ $resource := resources.GetRemote $url $opts }}
+```
+
+You can also change the request method and set the request body:
+
+```go-html-template
+{{ $url := "https://example.org/api" }}
+{{ $opts := dict
+ "method" "post"
+ "body" `{"complete": true}`
+ "headers" (dict "Content-Type" "application/json")
+}}
+{{ $resource := resources.GetRemote $url $opts }}
+```
+
+## Remote data
+
+When retrieving remote data, use the [`transform.Unmarshal`] function to [unmarshal] the response.
+
- {{ $data := "" }}
++[`transform.Unmarshal`]: /functions/transform/unmarshal/
+[unmarshal]: /getting-started/glossary/#unmarshal
+
+```go-html-template
- [`Err`]: /methods/resource/err
++{{ $data := dict }}
+{{ $url := "https://example.org/books.json" }}
+{{ with resources.GetRemote $url }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else }}
+ {{ $data = . | transform.Unmarshal }}
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+{{ end }}
+```
+
++{{% 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 %}}
++
+## Error handling
+
+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.
+
- [`Data`]: /methods/resource/data
++[`Err`]: /methods/resource/err/
+
+```go-html-template
+{{ $url := "https://broken-example.org/images/a.jpg" }}
+{{ with resources.GetRemote $url }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+{{ end }}
+```
+
+To log an error as a warning instead of an error:
+
+```go-html-template
+{{ $url := "https://broken-example.org/images/a.jpg" }}
+{{ with resources.GetRemote $url }}
+ {{ with .Err }}
+ {{ warnf "%s" . }}
+ {{ else }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+{{ end }}
+```
+
+## HTTP response
+
+The [`Data`] method on a resource returned by the `resources.GetRemote` function returns information from the HTTP response.
+
- ```text
++[`Data`]: /methods/resource/data/
+
+```go-html-template
+{{ $url := "https://example.org/images/a.jpg" }}
+{{ with resources.GetRemote $url }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else }}
+ {{ with .Data }}
+ {{ .ContentLength }} → 42764
+ {{ .ContentType }} → image/jpeg
+ {{ .Status }} → 200 OK
+ {{ .StatusCode }} → 200
+ {{ .TransferEncoding }} → []
+ {{ end }}
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+{{ end }}
+```
+
+ContentLength
+: (`int`) The content length in bytes.
+
+ContentType
+: (`string`) The content type.
+
+Status
+: (`string`) The HTTP status text.
+
+StatusCode
+: (`int`) The HTTP status code.
+
+TransferEncoding
+: (`string`) The transfer encoding.
+
+## Caching
+
+Resources returned from `resources.GetRemote` are cached to disk. See [configure file caches] for details.
+
+By default, Hugo derives the cache key from the arguments passed to the function, the URL and the options map, if any.
+
+Override the cache key by setting a `key` in the options map. Use this approach to have more control over how often Hugo fetches a remote resource.
+
+```go-html-template
+{{ $url := "https://example.org/images/a.jpg" }}
+{{ $cacheKey := print $url (now.Format "2006-01-02") }}
+{{ $resource := resources.GetRemote $url (dict "key" $cacheKey) }}
+```
+
+[configure file caches]: /getting-started/configuration/#configure-file-caches
+
+## Security
+
+To protect against malicious intent, the `resources.GetRemote` function inspects the server response including:
+
+- The [Content-Type] in the response header
+- The file extension, if any
+- The content itself
+
+If Hugo is unable to resolve the media type to an entry in its [allowlist], the function throws an error:
+
+```text
+ERROR error calling resources.GetRemote: failed to resolve media type...
+```
+
+For example, you will see the error above if you attempt to download an executable.
+
+Although the allowlist contains entries for common media types, you may encounter situations where Hugo is unable to resolve the media type of a file that you know to be safe. In these situations, edit your site configuration to add the media type to the allowlist. For example:
+
- mediaTypes=['application/vnd\.api\+json']
- ```
++{{< code-toggle file=hugo >}}
+[security.http]
- For example, to add two entries to the allowlist:
-
- ```text
- [security.http]
- mediaTypes=['application/vnd\.api\+json','image/avif']
- ```
-
++mediaTypes = ['^image/avif$','^application/vnd\.api\+json$']
++{{< /code-toggle >}}
+
+Note that the entry above is:
+
+- An _addition_ to the allowlist; it does not _replace_ the allowlist
+- An array of regular expressions
+
+[allowlist]: https://en.wikipedia.org/wiki/Whitelist
+[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
--- /dev/null
- [`Resources.Match`]: /methods/page/resources
+---
+title: resources.Match
+description: Returns a collection of global resources from paths matching the given glob pattern, or nil if none found.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/resources/ByType
+ - functions/resources/Get
+ - functions/resources/GetMatch
+ - functions/resources/GetRemote
+ - methods/page/Resources
+ returnType: resource.Resources
+ signatures: [resources.Match PATTERN]
+---
+
+```go-html-template
+{{ range resources.Match "images/*.jpg" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+{{% note %}}
+This function operates on global resources. A global resource is a file within the assets directory, or within any directory mounted to the assets directory.
+
+For page resources, use the [`Resources.Match`] method on the Page object.
+
++[`Resources.Match`]: /methods/page/resources/
+{{% /note %}}
+
+Hugo determines a match using a case-insensitive [glob pattern].
+
+{{% include "functions/_common/glob-patterns.md" %}}
+
+[glob pattern]: https://github.com/gobwas/glob#example
--- /dev/null
- : (`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/).
+---
+title: resources.ToCSS
+description: Transpiles Sass to CSS.
+categories: []
+keywords: []
+action:
+ aliases: [toCSS]
+ related:
+ - functions/resources/Fingerprint
+ - functions/resources/Minify
+ - functions/resources/PostCSS
+ - functions/resources/PostProcess
+ returnType: resource.Resource
+ signatures: ['resources.ToCSS [OPTIONS] RESOURCE']
+toc: true
+---
+
+```go-html-template
+{{ with resources.Get "sass/main.scss" }}
+ {{ $opts := dict "transpiler" "libsass" "targetPath" "css/style.css" }}
+ {{ with . | toCSS $opts }}
+ {{ if hugo.IsDevelopment }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ else }}
+ {{ with . | minify | fingerprint }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+Transpile Sass to CSS using the LibSass transpiler included in Hugo's extended edition, or [install Dart Sass](#dart-sass) to use the latest features of the Sass language.
+
+Sass has two forms of syntax: [SCSS] and [indented]. Hugo supports both.
+
+[scss]: https://sass-lang.com/documentation/syntax#scss
+[indented]: https://sass-lang.com/documentation/syntax#the-indented-syntax
+
+## Options
+
+transpiler
+: (`string`) The transpiler to use, either `libsass` (default) or `dartsass`. Hugo's extended edition includes the LibSass transpiler. To use the Dart Sass transpiler, see the [installation instructions](#dart-sass) below.
+
+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
- HUGO_VERSION: 0.122.0
- DART_SASS_VERSION: 1.70.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/).
+
+```scss
+// LibSass
+@import "hugo:vars";
+
+// Dart Sass
+@use "hugo:vars" as v;
+```
+
+outputStyle
+: (`string`) Output styles available to LibSass include `nested` (default), `expanded`, `compact`, and `compressed`. Output styles available to Dart Sass include `expanded` (default) and `compressed`.
+
+precision
+: (`int`) Precision of floating point math. Not applicable to Dart Sass.
+
+enableSourceMap
+: (`bool`) If `true`, generates a source map.
+
+sourceMapIncludeSources
+: (`bool`) If `true`, embeds sources in the generated source map. Not applicable to LibSass.
+
+includePaths
+: (`slice`) A slice of paths, relative to the project root, that the transpiler will use when resolving `@use` and `@import` statements.
+
+```go-html-template
+{{ $opts := dict
+ "transpiler" "dartsass"
+ "targetPath" "css/style.css"
+ "vars" site.Params.styles
+ "enableSourceMap" (not hugo.IsProduction)
+ "includePaths" (slice "node_modules/bootstrap/scss")
+}}
+{{ with resources.Get "sass/main.scss" | toCSS $opts | minify | fingerprint }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+{{ end }}
+```
+
+## Dart Sass
+
+The extended version of Hugo includes [LibSass] to transpile Sass to CSS. In 2020, the Sass team deprecated LibSass in favor of [Dart Sass].
+
+Use the latest features of the Sass language by installing Dart Sass in your development and production environments.
+
+### Installation overview
+
+Dart Sass is compatible with Hugo v0.114.0 and later.
+
+If you have been using Embedded Dart Sass[^1] with Hugo v0.113.0 and earlier, uninstall Embedded Dart Sass, then install Dart Sass. If you have installed both, Hugo will use Dart Sass.
+
+If you install Hugo as a [Snap package] there is no need to install Dart Sass. The Hugo Snap package includes Dart Sass.
+
+[^1]: In 2023, the Sass team deprecated Embedded Dart Sass in favor of Dart Sass.
+
+### Installing in a development environment
+
+When you install Dart Sass somewhere in your PATH, Hugo will find it.
+
+OS|Package manager|Site|Installation
+:--|:--|:--|:--
+Linux|Homebrew|[brew.sh]|`brew install sass/sass/sass`
+Linux|Snap|[snapcraft.io]|`sudo snap install dart-sass`
+macOS|Homebrew|[brew.sh]|`brew install sass/sass/sass`
+Windows|Chocolatey|[chocolatey.org]|`choco install sass`
+Windows|Scoop|[scoop.sh]|`scoop install sass`
+
+You may also install [prebuilt binaries] for Linux, macOS, and Windows.
+
+Run `hugo env` to list the active transpilers.
+
+### Installing in a production environment
+
+For [CI/CD] deployments (e.g., GitHub Pages, GitLab Pages, Netlify, etc.) you must edit the workflow to install Dart Sass before Hugo builds the site[^2]. Some providers allow you to use one of the package managers above, or you can download and extract one of the prebuilt binaries.
+
+[^2]: You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set `useResourceCacheWhen` to `never` in your [site configuration], and (c) you add and commit your resources directory to your repository.
+
+#### GitHub Pages
+
+To install Dart Sass for your builds on GitHub Pages, add this step to the GitHub Pages workflow file:
+
+```yaml
+- name: Install Dart Sass
+ run: sudo snap install dart-sass
+```
+
+If you are using GitHub Pages for the first time with your repository, GitHub provides a [starter workflow] for Hugo that includes Dart Sass. This is the simplest way to get started.
+
+#### GitLab Pages
+
+To install Dart Sass for your builds on GitLab Pages, the `.gitlab-ci.yml` file should look something like this:
+
+```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
+ TZ: America/Los_Angeles
+image:
+ name: golang:1.20-buster
+pages:
+ script:
+ # Install Dart Sass
+ - 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
+ - cp -r dart-sass/* /usr/local/bin
+ - rm -rf dart-sass*
+ # Install Hugo
+ - curl -LJO https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
+ - apt install -y ./hugo_extended_${HUGO_VERSION}_linux-amd64.deb
+ - rm hugo_extended_${HUGO_VERSION}_linux-amd64.deb
+ # Build
+ - hugo --gc --minify
+ artifacts:
+ paths:
+ - public
+ rules:
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+```
+
+#### Netlify
+
+To install Dart Sass for your builds on Netlify, the `netlify.toml` file should look something like this:
+
+```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 \
+ """
+```
+
+### Example
+
+To transpile with Dart Sass, set `transpiler` to `dartsass` in the options map passed to `resources.ToCSS`. For example:
+
+```go-html-template
+{{ with resources.Get "sass/main.scss" }}
+ {{ $opts := dict "transpiler" "dartsass" "targetPath" "css/style.css" }}
+ {{ with . | toCSS $opts }}
+ {{ if hugo.IsDevelopment }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ else }}
+ {{ with . | minify | fingerprint }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+### Miscellaneous
+
+If you build Hugo from source and run `mage test -v`, the test will fail if you install Dart Sass as a Snap package. This is due to the Snap package's strict confinement model.
+
+[brew.sh]: https://brew.sh/
+[chocolatey.org]: https://community.chocolatey.org/packages/sass
+[ci/cd]: https://en.wikipedia.org/wiki/CI/CD
+[dart sass]: https://sass-lang.com/dart-sass
+[libsass]: https://sass-lang.com/libsass
+[prebuilt binaries]: https://github.com/sass/dart-sass/releases/latest
+[scoop.sh]: https://scoop.sh/#/apps?q=sass
+[site configuration]: /getting-started/configuration/#configure-build
+[snap package]: /installation/linux/#snap
+[snapcraft.io]: https://snapcraft.io/dart-sass
+[starter workflow]: https://github.com/actions/starter-workflows/blob/main/pages/hugo.yml
--- /dev/null
- Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+---
+_build:
+ list: never
+ publishResources: false
+ render: never
+---
+
+<!--
++Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+
+Include the rendered content using the "include" shortcode.
+-->
--- /dev/null
- description: Declares the given string as safe CSS string.
+---
+title: safe.CSS
- In this context, *safe* means CSS content that matches any of the following:
++description: Declares the given string as a safe CSS string.
+categories: []
+keywords: []
+action:
+ aliases: [safeCSS]
+ related:
+ - functions/safe/HTML
+ - functions/safe/HTMLAttr
+ - functions/safe/JS
+ - functions/safe/JSStr
+ - functions/safe/URL
+ returnType: template.CSS
+ signatures: [safe.CSS INPUT]
++toc: true
+aliases: [/functions/safecss]
+---
+
- Example: Given `style = "color: red;"` defined in the front matter of your `.md` file:
++## Introduction
++
++{{% include "functions/_common/go-html-template-package.md" %}}
++
++## Usage
++
++Use the `safe.CSS` function to encapsulate known safe content that matches any of:
+
+1. The CSS3 stylesheet production, such as `p { color: purple }`.
+2. The CSS3 rule production, such as `a[href=~"https:"].foo#bar`.
+3. CSS3 declaration productions, such as `color: red; margin: 2px`.
+4. The CSS3 value production, such as `rgba(0, 0, 255, 127)`.
+
- * `<p style="{{ .Params.style | safeCSS }}">…</p>` → `<p style="color: red;">…</p>`
- * `<p style="{{ .Params.style }}">…</p>` → `<p style="ZgotmplZ">…</p>`
++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#CSS
++
++## Example
++
++Without a safe declaration:
+
- `ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context.
++```go-html-template
++{{ $style := "color: red;" }}
++<p style="{{ $style }}">foo</p>
++```
++
++Hugo renders the above to:
++
++```html
++<p style="ZgotmplZ">foo</p>
++```
+
+{{% 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:
++
++```go-html-template
++{{ $style := "color: red;" }}
++<p style="{{ $style | safeCSS }}">foo</p>
++```
++
++Hugo renders the above to:
++
++```html
++<p style="color: red;">foo</p>
++```
--- /dev/null
- It should not be used for HTML from a third-party, or HTML with unclosed tags or comments.
+---
+title: safe.HTML
+description: Declares the given string as a safeHTML string.
+categories: []
+keywords: []
+action:
+ aliases: [safeHTML]
+ related:
+ - functions/safe/CSS
+ - functions/safe/HTMLAttr
+ - functions/safe/JS
+ - functions/safe/JSStr
+ - functions/safe/URL
+ returnType: template.HTML
+ signatures: [safe.HTML INPUT]
++toc: true
+aliases: [/functions/safehtml]
+---
+
- Given a site-wide [`hugo.toml`][config] with the following `copyright` value:
++## Introduction
+
- {{< code-toggle file=hugo >}}
- copyright = "© 2015 Jane Doe. <a href=\"https://creativecommons.org/licenses/by/4.0/\">Some rights reserved</a>."
- {{< /code-toggle >}}
++{{% include "functions/_common/go-html-template-package.md" %}}
+
- `{{ .Site.Copyright | safeHTML }}` in a template would then output:
++## Usage
+
- ```html
- © 2015 Jane Doe. <a href="https://creativecommons.org/licenses/by/4.0/">Some rights reserved</a>.
++Use the `safe.HTML` function to encapsulate a known safe HTML document fragment. It should not be used for HTML from a third-party, or HTML with unclosed tags or comments.
+
- However, without the `safeHTML` function, html/template assumes `.Site.Copyright` to be unsafe and therefore escapes all HTML tags and renders the whole string as plain text:
++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#HTML
++
++## Example
++
++Without a safe declaration:
++
++```go-html-template
++{{ $html := "<em>emphasized</em>" }}
++{{ $html }}
+```
+
- <p>© 2015 Jane Doe. <a href="https://creativecommons.org/licenses by/4.0/">Some rights reserved</a>.</p>
++Hugo renders the above to:
+
+```html
- [config]: /getting-started/configuration/
++<em>emphasized</em>
+```
+
++To declare the string as safe:
++
++```go-html-template
++{{ $html := "<em>emphasized</em>" }}
++{{ $html | safeHTML }}
++```
++
++Hugo renders the above to:
++
++```html
++<em>emphasized</em>
++```
--- /dev/null
- description: Declares the given key/value pair as a safe HTML attribute.
+---
+title: safe.HTMLAttr
- Given a site configuration that contains this menu entry:
++description: Declares the given key-value pair as a safe HTML attribute.
+categories: []
+keywords: []
+action:
+ aliases: [safeHTMLAttr]
+ related:
+ - functions/safe/CSS
+ - functions/safe/HTML
+ - functions/safe/JS
+ - functions/safe/JSStr
+ - functions/safe/URL
+ returnType: template.HTMLAttr
+ signatures: [safe.HTMLAttr INPUT]
++toc: true
+aliases: [/functions/safehtmlattr]
+---
+
- {{< code-toggle file=hugo >}}
- [[menus.main]]
- name = "IRC"
- url = "irc://irc.freenode.net/#golang"
- {{< /code-toggle >}}
++## Introduction
+
- Attempting to use the `url` value directly in an attribute:
++{{% include "functions/_common/go-html-template-package.md" %}}
+
- {{ range site.Menus.main }}
- <a href="{{ .URL }}">{{ .Name }}</a>
++## Usage
++
++Use the `safe.HTMLAttr` function to encapsulate an HTML attribute from a trusted source.
++
++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#HTMLAttr
++
++## Example
++
++Without a safe declaration:
+
+```go-html-template
- Will produce:
++{{ with .Date }}
++ {{ $humanDate := time.Format "2 Jan 2006" . }}
++ {{ $machineDate := time.Format "2006-01-02T15:04:05-07:00" . }}
++ <time datetime="{{ $machineDate }}">{{ $humanDate }}</time>
+{{ end }}
+```
+
- <a href="#ZgotmplZ">IRC</a>
++Hugo renders the above to:
+
+```html
- `ZgotmplZ` is a special value, inserted by Go's [template/html] package, that indicates that unsafe content reached a CSS or URL context.
-
- To indicate that the HTML attribute is safe:
++<time datetime="2024-05-26T07:19:55+02:00">26 May 2024</time>
+```
+
- {{ range site.Menus.main }}
- <a {{ printf "href=%q" .URL | safeHTMLAttr }}>{{ .Name }}</a>
++To declare the key-value pair as safe:
+
+```go-html-template
- {{% note %}}
- As demonstrated above, you must pass the HTML attribute name _and_ value through the function. Applying `safeHTMLAttr` to the attribute value has no effect.
- {{% /note %}}
++{{ with .Date }}
++ {{ $humanDate := time.Format "2 Jan 2006" . }}
++ {{ $machineDate := time.Format "2006-01-02T15:04:05-07:00" . }}
++ <time {{ printf "datetime=%q" $machineDate | safeHTMLAttr }}>{{ $humanDate }}</time>
+{{ end }}
+```
+
- [template/html]: https://pkg.go.dev/html/template
++Hugo renders the above to:
+
++```html
++<time datetime="2024-05-26T07:19:55+02:00">26 May 2024</time>
++```
--- /dev/null
- In this context, *safe* means the string encapsulates a known safe EcmaScript5 Expression (e.g., `(x + y * z())`).
+---
+title: safe.JS
+description: Declares the given string as a safe JavaScript expression.
+categories: []
+keywords: []
+action:
+ aliases: [safeJS]
+ related:
+ - functions/safe/CSS
+ - functions/safe/HTML
+ - functions/safe/HTMLAttr
+ - functions/safe/JSStr
+ - functions/safe/URL
+ returnType: template.JS
+ signatures: [safe.JS INPUT]
++toc: true
+aliases: [/functions/safejs]
+---
+
- 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.
++## Introduction
+
- Example: Given `hash = "619c16f"` defined in the front matter of your `.md` file:
++{{% include "functions/_common/go-html-template-package.md" %}}
+
- * `<script>var form_{{ .Params.hash | safeJS }};…</script>` → `<script>var form_619c16f;…</script>`
- * `<script>var form_{{ .Params.hash }};…</script>` → `<script>var form_"619c16f";…</script>`
++## Usage
+
++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" }}
++<script>const a = {{ $js }}</script>
++```
++
++Hugo renders the above to:
++
++```html
++<script>const a = "x + y"</script>
++```
++
++To declare the string as safe:
++
++```go-html-template
++{{ $js := "x + y" }}
++<script>const a = {{ $js | safeJS }}</script>
++```
++
++Hugo renders the above to:
++
++```html
++<script>const a = x + y</script>
++```
--- /dev/null
- 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:
+---
+title: safe.JSStr
+description: Declares the given string as a safe JavaScript string.
+categories: []
+keywords: []
+action:
+ aliases: [safeJSStr]
+ related:
+ - functions/safe/CSS
+ - functions/safe/HTML
+ - functions/safe/HTMLAttr
+ - functions/safe/JS
+ - functions/safe/URL
+ returnType: template.JSStr
+ signatures: [safe.JSStr INPUT]
++toc: true
+aliases: [/functions/safejsstr]
+---
+
- Rendered:
++## 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" }}
+<script>
+ const a = "Title: " + {{ $title }};
+</script>
+```
+
- To avoid escaping by Go's [html/template] package:
++Hugo renders the above to:
+
+```html
+<script>
+ const a = "Title: " + "Lilo \u0026 Stitch";
+</script>
+```
+
- Rendered:
++To declare the string as safe:
+
+```go-html-template
+{{ $title := "Lilo & Stitch" }}
+<script>
+ const a = "Title: " + {{ $title | safeJSStr }};
+</script>
+```
+
-
- [html/template]: https://pkg.go.dev/html/template
++Hugo renders the above to:
+
+```html
+<script>
+ const a = "Title: " + "Lilo & Stitch";
+</script>
+```
--- /dev/null
- `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.
+---
+title: safe.URL
+description: Declares the given string as a safe URL or URL substring.
+categories: []
+keywords: []
+action:
+ aliases: [safeURL]
+ related:
+ - functions/safe/CSS
+ - functions/safe/HTML
+ - functions/safe/HTMLAttr
+ - functions/safe/JS
+ - functions/safe/JSStr
+ returnType: template.URL
+ signatures: [safe.URL INPUT]
++toc: true
+aliases: [/functions/safeurl]
+---
+
- 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.
++## Introduction
+
- The following examples use a [site `hugo.toml`][configuration] with the following [menu entry][menus]:
++{{% include "functions/_common/go-html-template-package.md" %}}
+
- {{< code-toggle file=hugo >}}
- [[menus.main]]
- name = "IRC: #golang at freenode"
- url = "irc://irc.freenode.net/#golang"
- {{< /code-toggle >}}
++## Usage
+
- The following is an example of a sidebar partial that may be used in conjunction with the preceding front matter example:
++Use the `safe.URL` function to encapsulate a known safe URL or URL substring. Schemes other than the following are considered unsafe:
+
- {{< code file=layouts/partials/bad-url-sidebar-menu.html >}}
- <!-- This unordered list may be part of a sidebar menu -->
- <ul>
- {{ range .Site.Menus.main }}
- <li><a href="{{ .URL }}">{{ .Name }}</a></li>
- {{ end }}
- </ul>
- {{< /code >}}
++- `http:`
++- `https:`
++- `mailto:`
+
- This partial would produce the following HTML output:
++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 unordered list may be part of a sidebar menu -->
- <ul>
- <li><a href="#ZgotmplZ">IRC: #golang at freenode</a></li>
- </ul>
++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" }}
++<a href="{{ $href }}">IRC</a>
++```
++
++Hugo renders the above to:
+
+```html
- The odd output can be remedied by adding ` | safeURL` to our `.URL` page variable:
++<a href="#ZgotmplZ">IRC</a>
+```
+
- {{< code file=layouts/partials/correct-url-sidebar-menu.html >}}
- <!-- This unordered list may be part of a sidebar menu -->
- <ul>
- <li><a href="{{ .URL | safeURL }}">{{ .Name }}</a></li>
- </ul>
- {{< /code >}}
++{{% 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:
+
- With the `.URL` page variable piped through `safeURL`, we get the desired output:
++```go-html-template
++{{ $href := "irc://irc.freenode.net/#golang" }}
++<a href="{{ $href | safeURL }}">IRC</a>
++```
+
- <ul class="sidebar-menu">
- <li><a href="irc://irc.freenode.net/#golang">IRC: #golang at freenode</a></li>
- </ul>
++Hugo renders the above to:
+
+```html
-
- [configuration]: /getting-started/configuration/
- [menus]: /content-management/menus/
- [RFC 3986]: https://tools.ietf.org/html/rfc3986
++<a href="irc://irc.freenode.net/#golang">IRC</a>
+```
--- /dev/null
- description: Reports whether the given string contains any non-space characters as defined by Unicode’s White Space property.
+---
+title: strings.ContainsNonSpace
- Common white space characters include:
++description: Reports whether the given string contains any non-space characters as defined by Unicode's White Space property.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/strings/Contains
+ - functions/strings/ContainsAny
+ - functions/strings/HasPrefix
+ - functions/strings/HasSuffix
+ - functions/collections/In
+ returnType: bool
+ signatures: [strings.ContainsNonSpace STRING]
+aliases: [/functions/strings.containsnonspace]
+---
+
+{{< new-in 0.111.0 >}}
+
+```go-html-template
+{{ strings.ContainsNonSpace "\n" }} → false
+{{ strings.ContainsNonSpace " " }} → false
+{{ strings.ContainsNonSpace "\n abc" }} → true
+```
+
++Common whitespace characters include:
+
+```text
+'\t', '\n', '\v', '\f', '\r', ' '
+```
+
+See the [Unicode Character Database] for a complete list.
+
+[Unicode Character Database]: https://www.unicode.org/Public/UCD/latest/ucd/PropList.txt
--- /dev/null
- [`strings.RuneCount`]: /functions/strings/runecount
+---
+title: strings.CountRunes
+description: Returns the number of runes in the given string excluding whitespace.
+categories: []
+keywords: []
+action:
+ aliases: [countrunes]
+ related:
+ - functions/go-template/len
+ - functions/strings/Count
+ - functions/strings/CountWords
+ - functions/strings/RuneCount
+ returnType: int
+ signatures: [strings.CountRunes INPUT]
+aliases: [/functions/countrunes]
+---
+
+In contrast with the [`strings.RuneCount`] function, which counts every rune in a string, `strings.CountRunes` excludes whitespace.
+
+```go-html-template
+{{ "Hello, 世界" | strings.CountRunes }} → 8
+```
+
++[`strings.RuneCount`]: /functions/strings/runecount/
--- /dev/null
--- /dev/null
++---
++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 := `
++<p>The product of 6 and 7 is 42.</p>
++<p>The product of 7 and 6 is 42.</p>
++`}}
++
++{{ $got := `
++<p>The product of 6 and 7 is 42.</p>
++<p>The product of 7 and 6 is 13.</p>
++`}}
++
++{{ $diff := strings.Diff "want" $want "got" $got }}
++{{ transform.Highlight $diff "diff" }}
++```
++
++Rendered:
++
++
--- /dev/null
- This markdown:
+---
+title: strings.FindRESubmatch
+description: Returns a slice of all successive matches of the regular expression. Each element is a slice of strings holding the text of the leftmost match of the regular expression and the matches, if any, of its subexpressions.
+categories: []
+keywords: []
+action:
+ aliases: [findRESubmatch]
+ related:
+ - functions/strings/FindRE
+ - functions/strings/Replace
+ - functions/strings/ReplaceRE
+ returnType: '[][]string'
+ signatures: ['strings.FindRESubmatch PATTERN INPUT [LIMIT]']
+aliases: [/functions/findresubmatch]
+---
+
+By default, `findRESubmatch` finds all matches. You can limit the number of matches with an optional LIMIT argument. A return value of nil indicates no match.
+
+{{% include "functions/_common/regular-expressions.md" %}}
+
+## Demonstrative examples
+
+```go-html-template
+{{ findRESubmatch `a(x*)b` "-ab-" }} → [["ab" ""]]
+{{ findRESubmatch `a(x*)b` "-axxb-" }} → [["axxb" "xx"]]
+{{ findRESubmatch `a(x*)b` "-ab-axb-" }} → [["ab" ""] ["axb" "x"]]
+{{ findRESubmatch `a(x*)b` "-axxb-ab-" }} → [["axxb" "xx"] ["ab" ""]]
+{{ findRESubmatch `a(x*)b` "-axxb-ab-" 1 }} → [["axxb" "xx"]]
+```
+
+## Practical example
+
++This Markdown:
+
+```text
+- [Example](https://example.org)
+- [Hugo](https://gohugo.io)
+```
+
+Produces this HTML:
+
+```html
+<ul>
+ <li><a href="https://example.org">Example</a></li>
+ <li><a href="https://gohugo.io">Hugo</a></li>
+</ul>
+```
+
+To match the anchor elements, capturing the link destination and text:
+
+```go-html-template
+{{ $regex := `<a\s*href="(.+?)">(.+?)</a>` }}
+{{ $matches := findRESubmatch $regex .Content }}
+```
+
+Viewed as JSON, the data structure of `$matches` in the code above is:
+
+```json
+[
+ [
+ "<a href=\"https://example.org\"></a>Example</a>",
+ "https://example.org",
+ "Example"
+ ],
+ [
+ "<a href=\"https://gohugo.io\">Hugo</a>",
+ "https://gohugo.io",
+ "Hugo"
+ ]
+]
+```
+
+To render the `href` attributes:
+
+```go-html-template
+{{ range $matches }}
+ {{ index . 1 }}
+{{ end }}
+```
+
+Result:
+
+```text
+https://example.org
+https://gohugo.io
+```
+
+{{% note %}}
+You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin.
+{{% /note %}}
--- /dev/null
- [`strings.CountRunes`]: /functions/strings/countrunes
+---
+title: strings.RuneCount
+description: Returns the number of runes in the given string.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/go-template/len
+ - functions/strings/Count
+ - functions/strings/CountRunes
+ - functions/strings/CountWords
+ returnType: int
+ signatures: [strings.RuneCount INPUT]
+aliases: [/functions/strings.runecount]
+---
+
+In contrast with the [`strings.CountRunes`] function, which excludes whitespace, `strings.RuneCount` counts every rune in a string.
+
+```go-html-template
+{{ "Hello, 世界" | strings.RuneCount }} → 9
+```
+
++[`strings.CountRunes`]: /functions/strings/countrunes/
--- /dev/null
- description: Creates a slice of a half-open range, including start and end indices.
+---
+title: strings.SliceString
- related: []
++description: Returns a substring of the given string, beginning with the start position and ending before the end position.
+categories: []
+keywords: []
+action:
+ aliases: [slicestr]
- signatures: ['strings.SliceString STRING START [END]']
++ related:
++ - functions/strings/Substr
+ returnType: string
- 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.
++ signatures: ['strings.SliceString STRING [START] [END]']
+aliases: [/functions/slicestr]
+---
+
- {{ slicestr "BatMan" 3 }}` → Man
- {{ slicestr "BatMan" 0 3 }}` → Bat
++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" }} → 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/
--- /dev/null
- [`collections.Delimit`]: /functions/collections/delimit
+---
+title: strings.Split
+description: Returns a slice of strings by splitting the given string by a delimiter.
+categories: []
+keywords: []
+action:
+ aliases: [split]
+ related:
+ - functions/collections/Delimit
+ returnType: string
+ signatures: [strings.Split STRING DELIM]
+aliases: [/functions/split]
+---
+
+Examples:
+
+```go-html-template
+{{ split "tag1,tag2,tag3" "," }} → ["tag1", "tag2", "tag3"]
+{{ split "abc" "" }} → ["a", "b", "c"]
+```
+
+{{% 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/
+{{% /note %}}
--- /dev/null
- description: Extracts parts of a string from a specified character's position and returns the specified number of characters.
+---
+title: strings.Substr
- related: []
++description: Returns a substring of the given string, beginning with the start position and ending after the given length.
+categories: []
+keywords: []
+action:
+ aliases: [substr]
- signatures: ['strings.Substr STRING START [LENGTH]']
++ related:
++ - functions/strings/SliceString
+ returnType: string
- 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.
++ signatures: ['strings.Substr STRING [START] [LENGTH]']
+aliases: [/functions/substr]
+---
+
- 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.
++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.
+
++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
+{{ substr "abcdef" 1 }} → bcdef
+
+{{ substr "abcdef" 0 1 }} → a
+{{ substr "abcdef" 1 1 }} → b
+
+{{ substr "abcdef" 0 -1 }} → abcde
+{{ substr "abcdef" 1 -1 }} → bcde
+
+{{ substr "abcdef" -1 }} → f
+{{ substr "abcdef" -2 }} → ef
+
+{{ substr "abcdef" -1 1 }} → f
+{{ substr "abcdef" -2 1 }} → e
+
+{{ substr "abcdef" -3 -1 }} → de
+{{ substr "abcdef" -3 -2 }} → d
+```
--- /dev/null
- For example, with this markdown:
+---
+title: strings.Trim
+description: Returns the given string, removing leading and trailing characters specified in the cutset.
+categories: []
+keywords: []
+action:
+ aliases: [trim]
+ related:
+ - functions/strings/Chomp
+ - functions/strings/TrimLeft
+ - functions/strings/TrimPrefix
+ - functions/strings/TrimRight
+ - functions/strings/TrimSuffix
+ returnType: string
+ signatures: [strings.Trim INPUT CUTSET]
+aliases: [/functions/trim]
+---
+
+```go-html-template
+{{ trim "++foo--" "+-" }} → foo
+```
+
+To remove leading and trailing newline characters and carriage returns:
+
+```go-html-template
+{{ trim "\nfoo\n" "\n\r" }} → foo
+{{ trim "\n\nfoo\n\n" "\n\r" }} → foo
+
+{{ trim "\r\nfoo\r\n" "\n\r" }} → foo
+{{ trim "\r\n\r\nfoo\r\n\r\n" "\n\r" }} → foo
+```
+
+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:
+
+```text
+{{</* my-shortcode */>}}
+Able was I ere I saw Elba.
+{{</* /my-shortcode */>}}
+```
+
+The value of `.Inner` in the shortcode template is:
+
+```text
+\nAble was I ere I saw Elba.\n
+```
+
+If authored on a Windows system the value of `.Inner` might, depending on the editor configuration, be:
+
+```text
+\r\nAble was I ere I saw Elba.\r\n
+```
+
+This construct is common in shortcode templates:
+
+```go-html-template
+{{ trim .Inner "\n\r" }}
+```
--- /dev/null
- [`safeHTML`]: /functions/safe/html
+---
+title: strings.Truncate
+description: Returns the given string, truncating it to a maximum length without cutting words or leaving unclosed HTML tags.
+categories: []
+keywords: []
+action:
+ aliases: [truncate]
+ related: []
+ returnType: template.HTML
+ signatures: ['strings.Truncate SIZE [ELLIPSIS] INPUT']
+aliases: [/functions/truncate]
+---
+
+Since Go templates are HTML-aware, `truncate` will intelligently handle normal strings vs HTML strings:
+
+```go-html-template
+{{ "<em>Keep my HTML</em>" | safeHTML | truncate 10 }} → <em>Keep my …</em>
+```
+
+{{% 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/
+{{% /note %}}
--- /dev/null
- [methods]: /methods/duration
+---
+title: time.Duration
+description: Returns a time.Duration value using the given time unit and number.
+categories: []
+keywords: []
+action:
+ aliases: [duration]
+ related:
+ - functions/time/AsTime
+ - functions/time/Format
+ - functions/time/Now
+ - functions/time/ParseDuration
+ returnType: time.Duration
+ signatures: [time.Duration TIME_UNIT NUMBER]
+aliases: [/functions/duration]
+---
+
+The `time.Duration` function returns a [`time.Duration`] value that you can use with any of the `Duration` [methods].
+
+This template:
+
+```go-html-template
+{{ $duration := time.Duration "hour" 24 }}
+{{ printf "There are %.0f seconds in one day." $duration.Seconds }}
+```
+
+Is rendered to:
+
+```text
+There are 86400 seconds in one day.
+```
+
+The time unit must be one of the following:
+
+
+Duration|Valid time units
+:--|:--
+hours|`hour`, `h`
+minutes|`minute`, `m`
+seconds|`second`, `s`
+milliseconds|`millisecond`, `ms`
+microseconds|`microsecond`, `us`, `µs`
+nanoseconds|`nanosecond`, `ns`
+
+[`time.Duration`]: https://pkg.go.dev/time#Duration
++[methods]: /methods/duration/
--- /dev/null
- [`time.Format`]: /functions/time/format
+---
+title: time.Now
+description: Returns the current local time.
+categories: []
+keywords: []
+action:
+ aliases: [now]
+ related:
+ - functions/time/AsTime
+ - functions/time/Duration
+ - functions/time/Format
+ - functions/time/ParseDuration
+ returnType: time.Time
+ signatures: [time.Now]
+aliases: [/functions/now]
+---
+
+For example, when building a site on October 15, 2023 in the America/Los_Angeles time zone:
+
+```go-html-template
+{{ time.Now }}
+```
+
+This produces a `time.Time` value, with a string representation such as:
+
+```text
+2023-10-15 12:59:28.337140706 -0700 PDT m=+0.041752605
+```
+
+To format and [localize] the value, pass it through the [`time.Format`] function:
+
+```go-html-template
+{{ time.Now | time.Format "Jan 2006" }} → Oct 2023
+```
+
+The `time.Now` function returns a `time.Time` value, so you can chain any of the [time methods] to the resulting value. For example:
+
+
+```go-html-template
+{{ time.Now.Year }} → 2023 (int)
+{{ time.Now.Weekday.String }} → Sunday
+{{ time.Now.Month.String }} → October
+{{ time.Now.Unix }} → 1697400955 (int64)
+```
+
++[`time.Format`]: /functions/time/format/
+[localize]: /getting-started/glossary/#localization
+[time methods]: /methods/time/
--- /dev/null
- [methods]: /methods/duration
+---
+title: time.ParseDuration
+description: Returns a time.Duration value by parsing the given duration string.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/time/AsTime
+ - functions/time/Duration
+ - functions/time/Format
+ - functions/time/Now
+ returnType: time.Duration
+ signatures: [time.ParseDuration DURATION]
+aliases: [/functions/time.parseduration]
+---
+
+The `time.ParseDuration` function returns a time.Duration value that you can use with any of the `Duration` [methods].
+
+
+A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as `300ms`, `-1.5h` or `2h45m`. Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`.
+
+This template:
+
+```go-html-template
+{{ $duration := time.ParseDuration "24h" }}
+{{ printf "There are %.0f seconds in one day." $duration.Seconds }}
+```
+
+Is rendered to:
+
+```text
+There are 86400 seconds in one day.
+```
+
+[`time.Duration`]: https://pkg.go.dev/time#Duration
++[methods]: /methods/duration/
--- /dev/null
- Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+---
+cascade:
+ _build:
+ list: never
+ publishResources: false
+ render: never
+---
+
+<!--
++Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+
+Include the rendered content using the "include" shortcode.
+-->
--- /dev/null
- [`safehtml`]: /functions/safe/html
+---
+title: transform.HTMLUnescape
+description: Returns the given string, replacing each HTML entity with its corresponding character.
+categories: []
+keywords: []
+action:
+ aliases: [htmlUnescape]
+ related:
+ - functions/transform/HTMLEscape
+ returnType: string
+ signatures: [transform.HTMLUnescape INPUT]
+aliases: [/functions/htmlunescape]
+---
+
+The `transform.HTMLUnescape` function replaces [HTML entities] with their corresponding characters.
+
+```go-html-template
+{{ htmlUnescape "Lilo & Stitch" }} → Lilo & Stitch
+{{ htmlUnescape "7 > 6" }} → 7 > 6
+```
+
+In most contexts Go's [html/template] package will escape special characters. To bypass this behavior, pass the unescaped string through the [`safeHTML`] function.
+
+```go-html-template
+{{ htmlUnescape "Lilo & Stitch" | safeHTML }}
+```
+
++[`safehtml`]: /functions/safe/html/
+[html entities]: https://developer.mozilla.org/en-us/docs/glossary/entity
+[html/template]: https://pkg.go.dev/html/template
--- /dev/null
- description: Renders markdown to HTML.
+---
+title: transform.Markdownify
- 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.
++description: Renders Markdown to HTML.
+categories: []
+keywords: []
+action:
+ aliases: [markdownify]
+ related:
+ - methods/page/RenderString
+ - methods/page/RenderShortcodes
+ returnType: template.HTML
+ signatures: [transform.Markdownify INPUT]
+aliases: [/functions/markdownify]
+---
+
+```go-html-template
+<h2>{{ .Title | markdownify }}</h2>
+```
+
+If the resulting HTML is a single paragraph, Hugo removes the wrapping `p` tags to produce inline HTML as required per the example above.
+
+To keep the wrapping `p` tags for a single paragraph, use the [`RenderString`] method on the `Page` object, setting the `display` option to `block`.
+
+[`RenderString`]: /methods/page/renderstring/
+
+{{% note %}}
- [markdown render hooks]: /templates/render-hooks/
++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]: /render-hooks/
+[#9692]: https://github.com/gohugoio/hugo/issues/9692
+{{% /note %}}
--- /dev/null
- {{ $data := "" }}
+---
+title: transform.Unmarshal
+description: Parses serialized data and returns a map or an array. Supports CSV, JSON, TOML, YAML, and XML.
+categories: []
+keywords: []
+action:
+ aliases: [unmarshal]
+ related:
+ - functions/transform/Remarshal
+ - functions/resources/Get
+ - functions/resources/GetRemote
+ - functions/encoding/Jsonify
+ returnType: any
+ signatures: ['transform.Unmarshal [OPTIONS] INPUT']
+toc: true
+aliases: [/functions/transform.unmarshal]
+---
+
+The input can be a string or a [resource].
+
+## Unmarshal a string
+
+```go-html-template
+{{ $string := `
+title: Les Misérables
+author: Victor Hugo
+`}}
+
+{{ $book := unmarshal $string }}
+{{ $book.title }} → Les Misérables
+{{ $book.author }} → Victor Hugo
+```
+
+## Unmarshal a resource
+
+Use the `transform.Unmarshal` function with global, page, and remote resources.
+
+### Global resource
+
+A global resource is a file within the assets directory, or within any directory mounted to the assets directory.
+
+```text
+assets/
+└── data/
+ └── books.json
+```
+
+```go-html-template
- {{ with unmarshal . }}
++{{ $data := dict }}
+{{ $path := "data/books.json" }}
+{{ with resources.Get $path }}
- {{ $data := "" }}
++ {{ with . | transform.Unmarshal }}
+ {{ $data = . }}
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get global resource %q" $path }}
+{{ end }}
+
+{{ range where $data "author" "Victor Hugo" }}
+ {{ .title }} → Les Misérables
+{{ end }}
+```
+
+### Page resource
+
+A page resource is a file within a [page bundle].
+
+```text
+content/
+├── post/
+│ └── book-reviews/
+│ ├── books.json
+│ └── index.md
+└── _index.md
+```
+
+```go-html-template
- {{ with unmarshal . }}
++{{ $data := dict }}
+{{ $path := "books.json" }}
+{{ with .Resources.Get $path }}
- {{ $data := "" }}
++ {{ with . | transform.Unmarshal }}
+ {{ $data = . }}
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get page resource %q" $path }}
+{{ end }}
+
+{{ range where $data "author" "Victor Hugo" }}
+ {{ .title }} → Les Misérables
+{{ end }}
+```
+
+### Remote resource
+
+A remote resource is a file on a remote server, accessible via HTTP or HTTPS.
+
+```go-html-template
- [resource]: /getting-started/glossary/#resource
- [page bundle]: /content-management/page-bundles
++{{ $data := dict }}
+{{ $url := "https://example.org/books.json" }}
+{{ with resources.GetRemote $url }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else }}
+ {{ $data = . | transform.Unmarshal }}
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+{{ end }}
+
+{{ range where $data "author" "Victor Hugo" }}
+ {{ .title }} → Les Misérables
+{{ end }}
+```
+
- {{ $data := "" }}
++{{% 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
+
+When unmarshaling a CSV file, provide an optional map of options.
+
+delimiter
+: (`string`) The delimiter used, default is `,`.
+
+comment
+: (`string`) The comment character used in the CSV. If set, lines beginning with the comment character without preceding whitespace are ignored.
+
+lazyQuotes {{< new-in 0.122.0 >}}
+: (`bool`) If true, a quote may appear in an unquoted field and a non-doubled quote may appear in a quoted field. Default is `false`.
+
+```go-html-template
+{{ $csv := "a;b;c" | transform.Unmarshal (dict "delimiter" ";") }}
+```
+
+## Working with XML
+
+When unmarshaling an XML file, do not include the root node when accessing data. For example, after unmarshaling the RSS feed below, access the feed title with `$data.channel.title`.
+
+```xml
+<?xml version="1.0" encoding="utf-8" standalone="yes"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+ <channel>
+ <title>Books on Example Site</title>
+ <link>https://example.org/books/</link>
+ <description>Recent content in Books on Example Site</description>
+ <language>en-US</language>
+ <atom:link href="https://example.org/books/index.xml" rel="self" type="application/rss+xml" />
+ <item>
+ <title>The Hunchback of Notre Dame</title>
+ <description>Written by Victor Hugo</description>
+ <link>https://example.org/books/the-hunchback-of-notre-dame/</link>
+ <pubDate>Mon, 09 Oct 2023 09:27:12 -0700</pubDate>
+ <guid>https://example.org/books/the-hunchback-of-notre-dame/</guid>
+ </item>
+ <item>
+ <title>Les Misérables</title>
+ <description>Written by Victor Hugo</description>
+ <link>https://example.org/books/les-miserables/</link>
+ <pubDate>Mon, 09 Oct 2023 09:27:11 -0700</pubDate>
+ <guid>https://example.org/books/les-miserables/</guid>
+ </item>
+ </channel>
+</rss>
+```
+
+Get the remote data:
+
+```go-html-template
- <pre>{{ jsonify (dict "indent" " ") $data }}</pre>
++{{ $data := dict }}
+{{ $url := "https://example.org/books/index.xml" }}
+{{ with resources.GetRemote $url }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else }}
+ {{ $data = . | transform.Unmarshal }}
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+{{ end }}
+```
+
+Inspect the data structure:
+
+```go-html-template
- <pre>{{ jsonify (dict "indent" " ") $data }}</pre>
++<pre>{{ debug.Dump $data }}</pre>
+```
+
+List the book titles:
+
+```go-html-template
+{{ with $data.channel.item }}
+ <ul>
+ {{ range . }}
+ <li>{{ .title }}</li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+Hugo renders this to:
+
+```html
+<ul>
+ <li>The Hunchback of Notre Dame</li>
+ <li>Les Misérables</li>
+</ul>
+```
+
+### XML attributes and namespaces
+
+Let's add a `lang` attribute to the `title` nodes of our RSS feed, and a namespaced node for the ISBN number:
+
+```xml
+<?xml version="1.0" encoding="utf-8" standalone="yes"?>
+<rss version="2.0"
+ xmlns:atom="http://www.w3.org/2005/Atom"
+ xmlns:isbn="http://schemas.isbn.org/ns/1999/basic.dtd"
+>
+ <channel>
+ <title>Books on Example Site</title>
+ <link>https://example.org/books/</link>
+ <description>Recent content in Books on Example Site</description>
+ <language>en-US</language>
+ <atom:link href="https://example.org/books/index.xml" rel="self" type="application/rss+xml" />
+ <item>
+ <title lang="fr">The Hunchback of Notre Dame</title>
+ <description>Written by Victor Hugo</description>
+ <isbn:number>9780140443530</isbn:number>
+ <link>https://example.org/books/the-hunchback-of-notre-dame/</link>
+ <pubDate>Mon, 09 Oct 2023 09:27:12 -0700</pubDate>
+ <guid>https://example.org/books/the-hunchback-of-notre-dame/</guid>
+ </item>
+ <item>
+ <title lang="en">Les Misérables</title>
+ <description>Written by Victor Hugo</description>
+ <isbn:number>9780451419439</isbn:number>
+ <link>https://example.org/books/les-miserables/</link>
+ <pubDate>Mon, 09 Oct 2023 09:27:11 -0700</pubDate>
+ <guid>https://example.org/books/les-miserables/</guid>
+ </item>
+ </channel>
+</rss>
+```
+
+After retrieving the remote data, inspect the data structure:
+
+```go-html-template
- [`index`]: /functions/collections/indexfunction
++<pre>{{ debug.Dump $data }}</pre>
+```
+
+Each item node looks like this:
+
+```json
+{
+ "description": "Written by Victor Hugo",
+ "guid": "https://example.org/books/the-hunchback-of-notre-dame/",
+ "link": "https://example.org/books/the-hunchback-of-notre-dame/",
+ "number": "9780140443530",
+ "pubDate": "Mon, 09 Oct 2023 09:27:12 -0700",
+ "title": {
+ "#text": "The Hunchback of Notre Dame",
+ "-lang": "fr"
+ }
+}
+```
+
+The title keys do not begin with an underscore or a letter---they are not valid [identifiers]. Use the [`index`] function to access the values:
+
+```go-html-template
+{{ with $data.channel.item }}
+ <ul>
+ {{ range . }}
+ {{ $title := index .title "#text" }}
+ {{ $lang := index .title "-lang" }}
+ {{ $ISBN := .number }}
+ <li>{{ $title }} ({{ $lang }}) {{ $ISBN }}</li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+Hugo renders this to:
+
+```html
+<ul>
+ <li>The Hunchback of Notre Dame (fr) 9780140443530</li>
+ <li>Les Misérables (en) 9780451419439</li>
+</ul>
+```
+
++[`index`]: /functions/collections/indexfunction/
+[identifiers]: https://go.dev/ref/spec#Identifiers
++[resource]: /getting-started/glossary/#resource
++[page bundle]: /content-management/page-bundles/
--- /dev/null
- 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.
+---
+title: urls.AbsLangURL
+description: Returns an absolute URL with a language prefix, if any.
+categories: []
+keywords: []
+action:
+ aliases: [absLangURL]
+ related:
+ - functions/urls/AbsURL
+ - functions/urls/RelLangURL
+ - functions/urls/RelURL
+ returnType: string
+ signatures: [urls.AbsLangURL INPUT]
+aliases: [/functions/abslangurl]
+---
+
+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 language prefix, if any
+
- If the input does not begin with a slash, the resulting URL will be correct regardless of the `baseURL`.
++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
+
- {{ absLangURL "" }} → https://example.org/en/
- {{ absLangURL "articles" }} → https://example.org/en/articles
- {{ absLangURL "style.css" }} → https://example.org/en/style.css
++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/docs/en/
- {{ absLangURL "articles" }} → https://example.org/docs/en/articles
- {{ absLangURL "style.css" }} → https://example.org/docs/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
- 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`.
++{{ 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
+
- {{ absLangURL "/" }} → https://example.org/en/
- {{ absLangURL "/articles" }} → https://example.org/en/articles
- {{ absLangURL "/style.css" }} → https://example.org/en/style.css
++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
-
- {{% 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 "/" }} → https://example.org/en/
++{{ absLangURL "/articles" }} → https://example.org/en/articles
++{{ absLangURL "/style.css" }} → https://example.org/en/style.css
+```
--- /dev/null
- With multilingual configurations, use the [`absLangURL`] function instead. The URL returned by this function depends on:
+---
+title: urls.AbsURL
+description: Returns an absolute URL.
+categories: []
+keywords: []
+action:
+ aliases: [absURL]
+ related:
+ - functions/urls/AbsLangURL
+ - functions/urls/RelLangURL
+ - functions/urls/RelURL
+ returnType: string
+ signatures: [urls.AbsURL INPUT]
+aliases: [/functions/absurl]
+---
+
- If the input does not begin with a slash, the resulting URL will be correct regardless of the `baseURL`.
++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
+
- {{ absURL "" }} → https://example.org/
- {{ absURL "articles" }} → https://example.org/articles
- {{ absURL "style.css" }} → https://example.org/style.css
++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/docs/
- {{ absURL "articles" }} → https://example.org/docs/articles
- {{ absURL "style.css" }} → https://example.org/docs/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
- 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`.
++{{ 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
+
- {{ absURL "/" }} → https://example.org/
- {{ absURL "/articles" }} → https://example.org/articles
- {{ absURL "/style.css" }} → https://example.org/style.css
++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
- {{% 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/
++{{ absURL "/" }} → https://example.org/
++{{ absURL "/articles" }} → https://example.org/articles
++{{ absURL "/style.css" }} → https://example.org/style.css
+```
+
++[`urls.AbsLangURL`]: /functions/urls/abslangurl/
--- /dev/null
- With the default markdown renderer, Goldmark, the sanitizing logic is controlled by your site configuration:
+---
+title: urls.Anchorize
+description: Returns the given string, sanitized for usage in an HTML id attribute.
+categories: []
+keywords: []
+action:
+ aliases: [anchorize]
+ related:
+ - functions/urls/URLize
+ returnType: string
+ signatures: [urls.Anchorize INPUT]
+aliases: [/functions/anchorize]
+---
+
+{{% include "/functions/urls/_common/anchorize-vs-urlize.md" %}}
+
+## Sanitizing logic
+
- This controls the behavior of the `anchorize` function and the generation of heading IDs when rendering markdown to HTML.
++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.
+
+Set `autoHeadingIDType` to one of:
+
+github
+: Compatible with GitHub. This is the default, and strongly recommended.
+
+github-ascii
+: Similar to the "github" setting, but removes non-ASCII characters.
+
+blackfriday
+: Provided for backwards compatibility with Hugo v0.59.1 and earlier. This option will be removed in a future release.
--- /dev/null
- [`path.Join`]: /functions/path/join
+---
+title: urls.JoinPath
+description: Joins the provided elements into a URL string and cleans the result of any ./ or ../ elements. If the argument list is empty, JoinPath returns an empty string.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/path/Join
+ returnType: string
+ signatures: [urls.JoinPath ELEMENT...]
+aliases: [/functions/urls.joinpath]
+---
+
+{{< new-in 0.112.0 >}}
+
+```go-html-template
+{{ urls.JoinPath }} → "" (empty string)
+{{ urls.JoinPath "" }} → /
+{{ urls.JoinPath "a" }} → a
+{{ urls.JoinPath "a" "b" }} → a/b
+{{ urls.JoinPath "/a" "b" }} → /a/b
+{{ urls.JoinPath "https://example.org" "b" }} → https://example.org/b
+
+{{ urls.JoinPath (slice "a" "b") }} → a/b
+```
+
+Unlike the [`path.Join`] function, `urls.JoinPath` retains consecutive leading slashes.
+
++[`path.Join`]: /functions/path/join/
--- /dev/null
+---
+title: urls.Parse
+description: Parses a URL into a URL structure.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related: []
+ returnType: url.URL
+ signatures: [urls.Parse URL]
+aliases: [/functions/urls.parse]
+---
+
+The `urls.Parse` function parses a URL into a [URL structure](https://godoc.org/net/url#URL). The URL may be relative (a path, without a host) or absolute (starting with a [scheme]). Hugo throws an error when parsing an invalid URL.
+
+[scheme]: https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml#uri-schemes-1
+
+```go-html-template
+{{ $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
+{{ $u.Hostname }} → example.org
+{{ $u.RequestURI }} → /foo?a=6&b=7
+{{ $u.Path }} → /foo
+{{ $u.Query }} → map[a:[6] b:[7]]
+{{ $u.Query.a }} → [6]
+{{ $u.Query.Get "a" }} → 6
+{{ $u.Query.Has "b" }} → true
+{{ $u.Fragment }} → bar
+```
--- /dev/null
- - The `baseURL` in site configuration
+---
+title: urls.RelLangURL
+description: Returns a relative URL with a language prefix, if any.
+categories: []
+keywords: []
+action:
+ aliases: [relLangURL]
+ related:
+ - functions/urls/AbsLangURL
+ - functions/urls/AbsURL
+ - functions/urls/RelURL
+ returnType: string
+ signatures: [urls.RelLangURL INPUT]
+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
- 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.
++- The `baseURL` in your site configuration
+- The language prefix, if any
+
- If the input does not begin with a slash, the resulting URL will be correct regardless of the `baseURL`.
++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
+
- {{ relLangURL "" }} → /en/
- {{ relLangURL "articles" }} → /en/articles
- {{ relLangURL "style.css" }} → /en/style.css
++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 "" }} → /docs/en/
- {{ relLangURL "articles" }} → /docs/en/articles
- {{ relLangURL "style.css" }} → /docs/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
- 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`.
++{{ 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
+
- {{ relLangURL "/" }} → /en/
- {{ relLangURL "/articles" }} → /en/articles
- {{ relLangURL "/style.css" }} → /en/style.css
++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
-
- {{% 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 "/" }} → /en/
++{{ relLangURL "/articles" }} → /en/articles
++{{ relLangURL "/style.css" }} → /en/style.css
+```
--- /dev/null
- With multilingual configurations, use the [`relLangURL`] function instead. The URL returned by this function depends on:
+---
+title: urls.RelURL
+description: Returns a relative URL.
+categories: []
+keywords: []
+action:
+ aliases: [relURL]
+ related:
+ - functions/urls/AbsLangURL
+ - functions/urls/AbsURL
+ - functions/urls/RelLangURL
+ returnType: string
+ signatures: [urls.RelURL INPUT]
+aliases: [/functions/relurl]
+---
+
- - The `baseURL` in site configuration
++With multilingual configurations, use the [`urls.RelLangURL`] function instead. The URL returned by this function depends on:
+
+- Whether the input begins with a slash
- If the input does not begin with a slash, the resulting URL will be correct regardless of the `baseURL`.
++- The `baseURL` in your site configuration
+
+### Input does not begin with a slash
+
- {{ relURL "" }} → /
- {{ relURL "articles" }} → /articles
- {{ relURL "style.css" }} → /style.css
++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 "" }} → /docs/
- {{ relURL "articles" }} → /docs/articles
- {{ relURL "style.css" }} → /docs/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
- 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`.
++{{ 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
+
- {{ relURL "/" }} → /
- {{ relURL "/articles" }} → /articles
- {{ relURL "style.css" }} → /style.css
++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
- {{% 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/
++{{ relURL "/" }} → /
++{{ relURL "/articles" }} → /articles
++{{ relURL "/style.css" }} → /style.css
+```
+
++[`urls.RelLangURL`]: /functions/urls/rellangurl/
--- /dev/null
- Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+---
+cascade:
+ _build:
+ list: never
+ publishResources: false
+ render: never
+---
+
+<!--
++Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+
+Include the rendered content using the "include" shortcode.
+-->
--- /dev/null
- [`anchorize`]: /functions/urls/anchorize
- [`urlize`]: /functions/urls/urlize
+---
+# Do not remove front matter.
+---
+
+The [`anchorize`] and [`urlize`] functions are similar:
+
++[`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
+
+For example:
+
+```go-html-template
+{{ $s := "A B C" }}
+{{ $s | anchorize }} → a-b-c
+{{ $s | urlize }} → a-b-c
+
+{{ $s := "a b c" }}
+{{ $s | anchorize }} → a-b---c
+{{ $s | urlize }} → a-b-c
+
+{{ $s := "< a, b, & c >" }}
+{{ $s | anchorize }} → -a-b--c-
+{{ $s | urlize }} → a-b-c
+
+{{ $s := "main.go" }}
+{{ $s | anchorize }} → maingo
+{{ $s | urlize }} → main.go
+
+{{ $s := "Hugö" }}
+{{ $s | anchorize }} → hugö
+{{ $s | urlize }} → hug%C3%B6
+```
--- /dev/null
- linkTitle: Overview
+---
+title: Getting started
- identifier: getting-started-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-in-this-section
+ parent: getting-started
+ weight: 10
+weight: 10
+aliases: [/overview/introduction/]
+---
+
+If this is your first time using Hugo and you've [already installed Hugo on your machine][installed], we recommend the [quick start]. You can also use [external learning resources] to learn Hugo.
+
+[installed]: /installation/
+[quick start]: /getting-started/quick-start/
+[external learning resources]: /getting-started/external-learning-resources/
--- /dev/null
- keywords: [configuration,highlighting]
+---
+title: Configure markup
+description: Configure rendering of markup to HTML.
+categories: [getting started,fundamentals]
- By default, Hugo uses [Goldmark] to render markdown to HTML.
++keywords: [markup,markdown,goldmark,asciidoc,asciidoctor,highlighting]
+menu:
+ docs:
+ parent: getting-started
+ weight: 50
+weight: 50
+slug: configuration-markup
+toc: true
+---
+
+## Default handler
+
- 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.
++Hugo uses [Goldmark] to render Markdown to HTML.
+
+{{< code-toggle file=hugo >}}
+[markup]
+defaultMarkdownHandler = 'goldmark'
+{{< /code-toggle >}}
+
- To use a different renderer for markdown files, specify one of `asciidocext`, `org`, `pandoc`, or `rst` in your site configuration.
++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 Asciidoc, Pandoc, or reStructuredText you must install the relevant renderer and update your [security policy].
++To use a different renderer for Markdown files, specify one of `asciidocext`, `org`, `pandoc`, or `rst` in your site configuration.
+
+defaultMarkdownHandler|Description
+:--|:--
+`asciidocext`|[AsciiDoc]
+`goldmark`|[Goldmark]
+`org`|[Emacs Org Mode]
+`pandoc`|[Pandoc]
+`rst`|[reStructuredText]
+
- 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).
++To use AsciiDoc, Pandoc, or reStructuredText you must install the relevant renderer and update your [security policy].
+
+{{% note %}}
- [content format]: /content-management/formats/#list-of-content-formats
++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/
- [security policy]: /about/security-model/#security-policy
++[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
- This is the default configuration for the Goldmark markdown renderer:
++[security policy]: /about/security/#security-policy
+
+## Goldmark
+
- For details on the extensions, refer to the [Goldmark documentation](https://github.com/yuin/goldmark/#built-in-extensions).
++This is the default configuration for the Goldmark Markdown renderer:
+
+{{< code-toggle config=markup.goldmark />}}
+
- Some settings explained:
++### 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++`|`<ins>foo</ins>`
++Mark text|`==bar==`|`<mark>bar</mark>`
++Subscript|`H~2~O`|`H<sub>2</sub>O`
++Superscript|`1^st^`|`1<sup>st</sup>`
++
++[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 >}}
+
- hardWraps
- : By default, Goldmark ignores newlines within a paragraph. Set to `true` to render newlines as `<br>` elements.
++Enable the passthrough extension to include mathematical equations and expressions in Markdown using LaTeX or TeX typesetting syntax. See [mathematics in Markdown] for details.
+
- 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.
++[mathematics in Markdown]: content-management/mathematics/
+
- typographer
- : The typographer extension replaces certain character combinations with HTML entities as specified below:
++#### Typographer extension
+
- 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.
++The Typographer extension replaces certain character combinations with HTML entities as specified below:
+
+Markdown|Replaced by|Description
+:--|:--|:--
+`...`|`…`|horizontal ellipsis
+`'`|`’`|apostrophe
+`--`|`–`|en dash
+`---`|`—`|em dash
+`«`|`«`|left angle quote
+`“`|`“`|left double quote
+`‘`|`‘`|left single quote
+`»`|`»`|right angle quote
+`”`|`”`|right double quote
+`’`|`’`|right single quote
+
- Hugo supports adding attributes (e.g. CSS classes) to Markdown blocks, e.g. tables, lists, paragraphs etc.
++### Goldmark settings explained
+
- A blockquote with a CSS class:
++Most of the Goldmark settings above are self-explanatory, but some require explanation.
+
- ```md
- > foo
- > bar
- {.myclass}
- ```
++###### duplicateResourceFiles
+
- 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}
- ```
++{{< new-in 0.123.0 >}}
+
- 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.:
++(`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`.
+
- ````txt
- ```go {.myclass linenos=table,hl_lines=[8,"15-17"],linenostart=199}
- // ... code
- ```
- ````
++[multilingual page resources]: /content-management/page-resources/#multilingual
+
- 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.
++{{% 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
+
- ## Asciidoc
++This is also the strategy used by the [anchorize](/functions/urls/anchorize) template function. Default is `github`.
+
- This is the default configuration for the AsciiDoc markdown renderer:
++###### parser.attribute.block
+
- attributes
- : (`map`) Variables to be referenced in your AsciiDoc file. This is a list of variable name/value maps. See Asciidoctor’s [attributes].
++(`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 />}}
+
- backend:
- : (`string`) Don’t change this unless you know what you are doing.
++### 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
+
- extensions
- : (`[]string`) Possible extensions are `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`, `asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, and `asciidoctor-question`.
++###### backend
++
++(`string`) The backend output file format. Default is `html5`.
+
- failureLevel
- : (`string`) The minimum logging level that triggers a non-zero exit code (failure).
++###### extensions
+
- 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.
++(`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`.
+
- 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.
++{{% 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 %}}
+
- safeMode
- : (`string`) Safe mode level `unsafe`, `safe`, `server`, or `secure`. Don’t change this unless you know what you are doing.
++###### failureLevel
+
- sectionNumbers
- : (`bool`) Auto-number section titles.
++(`string`) The minimum logging level that triggers a non-zero exit code (failure). Default is `fatal`.
+
- trace
- : (`bool`) Include backtrace information on errors.
++###### noHeaderOrFooter
+
- verbose
- : (`bool`) Verbosely print processing information and configuration file checks to stderr.
++(`bool`) If `true`, outputs an embeddable document, which excludes the header, the footer, and everything outside the body of the document. Default is `true`.
+
- 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`.
++###### preserveTOC
+
- [asciidoctor-diagram]: https://asciidoctor.org/docs/asciidoctor-diagram/
- [include]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files
++(`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`.
+
- 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.
++[`TableOfContents`]: /methods/page/tableofcontents/
++
++###### safeMode
+
- Example of how to set extensions and attributes:
++(`string`) The safe mode level, one of `unsafe`, `safe`, `server`, or `secure`. Default is `unsafe`.
+
- ```yml
++###### sectionNumbers
+
- ```
++(`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"
- 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
++{{< /code-toggle >}}
++
++### AsciiDoc troubleshooting
+
- These settings only works for the Goldmark renderer:
++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 -] ...
+```
+
+## Highlight
+
+This is the default `highlight` configuration. Note that some of these settings can be set per code block, see [Syntax Highlighting](/content-management/syntax-highlighting/).
+
+{{< code-toggle config=markup.highlight />}}
+
+For `style`, see these galleries:
+
+* [Short snippets](https://xyproto.github.io/splash/docs/all.html)
+* [Long snippets](https://xyproto.github.io/splash/docs/longer/all.html)
+
+For CSS, see [Generate Syntax Highlighter CSS](/content-management/syntax-highlighting/#generate-syntax-highlighter-css).
+
+## Table of contents
+
++This is the default configuration for the table of contents, applicable to Goldmark and Asciidoctor:
++
+{{< code-toggle config=markup.tableOfContents />}}
+
- startLevel
- : The heading level, values starting at 1 (`h1`), to start render the table of contents.
++###### startLevel
+
- endLevel
- : The heading level, inclusive, to stop 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`.
+
- ordered
- : If `true`, generates an ordered list instead of an unordered list.
++###### endLevel
+
- ## Render hooks
++(`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`.
+
- See [Markdown Render Hooks](/templates/render-hooks/).
++###### ordered
+
++(`bool`) If `true`, generates an ordered list instead of an unordered list. Default is `false`.
--- /dev/null
- ├── production/
- │ ├── hugo.toml
- │ └── params.toml
- └── staging/
- ├── hugo.toml
+---
+title: Configure Hugo
+linkTitle: Configuration
+description: How to configure your Hugo site.
+categories: [getting started,fundamentals]
+keywords: [configuration,toml,yaml,json]
+menu:
+ docs:
+ parent: getting-started
+ weight: 40
+weight: 40
+toc: true
+aliases: [/overview/source-directory/,/overview/configuration/]
+---
+
+## Configuration file
+
+Create a site configuration file in the root of your project directory, naming it `hugo.toml`, `hugo.yaml`, or `hugo.json`, with that order of precedence.
+
+```text
+my-project/
+└── hugo.toml
+```
+
+{{% note %}}
+With v0.109.0 and earlier the basename of the site configuration file was `config` instead of `hugo`. You can use either, but should transition to the new naming convention when practical.
+{{% /note %}}
+
+A simple example:
+
+{{< code-toggle file=hugo >}}
+baseURL = 'https://example.org/'
+languageCode = 'en-us'
+title = 'ABC Widgets, Inc.'
+[params]
+subtitle = 'The Best Widgets on Earth'
+[params.contact]
+email = 'info@example.org'
+phone = '+1 202-555-1212'
+{{< /code-toggle >}}
+
+To use a different configuration file when building your site, use the `--config` flag:
+
+```sh
+hugo --config other.toml
+```
+
+Combine two or more configuration files, with left-to-right precedence:
+
+```sh
+hugo --config a.toml,b.yaml,c.json
+```
+
+{{% note %}}
+See the specifications for each file format: [TOML], [YAML], and [JSON].
+
+[TOML]: https://toml.io/en/latest
+[YAML]: https://yaml.org/spec/
+[JSON]: https://datatracker.ietf.org/doc/html/rfc7159
+{{% /note %}}
+
+## Configuration directory
+
+Instead of a single site configuration file, split your configuration by [environment], root configuration key, and language. For example:
+
+[environment]: /getting-started/glossary/#environment
+
+```text
+my-project/
+└── config/
+ ├── _default/
+ │ ├── hugo.toml
+ │ ├── menus.en.toml
+ │ ├── menus.de.toml
+ │ └── 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`.
++ └── production/
+ └── params.toml
+```
+
- (`bool`) Include content with publishdate in the future. Default is `false`.
++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
+
+When splitting the configuration by root key, omit the root key in the given file. For example, these are equivalent:
+
+{{< code-toggle file=hugo >}}
+[params]
+foo = 'bar'
+{{< /code-toggle >}}
+
+{{< code-toggle file=params >}}
+foo = 'bar'
+{{< /code-toggle >}}
+
+### Recursive parsing
+
+Hugo parses the `config` directory recursively, allowing you to organize the files into subdirectories. For example:
+
+```text
+my-project/
+└── config/
+ └── _default/
+ ├── navigation/
+ │ ├── menus.de.toml
+ │ └── menus.en.toml
+ └── hugo.toml
+```
+
+### Example
+
+```text
+my-project/
+└── config/
+ ├── _default/
+ │ ├── hugo.toml
+ │ ├── menus.en.toml
+ │ ├── menus.de.toml
+ │ └── params.toml
+ ├── production/
+ │ ├── hugo.toml
+ │ └── params.toml
+ └── staging/
+ ├── hugo.toml
+ └── params.toml
+```
+
+Considering the structure above, when running `hugo --environment staging`, Hugo will use every setting from `config/_default` and merge `staging`'s on top of those.
+
+Let's take an example to understand this better. Let's say you are using Google Analytics for your website. This requires you to specify a [Google tag ID] in your site configuration:
+
+[Google tag ID]: https://support.google.com/tagmanager/answer/12326985?hl=en
+
+{{< code-toggle file=hugo copy=false >}}
+[services.googleAnalytics]
+ID = 'G-XXXXXXXXX'
+{{< /code-toggle >}}
+
+Now consider the following scenario:
+
+1. You don't want to load the analytics code when running `hugo server`.
+2. You want to use different Google tag IDs for your production and staging environments. For example:
+
+ - `G-PPPPPPPPP` for production
+ - `G-SSSSSSSSS` for staging
+
+To satisfy these requirements, configure your site as follows:
+
+1. `config/_default/hugo.toml`
+
+ Exclude the `services.googleAnalytics` section. This will prevent loading of the analytics code when you run `hugo server`.
+
+ By default, Hugo sets its `environment` to `development` when running `hugo server`. In the absence of a `config/development` directory, Hugo uses the `config/_default` directory.
+
+2. `config/production/hugo.toml`
+
+ Include this section only:
+
+ {{< code-toggle file=hugo copy=false >}}
+ [services.googleAnalytics]
+ ID = 'G-PPPPPPPPP'
+ {{< /code-toggle >}}
+
+ You do not need to include other parameters in this file. Include only those parameters that are specific to your production environment. Hugo will merge these parameters with the default configuration.
+
+ By default, Hugo sets its `environment` to `production` when running `hugo`. The analytics code will use the `G-PPPPPPPPP` tag ID.
+
+3. `config/staging/hugo.toml`
+
+ Include this section only:
+
+ {{< code-toggle file=hugo copy=false >}}
+ [services.googleAnalytics]
+ ID = 'G-SSSSSSSSS'
+ {{< /code-toggle >}}
+
+ You do not need to include other parameters in this file. Include only those parameters that are specific to your staging environment. Hugo will merge these parameters with the default configuration.
+
+ To build your staging site, run `hugo --environment staging`. The analytics code will use the `G-SSSSSSSSS` tag ID.
+
+## Merge configuration from themes
+
+The configuration value for `_merge` can be one of:
+
+none
+: No merge.
+
+shallow
+: Only add values for new keys.
+
+deep
+: Add values for new keys, merge existing.
+
+Note that you don't need to be so verbose as in the default setup below; a `_merge` value higher up will be inherited if not set.
+
+{{< code-toggle file=hugo dataKey="config_helpers.mergeStrategy" skipHeader=true />}}
+
+## All configuration settings
+
+###### archetypeDir
+
+(`string`) The directory where Hugo finds archetype files (content templates). Default is `archetypes`. {{% module-mounts-note %}}
+
+###### assetDir
+
+(`string`) The directory where Hugo finds asset files used in [Hugo Pipes](/hugo-pipes/). Default is `assets`. {{% module-mounts-note %}}
+
+###### baseURL
+
+(`string`) The absolute URL (protocol, host, path, and trailing slash) of your published site (e.g., `https://www.example.org/docs/`).
+
+###### build
+
+See [Configure Build](#configure-build).
+
+###### buildDrafts
+
+(`bool`) Include drafts when building. Default is `false`.
+
+###### buildExpired
+
+(`bool`) Include content already expired. Default is `false`.
+
+###### buildFuture
+
- 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).
++(`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
+
- 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).
++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 %}}
- (`bool`) Enable to turn relative URLs into absolute. Default is `false`. See [details](/content-management/urls/#canonical-urls).
++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
+
- - The `<language>` element in the internal [RSS template](https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/rss.xml)
- - The `lang` attribute of the `<html>` element in the internal [alias template](https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/alias.html)
++(`bool`) See [details](/content-management/urls/#canonical-urls) before enabling this feature. Default is `false`.
+
+###### cleanDestinationDir
+
+(`bool`) When building, removes files from destination not found in static directories. Default is `false`.
+
+###### contentDir
+
+(`string`) The directory from where Hugo reads content files. Default is `content`. {{% module-mounts-note %}}
+
+###### copyright
+
+(`string`) Copyright notice for your site, typically displayed in the footer.
+
+###### dataDir
+
+(`string`) The directory from where Hugo reads data files. Default is `data`. {{% module-mounts-note %}}
+
+###### defaultContentLanguage
+
+(`string`) Content without language indicator will default to this language. Default is `en`.
+
+###### defaultContentLanguageInSubdir
+
+(`bool`) Render the default content language in subdir, e.g. `content/en/`. The site root `/` will then redirect to `/en/`. Default is `false`.
+
+###### disableAliases
+
+(`bool`) Will disable generation of alias redirects. Note that even if `disableAliases` is set, the aliases themselves are preserved on the page. The motivation with this is to be able to generate 301 redirects in an `.htaccess`, a Netlify `_redirects` file or similar using a custom output format. Default is `false`.
+
+###### disableHugoGeneratorInject
+
+(`bool`) Hugo will, by default, inject a generator meta tag in the HTML head on the _home page only_. You can turn it off, but we would really appreciate if you don't, as this is a good way to watch Hugo's popularity on the rise. Default is `false`.
+
+###### disableKinds
+
+(`string slice`) Disable rendering of the specified page [kinds], any of `404`, `home`, `page`, `robotstxt`, `rss`, `section`, `sitemap`, `taxonomy`, or `term`.
+
+[kinds]: /getting-started/glossary/#page-kind
+
+###### disableLiveReload
+
+(`bool`) Disable automatic live reloading of browser window. Default is `false`.
+
+###### disablePathToLower
+
+(`bool`) Do not convert the url/path to lowercase. Default is `false`.
+
+###### enableEmoji
+
+(`bool`) Enable Emoji emoticons support for page content; see the [emoji shortcode quick reference guide](/quick-reference/emojis/). Default is `false`.
+
+###### enableGitInfo
+
+(`bool`) Enable `.GitInfo` object for each page (if the Hugo site is versioned by Git). This will then update the `Lastmod` parameter for each page using the last git commit date for that content file. Default is `false`.
+
+###### enableMissingTranslationPlaceholders
+
+(`bool`) Show a placeholder instead of the default value or an empty string if a translation is missing. Default is `false`.
+
+###### enableRobotsTXT
+
+(`bool`) Enable generation of `robots.txt` file. Default is `false`.
+
+###### frontmatter
+
+See [Front matter Configuration](#configure-front-matter).
+
+###### hasCJKLanguage
+
+(`bool`) If true, auto-detect Chinese/Japanese/Korean Languages in the content. This will make `.Summary` and `.WordCount` behave correctly for CJK languages. Default is `false`.
+
+###### imaging
+
+See [image processing configuration](/content-management/image-processing/#imaging-configuration).
+
+###### languageCode
+
+(`string`) A language tag as defined by [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646). This value is used to populate:
+
- See [Configure Output Formats](#configure-additional-output-formats).
++- The `<language>` element in the embedded [RSS template]({{% eturl rss %}})
++- The `lang` attribute of the `<html>` element in the embedded [alias template]({{% eturl alias %}})
++- The `og:locale` `meta` element in the embedded [Open Graph template]({{% eturl opengraph %}})
++
++When present in the root of the configuration, this value is ignored if one or more language keys exists. Please specify this value independently for each language key.
+
+###### languages
+
+See [Configure Languages](/content-management/multilingual/#configure-languages).
+
+###### disableLanguages
+
+See [Disable a Language](/content-management/multilingual/#disable-a-language)
+
+###### markup
+
+See [Configure Markup](/getting-started/configuration-markup).
+
+###### mediaTypes
+
+See [Configure Media Types](/templates/output-formats/#media-types).
+
+###### menus
+
+See [Menus](/content-management/menus/#define-in-site-configuration).
+
+###### minify
+
+See [Configure Minify](#configure-minify).
+
+###### module
+
+Module configuration see [module configuration](/hugo-modules/configuration/).
+
+###### newContentEditor
+
+(`string`) The editor to use when creating new content.
+
+###### noChmod
+
+(`bool`) Don't sync permission mode of files. Default is `false`.
+
+###### noTimes
+
+(`bool`) Don't sync modification time of files. Default is `false`.
+
+###### outputFormats
+
- (`bool`) Pluralize titles in lists. Default is `true`.
++See [custom output formats].
+
+###### paginate
+
+(`int`) Default number of elements per page in [pagination](/templates/pagination/). Default is `10`.
+
+###### paginatePath
+
+(`string`) The path element used during pagination (`https://example.org/page/2`). Default is `page`.
+
+###### permalinks
+
+See [Content Management](/content-management/urls/#permalinks).
+
+###### pluralizeListTitles
+
- (`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`) 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
+
- ###### refLinksErrorLevel
++(`bool`) See [details](/content-management/urls/#relative-urls) before enabling this feature. Default is `false`.
+
- (`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`.
++###### renderSegments
+
- ###### refLinksNotFoundURL
-
- (`string`) URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is.
++{{< new-in 0.124.0 >}}
+
- See [Security Policy](/about/security-model/#security-policy).
++(`string slice`) A list of segments to render. If not set, everything will be rendered. This is more commonly set in a CLI flag, e.g. `hugo --renderSegments segment1,segment2`. The segment names must match the names in the [segments](#configure-segments) configuration.
+
+###### removePathAccents
+
+(`bool`) Removes [non-spacing marks](https://www.compart.com/en/unicode/category/Mn) from [composite characters](https://en.wikipedia.org/wiki/Precomposed_character) in content paths. Default is `false`.
+
+```text
+content/post/hügó.md → https://example.org/post/hugo/
+```
+
+###### sectionPagesMenu
+
+See [Menus](/content-management/menus/#define-automatically).
+
+###### security
+
- (`int`) The length of text in words to show in a [`.Summary`](/content-management/summaries/#automatic-summary-splitting). Default is `70`.
++See [Security Policy](/about/security/#security-policy).
++
++###### segments
++
++See [Segments](#configure-segments).
+
+###### sitemap
+
+Default [sitemap configuration](/templates/sitemap-template/#configuration).
+
+###### summaryLength
+
- [`strings.Title`]: /functions/strings/title
++(`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
+
+See [Configure Taxonomies](/content-management/taxonomies#configure-taxonomies).
+
+###### theme
+
+See [module configuration](/hugo-modules/configuration/#module-configuration-imports) for how to import a theme.
+
+###### themesDir
+
+(`string`) The directory where Hugo reads the themes from. Default is `themes`.
+
+###### timeout
+
+(`string`) Timeout for generating page contents, specified as a [duration](https://pkg.go.dev/time#Duration) or in seconds. *Note:* this is used to bail out of recursive content generation. You might need to raise this limit if your pages are slow to generate (e.g., because they require large image processing or depend on remote contents). Default is `30s`.
+
+###### timeZone
+
+(`string`) The time zone (or location), e.g. `Europe/Oslo`, used to parse front matter dates without such information and in the [`time`] function. The list of valid values may be system dependent, but should include `UTC`, `Local`, and any location in the [IANA Time Zone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
+
+###### title
+
+(`string`) Site title.
+
+###### titleCaseStyle
+
+(`string`) Default is `ap`. See [Configure Title Case](#configure-title-case).
+
+###### uglyURLs
+
+(`bool`) When enabled, creates URL of the form `/filename.html` instead of `/filename/`. Default is `false`.
+
+###### watch
+
+(`bool`) Watch filesystem for changes and recreate as needed. Default is `false`.
+
+{{% note %}}
+If you are developing your site on a \*nix machine, here is a handy shortcut for finding a configuration option from the command line:
+```txt
+cd ~/sites/yourhugosite
+hugo config | grep emoji
+```
+
+which shows output like
+
+```txt
+enableemoji: true
+```
+{{% /note %}}
+
+## Configure build
+
+The `build` configuration section contains global build-related configuration options.
+
+{{< code-toggle config=build />}}
+
+buildStats {{< new-in 0.115.1 >}}
+: When enabled, creates a `hugo_stats.json` file in the root of your project. This file contains arrays of the `class` attributes, `id` attributes, and tags of every HTML element within your published site. Use this file as data source when [removing unused CSS] from your site. This process is also known as pruning, purging, or tree shaking.
+
+[removing unused CSS]: /hugo-pipes/postprocess/#css-purging-with-postcss
+
+Exclude `class` attributes, `id` attributes, or tags from `hugo_stats.json` with the `disableClasses`, `disableIDs`, and `disableTags` keys.
+
+{{% note %}}
+With v0.115.0 and earlier this feature was enabled by setting `writeStats` to `true`. Although still functional, the `writeStats` key will be deprecated in a future release.
+
+Given that CSS purging is typically limited to production builds, place the `buildStats` object below [config/production].
+
+[config/production]: /getting-started/configuration/#configuration-directory
+
+Built for speed, there may be "false positive" detections (e.g., HTML elements that are not HTML elements) while parsing the published site. These "false positives" are infrequent and inconsequential.
+{{% /note %}}
+
+Due to the nature of partial server builds, new HTML entities are added while the server is running, but old values will not be removed until you restart the server or run a regular `hugo` build.
+
+cachebusters
+: See [Configure Cache Busters](#configure-cache-busters)
+
+noJSConfigInAssets
+: Turn off writing a `jsconfig.json` into your `/assets` folder with mapping of imports from running [js.Build](/hugo-pipes/js). This file is intended to help with intellisense/navigation inside code editors such as [VS Code](https://code.visualstudio.com/). Note that if you do not use `js.Build`, no file will be written.
+
+useResourceCacheWhen
+: When to use the cached resources in `/resources/_gen` for PostCSS and ToCSS. Valid values are `never`, `always` and `fallback`. The last value means that the cache will be tried if PostCSS/extended version is not available.
+
+## Configure cache busters
+
+{{< new-in 0.112.0 >}}
+
+The `build.cachebusters` configuration option was added to support development using Tailwind 3.x's JIT compiler where a `build` configuration may look like this:
+
+{{< code-toggle file=hugo >}}
+[build]
+ [build.buildStats]
+ enable = true
+ [[build.cachebusters]]
+ source = "assets/watching/hugo_stats\\.json"
+ target = "styles\\.css"
+ [[build.cachebusters]]
+ source = "(postcss|tailwind)\\.config\\.js"
+ target = "css"
+ [[build.cachebusters]]
+ source = "assets/.*\\.(js|ts|jsx|tsx)"
+ target = "js"
+ [[build.cachebusters]]
+ source = "assets/.*\\.(.*)$"
+ target = "$1"
+{{< /code-toggle >}}
+
+When `buildStats` {{< new-in 0.115.1 >}} is enabled, Hugo writes a `hugo_stats.json` file on each build with HTML classes etc. that's used in the rendered output. Changes to this file will trigger a rebuild of the `styles.css` file. You also need to add `hugo_stats.json` to Hugo's server watcher. See [Hugo Starter Tailwind Basic](https://github.com/bep/hugo-starter-tailwind-basic) for a running example.
+
+source
+: A regexp matching file(s) relative to one of the virtual component directories in Hugo, typically `assets/...`.
+
+target
+: A regexp matching the keys in the resource cache that should be expired when `source` changes. You can use the matching regexp groups from `source` in the expression, e.g. `$1`.
+
+## Configure server
+
+This is only relevant when running `hugo server`, and it allows to set HTTP headers during development, which allows you to test out your Content Security Policy and similar. The configuration format matches [Netlify's](https://docs.netlify.com/routing/headers/#syntax-for-the-netlify-configuration-file) with slightly more powerful [Glob matching](https://github.com/gobwas/glob):
+
+{{< code-toggle file=hugo >}}
+[server]
+[[server.headers]]
+for = "/**"
+
+[server.headers.values]
+X-Frame-Options = "DENY"
+X-XSS-Protection = "1; mode=block"
+X-Content-Type-Options = "nosniff"
+Referrer-Policy = "strict-origin-when-cross-origin"
+Content-Security-Policy = "script-src localhost:1313"
+{{< /code-toggle >}}
+
+Since this is "development only", it may make sense to put it below the `development` environment:
+
+{{< code-toggle file=config/development/server >}}
+[[headers]]
+for = "/**"
+
+[headers.values]
+X-Frame-Options = "DENY"
+X-XSS-Protection = "1; mode=block"
+X-Content-Type-Options = "nosniff"
+Referrer-Policy = "strict-origin-when-cross-origin"
+Content-Security-Policy = "script-src localhost:1313"
+{{< /code-toggle >}}
+
+You can also specify simple redirects rules for the server. The syntax is again similar to Netlify's.
+
+Note that a `status` code of 200 will trigger a [URL rewrite](https://docs.netlify.com/routing/redirects/rewrites-proxies/), which is what you want in SPA situations, e.g:
+
+{{< code-toggle file=config/development/server >}}
+[[redirects]]
+from = "/myspa/**"
+to = "/myspa/"
+status = 200
+force = false
+{{< /code-toggle >}}
+
+Setting `force=true` will make a redirect even if there is existing content in the path. Note that before Hugo 0.76 `force` was the default behavior, but this is inline with how Netlify does it.
+
+## 404 server error page {#_404-server-error-page}
+
+{{< new-in 0.103.0 >}}
+
+Hugo will, by default, render all 404 errors when running `hugo server` with the `404.html` template. Note that if you have already added one or more redirects to your [server configuration](#configure-server), you need to add the 404 redirect explicitly, e.g:
+
+{{< code-toggle file=config/development/server >}}
+[[redirects]]
+from = "/**"
+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.
+
+Change this behavior by setting `titleCaseStyle` in your site configuration to any of the values below:
+
+ap
+: Use the capitalization rules published in the [Associated Press Stylebook].
+
+chicago
+: Use the capitalization rules published in the [Chicago Manual of Style].
+
+go
+: Capitalize the first letter of every word.
+
+firstupper
+: Capitalize the first letter of the first word.
+
+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.
+
- : 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.
++[`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
- ## 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.
-
++: (`int`) The number of workers used in parallel processing. Default is the number of logical CPUs.
+
+## Configure with environment variables
+
+In addition to the 3 configuration options already mentioned, configuration key-values can be defined through operating system environment variables.
+
+For example, the following command will effectively set a website's title on Unix-like systems:
+
+```txt
+$ env HUGO_TITLE="Some Title" hugo
+```
+
+This is really useful if you use a service such as Netlify to deploy your site. Look at the Hugo docs [Netlify configuration file](https://github.com/gohugoio/hugoDocs/blob/master/netlify.toml) for an example.
+
+{{% note %}}
+Names must be prefixed with `HUGO_` and the configuration key must be set in uppercase when setting operating system environment variables.
+
+To set configuration parameters, prefix the name with `HUGO_PARAMS_`
+{{% /note %}}
+
+If you are using snake_cased variable names, the above will not work. Hugo determines the delimiter to use by the first character after `HUGO`. This allows you to define environment variables on the form `HUGOxPARAMSxAPI_KEY=abcdefgh`, using any [allowed](https://stackoverflow.com/questions/2821043/allowed-characters-in-linux-environment-variable-names#:~:text=So%20names%20may%20contain%20any,not%20begin%20with%20a%20digit.) delimiter.
+
+## Ignore content and data files when rendering
+
+{{% note %}}
+This works, but we recommend you use the newer and more powerful [includeFiles and excludeFiles](/hugo-modules/configuration/#module-configuration-mounts) mount options.
+{{% /note %}}
+
+To exclude specific files from the `content`, `data`, and `i18n` directories when rendering your site, set `ignoreFiles` to one or more regular expressions to match against the absolute file path.
+
+To ignore files ending with `.foo` or `.boo`:
+
+{{< code-toggle file=hugo >}}
+ignoreFiles = ['\.foo$', '\.boo$']
+{{< /code-toggle >}}
+
+To ignore a file using the absolute file path:
+
+{{< code-toggle file=hugo >}}
+ignoreFiles = ['^/home/user/project/content/test\.md$']
+{{< /code-toggle >}}
+
+## Configure front matter
+
+### Configure dates
+
+Dates are important in Hugo, and you can configure how Hugo assigns dates to your content pages. You do this by adding a `frontmatter` section to your `hugo.toml`.
+
+The default configuration is:
+
+{{< code-toggle config=frontmatter />}}
+
+If you, as an example, have a non-standard date parameter in some of your content, you can override the setting for `date`:
+
+{{< code-toggle file=hugo >}}
+[frontmatter]
+date = ["myDate", ":default"]
+{{< /code-toggle >}}
+
+The `:default` is a shortcut to the default settings. The above will set `.Date` to the date value in `myDate` if present, if not we will look in `date`,`publishDate`, `lastmod` and pick the first valid date.
+
+In the list to the right, values starting with ":" are date handlers with a special meaning (see below). The others are just names of date parameters (case insensitive) in your front matter configuration. Also note that Hugo have some built-in aliases to the above: `lastmod` => `modified`, `publishDate` => `pubdate`, `published` and `expiryDate` => `unpublishdate`. With that, as an example, using `pubDate` as a date in front matter, will, by default, be assigned to `.PublishDate`.
+
+The special date handlers are:
+
+`:fileModTime`
+: Fetches the date from the content file's last modification timestamp.
+
+An example:
+
+{{< code-toggle file=hugo >}}
+[frontmatter]
+lastmod = ["lastmod", ":fileModTime", ":default"]
+{{< /code-toggle >}}
+
+The above will try first to extract the value for `.Lastmod` starting with the `lastmod` front matter parameter, then the content file's modification timestamp. The last, `:default` should not be needed here, but Hugo will finally look for a valid date in `:git`, `date` and then `publishDate`.
+
+`:filename`
+: Fetches the date from the content file's file name. For example, `2018-02-22-mypage.md` will extract the date `2018-02-22`. Also, if `slug` is not set, `mypage` will be used as the value for `.Slug`.
+
+An example:
+
+{{< code-toggle file=hugo >}}
+[frontmatter]
+date = [":filename", ":default"]
+{{< /code-toggle >}}
+
+The above will try first to extract the value for `.Date` from the file name, then it will look in front matter parameters `date`, `publishDate` and lastly `lastmod`.
+
+`: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.
+
- This can be set using the `cacheDir` config option or via the OS env variable `HUGO_CACHEDIR`.
+## Configure minify
+
+See the [tdewolff/minify] project page for details.
+
+[tdewolff/minify]: https://github.com/tdewolff/minify
+
+Default configuration:
+
+{{< code-toggle config=minify />}}
+
+## Configure file caches
+
+Since Hugo 0.52 you can configure more than just the `cacheDir`. This is the default configuration:
+
+{{< code-toggle config=caches />}}
+
+You can override any of these cache settings in your own `hugo.toml`.
+
+### The keywords explained
+
+cacheDir
+: (`string`) See [Configure cacheDir](#configure-cachedir).
+
+project
+: (`string`) The base directory name of the current Hugo project. This means that, in its default setting, every project will have separated file caches, which means that when you do `hugo --gc` you will not touch files related to other Hugo projects running on the same PC.
+
+resourceDir
+: (`string`) This is the value of the `resourceDir` configuration option.
+
+maxAge
+: (`string`) This is the duration before a cache entry will be evicted, -1 means forever and 0 effectively turns that particular cache off. Uses Go's `time.Duration`, so valid values are `"10s"` (10 seconds), `"10m"` (10 minutes) and `"10h"` (10 hours).
+
+dir
+: (`string`) The absolute path to where the files for this cache will be stored. Allowed starting placeholders are `:cacheDir` and `:resourceDir` (see above).
+
+## Configure cacheDir
+
+This is the directory where Hugo by default will store its file caches. See [Configure File Caches](#configure-file-caches).
+
- [`time`]: /functions/time/astime
- [`.Site.Params`]: /variables/site/
- [directory structure]: /getting-started/directory-structure
++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:
+
+1. If running on Netlify: `/opt/build/cache/hugo_cache/`. This means that if you run your builds on Netlify, all caches configured with `:cacheDir` will be saved and restored on the next build. For other CI vendors, please read their documentation. For an CircleCI example, see [this configuration](https://github.com/bep/hugo-sass-test/blob/6c3960a8f4b90e8938228688bc49bdcdd6b2d99e/.circleci/config.yml).
+1. In a `hugo_cache` directory below the OS user cache directory as defined by Go's [os.UserCacheDir](https://pkg.go.dev/os#UserCacheDir). On Unix systems, this is `$XDG_CACHE_HOME` as specified by [basedir-spec-latest](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) if non-empty, else `$HOME/.cache`. On MacOS, this is `$HOME/Library/Caches`. On Windows, this is`%LocalAppData%`. On Plan 9, this is `$home/lib/cache`. {{< new-in 0.116.0 >}}
+1. In a `hugo_cache_$USER` directory below the OS temp dir.
+
+If you want to know the current value of `cacheDir`, you can run `hugo config`, e.g: `hugo config | grep cachedir`.
+
- [Output Formats]: /templates/output-formats/
++[`time`]: /functions/time/astime/
++[`.Site.Params`]: /method/site/params/
++[directory structure]: /getting-started/directory-structure/
+[lookup order]: /templates/lookup-order/
++[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
++
--- /dev/null
- archetypes
- : The `archetypes` directory contains templates for new content. See [details](/content-management/archetypes/).
+---
+title: Directory structure
+description: Each Hugo project is a directory, with subdirectories that contribute to the content, structure, behavior, and presentation of your site.
+categories: [getting started,fundamentals]
+keywords: [source, organization, directories]
+menu:
+ docs:
+ parent: getting-started
+ weight: 30
+weight: 30
+toc: true
+aliases: [/overview/source-directory/]
+---
+
+## Site skeleton
+
+Hugo generates a project skeleton when you create a new site. For example, this command:
+
+```sh
+hugo new site my-site
+```
+
+Creates this directory structure:
+
+```txt
+my-site/
+├── archetypes/
+│ └── default.md
+├── assets/
+├── content/
+├── data/
+├── i18n/
+├── layouts/
+├── static/
+├── themes/
+└── hugo.toml <-- site configuration
+```
+
+Depending on requirements, you may wish to organize your site configuration into subdirectories:
+
+```txt
+my-site/
+├── archetypes/
+│ └── default.md
+├── assets/
+├── config/ <-- site configuration
+│ └── _default/
+│ └── hugo.toml
+├── content/
+├── data/
+├── i18n/
+├── layouts/
+├── static/
+└── themes/
+```
+
+When you build your site, Hugo creates a `public` directory, and typically a `resources` directory as well:
+
+```txt
+my-site/
+├── archetypes/
+│ └── default.md
+├── assets/
+├── config/
+│ └── _default/
+│ └── hugo.toml
+├── content/
+├── data/
+├── i18n/
+├── layouts/
+├── public/ <-- created when you build your site
+├── resources/ <-- created when you build your site
+├── static/
+└── themes/
+```
+
+## Directories
+
+Each of the subdirectories contributes to the content, structure, behavior, or presentation of your site.
+
- 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/).
++###### 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).
++The `archetypes` directory contains templates for new content. See [details](/content-management/archetypes/).
+
- 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/).
++###### assets
+
- data
- : The `data` directory contains data files (JSON, TOML, YAML, or XML) that augment content, configuration, localization, and navigation. See [details](/templates/data-templates/).
++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/).
+
- i18n
- : The `i18n` directory contains translation tables for multilingual sites. See [details](/content-management/multilingual/).
++###### config
+
- layouts
- : The layouts directory contains templates to transform content, data, and resources into a complete website. See [details](/templates/).
++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).
+
- 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).
++###### content
+
- resources
- : The `resources` directory contains cached output from Hugo's asset pipelines, generated when you run the `hugo` or `hugo server` commands. By default this cache directory includes CSS and images. Hugo recreates this directory and its content as needed.
++The `content` directory contains the markup files (typically Markdown) and page resources that comprise the content of your site. See [details](/content-management/organization/).
+
- 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/).
++###### data
+
- themes
- : The `themes` directory contains one or more [themes](/getting-started/glossary/#theme), each in its own subdirectory.
++The `data` directory contains data files (JSON, TOML, YAML, or XML) that augment content, configuration, localization, and navigation. See [details](/content-management/data-sources/).
+
- If you think you need a symbolic link in your project directory, use Hugo's union file system instead.
++###### 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
+
+Hugo creates a union file system, allowing you to mount two or more directories to the same location. For example, let's say your home directory contains a Hugo project in one directory, and shared content in another:
+
+```text
+home/
+└── user/
+ ├── my-site/
+ │ ├── content/
+ │ │ ├── books/
+ │ │ │ ├── _index.md
+ │ │ │ ├── book-1.md
+ │ │ │ └── book-2.md
+ │ │ └── _index.md
+ │ ├── themes/
+ │ │ └── my-theme/
+ │ └── hugo.toml
+ └── shared-content/
+ └── films/
+ ├── _index.md
+ ├── film-1.md
+ └── film-2.md
+```
+
+You can include the shared content when you build your site using mounts. In your site configuration:
+
+{{< code-toggle file=hugo >}}
+[[module.mounts]]
+source = 'content'
+target = 'content'
+
+[[module.mounts]]
+source = '/home/user/shared-content'
+target = 'content'
+{{< /code-toggle >}}
+
+{{% note %}}
+When you overlay one directory on top of another, you must mount both directories.
+
++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:
+
+```text
+home/
+└── user/
+ └── my-site/
+ ├── content/
+ │ ├── books/
+ │ │ ├── _index.md
+ │ │ ├── book-1.md
+ │ │ └── book-2.md
+ │ ├── films/
+ │ │ ├── _index.md
+ │ │ ├── film-1.md
+ │ │ └── film-2.md
+ │ └── _index.md
+ ├── themes/
+ │ └── my-theme/
+ └── hugo.toml
+```
+
+{{% note %}}
+When two or more files have the same path, the order of precedence follows the order of the mounts. For example, if the shared content directory contains `books/book-1.md`, it will be ignored because the project's content directory was mounted first.
+{{% /note %}}
+
+You can mount directories to `archetypes`, `assets`, `content`, `data`, `i18n`, `layouts`, and `static`. See [details](/hugo-modules/configuration/#module-configuration-mounts).
+
+You can also mount directories from Git repositories using Hugo Modules. See [details](/hugo-modules/).
+
+## Theme skeleton
+
+Hugo generates a functional theme skeleton when you create a new theme. For example, this command:
+
+```text
+hugo new theme my-theme
+```
+
+Creates this directory structure (subdirectories not shown):
+
+```text
+my-theme/
+├── archetypes/
+├── assets/
+├── content/
+├── data/
+├── i18n/
+├── layouts/
+├── static/
+├── LICENSE
+├── README.md
+├── hugo.toml
+└── theme.toml
+```
+
+Using the union file system described above, Hugo mounts each of these directories to the corresponding location in the project. When two files have the same path, the file in the project directory takes precedence. This allows you, for example, to override a theme's template by placing a copy in the same location within the project directory.
+
+If you are simultaneously using components from two or more themes or modules, and there's a path collision, the first mount takes precedence.
--- /dev/null
- description: A list of tutorials and books on Hugo.
+---
+title: External learning resources
- [](https://www.manning.com/books/hugo-in-action)
++description: Use these third-party resources to learn Hugo.
+categories: [getting started]
+keywords: [books, tutorials, learning, usage]
+menu:
+ docs:
+ parent: getting-started
+ weight: 70
+weight: 70
++toc: true
+---
+
+## 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.
+
- [Hugo In Action Home Page](https://www.manning.com/books/hugo-in-action)
++[{{< 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
+
- [Build Websites with Hugo - Fast Web Development with Markdown (2020)](https://pragprog.com/titles/bhhugo/) by Brian P. Hogan.
+
+### Build Websites with Hugo
+
- ## Beginner tutorials
++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/)
+
- ### Hugo tutorial by CloudCannon
++Creator: Mike Neumegen\
++Affiliation: [CloudCannon](https://cloudcannon.com/)\
++Creation date: April 2022
+
- [Step-by-step written tutorial](https://cloudcannon.com/community/learn/hugo-beginner-tutorial/) to teach you the basics of creating a Hugo site.
++#### Hugo Static Site Generator
+
- ## Video tutorials
++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!
+
- * Mike Dane explains the various features of Hugo via dedicated tutorials on [YouTube](https://www.youtube.com/watch?list=PLLAZ4kZ9dFpOnyRlyS-liKL5ReHDcj4G3&v=qtIqKaDlqXo).
+
- * [Introduction to building your first Hugo site](https://cloudcannon.com/community/learn/hugo-beginner-tutorial/) by Mike Neumegen.
++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/)
+
++Creator: Mike Dane\
++Affiliation: [Giraffe Academy](https://www.giraffeacademy.com/)\
++Creation date: September 2017
--- /dev/null
- [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)
+---
+title: Glossary of terms
+description: Terms commonly used throughout the documentation.
+categories: [getting started]
+keywords: [glossary]
+menu:
+ docs:
+ parent: getting-started
+ weight: 60
+weight: 60
+# Use level 6 headings for each term in the glossary.
+---
+
- 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](#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
+
+See [template action](#template-action).
+
+###### archetype
+
+A template for new content. See [details](/content-management/archetypes/).
+
+###### argument
+
+A [scalar](#scalar), [array](#array), [slice](#slice), [map](#map), or [object](#object) passed to a [function](#function), [method](#method), or [shortcode](#shortcode).
+
+###### array
+
+A numbered sequence of elements. Unlike Go's [slice](#slice) data type, an array has a fixed length. [Elements](#element) within an array can be [scalars](#scalar), slices, [maps](#map), pages, or other arrays. See the [Go documentation](https://go.dev/ref/spec#Array_types) for details.
+
+###### bool
+
+See [boolean](#boolean).
+
+###### boolean
+
+A data type with two possible values, either `true` or `false`.
+
+###### branch bundle
+
- A markup language for creating content. Typically markdown, but may also be HTML, AsciiDoc, Org, Pandoc, or reStructuredText. See [details](/content-management/formats/).
++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
+
+To generate a static site that includes HTML files and assets such as images, CSS, and JavaScript. The build process includes rendering and resource transformations.
+
+###### bundle
+
+See [page bundle](#page-bundle).
+
+###### cache
+
+A software component that stores data so that future requests for the same data are faster.
+
+###### chain
+
+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
+
- 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).
++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
+
+A classification of content inferred from the top-level directory name or the `type` set in [front matter](#front-matter). Pages in the root of the content directory, including the home page, are of type "page". Accessed via `.Page.Type` in [templates](#template). See [details](/content-management/types/).
+
+###### content view
+
+A template called with the `.Page.Render` method. See [details](/templates/views/).
+
+###### context
+
- 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.
++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
+
+The default sort order for page collections. Hugo sorts by [weight](#weight), then by date (descending), then by link title, and then by file path.
+
+###### element
+
+A member of a slice or array.
+
+###### environment
+
+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.
+
- [`hugo.Environment`]: /functions/hugo/environment
++When running the built-in development server with the `hugo server` command, the environment is set to `development`. When building your site with the `hugo` command, the environment is set to `production`. To override the environment value, use the `--environment` command line flag or the `HUGO_ENVIRONMENT` environment variable.
+
+To determine the current environment within a template, use the [`hugo.Environment`] function.
+
- A predefined key/value pair in front matter such as `date` or `title`. See also [parameter](#parameter).
++[`hugo.Environment`]: /functions/hugo/environment/
+
+###### field
+
- [`resources.Get`]: /functions/resources/get
- [`resources.GetMatch`]: /functions/resources/getmatch
- [`resources.Match`]: /functions/resources/match
- [`resources.ByType`]: /functions/resources/byType
++A predefined key-value pair in front matter such as `date` or `title`. See also [parameter](#parameter).
+
+
+###### flag
+
+An option passed to a command-line program, beginning with one or two hyphens. See [details](/commands/hugo/).
+
+###### float
+
+See [floating point](#floating-point).
+
+###### floating point
+
+A numeric data type with a fractional component. For example, `3.14159`.
+
+###### fragment
+
+The final segment of a URL, beginning with a hash (`#`) mark, that references an `id` attribute of an HTML element on the page.
+
+###### front matter
+
+Metadata at the beginning of each content page, separated from the content by format-specific delimiters. See [details](/content-management/front-matter/).
+
+###### function
+
+Used within a [template action](#template-action), a function takes one or more [arguments](#argument) and returns a value. Unlike [methods](#method), functions are not associated with an [object](#object). See [details](/functions/).
+
+###### global resource
+
+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.
+
- 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/).
++[`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
+
+A string that represents a variable, method, object, or field. It must conform to Go's [language specification](https://go.dev/ref/spec#Identifiers), beginning with a letter or underscore, followed by zero or more letters, digits, or underscores.
+
+###### int
+
+See [integer](#integer).
+
+###### integer
+
+A numeric data type without a fractional component. For example, `42`.
+
+###### internationalization
+
+Software design and development efforts that enable [localization](#localization). See the [W3C definition](https://www.w3.org/International/questions/qa-i18n). Abbreviated i18n.
+
+###### interval
+
+An [interval](https://en.wikipedia.org/wiki/Interval_(mathematics)) is a range of numbers between two endpoints: closed, open, or half-open.
+
+- A _closed_ interval, denoted by brackets, includes its endpoints. For example, [0, 1] is the interval where `0 <= x <= 1`.
+
+- An _open_ interval, denoted by parentheses, excludes its endpoints. For example, (0, 1) is the interval where `0 < x < 1`.
+
+- A _half-open_ interval includes only one of its endpoints. For example, (0, 1] is the _left-open_ interval where `0 < x <= 1`, while [0, 1) is the _right-open_ interval where `0 <= x < 1`.
+
+###### kind
+
+See [page kind](#page-kind).
+
+###### layout
+
+See [template](#template).
+
+###### leaf bundle
+
- ###### markdown attribute
++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
+
+Any [page kind](#page-kind) that receives a page [collection](#collection) in [context](#context). This includes the home page, [section pages](#section-page), [taxonomy pages](#taxonomy-page), and [term pages](#term-page).
+
+###### localization
+
+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. <!-- You may also set this value using the `path` front matter field. --> 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.
+
- 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).
++###### Markdown attribute
+
- [`Alphabetical`]: /methods/taxonomy/alphabetical
- [`ByCount`]: /methods/taxonomy/bycount
++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
+
+To transform a data structure into a serialized object. For example, transforming a [map](#map) into a JSON string. See [unmarshal](#unmarshal).
+
+###### method
+
+Used within a [template action](#template-action) and associated with an [object](#object), a method takes zero or more [arguments](#argument) and either returns a value or performs an action. For example, `.IsHome` is a method on the `.Page` object which returns `true` if the current page is the home page. See also [function](#function).
+
+###### module
+
+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).
+
+###### ordered taxonomy
+
+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).
+
- A classification of pages, one of `home`, `page`, `section`, `taxonomy`, or `term`. See [details](/templates/section-templates/#page-kinds).
++[`Alphabetical`]: /methods/taxonomy/alphabetical/
++[`ByCount`]: /methods/taxonomy/bycount/
+
+###### output format
+
+{{% include "methods/page/_common/output-format-definition.md" %}}
+
+###### page bundle
+
+A directory that encapsulates both content and associated [resources](#resource). There are two types of page bundles: [leaf bundles](#leaf-bundle) and [branch bundles](#branch-bundle). See [details](/content-management/page-bundles/).
+
+###### page collection
+
+A slice of page objects.
+
+###### page kind
+
- 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).
++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.
+
+###### page resource
+
+A file within a [page bundle](#page-bundle). Capture one or more page resources using any of the [`Resources`] methods on a `Page` object.
+
+[`Resources`]: /methods/page/resources/#methods
+
+###### pager
+
+Created during [pagination](#pagination), a pager contains a subset of a section list, and navigation links to other pagers.
+
+###### paginate
+
+To split a [section](#section) list into two or more [pagers](#pager) See [details](/templates/pagination/).
+
+###### pagination
+
+The process of [paginating](#paginate) a [section](#section) list.
+
+###### parameter
+
- A [template](#template) that overrides standard markdown rendering. See [details](/templates/render-hooks/).
++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
+
+A [template](#template) called from any other template including [shortcodes](#shortcode), [render hooks](#render-hook), and other partials. A partial either renders something or returns something. A partial can also call itself, for example, to [walk](#walk) a data structure.
+
+###### permalink
+
+The absolute URL of a published resource or a rendered page, including scheme and host.
+
+###### pipe
+
+See [pipeline](#pipeline).
+
+###### pipeline
+
+Within a [template action](#template-action), a pipeline is a possibly chained sequence of values, [function](#function) calls, or [method](#method) calls. Functions and methods in the pipeline may take multiple [arguments](#argument).
+
+A pipeline may be *chained* by separating a sequence of commands with pipeline characters "|". In a chained pipeline, the result of each command is passed as the last argument to the following command. The output of the final command in the pipeline is the value of the pipeline. See the [Go documentation](https://pkg.go.dev/text/template#hdr-Pipelines) for details.
+
+###### publish
+
+See [build](#build).
+
+###### regular page
+
+Content with the "page" [page kind](#page-kind). See also [section page](#section-page).
+
+###### relative permalink
+
+The host-relative URL of a published resource or a rendered page.
+
+###### render hook
+
- 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.
++A [template](#template) that overrides standard Markdown rendering. See [details](/render-hooks).
+
+###### remote resource
+
+A file on a remote server, accessible via HTTP or HTTPS with the [`resources.GetRemote`](/functions/resources/getremote) function.
+
+###### resource
+
+Any file consumed by the build process to augment or generate content, structure, behavior, or presentation. For example: images, videos, content snippets, CSS, Sass, JavaScript, and data.
+
+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
+
- [`Scratch`]: /methods/page/scratch
- [`Store`]: /methods/page/store
- [`newScratch`]: /functions/collections/newscratch
++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.
+
- A [template](#template) called from within markdown, taking zero or more [arguments](#argument). See [details](/content-management/shortcodes/).
++[`Scratch`]: /methods/page/scratch/
++[`Store`]: /methods/page/store/
++[`newScratch`]: /functions/collections/newscratch/
+
+###### section
+
+A top-level content directory, or any content directory with an _index.md file. A content directory with an _index.md file is also known as a [branch bundle](/getting-started/glossary/#branch-bundle). Section templates receive one or more page [collections](#collection) in [context](#context). See [details](/content-management/sections/).
+
+###### section page
+
+Content with the "section" [page kind](#page-kind). Typically a listing of [regular pages](#regular-page) and/or [section pages](#section-page) within the current [section](#section). See also [regular page](#regular-page).
+
+###### shortcode
+
- 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 [template](#template) called from within Markdown, taking zero or more [arguments](#argument). See [details](/content-management/shortcodes/).
+
+###### slice
+
+A numbered sequence of elements. Unlike Go's [array](#array) data type, slices are dynamically sized. [Elements](#element) within a slice can be [scalars](#scalar), [arrays](#array), [maps](#map), pages, or other slices. See the [Go documentation](https://go.dev/ref/spec#Slice_types) for details.
+
+###### string
+
+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).
+
+###### taxonomy
+
+A group of related [terms](#term) used to classify content. For example, a "colors" taxonomy might include the terms "red", "green", and "blue". See [details](/content-management/taxonomies/).
+
+###### taxonomy object
+
+A [map](#map) of [terms](#term) and the [weighted pages](#weighted-page) associated with each term.
+
+###### taxonomy page
+
+Content with the "taxonomy" [page kind](#page-kind). Typically a listing of [terms](#term) within a given [taxonomy](#taxonomy).
+
+###### template
+
+A file with [template actions](#template-action), located within the layouts directory of a project, theme, or module. See [details](/templates/).
+
+###### template action
+
+A data evaluation or control structure within a [template](#template), delimited by "{{" and "}}". See the [Go documentation](https://pkg.go.dev/text/template#hdr-Actions) for details.
+
+###### term
+
+A member of a [taxonomy](#taxonomy), used to classify content. See [details](/content-management/taxonomies/).
+
+###### term page
+
+Content with the "term" [page kind](#page-kind). Typically a listing of [regular pages](#regular-page) and [section pages](#section-page) with a given [term](#term).
+
+###### theme
+
+A packaged combination of [archetypes](#archetype), assets, content, data, [templates](#template), translation tables, static files, or configuration settings. A theme may serve as the basis for a new site, or to augment an existing site. See also [module](#module).
+
+###### token
+
+An identifier within a format string, beginning with a colon and replaced with a value when rendered. For example, use tokens in format strings for both [permalinks](/content-management/urls/#permalinks) and [dates](/functions/time/format/#localization).
+
+###### type
+
+See [content type](#content-type).
+
+###### unmarshal
+
+To transform a serialized object into a data structure. For example, transforming a JSON file into a [map](#map) that you can access within a template. See [marshal](#marshal).
+
+###### variable
+
++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
+
+To recursively traverse a nested data structure. For example, rendering a multilevel menu.
+
+###### weight
+
+Used to position an element within a collection sorted by weight. Assign weights using non-zero integers. Lighter items float to the top, while heavier items sink to the bottom. Unweighted or zero-weighted elements are placed at the end of the collection. Weights are typically assigned to pages, menu entries, languages, and output formats.
+
+###### 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.
--- /dev/null
- hugo new content posts/my-first-post.md
+---
+title: Quick start
+description: Learn to create a Hugo site in minutes.
+categories: [getting started]
+keywords: [quick start,usage]
+menu:
+ docs:
+ parent: getting-started
+ weight: 20
+weight: 20
+toc: true
+aliases: [/quickstart/,/overview/quickstart/]
+minVersion: v0.112.0
+---
+
+In this tutorial you will:
+
+1. Create a site
+2. Add content
+3. Configure the site
+4. Publish the site
+
+## Prerequisites
+
+Before you begin this tutorial you must:
+
+1. [Install Hugo] (extended edition, {{% param "minVersion" %}} or later)
+1. [Install Git]
+
+You must also be comfortable working from the command line.
+
+## Create a site
+
+### Commands
+
+{{% note %}}
+**If you are a Windows user:**
+
+- Do not use the Command Prompt
+- Do not use Windows PowerShell
+- Run these commands from [PowerShell] or a Linux terminal such as WSL or Git Bash
+
+PowerShell and Windows PowerShell [are different applications].
+
+[PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows
+[are different applications]: https://learn.microsoft.com/en-us/powershell/scripting/whats-new/differences-from-windows-powershell?view=powershell-7.3
+{{% /note %}}
+
+Verify that you have installed Hugo {{% param "minVersion" %}} or later.
+
+```text
+hugo version
+```
+
+Run these commands to create a Hugo site with the [Ananke] theme. The next section provides an explanation of each command.
+
+```text
+hugo new site quickstart
+cd quickstart
+git init
+git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
+echo "theme = 'ananke'" >> hugo.toml
+hugo server
+```
+
+View your site at the URL displayed in your terminal. Press `Ctrl + C` to stop Hugo's development server.
+
+### Explanation of commands
+
+Create the [directory structure] for your project in the `quickstart` directory.
+
+```text
+hugo new site quickstart
+```
+
+Change the current directory to the root of your project.
+
+```text
+cd quickstart
+```
+
+Initialize an empty Git repository in the current directory.
+
+```text
+git init
+```
+
+Clone the [Ananke] theme into the `themes` directory, adding it to your project as a [Git submodule].
+
+```text
+git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
+```
+
+Append a line to the site configuration file, indicating the current theme.
+
+```text
+echo "theme = 'ananke'" >> hugo.toml
+```
+
+Start Hugo's development server to view the site.
+
+```text
+hugo server
+```
+
+Press `Ctrl + C` to stop Hugo's development server.
+
+## Add content
+
+Add a new page to your site.
+
+```text
- Add some [markdown] to the body of the post, but do not change the `draft` value.
++hugo new content content/posts/my-first-post.md
+```
+
+Hugo created the file in the `content/posts` directory. Open the file with your editor.
+
+```text
++++
+title = 'My First Post'
+date = 2024-01-14T07:07:07+01:00
+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].
+
- 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.
++Add some [Markdown] to the body of the post, but do not change the `draft` value.
+
+[markdown]: https://commonmark.org/help/
+
+```text
++++
+title = 'My First Post'
+date = 2024-01-14T07:07:07+01:00
+draft = true
++++
+## Introduction
+
+This is **bold** text, and this is *emphasized* text.
+
+Visit the [Hugo](https://gohugo.io) website!
+```
+
+Save the file, then start Hugo’s development server to view the site. You can run either of the following commands to include draft content.
+
+```text
+hugo server --buildDrafts
+hugo server -D
+```
+
+View your site at the URL displayed in your terminal. Keep the development server running as you continue to add and change content.
+
++When satisfied with your new content, set the front matter `draft` parameter to `false`.
++
+{{% note %}}
- [directory structure]: /getting-started/directory-structure
++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/
+{{% /note %}}
+
+## Configure the site
+
+With your editor, open the [site configuration] file (`hugo.toml`) in the root of your project.
+
+```text
+baseURL = 'https://example.org/'
+languageCode = 'en-us'
+title = 'My New Hugo Site'
+theme = 'ananke'
+```
+
+Make the following changes:
+
+1. Set the `baseURL` for your production site. This value must begin with the protocol and end with a slash, as shown above.
+
+2. Set the `languageCode` to your language and region.
+
+3. Set the `title` for your production site.
+
+Start Hugo's development server to see your changes, remembering to include draft content.
+
+```text
+hugo server -D
+```
+
+{{% note %}}
+Most theme authors provide configuration guidelines and options. Make sure to visit your theme's repository or documentation site for details.
+
+[The New Dynamic], authors of the Ananke theme, provide [documentation] for configuration and usage. They also provide a [demonstration site].
+
+[demonstration site]: https://gohugo-ananke-theme-demo.netlify.app/
+[documentation]: https://github.com/theNewDynamic/gohugo-theme-ananke#readme
+[The New Dynamic]: https://www.thenewdynamic.com/
+{{% /note %}}
+
+## Publish the site
+
+In this step you will _publish_ your site, but you will not _deploy_ it.
+
+When you _publish_ your site, Hugo creates the entire static site in the `public` directory in the root of your project. This includes the HTML files, and assets such as images, CSS files, and JavaScript files.
+
+When you publish your site, you typically do _not_ want to include [draft, future, or expired content]. The command is simple.
+
+```text
+hugo
+```
+
+To learn how to _deploy_ your site, see the [hosting and deployment] section.
+
+## Ask for help
+
+Hugo's [forum] is an active community of users and developers who answer questions, share knowledge, and provide examples. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question.
+
+## Other resources
+
+For other resources to help you learn Hugo, including books and video tutorials, see the [external learning resources](/getting-started/external-learning-resources/) page.
+
+[Ananke]: https://github.com/theNewDynamic/gohugo-theme-ananke
- [front matter]: /content-management/front-matter
++[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/
+[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
+[Install Hugo]: /installation/
+[Requesting Help]: https://discourse.gohugo.io/t/requesting-help/9132
+[Requesting Help]: https://discourse.gohugo.io/t/requesting-help/9132
+[site configuration]: /getting-started/configuration/
--- /dev/null
- hugo v0.122.0-b9a03bd59d5f71a529acb3e33f995e0ef332b3aa+extended linux/amd64 BuildDate=2024-01-26T15:54:24Z VendorInfo=gohugoio
+---
+title: Basic usage
+description: Hugo's command line interface (CLI) is fully featured but simple to use, even for those with limited experience working from the command line.
+categories: [getting started]
+keywords: [usage,livereload,command,flags]
+menu:
+ docs:
+ parent: getting-started
+ weight: 30
+weight: 30
+toc: true
+aliases: [/overview/usage/,/extras/livereload/,/doc/usage/,/usage/]
+---
+
+## Test your installation
+
+After [installing] Hugo, test your installation by running:
+
+```sh
+hugo version
+```
+
+You should see something like:
+
+```text
- ├── post/
++hugo v0.123.0-3c8a4713908e48e6523f058ca126710397aa4ed5+extended linux/amd64 BuildDate=2024-02-19T16:32:38Z VendorInfo=gohugoio
+```
+
+## Display available commands
+
+To see a list of the available commands and flags:
+
+```sh
+hugo help
+```
+
+To get help with a subcommand, use the `--help` flag. For example:
+
+```sh
+hugo server --help
+```
+
+## Build your site
+
+To build your site, `cd` into your project directory and run:
+
+```sh
+hugo
+```
+
+The [`hugo`] command builds your site, publishing the files to the `public` directory. To publish your site to a different directory, use the [`--destination`] flag or set [`publishDir`] in your site configuration.
+
+{{% note %}}
+Hugo does not clear the `public` directory before building your site. Existing files are overwritten, but not deleted. This behavior is intentional to prevent the inadvertent removal of files that you may have added to the `public` directory after the build.
+
+Depending on your needs, you may wish to manually clear the contents of the public directory before every build.
+{{% /note %}}
+
+## Draft, future, and expired content
+
+Hugo allows you to set `draft`, `date`, `publishDate`, and `expiryDate` in the [front matter] of your content. By default, Hugo will not publish content when:
+
+- The `draft` value is `true`
+- The `date` is in the future
+- 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
+hugo --buildDrafts # or -D
+hugo --buildExpired # or -E
+hugo --buildFuture # or -F
+```
+
+Although you can also set these values in your site configuration, it can lead to unwanted results unless all content authors are aware of, and understand, the settings.
+
+{{% note %}}
+As noted above, Hugo does not clear the `public` directory before building your site. Depending on the _current_ evaluation of the four conditions above, after the build your `public` directory may contain extraneous files from a previous build.
+
+A common practice is to manually clear the contents of the `public` directory before each build to remove draft, expired, and future content.
+{{% /note %}}
+
+## Develop and test your site
+
+To view your site while developing layouts or creating content, `cd` into your project directory and run:
+
+```sh
+hugo server
+```
+
+The [`hugo server`] command builds your site into memory, and serves your pages using a minimal HTTP server. When you run `hugo server` it will display the URL of your local site:
+
+```text
+Web Server is available at http://localhost:1313/
+```
+
+While the server is running, it watches your project directory for changes to assets, configuration, content, data, layouts, translations, and static files. When it detects a change, the server rebuilds your site and refreshes your browser using [LiveReload].
+
+Most Hugo builds are so fast that you may not notice the change unless you are looking directly at your browser.
+
+### LiveReload
+
+While the server is running, Hugo injects JavaScript into the generated HTML pages. The LiveReload script creates a connection from the browser to the server via web sockets. You do not need to install any software or browser plugins, nor is any configuration required.
+
+### Automatic redirection
+
+When editing content, if you want your browser to automatically redirect to the page you last modified, run:
+
+```sh
+hugo server --navigateToChanged
+```
+
+## Deploy your site
+
+{{% note %}}
+As noted above, Hugo does not clear the public directory before building your site. Manually clear the contents of the public directory before each build to remove draft, expired, and future content.
+{{% /note %}}
+
+When you are ready to deploy your site, run:
+
+```sh
+hugo
+```
+
+This builds your site, publishing the files to the public directory. The directory structure will look something like this:
+
+```text
+public/
+├── categories/
+│ ├── index.html
+│ └── index.xml <-- RSS feed for this section
++├── posts/
+│ ├── my-first-post/
+│ │ └── index.html
+│ ├── index.html
+│ └── index.xml <-- RSS feed for this section
+├── tags/
+│ ├── index.html
+│ └── index.xml <-- RSS feed for this section
+├── index.html
+├── index.xml <-- RSS feed for the site
+└── sitemap.xml
+```
+
+In a simple hosting environment, where you typically `ftp`, `rsync`, or `scp` your files to the root of a virtual host, the contents of the `public` directory are all that you need.
+
+Most of our users deploy their sites using a CI/CD workflow, where a push[^1] to their GitHub or GitLab repository triggers a build and deployment. Popular providers include [AWS Amplify], [CloudCannon], [Cloudflare Pages], [GitHub Pages], [GitLab Pages], and [Netlify].
+
+Learn more in the [hosting and deployment] section.
+
+[^1]: The Git repository contains the entire project directory, typically excluding the public directory because the site is built _after_ the push.
+
+[`--destination`]: /commands/hugo/#options
+[`hugo server`]: /commands/hugo_server/
+[`hugo`]: /commands/hugo/
+[`publishDir`]: /getting-started/configuration/#publishdir
+[AWS Amplify]: https://aws.amazon.com/amplify/
+[CloudCannon]: https://cloudcannon.com/
+[Cloudflare Pages]: https://pages.cloudflare.com/
+[commands]: /commands/
+[front matter]: /content-management/front-matter/
+[GitHub Pages]: https://pages.github.com/
+[GitLab Pages]: https://docs.gitlab.com/ee/user/project/pages/
+[hosting and deployment]: /hosting-and-deployment/
+[hosting]: /hosting-and-deployment/
+[installing]: /installation/
+[LiveReload]: https://github.com/livereload/livereload-js
+[Netlify]: https://www.netlify.com/
--- /dev/null
- linkTitle: Overview
+---
+title: Hosting and deployment
- identifier: hosting-and-deployment-overview
++linkTitle: In this section
+description: Site builds, automated deployments, and popular hosting solutions.
+categories: []
+keywords: []
+menu:
+ docs:
++ identifier: hosting-and-deployment-in-this-section
+ parent: hosting-and-deployment
+ weight: 1
+weight: 1
+---
+
+Because Hugo renders *static* websites, you can host your new Hugo website virtually anywhere. The following represent only a few of the more popular hosting and automated deployment solutions used by the Hugo community.
--- /dev/null
- description: Deploy Hugo as a GitHub Pages project or personal/organizational site and automate the whole process with GitHub Actions
+---
+title: Host on GitHub Pages
- keywords: [hosting,github]
++description: Host your site on GitHub Pages with continuous deployment using project, user, or organization pages.
+categories: [hosting and deployment]
- 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.
-
++keywords: [hosting]
+menu:
+ docs:
+ parent: hosting-and-deployment
+toc: true
+aliases: [/tutorials/github-pages-blog/]
+---
+
- HUGO_VERSION: 0.122.0
+## Prerequisites
+
+1. [Create a GitHub account]
+2. [Install Git]
+3. [Create a Hugo site] and test it locally with `hugo server`.
+
+[Create a GitHub account]: https://github.com/signup
+[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+[Create a Hugo site]: /getting-started/quick-start/
+
+## Types of sites
+
+There are three types of GitHub Pages sites: project, user, and organization. Project sites are connected to a specific project hosted on GitHub. User and organization sites are connected to a specific account on GitHub.com.
+
+{{% note %}}
+See the [GitHub Pages documentation] to understand the requirements for repository ownership and naming.
+
+[GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites
+{{% /note %}}
+
+[GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites
+
+## Procedure
+
+Step 1
+: Create a GitHub repository.
+
+Step 2
+: Push your local repository to GitHub.
+
+Step 3
+: Visit your GitHub repository. From the main menu choose **Settings** > **Pages**. In the center of your screen you will see this:
+
+
+{style="max-width: 280px"}
+
+Step 4
+: Change the **Source** to `GitHub Actions`. The change is immediate; you do not have to press a Save button.
+
+
+{style="max-width: 280px"}
+
+Step 5
+: Create an empty file in your local repository.
+
+```text
+.github/workflows/hugo.yaml
+```
+
+Step 6
+: Copy and paste the YAML below into the file you created. Change the branch name and Hugo version as needed.
+
+{{< code file=.github/workflows/hugo.yaml copy=true >}}
+# Sample workflow for building and deploying a Hugo site to GitHub Pages
+name: Deploy Hugo site to Pages
+
+on:
+ # Runs on pushes targeting the default branch
+ push:
+ branches:
+ - main
+
+ # Allows you to run this workflow manually from the Actions tab
+ workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+ contents: read
+ pages: write
+ id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+ group: "pages"
+ cancel-in-progress: false
+
+# Default to bash
+defaults:
+ run:
+ shell: bash
+
+jobs:
+ # Build job
+ build:
+ runs-on: ubuntu-latest
+ env:
- uses: actions/upload-pages-artifact@v2
++ HUGO_VERSION: 0.127.0
+ steps:
+ - name: Install Hugo CLI
+ run: |
+ wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
+ && sudo dpkg -i ${{ runner.temp }}/hugo.deb
+ - name: Install Dart Sass
+ run: sudo snap install dart-sass
+ - name: Checkout
+ uses: actions/checkout@v4
+ with:
+ submodules: recursive
+ fetch-depth: 0
+ - name: Setup Pages
+ id: pages
+ uses: actions/configure-pages@v4
+ - name: Install Node.js dependencies
+ run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
+ - name: Build with Hugo
+ env:
+ # 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/deploy-pages@v3
++ uses: actions/upload-pages-artifact@v3
+ with:
+ path: ./public
+
+ # Deployment job
+ deploy:
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ runs-on: ubuntu-latest
+ needs: build
+ steps:
+ - name: Deploy to GitHub Pages
+ id: deployment
++ uses: actions/deploy-pages@v4
+{{< /code >}}
+
+Step 7
+: Commit the change to your local repository with a commit message of something like "Add workflow", and push to GitHub.
+
+Step 8
+: From GitHub's main menu, choose **Actions**. You will see something like this:
+
+
+{style="max-width: 350px"}
+
+Step 9
+: When GitHub has finished building and deploying your site, the color of the status indicator will change to green.
+
+
+{style="max-width: 350px"}
+
+Step 10
+: Click on the commit message as shown above. You will see this:
+
+
+{style="max-width: 611px"}
+
+Under the deploy step, you will see a link to your live site.
+
+In the future, whenever you push a change from your local repository, GitHub will rebuild your site and deploy the changes.
+
+## Customize the workflow
+
+The example workflow above includes this step, which typically takes 10‑15 seconds:
+
+```yaml
+- name: Install Dart Sass
+ run: sudo snap install dart-sass
+```
+
+You may remove this step if your site, themes, and modules do not transpile Sass to CSS using the [Dart Sass] transpiler.
+
+[Dart Sass]: /hugo-pipes/transpile-sass-to-css/#dart-sass
+
+## Additional resources
+
+- [Learn more about GitHub Actions](https://docs.github.com/en/actions)
+- [Caching dependencies to speed up workflows](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows)
+- [Manage a custom domain for your GitHub Pages site](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages)
--- /dev/null
- DART_SASS_VERSION: 1.70.0
- HUGO_VERSION: 0.122.0
+---
+title: Host on GitLab Pages
+description: GitLab makes it easy to build, deploy, and host your Hugo website via their free GitLab Pages service, which provides native support for Hugo.
+categories: [hosting and deployment]
+keywords: [hosting,gitlab]
+menu:
+ docs:
+ parent: hosting-and-deployment
+toc: true
+aliases: [/tutorials/hosting-on-gitlab/]
+---
+
+## Assumptions
+
+* Working familiarity with Git for version control
+* Completion of the Hugo [Quick Start]
+* A [GitLab account](https://gitlab.com/users/sign_in)
+* A Hugo website on your local machine that you are ready to publish
+
+## BaseURL
+
+The `baseURL` in your [site configuration](/getting-started/configuration/) must reflect the full URL of your GitLab pages repository if you are using the default GitLab Pages URL (e.g., `https://<YourUsername>.gitlab.io/<your-hugo-site>/`) and not a custom domain.
+
+## Configure GitLab CI/CD
+
+Define your [CI/CD](https://docs.gitlab.com/ee/ci/quick_start/) jobs by creating a `.gitlab-ci.yml` file in the root of your project.
+
+{{< code file=.gitlab-ci.yml copy=true >}}
+variables:
- name: golang:1.20.6-bookworm
++ DART_SASS_VERSION: 1.77.1
++ HUGO_VERSION: 0.126.0
+ NODE_VERSION: 20.x
+ GIT_DEPTH: 0
+ GIT_STRATEGY: clone
+ GIT_SUBMODULE_STRATEGY: recursive
+ TZ: America/Los_Angeles
+
+image:
++ name: golang:1.22.1-bookworm
+
+pages:
+ script:
+ # Install brotli
+ - apt-get update
+ - apt-get install -y brotli
+ # Install Dart Sass
+ - 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
+ - cp -r dart-sass/ /usr/local/bin
+ - rm -rf dart-sass*
+ - export PATH=/usr/local/bin/dart-sass:$PATH
+ # Install Hugo
+ - curl -LJO https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
+ - apt-get install -y ./hugo_extended_${HUGO_VERSION}_linux-amd64.deb
+ - rm hugo_extended_${HUGO_VERSION}_linux-amd64.deb
+ # Install Node.js
+ - curl -fsSL https://deb.nodesource.com/setup_${NODE_VERSION} | bash -
+ - apt-get install -y nodejs
+ # Install Node.js dependencies
+ - "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
+ # Build
+ - hugo --gc --minify
+ # Compress
+ - find public -type f -regex '.*\.\(css\|html\|js\|txt\|xml\)$' -exec gzip -f -k {} \;
+ - find public -type f -regex '.*\.\(css\|html\|js\|txt\|xml\)$' -exec brotli -f -k {} \;
+ artifacts:
+ paths:
+ - public
+ rules:
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+{{% /code %}}
+
+## Push your Hugo website to GitLab
+
+Next, create a new repository on GitLab. It is *not* necessary to make the repository public. In addition, you might want to add `/public` to your .gitignore file, as there is no need to push compiled assets to GitLab or keep your output website in version control.
+
+```sh
+# initialize new git repository
+git init
+
+# add /public directory to our .gitignore file
+echo "/public" >> .gitignore
+
+# commit and push code to master branch
+git add .
+git commit -m "Initial commit"
+git remote add origin https://gitlab.com/YourUsername/your-hugo-site.git
+git push -u origin master
+```
+
+## Wait for your page to build
+
+That's it! You can now follow the CI agent building your page at `https://gitlab.com/<YourUsername>/<your-hugo-site>/pipelines`.
+
+After the build has passed, your new website is available at `https://<YourUsername>.gitlab.io/<your-hugo-site>/`.
+
+## Next steps
+
+GitLab supports using custom CNAME's and TLS certificates. For more details on GitLab Pages, see the [GitLab Pages setup documentation](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/).
+
+[Quick Start]: /getting-started/quick-start/
--- /dev/null
--- /dev/null
++---
++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 >}}
--- /dev/null
- linkTitle: Overview
+---
+title: Hugo Modules
- identifier: hugo-modules-overview
++linkTitle: In this section
+description: How to use Hugo Modules.
+categories: []
+keywords: []
+menu:
+ docs:
- - [https://github.com/golang/go/wiki/Modules](https://github.com/golang/go/wiki/Modules)
++ identifier: hugo-modules-in-this-section
+ parent: modules
+ weight: 10
+weight: 10
+toc: true
+aliases: [/themes/overview/,/themes/]
+---
+
+**Hugo Modules** are the core building blocks in Hugo. A _module_ can be your main project or a smaller module providing one or more of the 7 component types defined in Hugo: **static**, **content**, **layouts**, **data**, **assets**, **i18n**, and **archetypes**.
+
+You can combine modules in any combination you like, and even mount directories from non-Hugo projects, forming a big, virtual union file system.
+
+Hugo Modules are powered by Go Modules. For more information about Go Modules, see:
+
++- [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:
+
+- [https://github.com/bep/docuapi](https://github.com/bep/docuapi) is a theme that has been ported to Hugo Modules while testing this feature. It is a good example of a non-Hugo-project mounted into Hugo’s folder structure. It even shows a JS Bundler implementation in regular Go templates.
+- [https://github.com/bep/my-modular-site](https://github.com/bep/my-modular-site) is a very simple site used for testing.
--- /dev/null
- : 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.
+---
+title: Configure Hugo modules
+description: This page describes the configuration options for a module.
+categories: [hugo modules]
+keywords: [modules,themes]
+menu:
+ docs:
+ parent: modules
+ weight: 20
+weight: 20
+toc: true
+---
+
+## Module configuration: top level
+
+{{< code-toggle file=hugo >}}
+[module]
+noProxy = 'none'
+noVendor = ''
+private = '*.*'
+proxy = 'direct'
+replacements = ''
+vendorClosest = false
+workspace = 'off'
+{{< /code-toggle >}}
+
+noProxy
+: Comma separated glob list matching paths that should not use the proxy configured above.
+
+noVendor
+: A optional Glob pattern matching module paths to skip when vendoring, e.g. "github.com/**"
+
+private
+: Comma separated glob list matching paths that should be treated as private.
+
+proxy
+: Defines the proxy server to use to download remote modules. Default is `direct`, which means "git clone" and similar.
+
+vendorClosest
+: When enabled, we will pick the vendored module closest to the module using it. The default behavior is to pick the first. Note that there can still be only one dependency of a given module path, so once it is in use it cannot be redefined.
+
+workspace
+: The workspace file to use. This enables Go workspace mode. Note that this can also be set via OS env, e.g. `export HUGO_MODULE_WORKSPACE=/my/hugo.work` This only works with Go 1.18+. In Hugo `v0.109.0` we changed the default to `off` and we now resolve any relative work file names relative to the working directory.
+
+replacements
+: A comma-separated list of mappings from module paths to directories, e.g. `github.com/bep/my-theme -> ../..,github.com/bep/shortcodes -> /some/path`. This is mostly useful for temporary local development of a module, in which case you might want to save it as an environment variable, e.g: `env HUGO_MODULE_REPLACEMENTS="github.com/bep/my-theme -> ../.."`. Relative paths are relative to [themesDir](/getting-started/configuration/#all-configuration-settings). Absolute paths are allowed.
+
+Note that the above terms maps directly to their counterparts in Go Modules. Some of these setting may be natural to set as OS environment variables. To set the proxy server to use, as an example:
+
+```txt
+env HUGO_MODULE_PROXY=https://proxy.example.org hugo
+```
+
+{{< gomodules-info >}}
+
+## Module configuration: hugoVersion
+
+If your module requires a particular version of Hugo to work, you can indicate that in the `module` section and the user will be warned if using a too old/new version.
+
+{{< code-toggle file=hugo >}}
+[module]
+[module.hugoVersion]
+ min = ""
+ max = ""
+ extended = false
+
+{{< /code-toggle >}}
+
+Any of the above can be omitted.
+
+min
+: The minimum Hugo version supported, e.g. `0.55.0`
+
+max
+: The maximum Hugo version supported, e.g. `0.55.0`
+
+extended
+: Whether the extended version of Hugo is required.
+
+## Module configuration: imports
+
+{{< code-toggle file=hugo >}}
+[module]
+[[module.imports]]
+ path = "github.com/gohugoio/hugoTestModules1_linux/modh1_2_1v"
+ ignoreConfig = false
+ ignoreImports = false
+ disable = false
+[[module.imports]]
+ path = "my-shortcodes"
+{{< /code-toggle >}}
+
+path
+: Can be either a valid Go Module module path, e.g. `github.com/gohugoio/myShortcodes`, or the directory name for the module as stored in your themes folder.
+
+ignoreConfig
+: If enabled, any module configuration file, e.g. `hugo.toml`, will not be loaded. Note that this will also stop the loading of any transitive module dependencies.
+
+ignoreImports
+: If enabled, module imports will not be followed.
+
+disable
+: Set to `true` to disable the module while keeping any version info in the `go.*` files.
+
+noMounts
+: Do not mount any folder in this import.
+
+noVendor
+: Never vendor this import (only allowed in main project).
+
+{{< gomodules-info >}}
+
+## Module configuration: mounts
+
+{{% note %}}
+When the `mounts` configuration was introduced in Hugo 0.56.0, we were careful to preserve the existing `contentDir`, `staticDir`, and similar configuration to make sure all existing sites just continued to work. But you should not have both: if you add a `mounts` section you should remove the old `contentDir`, `staticDir`, etc. settings.
+{{% /note %}}
+
+{{% note %}}
+When you add a mount, the default mount for the concerned target root is ignored: be sure to explicitly add it.
+{{% /note %}}
+
+**Default mounts**
+{{< code-toggle file=hugo >}}
+[module]
+[[module.mounts]]
+ source="content"
+ target="content"
+[[module.mounts]]
+ source="static"
+ target="static"
+[[module.mounts]]
+ source="layouts"
+ target="layouts"
+[[module.mounts]]
+ source="data"
+ target="data"
+[[module.mounts]]
+ source="assets"
+ target="assets"
+[[module.mounts]]
+ source="i18n"
+ target="i18n"
+[[module.mounts]]
+ source="archetypes"
+ target="archetypes"
+{{< /code-toggle >}}
+
+source
++: 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`.
+
+lang
+: The language code, e.g. "en". Only relevant for `content` mounts, and `static` mounts when in multihost mode.
+
+includeFiles (string or slice)
+: One or more [glob](https://github.com/gobwas/glob) patterns matching files or directories to include. If `excludeFiles` is not set, the files matching `includeFiles` will be the files mounted.
+
+The glob patterns are matched to the file names starting from the `source` root, they should have Unix styled slashes even on Windows, `/` matches the mount root and `**` can be used as a super-asterisk to match recursively down all directories, e.g `/posts/**.jpg`.
+
+The search is case-insensitive.
+
+excludeFiles (string or slice)
+: One or more glob patterns matching files to exclude.
+
+**Example**
+{{< code-toggle file=hugo >}}
+[module]
+[[module.mounts]]
+ source="content"
+ target="content"
+ excludeFiles="docs/*"
+[[module.mounts]]
+ source="node_modules"
+ target="assets"
+[[module.mounts]]
+ source="assets"
+ target="assets"
+{{< /code-toggle >}}
--- /dev/null
- hugo mod init github.com/gohugoio/myShortcodes
+---
+title: Use Hugo Modules
+description: How to use Hugo Modules to build and manage your site.
+categories: [hugo modules]
+keywords: [modules,themes]
+menu:
+ docs:
+ parent: modules
+ weight: 30
+weight: 30
+aliases: [/themes/usage/,/themes/installing/,/installing-and-using-themes/]
+toc: true
+---
+
+## Prerequisite
+
+{{< gomodules-info >}}
+
+## Initialize a new module
+
+Use `hugo mod init` to initialize a new Hugo Module. If it fails to guess the module path, you must provide it as an argument, e.g.:
+
+```sh
++hugo mod init github.com/<your_user>/<your_project>
+```
+
+Also see the [CLI Doc](/commands/hugo_mod_init/).
+
+## Use a module for a theme
+
+The easiest way to use a Module for a theme is to import it in the configuration.
+
+1. Initialize the hugo module system: `hugo mod init github.com/<your_user>/<your_project>`
+2. Import the theme:
+
+{{< code-toggle file=hugo >}}
+[module]
+ [[module.imports]]
+ path = "github.com/spf13/hyde"
+{{< /code-toggle >}}
+
+## Update modules
+
+Modules will be downloaded and added when you add them as imports to your configuration, see [Module Imports](/hugo-modules/configuration/#module-configuration-imports).
+
+To update or manage versions, you can use `hugo mod get`.
+
+Some examples:
+
+### Update all modules
+
+```sh
+hugo mod get -u
+```
+
+### Update all modules recursively
+
+```sh
+hugo mod get -u ./...
+```
+
+### Update one module
+
+```sh
+hugo mod get -u github.com/gohugoio/myShortcodes
+```
+
+### Get a specific version
+
+```sh
+hugo mod get github.com/gohugoio/myShortcodes@v1.0.7
+```
+
+Also see the [CLI Doc](/commands/hugo_mod_get/).
+
+## Make and test changes in a module
+
+One way to do local development of a module imported in a project is to add a replace directive to a local directory with the source in `go.mod`:
+
+```sh
+replace github.com/bep/hugotestmods/mypartials => /Users/bep/hugotestmods/mypartials
+```
+
+If you have the `hugo server` running, the configuration will be reloaded and `/Users/bep/hugotestmods/mypartials` put on the watch list.
+
+Instead of modifying the `go.mod` files, you can also use the modules configuration [`replacements`](/hugo-modules/configuration/#module-configuration-top-level) option.
+
+## Print dependency graph
+
+Use `hugo mod graph` from the relevant module directory and it will print the dependency graph, including vendoring, module replacement or disabled status.
+
+E.g.:
+
+```txt
+hugo mod graph
+
+github.com/bep/my-modular-site github.com/bep/hugotestmods/mymounts@v1.2.0
+github.com/bep/my-modular-site github.com/bep/hugotestmods/mypartials@v1.0.7
+github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myassets@v1.0.4
+github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myv2@v1.0.0
+DISABLED github.com/bep/my-modular-site github.com/spf13/hyde@v0.0.0-20190427180251-e36f5799b396
+github.com/bep/my-modular-site github.com/bep/hugo-fresh@v1.0.1
+github.com/bep/my-modular-site in-themesdir
+```
+
+Also see the [CLI Doc](/commands/hugo_mod_graph/).
+
+## Vendor your modules
+
+`hugo mod vendor` will write all the module dependencies to a `_vendor` folder, which will then be used for all subsequent builds.
+
+Note that:
+
+* You can run `hugo mod vendor` on any level in the module tree.
+* Vendoring will not store modules stored in your `themes` folder.
+* Most commands accept a `--ignoreVendorPaths` flag, which will then not use the vendored modules in `_vendor` for the module paths matching the [Glob](https://github.com/gobwas/glob) pattern given.
+
+Also see the [CLI Doc](/commands/hugo_mod_vendor/).
+
+## Tidy go.mod, go.sum
+
+Run `hugo mod tidy` to remove unused entries in `go.mod` and `go.sum`.
+
+Also see the [CLI Doc](/commands/hugo_mod_clean/).
+
+## Clean module cache
+
+Run `hugo mod clean` to delete the entire modules cache.
+
+Note that you can also configure the `modules` cache with a `maxAge`, see [File Caches](/getting-started/configuration/#configure-file-caches).
+
+Also see the [CLI Doc](/commands/hugo_mod_clean/).
+
+## Module workspaces
+
+{{< new-in 0.109.0 >}}
+
+Workspace support was added in [Go 1.18](https://go.dev/blog/get-familiar-with-workspaces) and Hugo got solid support for it in the `v0.109.0` version.
+
+A common use case for a workspace is to simplify local development of a site with its theme modules.
+
+A workspace can be configured in a `*.work` file and activated with the [module.workspace](/hugo-modules/configuration/) setting, which for this use is commonly controlled via the `HUGO_MODULE_WORKSPACE` OS environment variable.
+
+See the [hugo.work](https://github.com/gohugoio/hugo/blob/master/docs/hugo.work) file in the Hugo Docs repo for an example:
+
+```text
+go 1.20
+
+use .
+use ../gohugoioTheme
+```
+
+Using the `use` directive, list all the modules you want to work on, pointing to its relative location. As in the example above, it's recommended to always include the main project (the ".") in the list.
+
+With that you can start the Hugo server with that workspace enabled:
+
+```sh
+HUGO_MODULE_WORKSPACE=hugo.work hugo server --ignoreVendorPaths "**"
+```
+
+The `--ignoreVendorPaths` flag is added above to ignore any of the vendored dependencies inside `_vendor`. If you don't use vendoring, you don't need that flag. But now the server is set up watching the files and directories in the workspace and you can see your local edits reloaded.
--- /dev/null
- linkTitle: Overview
+---
+title: Hugo Pipes
- identifier: hugo-pipes-overview
++linkTitle: In this section
+categories: []
+keywords: []
+menu:
+ docs:
++ identifier: hugo-pipes-in-this-section
+ parent: hugo-pipes
+ weight: 10
+weight: 10
+---
--- /dev/null
- 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.
+---
+title: js.Build
+linkTitle: JavaScript building
+description: Bundle, transpile, tree shake, and minify JavaScript resources.
+categories: [asset management]
+keywords: []
+menu:
+ docs:
+ parent: hugo-pipes
+ weight: 60
+weight: 60
+action:
+ aliases: []
+ returnType: resource.Resource
+ signatures: ['js.Build [OPTIONS] RESOURCE']
+---
+
+## Usage
+
- params {{< new-in "0.96.0" >}}
++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
+
+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
+: (`map` or `slice`) Params that can be imported as JSON in your JS files, e.g.:
+
+```go-html-template
+{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }}
+```
+And then in your JS file:
+
+```js
+import * as params from '@params';
+```
+
+Note that this is meant for small data sets, e.g. configuration settings. For larger data, please put/mount the files into `/assets` and import them directly.
+
+minify
+: (`bool`) Let `js.Build` handle the minification.
+
+inject
+: (`slice`) This option allows you to automatically replace a global variable with an import from another file. The path names must be relative to `assets`. See https://esbuild.github.io/api/#inject
+
+shims
+: (`map`) This option allows swapping out a component with another. A common use case is to load dependencies like React from a CDN (with _shims_) when in production, but running with the full bundled `node_modules` dependency during development:
+
+```go-html-template
+{{ $shims := dict "react" "js/shims/react.js" "react-dom" "js/shims/react-dom.js" }}
+{{ $js = $js | js.Build dict "shims" $shims }}
+```
+
+The _shim_ files may look like these:
+
+```js
+// js/shims/react.js
+module.exports = window.React;
+```
+
+```js
+// js/shims/react-dom.js
+module.exports = window.ReactDOM;
+```
+
+With the above, these imports should work in both scenarios:
+
+```js
+import * as React from 'react'
+import * as ReactDOM from 'react-dom';
+```
+
+target
+: (`string`) The language target.
+ One of: `es5`, `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020` or `esnext`.
+ Default is `esnext`.
+
+externals
+: (`slice`) External dependencies. Use this to trim dependencies you know will never be executed. See https://esbuild.github.io/api/#external
+
+defines
+: (`map`) Allow to define a set of string replacement to be performed when building. Should be a map where each key is to be replaced by its value.
+
+```go-html-template
+{{ $defines := dict "process.env.NODE_ENV" `"development"` }}
+```
+
+format
+: (`string`) The output format.
+ One of: `iife`, `cjs`, `esm`.
+ Default is `iife`, a self-executing function, suitable for inclusion as a `<script>` tag.
+
+sourceMap
+: (`string`) Whether to generate `inline` or `external` source maps from esbuild. External source maps will be written to the target with the output file name + ".map". Input source maps can be read from js.Build and node modules and combined into the output source maps. By default, source maps are not created.
+
+JSX {{< new-in 0.124.0 >}}
+: (`string`) How to handle/transform JSX syntax. One of: `transform`, `preserve`, `automatic`. Default is `transform`. Notably, the `automatic` transform was introduced in React 17+ and will cause the necessary JSX helper functions to be imported automatically. See https://esbuild.github.io/api/#jsx
+
+JSXImportSource {{< new-in 0.124.0 >}}
+: (`string`) Which library to use to automatically import its JSX helper functions from. This only works if `JSX` is set to `automatic`. The specified library needs to be installed through NPM and expose certain exports. See https://esbuild.github.io/api/#jsx-import-source
+
+The combination of `JSX` and `JSXImportSource` is helpful if you want to use a non-React JSX library like Preact, e.g.:
+
+```go-html-template
+{{ $js := resources.Get "js/main.jsx" | js.Build (dict "JSX" "automatic" "JSXImportSource" "preact") }}
+```
+
+With the above, you can use Preact components and JSX without having to manually import `h` and `Fragment` every time:
+
+```jsx
+import { render } from 'preact';
+
+const App = () => <>Hello world!</>;
+
+const container = document.getElementById('app');
+if (container) render(<App />, container);
+```
+
+### Import JS code from /assets
+
+`js.Build` has full support for the virtual union file system in [Hugo Modules](/hugo-modules/). You can see some simple examples in this [test project](https://github.com/gohugoio/hugoTestProjectJSModImports), but in short this means that you can do this:
+
+```js
+import { hello } from 'my/module';
+```
+
+And it will resolve to the top-most `index.{js,ts,tsx,jsx}` inside `assets/my/module` in the layered file system.
+
+```js
+import { hello3 } from 'my/module/hello3';
+```
+
+Will resolve to `hello3.{js,ts,tsx,jsx}` inside `assets/my/module`.
+
+Any imports starting with `.` is resolved relative to the current file:
+
+```js
+import { hello4 } from './lib';
+```
+
+For other files (e.g. `JSON`, `CSS`) you need to use the relative path including any extension, e.g:
+
+```js
+import * as data from 'my/module/data.json';
+```
+
+Any imports in a file outside `/assets` or that does not resolve to a component inside `/assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`.
+
+Also note the new `params` option that can be passed from template to your JS files, e.g.:
+
+```go-html-template
+{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }}
+```
+And then in your JS file:
+
+```js
+import * as params from '@params';
+```
+
+Hugo will, by default, generate a `assets/jsconfig.json` file that maps the imports. This is useful for navigation/intellisense help inside code editors, but if you don't need/want it, you can [turn it off](/getting-started/configuration/#configure-build).
+
+### Include dependencies In package.json / node_modules
+
+Any imports in a file outside `/assets` or that does not resolve to a component inside `/assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`.
+
+The start directory for resolving npm packages (aka. packages that live inside a `node_modules` folder) is always the main project folder.
+
+{{% note %}}
+If you're developing a theme/component that is supposed to be imported and depends on dependencies inside `package.json`, we recommend reading about [hugo mod npm pack](/commands/hugo_mod_npm_pack/), a tool to consolidate all the npm dependencies in a project.
+{{% /note %}}
+
+### Examples
+
+```go-html-template
+{{ $built := resources.Get "js/index.js" | js.Build "main.js" }}
+```
+
+Or with options:
+
+```go-html-template
+{{ $externals := slice "react" "react-dom" }}
+{{ $defines := dict "process.env.NODE_ENV" `"development"` }}
+
+{{ $opts := dict "targetPath" "main.js" "externals" $externals "defines" $defines }}
+{{ $built := resources.Get "scripts/main.js" | js.Build $opts }}
+<script src="{{ $built.RelPermalink }}" defer></script>
+```
--- /dev/null
- : (`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/).
+---
+title: ToCSS
+linkTitle: Transpile Sass to CSS
+description: Transpile Sass to CSS.
+categories: [asset management]
+keywords: []
+menu:
+ docs:
+ parent: hugo-pipes
+ returnType: resource.Resource
+ weight: 30
+weight: 30
+action:
+ aliases: [toCSS]
+ returnType: resource.Resource
+ signatures: ['resources.ToCSS [OPTIONS] RESOURCE']
+toc: true
+aliases: [/hugo-pipes/transform-to-css/]
+---
+
+## Usage
+
+Transpile Sass to CSS using the LibSass transpiler included in Hugo's extended edition, or [install Dart Sass](#dart-sass) to use the latest features of the Sass language.
+
+```go-html-template
+{{ $opts := dict "transpiler" "libsass" "targetPath" "css/style.css" }}
+{{ with resources.Get "sass/main.scss" | toCSS $opts | minify | fingerprint }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+{{ end }}
+```
+
+Sass has two forms of syntax: [SCSS] and [indented]. Hugo supports both.
+
+[scss]: https://sass-lang.com/documentation/syntax#scss
+[indented]: https://sass-lang.com/documentation/syntax#the-indented-syntax
+
+## Options
+
+transpiler
+: (`string`) The transpiler to use, either `libsass` (default) or `dartsass`. Hugo's extended edition includes the LibSass transpiler. To use the Dart Sass transpiler, see the [installation instructions](#dart-sass) below.
+
+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 >}}
- HUGO_VERSION: 0.122.0
- DART_SASS_VERSION: 1.70.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/).
+
+```scss
+// LibSass
+@import "hugo:vars";
+
+// Dart Sass
+@use "hugo:vars" as v;
+```
+
+outputStyle
+: (`string`) Output styles available to LibSass include `nested` (default), `expanded`, `compact`, and `compressed`. Output styles available to Dart Sass include `expanded` (default) and `compressed`.
+
+precision
+: (`int`) Precision of floating point math. Not applicable to Dart Sass.
+
+enableSourceMap
+: (`bool`) If `true`, generates a source map.
+
+sourceMapIncludeSources {{< new-in 0.108.0 >}}
+: (`bool`) If `true`, embeds sources in the generated source map. Not applicable to LibSass.
+
+includePaths
+: (`slice`) A slice of paths, relative to the project root, that the transpiler will use when resolving `@use` and `@import` statements.
+
+```go-html-template
+{{ $opts := dict
+ "transpiler" "dartsass"
+ "targetPath" "css/style.css"
+ "vars" site.Params.styles
+ "enableSourceMap" (not hugo.IsProduction)
+ "includePaths" (slice "node_modules/bootstrap/scss")
+}}
+{{ with resources.Get "sass/main.scss" | toCSS $opts | minify | fingerprint }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+{{ end }}
+```
+
+## Dart Sass
+
+The extended version of Hugo includes [LibSass] to transpile Sass to CSS. In 2020, the Sass team deprecated LibSass in favor of [Dart Sass].
+
+Use the latest features of the Sass language by installing Dart Sass in your development and production environments.
+
+### Installation overview
+
+Dart Sass is compatible with Hugo v0.114.0 and later.
+
+If you have been using Embedded Dart Sass[^1] with Hugo v0.113.0 and earlier, uninstall Embedded Dart Sass, then install Dart Sass. If you have installed both, Hugo will use Dart Sass.
+
+If you install Hugo as a [Snap package] there is no need to install Dart Sass. The Hugo Snap package includes Dart Sass.
+
+[^1]: In 2023, the Sass team deprecated Embedded Dart Sass in favor of Dart Sass.
+
+### Installing in a development environment
+
+When you install Dart Sass somewhere in your PATH, Hugo will find it.
+
+OS|Package manager|Site|Installation
+:--|:--|:--|:--
+Linux|Homebrew|[brew.sh]|`brew install sass/sass/sass`
+Linux|Snap|[snapcraft.io]|`sudo snap install dart-sass`
+macOS|Homebrew|[brew.sh]|`brew install sass/sass/sass`
+Windows|Chocolatey|[chocolatey.org]|`choco install sass`
+Windows|Scoop|[scoop.sh]|`scoop install sass`
+
+You may also install [prebuilt binaries] for Linux, macOS, and Windows.
+
+Run `hugo env` to list the active transpilers.
+
+### Installing in a production environment
+
+For [CI/CD] deployments (e.g., GitHub Pages, GitLab Pages, Netlify, etc.) you must edit the workflow to install Dart Sass before Hugo builds the site[^2]. Some providers allow you to use one of the package managers above, or you can download and extract one of the prebuilt binaries.
+
+[^2]: You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set `useResourceCacheWhen` to `never` in your [site configuration], and (c) you add and commit your resources directory to your repository.
+
+#### GitHub Pages
+
+To install Dart Sass for your builds on GitHub Pages, add this step to the GitHub Pages workflow file:
+
+```yaml
+- name: Install Dart Sass
+ run: sudo snap install dart-sass
+```
+
+If you are using GitHub Pages for the first time with your repository, GitHub provides a [starter workflow] for Hugo that includes Dart Sass. This is the simplest way to get started.
+
+#### GitLab Pages
+
+To install Dart Sass for your builds on GitLab Pages, the `.gitlab-ci.yml` file should look something like this:
+
+```yaml
+variables:
- 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
+ TZ: America/Los_Angeles
+image:
+ name: golang:1.20-buster
+pages:
+ script:
+ # Install Dart Sass
+ - 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
+ - cp -r dart-sass/* /usr/local/bin
+ - rm -rf dart-sass*
+ # Install Hugo
+ - curl -LJO https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
+ - apt install -y ./hugo_extended_${HUGO_VERSION}_linux-amd64.deb
+ - rm hugo_extended_${HUGO_VERSION}_linux-amd64.deb
+ # Build
+ - hugo --gc --minify
+ artifacts:
+ paths:
+ - public
+ rules:
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+```
+
+#### Netlify
+
+To install Dart Sass for your builds on Netlify, the `netlify.toml` file should look something like this:
+
+```toml
+[build.environment]
+HUGO_VERSION = "0.122.2"
++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 \
+ """
+```
+
+### Example
+
+To transpile with Dart Sass, set `transpiler` to `dartsass` in the options map passed to `resources.ToCSS`. For example:
+
+```go-html-template
+{{ $opts := dict "transpiler" "dartsass" "targetPath" "css/style.css" }}
+{{ with resources.Get "sass/main.scss" | toCSS $opts | minify | fingerprint }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+{{ end }}
+```
+
+### Miscellaneous
+
+If you build Hugo from source and run `mage test -v`, the test will fail if you install Dart Sass as a Snap package. This is due to the Snap package's strict confinement model.
+
+[brew.sh]: https://brew.sh/
+[chocolatey.org]: https://community.chocolatey.org/packages/sass
+[ci/cd]: https://en.wikipedia.org/wiki/CI/CD
+[dart sass]: https://sass-lang.com/dart-sass
+[libsass]: https://sass-lang.com/libsass
+[prebuilt binaries]: https://github.com/sass/dart-sass/releases/latest
+[scoop.sh]: https://scoop.sh/#/apps?q=sass
+[site configuration]: /getting-started/configuration/#configure-build
+[snap package]: /installation/linux/#snap
+[snapcraft.io]: https://snapcraft.io/dart-sass
+[starter workflow]: https://github.com/actions/starter-workflows/blob/main/pages/hugo.yml
--- /dev/null
- [commit information]: /variables/git
+---
+# Do not remove front matter.
+---
+
+## Prebuilt binaries
+
+Prebuilt binaries are available for a variety of operating systems and architectures. Visit the [latest release] page, and scroll down to the Assets section.
+
+1. Download the archive for the desired edition, operating system, and architecture
+1. Extract the archive
+1. Move the executable to the desired directory
+1. Add this directory to the PATH environment variable
+1. Verify that you have _execute_ permission on the file
+
+Please consult your operating system documentation if you need help setting file permissions or modifying your PATH environment variable.
+
+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]: /methods/page/gitinfo/
+[Git]: https://git-scm.com/
+[Go]: https://go.dev/
+[Hugo Modules]: /hugo-modules/
+[latest release]: https://github.com/gohugoio/hugo/releases/latest
--- /dev/null
- Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+---
+cascade:
+ _build:
+ list: never
+ publishResources: false
+ render: never
+---
+
+<!--
++Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+
+Include the rendered content using the "include" shortcode.
+-->
--- /dev/null
- linkTitle: Overview
+---
+title: Installation
- identifier: installation-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-in-this-section
+ parent: installation
+ weight: 10
+weight: 10
+---
+
+Install Hugo on macOS, Linux, Windows, BSD, and on any machine that can run the Go compiler tool chain.
--- /dev/null
- Derivatives of the [Gentoo] distribution of Linux include [Calculate Linux], [Funtoo], and others. Follow the instructions below to install the extended edition of Hugo:
+---
+title: Linux
+description: Install Hugo on Linux.
+categories: [installation]
+keywords: []
+menu:
+ docs:
+ parent: installation
+ weight: 30
+weight: 30
+toc: true
+---
+{{% include "installation/_common/01-editions.md" %}}
+
+{{% include "installation/_common/02-prerequisites.md" %}}
+
+{{% include "installation/_common/03-prebuilt-binaries.md" %}}
+
+## Package managers
+
+### Snap
+
+[Snap] is a free and open-source package manager for Linux. Available for [most distributions], snap packages are simple to install and are automatically updated.
+
+The Hugo snap package is [strictly confined]. Strictly confined snaps run in complete isolation, up to a minimal access level that’s deemed always safe. The sites you create and build must be located within your home directory, or on removable media.
+
+To install the extended edition of Hugo:
+
+```sh
+sudo snap install hugo
+```
+
+To enable or revoke access to removable media:
+
+```sh
+sudo snap connect hugo:removable-media
+sudo snap disconnect hugo:removable-media
+```
+
+To enable or revoke access to SSH keys:
+
+```sh
+sudo snap connect hugo:ssh-keys
+sudo snap disconnect hugo:ssh-keys
+```
+
+[most distributions]: https://snapcraft.io/docs/installing-snapd
+[strictly confined]: https://snapcraft.io/docs/snap-confinement
+[Snap]: https://snapcraft.io/
+
+{{% include "installation/_common/homebrew.md" %}}
+
+## Repository packages
+
+Most Linux distributions maintain a repository for commonly installed applications.
+
+{{% note %}}
+The Hugo version available in package repositories varies based on Linux distribution and release, and in some cases will not be the [latest version].
+
+Use one of the other installation methods if your package repository does not provide the desired version.
+
+[latest version]: https://github.com/gohugoio/hugo/releases/latest
+{{% /note %}}
+
+### Alpine Linux
+
+To install the extended edition of Hugo on [Alpine Linux]:
+
+```sh
+doas apk add --no-cache --repository=https://dl-cdn.alpinelinux.org/alpine/edge/community hugo
+```
+
+[Alpine Linux]: https://alpinelinux.org/
+
+### Arch Linux
+
+Derivatives of the [Arch Linux] distribution of Linux include [EndeavourOS], [Garuda Linux], [Manjaro], and others. To install the extended edition of Hugo:
+
+```sh
+sudo pacman -S hugo
+```
+
+[Arch Linux]: https://archlinux.org/
+[EndeavourOS]: https://endeavouros.com/
+[Manjaro]: https://manjaro.org/
+[Garuda Linux]: https://garudalinux.org/
+
+### Debian
+
+Derivatives of the [Debian] distribution of Linux include [elementary OS], [KDE neon], [Linux Lite], [Linux Mint], [MX Linux], [Pop!_OS], [Ubuntu], [Zorin OS], and others. To install the extended edition of Hugo:
+
+```sh
+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/
+[Linux Mint]: https://linuxmint.com/
+[MX Linux]: https://mxlinux.org/
+[Pop!_OS]: https://pop.system76.com/
+[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:
+
+```sh
+sudo dnf install hugo
+```
+
+[CentOS]: https://www.centos.org/
+[Fedora]: https://getfedora.org/
+[Red Hat Enterprise Linux]: https://www.redhat.com/
+
+### Gentoo
+
++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:
+
+ ```text
+ www-apps/hugo extended
+ ```
+
+2. Build using the Portage package manager:
+
+ ```sh
+ sudo emerge www-apps/hugo
+ ```
+
+[Calculate Linux]: https://www.calculate-linux.org/
+[Funtoo]: https://www.funtoo.org/
+[Gentoo]: https://www.gentoo.org/
+[USE]: https://packages.gentoo.org/packages/www-apps/hugo
+
+### openSUSE
+
+Derivatives of the [openSUSE] distribution of Linux include [GeckoLinux], [Linux Karmada], and others. To install the extended edition of Hugo:
+
+```sh
+sudo zypper install hugo
+```
+
+[GeckoLinux]: https://geckolinux.github.io/
+[Linux Karmada]: https://linuxkamarada.com/
+[openSUSE]: https://www.opensuse.org/
+
+### Solus
+
+The [Solus] distribution of Linux includes Hugo in its package repository. To install the extended edition of Hugo:
+
+```sh
+sudo eopkg install hugo
+```
+
+[Solus]: https://getsol.us/
+
+{{% include "installation/_common/04-build-from-source.md" %}}
+
+## Comparison
+
+||Prebuilt binaries|Package managers|Repository packages|Build from source
+:--|:--:|:--:|:--:|:--:
+Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark:
+Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^1]|varies|:heavy_check_mark:
+Automatic updates?|:x:|varies [^2]|:x:|:x:
+Latest version available?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark:
+
+[^1]: Easy if a previous version is still installed.
+[^2]: Snap packages are automatically updated. Homebrew requires advanced configuration.
--- /dev/null
- Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+---
+cascade:
+ _build:
+ list: never
+ publishResources: false
+ render: never
+---
+
+<!--
++Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+
+Include the rendered content using the "include" shortcode.
+-->
--- /dev/null
- [`PAGES.Next`]: /methods/pages/next
- [`PAGES.Prev`]: /methods/pages/prev
- [`PAGE.Next`]: /methods/page/next
- [`PAGE.Prev`]: /methods/page/prev
+---
+# Do not remove front matter.
+---
+
+The `Next` and `Prev` methods on a `Pages` object are more flexible than the `Next` and `Prev` methods on a `Page` object.
+
+||Page collection|Custom sort order
+:--|:--|:-:
+[`PAGES.Next`] and [`PAGES.Prev`]|locally defined|✔️
+[`PAGE.Next`] and [`PAGE.Prev`]|globally defined|❌
+
- [date]: /methods/page/date
- [weight]: /methods/page/weight
- [linkTitle]: /methods/page/linktitle
- [title]: /methods/page/title
++[`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.
+
+With a local collection, the navigation sort order is the same as the collection sort order.
+
+globally defined
+: Build the page collection once, on a list page. Navigation between pages is relative to the current page's position within the global collection.
+
+With a global collection, the navigation sort order is fixed, using Hugo's default sort order. In order of precedence:
+
+1. Page [weight]
+2. Page [date] (descending)
+3. Page [linkTitle], falling back to page [title]
+4. Page file path if the page is backed by a file
+
+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/
--- /dev/null
- linkTitle: Overview
+---
+title: Methods
- identifier: methods-overview
++linkTitle: In this section
+description: A list of Hugo template methods including examples.
+categories: []
+keywords: []
+menu:
+ docs:
++ identifier: methods-in-this-section
+ parent: methods
+ weight: 10
+weight: 10
+showSectionMenu: true
++aliases: ['/variables/']
+---
+
+Use these methods within your templates.
--- /dev/null
- [`lower`]: functions/strings/tolower
+---
+title: KeyName
+description: Returns the `identifier` property of the given menu entry, falling back to its `name` property.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: string
+ signatures: [MENUENTRY.KeyName]
+---
+
+In this menu definition, the second entry does not contain an `identifier`, so the `Identifier` method returns its `name` property instead:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+identifier = 'about'
+name = 'About'
+pageRef = '/about'
+weight = 10
+
+[[menus.main]]
+name = 'Contact'
+pageRef = '/contact'
+weight = 20
+{{< /code-toggle >}}
+
+This example uses the `KeyName` method when querying the translation table on a multilingual site, falling back the `name` property if a matching key in the translation table does not exist:
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main }}
+ <li><a href="{{ .URL }}">{{ or (T (.KeyName | lower)) .Name }}</a></li>
+ {{ end }}
+</ul>
+```
+
+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/
--- /dev/null
- [`HasMenuCurrent`]: /methods/page/hasmenucurrent
- [`IsMenuCurrent`]: /methods/page/ismenucurrent
+---
+title: Menu
+description: Returns the identifier of the menu that contains the given menu entry.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/IsMenuCurrent
+ - methods/page/HasMenuCurrent
+ returnType: string
+ signatures: [MENUENTRY.Menu]
+---
+
+```go-html-template
+{{ range .Site.Menus.main }}
+ {{ .Menu }} → main
+{{ end }}
+```
+
+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/
+[this example]: /templates/menu-templates/#example
--- /dev/null
- [`LinkTitle`]: /methods/page/linktitle
- [`Title`]: /methods/page/title
+---
+title: Name
+description: Returns the `name` property of the given menu entry.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: string
+ signatures: [MENUENTRY.Name]
+---
+
+If you define the menu entry [automatically], the `Name` method returns the page’s [`LinkTitle`], falling back to its [`Title`].
+
+If you define the menu entry [in front matter] or [in site configuration], the `Name` method returns the `name` property, falling back to the page’s `LinkTitle`, then to its `Title`.
+
++[`LinkTitle`]: /methods/page/linktitle/
++[`Title`]: /methods/page/title/
+[automatically]: /content-management/menus/#define-automatically
+[in front matter]: /content-management/menus/#define-in-front-matter
+[in site configuration]: /content-management/menus/#define-in-site-configuration
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main }}
+ <li><a href="{{ .URL }}">{{ .Name }}</a></li>
+ {{ end }}
+</ul>
+```
--- /dev/null
- [`LinkTitle`]: /methods/page/linktitle
- [`RelPermalink`]: /methods/page/relpermalink
+---
+title: Page
+description: Returns the Page object associated with the given menu entry.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: page.Page
+ signatures: [MENUENTRY.Page]
+---
+
+Regardless of how you [define menu entries], an entry associated with a page has access to its [methods].
+
+In this menu definition, the first two entries are associated with a page, the last entry is not:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+pageRef = '/about'
+weight = 10
+
+[[menus.main]]
+pageRef = '/contact'
+weight = 20
+
+[[menus.main]]
+name = 'Hugo'
+url = 'https://gohugo.io'
+weight = 30
+{{< /code-toggle >}}
+
+In this example, if the menu entry is associated with a page, we use page's [`RelPermalink`] and [`LinkTitle`] when rendering the anchor element.
+
+If the entry is not associated with a page, we use its `url` and `name` properties.
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main }}
+ {{ with .Page }}
+ <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
+ {{ else }}
+ <li><a href="{{ .URL }}">{{ .Name }}</a></li>
+ {{ end }}
+ {{ end }}
+</ul>
+```
+
+See the [menu templates] section for more information.
+
- [methods]: /methods/page
++[`LinkTitle`]: /methods/page/linktitle/
++[`RelPermalink`]: /methods/page/relpermalink/
+[define menu entries]: /content-management/menus/
+[menu templates]: /templates/menu-templates/#page-references
++[methods]: /methods/page/
--- /dev/null
- 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`.
+---
+title: Title
+description: Returns the `title` property of the given menu entry.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: string
+ signatures: [MENUENTRY.Title]
+---
+
+If you define the menu entry [automatically], the `Title` method returns the page’s [`LinkTitle`], falling back to its [`Title`].
+
- [`LinkTitle`]: /methods/page/linktitle
- [`Title`]: /methods/page/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/
+[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
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main }}
+ <li><a href="{{ .URL }}">{{ .Title }}</a></li>
+ {{ end }}
+</ul>
+```
--- /dev/null
- [`RelPermalink`]: /methods/page/relpermalink
+---
+title: URL
+description: Returns the relative permalink of the page associated with the given menu entry, else its `url` property.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: string
+ signatures: [MENUENTRY.URL]
+---
+
+For menu entries associated with a page, the `URL` method returns the page's [`RelPermalink`], otherwise it returns the entry's `url` property.
+
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main }}
+ <li><a href="{{ .URL }}">{{ .Name }}</a></li>
+ {{ end }}
+</ul>
+```
+
++[`RelPermalink`]: /methods/page/relpermalink/
--- /dev/null
- [`Weight`]: /methods/page/weight
+---
+title: Weight
+description: Returns the `weight` property of the given menu entry.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: int
+ signatures: [MENUENTRY.Weight]
+---
+
+If you define the menu entry [automatically], the `Weight` method returns the page’s [`Weight`].
+
+If you define the menu entry [in front matter] or [in site configuration], the `Weight` method returns the `weight` property, falling back to the page’s `Weight`.
+
++[`Weight`]: /methods/page/weight/
+[automatically]: /content-management/menus/#define-automatically
+[in front matter]: /content-management/menus/#define-in-front-matter
+[in site configuration]: /content-management/menus/#define-in-site-configuration
+
+In this contrived example, we limit the number of menu entries based on weight:
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main }}
+ {{ if le .Weight 42 }}
+ <li><a href="{{ .URL }}">{{ .Name }}</a></li>
+ {{ end }}
+ {{ end }}
+</ul>
+```
--- /dev/null
- Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+---
+cascade:
+ _build:
+ list: never
+ publishResources: false
+ render: never
+---
+
+<!--
++Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+
+Include the rendered content using the "include" shortcode.
+-->
--- /dev/null
- [`sort`]: /functions/collections/sort
+---
+title: ByName
+description: Returns the given menu with its entries sorted by name.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: navigation.Menu
+ signatures: [MENU.ByName]
+---
+
+The `Sort` method returns the given menu with its entries sorted by `name`.
+
+Consider this menu definition:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+name = 'Services'
+pageRef = '/services'
+weight = 10
+
+[[menus.main]]
+name = 'About'
+pageRef = '/about'
+weight = 20
+
+[[menus.main]]
+name = 'Contact'
+pageRef = '/contact'
+weight = 30
+{{< /code-toggle >}}
+
+To sort the entries by `name`:
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main.ByName }}
+ <li><a href="{{ .URL }}">{{ .Name }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Hugo renders this to:
+
+```html
+<ul>
+ <li><a href="/about/">About</a></li>
+ <li><a href="/contact">Contact</a></li>
+ <li><a href="/services/">Services</a></li>
+</ul>
+```
+
+You can also sort menu entries using the [`sort`] function. For example, to sort by `name` in descending order:
+
+```go-html-template
+<ul>
+ {{ range sort .Site.Menus.main "Name" "desc" }}
+ <li><a href="{{ .URL }}">{{ .Name }}</a></li>
+ {{ end }}
+</ul>
+```
+
+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/
--- /dev/null
- [`sort`]: /functions/collections/sort
+---
+title: ByWeight
+description: Returns the given menu with its entries sorted by weight, then by name, then by identifier.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: navigation.Menu
+ signatures: [MENU.ByWeight]
+---
+
+The `ByWeight` method returns the given menu with its entries sorted by [`weight`], then by `name`, then by `identifier`. This is the default sort order.
+
+[`weight`]: /getting-started/glossary/#weight
+
+Consider this menu definition:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+identifier = 'about'
+name = 'About'
+pageRef = '/about'
+weight = 20
+
+[[menus.main]]
+identifier = 'services'
+name = 'Services'
+pageRef = '/services'
+weight = 10
+
+[[menus.main]]
+identifier = 'contact'
+name = 'Contact'
+pageRef = '/contact'
+weight = 30
+{{< /code-toggle >}}
+
+To sort the entries by `weight`, then by `name`, then by `identifier`:
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main.ByWeight }}
+ <li><a href="{{ .URL }}">{{ .Name }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Hugo renders this to:
+
+```html
+<ul>
+ <li><a href="/services/">Services</a></li>
+ <li><a href="/about/">About</a></li>
+ <li><a href="/contact">Contact</a></li>
+</ul>
+```
+
+{{% note %}}
+In the menu definition above, note that the `identifier` property is only required when two or more menu entries have the same name, or when localizing the name using translation tables.
+
+[details]: /content-management/menus/#properties-front-matter
+{{% /note %}}
+
+You can also sort menu entries using the [`sort`] function. For example, to sort by `weight` in descending order:
+
+```go-html-template
+<ul>
+ {{ range sort .Site.Menus.main "Weight" "desc" }}
+ <li><a href="{{ .URL }}">{{ .Name }}</a></li>
+ {{ end }}
+</ul>
+```
+
+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/
--- /dev/null
- description: Returns all translation of the given page, including the given page.
+---
+title: AllTranslations
- {{ $langName := or .Language.LanguageName .Language.Lang }}
- {{ $langCode := or .Language.LanguageCode .Language.Lang }}
- <li><a href="{{ .RelPermalink }}" hreflang="{{ $langCode }}">{{ .LinkTitle }} ({{ $langName }})</a></li>
++description: Returns all translations of the given page, including the current language.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Translations
+ - methods/page/IsTranslated
+ - methods/page/TranslationKey
+ returnType: page.Pages
+ signatures: [PAGE.AllTranslations]
+---
+
+With this site configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'en'
+
+[languages.en]
+contentDir = 'content/en'
+languageCode = 'en-US'
+languageName = 'English'
+weight = 1
+
+[languages.de]
+contentDir = 'content/de'
+languageCode = 'de-DE'
+languageName = 'Deutsch'
+weight = 2
+
+[languages.fr]
+contentDir = 'content/fr'
+languageCode = 'fr-FR'
+languageName = 'Français'
+weight = 3
+{{< /code-toggle >}}
+
+And this content:
+
+```text
+content/
+├── de/
+│ ├── books/
+│ │ ├── book-1.md
+│ │ └── book-2.md
+│ └── _index.md
+├── en/
+│ ├── books/
+│ │ ├── book-1.md
+│ │ └── book-2.md
+│ └── _index.md
+├── fr/
+│ ├── books/
+│ │ └── book-1.md
+│ └── _index.md
+└── _index.md
+```
+
+And this template:
+
+```go-html-template
+{{ with .AllTranslations }}
+ <ul>
+ {{ range . }}
++ <li>
++ <a href="{{ .RelPermalink }}" hreflang="{{ .Language.LanguageCode }}">{{ .LinkTitle }} ({{ or .Language.LanguageName .Language.Lang }})</a>
++ </li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+Hugo will render this list on the "Book 1" page of each site:
+
+```html
+<ul>
+ <li><a href="/books/book-1/" hreflang="en-US">Book 1 (English)</a></li>
+ <li><a href="/de/books/book-1/" hreflang="de-DE">Book 1 (Deutsch)</a></li>
+ <li><a href="/fr/books/book-1/" hreflang="fr-FR">Book 1 (Français)</a></li>
+</ul>
+```
+
+On the "Book 2" page of the English and German sites, Hugo will render this:
+
+```html
+<ul>
+ <li><a href="/books/book-1/" hreflang="en-US">Book 1 (English)</a></li>
+ <li><a href="/de/books/book-1/" hreflang="de-DE">Book 1 (Deutsch)</a></li>
+</ul>
+```
--- /dev/null
- returnType: files.ContentClass
+---
+title: BundleType
+description: Returns the bundle type of the given page, or an empty string if the page is not a page bundle.
+categories: []
+keywords: []
+action:
+ related: []
++ returnType: string
+ signatures: [PAGE.BundleType]
+---
+
+A page bundle is a directory that encapsulates both content and associated [resources]. There are two types of page bundles: [leaf bundles] and [branch bundles]. See [details](/content-management/page-bundles/).
+
+The `BundleType` method on a `Page` object returns `branch` for branch bundles, `leaf` for leaf bundles, and an empty string if the page is not a page bundle.
+
+```text
+content/
+├── films/
+│ ├── film-1/
+│ │ ├── a.jpg
+│ │ └── index.md <-- leaf bundle
+│ ├── _index.md <-- branch bundle
+│ ├── b.jpg
+│ ├── film-2.md
+│ └── film-3.md
+└── _index.md <-- branch bundle
+```
+
+To get the value within a template:
+
+```go-html-template
+{{ .BundleType }}
+```
+
+[resources]: /getting-started/glossary/#resource
+[leaf bundles]: /getting-started/glossary/#leaf-bundle
+[branch bundles]: /getting-started/glossary/#branch-bundle
--- /dev/null
- [`resources.GetRemote`]: functions/resources/getremote
+---
+title: CodeOwners
+description: Returns of slice of code owners for the given page, derived from the CODEOWNERS file in the root of the project directory.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/GitInfo
+ returnType: '[]string'
+ signatures: [PAGE.CodeOwners]
+---
+
+GitHub and GitLab support CODEOWNERS files. This file specifies the users responsible for developing and maintaining software and documentation. This definition can apply to the entire repository, specific directories, or to individual files. To learn more:
+
+- [GitHub CODEOWNERS documentation]
+- [GitLab CODEOWNERS documentation]
+
+Use the `CodeOwners` method on a `Page` object to determine the code owners for the given page.
+
+[GitHub CODEOWNERS documentation]: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+[GitLab CODEOWNERS documentation]: https://docs.gitlab.com/ee/user/project/code_owners.html
+
+To use the `CodeOwners` method you must enable access to your local Git repository:
+
+{{< code-toggle file=hugo >}}
+enableGitInfo = true
+{{< /code-toggle >}}
+
+Consider this project structure:
+
+```text
+my-project/
+├── content/
+│ ├── books/
+│ │ └── les-miserables.md
+│ └── films/
+│ └── the-hunchback-of-notre-dame.md
+└── CODEOWNERS
+```
+
+And this CODEOWNERS file:
+
+```text
+* @jdoe
+/content/books/ @tjones
+/content/films/ @mrichards @rsmith
+```
+
+The table below shows the slice of code owners returned for each file:
+
+Path|Code owners
+:--|:--
+`books/les-miserables.md`|`[@tjones]`
+`films/the-hunchback-of-notre-dame.md`|`[@mrichards @rsmith]`
+
+Render the code owners for each content page:
+
+```go-html-template
+{{ range .CodeOwners }}
+ {{ . }}
+{{ end }}
+```
+
+Combine this method with [`resources.GetRemote`] to retrieve names and avatars from your Git provider by querying their API.
+
++[`resources.GetRemote`]: /functions/resources/getremote/
--- /dev/null
- The `Content` method on a `Page` object renders markdown and shortcodes to HTML. The content does not include front matter.
+---
+title: Content
+description: Returns the rendered content of the given page.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/RawContent
+ - methods/page/Plain
+ - methods/page/PlainWords
+ - methods/page/RenderShortcodes
+ returnType: template.HTML
+ signatures: [PAGE.Content]
+---
+
++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
+
+```go-html-template
+{{ .Content }}
+```
--- /dev/null
- [taxonomy methods]: /methods/taxonomy
+---
+title: Data
+description: Returns a unique data object for each page kind.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: page.Data
+ signatures: [PAGE.Data]
+toc: true
+---
+
+The `Data` method on a `Page` object returns a unique data object for each [page kind].
+
+[page kind]: /getting-started/glossary/#page-kind
+
+{{% note %}}
+The `Data` method is only useful within [taxonomy] and [term] templates.
+
+Themes that are not actively maintained may still use `.Data.Pages` in list templates. Although that syntax remains functional, use one of these methods instead: [`Pages`], [`RegularPages`], or [`RegularPagesRecursive`]
+
+[`Pages`]: /methods/page/pages/
+[`RegularPages`]: /methods/page/regularpages/
+[`RegularPagesRecursive`]: /methods/page/regularpagesrecursive/
+[term]: /getting-started/glossary/#term
+[taxonomy]: /getting-started/glossary/#taxonomy
+{{% /note %}}
+
+The examples that follow are based on this site configuration:
+
+{{< code-toggle file=hugo >}}
+[taxonomies]
+genre = 'genres'
+author = 'authors'
+{{< /code-toggle >}}
+
+And this content structure:
+
+```text
+content/
+├── books/
+│ ├── and-then-there-were-none.md --> genres: suspense
+│ ├── death-on-the-nile.md --> genres: suspense
+│ └── jamaica-inn.md --> genres: suspense, romance
+│ └── pride-and-prejudice.md --> genres: romance
+└── _index.md
+```
+
+## In a taxonomy template
+
+Use these methods on the `Data` object within a taxonomy template.
+
+Singular
+: (`string`) Returns the singular name of the taxonomy.
+
+```go-html-template
+{{ .Data.Singular }} → genre
+```
+
+Plural
+: (`string`) Returns the plural name of the taxonomy.
+
+```go-html-template
+{{ .Data.Plural }} → genres
+```
+
+Terms
+: (`page.Taxonomy`) Returns the taxonomy object, consisting of a map of terms and the [weighted pages] associated with each term.
+
+```go-html-template
+{{ $taxonomyObject := .Data.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/
+{{% /note %}}
+
+Learn more about [taxonomy templates].
+
+## In a term template
+
+Use these methods on the `Data` object within a term template.
+
+Singular
+: (`string`) Returns the singular name of the taxonomy.
+
+```go-html-template
+{{ .Data.Singular }} → genre
+```
+
+Plural
+: (`string`) Returns the plural name of the taxonomy.
+
+```go-html-template
+{{ .Data.Plural }} → genres
+```
+
+Term
+: (`string`) Returns the name of the term.
+
+```go-html-template
+{{ .Data.Term }} → suspense
+```
+
+Learn more about [term templates].
+
+[taxonomy templates]: /templates/taxonomy-templates/
+[term templates]: /templates/taxonomy-templates/
+[weighted pages]: /getting-started/glossary/#weighted-page
--- /dev/null
- [`time.Format`]: /functions/time/format
+---
+title: Date
+description: Returns the date of the given page.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/ExpiryDate
+ - methods/page/LastMod
+ - methods/page/PublishDate
+ returnType: time.Time
+ signatures: [PAGE.Date]
+---
+
+Set the date in front matter:
+
+{{< code-toggle file=content/news/article-1.md fm=true >}}
+title = 'Article 1'
+date = 2023-10-19T00:40:04-07:00
+{{< /code-toggle >}}
+
+{{% note %}}
+The date field in front matter is often considered to be the creation date, You can change its meaning, and its effect on your site, in the site configuration. See [details].
+
+[details]: /getting-started/configuration/#configure-dates
+{{% /note %}}
+
+The date is a [time.Time] value. Format and localize the value with the [`time.Format`] function, or use it with any of the [time methods].
+
+```go-html-template
+{{ .Date | time.Format ":date_medium" }} → Oct 19, 2023
+```
+
+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 methods]: /methods/time
++[`time.Format`]: /functions/time/format/
+[details]: /getting-started/configuration/#configure-dates
++[time methods]: /methods/time/
+[time.Time]: https://pkg.go.dev/time#Time
--- /dev/null
- Conceptually different that a [content summary], a page description is typically used in metadata about the page.
+---
+title: Description
+description: Returns the description of the given page as defined in front matter.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Summary
+ returnType: string
+ signatures: [PAGE.Description]
+---
+
- [content summary]: /content-management/summaries
++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'
+description = 'Instructions for making spicy tuna hand rolls.'
+{{< /code-toggle >}}
+
+{{< code file=layouts/baseof.html >}}
+<head>
+ ...
+ <meta name="description" content="{{ .Description }}">
+ ...
+</head>
+{{< /code >}}
+
++[content summary]: /content-management/summaries/
--- /dev/null
- [`time.Format`]: /functions/time/format
+---
+title: ExpiryDate
+description: Returns the expiry date of the given page.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Date
+ - methods/page/LastMod
+ - methods/page/PublishDate
+ returnType: time.Time
+ signatures: [PAGE.ExpiryDate]
+---
+
+By default, Hugo excludes expired pages when building your site. To include expired pages, use the `--buildExpired` command line flag.
+
+Set the expiry date in front matter:
+
+{{< code-toggle file=content/news/article-1.md fm=true >}}
+title = 'Article 1'
+expiryDate = 2024-10-19T00:32:13-07:00
+{{< /code-toggle >}}
+
+The expiry date is a [time.Time] value. Format and localize the value with the [`time.Format`] function, or use it with any of the [time methods].
+
+```go-html-template
+{{ .ExpiryDate | time.Format ":date_medium" }} → Oct 19, 2024
+```
+
+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 methods]: /methods/time
++[`time.Format`]: /functions/time/format/
+[details]: /getting-started/configuration/#configure-dates
++[time methods]: /methods/time/
+[time.Time]: https://pkg.go.dev/time#Time
--- /dev/null
- Code defensively by verifying file existence as shown in each of the examples below.
+---
+title: File
+description: For pages backed by a file, returns file information for the given page.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: hugolib.fileInfo
+ signatures: [PAGE.File]
+toc: true
+---
+
+By default, not all pages are backed by a file, including top level [section] pages, [taxonomy] pages, and [term] pages. By definition, you cannot retrieve file information when the file does not exist.
+
+To back one of the pages above with a file, create an _index.md file in the corresponding directory. For example:
+
+```text
+content/
+└── books/
+ ├── _index.md <-- the top level section page
+ ├── book-1.md
+ └── book-2.md
+```
+
- ###### Lang
++{{% note %}}
++Code defensively by verifying file existence as shown in the examples below.
++{{% /note %}}
+
+## Methods
+
+{{% note %}}
+The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend on the operating system.
+{{% /note %}}
+
+###### BaseFileName
+
+(`string`) The file name, excluding the extension.
+
+```go-html-template
+{{ with .File }}
+ {{ .BaseFileName }}
+{{ end }}
+```
+
+###### ContentBaseName
+
+(`string`) If the page is a branch or leaf bundle, the name of the containing directory, else the `TranslationBaseName`.
+
+```go-html-template
+{{ with .File }}
+ {{ .ContentBaseName }}
+{{ end }}
+```
+
+###### Dir
+
+(`string`) The file path, excluding the file name, relative to the `content` directory.
+
+```go-html-template
+{{ with .File }}
+ {{ .Dir }}
+{{ end }}
+```
+
+###### Ext
+
+(`string`) The file extension.
+
+```go-html-template
+{{ with .File }}
+ {{ .Ext }}
+{{ end }}
+```
+
+###### Filename
+
+(`string`) The absolute file path.
+
+```go-html-template
+{{ with .File }}
+ {{ .Filename }}
+{{ end }}
+```
+
- (`string`) The language associated with the given file.
++###### IsContentAdapter
++
++{{< new-in 0.126.0 >}}
++
++(`bool`) Reports whether the file is a [content adapter].
+
- {{ .Lang }}
++[content adapter]: /content-management/content-adapters/
+
+```go-html-template
+{{ with .File }}
- Lang|en|en|en
++ {{ .IsContentAdapter }}
+{{ end }}
+```
+
+###### LogicalName
+
+(`string`) The file name.
+
+```go-html-template
+{{ with .File }}
+ {{ .LogicalName }}
+{{ end }}
+```
+
+###### Path
+
+(`string`) The file path, relative to the `content` directory.
+
+```go-html-template
+{{ with .File }}
+ {{ .Path }}
+{{ 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.
+
+```go-html-template
+{{ with .File }}
+ {{ .TranslationBaseName }}
+{{ end }}
+```
+
+###### UniqueID
+
+(`string`) The MD5 hash of `.File.Path`.
+
+```go-html-template
+{{ with .File }}
+ {{ .UniqueID }}
+{{ end }}
+```
+
+## Examples
+
+Consider this content structure in a multilingual project:
+
+```text
+content/
+├── news/
+│ ├── b/
+│ │ ├── index.de.md <-- leaf bundle
+│ │ └── index.en.md <-- leaf bundle
+│ ├── a.de.md <-- regular content
+│ ├── a.en.md <-- regular content
+│ ├── _index.de.md <-- branch bundle
+│ └── _index.en.md <-- branch bundle
+├── _index.de.md
+└── _index.en.md
+```
+
+With the English language site:
+
+ |regular content|leaf bundle|branch bundle
+:--|:--|:--|:--
+BaseFileName|a.en|index.en|_index.en
+ContentBaseName|a|b|news
+Dir|news/|news/b/|news/
+Ext|md|md|md
+Filename|/home/user/...|/home/user/...|/home/user/...
- 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:
++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...
+
+## Defensive coding
+
+Some of the pages on a site may not be backed by a file. For example:
+
+- Top level section pages
+- Taxonomy pages
+- Term pages
+
++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 }}
+ {{ .ContentBaseName }}
+{{ end }}
+```
+
+[section]: /getting-started/glossary/#section
+[taxonomy]: /getting-started/glossary/#taxonomy
+[term]: /getting-started/glossary/#term
--- /dev/null
- 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.
+---
+title: Fragments
+description: Returns a data structure of the fragments in the given page.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/TableOfContents
+ returnType: tableofcontents.Fragments
+ signatures: [PAGE.Fragments]
+toc: true
+---
+
+{{< new-in 0.111.0 >}}
+
+In a URL, whether absolute or relative, the [fragment] links to an `id` attribute of an HTML element on the page.
+
+```text
+/articles/article-1#section-2
+------------------- ---------
+ path fragment
+```
+
- <pre>{{ .Fragments.Headings | jsonify (dict "indent" " ") }}</pre>
++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.
+
+## Methods
+
+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
- <pre>{{ .Fragments.HeadingsMap | jsonify (dict "indent" " ") }}</pre>
++<pre>{{ debug.Dump .Fragments.Headings }}</pre>
+```
+
+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
- <pre>{{ .Fragments.Identifiers | jsonify (dict "indent" " ") }}</pre>
++<pre>{{ debug.Dump .Fragments.HeadingsMap }}</pre>
+```
+
+Identifiers
+: (`slice`) A slice containing the `id` of each heading on the page. To inspect the data structure:
+
+```go-html-template
- [table of contents]: /methods/page/tableofcontents
++<pre>{{ debug.Dump .Fragments.Identifiers }}</pre>
+```
+
+Identifiers.Contains ID
+: (`bool`) Reports whether one or more headings on the page has the given `id` attribute, useful for validating fragments within a link [render hook].
+
+```go-html-template
+{{ .Fragments.Identifiers.Contains "section-2" }} → true
+```
+
+Identifiers.Count ID
+: (`int`) The number of headings on a page with the given `id` attribute, useful for detecting duplicates.
+
+```go-html-template
+{{ .Fragments.Identifiers.Count "section-2" }} → 1
+```
+
+ToHTML
+: (`template.HTML`) Returns a TOC as a nested list, either ordered or unordered, identical to the HTML returned by the [`TableOfContents`] method. This method take three arguments: the start level (`int`), the end level (`int`), and a boolean (`true` to return an ordered list, `false` to return an unordered list).
+
+Use this method when you want to control the start level, end level, or list type independently from the table of contents settings in your site configuration.
+
+```go-html-template
+{{ $startLevel := 2 }}
+{{ $endLevel := 3 }}
+{{ $ordered := true }}
+{{ .Fragments.ToHTML $startLevel $endLevel $ordered }}
+```
+
+Hugo renders this to:
+
+```html
+<nav id="TableOfContents">
+ <ol>
+ <li><a href="#section-1">Section 1</a>
+ <ol>
+ <li><a href="#section-11">Section 1.1</a></li>
+ <li><a href="#section-12">Section 1.2</a></li>
+ </ol>
+ </li>
+ <li><a href="#section-2">Section 2</a></li>
+ </ol>
+</nav>
+```
+
+{{% note %}}
+It is safe to use the `Fragments` methods within a render hook, even for the current page.
+
+When using the `Fragments` methods within a shortcode, call the shortcode using the `{{</* */>}}` notation. If you use the `{{%/* */%}}` notation, the rendered shortcode is included in the creation of the fragments map, resulting in a circular loop.
+{{% /note %}}
+
+[atx]: https://spec.commonmark.org/0.30/#atx-headings
+[fragment]: /getting-started/glossary/#fragment
+[markdown attribute]: /getting-started/glossary/#markdown-attribute
+[setext]: https://spec.commonmark.org/0.30/#setext-headings
- [`tableofcontents`]: /methods/page/tableofcontents
++[table of contents]: /methods/page/tableofcontents/
+[walking]: /getting-started/glossary/#walk
++[`tableofcontents`]: /methods/page/tableofcontents/
+[render hook]: /getting-started/glossary/#render-hook
--- /dev/null
- [`WordCount`]: /methods/page/wordcount
+---
+title: FuzzyWordCount
+description: Returns the number of words in the content of the given page, rounded up to the nearest multiple of 100.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/WordCount
+ - methods/page/ReadingTime
+ returnType: int
+ signatures: [PAGE.FuzzyWordCount]
+---
+
+```go-html-template
+{{ .FuzzyWordCount }} → 200
+```
+
+To get the exact word count, use the [`WordCount`] method.
+
++[`WordCount`]: /methods/page/wordcount/
--- /dev/null
- [details]: /methods/site/getpage
+---
+title: GetPage
+description: Returns a Page object from the given path.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/site/GetPage
+ returnType: page.Page
+ signatures: [PAGE.GetPage PATH]
+aliases: [/functions/getpage]
+---
+
+The `GetPage` method is also available on a `Site` object. See [details].
+
- The examples below depict the result of rendering works/paintings/the-mona-list.md with a single page template:
++[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.
+
+If Hugo cannot resolve the path to a page, the method returns nil. If the path is ambiguous, Hugo throws an error and fails the build.
+
+Consider this content structure:
+
+```text
+content/
+├── works/
+│ ├── paintings/
+│ │ ├── _index.md
+│ │ ├── starry-night.md
+│ │ └── the-mona-lisa.md
+│ ├── sculptures/
+│ │ ├── _index.md
+│ │ ├── david.md
+│ │ └── the-thinker.md
+│ └── _index.md
+└── _index.md
+```
+
++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" }}
+ {{ .Title }} → Starry Night
+{{ end }}
+
+{{ with .GetPage "./starry-night" }}
+ {{ .Title }} → Starry Night
+{{ end }}
+
+{{ with .GetPage "../paintings/starry-night" }}
+ {{ .Title }} → Starry Night
+{{ end }}
+
+{{ with .GetPage "/works/paintings/starry-night" }}
+ {{ .Title }} → Starry Night
+{{ end }}
+
+{{ with .GetPage "../sculptures/david" }}
+ {{ .Title }} → David
+{{ end }}
+
+{{ with .GetPage "/works/sculptures/david" }}
+ {{ .Title }} → David
+{{ end }}
+```
--- /dev/null
- [`Related`]: /methods/pages/related
+---
+title: HeadingsFiltered
+description: Returns a slice of headings for each page related to the given page.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/pages/Related
+ - methods/page/Fragments
+ returnType: tableofcontents.Headings
+ signatures: [PAGE.HeadingsFiltered]
+---
+
+Use in conjunction with the [`Related`] method on a [`Pages`] object. See [details].
+
+[`Pages`]: /methods/pages/
++[`Related`]: /methods/pages/related/
+[details]: /content-management/related/#index-content-headings-in-related-content
--- /dev/null
- [`with`]: /functions/go-template/with
- [`else`]: /functions/go-template/else
+---
+title: InSection
+description: Reports whether the given page is in the given section.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Ancestors
+ - methods/page/CurrentSection
+ - methods/page/FirstSection
+ - methods/page/IsAncestor
+ - methods/page/IsDescendant
+ - methods/page/Parent
+ - methods/page/Sections
+ returnType: bool
+ signatures: [PAGE.InSection SECTION]
+toc: true
+---
+
+The `InSection` method on a page object reports whether the given page is in the given section. Note that the method returns `true` when comparing a page to a sibling.
+
+{{% include "methods/page/_common/definition-of-section.md" %}}
+
+With this content structure:
+
+```text
+content/
+├── auctions/
+│ ├── 2023-11/
+│ │ ├── _index.md
+│ │ ├── auction-1.md
+│ │ └── auction-2.md
+│ ├── 2023-12/
+│ │ ├── _index.md
+│ │ ├── auction-3.md
+│ │ └── auction-4.md
+│ ├── _index.md
+│ ├── bidding.md
+│ └── payment.md
+└── _index.md
+```
+
+When rendering the "auction-1" page:
+
+```go-html-template
+{{ with .Site.GetPage "/" }}
+ {{ $.InSection . }} → false
+{{ end }}
+
+{{ with .Site.GetPage "/auctions" }}
+ {{ $.InSection . }} → false
+{{ end }}
+
+{{ with .Site.GetPage "/auctions/2023-11" }}
+ {{ $.InSection . }} → true
+{{ end }}
+
+{{ with .Site.GetPage "/auctions/2023-11/auction-2" }}
+ {{ $.InSection . }} → true
+{{ end }}
+```
+
+In the examples above we are coding defensively using the [`with`] statement, returning nothing if the page does not exist. By adding an [`else`] clause we can do some error reporting:
+
+```go-html-template
+{{ $path := "/auctions/2023-11" }}
+{{ with .Site.GetPage $path }}
+ {{ $.InSection . }} → true
+{{ else }}
+ {{ errorf "Unable to find the section with path %s" $path }}
+{{ end }}
+ ```
+
+## Understanding context
+
+Inside of the `with` block, the [context] (the dot) is the section `Page` object, not the `Page` object passed into the template. If we were to use this syntax:
+
+```go-html-template
+{{ with .Site.GetPage "/auctions" }}
+ {{ .InSection . }} → true
+{{ end }}
+```
+
+The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself.
+
+{{% note %}}
+Use the `$` to get the context passed into the template.
+{{% /note %}}
+
+```go-html-template
+{{ with .Site.GetPage "/auctions" }}
+ {{ $.InSection . }} → true
+{{ end }}
+```
+
+{{% note %}}
+Gaining a thorough understanding of context is critical for anyone writing template code.
+{{% /note %}}
+
+[context]: /getting-started/glossary/#context
++[`with`]: /functions/go-template/with/
++[`else`]: /functions/go-template/else/
--- /dev/null
- description: Reports whether PAGE1 in an ancestor of PAGE2.
+---
+title: IsAncestor
- [`with`]: /functions/go-template/with
- [`else`]: /functions/go-template/else
++description: Reports whether PAGE1 is an ancestor of PAGE2.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Ancestors
+ - methods/page/CurrentSection
+ - methods/page/FirstSection
+ - methods/page/InSection
+ - methods/page/IsDescendant
+ - methods/page/Parent
+ - methods/page/Sections
+ returnType: bool
+ signatures: [PAGE1.IsAncestor PAGE2]
+toc: true
+---
+
+{{% include "methods/page/_common/definition-of-section.md" %}}
+
+With this content structure:
+
+```text
+content/
+├── auctions/
+│ ├── 2023-11/
+│ │ ├── _index.md
+│ │ ├── auction-1.md
+│ │ └── auction-2.md
+│ ├── 2023-12/
+│ │ ├── _index.md
+│ │ ├── auction-3.md
+│ │ └── auction-4.md
+│ ├── _index.md
+│ ├── bidding.md
+│ └── payment.md
+└── _index.md
+```
+
+When rendering the "auctions" page:
+
+```go-html-template
+{{ with .Site.GetPage "/" }}
+ {{ $.IsAncestor . }} → false
+{{ end }}
+
+{{ with .Site.GetPage "/auctions" }}
+ {{ $.IsAncestor . }} → false
+{{ end }}
+
+{{ with .Site.GetPage "/auctions/2023-11" }}
+ {{ $.IsAncestor . }} → true
+{{ end }}
+
+{{ with .Site.GetPage "/auctions/2023-11/auction-2" }}
+ {{ $.IsAncestor . }} → true
+{{ end }}
+```
+
+In the examples above we are coding defensively using the [`with`] statement, returning nothing if the page does not exist. By adding an [`else`] clause we can do some error reporting:
+
+```go-html-template
+{{ $path := "/auctions/2023-11" }}
+{{ with .Site.GetPage $path }}
+ {{ $.IsAncestor . }} → true
+{{ else }}
+ {{ errorf "Unable to find the section with path %s" $path }}
+{{ end }}
+ ```
+
+## Understanding context
+
+Inside of the `with` block, the [context] (the dot) is the section `Page` object, not the `Page` object passed into the template. If we were to use this syntax:
+
+```go-html-template
+{{ with .Site.GetPage "/auctions" }}
+ {{ .IsAncestor . }} → true
+{{ end }}
+```
+
+The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself.
+
+{{% note %}}
+Use the `$` to get the context passed into the template.
+{{% /note %}}
+
+```go-html-template
+{{ with .Site.GetPage "/auctions" }}
+ {{ $.IsAncestor . }} → true
+{{ end }}
+```
+
+{{% note %}}
+Gaining a thorough understanding of context is critical for anyone writing template code.
+{{% /note %}}
+
+[context]: /getting-started/glossary/#context
++[`with`]: /functions/go-template/with/
++[`else`]: /functions/go-template/else/
--- /dev/null
- description: Reports whether PAGE1 in a descendant of PAGE2.
+---
+title: IsDescendant
- [`with`]: /functions/go-template/with
- [`else`]: /functions/go-template/else
++description: Reports whether PAGE1 is a descendant of PAGE2.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Ancestors
+ - methods/page/CurrentSection
+ - methods/page/FirstSection
+ - methods/page/InSection
+ - methods/page/IsAncestor
+ - methods/page/Parent
+ - methods/page/Sections
+ returnType: bool
+ signatures: [PAGE1.IsDescendant PAGE2]
+---
+
+{{% include "methods/page/_common/definition-of-section.md" %}}
+
+With this content structure:
+
+```text
+content/
+├── auctions/
+│ ├── 2023-11/
+│ │ ├── _index.md
+│ │ ├── auction-1.md
+│ │ └── auction-2.md
+│ ├── 2023-12/
+│ │ ├── _index.md
+│ │ ├── auction-3.md
+│ │ └── auction-4.md
+│ ├── _index.md
+│ ├── bidding.md
+│ └── payment.md
+└── _index.md
+```
+
+When rendering the "auctions" page:
+
+```go-html-template
+{{ with .Site.GetPage "/" }}
+ {{ $.IsDescendant . }} → true
+{{ end }}
+
+{{ with .Site.GetPage "/auctions" }}
+ {{ $.IsDescendant . }} → false
+{{ end }}
+
+{{ with .Site.GetPage "/auctions/2023-11" }}
+ {{ $.IsDescendant . }} → false
+{{ end }}
+
+{{ with .Site.GetPage "/auctions/2023-11/auction-2" }}
+ {{ $.IsDescendant . }} → false
+{{ end }}
+```
+
+In the examples above we are coding defensively using the [`with`] statement, returning nothing if the page does not exist. By adding an [`else`] clause we can do some error reporting:
+
+```go-html-template
+{{ $path := "/auctions/2023-11" }}
+{{ with .Site.GetPage $path }}
+ {{ $.IsDescendant . }} → true
+{{ else }}
+ {{ errorf "Unable to find the section with path %s" $path }}
+{{ end }}
+ ```
+
+## Understanding context
+
+Inside of the `with` block, the [context] (the dot) is the section `Page` object, not the `Page` object passed into the template. If we were to use this syntax:
+
+```go-html-template
+{{ with .Site.GetPage "/auctions" }}
+ {{ .IsDescendant . }} → true
+{{ end }}
+```
+
+The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself.
+
+{{% note %}}
+Use the `$` to get the context passed into the template.
+{{% /note %}}
+
+```go-html-template
+{{ with .Site.GetPage "/auctions" }}
+ {{ $.IsDescendant . }} → true
+{{ end }}
+```
+
+{{% note %}}
+Gaining a thorough understanding of context is critical for anyone writing template code.
+{{% /note %}}
+
+[context]: /getting-started/glossary/#context
++[`with`]: /functions/go-template/with/
++[`else`]: /functions/go-template/else/
--- /dev/null
- [related content]: /content-management/related
+---
+title: Keywords
+description: Returns a slice of keywords as defined in front matter.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: '[]string'
+ signatures: [PAGE.Keywords]
+---
+
+By default, Hugo evaluates the keywords when creating collections of [related content].
+
- [delimit]: /functions/collections/delimit
++[related content]: /content-management/related/
+
+{{< code-toggle file=content/recipes/sushi.md fm=true >}}
+title = 'How to make spicy tuna hand rolls'
+keywords = ['tuna','sriracha','nori','rice']
+{{< /code-toggle >}}
+
+To list the keywords within a template:
+
+```go-html-template
+{{ range .Keywords }}
+ {{ . }}
+{{ end }}
+```
+
+Or use the [delimit] function:
+
+```go-html-template
+{{ delimit .Keywords ", " ", and " }} → tuna, sriracha, nori, and rice
+```
+
- [taxonomy]: /content-management/taxonomies
++[delimit]: /functions/collections/delimit/
+
+Keywords are also a useful [taxonomy]:
+
+{{< code-toggle file=hugo >}}
+[taxonomies]
+tag = 'tags'
+keyword = 'keywords'
+category = 'categories'
+{{< /code-toggle >}}
+
++[taxonomy]: /content-management/taxonomies/
--- /dev/null
- : (`string`) The language code from the site configuration.
+---
+title: Language
+description: Returns the language object for the given page.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/site/Language
+ returnType: langs.Language
+ signatures: [PAGE.Language]
+---
+
+The `Language` method on a `Page` object returns the language object for the given page. The language object points to the language definition in the site configuration.
+
+You can also use the `Language` method on a `Site` object. See [details].
+
+## Methods
+
+The examples below assume the following in your site configuration:
+
+{{< code-toggle file=hugo >}}
+[languages.de]
+languageCode = 'de-DE'
+languageDirection = 'ltr'
+languageName = 'Deutsch'
+weight = 2
+{{< /code-toggle >}}
+
+Lang
+: (`string`) The language tag as defined by [RFC 5646].
+
+```go-html-template
+{{ .Language.Lang }} → de
+```
+
+LanguageCode
- [details]: /methods/site/language
++: (`string`) The language code from the site configuration. Falls back to `Lang` if not defined.
+
+```go-html-template
+{{ .Language.LanguageCode }} → de-DE
+```
+
+LanguageDirection
+: (`string`) The language direction from the site configuration, either `ltr` or `rtl`.
+
+```go-html-template
+{{ .Language.LanguageDirection }} → ltr
+```
+
+LanguageName
+: (`string`) The language name from the site configuration.
+
+```go-html-template
+{{ .Language.LanguageName }} → Deutsch
+```
+
+Weight
+: (`int`) The language weight from the site configuration which determines its order in the slice of languages returned by the `Languages` method on a `Site` object.
+
+```go-html-template
+{{ .Language.Weight }} → 2
+```
+
++[details]: /methods/site/language/
+[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
--- /dev/null
- [`gitinfo`]: /methods/page/gitinfo
- [`time.format`]: /functions/time/format
+---
+title: Lastmod
+description: Returns the last modification date of the given page.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Date
+ - methods/page/ExpiryDate
+ - methods/page/PublishDate
+ - methods/page/GitInfo
+ returnType: time.Time
+ signatures: [PAGE.Lastmod]
+---
+
+Set the last modification date in front matter:
+
+{{< code-toggle file=content/news/article-1.md fm=true >}}
+title = 'Article 1'
+lastmod = 2023-10-19T00:40:04-07:00
+{{< /code-toggle >}}
+
+The last modification date is a [time.Time] value. Format and localize the value with the [`time.Format`] function, or use it with any of the [time methods].
+
+```go-html-template
+{{ .Lastmod | time.Format ":date_medium" }} → Oct 19, 2023
+```
+
+In the example above we explicitly set the last modification date in front matter. With Hugo's default configuration, the `Lastmod` method returns the front matter value. This behavior is configurable, allowing you to:
+
+- Set the last modification date to the Author Date of the last Git commit for that file. See [`GitInfo`] for details.
+- Set fallback values if the last modification date is not defined in front matter.
+
+Learn more about [date configuration].
+
- [time methods]: /methods/time
++[`gitinfo`]: /methods/page/gitinfo/
++[`time.format`]: /functions/time/format/
+[date configuration]: /getting-started/configuration/#configure-dates
++[time methods]: /methods/time/
+[time.time]: https://pkg.go.dev/time#time
--- /dev/null
- [`Title`]: /methods/page/title
+---
+title: LinkTitle
+description: Returns the link title of the given page.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Title
+ returnType: string
+ signatures: [PAGE.LinkTitle]
+---
+
+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/
+
+{{< code-toggle file=content/articles/healthy-desserts.md fm=true >}}
+title = 'Seventeen delightful recipes for healthy desserts'
+linkTitle = 'Dessert recipes'
+{{< /code-toggle >}}
+
+```go-html-template
+{{ .LinkTitle }} → Dessert recipes
+```
+
+As demonstrated above, defining a link title in front matter is advantageous when the page title is long. Use it when generating anchor elements in your templates:
+
+```go-html-template
+<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+```
--- /dev/null
- [date]: /methods/page/date
- [weight]: /methods/page/weight
- [linkTitle]: /methods/page/linktitle
- [title]: /methods/page/title
+---
+title: NextInSection
+description: Returns the next page within a section, relative to the given page.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/PrevInSection
+ - methods/page/Next
+ - methods/page/Prev
+ - methods/pages/Next
+ - methods/pages/Prev
+ returnType: page.Page
+ signatures: [PAGE.NextInSection]
+---
+
+The behavior of the `PrevInSection` and `NextInSection` methods on a `Page` object is probably the reverse of what you expect.
+
+With this content structure:
+
+```text
+content/
+├── books/
+│ ├── _index.md
+│ ├── book-1.md
+│ ├── book-2.md
+│ └── book-3.md
+├── films/
+│ ├── _index.md
+│ ├── film-1.md
+│ ├── film-2.md
+│ └── film-3.md
+└── _index.md
+```
+
+When you visit book-2:
+
+- The `PrevInSection` method points to book-3
+- The `NextInSection` method points to book-1
+
+{{% note %}}
+Use the opposite label in your navigation links as shown in the example below.
+{{% /note %}}
+
+```go-html-template
+{{ with .NextInSection }}
+ <a href="{{ .RelPermalink }}">Previous in section</a>
+{{ end }}
+
+{{ with .PrevInSection }}
+ <a href="{{ .RelPermalink }}">Next in section</a>
+{{ end }}
+```
+
+{{% note %}}
+The navigation sort order may be different than the page collection sort order.
+{{% /note %}}
+
+With the `PrevInSection` and `NextInSection` methods, the navigation sort order is fixed, using Hugo’s default sort order. In order of precedence:
+
+1. Page [weight]
+2. Page [date] (descending)
+3. Page [linkTitle], falling back to page [title]
+4. Page file path if the page is backed by a file
+
+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/
--- /dev/null
- [details]: /methods/site/pages
+---
+title: Pages
+description: Returns a collection of regular pages within the current section, and section pages of immediate descendant sections.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/RegularPages
+ - methods/page/RegularPagesRecursive
+ returnType: page.Pages
+ signatures: [PAGE.Pages]
+---
+
+The `Pages` method on a `Page` object is available to these [page kinds]: `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection] in [context].
+
+Range through the page collection in your template:
+
+```go-html-template
+{{ range .Pages.ByTitle }}
+ <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
+{{ end }}
+```
+
+Consider this content structure:
+
+```text
+content/
+├── lessons/
+│ ├── lesson-1/
+│ │ ├── _index.md
+│ │ ├── part-1.md
+│ │ └── part-2.md
+│ ├── lesson-2/
+│ │ ├── resources/
+│ │ │ ├── task-list.md
+│ │ │ └── worksheet.md
+│ │ ├── _index.md
+│ │ ├── part-1.md
+│ │ └── part-2.md
+│ ├── _index.md
+│ ├── grading-policy.md
+│ └── lesson-plan.md
+├── _index.md
+├── contact.md
+└── legal.md
+```
+
+When rendering the home page, the `Pages` method returns:
+
+ contact.md
+ legal.md
+ lessons/_index.md
+
+When rendering the lessons page, the `Pages` method returns:
+
+ lessons/grading-policy.md
+ lessons/lesson-plan.md
+ lessons/lesson-1/_index.md
+ lessons/lesson-2/_index.md
+
+When rendering lesson-1, the `Pages` method returns:
+
+ lessons/lesson-1/part-1.md
+ lessons/lesson-1/part-2.md
+
+When rendering lesson-2, the `Pages` method returns:
+
+ lessons/lesson-2/part-1.md
+ lessons/lesson-2/part-2.md
+ lessons/lesson-2/resources/task-list.md
+ lessons/lesson-2/resources/worksheet.md
+
+In the last example, the collection includes pages in the resources subdirectory. That directory is not a [section]---it does not contain an _index.md file. Its contents are part of the lesson-2 section.
+
+{{% note %}}
+When used with a `Site` object, the `Pages` method recursively returns all pages within the site. See [details].
+
++[details]: /methods/site/pages/
+{{% /note %}}
+
+```go-html-template
+{{ range .Site.Pages.ByTitle }}
+ <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
+{{ end }}
+```
+
+[collection]: /getting-started/glossary/#collection
+[context]: /getting-started/glossary/#context
+[page kinds]: /getting-started/glossary/#page-kind
+[section]: /getting-started/glossary/#section
--- /dev/null
- [`paginate`]: /methods/page/paginate
+---
+title: Paginator
+description: Paginates the collection of regular pages received in context.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Paginate
+ returnType: page.Pager
+ signatures: [PAGE.Paginator]
+---
+
+[Pagination] is the process of splitting a list page into two or more pagers, where each pager contains a subset of the page collection and navigation links to other pagers. The number of elements on each pager is determined by the value of the `paginate` setting in your site configuration. The default value is `10`.
+
+You can invoke pagination on the home page template, [`section`] templates, [`taxonomy`] templates, and [`term`] templates. Each of these receive a collection of regular pages in [context]. When you invoke the `Paginator` method, it paginates the page collection received in context.
+
+{{< code file=layouts/_default/list.html >}}
+{{ range .Paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+{{ template "_internal/pagination.html" . }}
+{{< /code >}}
+
+In the example above, the internal "pagination" template creates the navigation links between pagers.
+
+{{% note %}}
+Although simple to invoke, with the `Paginator` method you can neither filter nor sort the page collection. It acts upon the page collection received in context.
+
+The [`Paginate`] method is more flexible, and strongly recommended.
+
++[`paginate`]: /methods/page/paginate/
+{{% /note %}}
+
+{{% note %}}
+Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect.
+{{% /note %}}
+
+[context]: /getting-started/glossary/#context
+[pagination]: /templates/pagination/
+[`section`]: /getting-started/glossary/#section
+[`taxonomy`]: /getting-started/glossary/#taxonomy
+[`term`]: /getting-started/glossary/#term
--- /dev/null
+---
+title: Param
+description: Returns a page parameter with the given key, falling back to a site parameter if present.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: any
+ signatures: [PAGE.Param KEY]
+aliases: [/functions/param]
+---
+
+The `Param` method on a `Page` object looks for the given `KEY` in page parameters, and returns the corresponding value. If it cannot find the `KEY` in page parameters, it looks for the `KEY` in site parameters. If it cannot find the `KEY` in either location, the `Param` method returns `nil`.
+
+Site and theme developers commonly set parameters at the site level, allowing content authors to override those parameters at the page level.
+
+For example, to show a table of contents on every page, but allow authors to hide the table of contents as needed:
+
+Configuration:
+
+{{< code-toggle file=hugo >}}
+[params]
+display_toc = true
+{{< /code-toggle >}}
+
+Content:
+
+{{< code-toggle file=content/example.md fm=true >}}
+title = 'Example'
+date = 2023-01-01
+draft = false
++[params]
+display_toc = false
+{{< /code-toggle >}}
+
+Template:
+
+```go-html-template
+{{ if .Param "display_toc" }}
+ {{ .TableOfContents }}
+{{ end }}
+```
+
+The `Param` method returns the value associated with the given `KEY`, regardless of whether the value is truthy or falsy. If you need to ignore falsy values, use this construct instead:
+
+```go-html-template
+{{ or .Params.foo site.Params.foo }}
+```
--- /dev/null
- [author]
+---
+title: Params
+description: Returns a map of custom parameters as defined in the front matter of the given page.
+categories: []
+keywords: []
+action:
+ related:
+ - functions/collections/IndexFunction
+ - methods/site/Params
+ - methods/page/Param
+ returnType: maps.Params
+ signatures: [PAGE.Params]
+---
+
+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
- [`index`]: /functions/collections/indexfunction
++[params.author]
+ email = 'jsmith@example.org'
+ name = 'John Smith'
+{{< /code-toggle >}}
+
+The `title` and `date` fields are standard parameters---the other fields are user-defined.
+
+Access the custom parameters by [chaining] the [identifiers]:
+
+```go-html-template
+{{ .Params.display_related }} → true
+{{ .Params.author.name }} → John Smith
+```
+
+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:
+
+```go-html-template
+{{ index .Params "key-with-hyphens" }} → 2023
+```
+
++[`index`]: /functions/collections/indexfunction/
+[chaining]: /getting-started/glossary/#chain
+[identifiers]: /getting-started/glossary/#identifier
--- /dev/null
- [current section]: /methods/page/currentsection
+---
+title: Parent
+description: Returns the Page object of the parent section of the given page.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Ancestors
+ - methods/page/CurrentSection
+ - methods/page/FirstSection
+ - methods/page/InSection
+ - methods/page/IsAncestor
+ - methods/page/IsDescendant
+ - methods/page/Sections
+ returnType: page.Page
+ signatures: [PAGE.Parent]
+---
+
+{{% include "methods/page/_common/definition-of-section.md" %}}
+
+{{% note %}}
+The parent section of a regular page is the [current section].
+
++[current section]: /methods/page/currentsection/
+{{% /note %}}
+
+Consider this content structure:
+
+```text
+content/
+├── auctions/
+│ ├── 2023-11/
+│ │ ├── _index.md <-- parent: auctions
+│ │ ├── auction-1.md
+│ │ └── auction-2.md <-- parent: 2023-11
+│ ├── 2023-12/
+│ │ ├── _index.md
+│ │ ├── auction-3.md
+│ │ └── auction-4.md
+│ ├── _index.md <-- parent: home
+│ ├── bidding.md
+│ └── payment.md <-- parent: auctions
+├── books/
+│ ├── _index.md <-- parent: home
+│ ├── book-1.md
+│ └── book-2.md <-- parent: books
+├── films/
+│ ├── _index.md <-- parent: home
+│ ├── film-1.md
+│ └── film-2.md <-- parent: films
+└── _index.md <-- parent: nil
+```
+
+In the example above, note the parent section of the home page is nil. Code defensively by verifying existence of the parent section before calling methods on its `Page` object. To create a link to the parent section page of the current page:
+
+```go-html-template
+{{ with .Parent }}
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+{{ end }}
+```
--- /dev/null
--- /dev/null
++---
++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 %}}
--- /dev/null
- 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.
+---
+title: Plain
+description: Returns the rendered content of the given page, removing all HTML tags.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Content
+ - methods/page/RawContent
+ - methods/page/PlainWords
+ - methods/page/RenderShortcodes
+ returnType: string
+ signatures: [PAGE.Plain]
+---
+
- [`htmlUnescape`]: /functions/
++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.
+
+```go-html-template
+{{ .Plain | htmlUnescape }}
+```
+
+[shortcodes]: /getting-started/glossary/#shortcode
+[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/transform/htmlunescape/
--- /dev/null
- _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._
+---
+title: PlainWords
+description: Calls the Plain method, splits the result into a slice of words, and returns the slice.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Content
+ - methods/page/RawContent
+ - methods/page/Plain
+ returnType: '[]string'
+ signatures: [PAGE.PlainWords]
+---
+
+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 %}}
- [`Plain`]: /methods/page/plain
++_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 %}}
+
+As a result, elements within the slice may contain leading or trailing punctuation.
+
+```go-html-template
+{{ .PlainWords }}
+```
+
+To determine the approximate number of unique words on a page:
+
+```go-html-template
+{{ .PlainWords | uniq }} → 42
+```
+
++[`Plain`]: /methods/page/plain/
+[`strings.Fields`]: https://pkg.go.dev/strings#Fields
--- /dev/null
- [date]: /methods/page/date
- [weight]: /methods/page/weight
- [linkTitle]: /methods/page/linktitle
- [title]: /methods/page/title
+---
+title: PrevInSection
+description: Returns the previous page within a section, relative to the given page.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/NextInSection
+ - methods/page/Next
+ - methods/pages/Next
+ - methods/page/Prev
+ - methods/pages/Prev
+ returnType: page.Page
+ signatures: [PAGE.PrevInSection]
+---
+
+
+The behavior of the `PrevInSection` and `NextInSection` methods on a `Page` object is probably the reverse of what you expect.
+
+With this content structure:
+
+```text
+content/
+├── books/
+│ ├── _index.md
+│ ├── book-1.md
+│ ├── book-2.md
+│ └── book-3.md
+├── films/
+│ ├── _index.md
+│ ├── film-1.md
+│ ├── film-2.md
+│ └── film-3.md
+└── _index.md
+```
+
+When you visit book-2:
+
+- The `PrevInSection` method points to book-3
+- The `NextInSection` method points to book-1
+
+{{% note %}}
+Use the opposite label in your navigation links as shown in the example below.
+{{% /note %}}
+
+```go-html-template
+{{ with .NextInSection }}
+ <a href="{{ .RelPermalink }}">Previous in section</a>
+{{ end }}
+
+{{ with .PrevInSection }}
+ <a href="{{ .RelPermalink }}">Next in section</a>
+{{ end }}
+```
+
+{{% note %}}
+The navigation sort order may be different than the page collection sort order.
+{{% /note %}}
+
+With the `PrevInSection` and `NextInSection` methods, the navigation sort order is fixed, using Hugo’s default sort order. In order of precedence:
+
+1. Page [weight]
+2. Page [date] (descending)
+3. Page [linkTitle], falling back to page [title]
+4. Page file path if the page is backed by a file
+
+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/
--- /dev/null
- [`time.Format`]: /functions/time/format
+---
+title: PublishDate
+description: Returns the publish date of the given page.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Date
+ - methods/page/ExpiryDate
+ - methods/page/LastMod
+ returnType: time.Time
+ signatures: [PAGE.PublishDate]
+---
+
+By default, Hugo excludes pages with future publish dates when building your site. To include future pages, use the `--buildFuture` command line flag.
+
+Set the publish date in front matter:
+
+{{< code-toggle file=content/news/article-1.md fm=true >}}
+title = 'Article 1'
+publishDate = 2023-10-19T00:40:04-07:00
+{{< /code-toggle >}}
+
+The publish date is a [time.Time] value. Format and localize the value with the [`time.Format`] function, or use it with any of the [time methods].
+
+```go-html-template
+{{ .PublishDate | time.Format ":date_medium" }} → Oct 19, 2023
+```
+
+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 methods]: /methods/time
++[`time.Format`]: /functions/time/format/
+[details]: /getting-started/configuration/#configure-dates
++[time methods]: /methods/time/
+[time.Time]: https://pkg.go.dev/time#Time
--- /dev/null
- [`RenderShortcodes`]: /methods/page/rendershortcodes
+---
+title: RawContent
+description: Returns the raw content of the given page.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Content
+ - methods/page/Plain
+ - methods/page/PlainWords
+ - methods/page/RenderShortcodes
+ returnType: string
+ signatures: [PAGE.RawContent]
+---
+
+The `RawContent` method on a `Page` object returns the raw content. The raw content does not include front matter.
+
+```go-html-template
+{{ .RawContent }}
+```
+
+This is useful when rendering a page in a plain text [output format].
+
+{{% note %}}
+[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
- [output format]: /templates/output-formats
++[`RenderShortcodes`]: /methods/page/rendershortcodes/
+{{% /note %}}
+
++[output format]: /templates/output-formats/
--- /dev/null
- [details]: /methods/site/regularpages
+---
+title: RegularPages
+description: Returns a collection of regular pages within the current section.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Pages
+ - methods/page/RegularPagesRecursive
+ returnType: page.Pages
+ signatures: [PAGE.RegularPages]
+---
+
+The `RegularPages` method on a `Page` object is available to these [page kinds]: `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection] in [context].
+
+Range through the page collection in your template:
+
+```go-html-template
+{{ range .RegularPages.ByTitle }}
+ <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
+{{ end }}
+```
+
+Consider this content structure:
+
+```text
+content/
+├── lessons/
+│ ├── lesson-1/
+│ │ ├── _index.md
+│ │ ├── part-1.md
+│ │ └── part-2.md
+│ ├── lesson-2/
+│ │ ├── resources/
+│ │ │ ├── task-list.md
+│ │ │ └── worksheet.md
+│ │ ├── _index.md
+│ │ ├── part-1.md
+│ │ └── part-2.md
+│ ├── _index.md
+│ ├── grading-policy.md
+│ └── lesson-plan.md
+├── _index.md
+├── contact.md
+└── legal.md
+```
+
+When rendering the home page, the `RegularPages` method returns:
+
+ contact.md
+ legal.md
+
+When rendering the lessons page, the `RegularPages` method returns:
+
+ lessons/grading-policy.md
+ lessons/lesson-plan.md
+
+When rendering lesson-1, the `RegularPages` method returns:
+
+ lessons/lesson-1/part-1.md
+ lessons/lesson-1/part-2.md
+
+When rendering lesson-2, the `RegularPages` method returns:
+
+ lessons/lesson-2/part-1.md
+ lessons/lesson-2/part-2.md
+ lessons/lesson-2/resources/task-list.md
+ lessons/lesson-2/resources/worksheet.md
+
+In the last example, the collection includes pages in the resources subdirectory. That directory is not a [section]---it does not contain an _index.md file. Its contents are part of the lesson-2 section.
+
+{{% note %}}
+When used with the `Site` object, the `RegularPages` method recursively returns all regular pages within the site. See [details].
+
++[details]: /methods/site/regularpages/
+{{% /note %}}
+
+```go-html-template
+{{ range .Site.RegularPages.ByTitle }}
+ <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
+{{ end }}
+```
+
+[collection]: /getting-started/glossary/#collection
+[context]: /getting-started/glossary/#context
+[page kinds]: /getting-started/glossary/#page-kind
+[section]: /getting-started/glossary/#section
--- /dev/null
- [content views]: /templates/views
- [`partial`]: /functions/partials/include
+---
+title: Render
+description: Renders the given template with the given page as context.
+categories: []
+keywords: []
+action:
+ related:
+ - functions/partials/Include
+ - functions/partials/IncludeCached
+ returnType: template.HTML
+ signatures: [PAGE.Render NAME]
+aliases: [/functions/render]
+---
+
+Typically used when ranging over a page collection, the `Render` method on a `Page` object renders the given template, passing the given page as context.
+
+```go-html-template
+{{ range site.RegularPages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ .Render "summary" }}
+{{ end }}
+```
+
+In the example above, note that the template ("summary") is identified by its file name without directory or extension.
+
+Although similar to the [`partial`] function, there are key differences.
+
+`Render` method|`partial` function|
+:--|:--
+The `Page` object is automatically passed to the given template. You cannot pass additional context.| You must specify the context, allowing you to pass a combination of objects, slices, maps, and scalars.
+The path to the template is determined by the [content type].|You must specify the path to the template, relative to the layouts/partials directory.
+
+Consider this layout structure:
+
+```text
+layouts/
+├── _default/
+│ ├── baseof.html
+│ ├── home.html
+│ ├── li.html <-- used for other content types
+│ ├── list.html
+│ ├── single.html
+│ └── summary.html
+└── books/
+ ├── li.html <-- used when content type is "books"
+ └── summary.html
+```
+
+And this template:
+
+```go-html-template
+<ul>
+ {{ range site.RegularPages.ByDate }}
+ {{ .Render "li" }}
+ {{ end }}
+</ul>
+```
+
+When rendering content of type "books" the `Render` method calls:
+
+```text
+layouts/books/li.html
+```
+
+For all other content types the `Render` methods calls:
+
+```text
+layouts/_default/li.html
+```
+
+See [content views] for more examples.
+
++[content views]: /templates/views/
++[`partial`]: /functions/partials/include/
+[content type]: /getting-started/glossary/#content-type
--- /dev/null
- {{ $p := site.GetPage (.Get 0) }}
- {{ $p.RenderShortcodes }}
+---
+title: RenderShortcodes
+description: Renders all shortcodes in the content of the given page, preserving the surrounding markup.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/RenderString
+ - methods/page/Content
+ - methods/page/RawContent
+ - methods/page/Plain
+ - methods/page/PlainWords
+ returnType: template.HTML
+ signatures: [PAGE.RenderShortcodes]
+toc: true
+---
+
+{{< new-in 0.117.0 >}}
+
+Use this method in shortcode templates to compose a page from multiple content files, while preserving a global context for footnotes and the table of contents.
+
+For example:
+
+{{< code file=layouts/shortcodes/include.html >}}
- Then in your markdown:
++{{ with site.GetPage (.Get 0) }}
++ {{ .RenderShortcodes }}
++{{ end }}
+{{< /code >}}
+
- Each of the included markdown files can contain calls to other shortcodes.
++Then call the shortcode in your Markdown:
+
+{{< code file=content/about.md lang=md >}}
+{{%/* include "/snippets/services.md" */%}}
+{{%/* include "/snippets/values.md" */%}}
+{{%/* include "/snippets/leadership.md" */%}}
+{{< /code >}}
+
- - `{{%/* myshortcode */%}}` tells Hugo that the rendered shortcode needs further processing. For example, the shortcode content is markdown.
++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:
+
+- `{{</* myshortcode */>}}` tells Hugo that the rendered shortcode does not need further processing. For example, the shortcode content is HTML.
- Note that the shortcode within the content file was rendered, but the surrounding markdown was preserved.
++- `{{%/* 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.
+
+## Further explanation
+
+To understand what is returned by the `RenderShortcodes` method, consider this content file
+
+{{< code file=content/about.md lang=text >}}
++++
+title = 'About'
+date = 2023-10-07T12:28:33-07:00
++++
+
+{{</* ref "privacy" */>}}
+
+An *emphasized* word.
+{{< /code >}}
+
+With this template code:
+
+```go-html-template
+{{ $p := site.GetPage "/about" }}
+{{ $p.RenderShortcodes }}
+```
+
+Hugo renders this:;
+
+```html
+https://example.org/privacy/
+
+An *emphasized* word.
+```
+
++Note that the shortcode within the content file was rendered, but the surrounding Markdown was preserved.
--- /dev/null
- [markup identifier]: /content-management/formats/#list-of-content-formats
+---
+title: RenderString
+description: Renders markup to HTML.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/RenderShortcodes
+ - functions/transform/Markdownify
+ returnType: template.HTML
+ signatures: ['PAGE.RenderString [OPTIONS] MARKUP']
+aliases: [/functions/renderstring]
+---
+
+```go-html-template
+{{ $s := "An *emphasized* word" }}
+{{ $s | .RenderString }} → An <em>emphasized</em> word
+```
+
+This method takes an optional map of options:
+
+display
+: (`string`) Specify either `inline` or `block`. If `inline`, removes surrounding `p` tags from short snippets. Default is `inline`.
+
+markup
+: (`string`) Specify a [markup identifier] for the provided markup. Default is the `markup` front matter value, falling back to the value derived from the page's file extension.
+
+Render with the default markup renderer:
+
+```go-html-template
+{{ $s := "An *emphasized* word" }}
+{{ $s | .RenderString }} → An <em>emphasized</em> word
+
+{{ $opts := dict "display" "block" }}
+{{ $s | .RenderString $opts }} → <p>An <em>emphasized</em> word</p>
+```
+
+Render with [Pandoc]:
+
+```go-html-template
+{{ $s := "H~2~O" }}
+
+{{ $opts := dict "markup" "pandoc" }}
+{{ $s | .RenderString $opts }} → H<sub>2</sub>O
+
+{{ $opts := dict "display" "block" "markup" "pandoc" }}
+{{ .RenderString $opts $s }} → <p>H<sub>2</sub>O</p>
+```
+
++[markup identifier]: /content-management/formats/#classification
+[pandoc]: https://www.pandoc.org/
--- /dev/null
- [`resources.ByType`]: /functions/resources/ByType
- [`resources.GetMatch`]: /functions/resources/ByType
- [`resources.Get`]: /functions/resources/ByType
- [`resources.Match`]: /functions/resources/ByType
- [`resources`]: /functions/resources
+---
+title: Resources
+description: Returns a collection of page resources.
+categories: []
+keywords: []
+action:
+ related:
+ - functions/resources/ByType
+ - functions/resources/Get
+ - functions/resources/GetMatch
+ - functions/resources/GetRemote
+ - functions/resources/Match
+ returnType: resource.Resources
+ signatures: [PAGE.Resources]
+toc: true
+---
+
+The `Resources` method on a `Page` object returns a collection of page resources. A page resource is a file within a [page bundle].
+
+To work with global or remote resources, see the [`resources`] functions.
+
+## Methods
+
+###### ByType
+
+(`resource.Resources`) Returns a collection of page resources of the given [media type], or nil if none found. The media type is typically one of `image`, `text`, `audio`, `video`, or `application`.
+
+```go-html-template
+{{ range .Resources.ByType "image" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+When working with global resources instead of page resources, use the [`resources.ByType`] function.
+
+###### Get
+
+(`resource.Resource`) Returns a page resource from the given path, or nil if none found.
+
+```go-html-template
+{{ with .Resources.Get "images/a.jpg" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+When working with global resources instead of page resources, use the [`resources.Get`] function.
+
+###### GetMatch
+
+(`resource.Resource`) Returns the first page resource from paths matching the given [glob pattern], or nil if none found.
+
+```go-html-template
+{{ with .Resources.GetMatch "images/*.jpg" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+When working with global resources instead of page resources, use the [`resources.GetMatch`] function.
+
+###### Match
+
+(`resource.Resources`) Returns a collection of page resources from paths matching the given [glob pattern], or nil if none found.
+
+```go-html-template
+{{ range .Resources.Match "images/*.jpg" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+When working with global resources instead of page resources, use the [`resources.Match`] function.
+
+## Pattern matching
+
+With the `GetMatch` and `Match` methods, Hugo determines a match using a case-insensitive [glob pattern].
+
+{{% 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/
+[glob pattern]: https://github.com/gobwas/glob#example
+[media type]: https://en.wikipedia.org/wiki/Media_type
+[page bundle]: /getting-started/glossary/#page-bundle
--- /dev/null
- description: Creates a "scratch pad" on the given page to store and manipulate data.
+---
+title: Scratch
- [`Store`]: /methods/page/store
- [`newScratch`]: functions/collections/newscratch
++description: Returns a "scratch pad" on the given page to store and manipulate data.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Store
+ - functions/collections/NewScratch
+ returnType: maps.Scratch
+ signatures: [PAGE.Scratch]
++toc: true
+aliases: [/extras/scratch/,/doc/scratch/,/functions/scratch]
+---
+
+The `Scratch` method on a `Page` object creates a [scratch pad] to store and manipulate data. To create a scratch pad that is not reset on server rebuilds, use the [`Store`] method instead.
+
+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/
+[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" }}
++```
--- /dev/null
- [`where`]: /functions/collections/where
- [`Type`]: /methods/page/type
+---
+title: Section
+description: Returns the name of the top level section in which the given page resides.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Type
+ returnType: string
+ signatures: [PAGE.Section]
+---
+
+With this content structure:
+
+```text
+content/
+├── lessons/
+│ ├── math/
+│ │ ├── _index.md
+│ │ ├── lesson-1.md
+│ │ └── lesson-2.md
+│ └── _index.md
+└── _index.md
+```
+
+When rendering lesson-1.md:
+
+```go-html-template
+{{ .Section }} → lessons
+```
+
+In the example above "lessons" is the top level section.
+
+The `Section` method is often used with the [`where`] function to build a page collection.
+
+```go-html-template
+{{ range where .Site.RegularPages "Section" "lessons" }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+This is similar to using the [`Type`] method with the `where` function
+
+```go-html-template
+{{ range where .Site.RegularPages "Type" "lessons" }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+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/
--- /dev/null
- │ ├── _index.md <-- front matter: weight = 10
+---
+title: Sections
+description: Returns a collection of section pages, one for each immediate descendant section of the given page.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Ancestors
+ - methods/page/CurrentSection
+ - methods/page/FirstSection
+ - methods/page/InSection
+ - methods/page/IsAncestor
+ - methods/page/IsDescendant
+ - methods/page/Parent
+ returnType: page.Pages
+ signatures: [PAGE.Sections]
+---
+
+{{% include "methods/page/_common/definition-of-section.md" %}}
+
+With this content structure:
+
+```text
+content/
+├── auctions/
+│ ├── 2023-11/
+│ │ ├── _index.md <-- front matter: weight = 202311
+│ │ ├── auction-1.md
+│ │ └── auction-2.md
+│ ├── 2023-12/
+│ │ ├── _index.md <-- front matter: weight = 202312
+│ │ ├── auction-3.md
+│ │ └── auction-4.md
+│ ├── _index.md <-- front matter: weight = 30
+│ ├── bidding.md
+│ └── payment.md
+├── books/
- │ ├── _index.md <-- front matter: weight = 20
++│ ├── _index.md <-- front matter: weight = 20
+│ ├── book-1.md
+│ └── book-2.md
+├── films/
++│ ├── _index.md <-- front matter: weight = 10
+│ ├── film-1.md
+│ └── film-2.md
+└── _index.md
+```
+
+And this template:
+
+```go-html-template
+{{ range .Sections.ByWeight }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+On the home page, Hugo renders:
+
+```html
+<h2><a href="/films/">Films</a></h2>
+<h2><a href="/books/">Books</a></h2>
+<h2><a href="/auctions/">Auctions</a></h2>
+```
+
+On the auctions page, Hugo renders:
+
+```html
+<h2><a href="/auctions/2023-11/">Auctions in November 2023</a></h2>
+<h2><a href="/auctions/2023-12/">Auctions in December 2023</a></h2>
+```
--- /dev/null
- [Site methods]: /methods/site
+---
+title: Site
+description: Returns the Site object.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Sites
+ returnType: page.siteWrapper
+ signatures: [PAGE.Site]
+---
+
+See [Site methods].
+
++[Site methods]: /methods/site/
+
+```go-html-template
+{{ .Site.Title }}
+```
--- /dev/null
- 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).
+---
+title: Sitemap
+description: Returns the sitemap settings for the given page as defined in front matter, falling back to the sitemap settings as defined in the site configuration.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: config.SitemapConfig
+ signatures: [PAGE.Sitemap]
+toc: true
+---
+
+Access to the `Sitemap` method on a `Page` object is restricted to [sitemap templates].
+
+## Methods
+
- 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).
++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 }}
+```
+
++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 }}
+```
+
+## Example
+
+With this site configuration:
+
+{{< code-toggle file=hugo >}}
+[sitemap]
+changeFreq = 'monthly'
+{{< /code-toggle >}}
+
+And this content:
+
+{{< code-toggle file=content/news.md fm=true >}}
+title = 'News'
+[sitemap]
+changeFreq = 'hourly'
+{{< /code-toggle >}}
+
+And this simplistic sitemap template:
+
+{{< code file=layouts/_default/sitemap.xml >}}
+{{ printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>" | safeHTML }}
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
+ xmlns:xhtml="http://www.w3.org/1999/xhtml">
+ {{ range .Pages }}
+ <url>
+ <loc>{{ .Permalink }}</loc>
+ {{ if not .Lastmod.IsZero }}
+ <lastmod>{{ .Lastmod.Format "2006-01-02T15:04:05-07:00" | safeHTML }}</lastmod>
+ {{ end }}
+ {{ with .Sitemap.ChangeFreq }}
+ <changefreq>{{ . }}</changefreq>
+ {{ end }}
+ </url>
+ {{ end }}
+</urlset>
+{{< /code >}}
+
+The change frequency will be `hourly` for the news page, and `monthly` for other pages.
+
+[sitemap templates]: /templates/sitemap-template/
--- /dev/null
- To render a link to home page of the primary (first) language:
+---
+title: Sites
+description: Returns a collection of all Site objects, one for each language, ordered by language weight.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Site
+ returnType: page.Sites
+ signatures: [PAGE.Sites]
+---
+
+This is a convenience method to access `.Site.Sites`.
+
+With this site configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = false
+
+[languages.de]
+languageCode = 'de-DE'
+languageDirection = 'ltr'
+languageName = 'Deutsch'
+title = 'Projekt Dokumentation'
+weight = 1
+
+[languages.en]
+languageCode = 'en-US'
+languageDirection = 'ltr'
+languageName = 'English'
+title = 'Project Documentation'
+weight = 2
+{{< /code-toggle >}}
+
+This template:
+
+```go-html-template
+<ul>
+ {{ range .Sites }}
+ <li><a href="{{ .Home.Permalink }}">{{ .Title }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Produces a list of links to each home page:
+
+```html
+<ul>
+ <li><a href="https://example.org/de/">Projekt Dokumentation</a></li>
+ <li><a href="https://example.org/en/">Project Documentation</a></li>
+</ul>
+```
+
- {{ with .Sites.First }}
++To render a link to the home page of the site corresponding to the default content language:
+
+```go-html-template
++{{ with .Sites.Default }}
+ <a href="{{ .Home.Permalink }}">{{ .Title }}</a>
+{{ end }}
+```
+
+This is equivalent to:
+
+```go-html-template
+{{ with index .Sites 0 }}
+ <a href="{{ .Home.Permalink }}">{{ .Title }}</a>
+{{ end }}
+```
--- /dev/null
- description: Creates a persistent "scratch pad" on the given page to store and manipulate data.
+---
+title: Store
- [`Scratch`]: /methods/page/scratch
- [`newScratch`]: functions/collections/newscratch
++description: Returns a persistent "scratch pad" on the given page to store and manipulate data.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/scratch
+ - functions/collections/NewScratch
+ returnType: maps.Scratch
+ signatures: [PAGE.Store]
++toc: true
+aliases: [/functions/store]
+---
+
+The `Store` method on a `Page` object creates a persistent [scratch pad] to store and manipulate data. In contrast with the [`Scratch`] method, the scratch pad created by the `Store` method is not reset on server rebuilds.
+
+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 pad]: /getting-started/glossary/#scratch-pad
+
+## Methods
+
+###### Set
+
+Sets the value of a given key.
+
+```go-html-template
+{{ .Store.Set "greeting" "Hello" }}
+```
+
+###### Get
+
+Gets the value of a given key.
+
+```go-html-template
+{{ .Store.Set "greeting" "Hello" }}
+{{ .Store.Get "greeting" }} → Hello
+```
+
+###### Add
+
+Adds a given value to existing value(s) of the given key.
+
+For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list.
+
+```go-html-template
+{{ .Store.Set "greeting" "Hello" }}
+{{ .Store.Add "greeting" "Welcome" }}
+{{ .Store.Get "greeting" }} → HelloWelcome
+```
+
+```go-html-template
+{{ .Store.Set "total" 3 }}
+{{ .Store.Add "total" 7 }}
+{{ .Store.Get "total" }} → 10
+```
+
+```go-html-template
+{{ .Store.Set "greetings" (slice "Hello") }}
+{{ .Store.Add "greetings" (slice "Welcome" "Cheers") }}
+{{ .Store.Get "greetings" }} → [Hello Welcome Cheers]
+```
+
+###### SetInMap
+
+Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`.
+
+```go-html-template
+{{ .Store.SetInMap "greetings" "english" "Hello" }}
+{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
+{{ .Store.Get "greetings" }} → map[english:Hello french:Bonjour]
+```
+
+###### DeleteInMap
+
+Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
+
+```go-html-template
+{{ .Store.SetInMap "greetings" "english" "Hello" }}
+{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
+{{ .Store.DeleteInMap "greetings" "english" }}
+{{ .Store.Get "greetings" }} → map[french:Bonjour]
+```
+
+###### GetSortedMapValues
+
+Returns an array of values from `key` sorted by `mapKey`.
+
+```go-html-template
+{{ .Store.SetInMap "greetings" "english" "Hello" }}
+{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
+{{ .Store.GetSortedMapValues "greetings" }} → [Hello Bonjour]
+```
+
+###### Delete
+
+Removes the given key.
+
+```go-html-template
+{{ .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" }}
++```
--- /dev/null
- 2. Manually split the content with a `<--more-->` tag in markdown. Everything before the tag is included in the summary.
+---
+title: Summary
+description: Returns the content summary of the given page.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Truncated
+ - methods/page/Description
+ returnType: template.HTML
+ signatures: [PAGE.Summary]
+---
+
++<!-- Do not remove the manual summary divider below. -->
++<!-- If you do, you will break its first literal usage on this page. -->
++<!--more-->
++
+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.
- [content summary]: /content-management/summaries
++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.
+
+To list the pages in a section with a summary beneath each link:
+
+```go-html-template
+{{ range .Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ .Summary }}
+{{ end }}
+```
+
++[content summary]: /content-management/summaries/
--- /dev/null
- The `TableOfContents` method on a `Page` object returns an ordered or unordered list of the markdown [ATX] and [setext] headings within the page content.
+---
+title: TableOfContents
+description: Returns a table of contents for the given page.
+categories: []
+keywords: []
+action:
+ related:
+ - 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.
+
+[atx]: https://spec.commonmark.org/0.30/#atx-headings
+[setext]: https://spec.commonmark.org/0.30/#setext-headings
+
+This template code:
+
+```go-html-template
+{{ .TableOfContents }}
+```
+
+Produces this HTML:
+
+```html
+<nav id="TableOfContents">
+ <ul>
+ <li><a href="#section-1">Section 1</a>
+ <ul>
+ <li><a href="#section-11">Section 1.1</a></li>
+ <li><a href="#section-12">Section 1.2</a></li>
+ </ul>
+ </li>
+ <li><a href="#section-2">Section 2</a></li>
+ </ul>
+</nav>
+```
+
+By default, the `TableOfContents` method returns an unordered list of level 2 and level 3 headings. You can adjust this in your site configuration:
+
+{{< code-toggle file=hugo >}}
+[markup.tableOfContents]
+endLevel = 3
+ordered = false
+startLevel = 2
+{{< /code-toggle >}}
--- /dev/null
- With section pages not backed by a file, the `Title` method returns the section name, pluralized and converted to title case.
-
- To disable [pluralization]:
+---
+title: Title
+description: Returns the title of the given page.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/LinkTitle
+ returnType: string
+ signatures: [PAGE.Title]
+---
+
+With pages backed by a file, the `Title` method returns the `title` field as defined in front matter:
+
+{{< code-toggle file=content/about.md fm=true >}}
+title = 'About us'
+{{< /code-toggle >}}
+
+```go-html-template
+{{ .Title }} → About us
+```
+
- To change the [title case style], specify one of `ap`, `chicago`, `go`, `firstupper`, or `none`:
++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 >}}
+
- titleCaseStyle = "ap"
++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 >}}
- [pluralization]: /functions/inflect/pluralize
- [title case style]: /getting-started/configuration/#configure-title-case
++titleCaseStyle = "firstupper"
+{{< /code-toggle >}}
+
++ See [details].
++
++[`capitalizeListTitles`]: /getting-started/configuration/#capitalizelisttitles
++[`pluralizeListTitles`]: /getting-started/configuration/#pluralizelisttitles
++[details]: /getting-started/configuration/#configure-title-case
--- /dev/null
- description: Returns all translation of the given page, excluding the current language.
+---
+title: Translations
- {{ $langName := or .Language.LanguageName .Language.Lang }}
- {{ $langCode := or .Language.LanguageCode .Language.Lang }}
- <li><a href="{{ .RelPermalink }}" hreflang="{{ $langCode }}">{{ .LinkTitle }} ({{ $langName }})</a></li>
++description: Returns all translations of the given page, excluding the current language.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/AllTranslations
+ - methods/page/IsTranslated
+ - methods/page/TranslationKey
+ returnType: page.Pages
+ signatures: [PAGE.Translations]
+---
+
+With this site configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'en'
+
+[languages.en]
+contentDir = 'content/en'
+languageCode = 'en-US'
+languageName = 'English'
+weight = 1
+
+[languages.de]
+contentDir = 'content/de'
+languageCode = 'de-DE'
+languageName = 'Deutsch'
+weight = 2
+
+[languages.fr]
+contentDir = 'content/fr'
+languageCode = 'fr-FR'
+languageName = 'Français'
+weight = 3
+{{< /code-toggle >}}
+
+And this content:
+
+```text
+content/
+├── de/
+│ ├── books/
+│ │ ├── book-1.md
+│ │ └── book-2.md
+│ └── _index.md
+├── en/
+│ ├── books/
+│ │ ├── book-1.md
+│ │ └── book-2.md
+│ └── _index.md
+├── fr/
+│ ├── books/
+│ │ └── book-1.md
+│ └── _index.md
+└── _index.md
+```
+
+And this template:
+
+```go-html-template
+{{ with .Translations }}
+ <ul>
+ {{ range . }}
++ <li>
++ <a href="{{ .RelPermalink }}" hreflang="{{ .Language.LanguageCode }}">{{ .LinkTitle }} ({{ or .Language.LanguageName .Language.Lang }})</a>
++ </li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+Hugo will render this list on the "Book 1" page of the English site:
+
+```html
+<ul>
+ <li><a href="/de/books/book-1/" hreflang="de-DE">Book 1 (Deutsch)</a></li>
+ <li><a href="/fr/books/book-1/" hreflang="fr-FR">Book 1 (Français)</a></li>
+</ul>
+```
+
+Hugo will render this list on the "Book 2" page of the English site:
+
+```html
+<ul>
+ <li><a href="/de/books/book-1/" hreflang="de-DE">Book 1 (Deutsch)</a></li>
+</ul>
+```
--- /dev/null
- 2. Manually split the content with a `<--more-->` tag in markdown. Everything before the tag is included in the summary.
+---
+title: Truncated
+description: Reports whether the content length exceeds the summary length.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Summary
+ returnType: bool
+ signatures: [PAGE.Truncated]
+---
+
+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.
- [content summary]: /content-management/summaries
++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 %}}
+The `Truncated` method returns `false` if you define the summary in front matter.
+{{% /note %}}
+
+The `Truncated` method returns `true` if the content length exceeds the summary length. This is useful for rendering a "read more" link:
+
+```go-html-template
+{{ range .Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ .Summary }}
+ {{ if .Truncated }}
+ <a href="{{ .RelPermalink }}">Read more...</a>
+ {{ end }}
+{{ end }}
+```
+
++[content summary]: /content-management/summaries/
--- /dev/null
- [`FuzzyWordCount`]: /methods/page/fuzzywordcount
+---
+title: WordCount
+description: Returns the number of words in the content of the given page.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/FuzzyWordCount
+ - methods/page/ReadingTime
+ returnType: int
+ signatures: [PAGE.WordCount]
+---
+
+```go-html-template
+{{ .WordCount }} → 103
+```
+
+To round up to nearest multiple of 100, use the [`FuzzyWordCount`] method.
+
++[`FuzzyWordCount`]: /methods/page/fuzzywordcount/
--- /dev/null
- Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+---
+cascade:
+ _build:
+ list: never
+ publishResources: false
+ render: never
+---
+
+<!--
++Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+
+Include the rendered content using the "include" shortcode.
+-->
--- /dev/null
- [details]: /templates/output-formats
+---
+# Do not remove front matter.
+---
+
+Hugo generates one or more files per page when building a site. For example, when rendering home, [section], [taxonomy], and [term] pages, Hugo generates an HTML file and an RSS file. Both HTML and RSS are built-in _output formats_. Create multiple output formats, and control generation based on [page kind], or by enabling one or more output formats for one or more pages. See [details].
+
+[section]: /getting-started/glossary/#section
+[taxonomy]: /getting-started/glossary/#taxonomy
+[term]: /getting-started/glossary/#term
+[page kind]: /getting-started/glossary/#page-kind
++[details]: /templates/output-formats/
--- /dev/null
--- /dev/null
++---
++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 }}
++ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
++{{ end }}
++
++{{ with $paginator }}
++ <ul>
++ {{ with .First }}
++ <li><a href="{{ .URL }}">First</a></li>
++ {{ end }}
++ {{ with .Prev }}
++ <li><a href="{{ .URL }}">Previous</a></li>
++ {{ end }}
++ {{ with .Next }}
++ <li><a href="{{ .URL }}">Next</a></li>
++ {{ end }}
++ {{ with .Last }}
++ <li><a href="{{ .URL }}">Last</a></li>
++ {{ end }}
++ </ul>
++{{ end }}
++```
--- /dev/null
--- /dev/null
++---
++title: HasNext
++description: Reports whether there is a pager after the current pager.
++categories: []
++keywords: []
++action:
++ related:
++ - methods/pager/HasPrev
++ - methods/pager/Prev
++ - methods/pager/Next
++ - methods/pager/First
++ - methods/pager/Last
++ - methods/page/Paginate
++ returnType: bool
++ signatures: [PAGER.HasNext]
++---
++
++Use the `HasNext` method to build navigation between pagers.
++
++```go-html-template
++{{ $pages := where site.RegularPages "Type" "posts" }}
++{{ $paginator := .Paginate $pages }}
++
++{{ range $paginator.Pages }}
++ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
++{{ end }}
++
++{{ with $paginator }}
++ <ul>
++ {{ with .First }}
++ <li><a href="{{ .URL }}">First</a></li>
++ {{ end }}
++ {{ if .HasPrev }}
++ <li><a href="{{ .Prev.URL }}">Previous</a></li>
++ {{ end }}
++ {{ if .HasNext }}
++ <li><a href="{{ .Next.URL }}">Next</a></li>
++ {{ end }}
++ {{ with .Last }}
++ <li><a href="{{ .URL }}">Last</a></li>
++ {{ end }}
++ </ul>
++{{ 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 }}
++ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
++{{ end }}
++
++{{ with $paginator }}
++ <ul>
++ {{ with .First }}
++ <li><a href="{{ .URL }}">First</a></li>
++ {{ end }}
++ {{ with .Prev }}
++ <li><a href="{{ .URL }}">Previous</a></li>
++ {{ end }}
++ {{ with .Next }}
++ <li><a href="{{ .URL }}">Next</a></li>
++ {{ end }}
++ {{ with .Last }}
++ <li><a href="{{ .URL }}">Last</a></li>
++ {{ end }}
++ </ul>
++{{ end }}
++```
--- /dev/null
--- /dev/null
++---
++title: HasPrev
++description: Reports whether there is a pager before the current pager.
++categories: []
++keywords: []
++action:
++ related:
++ - methods/pager/HasNext
++ - methods/pager/Prev
++ - methods/pager/Next
++ - methods/pager/First
++ - methods/pager/Last
++ - methods/page/Paginate
++ returnType: bool
++ signatures: [PAGER.HasPrev]
++---
++
++Use the `HasPrev` method to build navigation between pagers.
++
++```go-html-template
++{{ $pages := where site.RegularPages "Type" "posts" }}
++{{ $paginator := .Paginate $pages }}
++
++{{ range $paginator.Pages }}
++ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
++{{ end }}
++
++{{ with $paginator }}
++ <ul>
++ {{ with .First }}
++ <li><a href="{{ .URL }}">First</a></li>
++ {{ end }}
++ {{ if .HasPrev }}
++ <li><a href="{{ .Prev.URL }}">Previous</a></li>
++ {{ end }}
++ {{ if .HasNext }}
++ <li><a href="{{ .Next.URL }}">Next</a></li>
++ {{ end }}
++ {{ with .Last }}
++ <li><a href="{{ .URL }}">Last</a></li>
++ {{ end }}
++ </ul>
++{{ 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 }}
++ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
++{{ end }}
++
++{{ with $paginator }}
++ <ul>
++ {{ with .First }}
++ <li><a href="{{ .URL }}">First</a></li>
++ {{ end }}
++ {{ with .Prev }}
++ <li><a href="{{ .URL }}">Previous</a></li>
++ {{ end }}
++ {{ with .Next }}
++ <li><a href="{{ .URL }}">Next</a></li>
++ {{ end }}
++ {{ with .Last }}
++ <li><a href="{{ .URL }}">Last</a></li>
++ {{ end }}
++ </ul>
++{{ end }}
++```
--- /dev/null
--- /dev/null
++---
++title: Last
++description: Returns the last pager in the pager collection.
++categories: []
++keywords: []
++action:
++ related:
++ - methods/pager/First
++ - methods/pager/Prev
++ - methods/pager/Next
++ - methods/pager/HasPrev
++ - methods/pager/HasNext
++ - methods/page/Paginate
++ returnType: page.Pager
++ signatures: [PAGER.Last]
++---
++
++Use the `Last` method to build navigation between pagers.
++
++```go-html-template
++{{ $pages := where site.RegularPages "Type" "posts" }}
++{{ $paginator := .Paginate $pages }}
++
++{{ range $paginator.Pages }}
++ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
++{{ end }}
++
++{{ with $paginator }}
++ <ul>
++ {{ with .First }}
++ <li><a href="{{ .URL }}">First</a></li>
++ {{ end }}
++ {{ with .Prev }}
++ <li><a href="{{ .URL }}">Previous</a></li>
++ {{ end }}
++ {{ with .Next }}
++ <li><a href="{{ .URL }}">Next</a></li>
++ {{ end }}
++ {{ with .Last }}
++ <li><a href="{{ .URL }}">Last</a></li>
++ {{ end }}
++ </ul>
++{{ end }}
++```
--- /dev/null
--- /dev/null
++---
++title: Next
++description: Returns the next pager in the pager collection.
++categories: []
++keywords: []
++action:
++ related:
++ - methods/pager/Prev
++ - methods/pager/HasPrev
++ - methods/pager/HasNext
++ - methods/pager/First
++ - methods/pager/Last
++ - methods/page/Paginate
++ returnType: page.Pager
++ signatures: [PAGER.Next]
++---
++
++Use the `Next` method to build navigation between pagers.
++
++```go-html-template
++{{ $pages := where site.RegularPages "Type" "posts" }}
++{{ $paginator := .Paginate $pages }}
++
++{{ range $paginator.Pages }}
++ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
++{{ end }}
++
++{{ with $paginator }}
++ <ul>
++ {{ with .First }}
++ <li><a href="{{ .URL }}">First</a></li>
++ {{ end }}
++ {{ with .Prev }}
++ <li><a href="{{ .URL }}">Previous</a></li>
++ {{ end }}
++ {{ with .Next }}
++ <li><a href="{{ .URL }}">Next</a></li>
++ {{ end }}
++ {{ with .Last }}
++ <li><a href="{{ .URL }}">Last</a></li>
++ {{ end }}
++ </ul>
++{{ end }}
++```
--- /dev/null
--- /dev/null
++---
++title: NumberOfElements
++description: Returns the number of pages in the current pager.
++categories: []
++keywords: []
++action:
++ related:
++ - methods/pager/TotalNumberOfElements
++ - methods/page/Paginate
++ returnType: int
++ signatures: [PAGER.NumberOfElements]
++---
++
++```go-html-template
++{{ $pages := where site.RegularPages "Type" "posts" }}
++{{ $paginator := .Paginate $pages }}
++
++{{ range $paginator.Pages }}
++ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
++{{ end }}
++
++{{ with $paginator }}
++ {{ .NumberOfElements }}
++{{ end }}
++```
--- /dev/null
--- /dev/null
++---
++title: PageGroups
++description: Returns the page groups in the current pager.
++categories: []
++keywords: []
++action:
++ related:
++ - methods/page/Paginate
++ returnType: page.PagesGroup
++ signatures: [PAGER.PageGroups]
++---
++
++Use the `PageGroups` method with any of the [grouping methods].
++
++[grouping methods]: /quick-reference/page-collections/#group
++
++```go-html-template
++{{ $pages := where site.RegularPages "Type" "posts" }}
++{{ $paginator := .Paginate ($pages.GroupByDate "Jan 2006") }}
++
++{{ range $paginator.PageGroups }}
++ <h2>{{ .Key }}</h2>
++ {{ range .Pages }}
++ <h3><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h3>
++ {{ end }}
++{{ end }}
++
++{{ template "_internal/pagination.html" . }}
++```
--- /dev/null
--- /dev/null
++---
++title: PageNumber
++description: Returns the current pager's number within the pager collection.
++categories: []
++keywords: []
++action:
++ related:
++ - methods/pager/TotalPages
++ - methods/page/Paginate
++ returnType: int
++ signatures: [PAGER.PageNumber]
++---
++
++Use the `PageNumber` method to build navigation between pagers.
++
++```go-html-template
++{{ $pages := where site.RegularPages "Type" "posts" }}
++{{ $paginator := .Paginate $pages }}
++
++{{ range $paginator.Pages }}
++ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
++{{ end }}
++
++{{ with $paginator }}
++ <ul>
++ {{ range .Pagers }}
++ <li><a href="{{ .URL }}">{{ .PageNumber }}</a></li>
++ {{ end }}
++ </ul>
++{{ end }}
++```
--- /dev/null
--- /dev/null
++---
++title: PageSize
++description: Returns the maximum number of pages per pager.
++categories: []
++keywords: []
++action:
++ related:
++ - methods/page/Paginate
++ returnType: int
++ signatures: [PAGER.PageSize]
++---
++
++```go-html-template
++{{ $pages := where site.RegularPages "Type" "posts" }}
++{{ $paginator := .Paginate $pages }}
++
++{{ range $paginator.Pages }}
++ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
++{{ end }}
++
++{{ with $paginator }}
++ {{ .PageSize }}
++{{ end }}
++```
--- /dev/null
--- /dev/null
++---
++title: Pagers
++description: Returns the pagers collection.
++categories: []
++keywords: []
++action:
++ related:
++ - methods/page/Paginate
++ returnType: page.pagers
++ signatures: [PAGER.Pagers]
++---
++
++Use the `Pagers` method to build navigation between pagers.
++
++```go-html-template
++{{ $pages := where site.RegularPages "Type" "posts" }}
++{{ $paginator := .Paginate $pages }}
++
++{{ range $paginator.Pages }}
++ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
++{{ end }}
++
++{{ with $paginator }}
++ <ul>
++ {{ range .Pagers }}
++ <li><a href="{{ .URL }}">{{ .PageNumber }}</a></li>
++ {{ end }}
++ </ul>
++{{ end }}
++```
--- /dev/null
--- /dev/null
++---
++title: Pages
++description: Returns the pages in the current pager.
++categories: []
++keywords: []
++action:
++ related:
++ - methods/page/Paginate
++ returnType: page.Pages
++ signatures: [PAGER.Pages]
++---
++
++```go-html-template
++{{ $pages := where site.RegularPages "Type" "posts" }}
++{{ $paginator := .Paginate $pages }}
++
++{{ range $paginator.Pages }}
++ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
++{{ end }}
++
++{{ template "_internal/pagination.html" . }}
++```
--- /dev/null
--- /dev/null
++---
++title: Prev
++description: Returns the previous pager in the pager collection.
++categories: []
++keywords: []
++action:
++ related:
++ - methods/pager/Next
++ - methods/pager/HasPrev
++ - methods/pager/HasNext
++ - methods/pager/First
++ - methods/pager/Last
++ - methods/page/Paginate
++ returnType: page.Pager
++ signatures: [PAGER.Prev]
++---
++
++Use the `Prev` method to build navigation between pagers.
++
++```go-html-template
++{{ $pages := where site.RegularPages "Type" "posts" }}
++{{ $paginator := .Paginate $pages }}
++
++{{ range $paginator.Pages }}
++ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
++{{ end }}
++
++{{ with $paginator }}
++ <ul>
++ {{ with .First }}
++ <li><a href="{{ .URL }}">First</a></li>
++ {{ end }}
++ {{ with .Prev }}
++ <li><a href="{{ .URL }}">Previous</a></li>
++ {{ end }}
++ {{ with .Next }}
++ <li><a href="{{ .URL }}">Next</a></li>
++ {{ end }}
++ {{ with .Last }}
++ <li><a href="{{ .URL }}">Last</a></li>
++ {{ end }}
++ </ul>
++{{ end }}
++```
--- /dev/null
--- /dev/null
++---
++title: TotalNumberOfElements
++description: Returns the number of pages in the pager collection.
++categories: []
++keywords: []
++action:
++ related:
++ - methods/pager/NumberOfElements
++ - methods/page/Paginate
++ returnType: int
++ signatures: [PAGER.TotalNumberOfElements]
++---
++
++```go-html-template
++{{ $pages := where site.RegularPages "Type" "posts" }}
++{{ $paginator := .Paginate $pages }}
++
++{{ range $paginator.Pages }}
++ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
++{{ end }}
++
++{{ with $paginator }}
++ {{ .TotalNumberOfElements }}
++{{ end }}
++```
--- /dev/null
--- /dev/null
++---
++title: TotalPages
++description: Returns the number of pagers in the pager collection.
++categories: []
++keywords: []
++action:
++ related:
++ - methods/pager/PageNumber
++ - methods/page/Paginate
++ returnType: int
++ signatures: [PAGER.TotalPages]
++---
++
++Use the `TotalPages` method to build navigation between pagers.
++
++```go-html-template
++{{ $pages := where site.RegularPages "Type" "posts" }}
++{{ $paginator := .Paginate $pages }}
++
++{{ range $paginator.Pages }}
++ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
++{{ end }}
++
++{{ with $paginator }}
++ <p>Pager {{ .PageNumber }} of {{ .TotalPages }}</p>
++ <ul>
++ {{ with .First }}
++ <li><a href="{{ .URL }}">First</a></li>
++ {{ end }}
++ {{ with .Prev }}
++ <li><a href="{{ .URL }}">Previous</a></li>
++ {{ end }}
++ {{ with .Next }}
++ <li><a href="{{ .URL }}">Next</a></li>
++ {{ end }}
++ {{ with .Last }}
++ <li><a href="{{ .URL }}">Last</a></li>
++ {{ end }}
++ </ul>
++{{ end }}
++```
--- /dev/null
--- /dev/null
++---
++title: URL
++description: Returns the URL of the current pager relative to the site root.
++categories: []
++keywords: []
++action:
++ related:
++ - methods/page/Paginate
++ returnType: string
++ signatures: [PAGER.URL]
++---
++
++Use the `URL` method to build navigation between pagers.
++
++```go-html-template
++{{ $pages := where site.RegularPages "Type" "posts" }}
++{{ $paginator := .Paginate $pages }}
++
++{{ range $paginator.Pages }}
++ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
++{{ end }}
++
++{{ with $paginator }}
++ <ul>
++ {{ with .First }}
++ <li><a href="{{ .URL }}">First</a></li>
++ {{ end }}
++ {{ with .Prev }}
++ <li><a href="{{ .URL }}">Previous</a></li>
++ {{ end }}
++ {{ with .Next }}
++ <li><a href="{{ .URL }}">Next</a></li>
++ {{ end }}
++ {{ with .Last }}
++ <li><a href="{{ .URL }}">Last</a></li>
++ {{ end }}
++ </ul>
++{{ end }}
++```
--- /dev/null
--- /dev/null
++---
++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/
--- /dev/null
- Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+---
+cascade:
+ _build:
+ list: never
+ publishResources: false
+ render: never
+---
+
+<!--
++Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+
+Include the rendered content using the "include" shortcode.
+-->
--- /dev/null
- returnType: '[]string'
+---
+title: Colors
+description: Applicable to images, returns a slice of the most dominant colors using a simple histogram method.
+categories: []
+keywords: []
+action:
+ related: []
- {{ .Colors }} → [#bebebd #514947 #768a9a #647789 #90725e #a48974]
++ 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" }}
- 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.
++ <table>
++ <thead>
++ <tr>
++ <th>Color</th>
++ <th>Relative luminance</th>
++ </tr>
++ </thead>
++ <tbody>
++ {{ range .Colors }}
++ <tr>
++ <td>{{ .ColorHex }}</td>
++ <td>{{ .Luminance | lang.FormatNumber 4 }}</td>
++ </tr>
++ {{ end }}
++ </tbody>
++ </table>
+{{ end }}
+```
+
- {{% include "methods/resource/_common/global-page-remote-resources.md" %}}
++Hugo renders this to:
+
++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 }}
++ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
++ {{ 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 }}
++ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
++ {{ 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 }}
++ <div style="background: {{ $darkest }};">
++ <div style="color: {{ $lightest }};">
++ <p>This is light text on a dark background.</p>
++ </div>
++ </div>
++{{ 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
--- /dev/null
- [resource type]: /methods/resource/resourcetype
+---
+title: Content
+description: Returns the content of the given resource.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: any
+ signatures: [RESOURCE.Content]
+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/
+
+{{< code file=assets/quotations/kipling.txt >}}
+He travels the fastest who travels alone.
+{{< /code >}}
+
+To get the content:
+
+```go-html-template
+{{ with resources.Get "quotations/kipling.txt" }}
+ {{ .Content }} → He travels the fastest who travels alone.
+{{ end }}
+```
+
+To get the size in bytes:
+
+```go-html-template
+{{ with resources.Get "quotations/kipling.txt" }}
+ {{ .Content | len }} → 42
+{{ end }}
+```
+
+To create an inline image:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ <img src="data:{{ .MediaType.Type }};base64,{{ .Content | base64Encode }}">
+{{ end }}
+```
+
+To create inline CSS:
+
+```go-html-template
+{{ with resources.Get "css/style.css" }}
+ <style>{{ .Content | safeCSS }}</style>
+{{ end }}
+```
+
+To create inline JavaScript:
+
+```go-html-template
+{{ with resources.Get "js/script.js" }}
+ <script>{{ .Content | safeJS }}</script>
+{{ end }}
+```
+
+{{% include "methods/resource/_common/global-page-remote-resources.md" %}}
--- /dev/null
- [`resources.GetRemote`]: functions/resources/getremote
+---
+title: Data
+description: Applicable to resources returned by the resources.GetRemote function, returns information from the HTTP response.
+categories: []
+keywords: []
+action:
+ related:
+ - functions/resources/GetRemote
+ - methods/resource/Err
+ returnType: map
+ signatures: [RESOURCE.Data]
+---
+
+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" }}
+{{ with resources.GetRemote $url }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else }}
+ {{ with .Data }}
+ {{ .ContentLength }} → 42764
+ {{ .ContentType }} → image/jpeg
+ {{ .Status }} → 200 OK
+ {{ .StatusCode }} → 200
+ {{ .TransferEncoding }} → []
+ {{ end }}
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+{{ end }}
+```
+
+ContentLength
+: (`int`) The content length in bytes.
+
+ContentType
+: (`string`) The content type.
+
+Status
+: (`string`) The HTTP status text.
+
+StatusCode
+: (`int`) The HTTP status code.
+
+TransferEncoding
+: (`string`) The transfer encoding.
+
+
++[`resources.GetRemote`]: /functions/resources/getremote/
--- /dev/null
- [`resources.GetRemote`]: functions/resources/getremote
+---
+title: Err
+description: Applicable to resources returned by the resources.GetRemote function, returns an error message if the HTTP request fails, else nil.
+categories: []
+keywords: []
+action:
+ related:
+ - functions/resources/GetRemote
+ - methods/resource/Data
+ returnType: resource.resourceError
+ signatures: [RESOURCE.Err]
+---
+
+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/
+
+In this example we send an HTTP request to a nonexistent domain:
+
+```go-html-template
+{{ $url := "https://broken-example.org/images/a.jpg" }}
+{{ with resources.GetRemote $url }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+{{ end }}
+```
+
+The code above captures the error from the HTTP request, then fails the build:
+
+```text
+ERROR error calling resources.GetRemote: Get "https://broken-example.org/images/a.jpg": dial tcp: lookup broken-example.org on 127.0.0.53:53: no such host
+```
+
+To log an error as a warning instead of an error:
+
+```go-html-template
+{{ $url := "https://broken-example.org/images/a.jpg" }}
+{{ with resources.GetRemote $url }}
+ {{ with .Err }}
+ {{ warnf "%s" . }}
+ {{ else }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+{{ end }}
+```
+
+{{% note %}}
+An HTTP response with a 404 status code is not an HTTP request error. To handle 404 status codes, code defensively using the nested `with-else-end` construct as shown above.
+{{% /note %}}
--- /dev/null
- : (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`]function.
+---
+title: Exif
+description: Applicable to JPEG and TIFF images, returns an EXIF object containing image metadata.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: exif.ExifInfo
+ signatures: [RESOURCE.Exif]
+toc: true
+---
+
+Applicable to JPEG and TIFF images, the `Exif` method on an image `Resource` object returns an [EXIF] object containing image metadata.
+
+## Methods
+
+Date
- [`time.Format`]: /functions/time/format
++: (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`] function.
+
+Lat
+: (`float64`) Returns the GPS latitude in degrees.
+
+Long
+: (`float64`) Returns the GPS longitude in degrees.
+
+Tags
+: (`exif.Tags`) Returns a collection of the available EXIF tags for this image. You may include or exclude specific tags from this collection in the [site configuration].
+
+## Examples
+
+To list the creation date, location, and EXIF tags:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ with .Exif }}
+ <p>Date: {{ .Date }}</p>
+ <p>Lat/Long: {{ .Lat }}/{{ .Long }}</p>
+ {{ with .Tags }}
+ <p>Tags</p>
+ <table>
+ <thead>
+ <tr><th>Tag</th><th>Value</th></tr>
+ </thead>
+ <tbody>
+ {{ range $k, $v := . }}
+ <tr><td>{{ $k }}</td><td>{{ $v }}</td></tr>
+ {{ end }}
+ </tbody>
+ </table>
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+To list specific values:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ with .Exif }}
+ <ul>
+ {{ with .Date }}<li>Date: {{ .Format "January 02, 2006" }}</li>{{ end }}
+ {{ with .Tags.ApertureValue }}<li>Aperture: {{ lang.FormatNumber 2 . }}</li>{{ end }}
+ {{ with .Tags.BrightnessValue }}<li>Brightness: {{ lang.FormatNumber 2 . }}</li>{{ end }}
+ {{ with .Tags.ExposureTime }}<li>Exposure Time: {{ . }}</li>{{ end }}
+ {{ with .Tags.FNumber }}<li>F Number: {{ . }}</li>{{ end }}
+ {{ with .Tags.FocalLength }}<li>Focal Length: {{ . }}</li>{{ end }}
+ {{ with .Tags.ISOSpeedRatings }}<li>ISO Speed Ratings: {{ . }}</li>{{ end }}
+ {{ with .Tags.LensModel }}<li>Lens Model: {{ . }}</li>{{ end }}
+ </ul>
+ {{ end }}
+{{ end }}
+```
+
+{{% include "methods/resource/_common/global-page-remote-resources.md" %}}
+
+[exif]: https://en.wikipedia.org/wiki/Exif
+[site configuration]: /content-management/image-processing/#exif-data
++[`time.Format`]: /functions/time/format/
--- /dev/null
- [`images.Filter`]: /functions/images/filter
+---
+title: Filter
+description: Applicable to images, applies one or more image filters to the given image resource.
+categories: []
+keywords: []
+action:
+ related:
+ - functions/images/Filter
+ returnType: resources.resourceAdapter
+ signatures: [RESOURCE.Filter FILTER...]
+toc: true
+---
+
+Apply one or more [image filters](#image-filters) to the given image.
+
+To apply a single filter:
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Filter images.Grayscale }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+To apply two or more filters, executing from left to right:
+
+```go-html-template
+{{ $filters := slice
+ images.Grayscale
+ (images.GaussianBlur 8)
+}}
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Filter $filters }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+You can also apply image filters using the [`images.Filter`] function.
+
++[`images.Filter`]: /functions/images/filter/
+
+{{% include "methods/resource/_common/global-page-remote-resources.md" %}}
+
+## Example
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Filter images.Grayscale }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Grayscale"
+ filterArgs=""
+ example=true
+>}}
+
+## Image filters
+
+Use any of these filters with the `Filter` method.
+
+{{< list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude >}}
--- /dev/null
- [`Permalink`]: /methods/resource/permalink
- [`RelPermalink`]: /methods/resource/relpermalink
- [`resources.Copy`]: /functions/resources/copy
+---
+title: Key
+description: Returns the unique key for the given resource, equivalent to its publishing path.
++draft: true
+categories: []
+keywords: []
+action:
+ related:
+ - methods/resource/Permalink
+ - methods/resource/RelPermalink
+ - methods/resource/Publish
+ returnType: string
+ signatures: [RESOURCE.Key]
+---
+
+By way of example, consider this site configuration:
+
+{{< code-toggle file=hugo >}}
+baseURL = 'https://example.org/docs/'
+{{< /code-toggle >}}
+
+And this template:
+
+```go-html-template
+ {{ with resources.Get "images/a.jpg" }}
+ {{ with resources.Copy "foo/bar/b.jpg" . }}
+ {{ .Key }} → foo/bar/b.jpg
+
+ {{ .Name }} → images/a.jpg
+ {{ .Title }} → images/a.jpg
+
+ {{ .RelPermalink }} → /docs/foo/bar/b.jpg
+ {{ end }}
+ {{ end }}
+```
+
+We used the [`resources.Copy`] function to change the publishing path. The `Key` method returns the updated path, but note that it is different than the value returned by [`RelPermalink`]. The `RelPermalink` value includes the subdirectory segment of the `baseURL` in the site configuration.
+
+The `Key` method is useful if you need to get the resource's publishing path without publishing the resource. Unlike the `Permalink`, `RelPermalink`, or `Publish` methods, calling `Key` will not publish the resource.
+
+
+{{% include "methods/resource/_common/global-page-remote-resources.md" %}}
+
++[`Permalink`]: /methods/resource/permalink/
++[`RelPermalink`]: /methods/resource/relpermalink/
++[`resources.Copy`]: /functions/resources/copy/
--- /dev/null
- 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.
+---
+title: Name
- └── a.jpg
++description: Returns the name of the given resource as optionally defined in front matter, falling back to its file path.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/resource/Title
+ returnType: string
+ signatures: [RESOURCE.Name]
+toc: true
+---
+
+The value returned by the `Name` method on a `Resource` object depends on the resource type.
+
+## Global resource
+
+With a [global resource], the `Name` method returns the path to the resource, relative to the assets directory.
+
+```text
+assets/
+└── images/
- {{ with resources.Get "images/a.jpg" }}
- {{ .Name }} → images/a.jpg
++ └── Sunrise in Bryce Canyon.jpg
+```
+
+```go-html-template
- With a [page resource], the `Name` method returns the path to the resource, relative to the page bundle.
++{{ with resources.Get "images/Sunrise in Bryce Canyon.jpg" }}
++ {{ .Name }} → /images/Sunrise in Bryce Canyon.jpg
+{{ end }}
+```
+
+## Page resource
+
- ├── posts/
- │ ├── post-1/
- │ │ ├── images/
- │ │ │ └── a.jpg
- │ │ └── index.md
- │ └── _index.md
++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/
- {{ .Name }} → images/a.jpg
++├── 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" }}
- If you create an element in the `resources` array in front matter, the `Name` method returns the value of the `name` parameter:
++ {{ .Name }} → Sunrise in Bryce Canyon
+{{ end }}
+```
+
- {{< 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 >}}
++You can also capture the image by specifying its `name` instead of its path:
+
- {{ with .Resources.Get "cat" }}
- {{ .Name }} → cat
++```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
- {{ .Name }} → a_18432433023265451104.jpg
++{{ with .Resources.Get "images/Sunrise in Bryce Canyon.jpg" }}
++ {{ .Name }} → images/Sunrise in Bryce Canyon.jpg
+{{ end }}
+```
+## Remote resource
+
+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
+{{ 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
--- /dev/null
- [page resources]: /content-management/page-resources
+---
+title: Params
+description: Returns a map of resource parameters as defined in front matter.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: map
+ signatures: [RESOURCE.Params]
+---
+
+Use the `Params` method with [page resources]. It is not applicable to either [global] or [remote] resources.
+
+[global]: /getting-started/glossary/#global-resource
+[page resources]: /getting-started/glossary/#page-resource
+[remote]: /getting-started/glossary/#remote-resource
+
+With this content structure:
+
+```text
+content/
+├── posts/
+│ ├── cats/
+│ │ ├── images/
+│ │ │ └── a.jpg
+│ │ └── index.md
+│ └── _index.md
+└── _index.md
+```
+
+And this front matter:
+
+{{< code-toggle file=content/posts/cats.md fm=true >}}
+title = 'Cats'
+[[resources]]
+ src = 'images/a.jpg'
+ title = 'Felix the cat'
+ [resources.params]
+ alt = 'Photograph of black cat'
+ temperament = 'vicious'
+{{< /code-toggle >}}
+
+And this template:
+
+```go-html-template
+{{ with .Resources.Get "images/a.jpg" }}
+ <figure>
+ <img alt="{{ .Params.alt }}" src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+ <figcaption>{{ .Title }} is {{ .Params.temperament }}</figcaption>
+ </figure>
+{{ end }}
+```
+
+Hugo renders:
+
+```html
+<figure>
+ <img alt="Photograph of black cat" src="/posts/post-1/images/a.jpg" width="600" height="400">
+ <figcaption>Felix the cat is vicious</figcaption>
+</figure>
+```
+
+See the [page resources] section for more information.
+
++[page resources]: /content-management/page-resources/
--- /dev/null
- - methods/resource/Key
+---
+title: Permalink
+description: Publishes the given resource and returns its permalink.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/resource/RelPermalink
+ - methods/resource/Publish
+ returnType: string
+ signatures: [RESOURCE.Permalink]
+---
+
+The `Permalink` method on a `Resource` object writes the resource to the publish directory, typically `public`, and returns its [permalink].
+
+[permalink]: /getting-started/glossary/#permalink
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ .Permalink }} → https://example.org/images/a.jpg
+{{ end }}
+```
+
+{{% include "methods/resource/_common/global-page-remote-resources.md" %}}
--- /dev/null
- [`Crop`]: /methods/resource/crop
- [`Fill`]: /methods/resource/fill
- [`Fit`]: /methods/resource/fit
- [`Resize`]: /methods/resource/resize
- [`images.Process`]: /functions/images/process
+---
+title: Process
+description: Applicable to images, returns an image resource processed with the given specification.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/resource/Crop
+ - methods/resource/Fit
+ - methods/resource/Fill
+ - methods/resource/Resize
+ - functions/images/Process
+ returnType: images.ImageResource
+ signatures: [RESOURCE.Process SPEC]
+toc: true
+---
+
+Process an image with the given specification. The specification can contain an optional action, one of `crop`, `fill`, `fit`, or `resize`. This means that you can use this method instead of [`Crop`], [`Fill`], [`Fit`], or [`Resize`].
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Process "crop 200x200" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+You can also use this method to apply simple transformations such as rotation and conversion:
+
+```go-html-template
+{{/* Rotate 90 degrees counter-clockwise. */}}
+{{ $image := $image.Process "r90" }}
+
+{{/* Convert to WebP. */}}
+{{ $image := $image.Process "webp" }}
+```
+
+The `Process` method is also available as a filter, which is more effective if you need to apply multiple filters to an image. See [`images.Process`].
+
+{{% include "methods/resource/_common/global-page-remote-resources.md" %}}
+
+{{% include "/methods/resource/_common/processing-spec.md" %}}
+
+## Example
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Process "crop 200x200 topright webp q85 lanczos" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Process"
+ filterArgs="crop 200x200 topright webp q85 lanczos"
+ example=true
+>}}
+
++[`Crop`]: /methods/resource/crop/
++[`Fill`]: /methods/resource/fill/
++[`Fit`]: /methods/resource/fit/
++[`Resize`]: /methods/resource/resize/
++[`images.Process`]: /functions/images/process/
--- /dev/null
- - methods/resource/Key
+---
+title: Publish
+description: Publishes the given resource.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/resource/Permalink
+ - methods/resource/RelPermalink
+ returnType: nil
+ signatures: [RESOURCE.Publish]
+---
+
+The `Publish` method on a `Resource` object writes the resource to the publish directory, typically `public`.
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ .Publish }}
+{{ end }}
+```
+
+The `Permalink` and `RelPermalink` methods also publish a resource. `Publish` is a convenience method for publishing without a return value. For example, this:
+
+```go-html-template
+{{ $resource.Publish }}
+```
+
+Instead of this:
+
+```go-html-template
+{{ $noop := $resource.Permalink }}
+```
+
+{{% include "methods/resource/_common/global-page-remote-resources.md" %}}
--- /dev/null
- - methods/resource/Key
+---
+title: RelPermalink
+description: Publishes the given resource and returns its relative permalink.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/resource/Permalink
+ - methods/resource/Publish
+ returnType: string
+ signatures: [RESOURCE.RelPermalink]
+---
+
+The `Permalink` method on a `Resource` object writes the resource to the publish directory, typically `public`, and returns its [relative permalink].
+
+[relative permalink]: /getting-started/glossary/#relative-permalink
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ .RelPermalink }} → /images/a.jpg
+{{ end }}
+```
+
+{{% include "methods/resource/_common/global-page-remote-resources.md" %}}
--- /dev/null
- └── a.jpg
+---
+title: Title
+description: Returns the title of the given resource as optionally defined in front matter, falling back to a relative path or hashed file name depending on resource type.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/resource/Name
+ returnType: string
+ signatures: [RESOURCE.Title]
+toc: true
+---
+
+The value returned by the `Title` method on a `Resource` object depends on the resource type.
+
+## Global resource
+
+With a [global resource], the `Title` method returns the path to the resource, relative to the assets directory.
+
+```text
+assets/
+└── images/
- {{ with resources.Get "images/a.jpg" }}
- {{ .Title }} → images/a.jpg
++ └── Sunrise in Bryce Canyon.jpg
+```
+
+```go-html-template
- With a [page resource], the `Title` method returns the path to the resource, relative to the page bundle.
++{{ with resources.Get "images/Sunrise in Bryce Canyon.jpg" }}
++ {{ .Title }} → /images/Sunrise in Bryce Canyon.jpg
+{{ end }}
+```
+
+## Page resource
+
- ├── posts/
- │ ├── post-1/
- │ │ ├── images/
- │ │ │ └── a.jpg
- │ │ └── index.md
- │ └── _index.md
++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/
- ```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'
++├── example/
++│ ├── images/
++│ │ └── a.jpg
++│ └── index.md
+└── _index.md
+```
+
- name = 'cat'
- title = 'Felix the cat'
- [resources.params]
- temperament = 'malicious'
++{{< code-toggle file=content/example/index.md fm=true >}}
++title = 'Example'
+[[resources]]
+src = 'images/a.jpg'
- {{ with .Resources.Get "cat" }}
- {{ .Title }} → Felix the cat
++title = 'A beautiful sunrise in Bryce Canyon'
+{{< /code-toggle >}}
+
+```go-html-template
- If the page resource is a content file, the `Title` methods return the `title` field as defined in front matter.
++{{ with .Resources.Get "images/a.jpg" }}
++ {{ .Title }} → A beautiful sunrise in Bryce Canyon
+{{ end }}
+```
+
- ├── lessons/
- │ ├── lesson-1/
- │ │ ├── _objectives.md <-- resource type = page
- │ │ └── index.md
- │ └── _index.md
++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/
- {{ .Title }} → a_18432433023265451104.jpg
++├── 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
+{{ end }}
+```
+
+[global resource]: /getting-started/glossary/#global-resource
+[page resource]: /getting-started/glossary/#page-resource
+[remote resource]: /getting-started/glossary/#remote-resource
--- /dev/null
- Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+---
+cascade:
+ _build:
+ list: never
+ publishResources: false
+ render: never
+---
+
+<!--
++Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+
+Include the rendered content using the "include" shortcode.
+-->
--- /dev/null
- description: Returns the value of the given parameter.
+---
+title: Get
- signatures: [SHORTCODE.Get PARAM]
++description: Returns the value of the given argument.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/shortcode/IsNamedParams
+ - methods/shortcode/Params
+ returnType: any
- Specify the parameter by position or by name. When calling a shortcode within markdown, use either positional or named parameters, but not both.
++ signatures: [SHORTCODE.Get ARG]
+toc: true
+---
+
- Some shortcodes support positional parameters, some support named parameters, and others support both. Refer to the shortcode's documentation for usage details.
++Specify the argument by position or by name. When calling a shortcode within Markdown, use either positional or named argument, but not both.
+
+{{% note %}}
- ## Positional parameters
++Some shortcodes support positional arguments, some support named arguments, and others support both. Refer to the shortcode's documentation for usage details.
+{{% /note %}}
+
- This shortcode call uses positional parameters:
++## Positional arguments
+
- To retrieve parameters by position:
++This shortcode call uses positional arguments:
+
+{{< code file=content/about.md lang=md >}}
+{{</* myshortcode "Hello" "world" */>}}
+{{< /code >}}
+
- ## Named parameters
++To retrieve arguments by position:
+
+{{< code file=layouts/shortcodes/myshortcode.html >}}
+{{ printf "%s %s." (.Get 0) (.Get 1) }} → Hello world.
+{{< /code >}}
+
- This shortcode call uses named parameters:
++## Named arguments
+
- To retrieve parameters by name:
++This shortcode call uses named arguments:
+
+{{< code file=content/about.md lang=md >}}
+{{</* myshortcode greeting="Hello" firstName="world" */>}}
+{{< /code >}}
+
- Parameter names are case-sensitive.
++To retrieve arguments by name:
+
+{{< code file=layouts/shortcodes/myshortcode.html >}}
+{{ printf "%s %s." (.Get "greeting") (.Get "firstName") }} → Hello world.
+{{< /code >}}
+
+{{% note %}}
++Argument names are case-sensitive.
+{{% /note %}}
--- /dev/null
- 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.
+---
+title: Inner
+description: Returns the content between opening and closing shortcode tags, applicable when the shortcode call includes a closing tag.
+categories: []
+keywords: []
+action:
+ related:
+ - functions/strings/Trim
+ - methods/page/RenderString
+ - functions/transform/Markdownify
+ - methods/shortcode/InnerDeindent
+ returnType: template.HTML
+ signatures: [SHORTCODE.Inner]
+---
+
+This content:
+
+{{< code file=content/services.md lang=md >}}
+{{</* card title="Product Design" */>}}
+We design the **best** widgets in the world.
+{{</* /card */>}}
+{{< /code >}}
+
+With this shortcode:
+
+{{< code file=layouts/shortcodes/card.html >}}
+<div class="card">
+ {{ with .Get "title" }}
+ <div class="card-title">{{ . }}</div>
+ {{ end }}
+ <div class="card-content">
+ {{ trim .Inner "\r\n" }}
+ </div>
+</div>
+{{< /code >}}
+
+Is rendered to:
+
+```html
+<div class="card">
+ <div class="card-title">Product Design</div>
+ <div class="card-content">
+ We design the **best** widgets in the world.
+ </div>
+</div>
+```
+
+{{% note %}}
- [`trim`]: /functions/strings/trim
++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.
+
- 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.
++[`trim`]: /functions/strings/trim/
+{{% /note %}}
+
+{{% note %}}
- [`RenderString`]: /methods/page/renderstring
++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 %}}
+
+
+## Use the RenderString method
+
+Let's modify the example above to pass the value returned by `Inner` through the [`RenderString`] method on the `Page` object:
+
- [details]: /methods/page/renderstring
- [`markdownify`]: /functions/transform/markdownify
++[`RenderString`]: /methods/page/renderstring/
+
+{{< code file=layouts/shortcodes/card.html >}}
+<div class="card">
+ {{ with .Get "title" }}
+ <div class="card-title">{{ . }}</div>
+ {{ end }}
+ <div class="card-content">
+ {{ trim .Inner "\r\n" | .Page.RenderString }}
+ </div>
+</div>
+{{< /code >}}
+
+Hugo renders this to:
+
+```html
+<div class="card">
+ <div class="card-title">Product design</div>
+ <div class="card-content">
+ We produce the <strong>best</strong> widgets in the world.
+ </div>
+</div>
+```
+
+You can use the [`markdownify`] function instead of the `RenderString` method, but the latter is more flexible. See [details].
+
- When you use the `{{%/* */%}}` notation, Hugo renders the entire shortcode as markdown, requiring the following changes.
++[details]: /methods/page/renderstring/
++[`markdownify`]: /functions/transform/markdownify/
+
+## Use alternate notation
+
+Instead of calling the shortcode with the `{{</* */>}}` notation, use the `{{%/* */%}}` notation:
+
+{{< code file=content/services.md lang=md >}}
+{{%/* card title="Product Design" */%}}
+We design the **best** widgets in the world.
+{{%/* /card */%}}
+{{< /code >}}
+
- First, configure the renderer to allow raw HTML within markdown:
++When you use the `{{%/* */%}}` notation, Hugo renders the entire shortcode as Markdown, requiring the following changes.
+
- 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.
++First, configure the renderer to allow raw HTML within Markdown:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.renderer]
+unsafe = true
+{{< /code-toggle >}}
+
+This configuration is not unsafe if _you_ control the content. Read more about Hugo's [security model].
+
- [security model]: /about/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.
+
+{{< code file=layouts/shortcodes/card.html >}}
+<div class="card">
+ {{ with .Get "title" }}
+ <div class="card-title">{{ . }}</div>
+ {{ end }}
+ <div class="card-content">
+
+ {{ trim .Inner "\r\n" }}
+ </div>
+</div>
+{{< /code >}}
+
+The difference between this and the previous example is subtle but required. Note the change in indentation, the addition of a blank line, and removal of the `RenderString` method.
+
+```diff
+--- layouts/shortcodes/a.html
++++ layouts/shortcodes/b.html
+@@ -1,8 +1,9 @@
+ <div class="card">
+ {{ with .Get "title" }}
+- <div class="card-title">{{ . }}</div>
++ <div class="card-title">{{ . }}</div>
+ {{ end }}
+ <div class="card-content">
+- {{ trim .Inner "\r\n" | .Page.RenderString }}
++
++ {{ trim .Inner "\r\n" }}
+ </div>
+ </div>
+```
+
+{{% note %}}
+When using the `{{%/* */%}}` notation, do not pass the value returned by `Inner` through the `RenderString` method or the `markdownify` function.
+{{% /note %}}
+
+[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/
--- /dev/null
- Consider this markdown, an unordered list with a small gallery of thumbnail images within each list item:
+---
+title: InnerDeindent
+description: Returns the content between opening and closing shortcode tags, with indentation removed, applicable when the shortcode call includes a closing tag.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/shortcode/Inner
+ returnType: template.HTML
+ signatures: [SHORTCODE.InnerDeindent]
+---
+
+Similar to the [`Inner`] method, `InnerDeindent` returns the content between opening and closing shortcode tags. However, with `InnerDeindent`, indentation before the content is removed.
+
+This allows us to effectively bypass the rules governing [indentation] as provided in the [CommonMark] specification.
+
- Hugo renders the markdown to:
++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
+
+ {{</* gallery */>}}
+ 
+ 
+ {{</* /gallery */>}}
+
+- Gallery two
+
+ {{</* gallery */>}}
+ 
+ 
+ {{</* /gallery */>}}
+{{< /code >}}
+
+In the example above, notice that the content between the opening and closing shortcode tags is indented by four spaces. Per the CommonMark specification, this is treated as an indented code block.
+
+With this shortcode, calling `Inner` instead of `InnerDeindent`:
+
+{{< code file=layouts/shortcodes/gallery.html >}}
+<div class="gallery">
+ {{ trim .Inner "\r\n" | .Page.RenderString }}
+</div>
+{{< /code >}}
+
- Hugo renders the markdown to:
++Hugo renders the Markdown to:
+
+```html
+<ul>
+ <li>
+ <p>Gallery one</p>
+ <div class="gallery">
+ <pre><code>
+ 
+ </code></pre>
+ </div>
+ </li>
+ <li>
+ <p>Gallery two</p>
+ <div class="gallery">
+ <pre><code>
+ 
+ </code></pre>
+ </div>
+ </li>
+</ul>
+```
+
+Although technically correct per the CommonMark specification, this is not what we want. If we remove the indentation using the `InnerDeindent` method:
+
+{{< code file=layouts/shortcodes/gallery.html >}}
+<div class="gallery">
+ {{ trim .InnerDeindent "\r\n" | .Page.RenderString }}
+</div>
+{{< /code >}}
+
- [`Inner`]: /methods/shortcode/inner
++Hugo renders the Markdown to:
+
+```html
+<ul>
+ <li>
+ <p>Gallery one</p>
+ <div class="gallery">
+ <img src="images/a.jpg" alt="kitten a">
+ <img src="images/b.jpg" alt="kitten b">
+ </div>
+ </li>
+ <li>
+ <p>Gallery two</p>
+ <div class="gallery">
+ <img src="images/c.jpg" alt="kitten c">
+ <img src="images/d.jpg" alt="kitten d">
+ </div>
+ </li>
+</ul>
+```
+
+[commonmark]: https://commonmark.org/
+[indentation]: https://spec.commonmark.org/0.30/#indented-code-blocks
++[`Inner`]: /methods/shortcode/inner/
--- /dev/null
- description: Reports whether the shortcode call uses named parameters.
+---
+title: IsNamedParams
- To support both positional and named parameters when calling a shortcode, use the `IsNamedParams` method to determine how the shortcode was called.
++description: Reports whether the shortcode call uses named arguments.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/shortcode/Get
+ returnType: bool
+ signatures: [SHORTCODE.IsNamedParams]
+---
+
++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:
+
+{{< code file=layouts/shortcodes/myshortcode.html >}}
+{{ if .IsNamedParams }}
+ {{ printf "%s %s." (.Get "greeting") (.Get "firstName") }}
+{{ else }}
+ {{ printf "%s %s." (.Get 0) (.Get 1) }}
+{{ end }}
+{{< /code >}}
+
+Both of these calls return the same value:
+
+{{< code file=content/about.md lang=md >}}
+{{</* myshortcode greeting="Hello" firstName="world" */>}}
+{{</* myshortcode "Hello" "world" */>}}
+{{< /code >}}
--- /dev/null
- The `Name` method is useful for error reporting. For example, if your shortcode requires a "greeting" parameter:
+---
+title: Name
+description: Returns the shortcode file name, excluding the file extension.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/shortcode/Position
+ - functions/fmt/Errorf
+ returnType: string
+ signatures: [SHORTCODE.Name]
+---
+
- {{ errorf "The %q shortcode requires a 'greeting' parameter. See %s" .Name .Position }}
++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 }}
- In the absence of a "greeting" parameter, Hugo will throw an error message and fail the build:
++ {{ errorf "The %q shortcode requires a 'greeting' argument. See %s" .Name .Position }}
+{{ end }}
+{{< /code >}}
+
- ERROR The "myshortcode" shortcode requires a 'greeting' parameter. See "/home/user/project/content/about.md:11:1"
++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' argument. See "/home/user/project/content/about.md:11:1"
+```
--- /dev/null
- {{ errorf "The %q shortcode requires a 'src' parameter. See %s" .Name .Position }}
+---
+title: Ordinal
+description: Returns the zero-based ordinal of the shortcode in relation to its parent.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: int
+ signatures: [SHORTCODE.Ordinal]
+---
+
+The `Ordinal` method returns the zero-based ordinal of the shortcode in relation to its parent. If the parent is the page itself, the ordinal represents the position of this shortcode in the page content.
+
+This method is useful for, among other things, assigning unique element IDs when a shortcode is called two or more times from the same page. For example:
+
+{{< code file=content/about.md lang=md >}}
+{{</* img src="images/a.jpg" */>}}
+
+{{</* img src="images/b.jpg" */>}}
+{{< /code >}}
+
+This shortcode performs error checking, then renders an HTML `img` element with a unique `id` attribute:
+
+{{< code file=layouts/shortcodes/img.html >}}
+{{ $src := "" }}
+{{ with .Get "src" }}
+ {{ $src = . }}
+ {{ with resources.Get $src }}
+ {{ $id := printf "img-%03d" $.Ordinal }}
+ <img id="{{ $id }}" src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ else }}
+ {{ errorf "The %q shortcode was unable to find %s. See %s" $.Name $src $.Position }}
+ {{ end }}
+{{ else }}
- [`with`]: /functions/go-template/with
++ {{ errorf "The %q shortcode requires a 'src' argument. See %s" .Name .Position }}
+{{ end }}
+{{< /code >}}
+
+Hugo renders the page to:
+
+```html
+<img id="img-000" src="/images/a.jpg" width="600" height="400" alt="">
+<img id="img-001" src="/images/b.jpg" width="600" height="400" alt="">
+```
+
+{{% 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/
+{{% /note %}}
--- /dev/null
- description: Returns a collection of the shortcode parameters.
+---
+title: Params
- When you call a shortcode using positional parameters, the `Params` method returns a slice.
++description: Returns a collection of the shortcode arguments.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/shortcode/Get
+ returnType: any
+ signatures: [SHORTCODE.Params]
+---
+
- When you call a shortcode using named parameters, the `Params` method returns a map.
++When you call a shortcode using positional arguments, the `Params` method returns a slice.
+
+{{< code file=content/about.md lang=md >}}
+{{</* myshortcode "Hello" "world" */>}}
+{{< /code >}}
+
+{{< code file=layouts/shortcodes/myshortcode.html >}}
+{{ index .Params 0 }} → Hello
+{{ index .Params 1 }} → world
+{{< /code >}}
+
++When you call a shortcode using named arguments, the `Params` method returns a map.
+
+{{< code file=content/about.md lang=md >}}
+{{</* myshortcode greeting="Hello" name="world" */>}}
+{{< /code >}}
+
+{{< code file=layouts/shortcodes/myshortcode.html >}}
+{{ .Params.greeting }} → Hello
+{{ .Params.name }} → world
+{{< /code >}}
--- /dev/null
- This is useful for inheritance of common shortcode parameters from the root.
+---
+title: Parent
+description: Returns the parent shortcode context in nested shortcodes.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: hugolib.ShortcodeWithPage
+ signatures: [SHORTCODE.Parent]
+---
+
- 1. The `dateFormat` parameter passed to the "now" shortcode, if present
- 2. The `dateFormat` parameter passed to the "greeting" shortcode, if present
++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.
+
+{{< code file=content/welcome.md lang=md >}}
+{{</* greeting dateFormat="Jan 2, 2006" */>}}
+Welcome. Today is {{</* now */>}}.
+{{</* /greeting */>}}
+{{< /code >}}
+
+{{< code file=layouts/shortcodes/greeting.html >}}
+<div class="greeting">
+ {{ trim .Inner "\r\n" | .Page.RenderString }}
+</div>
+{{< /code >}}
+
+{{< code file=layouts/shortcodes/now.html >}}
+{{- $dateFormat := "January 2, 2006 15:04:05" }}
+
+{{- with .Params }}
+ {{- with .dateFormat }}
+ {{- $dateFormat = . }}
+ {{- end }}
+{{- else }}
+ {{- with .Parent.Params }}
+ {{- with .dateFormat }}
+ {{- $dateFormat = . }}
+ {{- end }}
+ {{- end }}
+{{- end }}
+
+{{- now | time.Format $dateFormat -}}
+{{< /code >}}
+
+The "now" shortcode formats the current time using:
+
++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
--- /dev/null
- The `Position` method is useful for error reporting. For example, if your shortcode requires a "greeting" parameter:
+---
+title: Position
+description: Returns the filename and position from which the shortcode was called.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/shortcode/Name
+ - functions/fmt/Errorf
+ returnType: text.Position
+ signatures: [SHORTCODE.Position]
+---
+
- {{ errorf "The %q shortcode requires a 'greeting' parameter. See %s" .Name .Position }}
++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 }}
- In the absence of a "greeting" parameter, Hugo will throw an error message and fail the build:
++ {{ errorf "The %q shortcode requires a 'greeting' argument. See %s" .Name .Position }}
+{{ end }}
+{{< /code >}}
+
- ERROR The "myshortcode" shortcode requires a 'greeting' parameter. See "/home/user/project/content/about.md:11:1"
++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' argument. See "/home/user/project/content/about.md:11:1"
+```
+
+{{% note %}}
+The position can be expensive to calculate. Limit its use to error reporting.
+{{% /note %}}
--- /dev/null
- description: Creates a "scratch pad" scoped to the shortcode to store and manipulate data.
+---
+title: Scratch
- [`newScratch`]: functions/collections/newscratch
++description: Returns a "scratch pad" scoped to the shortcode to store and manipulate data.
+categories: []
+keywords: []
+action:
+ related:
+ - functions/collections/NewScratch
+ returnType: maps.Scratch
+ signatures: [SHORTCODE.Scratch]
+---
+
+The `Scratch` method within a shortcode creates a [scratch pad] to store and manipulate data. The scratch pad is scoped to the shortcode, and is reset on server rebuilds.
+
+{{% note %}}
+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/
+{{% /note %}}
+
+[scratch pad]: /getting-started/glossary/#scratch-pad
+
+{{% include "methods/page/_common/scratch-methods.md" %}}
--- /dev/null
- [Site methods]: /methods/site
+---
+title: Site
+description: Returns the Site object.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/Sites
+ returnType: page.siteWrapper
+ signatures: [SHORTCODE.Site]
+---
+
+See [Site methods].
+
++[Site methods]: /methods/site/
+
+```go-html-template
+{{ .Site.Title }}
+```
--- /dev/null
- [`RegularPages`]: methods/site/regularpages
+---
+title: AllPages
+description: Returns a collection of all pages in all languages.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/site/Pages
+ - methods/site/RegularPages
+ - methods/site/Sections
+ returnType: page.Pages
+ signatures: [SITE.AllPages]
+---
+
+This method returns all page [kinds] in all languages. That includes the home page, section pages, taxonomy pages, term pages, and regular pages.
+
+In most cases you should use the [`RegularPages`] method instead.
+
++[`RegularPages`]: /methods/site/regularpages/
+[kinds]: /getting-started/glossary/#page-kind
+
+```go-html-template
+{{ range .Site.AllPages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
--- /dev/null
- [`absURL`]: /functions/urls/absURL
- [`absLangURL`]: /functions/urls/absLangURL
- [`relURL`]: /functions/urls/relURL
- [`relLangURL`]: /functions/urls/relLangURL
+---
+title: BaseURL
+description: Returns the base URL as defined in the site configuration.
+categories: []
+keywords: []
+action:
+ related:
+ - functions/urls/AbsURL
+ - functions/urls/AbsLangURL
+ - functions/urls/RelURL
+ - functions/urls/RelLangURL
+ returnType: string
+ signatures: [SITE.BaseURL]
+---
+
+Site configuration:
+
+{{< code-toggle file=hugo >}}
+baseURL = 'https://example.org/docs/'
+{{< /code-toggle >}}
+
+Template:
+
+```go-html-template
+{{ .Site.BaseURL }} → https://example.org/docs/
+```
+
+{{% note %}}
+There is almost never a good reason to use this method in your templates. Its usage tends to be fragile due to misconfiguration.
+
+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/
+{{% /note %}}
--- /dev/null
- [`transform.Unmarshal`]: /functions/transform/unmarshal
+---
+title: Data
+description: Returns a data structure composed from the files in the data directory.
+categories: []
+keywords: []
+action:
+ related:
+ - functions/collections/IndexFunction
+ - functions/transform/Unmarshal
+ - functions/collections/Where
+ - functions/collections/Sort
+ returnType: map
+ signatures: [SITE.Data]
+---
+
+Use the `Data` method on a `Site` object to access data within the data directory, or within any directory [mounted] to the data directory. Supported data formats include JSON, TOML, YAML, and XML.
+
+[mounted]: /hugo-modules/configuration/#module-configuration-mounts
+
+{{% 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.
+
- 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:
++[`transform.Unmarshal`]: /functions/transform/unmarshal/
+{{% /note %}}
+
+Consider this data directory:
+
+```text
+data/
+├── books/
+│ ├── fiction.yaml
+│ └── nonfiction.yaml
+├── films.json
+├── paintings.xml
+└── sculptures.toml
+```
+
+And these data files:
+
+{{< code file=data/books/fiction.yaml lang=yaml >}}
+- title: The Hunchback of Notre Dame
+ author: Victor Hugo
+ isbn: 978-0140443530
+- title: Les Misérables
+ author: Victor Hugo
+ isbn: 978-0451419439
+{{< /code >}}
+
+{{< code file=data/books/nonfiction.yaml lang=yaml >}}
+- title: The Ancien Régime and the Revolution
+ author: Alexis de Tocqueville
+ isbn: 978-0141441641
+- title: Interpreting the French Revolution
+ author: François Furet
+ isbn: 978-0521280495
+{{< /code >}}
+
+Access the data by [chaining] the [identifiers]:
+
+```go-html-template
+{{ range $category, $books := .Site.Data.books }}
+ <p>{{ $category | title }}</p>
+ <ul>
+ {{ range $books }}
+ <li>{{ .title }} ({{ .isbn }})</li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+Hugo renders this to:
+
+```html
+<p>Fiction</p>
+<ul>
+ <li>The Hunchback of Notre Dame (978-0140443530)</li>
+ <li>Les Misérables (978-0451419439)</li>
+</ul>
+<p>Nonfiction</p>
+<ul>
+ <li>The Ancien Régime and the Revolution (978-0141441641)</li>
+ <li>Interpreting the French Revolution (978-0521280495)</li>
+</ul>
+```
+
+To limit the listing to fiction, and sort by title:
+
+```go-html-template
+<ul>
+ {{ range sort .Site.Data.books.fiction "title" }}
+ <li>{{ .title }} ({{ .author }})</li>
+ {{ end }}
+</ul>
+```
+
+To find a fiction book by ISBN:
+
+```go-html-template
+{{ range where .Site.Data.books.fiction "isbn" "978-0140443530" }}
+ <li>{{ .title }} ({{ .author }})</li>
+{{ end }}
+```
+
- [`index`]: /functions/collections/indexfunction
++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:
+
++[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
--- /dev/null
- [`Site.Config.Services.Disqus.Shortname`]: /methods/site/config
+---
+title: DisqusShortname
+description: Returns the Disqus shortname as defined in the site configuration.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: string
+ signatures: [SITE.DisqusShortname]
+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/
+{{% /deprecated-in %}}
--- /dev/null
- [details]: /methods/page/getpage
+---
+title: GetPage
+description: Returns a Page object from the given path.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/GetPage
+ returnType: page.Page
+ signatures: [SITE.GetPage PATH]
+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/
+
+When using the `GetPage` method on a `Site` object, specify a path relative to the content directory.
+
+If Hugo cannot resolve the path to a page, the method returns nil.
+
+Consider this content structure:
+
+```text
+content/
+├── works/
+│ ├── paintings/
+│ │ ├── _index.md
+│ │ ├── starry-night.md
+│ │ └── the-mona-lisa.md
+│ ├── sculptures/
+│ │ ├── _index.md
+│ │ ├── david.md
+│ │ └── the-thinker.md
+│ └── _index.md
+└── _index.md
+```
+
+This home page template:
+
+```go-html-template
+{{ with .Site.GetPage "/works/paintings" }}
+ <ul>
+ {{ range .Pages }}
+ <li>{{ .Title }} by {{ .Params.artist }}</li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li>Starry Night by Vincent van Gogh</li>
+ <li>The Mona Lisa by Leonardo da Vinci</li>
+</ul>
+```
+
+To get a regular page instead of a section page:
+
+```go-html-template
+{{ with .Site.GetPage "/works/paintings/starry-night" }}
+ {{ .Title }} → Starry Night
+ {{ .Params.artist }} → Vincent van Gogh
+{{ end }}
+```
+
+## Multilingual projects
+
+With multilingual projects, the `GetPage` method on a `Site` object resolves the given path to a page in the current language.
+
+To get a page from a different language, query the `Sites` object:
+
+```go-html-template
+{{ with where .Site.Sites "Language.Lang" "eq" "de" }}
+ {{ with index . 0 }}
+ {{ with .GetPage "/works/paintings/starry-night" }}
+ {{ .Title }} → Sternenklare Nacht
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+## Page bundles
+
+Consider this content structure:
+
+```text
+content/
+├── headless/
+│ ├── a.jpg
+│ ├── b.jpg
+│ ├── c.jpg
+│ └── index.md <-- front matter: headless = true
+└── _index.md
+```
+
+In the home page template, use the `GetPage` method on a `Site` object to render all the images in the headless [page bundle]:
+
+```go-html-template
+{{ with .Site.GetPage "/headless" }}
+ {{ range .Resources.ByType "image" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+[page bundle]: /getting-started/glossary/#page-bundle
--- /dev/null
- [`Site.Config.Services.GoogleAnalytics.ID`]: /methods/site/config
+---
+title: GoogleAnalytics
+description: Returns the Google Analytics tracking ID as defined in the site configuration.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: string
+ signatures: [SITE.GoogleAnalytics]
+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/
+{{% /deprecated-in %}}
--- /dev/null
- [`hugo.IsDevelopment`]: /functions/hugo/isdevelopment
+---
+title: IsDevelopment
+description: Reports whether the current running environment is “development”.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: bool
+ signatures: [SITE.IsDevelopment]
+expiryDate: 2024-10-30 # deprecated 2023-10-30
+---
+
+{{% deprecated-in 0.120.0 %}}
+Use [`hugo.IsDevelopment`] instead.
+
++[`hugo.IsDevelopment`]: /functions/hugo/isdevelopment/
+{{% /deprecated-in %}}
+
+```go-html-template
+{{ .Site.IsDevelopment }} → true/false
+```
--- /dev/null
- description: Reports whether the site is multilingual.
+---
+title: IsMultiLingual
++description: Reports whether there are two or more configured languages.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: bool
+ 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 >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = true
+[languages]
+ [languages.de]
+ languageCode = 'de-DE'
+ languageName = 'Deutsch'
+ title = 'Projekt Dokumentation'
+ weight = 1
+ [languages.en]
+ languageCode = 'en-US'
+ languageName = 'English'
+ title = 'Project Documentation'
+ weight = 2
+{{< /code-toggle >}}
+
+Template:
+
+```go-html-template
+{{ .Site.IsMultiLingual }} → true
+```
--- /dev/null
- [`hugo.IsServer`]: /functions/hugo/isserver
+---
+title: IsServer
+description: Reports whether the built-in development server is running.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: bool
+ signatures: [SITE.IsServer]
+expiryDate: 2024-10-30 # deprecated 2023-10-30
+---
+
+{{% deprecated-in 0.120.0 %}}
+Use [`hugo.IsServer`] instead.
+
++[`hugo.IsServer`]: /functions/hugo/isserver/
+{{% /deprecated-in %}}
+
+```go-html-template
+{{ .Site.IsServer }} → true/false
+```
--- /dev/null
- : (`string`) The language code from the site configuration.
+---
+title: Language
+description: Returns the language object for the given site.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/language
+ returnType: langs.Language
+ signatures: [SITE.Language]
+toc: true
+---
+
+The `Language` method on a `Site` object returns the language object for the given site. The language object points to the language definition in the site configuration.
+
+You can also use the `Language` method on a `Page` object. See [details].
+
+## Methods
+
+The examples below assume the following in your site configuration:
+
+{{< code-toggle file=hugo >}}
+[languages.de]
+languageCode = 'de-DE'
+languageDirection = 'ltr'
+languageName = 'Deutsch'
+weight = 1
+{{< /code-toggle >}}
+
+Lang
+: (`string`) The language tag as defined by [RFC 5646].
+
+```go-html-template
+{{ .Site.Language.Lang }} → de
+```
+
+LanguageCode
- lang="{{ or site.Language.LanguageCode site.Language.Lang }}"
- dir="{{ or site.Language.LanguageDirection `ltr` }}
++: (`string`) The language code from the site configuration. Falls back to `Lang` if not defined.
+
+```go-html-template
+{{ .Site.Language.LanguageCode }} → de-DE
+```
+
+LanguageDirection
+: (`string`) The language direction from the site configuration, either `ltr` or `rtl`.
+
+```go-html-template
+{{ .Site.Language.LanguageDirection }} → ltr
+```
+
+LanguageName
+: (`string`) The language name from the site configuration.
+
+```go-html-template
+{{ .Site.Language.LanguageName }} → Deutsch
+```
+
+Weight
+: (`int`) The language weight from the site configuration which determines its order in the slice of languages returned by the `Languages` method on a `Site` object.
+
+```go-html-template
+{{ .Site.Language.Weight }} → 1
+```
+
+## Example
+
+Some of the methods above are commonly used in a base template as attributes for the `html` element.
+
+```go-html-template
+<html
- The example above uses the global [`site`] function instead of accessing the `Site` object via the `.Site` notation.
-
- Also note that each attribute has a fallback value assigned via the [`or`] operator.
-
- [details]: /methods/page/language
++ lang="{{ .Site.Language.LanguageCode }}"
++ dir="{{ or .Site.Language.LanguageDirection `ltr` }}
+>
+```
+
- [`or`]: /functions/go-template/or
- [`site`]: /functions/global/site
++[details]: /methods/page/language/
+[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
--- /dev/null
- To view the data structure:
+---
+title: Languages
+description: Returns a collection of language objects for all sites, ordered by language weight.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/site/Language
+ returnType: langs.Languages
+ signatures: [SITE.Languages]
+---
+
+The `Languages` method on a `Site` object returns a collection of language objects for all sites, ordered by language weight. Each language object points to its language definition in the site configuration.
+
- <pre>{{ jsonify (dict "indent" " ") .Site.Languages }}</pre>
++To inspect the data structure:
+
+```go-html-template
++<pre>{{ debug.Dump .Site.Languages }}</pre>
+```
+
+With this site configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = false
+
+[languages.de]
+languageCode = 'de-DE'
+languageDirection = 'ltr'
+languageName = 'Deutsch'
+title = 'Projekt Dokumentation'
+weight = 1
+
+[languages.en]
+languageCode = 'en-US'
+languageDirection = 'ltr'
+languageName = 'English'
+title = 'Project Documentation'
+weight = 2
+{{< /code-toggle >}}
+
+This template:
+
+```go-html-template
+<ul>
+ {{ range .Site.Languages }}
+ <li>{{ .Title }} ({{ .LanguageName }})</li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li>Projekt Dokumentation (Deutsch)</li>
+ <li>Project Documentation (English)</li>
+</ul>
+```
--- /dev/null
- {{ .Site.LastChange | time.Format ":date_long" }} → October 16, 2023
+---
+title: LastChange
+description: Returns the last modification date of site content.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: time.Time
+ 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
- [functions]: /functions/time
- [methods]: /methods/time
++{{ .Site.LastChange | time.Format ":date_long" }} → January 31, 2024
+
+```
+
+[`time.Time`]: https://pkg.go.dev/time#Time
++[functions]: /functions/time/
++[methods]: /methods/time/
--- /dev/null
--- /dev/null
++---
++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/
--- /dev/null
- [menu templates]: /templates/menu-templates
+---
+title: Menus
+description: Returns a collection of menu objects for the given site.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/page/IsMenuCurrent
+ - methods/page/HasMenuCurrent
+ returnType: navigation.Menus
+ signatures: [SITE.Menus]
+---
+
+The `Menus` method on a `Site` object returns a collection of menus, where each menu contains one or more entries, either flat or nested. Each entry points to a page within the site, or to an external resource.
+
+{{% note %}}
+Menus can be defined and localized in several ways. Please see the [menus] section for a complete explanation and examples.
+
+[menus]: /content-management/menus/
+{{% /note %}}
+
+A site can have multiple menus. For example, a main menu and a footer menu:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+name = 'Home'
+pageRef = '/'
+weight = 10
+
+[[menus.main]]
+name = 'Books'
+pageRef = '/books'
+weight = 20
+
+[[menus.main]]
+name = 'Films'
+pageRef = '/films'
+weight = 30
+
+[[menus.footer]]
+name = 'Legal'
+pageRef = '/legal'
+weight = 10
+
+[[menus.footer]]
+name = 'Privacy'
+pageRef = '/privacy'
+weight = 20
+{{< /code-toggle >}}
+
+This template renders the main menu:
+
+```go-html-template
+{{ with site.Menus.main }}
+ <nav class="menu">
+ {{ range . }}
+ {{ if $.IsMenuCurrent .Menu . }}
+ <a class="active" aria-current="page" href="{{ .URL }}">{{ .Name }}</a>
+ {{ else }}
+ <a href="{{ .URL }}">{{ .Name }}</a>
+ {{ end }}
+ {{ end }}
+ </nav>
+{{ end }}
+```
+
+When viewing the home page, the result is:
+
+```html
+<nav class="menu">
+ <a class="active" aria-current="page" href="/">Home</a>
+ <a href="/books/">Books</a>
+ <a href="/films/">Films</a>
+</nav>
+```
+
+When viewing the "books" page, the result is:
+
+```html
+<nav class="menu">
+ <a href="/">Home</a>
+ <a class="active" aria-current="page" href="/books/">Books</a>
+ <a href="/films/">Films</a>
+</nav>
+```
+
+You will typically render a menu using a partial template. As the active menu entry will be different on each page, use the [`partial`] function to call the template. Do not use the [`partialCached`] function.
+
+The example above is simplistic. Please see the [menu templates] section for more information.
+
- [`partial`]: /functions/partials/include
- [`partialCached`]: /functions/partials/includecached
++[menu templates]: /templates/menu-templates/
+
++[`partial`]: /functions/partials/include/
++[`partialCached`]: /functions/partials/includecached/
--- /dev/null
- [`RegularPages`]: methods/site/regularpages
+---
+title: Pages
+description: Returns a collection of all pages.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/site/AllPages
+ - methods/site/RegularPages
+ - methods/site/Sections
+ returnType: page.Pages
+ signatures: [SITE.Pages]
+---
+
+This method returns all page [kinds] in the current language. That includes the home page, section pages, taxonomy pages, term pages, and regular pages.
+
+In most cases you should use the [`RegularPages`] method instead.
+
++[`RegularPages`]: /methods/site/regularpages/
+[kinds]: /getting-started/glossary/#page-kind
+
+```go-html-template
+{{ range .Site.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
--- /dev/null
- {{ .Site.LastChange.Format $layout }} → Tue, 17 Oct 2023 13:21:02 PDT
+---
+title: Params
+description: Returns a map of custom parameters as defined in the site configuration.
+categories: []
+keywords: []
+action:
+ related:
+ - functions/collections/indexFunction
+ - methods/page/Params
+ - methods/page/Param
+ returnType: maps.Params
+ signatures: [SITE.Params]
+---
+
+With this site configuration:
+
+{{< code-toggle file=hugo >}}
+[params]
+ subtitle = 'The Best Widgets on Earth'
+ copyright-year = '2023'
+ [params.author]
+ email = 'jsmith@example.org'
+ name = 'John Smith'
+ [params.layouts]
+ rfc_1123 = 'Mon, 02 Jan 2006 15:04:05 MST'
+ rfc_3339 = '2006-01-02T15:04:05-07:00'
+{{< /code-toggle >}}
+
+Access the custom parameters by [chaining] the [identifiers]:
+
+```go-html-template
+{{ .Site.Params.subtitle }} → The Best Widgets on Earth
+{{ .Site.Params.author.name }} → John Smith
+
+{{ $layout := .Site.Params.layouts.rfc_1123 }}
- [`index`]: /functions/collections/indexfunction
++{{ .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:
+
+```go-html-template
+{{ index .Site.Params "copyright-year" }} → 2023
+```
+
++[`index`]: /functions/collections/indexfunction/
+[chaining]: /getting-started/glossary/#chain
+[identifiers]: /getting-started/glossary/#identifier
--- /dev/null
- description: Returns a collection of all Site objects, one for each language, ordered by language weight.
+---
+title: Sites
- To render a link to home page of the primary (first) language:
++description: Returns a collection of all Site objects, one for each language, ordered by default content language then by language weight.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: page.Sites
+ signatures: [SITE.Sites]
+---
+
+With this site configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = false
+
+[languages.de]
+languageCode = 'de-DE'
+languageDirection = 'ltr'
+languageName = 'Deutsch'
+title = 'Projekt Dokumentation'
+weight = 1
+
+[languages.en]
+languageCode = 'en-US'
+languageDirection = 'ltr'
+languageName = 'English'
+title = 'Project Documentation'
+weight = 2
+{{< /code-toggle >}}
+
+This template:
+
+```go-html-template
+<ul>
+ {{ range .Site.Sites }}
+ <li><a href="{{ .Home.Permalink }}">{{ .Title }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Produces a list of links to each home page:
+
+```html
+<ul>
+ <li><a href="https://example.org/de/">Projekt Dokumentation</a></li>
+ <li><a href="https://example.org/en/">Project Documentation</a></li>
+</ul>
+```
+
- {{ with .Site.Sites.First }}
++To render a link to the home page of the site corresponding to the default content language:
+
+```go-html-template
++{{ with .Site.Sites.Default }}
+ <a href="{{ .Home.Permalink }}">{{ .Title }}</a>
+{{ end }}
+```
+
+This is equivalent to:
+
+```go-html-template
+{{ with index .Site.Sites 0 }}
+ <a href="{{ .Home.Permalink }}">{{ .Title }}</a>
+{{ end }}
+```
--- /dev/null
- [taxonomies]: content-management/taxonomies/
+---
+title: Taxonomies
+description: Returns a data structure containing the site's taxonomy objects, the terms within each taxonomy object, and the pages to which the terms are assigned.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: page.TaxonomyList
+ signatures: [SITE.Taxonomies]
+---
+
+Conceptually, the `Taxonomies` method on a `Site` object returns a data structure such as:
+
+{{< code-toggle >}}
+taxonomy a:
+ - term 1:
+ - page 1
+ - page 2
+ - term 2:
+ - page 1
+taxonomy b:
+ - term 1:
+ - page 2
+ - term 2:
+ - page 1
+ - page 2
+{{< /code-toggle >}}
+
+For example, on a book review site you might create two taxonomies; one for genres and another for authors.
+
+With this site configuration:
+
+{{< code-toggle file=hugo >}}
+[taxonomies]
+genre = 'genres'
+author = 'authors'
+{{< /code-toggle >}}
+
+And this content structure:
+
+```text
+content/
+├── books/
+│ ├── and-then-there-were-none.md --> genres: suspense
+│ ├── death-on-the-nile.md --> genres: suspense
+│ └── jamaica-inn.md --> genres: suspense, romance
+│ └── pride-and-prejudice.md --> genres: romance
+└── _index.md
+```
+
+Conceptually, the taxonomies data structure looks like:
+
+{{< code-toggle >}}
+genres:
+ - suspense:
+ - And Then There Were None
+ - Death on the Nile
+ - Jamaica Inn
+ - romance:
+ - Jamaica Inn
+ - Pride and Prejudice
+authors:
+ - achristie:
+ - And Then There Were None
+ - Death on the Nile
+ - ddmaurier:
+ - Jamaica Inn
+ - jausten:
+ - Pride and Prejudice
+{{< /code-toggle >}}
+
+
+To list the "suspense" books:
+
+```go-html-template
+<ul>
+ {{ range .Site.Taxonomies.genres.suspense }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Hugo renders this to:
+
+```html
+<ul>
+ <li><a href="/books/and-then-there-were-none/">And Then There Were None</a></li>
+ <li><a href="/books/death-on-the-nile/">Death on the Nile</a></li>
+ <li><a href="/books/jamaica-inn/">Jamaica Inn</a></li>
+</ul>
+```
+
+{{% note %}}
+Hugo's taxonomy system is powerful, allowing you to classify content and create relationships between pages.
+
+Please see the [taxonomies] section for a complete explanation and examples.
+
++[taxonomies]: /content-management/taxonomies/
+{{% /note %}}
--- /dev/null
- <pre>{{ jsonify (dict "indent" " ") $taxonomyObject.Alphabetical }}</pre>
+---
+title: Alphabetical
+description: Returns an ordered taxonomy, sorted alphabetically by term.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/taxonomy/ByCount
+ returnType: page.OrderedTaxonomy
+ signatures: [TAXONOMY.Alphabetical]
+toc: true
+---
+
+The `Alphabetical` method on a `Taxonomy` object returns an [ordered taxonomy], sorted alphabetically by [term].
+
+While a `Taxonomy` object is a [map], an ordered taxonomy is a [slice], where each element is an object that contains the term and a slice of its [weighted pages].
+
+{{% include "methods/taxonomy/_common/get-a-taxonomy-object.md" %}}
+
+## Get the ordered taxonomy
+
+Now that we have captured the “genres” Taxonomy object, let’s get the ordered taxonomy sorted alphabetically by term:
+
+```go-html-template
+{{ $taxonomyObject.Alphabetical }}
+```
+
+To reverse the sort order:
+
+```go-html-template
+{{ $taxonomyObject.Alphabetical.Reverse }}
+```
+
+To inspect the data structure:
+
+```go-html-template
++<pre>{{ debug.Dump $taxonomyObject.Alphabetical }}</pre>
+```
+
+{{% include "methods/taxonomy/_common/ordered-taxonomy-element-methods.md" %}}
+
+## Example
+
+With this template:
+
+```go-html-template
+{{ range $taxonomyObject.Alphabetical }}
+ <h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a> ({{ .Count }})</h2>
+ <ul>
+ {{ range .Pages.ByTitle }}
+ <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+Hugo renders:
+
+```html
+<h2><a href="/genres/romance/">romance</a> (2)</h2>
+<ul>
+ <li><a href="/books/jamaica-inn/">Jamaica inn</a></li>
+ <li><a href="/books/pride-and-prejudice/">Pride and prejudice</a></li>
+</ul>
+<h2><a href="/genres/suspense/">suspense</a> (3)</h2>
+<ul>
+ <li><a href="/books/and-then-there-were-none/">And then there were none</a></li>
+ <li><a href="/books/death-on-the-nile/">Death on the nile</a></li>
+ <li><a href="/books/jamaica-inn/">Jamaica inn</a></li>
+</ul>
+```
+
+[ordered taxonomy]: /getting-started/glossary/#ordered-taxonomy
+[term]: /getting-started/glossary/#term
+[map]: /getting-started/glossary/#map
+[slice]: /getting-started/glossary/#slice
+[term]: /getting-started/glossary/#term
+[weighted pages]: /getting-started/glossary/#weighted-page
--- /dev/null
- <pre>{{ jsonify (dict "indent" " ") $taxonomyObject.ByCount }}</pre>
+---
+title: ByCount
+description: Returns an ordered taxonomy, sorted by the number of pages associated with each term.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/taxonomy/Alphabetical
+ returnType: page.OrderedTaxonomy
+ signatures: [TAXONOMY.ByCount]
+toc: true
+---
+
+The `ByCount` method on a `Taxonomy` object returns an [ordered taxonomy], sorted by the number of pages associated with each [term].
+
+While a `Taxonomy` object is a [map], an ordered taxonomy is a [slice], where each element is an object that contains the term and a slice of its [weighted pages].
+
+{{% include "methods/taxonomy/_common/get-a-taxonomy-object.md" %}}
+
+## Get the ordered taxonomy
+
+Now that we have captured the “genres” Taxonomy object, let’s get the ordered taxonomy sorted by the number of pages associated with each term:
+
+```go-html-template
+{{ $taxonomyObject.ByCount }}
+```
+
+To reverse the sort order:
+
+```go-html-template
+{{ $taxonomyObject.ByCount.Reverse }}
+```
+
+To inspect the data structure:
+
+```go-html-template
++<pre>{{ debug.Dump $taxonomyObject.ByCount }}</pre>
+```
+
+{{% include "methods/taxonomy/_common/ordered-taxonomy-element-methods.md" %}}
+
+## Example
+
+With this template:
+
+```go-html-template
+{{ range $taxonomyObject.ByCount }}
+ <h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a> ({{ .Count }})</h2>
+ <ul>
+ {{ range .Pages.ByTitle }}
+ <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+Hugo renders:
+
+```html
+<h2><a href="/genres/suspense/">suspense</a> (3)</h2>
+<ul>
+ <li><a href="/books/and-then-there-were-none/">And then there were none</a></li>
+ <li><a href="/books/death-on-the-nile/">Death on the nile</a></li>
+ <li><a href="/books/jamaica-inn/">Jamaica inn</a></li>
+</ul>
+<h2><a href="/genres/romance/">romance</a> (2)</h2>
+<ul>
+ <li><a href="/books/jamaica-inn/">Jamaica inn</a></li>
+ <li><a href="/books/pride-and-prejudice/">Pride and prejudice</a></li>
+</ul>
+```
+
+[ordered taxonomy]: /getting-started/glossary/#ordered-taxonomy
+[term]: /getting-started/glossary/#term
+[map]: /getting-started/glossary/#map
+[slice]: /getting-started/glossary/#slice
+[term]: /getting-started/glossary/#term
+[weighted pages]: /getting-started/glossary/#weighted-page
--- /dev/null
- <pre>{{ jsonify (dict "indent" " ") $weightedPages }}</pre>
+---
+title: Get
+description: Returns a slice of weighted pages to which the given term has been assigned.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: page.WeightedPages
+ signatures: [TAXONOMY.Get TERM]
+toc: true
+---
+
+The `Get` method on a `Taxonomy` object returns a slice of [weighted pages] to which the given [term] has been assigned.
+
+{{% include "methods/taxonomy/_common/get-a-taxonomy-object.md" %}}
+
+## Get the weighted pages
+
+Now that we have captured the "genres" `Taxonomy` object, let's get the weighted pages to which the "suspense" term has been assigned:
+
+```go-html-template
+{{ $weightedPages := $taxonomyObject.Get "suspense" }}
+```
+
+The above is equivalent to:
+
+```go-html-template
+{{ $weightedPages := $taxonomyObject.suspense }}
+```
+
+But, if the term is not a valid [identifier], you cannot use the [chaining] syntax. For example, this will throw an error because the identifier contains a hyphen:
+
+```go-html-template
+{{ $weightedPages := $taxonomyObject.my-genre }}
+```
+
+You could also use the [`index`] function, but the syntax is more verbose:
+
+```go-html-template
+{{ $weightedPages := index $taxonomyObject "my-genre" }}
+```
+
+To inspect the data structure:
+
+```go-html-template
- [`index`]: /functions/collections/indexfunction
++<pre>{{ debug.Dump $weightedPages }}</pre>
+```
+
+## Example
+
+With this template:
+
+```go-html-template
+{{ $weightedPages := $taxonomyObject.Get "suspense" }}
+{{ range $weightedPages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+Hugo renders:
+
+```html
+<h2><a href="/books/jamaica-inn/">Jamaica inn</a></h2>
+<h2><a href="/books/death-on-the-nile/">Death on the nile</a></h2>
+<h2><a href="/books/and-then-there-were-none/">And then there were none</a></h2>
+```
+
+[chaining]: /getting-started/glossary/#chain
++[`index`]: /functions/collections/indexfunction/
+[identifier]: /getting-started/glossary/#identifier
+[term]: /getting-started/glossary/#term
+[weighted pages]: /getting-started/glossary/#weighted-page
--- /dev/null
--- /dev/null
++---
++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 }}
++ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
++{{ end }}
++```
++
++This is rendered to:
++
++```html
++<a href="/tags/">Tags</a>
++```
--- /dev/null
- Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+---
+cascade:
+ _build:
+ list: never
+ publishResources: false
+ render: never
+---
+
+<!--
++Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+
+Include the rendered content using the "include" shortcode.
+-->
--- /dev/null
- <pre>{{ jsonify (dict "indent" " ") $taxonomyObject }}</pre>
+---
+# Do not remove front matter.
+---
+
+Before we can use a `Taxonomy` method, we need to capture a `Taxonomy` object.
+
+## Capture a taxonomy object
+
+Consider this site configuration:
+
+{{< code-toggle file=hugo >}}
+[taxonomies]
+genre = 'genres'
+author = 'authors'
+{{< /code-toggle >}}
+
+And this content structure:
+
+```text
+content/
+├── books/
+│ ├── and-then-there-were-none.md --> genres: suspense
+│ ├── death-on-the-nile.md --> genres: suspense
+│ └── jamaica-inn.md --> genres: suspense, romance
+│ └── pride-and-prejudice.md --> genres: romance
+└── _index.md
+```
+
+To capture the "genres" taxonomy object from within any template, use the [`Taxonomies`] method on a `Site` object.
+
+```go-html-template
+{{ $taxonomyObject := .Site.Taxonomies.genres }}
+```
+
+To capture the "genres" taxonomy object when rendering its page with a taxonomy template, use the [`Terms`] method on the page's [`Data`] object:
+
+{{< code file=layouts/_default/taxonomy.html >}}
+{{ $taxonomyObject := .Data.Terms }}
+{{< /code >}}
+
+To inspect the data structure:
+
+```go-html-template
- [`Alphabetical`]: /methods/taxonomy/alphabetical
- [`ByCount`]: /methods/taxonomy/bycount
++<pre>{{ debug.Dump $taxonomyObject }}</pre>
+```
+
+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:
+
+```go-html-template
+{{ range $term, $weightedPages := $taxonomyObject }}
+ <h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a></h2>
+ <ul>
+ {{ range $weightedPages }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+In the example above, the first anchor element is a link to the term page.
+
+
- [`data`]: /methods/page/data
++[`Alphabetical`]: /methods/taxonomy/alphabetical/
++[`ByCount`]: /methods/taxonomy/bycount/
+
- [`taxonomies`]: /methods/site/taxonomies
++[`data`]: /methods/page/data/
+[`terms`]: /methods/page/data/#in-a-taxonomy-template
++[`taxonomies`]: /methods/site/taxonomies/
--- /dev/null
- [methods]: /methods/pages
+---
+# Do not remove front matter.
+---
+
+An ordered taxonomy is a slice, where each element is an object that contains the term and a slice of its weighted pages.
+
+Each element of the slice provides these methods:
+
+Count
+: (`int`) Returns the number of pages to which the term is assigned.
+
+Page
+: (`page.Page`) Returns the term's `Page` object, useful for linking to the term page.
+
+Pages
+: (`page.Pages`) Returns a `Pages` object containing the `Page` objects to which the term is assigned, sorted by [taxonomic weight]. To sort or group, use any of the [methods] available to the `Pages` object. For example, sort by the last modification date.
+
+Term
+: (`string`) Returns the term name.
+
+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/
+[taxonomic weight]: /getting-started/glossary/#taxonomic-weight
--- /dev/null
- [`time.Format`]: /functions/time/format
+---
+title: Format
+description: Returns a textual representation of the time.Time value formatted according to the layout string.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/time/AsTime
+ - methods/time/UTC
+ - methods/time/Local
+ returnType: string
+ signatures: [TIME.Format LAYOUT]
+toc: true
+aliases: [/methods/time/format]
+---
+
+```go-template
+{{ $t := "2023-01-27T23:44:58-08:00" }}
+{{ $t = time.AsTime $t }}
+{{ $format := "2 Jan 2006" }}
+
+{{ $t.Format $format }} → 27 Jan 2023
+```
+
+{{% note %}}
+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:
+
+```go-html-template
+{{ $format := "2 Jan 2006" }}
+
+{{ .Date.Format $format }}
+{{ .PublishDate.Format $format }}
+{{ .ExpiryDate.Format $format }}
+{{ .Lastmod.Format $format }}
+```
+
+{{% 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/
+{{% /note %}}
+
+## Layout string
+
+{{% include "functions/_common/time-layout-string.md" %}}
+
+## Examples
+
+Given this front matter:
+
+{{< code-toggle fm=true >}}
+title = "About time"
+date = 2023-01-27T23:44:58-08:00
+{{< /code-toggle >}}
+
+The examples below were rendered in the `America/Los_Angeles` time zone:
+
+Format string|Result
+:--|:--
+`Monday, January 2, 2006`|`Friday, January 27, 2023`
+`Mon Jan 2 2006`|`Fri Jan 27 2023`
+`January 2006`|`January 2023`
+`2006-01-02`|`2023-01-27`
+`Monday`|`Friday`
+`02 Jan 06 15:04 MST`|`27 Jan 23 23:44 PST`
+`Mon, 02 Jan 2006 15:04:05 MST`|`Fri, 27 Jan 2023 23:44:58 PST`
+`Mon, 02 Jan 2006 15:04:05 -0700`|`Fri, 27 Jan 2023 23:44:58 -0800`
+
+## UTC and local time
+
+Convert and format any `time.Time` value to either Coordinated Universal Time (UTC) or local time.
+
+```go-html-template
+{{ $t := "2023-01-27T23:44:58-08:00" }}
+{{ $t = time.AsTime $t }}
+{{ $format := "2 Jan 2006 3:04:05 PM MST" }}
+
+{{ $t.UTC.Format $format }} → 28 Jan 2023 7:44:58 AM UTC
+{{ $t.Local.Format $format }} → 27 Jan 2023 11:44:58 PM PST
+```
+
+## Ordinal representation
+
+Use the [`humanize`](/functions/inflect/humanize) function to render the day of the month as an ordinal number:
+
+```go-html-template
+{{ $t := "2023-01-27T23:44:58-08:00" }}
+{{ $t = time.AsTime $t }}
+
+{{ humanize $t.Day }} of {{ $t.Format "January 2006" }} → 27th of January 2023
+```
--- /dev/null
--- /dev/null
++---
++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
--- /dev/null
--- /dev/null
++---
++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
--- /dev/null
- 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.
+---
+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.
+categories: []
+keywords: []
+action:
+ related: []
+ returnType: int
+ signatures: [TIME.YearDay]
+---
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.YearDay }} → 27
+```
--- /dev/null
- title: Hugo News
+---
++title: News
++outputs:
++ - html
++ - rss
+aliases: [/release-notes/]
+---
--- /dev/null
- linkTitle: Overview
+---
+title: Quick reference guides
- identifier: quick-reference-overview
++linkTitle: In this section
+description: Quick reference guides to Hugo's features, functions, and methods.
+categories: []
+keywords: []
+menu:
+ docs:
++ identifier: quick-reference-in-this-section
+ parent: quick-reference
+ weight: 10
+weight: 10
+showSectionMenu: false
+---
+
+Quick reference guides to Hugo's features, functions, and methods.
--- /dev/null
- description: Include emoji shortcodes in your markdown or templates.
+---
+title: Emojis
- Configure Hugo to enable emoji processing in markdown:
++description: Include emoji shortcodes in your Markdown or templates.
+categories: [quick reference]
+keywords: [emoji]
+menu:
+ docs:
+ parent: quick-reference
+ weight: 20
+weight: 20
+toc: true
+---
+
- With emoji processing enabled, this markdown:
++Configure Hugo to enable emoji processing in Markdown:
+
+{{< code-toggle file=hugo >}}
+enableEmoji = true
+{{< /code-toggle >}}
+
- [`emojify`]: /functions/transform/emojify
- [`RenderString`]: /methods/page/renderstring
++With emoji processing enabled, this Markdown:
+
+```md
+Hello! :wave:
+```
+
+Is rendered to:
+
+```html
+Hello! 👋
+```
+
+And in your browser... Hello! :wave:
+
+To process an emoji shortcode from within a template, use the [`emojify`] function or pass the string through the [`RenderString`] method on a `Page` object:
+
+```go-html-template
+{{ "Hello! :wave:" | .RenderString }}
+```
+
++[`emojify`]: /functions/transform/emojify/
++[`RenderString`]: /methods/page/renderstring/
+
+## Introduction
+
+This quick reference guide was automatically generated from [GitHub Emoji API] and [Unicode Full Emoji List]. Specials thanks to [@ikatyang] for making [this list] available to the open-source community.
+
+GitHub [custom emoji] are not supported.
+
+[custom emoji]: #github-custom-emoji
+[@ikatyang]: https://github.com/ikatyang
+[github emoji api]: https://api.github.com/emojis
+[unicode full emoji list]: https://unicode.org/emoji/charts/full-emoji-list.html
+[this list]: https://github.com/ikatyang/emoji-cheat-sheet/#readme
+
+## Smileys & Emotion
+
+- [Face Smiling](#face-smiling)
+- [Face Affection](#face-affection)
+- [Face Tongue](#face-tongue)
+- [Face Hand](#face-hand)
+- [Face Neutral Skeptical](#face-neutral-skeptical)
+- [Face Sleepy](#face-sleepy)
+- [Face Unwell](#face-unwell)
+- [Face Hat](#face-hat)
+- [Face Glasses](#face-glasses)
+- [Face Concerned](#face-concerned)
+- [Face Negative](#face-negative)
+- [Face Costume](#face-costume)
+- [Cat Face](#cat-face)
+- [Monkey Face](#monkey-face)
+- [Heart](#heart)
+- [Emotion](#emotion)
+
+### Face Smiling
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#introduction) | :grinning: | `:grinning:` | :smiley: | `:smiley:` | [top](#introduction) |
+| [top](#introduction) | :smile: | `:smile:` | :grin: | `:grin:` | [top](#introduction) |
+| [top](#introduction) | :laughing: | `:laughing:` `:satisfied:` | :sweat_smile: | `:sweat_smile:` | [top](#introduction) |
+| [top](#introduction) | :rofl: | `:rofl:` | :joy: | `:joy:` | [top](#introduction) |
+| [top](#introduction) | :slightly_smiling_face: | `:slightly_smiling_face:` | :upside_down_face: | `:upside_down_face:` | [top](#introduction) |
+| [top](#introduction) | :wink: | `:wink:` | :blush: | `:blush:` | [top](#introduction) |
+| [top](#introduction) | :innocent: | `:innocent:` | | | [top](#introduction) |
+
+### Face Affection
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#introduction) | :smiling_face_with_three_hearts: | `:smiling_face_with_three_hearts:` | :heart_eyes: | `:heart_eyes:` | [top](#introduction) |
+| [top](#introduction) | :star_struck: | `:star_struck:` | :kissing_heart: | `:kissing_heart:` | [top](#introduction) |
+| [top](#introduction) | :kissing: | `:kissing:` | :relaxed: | `:relaxed:` | [top](#introduction) |
+| [top](#introduction) | :kissing_closed_eyes: | `:kissing_closed_eyes:` | :kissing_smiling_eyes: | `:kissing_smiling_eyes:` | [top](#introduction) |
+| [top](#introduction) | :smiling_face_with_tear: | `:smiling_face_with_tear:` | | | [top](#introduction) |
+
+### Face Tongue
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#introduction) | :yum: | `:yum:` | :stuck_out_tongue: | `:stuck_out_tongue:` | [top](#introduction) |
+| [top](#introduction) | :stuck_out_tongue_winking_eye: | `:stuck_out_tongue_winking_eye:` | :zany_face: | `:zany_face:` | [top](#introduction) |
+| [top](#introduction) | :stuck_out_tongue_closed_eyes: | `:stuck_out_tongue_closed_eyes:` | :money_mouth_face: | `:money_mouth_face:` | [top](#introduction) |
+
+### Face Hand
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#introduction) | :hugs: | `:hugs:` | :hand_over_mouth: | `:hand_over_mouth:` | [top](#introduction) |
+| [top](#introduction) | :shushing_face: | `:shushing_face:` | :thinking: | `:thinking:` | [top](#introduction) |
+
+### Face Neutral Skeptical
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#introduction) | :zipper_mouth_face: | `:zipper_mouth_face:` | :raised_eyebrow: | `:raised_eyebrow:` | [top](#introduction) |
+| [top](#introduction) | :neutral_face: | `:neutral_face:` | :expressionless: | `:expressionless:` | [top](#introduction) |
+| [top](#introduction) | :no_mouth: | `:no_mouth:` | :face_in_clouds: | `:face_in_clouds:` | [top](#introduction) |
+| [top](#introduction) | :smirk: | `:smirk:` | :unamused: | `:unamused:` | [top](#introduction) |
+| [top](#introduction) | :roll_eyes: | `:roll_eyes:` | :grimacing: | `:grimacing:` | [top](#introduction) |
+| [top](#introduction) | :face_exhaling: | `:face_exhaling:` | :lying_face: | `:lying_face:` | [top](#introduction) |
+
+### Face Sleepy
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#introduction) | :relieved: | `:relieved:` | :pensive: | `:pensive:` | [top](#introduction) |
+| [top](#introduction) | :sleepy: | `:sleepy:` | :drooling_face: | `:drooling_face:` | [top](#introduction) |
+| [top](#introduction) | :sleeping: | `:sleeping:` | | | [top](#introduction) |
+
+### Face Unwell
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#introduction) | :mask: | `:mask:` | :face_with_thermometer: | `:face_with_thermometer:` | [top](#introduction) |
+| [top](#introduction) | :face_with_head_bandage: | `:face_with_head_bandage:` | :nauseated_face: | `:nauseated_face:` | [top](#introduction) |
+| [top](#introduction) | :vomiting_face: | `:vomiting_face:` | :sneezing_face: | `:sneezing_face:` | [top](#introduction) |
+| [top](#introduction) | :hot_face: | `:hot_face:` | :cold_face: | `:cold_face:` | [top](#introduction) |
+| [top](#introduction) | :woozy_face: | `:woozy_face:` | :dizzy_face: | `:dizzy_face:` | [top](#introduction) |
+| [top](#introduction) | :face_with_spiral_eyes: | `:face_with_spiral_eyes:` | :exploding_head: | `:exploding_head:` | [top](#introduction) |
+
+### Face Hat
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#introduction) | :cowboy_hat_face: | `:cowboy_hat_face:` | :partying_face: | `:partying_face:` | [top](#introduction) |
+| [top](#introduction) | :disguised_face: | `:disguised_face:` | | | [top](#introduction) |
+
+### Face Glasses
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#introduction) | :sunglasses: | `:sunglasses:` | :nerd_face: | `:nerd_face:` | [top](#introduction) |
+| [top](#introduction) | :monocle_face: | `:monocle_face:` | | | [top](#introduction) |
+
+### Face Concerned
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#introduction) | :confused: | `:confused:` | :worried: | `:worried:` | [top](#introduction) |
+| [top](#introduction) | :slightly_frowning_face: | `:slightly_frowning_face:` | :frowning_face: | `:frowning_face:` | [top](#introduction) |
+| [top](#introduction) | :open_mouth: | `:open_mouth:` | :hushed: | `:hushed:` | [top](#introduction) |
+| [top](#introduction) | :astonished: | `:astonished:` | :flushed: | `:flushed:` | [top](#introduction) |
+| [top](#introduction) | :pleading_face: | `:pleading_face:` | :frowning: | `:frowning:` | [top](#introduction) |
+| [top](#introduction) | :anguished: | `:anguished:` | :fearful: | `:fearful:` | [top](#introduction) |
+| [top](#introduction) | :cold_sweat: | `:cold_sweat:` | :disappointed_relieved: | `:disappointed_relieved:` | [top](#introduction) |
+| [top](#introduction) | :cry: | `:cry:` | :sob: | `:sob:` | [top](#introduction) |
+| [top](#introduction) | :scream: | `:scream:` | :confounded: | `:confounded:` | [top](#introduction) |
+| [top](#introduction) | :persevere: | `:persevere:` | :disappointed: | `:disappointed:` | [top](#introduction) |
+| [top](#introduction) | :sweat: | `:sweat:` | :weary: | `:weary:` | [top](#introduction) |
+| [top](#introduction) | :tired_face: | `:tired_face:` | :yawning_face: | `:yawning_face:` | [top](#introduction) |
+
+### Face Negative
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#introduction) | :triumph: | `:triumph:` | :pout: | `:pout:` `:rage:` | [top](#introduction) |
+| [top](#introduction) | :angry: | `:angry:` | :cursing_face: | `:cursing_face:` | [top](#introduction) |
+| [top](#introduction) | :smiling_imp: | `:smiling_imp:` | :imp: | `:imp:` | [top](#introduction) |
+| [top](#introduction) | :skull: | `:skull:` | :skull_and_crossbones: | `:skull_and_crossbones:` | [top](#introduction) |
+
+### Face Costume
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#introduction) | :hankey: | `:hankey:` `:poop:` `:shit:` | :clown_face: | `:clown_face:` | [top](#introduction) |
+| [top](#introduction) | :japanese_ogre: | `:japanese_ogre:` | :japanese_goblin: | `:japanese_goblin:` | [top](#introduction) |
+| [top](#introduction) | :ghost: | `:ghost:` | :alien: | `:alien:` | [top](#introduction) |
+| [top](#introduction) | :space_invader: | `:space_invader:` | :robot: | `:robot:` | [top](#introduction) |
+
+### Cat Face
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#introduction) | :smiley_cat: | `:smiley_cat:` | :smile_cat: | `:smile_cat:` | [top](#introduction) |
+| [top](#introduction) | :joy_cat: | `:joy_cat:` | :heart_eyes_cat: | `:heart_eyes_cat:` | [top](#introduction) |
+| [top](#introduction) | :smirk_cat: | `:smirk_cat:` | :kissing_cat: | `:kissing_cat:` | [top](#introduction) |
+| [top](#introduction) | :scream_cat: | `:scream_cat:` | :crying_cat_face: | `:crying_cat_face:` | [top](#introduction) |
+| [top](#introduction) | :pouting_cat: | `:pouting_cat:` | | | [top](#introduction) |
+
+### Monkey Face
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#introduction) | :see_no_evil: | `:see_no_evil:` | :hear_no_evil: | `:hear_no_evil:` | [top](#introduction) |
+| [top](#introduction) | :speak_no_evil: | `:speak_no_evil:` | | | [top](#introduction) |
+
+### Heart
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#introduction) | :love_letter: | `:love_letter:` | :cupid: | `:cupid:` | [top](#introduction) |
+| [top](#introduction) | :gift_heart: | `:gift_heart:` | :sparkling_heart: | `:sparkling_heart:` | [top](#introduction) |
+| [top](#introduction) | :heartpulse: | `:heartpulse:` | :heartbeat: | `:heartbeat:` | [top](#introduction) |
+| [top](#introduction) | :revolving_hearts: | `:revolving_hearts:` | :two_hearts: | `:two_hearts:` | [top](#introduction) |
+| [top](#introduction) | :heart_decoration: | `:heart_decoration:` | :heavy_heart_exclamation: | `:heavy_heart_exclamation:` | [top](#introduction) |
+| [top](#introduction) | :broken_heart: | `:broken_heart:` | :heart_on_fire: | `:heart_on_fire:` | [top](#introduction) |
+| [top](#introduction) | :mending_heart: | `:mending_heart:` | :heart: | `:heart:` | [top](#introduction) |
+| [top](#introduction) | :orange_heart: | `:orange_heart:` | :yellow_heart: | `:yellow_heart:` | [top](#introduction) |
+| [top](#introduction) | :green_heart: | `:green_heart:` | :blue_heart: | `:blue_heart:` | [top](#introduction) |
+| [top](#introduction) | :purple_heart: | `:purple_heart:` | :brown_heart: | `:brown_heart:` | [top](#introduction) |
+| [top](#introduction) | :black_heart: | `:black_heart:` | :white_heart: | `:white_heart:` | [top](#introduction) |
+
+### Emotion
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#introduction) | :kiss: | `:kiss:` | :100: | `:100:` | [top](#introduction) |
+| [top](#introduction) | :anger: | `:anger:` | :boom: | `:boom:` `:collision:` | [top](#introduction) |
+| [top](#introduction) | :dizzy: | `:dizzy:` | :sweat_drops: | `:sweat_drops:` | [top](#introduction) |
+| [top](#introduction) | :dash: | `:dash:` | :hole: | `:hole:` | [top](#introduction) |
+| [top](#introduction) | :speech_balloon: | `:speech_balloon:` | :eye_speech_bubble: | `:eye_speech_bubble:` | [top](#introduction) |
+| [top](#introduction) | :left_speech_bubble: | `:left_speech_bubble:` | :right_anger_bubble: | `:right_anger_bubble:` | [top](#introduction) |
+| [top](#introduction) | :thought_balloon: | `:thought_balloon:` | :zzz: | `:zzz:` | [top](#introduction) |
+
+## People & Body
+
+- [Hand Fingers Open](#hand-fingers-open)
+- [Hand Fingers Partial](#hand-fingers-partial)
+- [Hand Single Finger](#hand-single-finger)
+- [Hand Fingers Closed](#hand-fingers-closed)
+- [Hands](#hands)
+- [Hand Prop](#hand-prop)
+- [Body Parts](#body-parts)
+- [Person](#person)
+- [Person Gesture](#person-gesture)
+- [Person Role](#person-role)
+- [Person Fantasy](#person-fantasy)
+- [Person Activity](#person-activity)
+- [Person Sport](#person-sport)
+- [Person Resting](#person-resting)
+- [Family](#family)
+- [Person Symbol](#person-symbol)
+
+### Hand Fingers Open
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :wave: | `:wave:` | :raised_back_of_hand: | `:raised_back_of_hand:` | [top](#introduction) |
+| [top](#people--body) | :raised_hand_with_fingers_splayed: | `:raised_hand_with_fingers_splayed:` | :hand: | `:hand:` `:raised_hand:` | [top](#introduction) |
+| [top](#people--body) | :vulcan_salute: | `:vulcan_salute:` | | | [top](#introduction) |
+
+### Hand Fingers Partial
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :ok_hand: | `:ok_hand:` | :pinched_fingers: | `:pinched_fingers:` | [top](#introduction) |
+| [top](#people--body) | :pinching_hand: | `:pinching_hand:` | :v: | `:v:` | [top](#introduction) |
+| [top](#people--body) | :crossed_fingers: | `:crossed_fingers:` | :love_you_gesture: | `:love_you_gesture:` | [top](#introduction) |
+| [top](#people--body) | :metal: | `:metal:` | :call_me_hand: | `:call_me_hand:` | [top](#introduction) |
+
+### Hand Single Finger
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :point_left: | `:point_left:` | :point_right: | `:point_right:` | [top](#introduction) |
+| [top](#people--body) | :point_up_2: | `:point_up_2:` | :fu: | `:fu:` `:middle_finger:` | [top](#introduction) |
+| [top](#people--body) | :point_down: | `:point_down:` | :point_up: | `:point_up:` | [top](#introduction) |
+
+### Hand Fingers Closed
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :+1: | `:+1:` `:thumbsup:` | :-1: | `:-1:` `:thumbsdown:` | [top](#introduction) |
+| [top](#people--body) | :fist: | `:fist:` `:fist_raised:` | :facepunch: | `:facepunch:` `:fist_oncoming:` `:punch:` | [top](#introduction) |
+| [top](#people--body) | :fist_left: | `:fist_left:` | :fist_right: | `:fist_right:` | [top](#introduction) |
+
+### Hands
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :clap: | `:clap:` | :raised_hands: | `:raised_hands:` | [top](#introduction) |
+| [top](#people--body) | :open_hands: | `:open_hands:` | :palms_up_together: | `:palms_up_together:` | [top](#introduction) |
+| [top](#people--body) | :handshake: | `:handshake:` | :pray: | `:pray:` | [top](#introduction) |
+
+### Hand Prop
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :writing_hand: | `:writing_hand:` | :nail_care: | `:nail_care:` | [top](#introduction) |
+| [top](#people--body) | :selfie: | `:selfie:` | | | [top](#introduction) |
+
+### Body Parts
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :muscle: | `:muscle:` | :mechanical_arm: | `:mechanical_arm:` | [top](#introduction) |
+| [top](#people--body) | :mechanical_leg: | `:mechanical_leg:` | :leg: | `:leg:` | [top](#introduction) |
+| [top](#people--body) | :foot: | `:foot:` | :ear: | `:ear:` | [top](#introduction) |
+| [top](#people--body) | :ear_with_hearing_aid: | `:ear_with_hearing_aid:` | :nose: | `:nose:` | [top](#introduction) |
+| [top](#people--body) | :brain: | `:brain:` | :anatomical_heart: | `:anatomical_heart:` | [top](#introduction) |
+| [top](#people--body) | :lungs: | `:lungs:` | :tooth: | `:tooth:` | [top](#introduction) |
+| [top](#people--body) | :bone: | `:bone:` | :eyes: | `:eyes:` | [top](#introduction) |
+| [top](#people--body) | :eye: | `:eye:` | :tongue: | `:tongue:` | [top](#introduction) |
+| [top](#people--body) | :lips: | `:lips:` | | | [top](#introduction) |
+
+### Person
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :baby: | `:baby:` | :child: | `:child:` | [top](#introduction) |
+| [top](#people--body) | :boy: | `:boy:` | :girl: | `:girl:` | [top](#introduction) |
+| [top](#people--body) | :adult: | `:adult:` | :blond_haired_person: | `:blond_haired_person:` | [top](#introduction) |
+| [top](#people--body) | :man: | `:man:` | :bearded_person: | `:bearded_person:` | [top](#introduction) |
+| [top](#people--body) | :man_beard: | `:man_beard:` | :woman_beard: | `:woman_beard:` | [top](#introduction) |
+| [top](#people--body) | :red_haired_man: | `:red_haired_man:` | :curly_haired_man: | `:curly_haired_man:` | [top](#introduction) |
+| [top](#people--body) | :white_haired_man: | `:white_haired_man:` | :bald_man: | `:bald_man:` | [top](#introduction) |
+| [top](#people--body) | :woman: | `:woman:` | :red_haired_woman: | `:red_haired_woman:` | [top](#introduction) |
+| [top](#people--body) | :person_red_hair: | `:person_red_hair:` | :curly_haired_woman: | `:curly_haired_woman:` | [top](#introduction) |
+| [top](#people--body) | :person_curly_hair: | `:person_curly_hair:` | :white_haired_woman: | `:white_haired_woman:` | [top](#introduction) |
+| [top](#people--body) | :person_white_hair: | `:person_white_hair:` | :bald_woman: | `:bald_woman:` | [top](#introduction) |
+| [top](#people--body) | :person_bald: | `:person_bald:` | :blond_haired_woman: | `:blond_haired_woman:` `:blonde_woman:` | [top](#introduction) |
+| [top](#people--body) | :blond_haired_man: | `:blond_haired_man:` | :older_adult: | `:older_adult:` | [top](#introduction) |
+| [top](#people--body) | :older_man: | `:older_man:` | :older_woman: | `:older_woman:` | [top](#introduction) |
+
+### Person Gesture
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :frowning_person: | `:frowning_person:` | :frowning_man: | `:frowning_man:` | [top](#introduction) |
+| [top](#people--body) | :frowning_woman: | `:frowning_woman:` | :pouting_face: | `:pouting_face:` | [top](#introduction) |
+| [top](#people--body) | :pouting_man: | `:pouting_man:` | :pouting_woman: | `:pouting_woman:` | [top](#introduction) |
+| [top](#people--body) | :no_good: | `:no_good:` | :ng_man: | `:ng_man:` `:no_good_man:` | [top](#introduction) |
+| [top](#people--body) | :ng_woman: | `:ng_woman:` `:no_good_woman:` | :ok_person: | `:ok_person:` | [top](#introduction) |
+| [top](#people--body) | :ok_man: | `:ok_man:` | :ok_woman: | `:ok_woman:` | [top](#introduction) |
+| [top](#people--body) | :information_desk_person: | `:information_desk_person:` `:tipping_hand_person:` | :sassy_man: | `:sassy_man:` `:tipping_hand_man:` | [top](#introduction) |
+| [top](#people--body) | :sassy_woman: | `:sassy_woman:` `:tipping_hand_woman:` | :raising_hand: | `:raising_hand:` | [top](#introduction) |
+| [top](#people--body) | :raising_hand_man: | `:raising_hand_man:` | :raising_hand_woman: | `:raising_hand_woman:` | [top](#introduction) |
+| [top](#people--body) | :deaf_person: | `:deaf_person:` | :deaf_man: | `:deaf_man:` | [top](#introduction) |
+| [top](#people--body) | :deaf_woman: | `:deaf_woman:` | :bow: | `:bow:` | [top](#introduction) |
+| [top](#people--body) | :bowing_man: | `:bowing_man:` | :bowing_woman: | `:bowing_woman:` | [top](#introduction) |
+| [top](#people--body) | :facepalm: | `:facepalm:` | :man_facepalming: | `:man_facepalming:` | [top](#introduction) |
+| [top](#people--body) | :woman_facepalming: | `:woman_facepalming:` | :shrug: | `:shrug:` | [top](#introduction) |
+| [top](#people--body) | :man_shrugging: | `:man_shrugging:` | :woman_shrugging: | `:woman_shrugging:` | [top](#introduction) |
+
+### Person Role
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :health_worker: | `:health_worker:` | :man_health_worker: | `:man_health_worker:` | [top](#introduction) |
+| [top](#people--body) | :woman_health_worker: | `:woman_health_worker:` | :student: | `:student:` | [top](#introduction) |
+| [top](#people--body) | :man_student: | `:man_student:` | :woman_student: | `:woman_student:` | [top](#introduction) |
+| [top](#people--body) | :teacher: | `:teacher:` | :man_teacher: | `:man_teacher:` | [top](#introduction) |
+| [top](#people--body) | :woman_teacher: | `:woman_teacher:` | :judge: | `:judge:` | [top](#introduction) |
+| [top](#people--body) | :man_judge: | `:man_judge:` | :woman_judge: | `:woman_judge:` | [top](#introduction) |
+| [top](#people--body) | :farmer: | `:farmer:` | :man_farmer: | `:man_farmer:` | [top](#introduction) |
+| [top](#people--body) | :woman_farmer: | `:woman_farmer:` | :cook: | `:cook:` | [top](#introduction) |
+| [top](#people--body) | :man_cook: | `:man_cook:` | :woman_cook: | `:woman_cook:` | [top](#introduction) |
+| [top](#people--body) | :mechanic: | `:mechanic:` | :man_mechanic: | `:man_mechanic:` | [top](#introduction) |
+| [top](#people--body) | :woman_mechanic: | `:woman_mechanic:` | :factory_worker: | `:factory_worker:` | [top](#introduction) |
+| [top](#people--body) | :man_factory_worker: | `:man_factory_worker:` | :woman_factory_worker: | `:woman_factory_worker:` | [top](#introduction) |
+| [top](#people--body) | :office_worker: | `:office_worker:` | :man_office_worker: | `:man_office_worker:` | [top](#introduction) |
+| [top](#people--body) | :woman_office_worker: | `:woman_office_worker:` | :scientist: | `:scientist:` | [top](#introduction) |
+| [top](#people--body) | :man_scientist: | `:man_scientist:` | :woman_scientist: | `:woman_scientist:` | [top](#introduction) |
+| [top](#people--body) | :technologist: | `:technologist:` | :man_technologist: | `:man_technologist:` | [top](#introduction) |
+| [top](#people--body) | :woman_technologist: | `:woman_technologist:` | :singer: | `:singer:` | [top](#introduction) |
+| [top](#people--body) | :man_singer: | `:man_singer:` | :woman_singer: | `:woman_singer:` | [top](#introduction) |
+| [top](#people--body) | :artist: | `:artist:` | :man_artist: | `:man_artist:` | [top](#introduction) |
+| [top](#people--body) | :woman_artist: | `:woman_artist:` | :pilot: | `:pilot:` | [top](#introduction) |
+| [top](#people--body) | :man_pilot: | `:man_pilot:` | :woman_pilot: | `:woman_pilot:` | [top](#introduction) |
+| [top](#people--body) | :astronaut: | `:astronaut:` | :man_astronaut: | `:man_astronaut:` | [top](#introduction) |
+| [top](#people--body) | :woman_astronaut: | `:woman_astronaut:` | :firefighter: | `:firefighter:` | [top](#introduction) |
+| [top](#people--body) | :man_firefighter: | `:man_firefighter:` | :woman_firefighter: | `:woman_firefighter:` | [top](#introduction) |
+| [top](#people--body) | :cop: | `:cop:` `:police_officer:` | :policeman: | `:policeman:` | [top](#introduction) |
+| [top](#people--body) | :policewoman: | `:policewoman:` | :detective: | `:detective:` | [top](#introduction) |
+| [top](#people--body) | :male_detective: | `:male_detective:` | :female_detective: | `:female_detective:` | [top](#introduction) |
+| [top](#people--body) | :guard: | `:guard:` | :guardsman: | `:guardsman:` | [top](#introduction) |
+| [top](#people--body) | :guardswoman: | `:guardswoman:` | :ninja: | `:ninja:` | [top](#introduction) |
+| [top](#people--body) | :construction_worker: | `:construction_worker:` | :construction_worker_man: | `:construction_worker_man:` | [top](#introduction) |
+| [top](#people--body) | :construction_worker_woman: | `:construction_worker_woman:` | :prince: | `:prince:` | [top](#introduction) |
+| [top](#people--body) | :princess: | `:princess:` | :person_with_turban: | `:person_with_turban:` | [top](#introduction) |
+| [top](#people--body) | :man_with_turban: | `:man_with_turban:` | :woman_with_turban: | `:woman_with_turban:` | [top](#introduction) |
+| [top](#people--body) | :man_with_gua_pi_mao: | `:man_with_gua_pi_mao:` | :woman_with_headscarf: | `:woman_with_headscarf:` | [top](#introduction) |
+| [top](#people--body) | :person_in_tuxedo: | `:person_in_tuxedo:` | :man_in_tuxedo: | `:man_in_tuxedo:` | [top](#introduction) |
+| [top](#people--body) | :woman_in_tuxedo: | `:woman_in_tuxedo:` | :person_with_veil: | `:person_with_veil:` | [top](#introduction) |
+| [top](#people--body) | :man_with_veil: | `:man_with_veil:` | :bride_with_veil: | `:bride_with_veil:` `:woman_with_veil:` | [top](#introduction) |
+| [top](#people--body) | :pregnant_woman: | `:pregnant_woman:` | :breast_feeding: | `:breast_feeding:` | [top](#introduction) |
+| [top](#people--body) | :woman_feeding_baby: | `:woman_feeding_baby:` | :man_feeding_baby: | `:man_feeding_baby:` | [top](#introduction) |
+| [top](#people--body) | :person_feeding_baby: | `:person_feeding_baby:` | | | [top](#introduction) |
+
+### Person Fantasy
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :angel: | `:angel:` | :santa: | `:santa:` | [top](#introduction) |
+| [top](#people--body) | :mrs_claus: | `:mrs_claus:` | :mx_claus: | `:mx_claus:` | [top](#introduction) |
+| [top](#people--body) | :superhero: | `:superhero:` | :superhero_man: | `:superhero_man:` | [top](#introduction) |
+| [top](#people--body) | :superhero_woman: | `:superhero_woman:` | :supervillain: | `:supervillain:` | [top](#introduction) |
+| [top](#people--body) | :supervillain_man: | `:supervillain_man:` | :supervillain_woman: | `:supervillain_woman:` | [top](#introduction) |
+| [top](#people--body) | :mage: | `:mage:` | :mage_man: | `:mage_man:` | [top](#introduction) |
+| [top](#people--body) | :mage_woman: | `:mage_woman:` | :fairy: | `:fairy:` | [top](#introduction) |
+| [top](#people--body) | :fairy_man: | `:fairy_man:` | :fairy_woman: | `:fairy_woman:` | [top](#introduction) |
+| [top](#people--body) | :vampire: | `:vampire:` | :vampire_man: | `:vampire_man:` | [top](#introduction) |
+| [top](#people--body) | :vampire_woman: | `:vampire_woman:` | :merperson: | `:merperson:` | [top](#introduction) |
+| [top](#people--body) | :merman: | `:merman:` | :mermaid: | `:mermaid:` | [top](#introduction) |
+| [top](#people--body) | :elf: | `:elf:` | :elf_man: | `:elf_man:` | [top](#introduction) |
+| [top](#people--body) | :elf_woman: | `:elf_woman:` | :genie: | `:genie:` | [top](#introduction) |
+| [top](#people--body) | :genie_man: | `:genie_man:` | :genie_woman: | `:genie_woman:` | [top](#introduction) |
+| [top](#people--body) | :zombie: | `:zombie:` | :zombie_man: | `:zombie_man:` | [top](#introduction) |
+| [top](#people--body) | :zombie_woman: | `:zombie_woman:` | | | [top](#introduction) |
+
+### Person Activity
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :massage: | `:massage:` | :massage_man: | `:massage_man:` | [top](#introduction) |
+| [top](#people--body) | :massage_woman: | `:massage_woman:` | :haircut: | `:haircut:` | [top](#introduction) |
+| [top](#people--body) | :haircut_man: | `:haircut_man:` | :haircut_woman: | `:haircut_woman:` | [top](#introduction) |
+| [top](#people--body) | :walking: | `:walking:` | :walking_man: | `:walking_man:` | [top](#introduction) |
+| [top](#people--body) | :walking_woman: | `:walking_woman:` | :standing_person: | `:standing_person:` | [top](#introduction) |
+| [top](#people--body) | :standing_man: | `:standing_man:` | :standing_woman: | `:standing_woman:` | [top](#introduction) |
+| [top](#people--body) | :kneeling_person: | `:kneeling_person:` | :kneeling_man: | `:kneeling_man:` | [top](#introduction) |
+| [top](#people--body) | :kneeling_woman: | `:kneeling_woman:` | :person_with_probing_cane: | `:person_with_probing_cane:` | [top](#introduction) |
+| [top](#people--body) | :man_with_probing_cane: | `:man_with_probing_cane:` | :woman_with_probing_cane: | `:woman_with_probing_cane:` | [top](#introduction) |
+| [top](#people--body) | :person_in_motorized_wheelchair: | `:person_in_motorized_wheelchair:` | :man_in_motorized_wheelchair: | `:man_in_motorized_wheelchair:` | [top](#introduction) |
+| [top](#people--body) | :woman_in_motorized_wheelchair: | `:woman_in_motorized_wheelchair:` | :person_in_manual_wheelchair: | `:person_in_manual_wheelchair:` | [top](#introduction) |
+| [top](#people--body) | :man_in_manual_wheelchair: | `:man_in_manual_wheelchair:` | :woman_in_manual_wheelchair: | `:woman_in_manual_wheelchair:` | [top](#introduction) |
+| [top](#people--body) | :runner: | `:runner:` `:running:` | :running_man: | `:running_man:` | [top](#introduction) |
+| [top](#people--body) | :running_woman: | `:running_woman:` | :dancer: | `:dancer:` `:woman_dancing:` | [top](#introduction) |
+| [top](#people--body) | :man_dancing: | `:man_dancing:` | :business_suit_levitating: | `:business_suit_levitating:` | [top](#introduction) |
+| [top](#people--body) | :dancers: | `:dancers:` | :dancing_men: | `:dancing_men:` | [top](#introduction) |
+| [top](#people--body) | :dancing_women: | `:dancing_women:` | :sauna_person: | `:sauna_person:` | [top](#introduction) |
+| [top](#people--body) | :sauna_man: | `:sauna_man:` | :sauna_woman: | `:sauna_woman:` | [top](#introduction) |
+| [top](#people--body) | :climbing: | `:climbing:` | :climbing_man: | `:climbing_man:` | [top](#introduction) |
+| [top](#people--body) | :climbing_woman: | `:climbing_woman:` | | | [top](#introduction) |
+
+### Person Sport
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :person_fencing: | `:person_fencing:` | :horse_racing: | `:horse_racing:` | [top](#introduction) |
+| [top](#people--body) | :skier: | `:skier:` | :snowboarder: | `:snowboarder:` | [top](#introduction) |
+| [top](#people--body) | :golfing: | `:golfing:` | :golfing_man: | `:golfing_man:` | [top](#introduction) |
+| [top](#people--body) | :golfing_woman: | `:golfing_woman:` | :surfer: | `:surfer:` | [top](#introduction) |
+| [top](#people--body) | :surfing_man: | `:surfing_man:` | :surfing_woman: | `:surfing_woman:` | [top](#introduction) |
+| [top](#people--body) | :rowboat: | `:rowboat:` | :rowing_man: | `:rowing_man:` | [top](#introduction) |
+| [top](#people--body) | :rowing_woman: | `:rowing_woman:` | :swimmer: | `:swimmer:` | [top](#introduction) |
+| [top](#people--body) | :swimming_man: | `:swimming_man:` | :swimming_woman: | `:swimming_woman:` | [top](#introduction) |
+| [top](#people--body) | :bouncing_ball_person: | `:bouncing_ball_person:` | :basketball_man: | `:basketball_man:` `:bouncing_ball_man:` | [top](#introduction) |
+| [top](#people--body) | :basketball_woman: | `:basketball_woman:` `:bouncing_ball_woman:` | :weight_lifting: | `:weight_lifting:` | [top](#introduction) |
+| [top](#people--body) | :weight_lifting_man: | `:weight_lifting_man:` | :weight_lifting_woman: | `:weight_lifting_woman:` | [top](#introduction) |
+| [top](#people--body) | :bicyclist: | `:bicyclist:` | :biking_man: | `:biking_man:` | [top](#introduction) |
+| [top](#people--body) | :biking_woman: | `:biking_woman:` | :mountain_bicyclist: | `:mountain_bicyclist:` | [top](#introduction) |
+| [top](#people--body) | :mountain_biking_man: | `:mountain_biking_man:` | :mountain_biking_woman: | `:mountain_biking_woman:` | [top](#introduction) |
+| [top](#people--body) | :cartwheeling: | `:cartwheeling:` | :man_cartwheeling: | `:man_cartwheeling:` | [top](#introduction) |
+| [top](#people--body) | :woman_cartwheeling: | `:woman_cartwheeling:` | :wrestling: | `:wrestling:` | [top](#introduction) |
+| [top](#people--body) | :men_wrestling: | `:men_wrestling:` | :women_wrestling: | `:women_wrestling:` | [top](#introduction) |
+| [top](#people--body) | :water_polo: | `:water_polo:` | :man_playing_water_polo: | `:man_playing_water_polo:` | [top](#introduction) |
+| [top](#people--body) | :woman_playing_water_polo: | `:woman_playing_water_polo:` | :handball_person: | `:handball_person:` | [top](#introduction) |
+| [top](#people--body) | :man_playing_handball: | `:man_playing_handball:` | :woman_playing_handball: | `:woman_playing_handball:` | [top](#introduction) |
+| [top](#people--body) | :juggling_person: | `:juggling_person:` | :man_juggling: | `:man_juggling:` | [top](#introduction) |
+| [top](#people--body) | :woman_juggling: | `:woman_juggling:` | | | [top](#introduction) |
+
+### Person Resting
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :lotus_position: | `:lotus_position:` | :lotus_position_man: | `:lotus_position_man:` | [top](#introduction) |
+| [top](#people--body) | :lotus_position_woman: | `:lotus_position_woman:` | :bath: | `:bath:` | [top](#introduction) |
+| [top](#people--body) | :sleeping_bed: | `:sleeping_bed:` | | | [top](#introduction) |
+
+### Family
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :people_holding_hands: | `:people_holding_hands:` | :two_women_holding_hands: | `:two_women_holding_hands:` | [top](#introduction) |
+| [top](#people--body) | :couple: | `:couple:` | :two_men_holding_hands: | `:two_men_holding_hands:` | [top](#introduction) |
+| [top](#people--body) | :couplekiss: | `:couplekiss:` | :couplekiss_man_woman: | `:couplekiss_man_woman:` | [top](#introduction) |
+| [top](#people--body) | :couplekiss_man_man: | `:couplekiss_man_man:` | :couplekiss_woman_woman: | `:couplekiss_woman_woman:` | [top](#introduction) |
+| [top](#people--body) | :couple_with_heart: | `:couple_with_heart:` | :couple_with_heart_woman_man: | `:couple_with_heart_woman_man:` | [top](#introduction) |
+| [top](#people--body) | :couple_with_heart_man_man: | `:couple_with_heart_man_man:` | :couple_with_heart_woman_woman: | `:couple_with_heart_woman_woman:` | [top](#introduction) |
+| [top](#people--body) | :family_man_woman_boy: | `:family_man_woman_boy:` | :family_man_woman_girl: | `:family_man_woman_girl:` | [top](#introduction) |
+| [top](#people--body) | :family_man_woman_girl_boy: | `:family_man_woman_girl_boy:` | :family_man_woman_boy_boy: | `:family_man_woman_boy_boy:` | [top](#introduction) |
+| [top](#people--body) | :family_man_woman_girl_girl: | `:family_man_woman_girl_girl:` | :family_man_man_boy: | `:family_man_man_boy:` | [top](#introduction) |
+| [top](#people--body) | :family_man_man_girl: | `:family_man_man_girl:` | :family_man_man_girl_boy: | `:family_man_man_girl_boy:` | [top](#introduction) |
+| [top](#people--body) | :family_man_man_boy_boy: | `:family_man_man_boy_boy:` | :family_man_man_girl_girl: | `:family_man_man_girl_girl:` | [top](#introduction) |
+| [top](#people--body) | :family_woman_woman_boy: | `:family_woman_woman_boy:` | :family_woman_woman_girl: | `:family_woman_woman_girl:` | [top](#introduction) |
+| [top](#people--body) | :family_woman_woman_girl_boy: | `:family_woman_woman_girl_boy:` | :family_woman_woman_boy_boy: | `:family_woman_woman_boy_boy:` | [top](#introduction) |
+| [top](#people--body) | :family_woman_woman_girl_girl: | `:family_woman_woman_girl_girl:` | :family_man_boy: | `:family_man_boy:` | [top](#introduction) |
+| [top](#people--body) | :family_man_boy_boy: | `:family_man_boy_boy:` | :family_man_girl: | `:family_man_girl:` | [top](#introduction) |
+| [top](#people--body) | :family_man_girl_boy: | `:family_man_girl_boy:` | :family_man_girl_girl: | `:family_man_girl_girl:` | [top](#introduction) |
+| [top](#people--body) | :family_woman_boy: | `:family_woman_boy:` | :family_woman_boy_boy: | `:family_woman_boy_boy:` | [top](#introduction) |
+| [top](#people--body) | :family_woman_girl: | `:family_woman_girl:` | :family_woman_girl_boy: | `:family_woman_girl_boy:` | [top](#introduction) |
+| [top](#people--body) | :family_woman_girl_girl: | `:family_woman_girl_girl:` | | | [top](#introduction) |
+
+### Person Symbol
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :speaking_head: | `:speaking_head:` | :bust_in_silhouette: | `:bust_in_silhouette:` | [top](#introduction) |
+| [top](#people--body) | :busts_in_silhouette: | `:busts_in_silhouette:` | :people_hugging: | `:people_hugging:` | [top](#introduction) |
+| [top](#people--body) | :family: | `:family:` | :footprints: | `:footprints:` | [top](#introduction) |
+
+## Animals & Nature
+
+- [Animal Mammal](#animal-mammal)
+- [Animal Bird](#animal-bird)
+- [Animal Amphibian](#animal-amphibian)
+- [Animal Reptile](#animal-reptile)
+- [Animal Marine](#animal-marine)
+- [Animal Bug](#animal-bug)
+- [Plant Flower](#plant-flower)
+- [Plant Other](#plant-other)
+
+### Animal Mammal
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#animals--nature) | :monkey_face: | `:monkey_face:` | :monkey: | `:monkey:` | [top](#introduction) |
+| [top](#animals--nature) | :gorilla: | `:gorilla:` | :orangutan: | `:orangutan:` | [top](#introduction) |
+| [top](#animals--nature) | :dog: | `:dog:` | :dog2: | `:dog2:` | [top](#introduction) |
+| [top](#animals--nature) | :guide_dog: | `:guide_dog:` | :service_dog: | `:service_dog:` | [top](#introduction) |
+| [top](#animals--nature) | :poodle: | `:poodle:` | :wolf: | `:wolf:` | [top](#introduction) |
+| [top](#animals--nature) | :fox_face: | `:fox_face:` | :raccoon: | `:raccoon:` | [top](#introduction) |
+| [top](#animals--nature) | :cat: | `:cat:` | :cat2: | `:cat2:` | [top](#introduction) |
+| [top](#animals--nature) | :black_cat: | `:black_cat:` | :lion: | `:lion:` | [top](#introduction) |
+| [top](#animals--nature) | :tiger: | `:tiger:` | :tiger2: | `:tiger2:` | [top](#introduction) |
+| [top](#animals--nature) | :leopard: | `:leopard:` | :horse: | `:horse:` | [top](#introduction) |
+| [top](#animals--nature) | :racehorse: | `:racehorse:` | :unicorn: | `:unicorn:` | [top](#introduction) |
+| [top](#animals--nature) | :zebra: | `:zebra:` | :deer: | `:deer:` | [top](#introduction) |
+| [top](#animals--nature) | :bison: | `:bison:` | :cow: | `:cow:` | [top](#introduction) |
+| [top](#animals--nature) | :ox: | `:ox:` | :water_buffalo: | `:water_buffalo:` | [top](#introduction) |
+| [top](#animals--nature) | :cow2: | `:cow2:` | :pig: | `:pig:` | [top](#introduction) |
+| [top](#animals--nature) | :pig2: | `:pig2:` | :boar: | `:boar:` | [top](#introduction) |
+| [top](#animals--nature) | :pig_nose: | `:pig_nose:` | :ram: | `:ram:` | [top](#introduction) |
+| [top](#animals--nature) | :sheep: | `:sheep:` | :goat: | `:goat:` | [top](#introduction) |
+| [top](#animals--nature) | :dromedary_camel: | `:dromedary_camel:` | :camel: | `:camel:` | [top](#introduction) |
+| [top](#animals--nature) | :llama: | `:llama:` | :giraffe: | `:giraffe:` | [top](#introduction) |
+| [top](#animals--nature) | :elephant: | `:elephant:` | :mammoth: | `:mammoth:` | [top](#introduction) |
+| [top](#animals--nature) | :rhinoceros: | `:rhinoceros:` | :hippopotamus: | `:hippopotamus:` | [top](#introduction) |
+| [top](#animals--nature) | :mouse: | `:mouse:` | :mouse2: | `:mouse2:` | [top](#introduction) |
+| [top](#animals--nature) | :rat: | `:rat:` | :hamster: | `:hamster:` | [top](#introduction) |
+| [top](#animals--nature) | :rabbit: | `:rabbit:` | :rabbit2: | `:rabbit2:` | [top](#introduction) |
+| [top](#animals--nature) | :chipmunk: | `:chipmunk:` | :beaver: | `:beaver:` | [top](#introduction) |
+| [top](#animals--nature) | :hedgehog: | `:hedgehog:` | :bat: | `:bat:` | [top](#introduction) |
+| [top](#animals--nature) | :bear: | `:bear:` | :polar_bear: | `:polar_bear:` | [top](#introduction) |
+| [top](#animals--nature) | :koala: | `:koala:` | :panda_face: | `:panda_face:` | [top](#introduction) |
+| [top](#animals--nature) | :sloth: | `:sloth:` | :otter: | `:otter:` | [top](#introduction) |
+| [top](#animals--nature) | :skunk: | `:skunk:` | :kangaroo: | `:kangaroo:` | [top](#introduction) |
+| [top](#animals--nature) | :badger: | `:badger:` | :feet: | `:feet:` `:paw_prints:` | [top](#introduction) |
+
+### Animal Bird
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#animals--nature) | :turkey: | `:turkey:` | :chicken: | `:chicken:` | [top](#introduction) |
+| [top](#animals--nature) | :rooster: | `:rooster:` | :hatching_chick: | `:hatching_chick:` | [top](#introduction) |
+| [top](#animals--nature) | :baby_chick: | `:baby_chick:` | :hatched_chick: | `:hatched_chick:` | [top](#introduction) |
+| [top](#animals--nature) | :bird: | `:bird:` | :penguin: | `:penguin:` | [top](#introduction) |
+| [top](#animals--nature) | :dove: | `:dove:` | :eagle: | `:eagle:` | [top](#introduction) |
+| [top](#animals--nature) | :duck: | `:duck:` | :swan: | `:swan:` | [top](#introduction) |
+| [top](#animals--nature) | :owl: | `:owl:` | :dodo: | `:dodo:` | [top](#introduction) |
+| [top](#animals--nature) | :feather: | `:feather:` | :flamingo: | `:flamingo:` | [top](#introduction) |
+| [top](#animals--nature) | :peacock: | `:peacock:` | :parrot: | `:parrot:` | [top](#introduction) |
+
+### Animal Amphibian
+
+| | ico | shortcode | |
+| - | :-: | - | - |
+| [top](#animals--nature) | :frog: | `:frog:` | [top](#introduction) |
+
+### Animal Reptile
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#animals--nature) | :crocodile: | `:crocodile:` | :turtle: | `:turtle:` | [top](#introduction) |
+| [top](#animals--nature) | :lizard: | `:lizard:` | :snake: | `:snake:` | [top](#introduction) |
+| [top](#animals--nature) | :dragon_face: | `:dragon_face:` | :dragon: | `:dragon:` | [top](#introduction) |
+| [top](#animals--nature) | :sauropod: | `:sauropod:` | :t-rex: | `:t-rex:` | [top](#introduction) |
+
+### Animal Marine
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#animals--nature) | :whale: | `:whale:` | :whale2: | `:whale2:` | [top](#introduction) |
+| [top](#animals--nature) | :dolphin: | `:dolphin:` `:flipper:` | :seal: | `:seal:` | [top](#introduction) |
+| [top](#animals--nature) | :fish: | `:fish:` | :tropical_fish: | `:tropical_fish:` | [top](#introduction) |
+| [top](#animals--nature) | :blowfish: | `:blowfish:` | :shark: | `:shark:` | [top](#introduction) |
+| [top](#animals--nature) | :octopus: | `:octopus:` | :shell: | `:shell:` | [top](#introduction) |
+
+### Animal Bug
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#animals--nature) | :snail: | `:snail:` | :butterfly: | `:butterfly:` | [top](#introduction) |
+| [top](#animals--nature) | :bug: | `:bug:` | :ant: | `:ant:` | [top](#introduction) |
+| [top](#animals--nature) | :bee: | `:bee:` `:honeybee:` | :beetle: | `:beetle:` | [top](#introduction) |
+| [top](#animals--nature) | :lady_beetle: | `:lady_beetle:` | :cricket: | `:cricket:` | [top](#introduction) |
+| [top](#animals--nature) | :cockroach: | `:cockroach:` | :spider: | `:spider:` | [top](#introduction) |
+| [top](#animals--nature) | :spider_web: | `:spider_web:` | :scorpion: | `:scorpion:` | [top](#introduction) |
+| [top](#animals--nature) | :mosquito: | `:mosquito:` | :fly: | `:fly:` | [top](#introduction) |
+| [top](#animals--nature) | :worm: | `:worm:` | :microbe: | `:microbe:` | [top](#introduction) |
+
+### Plant Flower
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#animals--nature) | :bouquet: | `:bouquet:` | :cherry_blossom: | `:cherry_blossom:` | [top](#introduction) |
+| [top](#animals--nature) | :white_flower: | `:white_flower:` | :rosette: | `:rosette:` | [top](#introduction) |
+| [top](#animals--nature) | :rose: | `:rose:` | :wilted_flower: | `:wilted_flower:` | [top](#introduction) |
+| [top](#animals--nature) | :hibiscus: | `:hibiscus:` | :sunflower: | `:sunflower:` | [top](#introduction) |
+| [top](#animals--nature) | :blossom: | `:blossom:` | :tulip: | `:tulip:` | [top](#introduction) |
+
+### Plant Other
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#animals--nature) | :seedling: | `:seedling:` | :potted_plant: | `:potted_plant:` | [top](#introduction) |
+| [top](#animals--nature) | :evergreen_tree: | `:evergreen_tree:` | :deciduous_tree: | `:deciduous_tree:` | [top](#introduction) |
+| [top](#animals--nature) | :palm_tree: | `:palm_tree:` | :cactus: | `:cactus:` | [top](#introduction) |
+| [top](#animals--nature) | :ear_of_rice: | `:ear_of_rice:` | :herb: | `:herb:` | [top](#introduction) |
+| [top](#animals--nature) | :shamrock: | `:shamrock:` | :four_leaf_clover: | `:four_leaf_clover:` | [top](#introduction) |
+| [top](#animals--nature) | :maple_leaf: | `:maple_leaf:` | :fallen_leaf: | `:fallen_leaf:` | [top](#introduction) |
+| [top](#animals--nature) | :leaves: | `:leaves:` | :mushroom: | `:mushroom:` | [top](#introduction) |
+
+## Food & Drink
+
+- [Food Fruit](#food-fruit)
+- [Food Vegetable](#food-vegetable)
+- [Food Prepared](#food-prepared)
+- [Food Asian](#food-asian)
+- [Food Marine](#food-marine)
+- [Food Sweet](#food-sweet)
+- [Drink](#drink)
+- [Dishware](#dishware)
+
+### Food Fruit
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#food--drink) | :grapes: | `:grapes:` | :melon: | `:melon:` | [top](#introduction) |
+| [top](#food--drink) | :watermelon: | `:watermelon:` | :mandarin: | `:mandarin:` `:orange:` `:tangerine:` | [top](#introduction) |
+| [top](#food--drink) | :lemon: | `:lemon:` | :banana: | `:banana:` | [top](#introduction) |
+| [top](#food--drink) | :pineapple: | `:pineapple:` | :mango: | `:mango:` | [top](#introduction) |
+| [top](#food--drink) | :apple: | `:apple:` | :green_apple: | `:green_apple:` | [top](#introduction) |
+| [top](#food--drink) | :pear: | `:pear:` | :peach: | `:peach:` | [top](#introduction) |
+| [top](#food--drink) | :cherries: | `:cherries:` | :strawberry: | `:strawberry:` | [top](#introduction) |
+| [top](#food--drink) | :blueberries: | `:blueberries:` | :kiwi_fruit: | `:kiwi_fruit:` | [top](#introduction) |
+| [top](#food--drink) | :tomato: | `:tomato:` | :olive: | `:olive:` | [top](#introduction) |
+| [top](#food--drink) | :coconut: | `:coconut:` | | | [top](#introduction) |
+
+### Food Vegetable
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#food--drink) | :avocado: | `:avocado:` | :eggplant: | `:eggplant:` | [top](#introduction) |
+| [top](#food--drink) | :potato: | `:potato:` | :carrot: | `:carrot:` | [top](#introduction) |
+| [top](#food--drink) | :corn: | `:corn:` | :hot_pepper: | `:hot_pepper:` | [top](#introduction) |
+| [top](#food--drink) | :bell_pepper: | `:bell_pepper:` | :cucumber: | `:cucumber:` | [top](#introduction) |
+| [top](#food--drink) | :leafy_green: | `:leafy_green:` | :broccoli: | `:broccoli:` | [top](#introduction) |
+| [top](#food--drink) | :garlic: | `:garlic:` | :onion: | `:onion:` | [top](#introduction) |
+| [top](#food--drink) | :peanuts: | `:peanuts:` | :chestnut: | `:chestnut:` | [top](#introduction) |
+
+### Food Prepared
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#food--drink) | :bread: | `:bread:` | :croissant: | `:croissant:` | [top](#introduction) |
+| [top](#food--drink) | :baguette_bread: | `:baguette_bread:` | :flatbread: | `:flatbread:` | [top](#introduction) |
+| [top](#food--drink) | :pretzel: | `:pretzel:` | :bagel: | `:bagel:` | [top](#introduction) |
+| [top](#food--drink) | :pancakes: | `:pancakes:` | :waffle: | `:waffle:` | [top](#introduction) |
+| [top](#food--drink) | :cheese: | `:cheese:` | :meat_on_bone: | `:meat_on_bone:` | [top](#introduction) |
+| [top](#food--drink) | :poultry_leg: | `:poultry_leg:` | :cut_of_meat: | `:cut_of_meat:` | [top](#introduction) |
+| [top](#food--drink) | :bacon: | `:bacon:` | :hamburger: | `:hamburger:` | [top](#introduction) |
+| [top](#food--drink) | :fries: | `:fries:` | :pizza: | `:pizza:` | [top](#introduction) |
+| [top](#food--drink) | :hotdog: | `:hotdog:` | :sandwich: | `:sandwich:` | [top](#introduction) |
+| [top](#food--drink) | :taco: | `:taco:` | :burrito: | `:burrito:` | [top](#introduction) |
+| [top](#food--drink) | :tamale: | `:tamale:` | :stuffed_flatbread: | `:stuffed_flatbread:` | [top](#introduction) |
+| [top](#food--drink) | :falafel: | `:falafel:` | :egg: | `:egg:` | [top](#introduction) |
+| [top](#food--drink) | :fried_egg: | `:fried_egg:` | :shallow_pan_of_food: | `:shallow_pan_of_food:` | [top](#introduction) |
+| [top](#food--drink) | :stew: | `:stew:` | :fondue: | `:fondue:` | [top](#introduction) |
+| [top](#food--drink) | :bowl_with_spoon: | `:bowl_with_spoon:` | :green_salad: | `:green_salad:` | [top](#introduction) |
+| [top](#food--drink) | :popcorn: | `:popcorn:` | :butter: | `:butter:` | [top](#introduction) |
+| [top](#food--drink) | :salt: | `:salt:` | :canned_food: | `:canned_food:` | [top](#introduction) |
+
+### Food Asian
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#food--drink) | :bento: | `:bento:` | :rice_cracker: | `:rice_cracker:` | [top](#introduction) |
+| [top](#food--drink) | :rice_ball: | `:rice_ball:` | :rice: | `:rice:` | [top](#introduction) |
+| [top](#food--drink) | :curry: | `:curry:` | :ramen: | `:ramen:` | [top](#introduction) |
+| [top](#food--drink) | :spaghetti: | `:spaghetti:` | :sweet_potato: | `:sweet_potato:` | [top](#introduction) |
+| [top](#food--drink) | :oden: | `:oden:` | :sushi: | `:sushi:` | [top](#introduction) |
+| [top](#food--drink) | :fried_shrimp: | `:fried_shrimp:` | :fish_cake: | `:fish_cake:` | [top](#introduction) |
+| [top](#food--drink) | :moon_cake: | `:moon_cake:` | :dango: | `:dango:` | [top](#introduction) |
+| [top](#food--drink) | :dumpling: | `:dumpling:` | :fortune_cookie: | `:fortune_cookie:` | [top](#introduction) |
+| [top](#food--drink) | :takeout_box: | `:takeout_box:` | | | [top](#introduction) |
+
+### Food Marine
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#food--drink) | :crab: | `:crab:` | :lobster: | `:lobster:` | [top](#introduction) |
+| [top](#food--drink) | :shrimp: | `:shrimp:` | :squid: | `:squid:` | [top](#introduction) |
+| [top](#food--drink) | :oyster: | `:oyster:` | | | [top](#introduction) |
+
+### Food Sweet
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#food--drink) | :icecream: | `:icecream:` | :shaved_ice: | `:shaved_ice:` | [top](#introduction) |
+| [top](#food--drink) | :ice_cream: | `:ice_cream:` | :doughnut: | `:doughnut:` | [top](#introduction) |
+| [top](#food--drink) | :cookie: | `:cookie:` | :birthday: | `:birthday:` | [top](#introduction) |
+| [top](#food--drink) | :cake: | `:cake:` | :cupcake: | `:cupcake:` | [top](#introduction) |
+| [top](#food--drink) | :pie: | `:pie:` | :chocolate_bar: | `:chocolate_bar:` | [top](#introduction) |
+| [top](#food--drink) | :candy: | `:candy:` | :lollipop: | `:lollipop:` | [top](#introduction) |
+| [top](#food--drink) | :custard: | `:custard:` | :honey_pot: | `:honey_pot:` | [top](#introduction) |
+
+### Drink
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#food--drink) | :baby_bottle: | `:baby_bottle:` | :milk_glass: | `:milk_glass:` | [top](#introduction) |
+| [top](#food--drink) | :coffee: | `:coffee:` | :teapot: | `:teapot:` | [top](#introduction) |
+| [top](#food--drink) | :tea: | `:tea:` | :sake: | `:sake:` | [top](#introduction) |
+| [top](#food--drink) | :champagne: | `:champagne:` | :wine_glass: | `:wine_glass:` | [top](#introduction) |
+| [top](#food--drink) | :cocktail: | `:cocktail:` | :tropical_drink: | `:tropical_drink:` | [top](#introduction) |
+| [top](#food--drink) | :beer: | `:beer:` | :beers: | `:beers:` | [top](#introduction) |
+| [top](#food--drink) | :clinking_glasses: | `:clinking_glasses:` | :tumbler_glass: | `:tumbler_glass:` | [top](#introduction) |
+| [top](#food--drink) | :cup_with_straw: | `:cup_with_straw:` | :bubble_tea: | `:bubble_tea:` | [top](#introduction) |
+| [top](#food--drink) | :beverage_box: | `:beverage_box:` | :mate: | `:mate:` | [top](#introduction) |
+| [top](#food--drink) | :ice_cube: | `:ice_cube:` | | | [top](#introduction) |
+
+### Dishware
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#food--drink) | :chopsticks: | `:chopsticks:` | :plate_with_cutlery: | `:plate_with_cutlery:` | [top](#introduction) |
+| [top](#food--drink) | :fork_and_knife: | `:fork_and_knife:` | :spoon: | `:spoon:` | [top](#introduction) |
+| [top](#food--drink) | :hocho: | `:hocho:` `:knife:` | :amphora: | `:amphora:` | [top](#introduction) |
+
+## Travel & Places
+
+- [Place Map](#place-map)
+- [Place Geographic](#place-geographic)
+- [Place Building](#place-building)
+- [Place Religious](#place-religious)
+- [Place Other](#place-other)
+- [Transport Ground](#transport-ground)
+- [Transport Water](#transport-water)
+- [Transport Air](#transport-air)
+- [Hotel](#hotel)
+- [Time](#time)
+- [Sky & Weather](#sky--weather)
+
+### Place Map
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#travel--places) | :earth_africa: | `:earth_africa:` | :earth_americas: | `:earth_americas:` | [top](#introduction) |
+| [top](#travel--places) | :earth_asia: | `:earth_asia:` | :globe_with_meridians: | `:globe_with_meridians:` | [top](#introduction) |
+| [top](#travel--places) | :world_map: | `:world_map:` | :japan: | `:japan:` | [top](#introduction) |
+| [top](#travel--places) | :compass: | `:compass:` | | | [top](#introduction) |
+
+### Place Geographic
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#travel--places) | :mountain_snow: | `:mountain_snow:` | :mountain: | `:mountain:` | [top](#introduction) |
+| [top](#travel--places) | :volcano: | `:volcano:` | :mount_fuji: | `:mount_fuji:` | [top](#introduction) |
+| [top](#travel--places) | :camping: | `:camping:` | :beach_umbrella: | `:beach_umbrella:` | [top](#introduction) |
+| [top](#travel--places) | :desert: | `:desert:` | :desert_island: | `:desert_island:` | [top](#introduction) |
+| [top](#travel--places) | :national_park: | `:national_park:` | | | [top](#introduction) |
+
+### Place Building
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#travel--places) | :stadium: | `:stadium:` | :classical_building: | `:classical_building:` | [top](#introduction) |
+| [top](#travel--places) | :building_construction: | `:building_construction:` | :bricks: | `:bricks:` | [top](#introduction) |
+| [top](#travel--places) | :rock: | `:rock:` | :wood: | `:wood:` | [top](#introduction) |
+| [top](#travel--places) | :hut: | `:hut:` | :houses: | `:houses:` | [top](#introduction) |
+| [top](#travel--places) | :derelict_house: | `:derelict_house:` | :house: | `:house:` | [top](#introduction) |
+| [top](#travel--places) | :house_with_garden: | `:house_with_garden:` | :office: | `:office:` | [top](#introduction) |
+| [top](#travel--places) | :post_office: | `:post_office:` | :european_post_office: | `:european_post_office:` | [top](#introduction) |
+| [top](#travel--places) | :hospital: | `:hospital:` | :bank: | `:bank:` | [top](#introduction) |
+| [top](#travel--places) | :hotel: | `:hotel:` | :love_hotel: | `:love_hotel:` | [top](#introduction) |
+| [top](#travel--places) | :convenience_store: | `:convenience_store:` | :school: | `:school:` | [top](#introduction) |
+| [top](#travel--places) | :department_store: | `:department_store:` | :factory: | `:factory:` | [top](#introduction) |
+| [top](#travel--places) | :japanese_castle: | `:japanese_castle:` | :european_castle: | `:european_castle:` | [top](#introduction) |
+| [top](#travel--places) | :wedding: | `:wedding:` | :tokyo_tower: | `:tokyo_tower:` | [top](#introduction) |
+| [top](#travel--places) | :statue_of_liberty: | `:statue_of_liberty:` | | | [top](#introduction) |
+
+### Place Religious
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#travel--places) | :church: | `:church:` | :mosque: | `:mosque:` | [top](#introduction) |
+| [top](#travel--places) | :hindu_temple: | `:hindu_temple:` | :synagogue: | `:synagogue:` | [top](#introduction) |
+| [top](#travel--places) | :shinto_shrine: | `:shinto_shrine:` | :kaaba: | `:kaaba:` | [top](#introduction) |
+
+### Place Other
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#travel--places) | :fountain: | `:fountain:` | :tent: | `:tent:` | [top](#introduction) |
+| [top](#travel--places) | :foggy: | `:foggy:` | :night_with_stars: | `:night_with_stars:` | [top](#introduction) |
+| [top](#travel--places) | :cityscape: | `:cityscape:` | :sunrise_over_mountains: | `:sunrise_over_mountains:` | [top](#introduction) |
+| [top](#travel--places) | :sunrise: | `:sunrise:` | :city_sunset: | `:city_sunset:` | [top](#introduction) |
+| [top](#travel--places) | :city_sunrise: | `:city_sunrise:` | :bridge_at_night: | `:bridge_at_night:` | [top](#introduction) |
+| [top](#travel--places) | :hotsprings: | `:hotsprings:` | :carousel_horse: | `:carousel_horse:` | [top](#introduction) |
+| [top](#travel--places) | :ferris_wheel: | `:ferris_wheel:` | :roller_coaster: | `:roller_coaster:` | [top](#introduction) |
+| [top](#travel--places) | :barber: | `:barber:` | :circus_tent: | `:circus_tent:` | [top](#introduction) |
+
+### Transport Ground
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#travel--places) | :steam_locomotive: | `:steam_locomotive:` | :railway_car: | `:railway_car:` | [top](#introduction) |
+| [top](#travel--places) | :bullettrain_side: | `:bullettrain_side:` | :bullettrain_front: | `:bullettrain_front:` | [top](#introduction) |
+| [top](#travel--places) | :train2: | `:train2:` | :metro: | `:metro:` | [top](#introduction) |
+| [top](#travel--places) | :light_rail: | `:light_rail:` | :station: | `:station:` | [top](#introduction) |
+| [top](#travel--places) | :tram: | `:tram:` | :monorail: | `:monorail:` | [top](#introduction) |
+| [top](#travel--places) | :mountain_railway: | `:mountain_railway:` | :train: | `:train:` | [top](#introduction) |
+| [top](#travel--places) | :bus: | `:bus:` | :oncoming_bus: | `:oncoming_bus:` | [top](#introduction) |
+| [top](#travel--places) | :trolleybus: | `:trolleybus:` | :minibus: | `:minibus:` | [top](#introduction) |
+| [top](#travel--places) | :ambulance: | `:ambulance:` | :fire_engine: | `:fire_engine:` | [top](#introduction) |
+| [top](#travel--places) | :police_car: | `:police_car:` | :oncoming_police_car: | `:oncoming_police_car:` | [top](#introduction) |
+| [top](#travel--places) | :taxi: | `:taxi:` | :oncoming_taxi: | `:oncoming_taxi:` | [top](#introduction) |
+| [top](#travel--places) | :car: | `:car:` `:red_car:` | :oncoming_automobile: | `:oncoming_automobile:` | [top](#introduction) |
+| [top](#travel--places) | :blue_car: | `:blue_car:` | :pickup_truck: | `:pickup_truck:` | [top](#introduction) |
+| [top](#travel--places) | :truck: | `:truck:` | :articulated_lorry: | `:articulated_lorry:` | [top](#introduction) |
+| [top](#travel--places) | :tractor: | `:tractor:` | :racing_car: | `:racing_car:` | [top](#introduction) |
+| [top](#travel--places) | :motorcycle: | `:motorcycle:` | :motor_scooter: | `:motor_scooter:` | [top](#introduction) |
+| [top](#travel--places) | :manual_wheelchair: | `:manual_wheelchair:` | :motorized_wheelchair: | `:motorized_wheelchair:` | [top](#introduction) |
+| [top](#travel--places) | :auto_rickshaw: | `:auto_rickshaw:` | :bike: | `:bike:` | [top](#introduction) |
+| [top](#travel--places) | :kick_scooter: | `:kick_scooter:` | :skateboard: | `:skateboard:` | [top](#introduction) |
+| [top](#travel--places) | :roller_skate: | `:roller_skate:` | :busstop: | `:busstop:` | [top](#introduction) |
+| [top](#travel--places) | :motorway: | `:motorway:` | :railway_track: | `:railway_track:` | [top](#introduction) |
+| [top](#travel--places) | :oil_drum: | `:oil_drum:` | :fuelpump: | `:fuelpump:` | [top](#introduction) |
+| [top](#travel--places) | :rotating_light: | `:rotating_light:` | :traffic_light: | `:traffic_light:` | [top](#introduction) |
+| [top](#travel--places) | :vertical_traffic_light: | `:vertical_traffic_light:` | :stop_sign: | `:stop_sign:` | [top](#introduction) |
+| [top](#travel--places) | :construction: | `:construction:` | | | [top](#introduction) |
+
+### Transport Water
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#travel--places) | :anchor: | `:anchor:` | :boat: | `:boat:` `:sailboat:` | [top](#introduction) |
+| [top](#travel--places) | :canoe: | `:canoe:` | :speedboat: | `:speedboat:` | [top](#introduction) |
+| [top](#travel--places) | :passenger_ship: | `:passenger_ship:` | :ferry: | `:ferry:` | [top](#introduction) |
+| [top](#travel--places) | :motor_boat: | `:motor_boat:` | :ship: | `:ship:` | [top](#introduction) |
+
+### Transport Air
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#travel--places) | :airplane: | `:airplane:` | :small_airplane: | `:small_airplane:` | [top](#introduction) |
+| [top](#travel--places) | :flight_departure: | `:flight_departure:` | :flight_arrival: | `:flight_arrival:` | [top](#introduction) |
+| [top](#travel--places) | :parachute: | `:parachute:` | :seat: | `:seat:` | [top](#introduction) |
+| [top](#travel--places) | :helicopter: | `:helicopter:` | :suspension_railway: | `:suspension_railway:` | [top](#introduction) |
+| [top](#travel--places) | :mountain_cableway: | `:mountain_cableway:` | :aerial_tramway: | `:aerial_tramway:` | [top](#introduction) |
+| [top](#travel--places) | :artificial_satellite: | `:artificial_satellite:` | :rocket: | `:rocket:` | [top](#introduction) |
+| [top](#travel--places) | :flying_saucer: | `:flying_saucer:` | | | [top](#introduction) |
+
+### Hotel
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#travel--places) | :bellhop_bell: | `:bellhop_bell:` | :luggage: | `:luggage:` | [top](#introduction) |
+
+### Time
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#travel--places) | :hourglass: | `:hourglass:` | :hourglass_flowing_sand: | `:hourglass_flowing_sand:` | [top](#introduction) |
+| [top](#travel--places) | :watch: | `:watch:` | :alarm_clock: | `:alarm_clock:` | [top](#introduction) |
+| [top](#travel--places) | :stopwatch: | `:stopwatch:` | :timer_clock: | `:timer_clock:` | [top](#introduction) |
+| [top](#travel--places) | :mantelpiece_clock: | `:mantelpiece_clock:` | :clock12: | `:clock12:` | [top](#introduction) |
+| [top](#travel--places) | :clock1230: | `:clock1230:` | :clock1: | `:clock1:` | [top](#introduction) |
+| [top](#travel--places) | :clock130: | `:clock130:` | :clock2: | `:clock2:` | [top](#introduction) |
+| [top](#travel--places) | :clock230: | `:clock230:` | :clock3: | `:clock3:` | [top](#introduction) |
+| [top](#travel--places) | :clock330: | `:clock330:` | :clock4: | `:clock4:` | [top](#introduction) |
+| [top](#travel--places) | :clock430: | `:clock430:` | :clock5: | `:clock5:` | [top](#introduction) |
+| [top](#travel--places) | :clock530: | `:clock530:` | :clock6: | `:clock6:` | [top](#introduction) |
+| [top](#travel--places) | :clock630: | `:clock630:` | :clock7: | `:clock7:` | [top](#introduction) |
+| [top](#travel--places) | :clock730: | `:clock730:` | :clock8: | `:clock8:` | [top](#introduction) |
+| [top](#travel--places) | :clock830: | `:clock830:` | :clock9: | `:clock9:` | [top](#introduction) |
+| [top](#travel--places) | :clock930: | `:clock930:` | :clock10: | `:clock10:` | [top](#introduction) |
+| [top](#travel--places) | :clock1030: | `:clock1030:` | :clock11: | `:clock11:` | [top](#introduction) |
+| [top](#travel--places) | :clock1130: | `:clock1130:` | | | [top](#introduction) |
+
+### Sky & Weather
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#travel--places) | :new_moon: | `:new_moon:` | :waxing_crescent_moon: | `:waxing_crescent_moon:` | [top](#introduction) |
+| [top](#travel--places) | :first_quarter_moon: | `:first_quarter_moon:` | :moon: | `:moon:` `:waxing_gibbous_moon:` | [top](#introduction) |
+| [top](#travel--places) | :full_moon: | `:full_moon:` | :waning_gibbous_moon: | `:waning_gibbous_moon:` | [top](#introduction) |
+| [top](#travel--places) | :last_quarter_moon: | `:last_quarter_moon:` | :waning_crescent_moon: | `:waning_crescent_moon:` | [top](#introduction) |
+| [top](#travel--places) | :crescent_moon: | `:crescent_moon:` | :new_moon_with_face: | `:new_moon_with_face:` | [top](#introduction) |
+| [top](#travel--places) | :first_quarter_moon_with_face: | `:first_quarter_moon_with_face:` | :last_quarter_moon_with_face: | `:last_quarter_moon_with_face:` | [top](#introduction) |
+| [top](#travel--places) | :thermometer: | `:thermometer:` | :sunny: | `:sunny:` | [top](#introduction) |
+| [top](#travel--places) | :full_moon_with_face: | `:full_moon_with_face:` | :sun_with_face: | `:sun_with_face:` | [top](#introduction) |
+| [top](#travel--places) | :ringed_planet: | `:ringed_planet:` | :star: | `:star:` | [top](#introduction) |
+| [top](#travel--places) | :star2: | `:star2:` | :stars: | `:stars:` | [top](#introduction) |
+| [top](#travel--places) | :milky_way: | `:milky_way:` | :cloud: | `:cloud:` | [top](#introduction) |
+| [top](#travel--places) | :partly_sunny: | `:partly_sunny:` | :cloud_with_lightning_and_rain: | `:cloud_with_lightning_and_rain:` | [top](#introduction) |
+| [top](#travel--places) | :sun_behind_small_cloud: | `:sun_behind_small_cloud:` | :sun_behind_large_cloud: | `:sun_behind_large_cloud:` | [top](#introduction) |
+| [top](#travel--places) | :sun_behind_rain_cloud: | `:sun_behind_rain_cloud:` | :cloud_with_rain: | `:cloud_with_rain:` | [top](#introduction) |
+| [top](#travel--places) | :cloud_with_snow: | `:cloud_with_snow:` | :cloud_with_lightning: | `:cloud_with_lightning:` | [top](#introduction) |
+| [top](#travel--places) | :tornado: | `:tornado:` | :fog: | `:fog:` | [top](#introduction) |
+| [top](#travel--places) | :wind_face: | `:wind_face:` | :cyclone: | `:cyclone:` | [top](#introduction) |
+| [top](#travel--places) | :rainbow: | `:rainbow:` | :closed_umbrella: | `:closed_umbrella:` | [top](#introduction) |
+| [top](#travel--places) | :open_umbrella: | `:open_umbrella:` | :umbrella: | `:umbrella:` | [top](#introduction) |
+| [top](#travel--places) | :parasol_on_ground: | `:parasol_on_ground:` | :zap: | `:zap:` | [top](#introduction) |
+| [top](#travel--places) | :snowflake: | `:snowflake:` | :snowman_with_snow: | `:snowman_with_snow:` | [top](#introduction) |
+| [top](#travel--places) | :snowman: | `:snowman:` | :comet: | `:comet:` | [top](#introduction) |
+| [top](#travel--places) | :fire: | `:fire:` | :droplet: | `:droplet:` | [top](#introduction) |
+| [top](#travel--places) | :ocean: | `:ocean:` | | | [top](#introduction) |
+
+## Activities
+
+- [Event](#event)
+- [Award Medal](#award-medal)
+- [Sport](#sport)
+- [Game](#game)
+- [Arts & Crafts](#arts--crafts)
+
+### Event
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#activities) | :jack_o_lantern: | `:jack_o_lantern:` | :christmas_tree: | `:christmas_tree:` | [top](#introduction) |
+| [top](#activities) | :fireworks: | `:fireworks:` | :sparkler: | `:sparkler:` | [top](#introduction) |
+| [top](#activities) | :firecracker: | `:firecracker:` | :sparkles: | `:sparkles:` | [top](#introduction) |
+| [top](#activities) | :balloon: | `:balloon:` | :tada: | `:tada:` | [top](#introduction) |
+| [top](#activities) | :confetti_ball: | `:confetti_ball:` | :tanabata_tree: | `:tanabata_tree:` | [top](#introduction) |
+| [top](#activities) | :bamboo: | `:bamboo:` | :dolls: | `:dolls:` | [top](#introduction) |
+| [top](#activities) | :flags: | `:flags:` | :wind_chime: | `:wind_chime:` | [top](#introduction) |
+| [top](#activities) | :rice_scene: | `:rice_scene:` | :red_envelope: | `:red_envelope:` | [top](#introduction) |
+| [top](#activities) | :ribbon: | `:ribbon:` | :gift: | `:gift:` | [top](#introduction) |
+| [top](#activities) | :reminder_ribbon: | `:reminder_ribbon:` | :tickets: | `:tickets:` | [top](#introduction) |
+| [top](#activities) | :ticket: | `:ticket:` | | | [top](#introduction) |
+
+### Award Medal
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#activities) | :medal_military: | `:medal_military:` | :trophy: | `:trophy:` | [top](#introduction) |
+| [top](#activities) | :medal_sports: | `:medal_sports:` | :1st_place_medal: | `:1st_place_medal:` | [top](#introduction) |
+| [top](#activities) | :2nd_place_medal: | `:2nd_place_medal:` | :3rd_place_medal: | `:3rd_place_medal:` | [top](#introduction) |
+
+### Sport
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#activities) | :soccer: | `:soccer:` | :baseball: | `:baseball:` | [top](#introduction) |
+| [top](#activities) | :softball: | `:softball:` | :basketball: | `:basketball:` | [top](#introduction) |
+| [top](#activities) | :volleyball: | `:volleyball:` | :football: | `:football:` | [top](#introduction) |
+| [top](#activities) | :rugby_football: | `:rugby_football:` | :tennis: | `:tennis:` | [top](#introduction) |
+| [top](#activities) | :flying_disc: | `:flying_disc:` | :bowling: | `:bowling:` | [top](#introduction) |
+| [top](#activities) | :cricket_game: | `:cricket_game:` | :field_hockey: | `:field_hockey:` | [top](#introduction) |
+| [top](#activities) | :ice_hockey: | `:ice_hockey:` | :lacrosse: | `:lacrosse:` | [top](#introduction) |
+| [top](#activities) | :ping_pong: | `:ping_pong:` | :badminton: | `:badminton:` | [top](#introduction) |
+| [top](#activities) | :boxing_glove: | `:boxing_glove:` | :martial_arts_uniform: | `:martial_arts_uniform:` | [top](#introduction) |
+| [top](#activities) | :goal_net: | `:goal_net:` | :golf: | `:golf:` | [top](#introduction) |
+| [top](#activities) | :ice_skate: | `:ice_skate:` | :fishing_pole_and_fish: | `:fishing_pole_and_fish:` | [top](#introduction) |
+| [top](#activities) | :diving_mask: | `:diving_mask:` | :running_shirt_with_sash: | `:running_shirt_with_sash:` | [top](#introduction) |
+| [top](#activities) | :ski: | `:ski:` | :sled: | `:sled:` | [top](#introduction) |
+| [top](#activities) | :curling_stone: | `:curling_stone:` | | | [top](#introduction) |
+
+### Game
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#activities) | :dart: | `:dart:` | :yo_yo: | `:yo_yo:` | [top](#introduction) |
+| [top](#activities) | :kite: | `:kite:` | :gun: | `:gun:` | [top](#introduction) |
+| [top](#activities) | :8ball: | `:8ball:` | :crystal_ball: | `:crystal_ball:` | [top](#introduction) |
+| [top](#activities) | :magic_wand: | `:magic_wand:` | :video_game: | `:video_game:` | [top](#introduction) |
+| [top](#activities) | :joystick: | `:joystick:` | :slot_machine: | `:slot_machine:` | [top](#introduction) |
+| [top](#activities) | :game_die: | `:game_die:` | :jigsaw: | `:jigsaw:` | [top](#introduction) |
+| [top](#activities) | :teddy_bear: | `:teddy_bear:` | :pinata: | `:pinata:` | [top](#introduction) |
+| [top](#activities) | :nesting_dolls: | `:nesting_dolls:` | :spades: | `:spades:` | [top](#introduction) |
+| [top](#activities) | :hearts: | `:hearts:` | :diamonds: | `:diamonds:` | [top](#introduction) |
+| [top](#activities) | :clubs: | `:clubs:` | :chess_pawn: | `:chess_pawn:` | [top](#introduction) |
+| [top](#activities) | :black_joker: | `:black_joker:` | :mahjong: | `:mahjong:` | [top](#introduction) |
+| [top](#activities) | :flower_playing_cards: | `:flower_playing_cards:` | | | [top](#introduction) |
+
+### Arts & Crafts
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#activities) | :performing_arts: | `:performing_arts:` | :framed_picture: | `:framed_picture:` | [top](#introduction) |
+| [top](#activities) | :art: | `:art:` | :thread: | `:thread:` | [top](#introduction) |
+| [top](#activities) | :sewing_needle: | `:sewing_needle:` | :yarn: | `:yarn:` | [top](#introduction) |
+| [top](#activities) | :knot: | `:knot:` | | | [top](#introduction) |
+
+## Objects
+
+- [Clothing](#clothing)
+- [Sound](#sound)
+- [Music](#music)
+- [Musical Instrument](#musical-instrument)
+- [Phone](#phone)
+- [Computer](#computer)
+- [Light & Video](#light--video)
+- [Book Paper](#book-paper)
+- [Money](#money)
+- [Mail](#mail)
+- [Writing](#writing)
+- [Office](#office)
+- [Lock](#lock)
+- [Tool](#tool)
+- [Science](#science)
+- [Medical](#medical)
+- [Household](#household)
+- [Other Object](#other-object)
+
+### Clothing
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :eyeglasses: | `:eyeglasses:` | :dark_sunglasses: | `:dark_sunglasses:` | [top](#introduction) |
+| [top](#objects) | :goggles: | `:goggles:` | :lab_coat: | `:lab_coat:` | [top](#introduction) |
+| [top](#objects) | :safety_vest: | `:safety_vest:` | :necktie: | `:necktie:` | [top](#introduction) |
+| [top](#objects) | :shirt: | `:shirt:` `:tshirt:` | :jeans: | `:jeans:` | [top](#introduction) |
+| [top](#objects) | :scarf: | `:scarf:` | :gloves: | `:gloves:` | [top](#introduction) |
+| [top](#objects) | :coat: | `:coat:` | :socks: | `:socks:` | [top](#introduction) |
+| [top](#objects) | :dress: | `:dress:` | :kimono: | `:kimono:` | [top](#introduction) |
+| [top](#objects) | :sari: | `:sari:` | :one_piece_swimsuit: | `:one_piece_swimsuit:` | [top](#introduction) |
+| [top](#objects) | :swim_brief: | `:swim_brief:` | :shorts: | `:shorts:` | [top](#introduction) |
+| [top](#objects) | :bikini: | `:bikini:` | :womans_clothes: | `:womans_clothes:` | [top](#introduction) |
+| [top](#objects) | :purse: | `:purse:` | :handbag: | `:handbag:` | [top](#introduction) |
+| [top](#objects) | :pouch: | `:pouch:` | :shopping: | `:shopping:` | [top](#introduction) |
+| [top](#objects) | :school_satchel: | `:school_satchel:` | :thong_sandal: | `:thong_sandal:` | [top](#introduction) |
+| [top](#objects) | :mans_shoe: | `:mans_shoe:` `:shoe:` | :athletic_shoe: | `:athletic_shoe:` | [top](#introduction) |
+| [top](#objects) | :hiking_boot: | `:hiking_boot:` | :flat_shoe: | `:flat_shoe:` | [top](#introduction) |
+| [top](#objects) | :high_heel: | `:high_heel:` | :sandal: | `:sandal:` | [top](#introduction) |
+| [top](#objects) | :ballet_shoes: | `:ballet_shoes:` | :boot: | `:boot:` | [top](#introduction) |
+| [top](#objects) | :crown: | `:crown:` | :womans_hat: | `:womans_hat:` | [top](#introduction) |
+| [top](#objects) | :tophat: | `:tophat:` | :mortar_board: | `:mortar_board:` | [top](#introduction) |
+| [top](#objects) | :billed_cap: | `:billed_cap:` | :military_helmet: | `:military_helmet:` | [top](#introduction) |
+| [top](#objects) | :rescue_worker_helmet: | `:rescue_worker_helmet:` | :prayer_beads: | `:prayer_beads:` | [top](#introduction) |
+| [top](#objects) | :lipstick: | `:lipstick:` | :ring: | `:ring:` | [top](#introduction) |
+| [top](#objects) | :gem: | `:gem:` | | | [top](#introduction) |
+
+### Sound
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :mute: | `:mute:` | :speaker: | `:speaker:` | [top](#introduction) |
+| [top](#objects) | :sound: | `:sound:` | :loud_sound: | `:loud_sound:` | [top](#introduction) |
+| [top](#objects) | :loudspeaker: | `:loudspeaker:` | :mega: | `:mega:` | [top](#introduction) |
+| [top](#objects) | :postal_horn: | `:postal_horn:` | :bell: | `:bell:` | [top](#introduction) |
+| [top](#objects) | :no_bell: | `:no_bell:` | | | [top](#introduction) |
+
+### Music
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :musical_score: | `:musical_score:` | :musical_note: | `:musical_note:` | [top](#introduction) |
+| [top](#objects) | :notes: | `:notes:` | :studio_microphone: | `:studio_microphone:` | [top](#introduction) |
+| [top](#objects) | :level_slider: | `:level_slider:` | :control_knobs: | `:control_knobs:` | [top](#introduction) |
+| [top](#objects) | :microphone: | `:microphone:` | :headphones: | `:headphones:` | [top](#introduction) |
+| [top](#objects) | :radio: | `:radio:` | | | [top](#introduction) |
+
+### Musical Instrument
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :saxophone: | `:saxophone:` | :accordion: | `:accordion:` | [top](#introduction) |
+| [top](#objects) | :guitar: | `:guitar:` | :musical_keyboard: | `:musical_keyboard:` | [top](#introduction) |
+| [top](#objects) | :trumpet: | `:trumpet:` | :violin: | `:violin:` | [top](#introduction) |
+| [top](#objects) | :banjo: | `:banjo:` | :drum: | `:drum:` | [top](#introduction) |
+| [top](#objects) | :long_drum: | `:long_drum:` | | | [top](#introduction) |
+
+### Phone
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :iphone: | `:iphone:` | :calling: | `:calling:` | [top](#introduction) |
+| [top](#objects) | :phone: | `:phone:` `:telephone:` | :telephone_receiver: | `:telephone_receiver:` | [top](#introduction) |
+| [top](#objects) | :pager: | `:pager:` | :fax: | `:fax:` | [top](#introduction) |
+
+### Computer
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :battery: | `:battery:` | :electric_plug: | `:electric_plug:` | [top](#introduction) |
+| [top](#objects) | :computer: | `:computer:` | :desktop_computer: | `:desktop_computer:` | [top](#introduction) |
+| [top](#objects) | :printer: | `:printer:` | :keyboard: | `:keyboard:` | [top](#introduction) |
+| [top](#objects) | :computer_mouse: | `:computer_mouse:` | :trackball: | `:trackball:` | [top](#introduction) |
+| [top](#objects) | :minidisc: | `:minidisc:` | :floppy_disk: | `:floppy_disk:` | [top](#introduction) |
+| [top](#objects) | :cd: | `:cd:` | :dvd: | `:dvd:` | [top](#introduction) |
+| [top](#objects) | :abacus: | `:abacus:` | | | [top](#introduction) |
+
+### Light & Video
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :movie_camera: | `:movie_camera:` | :film_strip: | `:film_strip:` | [top](#introduction) |
+| [top](#objects) | :film_projector: | `:film_projector:` | :clapper: | `:clapper:` | [top](#introduction) |
+| [top](#objects) | :tv: | `:tv:` | :camera: | `:camera:` | [top](#introduction) |
+| [top](#objects) | :camera_flash: | `:camera_flash:` | :video_camera: | `:video_camera:` | [top](#introduction) |
+| [top](#objects) | :vhs: | `:vhs:` | :mag: | `:mag:` | [top](#introduction) |
+| [top](#objects) | :mag_right: | `:mag_right:` | :candle: | `:candle:` | [top](#introduction) |
+| [top](#objects) | :bulb: | `:bulb:` | :flashlight: | `:flashlight:` | [top](#introduction) |
+| [top](#objects) | :izakaya_lantern: | `:izakaya_lantern:` `:lantern:` | :diya_lamp: | `:diya_lamp:` | [top](#introduction) |
+
+### Book Paper
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :notebook_with_decorative_cover: | `:notebook_with_decorative_cover:` | :closed_book: | `:closed_book:` | [top](#introduction) |
+| [top](#objects) | :book: | `:book:` `:open_book:` | :green_book: | `:green_book:` | [top](#introduction) |
+| [top](#objects) | :blue_book: | `:blue_book:` | :orange_book: | `:orange_book:` | [top](#introduction) |
+| [top](#objects) | :books: | `:books:` | :notebook: | `:notebook:` | [top](#introduction) |
+| [top](#objects) | :ledger: | `:ledger:` | :page_with_curl: | `:page_with_curl:` | [top](#introduction) |
+| [top](#objects) | :scroll: | `:scroll:` | :page_facing_up: | `:page_facing_up:` | [top](#introduction) |
+| [top](#objects) | :newspaper: | `:newspaper:` | :newspaper_roll: | `:newspaper_roll:` | [top](#introduction) |
+| [top](#objects) | :bookmark_tabs: | `:bookmark_tabs:` | :bookmark: | `:bookmark:` | [top](#introduction) |
+| [top](#objects) | :label: | `:label:` | | | [top](#introduction) |
+
+### Money
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :moneybag: | `:moneybag:` | :coin: | `:coin:` | [top](#introduction) |
+| [top](#objects) | :yen: | `:yen:` | :dollar: | `:dollar:` | [top](#introduction) |
+| [top](#objects) | :euro: | `:euro:` | :pound: | `:pound:` | [top](#introduction) |
+| [top](#objects) | :money_with_wings: | `:money_with_wings:` | :credit_card: | `:credit_card:` | [top](#introduction) |
+| [top](#objects) | :receipt: | `:receipt:` | :chart: | `:chart:` | [top](#introduction) |
+
+### Mail
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :envelope: | `:envelope:` | :e-mail: | `:e-mail:` `:email:` | [top](#introduction) |
+| [top](#objects) | :incoming_envelope: | `:incoming_envelope:` | :envelope_with_arrow: | `:envelope_with_arrow:` | [top](#introduction) |
+| [top](#objects) | :outbox_tray: | `:outbox_tray:` | :inbox_tray: | `:inbox_tray:` | [top](#introduction) |
+| [top](#objects) | :package: | `:package:` | :mailbox: | `:mailbox:` | [top](#introduction) |
+| [top](#objects) | :mailbox_closed: | `:mailbox_closed:` | :mailbox_with_mail: | `:mailbox_with_mail:` | [top](#introduction) |
+| [top](#objects) | :mailbox_with_no_mail: | `:mailbox_with_no_mail:` | :postbox: | `:postbox:` | [top](#introduction) |
+| [top](#objects) | :ballot_box: | `:ballot_box:` | | | [top](#introduction) |
+
+### Writing
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :pencil2: | `:pencil2:` | :black_nib: | `:black_nib:` | [top](#introduction) |
+| [top](#objects) | :fountain_pen: | `:fountain_pen:` | :pen: | `:pen:` | [top](#introduction) |
+| [top](#objects) | :paintbrush: | `:paintbrush:` | :crayon: | `:crayon:` | [top](#introduction) |
+| [top](#objects) | :memo: | `:memo:` `:pencil:` | | | [top](#introduction) |
+
+### Office
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :briefcase: | `:briefcase:` | :file_folder: | `:file_folder:` | [top](#introduction) |
+| [top](#objects) | :open_file_folder: | `:open_file_folder:` | :card_index_dividers: | `:card_index_dividers:` | [top](#introduction) |
+| [top](#objects) | :date: | `:date:` | :calendar: | `:calendar:` | [top](#introduction) |
+| [top](#objects) | :spiral_notepad: | `:spiral_notepad:` | :spiral_calendar: | `:spiral_calendar:` | [top](#introduction) |
+| [top](#objects) | :card_index: | `:card_index:` | :chart_with_upwards_trend: | `:chart_with_upwards_trend:` | [top](#introduction) |
+| [top](#objects) | :chart_with_downwards_trend: | `:chart_with_downwards_trend:` | :bar_chart: | `:bar_chart:` | [top](#introduction) |
+| [top](#objects) | :clipboard: | `:clipboard:` | :pushpin: | `:pushpin:` | [top](#introduction) |
+| [top](#objects) | :round_pushpin: | `:round_pushpin:` | :paperclip: | `:paperclip:` | [top](#introduction) |
+| [top](#objects) | :paperclips: | `:paperclips:` | :straight_ruler: | `:straight_ruler:` | [top](#introduction) |
+| [top](#objects) | :triangular_ruler: | `:triangular_ruler:` | :scissors: | `:scissors:` | [top](#introduction) |
+| [top](#objects) | :card_file_box: | `:card_file_box:` | :file_cabinet: | `:file_cabinet:` | [top](#introduction) |
+| [top](#objects) | :wastebasket: | `:wastebasket:` | | | [top](#introduction) |
+
+### Lock
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :lock: | `:lock:` | :unlock: | `:unlock:` | [top](#introduction) |
+| [top](#objects) | :lock_with_ink_pen: | `:lock_with_ink_pen:` | :closed_lock_with_key: | `:closed_lock_with_key:` | [top](#introduction) |
+| [top](#objects) | :key: | `:key:` | :old_key: | `:old_key:` | [top](#introduction) |
+
+### Tool
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :hammer: | `:hammer:` | :axe: | `:axe:` | [top](#introduction) |
+| [top](#objects) | :pick: | `:pick:` | :hammer_and_pick: | `:hammer_and_pick:` | [top](#introduction) |
+| [top](#objects) | :hammer_and_wrench: | `:hammer_and_wrench:` | :dagger: | `:dagger:` | [top](#introduction) |
+| [top](#objects) | :crossed_swords: | `:crossed_swords:` | :bomb: | `:bomb:` | [top](#introduction) |
+| [top](#objects) | :boomerang: | `:boomerang:` | :bow_and_arrow: | `:bow_and_arrow:` | [top](#introduction) |
+| [top](#objects) | :shield: | `:shield:` | :carpentry_saw: | `:carpentry_saw:` | [top](#introduction) |
+| [top](#objects) | :wrench: | `:wrench:` | :screwdriver: | `:screwdriver:` | [top](#introduction) |
+| [top](#objects) | :nut_and_bolt: | `:nut_and_bolt:` | :gear: | `:gear:` | [top](#introduction) |
+| [top](#objects) | :clamp: | `:clamp:` | :balance_scale: | `:balance_scale:` | [top](#introduction) |
+| [top](#objects) | :probing_cane: | `:probing_cane:` | :link: | `:link:` | [top](#introduction) |
+| [top](#objects) | :chains: | `:chains:` | :hook: | `:hook:` | [top](#introduction) |
+| [top](#objects) | :toolbox: | `:toolbox:` | :magnet: | `:magnet:` | [top](#introduction) |
+| [top](#objects) | :ladder: | `:ladder:` | | | [top](#introduction) |
+
+### Science
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :alembic: | `:alembic:` | :test_tube: | `:test_tube:` | [top](#introduction) |
+| [top](#objects) | :petri_dish: | `:petri_dish:` | :dna: | `:dna:` | [top](#introduction) |
+| [top](#objects) | :microscope: | `:microscope:` | :telescope: | `:telescope:` | [top](#introduction) |
+| [top](#objects) | :satellite: | `:satellite:` | | | [top](#introduction) |
+
+### Medical
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :syringe: | `:syringe:` | :drop_of_blood: | `:drop_of_blood:` | [top](#introduction) |
+| [top](#objects) | :pill: | `:pill:` | :adhesive_bandage: | `:adhesive_bandage:` | [top](#introduction) |
+| [top](#objects) | :stethoscope: | `:stethoscope:` | | | [top](#introduction) |
+
+### Household
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :door: | `:door:` | :elevator: | `:elevator:` | [top](#introduction) |
+| [top](#objects) | :mirror: | `:mirror:` | :window: | `:window:` | [top](#introduction) |
+| [top](#objects) | :bed: | `:bed:` | :couch_and_lamp: | `:couch_and_lamp:` | [top](#introduction) |
+| [top](#objects) | :chair: | `:chair:` | :toilet: | `:toilet:` | [top](#introduction) |
+| [top](#objects) | :plunger: | `:plunger:` | :shower: | `:shower:` | [top](#introduction) |
+| [top](#objects) | :bathtub: | `:bathtub:` | :mouse_trap: | `:mouse_trap:` | [top](#introduction) |
+| [top](#objects) | :razor: | `:razor:` | :lotion_bottle: | `:lotion_bottle:` | [top](#introduction) |
+| [top](#objects) | :safety_pin: | `:safety_pin:` | :broom: | `:broom:` | [top](#introduction) |
+| [top](#objects) | :basket: | `:basket:` | :roll_of_paper: | `:roll_of_paper:` | [top](#introduction) |
+| [top](#objects) | :bucket: | `:bucket:` | :soap: | `:soap:` | [top](#introduction) |
+| [top](#objects) | :toothbrush: | `:toothbrush:` | :sponge: | `:sponge:` | [top](#introduction) |
+| [top](#objects) | :fire_extinguisher: | `:fire_extinguisher:` | :shopping_cart: | `:shopping_cart:` | [top](#introduction) |
+
+### Other Object
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :smoking: | `:smoking:` | :coffin: | `:coffin:` | [top](#introduction) |
+| [top](#objects) | :headstone: | `:headstone:` | :funeral_urn: | `:funeral_urn:` | [top](#introduction) |
+| [top](#objects) | :nazar_amulet: | `:nazar_amulet:` | :moyai: | `:moyai:` | [top](#introduction) |
+| [top](#objects) | :placard: | `:placard:` | | | [top](#introduction) |
+
+## Symbols
+
+- [Transport Sign](#transport-sign)
+- [Warning](#warning)
+- [Arrow](#arrow)
+- [Religion](#religion)
+- [Zodiac](#zodiac)
+- [Av Symbol](#av-symbol)
+- [Gender](#gender)
+- [Math](#math)
+- [Punctuation](#punctuation)
+- [Currency](#currency)
+- [Other Symbol](#other-symbol)
+- [Keycap](#keycap)
+- [Alphanum](#alphanum)
+- [Geometric](#geometric)
+
+### Transport Sign
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :atm: | `:atm:` | :put_litter_in_its_place: | `:put_litter_in_its_place:` | [top](#introduction) |
+| [top](#symbols) | :potable_water: | `:potable_water:` | :wheelchair: | `:wheelchair:` | [top](#introduction) |
+| [top](#symbols) | :mens: | `:mens:` | :womens: | `:womens:` | [top](#introduction) |
+| [top](#symbols) | :restroom: | `:restroom:` | :baby_symbol: | `:baby_symbol:` | [top](#introduction) |
+| [top](#symbols) | :wc: | `:wc:` | :passport_control: | `:passport_control:` | [top](#introduction) |
+| [top](#symbols) | :customs: | `:customs:` | :baggage_claim: | `:baggage_claim:` | [top](#introduction) |
+| [top](#symbols) | :left_luggage: | `:left_luggage:` | | | [top](#introduction) |
+
+### Warning
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :warning: | `:warning:` | :children_crossing: | `:children_crossing:` | [top](#introduction) |
+| [top](#symbols) | :no_entry: | `:no_entry:` | :no_entry_sign: | `:no_entry_sign:` | [top](#introduction) |
+| [top](#symbols) | :no_bicycles: | `:no_bicycles:` | :no_smoking: | `:no_smoking:` | [top](#introduction) |
+| [top](#symbols) | :do_not_litter: | `:do_not_litter:` | :non-potable_water: | `:non-potable_water:` | [top](#introduction) |
+| [top](#symbols) | :no_pedestrians: | `:no_pedestrians:` | :no_mobile_phones: | `:no_mobile_phones:` | [top](#introduction) |
+| [top](#symbols) | :underage: | `:underage:` | :radioactive: | `:radioactive:` | [top](#introduction) |
+| [top](#symbols) | :biohazard: | `:biohazard:` | | | [top](#introduction) |
+
+### Arrow
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :arrow_up: | `:arrow_up:` | :arrow_upper_right: | `:arrow_upper_right:` | [top](#introduction) |
+| [top](#symbols) | :arrow_right: | `:arrow_right:` | :arrow_lower_right: | `:arrow_lower_right:` | [top](#introduction) |
+| [top](#symbols) | :arrow_down: | `:arrow_down:` | :arrow_lower_left: | `:arrow_lower_left:` | [top](#introduction) |
+| [top](#symbols) | :arrow_left: | `:arrow_left:` | :arrow_upper_left: | `:arrow_upper_left:` | [top](#introduction) |
+| [top](#symbols) | :arrow_up_down: | `:arrow_up_down:` | :left_right_arrow: | `:left_right_arrow:` | [top](#introduction) |
+| [top](#symbols) | :leftwards_arrow_with_hook: | `:leftwards_arrow_with_hook:` | :arrow_right_hook: | `:arrow_right_hook:` | [top](#introduction) |
+| [top](#symbols) | :arrow_heading_up: | `:arrow_heading_up:` | :arrow_heading_down: | `:arrow_heading_down:` | [top](#introduction) |
+| [top](#symbols) | :arrows_clockwise: | `:arrows_clockwise:` | :arrows_counterclockwise: | `:arrows_counterclockwise:` | [top](#introduction) |
+| [top](#symbols) | :back: | `:back:` | :end: | `:end:` | [top](#introduction) |
+| [top](#symbols) | :on: | `:on:` | :soon: | `:soon:` | [top](#introduction) |
+| [top](#symbols) | :top: | `:top:` | | | [top](#introduction) |
+
+### Religion
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :place_of_worship: | `:place_of_worship:` | :atom_symbol: | `:atom_symbol:` | [top](#introduction) |
+| [top](#symbols) | :om: | `:om:` | :star_of_david: | `:star_of_david:` | [top](#introduction) |
+| [top](#symbols) | :wheel_of_dharma: | `:wheel_of_dharma:` | :yin_yang: | `:yin_yang:` | [top](#introduction) |
+| [top](#symbols) | :latin_cross: | `:latin_cross:` | :orthodox_cross: | `:orthodox_cross:` | [top](#introduction) |
+| [top](#symbols) | :star_and_crescent: | `:star_and_crescent:` | :peace_symbol: | `:peace_symbol:` | [top](#introduction) |
+| [top](#symbols) | :menorah: | `:menorah:` | :six_pointed_star: | `:six_pointed_star:` | [top](#introduction) |
+
+### Zodiac
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :aries: | `:aries:` | :taurus: | `:taurus:` | [top](#introduction) |
+| [top](#symbols) | :gemini: | `:gemini:` | :cancer: | `:cancer:` | [top](#introduction) |
+| [top](#symbols) | :leo: | `:leo:` | :virgo: | `:virgo:` | [top](#introduction) |
+| [top](#symbols) | :libra: | `:libra:` | :scorpius: | `:scorpius:` | [top](#introduction) |
+| [top](#symbols) | :sagittarius: | `:sagittarius:` | :capricorn: | `:capricorn:` | [top](#introduction) |
+| [top](#symbols) | :aquarius: | `:aquarius:` | :pisces: | `:pisces:` | [top](#introduction) |
+| [top](#symbols) | :ophiuchus: | `:ophiuchus:` | | | [top](#introduction) |
+
+### Av Symbol
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :twisted_rightwards_arrows: | `:twisted_rightwards_arrows:` | :repeat: | `:repeat:` | [top](#introduction) |
+| [top](#symbols) | :repeat_one: | `:repeat_one:` | :arrow_forward: | `:arrow_forward:` | [top](#introduction) |
+| [top](#symbols) | :fast_forward: | `:fast_forward:` | :next_track_button: | `:next_track_button:` | [top](#introduction) |
+| [top](#symbols) | :play_or_pause_button: | `:play_or_pause_button:` | :arrow_backward: | `:arrow_backward:` | [top](#introduction) |
+| [top](#symbols) | :rewind: | `:rewind:` | :previous_track_button: | `:previous_track_button:` | [top](#introduction) |
+| [top](#symbols) | :arrow_up_small: | `:arrow_up_small:` | :arrow_double_up: | `:arrow_double_up:` | [top](#introduction) |
+| [top](#symbols) | :arrow_down_small: | `:arrow_down_small:` | :arrow_double_down: | `:arrow_double_down:` | [top](#introduction) |
+| [top](#symbols) | :pause_button: | `:pause_button:` | :stop_button: | `:stop_button:` | [top](#introduction) |
+| [top](#symbols) | :record_button: | `:record_button:` | :eject_button: | `:eject_button:` | [top](#introduction) |
+| [top](#symbols) | :cinema: | `:cinema:` | :low_brightness: | `:low_brightness:` | [top](#introduction) |
+| [top](#symbols) | :high_brightness: | `:high_brightness:` | :signal_strength: | `:signal_strength:` | [top](#introduction) |
+| [top](#symbols) | :vibration_mode: | `:vibration_mode:` | :mobile_phone_off: | `:mobile_phone_off:` | [top](#introduction) |
+
+### Gender
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :female_sign: | `:female_sign:` | :male_sign: | `:male_sign:` | [top](#introduction) |
+| [top](#symbols) | :transgender_symbol: | `:transgender_symbol:` | | | [top](#introduction) |
+
+### Math
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :heavy_multiplication_x: | `:heavy_multiplication_x:` | :heavy_plus_sign: | `:heavy_plus_sign:` | [top](#introduction) |
+| [top](#symbols) | :heavy_minus_sign: | `:heavy_minus_sign:` | :heavy_division_sign: | `:heavy_division_sign:` | [top](#introduction) |
+| [top](#symbols) | :infinity: | `:infinity:` | | | [top](#introduction) |
+
+### Punctuation
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :bangbang: | `:bangbang:` | :interrobang: | `:interrobang:` | [top](#introduction) |
+| [top](#symbols) | :question: | `:question:` | :grey_question: | `:grey_question:` | [top](#introduction) |
+| [top](#symbols) | :grey_exclamation: | `:grey_exclamation:` | :exclamation: | `:exclamation:` `:heavy_exclamation_mark:` | [top](#introduction) |
+| [top](#symbols) | :wavy_dash: | `:wavy_dash:` | | | [top](#introduction) |
+
+### Currency
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :currency_exchange: | `:currency_exchange:` | :heavy_dollar_sign: | `:heavy_dollar_sign:` | [top](#introduction) |
+
+### Other Symbol
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :medical_symbol: | `:medical_symbol:` | :recycle: | `:recycle:` | [top](#introduction) |
+| [top](#symbols) | :fleur_de_lis: | `:fleur_de_lis:` | :trident: | `:trident:` | [top](#introduction) |
+| [top](#symbols) | :name_badge: | `:name_badge:` | :beginner: | `:beginner:` | [top](#introduction) |
+| [top](#symbols) | :o: | `:o:` | :white_check_mark: | `:white_check_mark:` | [top](#introduction) |
+| [top](#symbols) | :ballot_box_with_check: | `:ballot_box_with_check:` | :heavy_check_mark: | `:heavy_check_mark:` | [top](#introduction) |
+| [top](#symbols) | :x: | `:x:` | :negative_squared_cross_mark: | `:negative_squared_cross_mark:` | [top](#introduction) |
+| [top](#symbols) | :curly_loop: | `:curly_loop:` | :loop: | `:loop:` | [top](#introduction) |
+| [top](#symbols) | :part_alternation_mark: | `:part_alternation_mark:` | :eight_spoked_asterisk: | `:eight_spoked_asterisk:` | [top](#introduction) |
+| [top](#symbols) | :eight_pointed_black_star: | `:eight_pointed_black_star:` | :sparkle: | `:sparkle:` | [top](#introduction) |
+| [top](#symbols) | :copyright: | `:copyright:` | :registered: | `:registered:` | [top](#introduction) |
+| [top](#symbols) | :tm: | `:tm:` | | | [top](#introduction) |
+
+### Keycap
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :hash: | `:hash:` | :asterisk: | `:asterisk:` | [top](#introduction) |
+| [top](#symbols) | :zero: | `:zero:` | :one: | `:one:` | [top](#introduction) |
+| [top](#symbols) | :two: | `:two:` | :three: | `:three:` | [top](#introduction) |
+| [top](#symbols) | :four: | `:four:` | :five: | `:five:` | [top](#introduction) |
+| [top](#symbols) | :six: | `:six:` | :seven: | `:seven:` | [top](#introduction) |
+| [top](#symbols) | :eight: | `:eight:` | :nine: | `:nine:` | [top](#introduction) |
+| [top](#symbols) | :keycap_ten: | `:keycap_ten:` | | | [top](#introduction) |
+
+### Alphanum
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :capital_abcd: | `:capital_abcd:` | :abcd: | `:abcd:` | [top](#introduction) |
+| [top](#symbols) | :1234: | `:1234:` | :symbols: | `:symbols:` | [top](#introduction) |
+| [top](#symbols) | :abc: | `:abc:` | :a: | `:a:` | [top](#introduction) |
+| [top](#symbols) | :ab: | `:ab:` | :b: | `:b:` | [top](#introduction) |
+| [top](#symbols) | :cl: | `:cl:` | :cool: | `:cool:` | [top](#introduction) |
+| [top](#symbols) | :free: | `:free:` | :information_source: | `:information_source:` | [top](#introduction) |
+| [top](#symbols) | :id: | `:id:` | :m: | `:m:` | [top](#introduction) |
+| [top](#symbols) | :new: | `:new:` | :ng: | `:ng:` | [top](#introduction) |
+| [top](#symbols) | :o2: | `:o2:` | :ok: | `:ok:` | [top](#introduction) |
+| [top](#symbols) | :parking: | `:parking:` | :sos: | `:sos:` | [top](#introduction) |
+| [top](#symbols) | :up: | `:up:` | :vs: | `:vs:` | [top](#introduction) |
+| [top](#symbols) | :koko: | `:koko:` | :sa: | `:sa:` | [top](#introduction) |
+| [top](#symbols) | :u6708: | `:u6708:` | :u6709: | `:u6709:` | [top](#introduction) |
+| [top](#symbols) | :u6307: | `:u6307:` | :ideograph_advantage: | `:ideograph_advantage:` | [top](#introduction) |
+| [top](#symbols) | :u5272: | `:u5272:` | :u7121: | `:u7121:` | [top](#introduction) |
+| [top](#symbols) | :u7981: | `:u7981:` | :accept: | `:accept:` | [top](#introduction) |
+| [top](#symbols) | :u7533: | `:u7533:` | :u5408: | `:u5408:` | [top](#introduction) |
+| [top](#symbols) | :u7a7a: | `:u7a7a:` | :congratulations: | `:congratulations:` | [top](#introduction) |
+| [top](#symbols) | :secret: | `:secret:` | :u55b6: | `:u55b6:` | [top](#introduction) |
+| [top](#symbols) | :u6e80: | `:u6e80:` | | | [top](#introduction) |
+
+### Geometric
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :red_circle: | `:red_circle:` | :orange_circle: | `:orange_circle:` | [top](#introduction) |
+| [top](#symbols) | :yellow_circle: | `:yellow_circle:` | :green_circle: | `:green_circle:` | [top](#introduction) |
+| [top](#symbols) | :large_blue_circle: | `:large_blue_circle:` | :purple_circle: | `:purple_circle:` | [top](#introduction) |
+| [top](#symbols) | :brown_circle: | `:brown_circle:` | :black_circle: | `:black_circle:` | [top](#introduction) |
+| [top](#symbols) | :white_circle: | `:white_circle:` | :red_square: | `:red_square:` | [top](#introduction) |
+| [top](#symbols) | :orange_square: | `:orange_square:` | :yellow_square: | `:yellow_square:` | [top](#introduction) |
+| [top](#symbols) | :green_square: | `:green_square:` | :blue_square: | `:blue_square:` | [top](#introduction) |
+| [top](#symbols) | :purple_square: | `:purple_square:` | :brown_square: | `:brown_square:` | [top](#introduction) |
+| [top](#symbols) | :black_large_square: | `:black_large_square:` | :white_large_square: | `:white_large_square:` | [top](#introduction) |
+| [top](#symbols) | :black_medium_square: | `:black_medium_square:` | :white_medium_square: | `:white_medium_square:` | [top](#introduction) |
+| [top](#symbols) | :black_medium_small_square: | `:black_medium_small_square:` | :white_medium_small_square: | `:white_medium_small_square:` | [top](#introduction) |
+| [top](#symbols) | :black_small_square: | `:black_small_square:` | :white_small_square: | `:white_small_square:` | [top](#introduction) |
+| [top](#symbols) | :large_orange_diamond: | `:large_orange_diamond:` | :large_blue_diamond: | `:large_blue_diamond:` | [top](#introduction) |
+| [top](#symbols) | :small_orange_diamond: | `:small_orange_diamond:` | :small_blue_diamond: | `:small_blue_diamond:` | [top](#introduction) |
+| [top](#symbols) | :small_red_triangle: | `:small_red_triangle:` | :small_red_triangle_down: | `:small_red_triangle_down:` | [top](#introduction) |
+| [top](#symbols) | :diamond_shape_with_a_dot_inside: | `:diamond_shape_with_a_dot_inside:` | :radio_button: | `:radio_button:` | [top](#introduction) |
+| [top](#symbols) | :white_square_button: | `:white_square_button:` | :black_square_button: | `:black_square_button:` | [top](#introduction) |
+
+## Flags
+
+- [Flag](#flag)
+- [Country Flag](#country-flag)
+- [Subdivision Flag](#subdivision-flag)
+
+### Flag
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#flags) | :checkered_flag: | `:checkered_flag:` | :triangular_flag_on_post: | `:triangular_flag_on_post:` | [top](#introduction) |
+| [top](#flags) | :crossed_flags: | `:crossed_flags:` | :black_flag: | `:black_flag:` | [top](#introduction) |
+| [top](#flags) | :white_flag: | `:white_flag:` | :rainbow_flag: | `:rainbow_flag:` | [top](#introduction) |
+| [top](#flags) | :transgender_flag: | `:transgender_flag:` | :pirate_flag: | `:pirate_flag:` | [top](#introduction) |
+
+### Country Flag
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#flags) | :ascension_island: | `:ascension_island:` | :andorra: | `:andorra:` | [top](#introduction) |
+| [top](#flags) | :united_arab_emirates: | `:united_arab_emirates:` | :afghanistan: | `:afghanistan:` | [top](#introduction) |
+| [top](#flags) | :antigua_barbuda: | `:antigua_barbuda:` | :anguilla: | `:anguilla:` | [top](#introduction) |
+| [top](#flags) | :albania: | `:albania:` | :armenia: | `:armenia:` | [top](#introduction) |
+| [top](#flags) | :angola: | `:angola:` | :antarctica: | `:antarctica:` | [top](#introduction) |
+| [top](#flags) | :argentina: | `:argentina:` | :american_samoa: | `:american_samoa:` | [top](#introduction) |
+| [top](#flags) | :austria: | `:austria:` | :australia: | `:australia:` | [top](#introduction) |
+| [top](#flags) | :aruba: | `:aruba:` | :aland_islands: | `:aland_islands:` | [top](#introduction) |
+| [top](#flags) | :azerbaijan: | `:azerbaijan:` | :bosnia_herzegovina: | `:bosnia_herzegovina:` | [top](#introduction) |
+| [top](#flags) | :barbados: | `:barbados:` | :bangladesh: | `:bangladesh:` | [top](#introduction) |
+| [top](#flags) | :belgium: | `:belgium:` | :burkina_faso: | `:burkina_faso:` | [top](#introduction) |
+| [top](#flags) | :bulgaria: | `:bulgaria:` | :bahrain: | `:bahrain:` | [top](#introduction) |
+| [top](#flags) | :burundi: | `:burundi:` | :benin: | `:benin:` | [top](#introduction) |
+| [top](#flags) | :st_barthelemy: | `:st_barthelemy:` | :bermuda: | `:bermuda:` | [top](#introduction) |
+| [top](#flags) | :brunei: | `:brunei:` | :bolivia: | `:bolivia:` | [top](#introduction) |
+| [top](#flags) | :caribbean_netherlands: | `:caribbean_netherlands:` | :brazil: | `:brazil:` | [top](#introduction) |
+| [top](#flags) | :bahamas: | `:bahamas:` | :bhutan: | `:bhutan:` | [top](#introduction) |
+| [top](#flags) | :bouvet_island: | `:bouvet_island:` | :botswana: | `:botswana:` | [top](#introduction) |
+| [top](#flags) | :belarus: | `:belarus:` | :belize: | `:belize:` | [top](#introduction) |
+| [top](#flags) | :canada: | `:canada:` | :cocos_islands: | `:cocos_islands:` | [top](#introduction) |
+| [top](#flags) | :congo_kinshasa: | `:congo_kinshasa:` | :central_african_republic: | `:central_african_republic:` | [top](#introduction) |
+| [top](#flags) | :congo_brazzaville: | `:congo_brazzaville:` | :switzerland: | `:switzerland:` | [top](#introduction) |
+| [top](#flags) | :cote_divoire: | `:cote_divoire:` | :cook_islands: | `:cook_islands:` | [top](#introduction) |
+| [top](#flags) | :chile: | `:chile:` | :cameroon: | `:cameroon:` | [top](#introduction) |
+| [top](#flags) | :cn: | `:cn:` | :colombia: | `:colombia:` | [top](#introduction) |
+| [top](#flags) | :clipperton_island: | `:clipperton_island:` | :costa_rica: | `:costa_rica:` | [top](#introduction) |
+| [top](#flags) | :cuba: | `:cuba:` | :cape_verde: | `:cape_verde:` | [top](#introduction) |
+| [top](#flags) | :curacao: | `:curacao:` | :christmas_island: | `:christmas_island:` | [top](#introduction) |
+| [top](#flags) | :cyprus: | `:cyprus:` | :czech_republic: | `:czech_republic:` | [top](#introduction) |
+| [top](#flags) | :de: | `:de:` | :diego_garcia: | `:diego_garcia:` | [top](#introduction) |
+| [top](#flags) | :djibouti: | `:djibouti:` | :denmark: | `:denmark:` | [top](#introduction) |
+| [top](#flags) | :dominica: | `:dominica:` | :dominican_republic: | `:dominican_republic:` | [top](#introduction) |
+| [top](#flags) | :algeria: | `:algeria:` | :ceuta_melilla: | `:ceuta_melilla:` | [top](#introduction) |
+| [top](#flags) | :ecuador: | `:ecuador:` | :estonia: | `:estonia:` | [top](#introduction) |
+| [top](#flags) | :egypt: | `:egypt:` | :western_sahara: | `:western_sahara:` | [top](#introduction) |
+| [top](#flags) | :eritrea: | `:eritrea:` | :es: | `:es:` | [top](#introduction) |
+| [top](#flags) | :ethiopia: | `:ethiopia:` | :eu: | `:eu:` `:european_union:` | [top](#introduction) |
+| [top](#flags) | :finland: | `:finland:` | :fiji: | `:fiji:` | [top](#introduction) |
+| [top](#flags) | :falkland_islands: | `:falkland_islands:` | :micronesia: | `:micronesia:` | [top](#introduction) |
+| [top](#flags) | :faroe_islands: | `:faroe_islands:` | :fr: | `:fr:` | [top](#introduction) |
+| [top](#flags) | :gabon: | `:gabon:` | :gb: | `:gb:` `:uk:` | [top](#introduction) |
+| [top](#flags) | :grenada: | `:grenada:` | :georgia: | `:georgia:` | [top](#introduction) |
+| [top](#flags) | :french_guiana: | `:french_guiana:` | :guernsey: | `:guernsey:` | [top](#introduction) |
+| [top](#flags) | :ghana: | `:ghana:` | :gibraltar: | `:gibraltar:` | [top](#introduction) |
+| [top](#flags) | :greenland: | `:greenland:` | :gambia: | `:gambia:` | [top](#introduction) |
+| [top](#flags) | :guinea: | `:guinea:` | :guadeloupe: | `:guadeloupe:` | [top](#introduction) |
+| [top](#flags) | :equatorial_guinea: | `:equatorial_guinea:` | :greece: | `:greece:` | [top](#introduction) |
+| [top](#flags) | :south_georgia_south_sandwich_islands: | `:south_georgia_south_sandwich_islands:` | :guatemala: | `:guatemala:` | [top](#introduction) |
+| [top](#flags) | :guam: | `:guam:` | :guinea_bissau: | `:guinea_bissau:` | [top](#introduction) |
+| [top](#flags) | :guyana: | `:guyana:` | :hong_kong: | `:hong_kong:` | [top](#introduction) |
+| [top](#flags) | :heard_mcdonald_islands: | `:heard_mcdonald_islands:` | :honduras: | `:honduras:` | [top](#introduction) |
+| [top](#flags) | :croatia: | `:croatia:` | :haiti: | `:haiti:` | [top](#introduction) |
+| [top](#flags) | :hungary: | `:hungary:` | :canary_islands: | `:canary_islands:` | [top](#introduction) |
+| [top](#flags) | :indonesia: | `:indonesia:` | :ireland: | `:ireland:` | [top](#introduction) |
+| [top](#flags) | :israel: | `:israel:` | :isle_of_man: | `:isle_of_man:` | [top](#introduction) |
+| [top](#flags) | :india: | `:india:` | :british_indian_ocean_territory: | `:british_indian_ocean_territory:` | [top](#introduction) |
+| [top](#flags) | :iraq: | `:iraq:` | :iran: | `:iran:` | [top](#introduction) |
+| [top](#flags) | :iceland: | `:iceland:` | :it: | `:it:` | [top](#introduction) |
+| [top](#flags) | :jersey: | `:jersey:` | :jamaica: | `:jamaica:` | [top](#introduction) |
+| [top](#flags) | :jordan: | `:jordan:` | :jp: | `:jp:` | [top](#introduction) |
+| [top](#flags) | :kenya: | `:kenya:` | :kyrgyzstan: | `:kyrgyzstan:` | [top](#introduction) |
+| [top](#flags) | :cambodia: | `:cambodia:` | :kiribati: | `:kiribati:` | [top](#introduction) |
+| [top](#flags) | :comoros: | `:comoros:` | :st_kitts_nevis: | `:st_kitts_nevis:` | [top](#introduction) |
+| [top](#flags) | :north_korea: | `:north_korea:` | :kr: | `:kr:` | [top](#introduction) |
+| [top](#flags) | :kuwait: | `:kuwait:` | :cayman_islands: | `:cayman_islands:` | [top](#introduction) |
+| [top](#flags) | :kazakhstan: | `:kazakhstan:` | :laos: | `:laos:` | [top](#introduction) |
+| [top](#flags) | :lebanon: | `:lebanon:` | :st_lucia: | `:st_lucia:` | [top](#introduction) |
+| [top](#flags) | :liechtenstein: | `:liechtenstein:` | :sri_lanka: | `:sri_lanka:` | [top](#introduction) |
+| [top](#flags) | :liberia: | `:liberia:` | :lesotho: | `:lesotho:` | [top](#introduction) |
+| [top](#flags) | :lithuania: | `:lithuania:` | :luxembourg: | `:luxembourg:` | [top](#introduction) |
+| [top](#flags) | :latvia: | `:latvia:` | :libya: | `:libya:` | [top](#introduction) |
+| [top](#flags) | :morocco: | `:morocco:` | :monaco: | `:monaco:` | [top](#introduction) |
+| [top](#flags) | :moldova: | `:moldova:` | :montenegro: | `:montenegro:` | [top](#introduction) |
+| [top](#flags) | :st_martin: | `:st_martin:` | :madagascar: | `:madagascar:` | [top](#introduction) |
+| [top](#flags) | :marshall_islands: | `:marshall_islands:` | :macedonia: | `:macedonia:` | [top](#introduction) |
+| [top](#flags) | :mali: | `:mali:` | :myanmar: | `:myanmar:` | [top](#introduction) |
+| [top](#flags) | :mongolia: | `:mongolia:` | :macau: | `:macau:` | [top](#introduction) |
+| [top](#flags) | :northern_mariana_islands: | `:northern_mariana_islands:` | :martinique: | `:martinique:` | [top](#introduction) |
+| [top](#flags) | :mauritania: | `:mauritania:` | :montserrat: | `:montserrat:` | [top](#introduction) |
+| [top](#flags) | :malta: | `:malta:` | :mauritius: | `:mauritius:` | [top](#introduction) |
+| [top](#flags) | :maldives: | `:maldives:` | :malawi: | `:malawi:` | [top](#introduction) |
+| [top](#flags) | :mexico: | `:mexico:` | :malaysia: | `:malaysia:` | [top](#introduction) |
+| [top](#flags) | :mozambique: | `:mozambique:` | :namibia: | `:namibia:` | [top](#introduction) |
+| [top](#flags) | :new_caledonia: | `:new_caledonia:` | :niger: | `:niger:` | [top](#introduction) |
+| [top](#flags) | :norfolk_island: | `:norfolk_island:` | :nigeria: | `:nigeria:` | [top](#introduction) |
+| [top](#flags) | :nicaragua: | `:nicaragua:` | :netherlands: | `:netherlands:` | [top](#introduction) |
+| [top](#flags) | :norway: | `:norway:` | :nepal: | `:nepal:` | [top](#introduction) |
+| [top](#flags) | :nauru: | `:nauru:` | :niue: | `:niue:` | [top](#introduction) |
+| [top](#flags) | :new_zealand: | `:new_zealand:` | :oman: | `:oman:` | [top](#introduction) |
+| [top](#flags) | :panama: | `:panama:` | :peru: | `:peru:` | [top](#introduction) |
+| [top](#flags) | :french_polynesia: | `:french_polynesia:` | :papua_new_guinea: | `:papua_new_guinea:` | [top](#introduction) |
+| [top](#flags) | :philippines: | `:philippines:` | :pakistan: | `:pakistan:` | [top](#introduction) |
+| [top](#flags) | :poland: | `:poland:` | :st_pierre_miquelon: | `:st_pierre_miquelon:` | [top](#introduction) |
+| [top](#flags) | :pitcairn_islands: | `:pitcairn_islands:` | :puerto_rico: | `:puerto_rico:` | [top](#introduction) |
+| [top](#flags) | :palestinian_territories: | `:palestinian_territories:` | :portugal: | `:portugal:` | [top](#introduction) |
+| [top](#flags) | :palau: | `:palau:` | :paraguay: | `:paraguay:` | [top](#introduction) |
+| [top](#flags) | :qatar: | `:qatar:` | :reunion: | `:reunion:` | [top](#introduction) |
+| [top](#flags) | :romania: | `:romania:` | :serbia: | `:serbia:` | [top](#introduction) |
+| [top](#flags) | :ru: | `:ru:` | :rwanda: | `:rwanda:` | [top](#introduction) |
+| [top](#flags) | :saudi_arabia: | `:saudi_arabia:` | :solomon_islands: | `:solomon_islands:` | [top](#introduction) |
+| [top](#flags) | :seychelles: | `:seychelles:` | :sudan: | `:sudan:` | [top](#introduction) |
+| [top](#flags) | :sweden: | `:sweden:` | :singapore: | `:singapore:` | [top](#introduction) |
+| [top](#flags) | :st_helena: | `:st_helena:` | :slovenia: | `:slovenia:` | [top](#introduction) |
+| [top](#flags) | :svalbard_jan_mayen: | `:svalbard_jan_mayen:` | :slovakia: | `:slovakia:` | [top](#introduction) |
+| [top](#flags) | :sierra_leone: | `:sierra_leone:` | :san_marino: | `:san_marino:` | [top](#introduction) |
+| [top](#flags) | :senegal: | `:senegal:` | :somalia: | `:somalia:` | [top](#introduction) |
+| [top](#flags) | :suriname: | `:suriname:` | :south_sudan: | `:south_sudan:` | [top](#introduction) |
+| [top](#flags) | :sao_tome_principe: | `:sao_tome_principe:` | :el_salvador: | `:el_salvador:` | [top](#introduction) |
+| [top](#flags) | :sint_maarten: | `:sint_maarten:` | :syria: | `:syria:` | [top](#introduction) |
+| [top](#flags) | :swaziland: | `:swaziland:` | :tristan_da_cunha: | `:tristan_da_cunha:` | [top](#introduction) |
+| [top](#flags) | :turks_caicos_islands: | `:turks_caicos_islands:` | :chad: | `:chad:` | [top](#introduction) |
+| [top](#flags) | :french_southern_territories: | `:french_southern_territories:` | :togo: | `:togo:` | [top](#introduction) |
+| [top](#flags) | :thailand: | `:thailand:` | :tajikistan: | `:tajikistan:` | [top](#introduction) |
+| [top](#flags) | :tokelau: | `:tokelau:` | :timor_leste: | `:timor_leste:` | [top](#introduction) |
+| [top](#flags) | :turkmenistan: | `:turkmenistan:` | :tunisia: | `:tunisia:` | [top](#introduction) |
+| [top](#flags) | :tonga: | `:tonga:` | :tr: | `:tr:` | [top](#introduction) |
+| [top](#flags) | :trinidad_tobago: | `:trinidad_tobago:` | :tuvalu: | `:tuvalu:` | [top](#introduction) |
+| [top](#flags) | :taiwan: | `:taiwan:` | :tanzania: | `:tanzania:` | [top](#introduction) |
+| [top](#flags) | :ukraine: | `:ukraine:` | :uganda: | `:uganda:` | [top](#introduction) |
+| [top](#flags) | :us_outlying_islands: | `:us_outlying_islands:` | :united_nations: | `:united_nations:` | [top](#introduction) |
+| [top](#flags) | :us: | `:us:` | :uruguay: | `:uruguay:` | [top](#introduction) |
+| [top](#flags) | :uzbekistan: | `:uzbekistan:` | :vatican_city: | `:vatican_city:` | [top](#introduction) |
+| [top](#flags) | :st_vincent_grenadines: | `:st_vincent_grenadines:` | :venezuela: | `:venezuela:` | [top](#introduction) |
+| [top](#flags) | :british_virgin_islands: | `:british_virgin_islands:` | :us_virgin_islands: | `:us_virgin_islands:` | [top](#introduction) |
+| [top](#flags) | :vietnam: | `:vietnam:` | :vanuatu: | `:vanuatu:` | [top](#introduction) |
+| [top](#flags) | :wallis_futuna: | `:wallis_futuna:` | :samoa: | `:samoa:` | [top](#introduction) |
+| [top](#flags) | :kosovo: | `:kosovo:` | :yemen: | `:yemen:` | [top](#introduction) |
+| [top](#flags) | :mayotte: | `:mayotte:` | :south_africa: | `:south_africa:` | [top](#introduction) |
+| [top](#flags) | :zambia: | `:zambia:` | :zimbabwe: | `:zimbabwe:` | [top](#introduction) |
+
+### Subdivision Flag
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#flags) | :england: | `:england:` | :scotland: | `:scotland:` | [top](#introduction) |
+| [top](#flags) | :wales: | `:wales:` | | | [top](#introduction) |
+
+## GitHub Custom Emoji
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#github-custom-emoji) | :accessibility: | `:accessibility:` | :atom: | `:atom:` | [top](#introduction) |
+| [top](#github-custom-emoji) | :basecamp: | `:basecamp:` | :basecampy: | `:basecampy:` | [top](#introduction) |
+| [top](#github-custom-emoji) | :bowtie: | `:bowtie:` | :dependabot: | `:dependabot:` | [top](#introduction) |
+| [top](#github-custom-emoji) | :electron: | `:electron:` | :feelsgood: | `:feelsgood:` | [top](#introduction) |
+| [top](#github-custom-emoji) | :finnadie: | `:finnadie:` | :fishsticks: | `:fishsticks:` | [top](#introduction) |
+| [top](#github-custom-emoji) | :goberserk: | `:goberserk:` | :godmode: | `:godmode:` | [top](#introduction) |
+| [top](#github-custom-emoji) | :hurtrealbad: | `:hurtrealbad:` | :neckbeard: | `:neckbeard:` | [top](#introduction) |
+| [top](#github-custom-emoji) | :octocat: | `:octocat:` | :rage1: | `:rage1:` | [top](#introduction) |
+| [top](#github-custom-emoji) | :rage2: | `:rage2:` | :rage3: | `:rage3:` | [top](#introduction) |
+| [top](#github-custom-emoji) | :rage4: | `:rage4:` | :shipit: | `:shipit:` | [top](#introduction) |
+| [top](#github-custom-emoji) | :suspect: | `:suspect:` | :trollface: | `:trollface:` | [top](#introduction) |
--- /dev/null
- [`where`]: /functions/collections/where
+---
+title: Page collections
+description: A quick reference guide to Hugo's page collections.
+categories: [quick reference]
+keywords: []
+menu:
+ docs:
+ parent: quick-reference
+ weight: 50
+weight: 50
+toc: true
+---
+
+## Page
+
+Use these `Page` methods when rendering lists on [section] pages, [taxonomy] pages, [term] pages, and the home page.
+
+[section]: /getting-started/glossary/#section
+[taxonomy]: /getting-started/glossary/#taxonomy
+[term]: /getting-started/glossary/#term
+
+{{< list-pages-in-section path=/methods/page filter=methods_page_page_collections filterType=include omitElementIDs=true titlePrefix=PAGE. >}}
+
+## Site
+
+Use these `Site` methods when rendering lists on any page.
+
+{{< list-pages-in-section path=/methods/site filter=methods_site_page_collections filterType=include omitElementIDs=true titlePrefix=SITE. >}}
+
+## Filter
+
+Use the [`where`] function to filter page collections.
+
++[`where`]: /functions/collections/where/
+
+## Sort
+
+Use these methods to sort page collections.
+
+{{< list-pages-in-section path=/methods/pages filter=methods_pages_sort filterType=include titlePrefix=. omitElementIDs=true titlePrefix=PAGES. >}}
+
+## Group
+
+Use these methods to group page collections.
+
+{{< list-pages-in-section path=/methods/pages filter=methods_pages_group filterType=include titlePrefix=. omitElementIDs=true titlePrefix=PAGES. >}}
--- /dev/null
--- /dev/null
++---
++cascade:
++ _build:
++ list: never
++ publishResources: false
++ render: never
++---
++
++<!--
++Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
++
++Include the rendered content using the "include" shortcode.
++-->
--- /dev/null
--- /dev/null
++---
++# 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
--- /dev/null
--- /dev/null
++---
++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.
--- /dev/null
--- /dev/null
++---
++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 >}}
++<pre class="mermaid">
++ {{- .Inner | safeHTML }}
++</pre>
++{{ .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" }}
++ <script type="module">
++ import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
++ mermaid.initialize({ startOnLoad: true });
++ </script>
++{{ 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" %}}
--- /dev/null
--- /dev/null
++---
++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 >}}
++<h{{ .Level }} id="{{ .Anchor }}">
++ {{- .Text | safeHTML -}}
++</h{{ .Level }}>
++{{< /code >}}
++
++To add an anchor link to the right of each heading:
++
++{{< code file=layouts/_default/_markup/render-heading.html copy=true >}}
++<h{{ .Level }} id="{{ .Anchor }}">
++ {{ .Text | safeHTML }}
++ <a href="#{{ .Anchor }}">#</a>
++</h{{ .Level }}>
++{{< /code >}}
++
++{{% include "/render-hooks/_common/pageinner.md" %}}
--- /dev/null
--- /dev/null
++---
++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 >}}
++<img src="{{ .Destination | safeURL }}"
++ {{- with .Text }} alt="{{ . }}"{{ end -}}
++ {{- with .Title }} title="{{ . }}"{{ end -}}
++>
++{{- /* chomp trailing newline */ -}}
++{{< /code >}}
++
++To render standalone images within `figure` elements:
++
++{{< code file=layouts/_default/_markup/render-image.html copy=true >}}
++{{- if .IsBlock -}}
++ <figure>
++ <img src="{{ .Destination | safeURL }}"
++ {{- with .Text }} alt="{{ . }}"{{ end -}}
++ >
++ <figcaption>{{ .Title }}</figcaption>
++ </figure>
++{{- else -}}
++ <img src="{{ .Destination | safeURL }}"
++ {{- with .Text }} alt="{{ . }}"{{ end -}}
++ {{- with .Title }} title="{{ . }}"{{ end -}}
++ >
++{{- 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" %}}
--- /dev/null
--- /dev/null
++---
++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
++<p><a href="https://gohugo.io">Hugo</a></p>
++<p><img alt="kitten" src="kitten.jpg"></p>
++```
++
++By creating link and image render hooks, you can alter the conversion from Markdown to HTML. For example:
++
++```html
++<p><a href="https://gohugo.io" rel="external">Hugo</a></p>
++<p><img alt="kitten" src="kitten.jpg" width="600" height="400"></p>
++```
++
++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.
--- /dev/null
--- /dev/null
++---
++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 >}}
++<a href="{{ .Destination | safeURL }}"
++ {{- with .Title }} title="{{ . }}"{{ end -}}
++>
++ {{- with .Text | safeHTML }}{{ . }}{{ end -}}
++</a>
++{{- /* 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 -}}
++<a href="{{ .Destination | safeURL }}"
++ {{- with .Title }} title="{{ . }}"{{ end -}}
++ {{- if $u.IsAbs }} rel="external"{{ end -}}
++>
++ {{- with .Text | safeHTML }}{{ . }}{{ end -}}
++</a>
++{{- /* 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" %}}
--- /dev/null
- * 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).
+---
+title: Forestry.io
+date: 2018-03-16
+description: "Showcase: \"Seeing Hugo in action is a whole different world of awesome.\""
+siteURL: https://forestry.io/
+siteSource: https://github.com/forestryio/forestry.io
+---
+
+It was clear from the get-go that we had to go with a static site generator. Static sites are secure, performant, and give you 100% flexibility. At [Forestry.io](https://forestry.io/) we provide Content Management Solutions for websites built with static site generators, so we might be a little biased. The only question: Which static site generator was the right choice for us?
+
+### Why Hugo?
+
+In our early research we looked at Ionic’s [site](https://github.com/ionic-team/ionic) to get some inspiration. They used Jekyll to build their website. While Jekyll is a great generator, the build times for larger sites can be painfully slow. With more than 150 pages plus many custom configurations and add-ons, our website doesn’t fall into the low-volume category anymore. Our developers want a smooth experience when working on the website and our content editors need the ability to preview content quickly. In short, we need our builds to be lightning fast.
+
+We knew Hugo was fast but we did [some additional benchmarking](https://forestry.io/blog/hugo-vs-jekyll-benchmark/) before making our decision. Seeing Hugo in action is a whole different world of awesome. Hugo takes less than one second to build our 150-page site! Take a look:
+
+```text
+ | EN
++------------------+-----+
+ Pages | 141
+ Paginator pages | 4
+ Non-page files | 0
+ Static files | 537
+ Processed images | 0
+ Aliases | 60
+ Sitemaps | 1
+ Cleaned | 0
+
+Total in 739 ms
+```
+
+In fact, we liked Hugo so much that our wizard Chris made his workflow public and we started the open-source project [Create-Static-Site](https://github.com/forestryio/create-static-site). It's [a simple way to spin up sites](https://forestry.io/blog/up-and-running-with-hugo/) and set up a modern web development workflow with one line of code. Essentially it adds build configurations as a dependency for JS, CSS and Image Processing.
+
+Lastly, we want to take the opportunity to give some love to other amazing tools we used building our website.
+
+### 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://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.
+* We can’t stop raving about [**Algolia**](https://www.algolia.com/). Chris loves it and even wrote a tutorial on [how to implement Algolia](https://forestry.io/blog/search-with-algolia-in-hugo/) into static sites using Hugo’s [Custom Outputs](/templates/output-formats/).
+* [**Cloudinary**](https://cloudinary.com/) is probably one of the easiest ways to get responsive images into your website.
+* We might be a little biased on this one - We think [**Forestry.io**](https://forestry.io/) is a great way to add a content management system with a clean UI on top of your site without interrupting your experience as a developer.
+* For hosting purposes we use the almighty [**AWS**](https://aws.amazon.com/).
+* [**Formspree.io**](https://formspree.io/) is managing our support and enterprise requests.
+* We also use browser cookies and JS to customize our user’s experience and give it a more dynamic feel.
--- /dev/null
- * Our writers use shortcodes to enhance the capability of markdown.
+---
+
+title: KeyCDN
+date: 2020-04-10
+description: "Showcase: \"Hugo has become an integral part of our stack.\""
+siteURL: https://www.keycdn.com
+
+---
+
+At KeyCDN one of our primary focuses is on performance. With speed being ingrained in our DNA we knew from the start that we must use a fast static website generator that could meet our requirements. When evaluating the right solution, Hugo met our requirements and we looked no further as it was the fastest and most flexible.
+
+## Why we chose Hugo
+
+Before our migration to Hugo our website was powered by a PHP-based website that had about 50 pages and a WordPress website that had over 500 posts between our blog and knowledge base. This became harder to maintain as time continued. We felt like we were losing the speed and flexibility that we require. To overcome this we knew we needed to convert our website to be static. This would allow our website to be faster and more secure as it could be delivered by all of our edge locations.
+
+It wasn’t an easy task at the beginning, however, after evaluating Hugo and benchmarking it we knew we had found the ideal solution. Hugo was by far the fastest setup and offered an intuitive way to build our entire website exactly as needed. The Go-based templates, shortcodes, and configuration options made it easy to build a complex website.
+
+In the fall of 2018 we started the migration and within a couple short months we had built a custom static website with Hugo and migrated all content from our old systems. The simplicity and vast amount of functionality that Hugo offers made this process fast and left our entire team, including all of our writers and developers, happy with the migration. Since migrating to Hugo we haven’t looked back. Hugo has become an integral part of our stack. We’re grateful to all those who have contributed to make Hugo what it is today.
+
+## Technical overview
+
+Below is an overview of what we used with Hugo to build our website:
+
+* [KeyCDN](https://www.keycdn.com) uses a custom theme and is our primary hub for all style sheets and JavaScript. Our other websites, like [KeyCDN Tools](https://tools.keycdn.com), only import the required style sheets and JavaScript.
+* We use [Gulp](https://gulpjs.com) in our build process for many tasks, such as combining, versioning, and compressing our style sheets as well as our JavaScript.
+* 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 entire website is delivered through KeyCDN using a Pull Zone, which means all of our edge locations are delivering our website.
--- /dev/null
- 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.
+---
+
+# A suitable title for this article.
+title: Quiply Employee Communications App
+
+# Set this to the current date.
+date: 2018-02-13
+
+description: "\"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.\""
+
+# The URL to the site on the internet.
+siteURL: https://www.quiply.com
+
+# Link to the site's Hugo source code if public and you can/want to share.
+# Remove or leave blank if not needed/wanted.
+# siteSource: https://github.com/gohugoio/hugoDocs
+
+# Add credit to the article author. Leave blank or remove if not needed/wanted.
+byline: "[Sebastian Schirmer](mailto:sebastian.schirmer@quiply.com), Quiply Co-Founder"
+
+---
+
+With the launch of our Employee Communications app Quiply we created a very simple and static one-page website to showcase our product.
+
+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.
+
+Huge thanks to everyone involved in making Hugo a success.
--- /dev/null
- linkTitle: 404 page
- description: If you know how to create a single page template, you have unlimited options for creating a custom 404.
+---
+title: Custom 404 page
- 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:
++linkTitle: 404 template
++description: Create a template to render a 404 error page.
+categories: [templates]
+keywords: ['404',page not found]
+menu:
+ docs:
+ parent: templates
+ weight: 220
+weight: 220
+---
+
- <main id="main">
- <div>
- <h1 id="title"><a href="{{ "" | relURL }}">Go Home</a></h1>
- </div>
- </main>
++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" }}
- ## Automatic loading
++ <h1>404 Not Found</h1>
++ <p>The page you requested cannot be found.</p>
++ <p>
++ <a href="{{ .Site.Home.RelPermalink }}">
++ Return to the home page
++ </a>
++ </p>
+{{ end }}
+{{< /code >}}
+
- 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.
++For multilingual sites, add the language key to the file name:
+
- [pagevars]: /variables/page/
++```text
++layouts/
++├── 404.de.html
++├── 404.en.html
++└── 404.fr.html
++```
+
++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/).
--- /dev/null
- linkTitle: Overview
+---
+title: Templates
- identifier: templates-overview
++linkTitle: In this section
+description: Go templating, template types and lookup order, shortcodes, and data.
+categories: []
+keywords: []
+menu:
+ docs:
++ identifier: templates-in-this-section
+ parent: templates
+ weight: 10
+weight: 10
+aliases: [/templates/overview/,/templates/content]
+---
+
+A template is an HTML file with [template actions](/getting-started/glossary/#template-action), located within the layouts directory of a project, theme, or module. Visit the topics below, in the order presented, to understand template selection and creation.
--- /dev/null
- [hugolists]: /templates/lists
+---
+title: Base templates and blocks
+description: The base and block constructs allow you to define the outer shell of your master templates (i.e., the chrome of the page).
+categories: [templates,fundamentals]
+keywords: [blocks,base]
+menu:
+ docs:
+ parent: templates
+ weight: 40
+weight: 40
+toc: true
+aliases: [/templates/blocks/,/templates/base-templates-and-blocks/]
+---
+
+The `block` keyword allows you to define the outer shell of your pages' one or more master template(s) and then fill in or override portions as necessary.
+
+{{< youtube QVOMCYitLEc >}}
+
+## Base template lookup order
+
+The base template lookup order closely follows that of the template it applies to (e.g. `_default/list.html`).
+
+See [Template Lookup Order](/templates/lookup-order/) for details and examples.
+
+## Define the base template
+
+The following defines a simple base template at `_default/baseof.html`. As a default template, it is the shell from which all your pages will be rendered unless you specify another `*baseof.html` closer to the beginning of the lookup order.
+
+{{< code file=layouts/_default/baseof.html >}}
+<!DOCTYPE html>
+<html>
+ <head>
+ <meta charset="utf-8">
+ <title>{{ block "title" . }}
+ <!-- Blocks may include default content. -->
+ {{ .Site.Title }}
+ {{ end }}</title>
+ </head>
+ <body>
+ <!-- Code that all your templates share, like a header -->
+ {{ block "main" . }}
+ <!-- The part of the page that begins to differ between templates -->
+ {{ end }}
+ {{ block "footer" . }}
+ <!-- More shared code, perhaps a footer but that can be overridden if need be in -->
+ {{ end }}
+ </body>
+</html>
+{{< /code >}}
+
+## Override the base template
+
+From the above base template, you can define a [default list template][hugolists]. The default list template will inherit all of the code defined above and can then implement its own `"main"` block from:
+
+{{< code file=layouts/_default/list.html >}}
+{{ define "main" }}
+ <h1>Posts</h1>
+ {{ range .Pages }}
+ <article>
+ <h2>{{ .Title }}</h2>
+ {{ .Content }}
+ </article>
+ {{ end }}
+{{ end }}
+{{< /code >}}
+
+This replaces the contents of our (basically empty) "main" block with something useful for the list template. In this case, we didn't define a `"title"` block, so the contents from our base template remain unchanged in lists.
+
+{{% note %}}
+Code that you put outside the block definitions *can* break your layout. This even includes HTML comments. For example:
+
+```go-html-template
+<!-- Seemingly harmless HTML comment..that will break your layout at build -->
+{{ define "main" }}
+...your code here
+{{ end }}
+```
+[See this thread from the Hugo discussion forums.](https://discourse.gohugo.io/t/baseof-html-block-templates-and-list-types-results-in-empty-pages/5612/6)
+{{% /note %}}
+
+The following shows how you can override both the `"main"` and `"title"` block areas from the base template with code unique to your [default single page template][singletemplate]:
+
+{{< code file=layouts/_default/single.html >}}
+{{ define "title" }}
+ <!-- This will override the default value set in baseof.html; i.e., "{{ .Site.Title }}" in the original example-->
+ {{ .Title }} – {{ .Site.Title }}
+{{ end }}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+{{ end }}
+{{< /code >}}
+
++[hugolists]: /templates/lists/
+[lookup]: /templates/lookup-order/
+[rendering the section]: /templates/section-templates/
+[singletemplate]: /templates/single-page-templates/
--- /dev/null
--- /dev/null
++---
++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'
++{{</ code-toggle >}}
++
++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"
++{{</ code-toggle >}}
++
++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 >}}
++
++{{< 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 = []
++{{</ code-toggle >}}
++
++Hugo uses the page title and description for the title and description metadata.
++The first 6 URLs from the `images` array are used for image metadata.
++If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with file names matching `*feature*` 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 `<meta property="og:video" content="url">`. Use the `https://youtu.be/<id>` 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 >}}
++
++{{< code-toggle file=content/blog/my-post.md >}}
++title = "Post title"
++description = "Text about this post"
++images = ["post-cover.png"]
++{{</ code-toggle >}}
++
++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"
++{{</ code-toggle >}}
++
++NOTE: The `@` will be added for you
++
++```html
++<meta name="twitter:site" content="@GoHugoIO"/>
++```
--- /dev/null
- Homepage is a `Page` and therefore has all the [page variables][pagevars] and [site variables][sitevars] available for use.
-
- {{% note %}}
+---
+title: Homepage template
+description: The homepage of a website is often formatted differently than the other pages. For this reason, Hugo makes it easy for you to define your new site's homepage as a unique template.
+categories: [templates]
+keywords: [homepage]
+menu:
+ docs:
+ parent: templates
+ weight: 70
+weight: 70
+toc: true
+aliases: [/layout/homepage/,/templates/homepage-template/]
+---
+
- {{% /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.
- 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].
-
++
+
+{{< youtube ut1xtRZ1QOA >}}
+
+## Homepage template lookup order
+
+See [Template Lookup](/templates/lookup-order/).
+
+## Add content and front matter to the homepage
+
+The homepage, similar to other [list pages in Hugo][lists], accepts content and front matter from an `_index.md` file. This file should live at the root of your `content` folder (i.e., `content/_index.md`). You can then add body copy and metadata to your homepage the way you would any other content file.
+
+See the homepage template below or [Content Organization][contentorg] for more information on the role of `_index.md` in adding content and front matter to list pages.
+
+## Example homepage template
+
- [base]: /templates/base/
+{{< code file=layouts/index.html >}}
+{{ define "main" }}
+ <main aria-role="main">
+ <header class="homepage-header">
+ <h1>{{ .Title }}</h1>
+ {{ with .Params.subtitle }}
+ <span class="subtitle">{{ . }}</span>
+ {{ end }}
+ </header>
+ <div class="homepage-content">
+ <!-- Note that the content for index.html, as a sort of list page, will pull from content/_index.md -->
+ {{ .Content }}
+ </div>
+ <div>
+ {{ range first 10 .Site.RegularPages }}
+ {{ .Render "summary" }}
+ {{ end }}
+ </div>
+ </main>
+{{ end }}
+{{< /code >}}
+
- [pagevars]: /variables/page/
- [partials]: /templates/partials/
- [sitevars]: /variables/site/
+[contentorg]: /content-management/organization/
+[lists]: /templates/lists/
+[lookup]: /templates/lookup-order/
--- /dev/null
- title: Templating
- linkTitle: Templating
- description: Hugo uses Go's `html/template` and `text/template` libraries as the basis for the templating.
+---
- keywords: [go]
++title: Introduction to templating
++linkTitle: Introduction
++description: Create templates to render your content, resources, and data.
+categories: [templates,fundamentals]
- aliases: [/layouts/introduction/,/layout/introduction/, /templates/go-templates/]
++keywords: []
+menu:
+ docs:
++ identifier: templates-introduction
+ parent: templates
+ weight: 20
+weight: 20
+toc: true
- {{% 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.
+---
+
- ## Basic syntax
++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.
+
- Go Templates are HTML files with the addition of [variables][variables] and [functions][functions]. Go Template variables and functions are accessible within `{{ }}`.
++[functions]: /functions/
++[methods]: /methods/
++[variables]: #variables
+
- ### Access a predefined variable
++{{% note %}}
++Hugo uses Go's [text/template] and [html/template] packages.
+
- 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).
++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.
+
- ```go-html-template
- {{ .Title }}
- {{ $address }}
- ```
++By default, Hugo uses the html/template package when rendering HTML files.
+
- Parameters for functions are separated using spaces. The general syntax is:
++[text/template]: https://pkg.go.dev/text/template
++[html/template]: https://pkg.go.dev/html/template
++{{% /note %}}
+
- {{ FUNCTION ARG1 ARG2 .. }}
++For example, this HTML template initializes the `$v1` and `$v2` variables, then displays them and their product within an HTML paragraph.
+
+```go-html-template
- The following example calls the `add` function with inputs of `1` and `2`:
++{{ $v1 := 6 }}
++{{ $v2 := 7 }}
++<p>The product of {{ $v1 }} and {{ $v2 }} is {{ mul $v1 $v2 }}.</p>
+```
+
- ```go-html-template
- {{ add 1 2 }}
- ```
++While HTML templates are the most common, you can create templates for any [output format] including CSV, JSON, RSS, and plain text.
+
- #### Methods and fields are accessed via dot notation
++[output format]: /templates/output-formats/
+
- Accessing the Page Parameter `bar` defined in a piece of content's [front matter].
++## Context
+
- ```go-html-template
- {{ .Params.bar }}
- ```
++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].
+
- #### Parentheses can be used to group items together
++[objects]: /getting-started/glossary/#object
++[methods]: /getting-started/glossary/#method
+
- ```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")
- }}
- ```
++For example, a template for a single page receives a `Page` object, and the `Page` object provides methods to return values or perform actions.
+
- #### Raw string literals can include newlines
-
- ```go-html-template
- {{ $msg := `Line one.
- Line two.` }}
- ```
-
- ## Variables
++### 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].
++Within a template, the dot (`.`) represents the current context.
+
- 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`):
++{{< code file=layouts/_default/single.html >}}
++<h2>{{ .Title }}</h2>
++{{< /code >}}
+
- ```go-html-template
- <title>{{ .Title }}</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].
+
- Values can also be stored in custom variables and referenced later:
++[front matter]: /content-management/front-matter/
++[`Title`]: /methods/page/title
+
- {{% note %}}
- The custom variables need to be prefixed with `$`.
- {{% /note %}}
++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.
+
- ```go-html-template
- {{ $address := "123 Main St." }}
- {{ $address }}
- ```
++[`range`]: /functions/go-template/range/
++[`with`]: /functions/go-template/with/
+
- 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:
++{{< code file=layouts/_default/single.html >}}
++<h2>{{ .Title }}</h2>
+
- ```go-html-template
- {{ $var := "Hugo Page" }}
- {{ if .IsHome }}
- {{ $var = "Hugo Home" }}
++{{ range slice "foo" "bar" }}
++ <p>{{ . }}</p>
++{{ end }}
+
- Var is {{ $var }}
- ```
++{{ with "baz" }}
++ <p>{{ . }}</p>
+{{ end }}
- Variable names must conform to Go's naming rules for [identifiers][identifier].
++{{< /code >}}
+
- ## Functions
++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:
+
- Go Templates only ship with a few basic functions but also provide a mechanism for applications to extend the original set.
++[slice]: /getting-started/glossary/#slice
+
- [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.
++```html
++<h2>My Page Title</h2>
++<p>foo</p>
++<p>bar</p>
++<p>baz</p>
++```
+
- ### Example 1: adding numbers
++### Template context
+
- ```go-html-template
- {{ add 1 2 }}
- <!-- prints 3 -->
- ```
++Within a `range` or `with` block you can access the context passed into the template by prepending a dollar sign (`$`) to the dot:
+
- ### Example 2: comparing numbers
++{{< code file=layouts/_default/single.html >}}
++{{ with "foo" }}
++ <p>{{ $.Title }} - {{ . }}</p>
++{{ end }}
++{{< /code >}}
+
- ```go-html-template
- {{ lt 1 2 }}
- <!-- prints true (i.e., since 1 is less than 2) -->
++Hugo renders this to:
+
- Note that both examples make use of Go Template's [math][math] functions.
-
++```html
++<p>My Page Title - foo</p>
+```
+
- 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).
+{{% note %}}
- ## Includes
++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 %}}
+
- When including another template, you will need to pass it the data that it would
- need to access.
++## Actions
+
- {{% note %}}
- To pass along the current context, please remember to include a trailing **dot**.
- {{% /note %}}
++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.
+
- The templates location will always be starting at the `layouts/` directory
- within Hugo.
++A template action may contain literal values ([boolean], [string], [integer], and [float]), variables, functions, and methods.
+
- ### Partial
++[boolean]: /getting-started/glossary/#boolean
++[string]: /getting-started/glossary/#string
++[integer]: /getting-started/glossary/#integer
++[float]: /getting-started/glossary/#float
+
- The [`partial`][partials] function is used to include _partial_ templates using
- the syntax `{{ partial "<PATH>/<PARTIAL>.<EXTENSION>" . }}`.
++{{< code file=layouts/_default/single.html >}}
++{{ $convertToLower := true }}
++{{ if $convertToLower }}
++ <h2>{{ strings.ToLower .Title }}</h2>
++{{ end }}
++{{< /code >}}
+
- Example of including a `layouts/partials/header.html` partial:
++In the example above:
+
- ```go-html-template
- {{ partial "header.html" . }}
++- `$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
+
- ### Template
++Hugo renders the above to:
++
++```html
++
++
++ <h2>my page title</h2>
++
+```
+
- 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/<TEMPLATE>.<EXTENSION>" . }}`.
++### Whitespace
+
- {{% note %}}
- The available **internal** templates can be found
- [here](https://github.com/gohugoio/hugo/tree/master/tpl/tplimpl/embedded/templates).
- {{% /note %}}
++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:
+
- Example of including the internal `opengraph.html` template:
++{{< code file=layouts/_default/single.html >}}
++{{- $convertToLower := true -}}
++{{- if $convertToLower -}}
++ <h2>{{ strings.ToLower .Title }}</h2>
++{{- end -}}
++{{< /code >}}
+
- ```go-html-template
- {{ template "_internal/opengraph.html" . }}
++Hugo renders this to:
+
- ## Logic
-
- Go Templates provide the most basic iteration and conditional logic.
++```html
++<h2>my page title</h2>
+```
+
- ### Iteration
++Whitespace includes spaces, horizontal tabs, carriage returns, and newlines.
+
- 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`.
++### Pipes
+
- #### Example 1: using context (`.`)
++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:
+
- {{ range $array }}
- {{ . }} <!-- The . represents an element in $array -->
- {{ end }}
++[pipe]: /getting-started/glossary/#pipeline
+
+```go-html-template
- #### Example 2: declaring a variable name for an array element's value
++{{ strings.ToLower "Hugo" }} → hugo
++{{ "Hugo" | strings.ToLower }} → hugo
+```
+
- {{ range $elem_val := $array }}
- {{ $elem_val }}
- {{ end }}
++You can pipe the result of one function or method into another. For example, these are equivalent:
+
+```go-html-template
- #### 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.
++{{ strings.TrimSuffix "o" (strings.ToLower "Hugo") }} → hug
++{{ "Hugo" | strings.ToLower | strings.TrimSuffix "o" }} → hug
+```
+
- {{ range $elem_index, $elem_val := $array }}
- {{ $elem_index }} -- {{ $elem_val }}
- {{ end }}
++These are also equivalent:
+
+```go-html-template
- #### 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 }}
- ```
++{{ mul 6 (add 2 5) }} → 42
++{{ 5 | add 2 | mul 6 }} → 42
+```
+
- #### Example 5: conditional on empty _map_, _array_, or _slice_
++{{% note %}}
++Remember that the piped value becomes the final argument to the function or method to which you are piping.
++{{% /note %}}
+
- If the _map_, _array_, or _slice_ passed into the range is zero-length then the else statement is evaluated.
++### Line splitting
+
- {{ range $array }}
- {{ . }}
- {{ else }}
- <!-- This is only evaluated if $array is empty -->
- {{ end }}
- ```
++You can split a template action over two or more lines. For example, these are equivalent:
+
+```go-html-template
- ### 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 }}`.
++{{ $v := or
++ .Site.Language.LanguageName
++ .Site.Language.Lang
++}}
++```
+
- Go Templates treat the following values as **false**:
++You can also split [raw string literals] over two or more lines. For example, these are equivalent:
+
- - `false` (boolean)
- - 0 (integer)
- - any zero-length array, slice, map, or string
++[raw string literals]: /getting-started/glossary/#string-literal-raw
+
- #### Example 1: `with`
++```go-html-template
++{{ $msg := "This is line one.\nThis is line two." }}
+
- It is common to write "if something exists, do this" kind of
- statements using `with`.
++{{ $msg := `This is line one.
++This is line two.`
++}}
++```
+
- {{% note %}}
- `with` rebinds the context `.` within its scope (just like in `range`).
- {{% /note %}}
++## Variables
+
- It skips the block if the variable is absent, or if it evaluates to
- "false" as explained above.
++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.
+
- ```go-html-template
- {{ with .Params.title }}
- <h4>{{ . }}</h4>
- {{ end }}
- ```
++[identifier]: /getting-started/glossary/#identifier
+
- #### Example 2: `with` .. `else`
++Variables may contain [scalars], [slices], [maps], or [objects].
+
- Below snippet uses the "description" front-matter parameter's value if
- set, else uses the default `.Summary` [Page variable][pagevars]:
++[scalars]: /getting-started/glossary/#scalar
++[slices]: /getting-started/glossary/#slice
++[maps]: /getting-started/glossary/#map
++[objects]: /getting-started/glossary/#object
+
- {{ with .Param "description" }}
- {{ . }}
- {{ else }}
- {{ .Summary }}
++Use `:=` to initialize a variable, and use `=` to assign a value to a variable that has been previously initialized. For example:
+
+```go-html-template
- See the [`.Param` function][param].
-
- #### Example 3: `if`
++{{ $total := 3 }}
++{{ range slice 7 11 21 }}
++ {{ $total = add $total . }}
+{{ end }}
++{{ $total }} → 42
+```
+
- An alternative (and a more verbose) way of writing `with` is using
- `if`. Here, the `.` does not get rebound.
++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.
+
- Below example is "Example 1" rewritten using `if`:
++With variables that represent a slice or map, use the [`index`] function to return the desired value.
+
- {{ if isset .Params "title" }}
- <h4>{{ index .Params "title" }}</h4>
- {{ 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:
++[`index`]: /functions/collections/indexfunction/
+
+```go-html-template
- ```go-html-template
- {{ if (isset .Params "description") }}
- {{ index .Params "description" }}
- {{ else }}
- {{ .Summary }}
- {{ end }}
++{{ $slice := slice "foo" "bar" "baz" }}
++{{ index $slice 2 }} → baz
+
- #### Example 5: `if` .. `else if` .. `else`
-
- Unlike `with`, `if` can contain `else if` clauses too.
++{{ $map := dict "a" "foo" "b" "bar" "c" "baz" }}
++{{ index $map "c" }} → baz
+```
+
- ```go-html-template
- {{ if (isset .Params "description") }}
- {{ index .Params "description" }}
- {{ else if (isset .Params "summary") }}
- {{ index .Params "summary" }}
- {{ else }}
- {{ .Summary }}
- {{ end }}
- ```
++{{% note %}}
++Slices and arrays are zero-based; element 0 is the first element.
++{{% /note %}}
+
- #### Example 6: `and` & `or`
++With variables that represent a map or object, [chain] identifiers to return the desired value or to access the desired method.
+
- {{ if (and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")) }}
- ```
++[chain]: /getting-started/glossary/#chain
+
+```go-html-template
- ## 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.
++{{ $map := dict "a" "foo" "b" "bar" "c" "baz" }}
++{{ $map.c }} → baz
+
- 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.
++{{ $homePage := .Site.Home }}
++{{ $homePage.Title }} → My Homepage
++```
+
- A few simple examples should help convey how to use the pipe.
++{{% 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 %}}
+
- ### Example 1: `shuffle`
++## Functions
+
- The following two examples are functionally the same:
++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.
+
- ```go-html-template
- {{ shuffle (seq 1 5) }}
- ```
++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
- {{ (seq 1 5) | shuffle }}
- ```
++[go-templates]: /functions/go-template/
+
- ### Example 2: `index`
++Hugo provides hundreds of custom [functions] categorized by namespace. For example, the `strings` namespace includes these and other 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:
++[functions]: /functions
+
- ```go-html-template
- {{ index .Params "disqus_url" | html }}
- ```
++Function|Alias
++:--|:--
++[`strings.ToLower`](/functions/strings/tolower)|`lower`
++[`strings.ToUpper`](/functions/strings/toupper)|`upper`
++[`strings.Replace`](/functions/strings/replace)|`replace`
+
- ### Example 3: `or` with `isset`
++As shown above, frequently used functions have an alias. Use aliases in your templates to reduce code length.
+
- {{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr") }}
- Stuff Here
- {{ end }}
++When calling a function, separate the arguments from the function, and from each other, with a space. For example:
+
+```go-html-template
- Could be rewritten as
-
- ```go-html-template
- {{ if isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" }}
- Stuff Here
- {{ end }}
- ```
++{{ $total := add 1 2 3 4 }}
+```
+
- ## Context (aka "the dot") {#the-dot}
++## Methods
+
- The most easily overlooked concept to understand about Go Templates is
- that `{{ . }}` always refers to the **current context**.
++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.
+
- - 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.
++The most commonly accessed objects are the [`Page`] and [`Site`] objects. This is a small sampling of the [methods] available to each object.
+
- 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:
++[`Site`]: /methods/site/
++[`Page`]: /methods/page/
++[methods]: /methods/
+
- ### 1. Define a variable independent of context
++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.
+
- The following shows how to define a variable independent of the context.
++Chain the method to its object with a dot (`.`) as shown below, remembering that the leading dot represents the [current context].
+
- {{< code file=tags-range-with-page-variable.html >}}
- {{ $title := .Site.Title }}
- <ul>
- {{ range .Params.tags }}
- <li>
- <a href="/tags/{{ . | urlize }}">{{ . }}</a>
- - {{ $title }}
- </li>
- {{ end }}
- </ul>
++[current context]: #current-context
+
- {{% 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 %}}
++{{< code file=layouts/_default/single.html >}}
++{{ .Site.Title }} → My Site Title
++{{ .Page.Title }} → My Page Title
+{{< /code >}}
+
- ### 2. Use `$.` to access the global context
++The context passed into most templates is a `Page` object, so this is equivalent to the previous example:
+
- `$` 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:
++{{< code file=layouts/_default/single.html >}}
++{{ .Site.Title }} → My Site Title
++{{ .Title }} → My Page Title
++{{< /code >}}
+
- {{< code file=range-through-tags-w-global.html >}}
- <ul>
- {{ range .Params.tags }}
- <li>
- <a href="/tags/{{ . | urlize }}">{{ . }}</a>
- - {{ $.Site.Title }}
- </li>
- {{ end }}
- </ul>
++Some methods take an argument. Separate the argument from the method with a space. For example:
+
- {{% 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 %}}
++{{< code file=layouts/_default/single.html >}}
++{{ $page := .Page.GetPage "/books/les-miserables" }}
++{{ $page.Title }} → Les Misérables
+{{< /code >}}
+
- ## Whitespace
++## Comments
+
- 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.
++{{% note %}}
++Do not attempt to use HTML comment delimiters to comment out template code.
+
- For instance, the following Go Template will include the newlines and horizontal tab in its HTML output:
++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 %}}
+
- ```go-html-template
- <div>
- {{ .Title }}
- </div>
++Template comments are similar to template actions. Paired opening and closing braces represent the beginning and end of a comment. For example:
+
- Which will output:
++```text
++{{/* This is an inline comment. */}}
++{{- /* This is an inline comment with adjacent whitespace removed. */ -}}
+```
+
- ```html
- <div>
- Hello, World!
- </div>
++Code within a comment is not parsed, executed, or displayed. Comments may be inline, as shown above, or in block form:
+
- Leveraging the `-` in the following example will remove the extra white space surrounding the `.Title` variable and remove the newline:
++```text
++{{/*
++This is a block comment.
++*/}}
++
++{{- /*
++This is a block comment with
++adjacent whitespace removed.
++*/ -}}
+```
+
- ```go-html-template
- <div>
- {{- .Title -}}
- </div>
- ```
++You may not nest one comment inside of another.
+
- Which then outputs:
++To render an HTML comment, pass a string through the [`safeHTML`] template function. For example:
+
- ```html
- <div>Hello, World!</div>
++[`safeHTML`]: /functions/safe/html
+
- Go considers the following characters _whitespace_:
++```go-html-template
++{{ "<!-- I am an HTML comment. -->" | safeHTML }}
++{{ printf "<!-- This is the %s site. -->" .Site.Title | safeHTML }}
+```
+
- * space
- * horizontal tab
- * carriage return
- * newline
++## Include
+
- ## Comments
++Use the [`template`] function to include one or more of Hugo's [embedded templates]:
+
- 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.
++[embedded templates]: /templates/embedded/
+
- ### Go templates comments
++```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 support `{{/*` and `*/}}` to open and close a comment block. Nothing within that block will be rendered.
++[`partial`]: /functions/partials/include/
++[`partialCached`]: /functions/partials/includecached/
++[`template`]: functions/go-template/template/
+
- For example:
++Use the [`partial`] or [`partialCached`] function to include one or more [partial templates]:
+
- Bonsoir, {{/* {{ add 0 + 2 }} */}}Eliott.
++[partial templates]: /templates/partials
+
+```go-html-template
- Will render `Bonsoir, Eliott.`, and not care about the syntax error (`add 0 + 2`) in the comment block.
++{{ partial "breadcrumbs.html" . }}
++{{ partialCached "css.html" . }}
+```
+
- ### HTML comments
++Create your partial templates in the layouts/partials directory.
+
- You can add html comments by piping a string HTML code comment to `safeHTML`.
++{{% note %}}
++In the examples above, note that we are passing the current context (the dot) to each of the templates.
++{{% /note %}}
+
- For example:
++## Examples
+
- ```go-html-template
- {{ "<!-- This is an HTML comment -->" | safeHTML }}
- ```
++This limited set of contrived examples demonstrates some of concepts described above. Please see the [functions], [methods], and [templates] documentation for specific examples.
+
- If you need variables to construct such HTML comments, just pipe `printf` to `safeHTML`.
++[templates]: /templates/
+
- For example:
++### Conditional blocks
+
- {{ printf "<!-- Our website is named: %s -->" .Site.Title | safeHTML }}
++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
- #### HTML comments containing Go templates
++{{ $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 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.
++### Logical operators
+
- {{% note %}}
- Do **not** try to comment out Go Template code using HTML comments.
- {{% /note %}}
++See documentation for [`and`] and [`or`].
+
- <!-- {{ $author := "Emma Goldman" }} was a great woman. -->
- {{ $author }}
- ```
++[`and`]: /functions/go-template/and
++[`or`]: /functions/go-template/or
+
+```go-html-template
- 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).
++{{ $v1 := true }}
++{{ $v2 := false }}
++{{ $v3 := false }}
++{{ $result := false }}
+
- ## Use content (`Page`) parameters
++{{ if and $v1 $v2 $v3 }}
++ {{ $result = true }}
++{{ end }}
++{{ $result }} → false
+
- You can provide variables to be used by templates in individual content's [front matter].
++{{ if or $v1 $v2 $v3 }}
++ {{ $result = true }}
++{{ end }}
++{{ $result }} → true
++```
+
- 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`.
++### Loops
+
- Here is the example front matter:
++See documentation for [`range`], [`else`], and [`end`].
+
- {{< 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 }}
- <aside>
- <header>
- <a href="#{{ .Title | urlize }}">
- <h3>{{ .Title }}</h3>
- </a>
- </header>
- {{ .TableOfContents }}
- </aside>
- <a href="#" id="toc-toggle"></a>
++[`range`]: /functions/go-template/range/
+
- {{< /code >}}
++```go-html-template
++{{ $s := slice "foo" "bar" "baz" }}
++{{ range $s }}
++ <p>{{ . }}</p>
++{{ else }}
++ <p>The collection is empty</p>
+{{ end }}
- We want the *default* behavior to be for pages to include a TOC unless otherwise specified. This template checks to make sure that the `notoc:` field in this page's front matter is not `true`.
++```
+
- ## Use site configuration parameters
++Use the [`seq`] function to loop a specified number of times:
+
- You can arbitrarily define as many site-level parameters as you want in your [site's configuration file][config]. These parameters are globally available in your templates.
++[`seq`]: /functions/collections/seq
+
- For instance, you might declare the following:
++```go-html-template
++{{ $total := 0 }}
++{{ range seq 4 }}
++ {{ $total = add $total . }}
++{{ end }}
++{{ $total }} → 10
++```
+
- {{< code-toggle file=hugo >}}
- params:
- copyrighthtml: "Copyright © 2017 John Doe. All Rights Reserved."
- twitteruser: "spf13"
- sidebarrecentlimit: 5
- {{< /code >}}
++### Rebind context
+
- Within a footer layout, you might then declare a `<footer>` that is only rendered if the `copyrighthtml` parameter is provided. If it *is* provided, you will then need to declare the string is safe to use via the [`safeHTML`] function so that the HTML entity is not escaped again. This would let you easily update just your top-level configuration file each January 1st, instead of hunting through your templates.
++See documentation for [`with`], [`else`], and [`end`].
+
- {{ if .Site.Params.copyrighthtml }}
- <footer>
- <div class="text-center">{{ .Site.Params.CopyrightHTML | safeHTML }}</div>
- </footer>
++[`with`]: /functions/go-template/with/
+
+```go-html-template
- An alternative way of writing the "`if`" and then referencing the same value is to use [`with`] instead. `with` rebinds the context (`.`) within its scope and skips the block if the variable is absent:
++{{ $var := "foo" }}
++{{ with $var }}
++ {{ . }} → foo
++{{ else }}
++ {{ print "var is falsy" }}
+{{ end }}
+```
+
- {{< code file=layouts/partials/twitter.html >}}
- {{ with .Site.Params.twitteruser }}
- <div>
- <a href="https://twitter.com/{{ . }}" rel="author">
- <img src="/images/twitter.png" width="48" height="48" title="Twitter: {{ . }}" alt="Twitter"></a>
- </div>
- {{ end }}
- {{< /code >}}
++### Access site parameters
+
- Finally, you can pull "magic constants" out of your layouts as well. The following uses the [`first`] function, as well as the [`.RelPermalink`][relpermalink] page variable and the [`.Site.Pages`][sitevars] site variable.
++See documentation for the [`Params`](/methods/site/params/) method on a `Site` object.
++
++With this site configuration:
++
++{{< code-toggle file=hugo >}}
++title = 'ABC Widgets'
++baseURL = 'https://example.org'
++[params]
++ subtitle = 'The Best Widgets on Earth'
++ copyright-year = '2023'
++ [params.author]
++ email = 'jsmith@example.org'
++ name = 'John Smith'
++ [params.layouts]
++ rfc_1123 = 'Mon, 02 Jan 2006 15:04:05 MST'
++ rfc_3339 = '2006-01-02T15:04:05-07:00'
++{{< /code-toggle >}}
+
- <nav>
- <h1>Recent Posts</h1>
- <ul>
- {{- range first .Site.Params.SidebarRecentLimit .Site.Pages -}}
- <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
- {{- end -}}
- </ul>
- </nav>
++Access the custom site parameters by chaining the identifiers:
+
+```go-html-template
- ## Example: show future events
++{{ .Site.Params.subtitle }} → The Best Widgets on Earth
++{{ .Site.Params.author.name }} → John Smith
++
++{{ $layout := .Site.Params.layouts.rfc_1123 }}
++{{ .Site.Lastmod.Format $layout }} → Tue, 17 Oct 2023 13:21:02 PDT
+```
+
- Given the following content structure and [front matter]:
++### Access page parameters
+
- ```text
- content/
- └── events/
- ├── event-1.md
- ├── event-2.md
- └── event-3.md
- ```
++See documentation for the [`Params`](/methods/page/params/) method on a `Page` object.
+
- {{< code-toggle file=content/events/event-1.md >}}
- title = 'Event 1'
- date = 2021-12-06T10:37:16-08:00
- draft = false
- start_date = 2021-12-05T09:00:00-08:00
- end_date = 2021-12-05T11:00:00-08:00
++With this front matter:
+
- This [partial template][partials] renders future events:
-
- {{< code file=layouts/partials/future-events.html >}}
- <h2>Future Events</h2>
- <ul>
- {{ range where site.RegularPages "Type" "events" }}
- {{ if gt (.Params.start_date | time.AsTime) now }}
- {{ $startDate := .Params.start_date | time.Format ":date_medium" }}
- <li>
- <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> - {{ $startDate }}
- </li>
- {{ end }}
- {{ end }}
- </ul>
- {{< /code >}}
++{{< code-toggle file=content/news/annual-conference.md >}}
++title = 'Annual conference'
++date = 2023-10-17T15:11:37-07:00
++[params]
++display_related = true
++[params.author]
++ email = 'jsmith@example.org'
++ name = 'John Smith'
+{{< /code-toggle >}}
+
- If you restrict front matter to the TOML format, and omit quotation marks surrounding date fields, you can perform date comparisons without casting.
-
- {{< code file=layouts/partials/future-events.html >}}
- <h2>Future Events</h2>
- <ul>
- {{ range where (where site.RegularPages "Type" "events") "Params.start_date" "gt" now }}
- {{ $startDate := .Params.start_date | time.Format ":date_medium" }}
- <li>
- <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> - {{ $startDate }}
- </li>
- {{ end }}
- </ul>
- {{< /code >}}
-
- [`first`]: /functions/collections/first
- [`index`]: /functions/collections/indexfunction
- [`isset`]: /functions/collections/isset
- [config]: /getting-started/configuration
- [dotdoc]: https://golang.org/pkg/text/template/#hdr-Variables
- [front matter]: /content-management/front-matter
- [functions]: /functions
- [identifier]: /getting-started/glossary/#identifier
- [internal templates]: /templates/internal
- [math]: /functions/math
- [pagevars]: /variables/page
- [param]: /methods/page/param
- [partials]: /templates/partials
- [relpermalink]: /variables/page
- [`safehtml`]: /functions/safe/html
- [sitevars]: /variables/site
- [variables]: /variables
- [`with`]: /functions/go-template/with
++Access the custom page parameters by chaining the identifiers:
+
++```go-html-template
++{{ .Params.display_related }} → true
++{{ .Params.author.name }} → John Smith
++```
--- /dev/null
- ## List defaults
-
- ### Default templates
-
- Since section lists and taxonomy lists (N.B., *not* [taxonomy terms lists][taxterms]) are both *lists* with regards to their templates, both have the same terminating default of `_default/list.html` or `themes/<THEME>/layouts/_default/list.html` in their lookup order. In addition, both [section lists][sectiontemps] and [taxonomy lists][taxlists] have their own default list templates in `_default`.
-
- See [Template Lookup Order](/templates/lookup-order/) for the complete reference.
-
+---
+title: Lists of content in Hugo
+linkTitle: List templates
+description: Lists have a specific meaning and usage in Hugo when it comes to rendering your site homepage, section page, taxonomy list, or taxonomy terms list.
+categories: [templates]
+keywords: [lists,sections,rss,taxonomies,terms]
+menu:
+ docs:
+ parent: templates
+ weight: 60
+weight: 60
+toc: true
+aliases: [/templates/list/,/layout/indexes/]
+---
+
+## What is a list page template?
+
+{{< youtube 8b2YTSMdMps >}}
+
+A list page template is a template used to render multiple pieces of content in a single HTML page. The exception to this rule is the homepage, which is still a list but has its own [dedicated template][homepage].
+
+Hugo uses the term *list* in its truest sense; i.e. a sequential arrangement of material, especially in alphabetical or numerical order. Hugo uses list templates on any output HTML page where content is traditionally listed:
+
+* [Home page](/templates/homepage)
+* [Section pages](/templates/section-templates)
+* [Taxonomy pages](/templates/taxonomy-templates)
+* [Taxonomy term pages](/templates/taxonomy-templates)
+* [RSS feeds](/templates/rss)
+* [Sitemaps](/templates/sitemap-template)
+
+For template lookup order, see [Template Lookup](/templates/lookup-order/).
+
+The idea of a list page comes from the [hierarchical mental model of the web][mentalmodel] and is best demonstrated visually:
+
+[](site-hierarchy.svg)
+
- Since v0.18, [everything in Hugo is a `Page`][bepsays]. This means list pages and the homepage can have associated content files (i.e. `_index.md`) that contain page metadata (i.e., front matter) and content.
-
- This new model allows you to include list-specific front matter via `.Params` and also means that list templates (e.g., `layouts/_default/list.html`) have access to all [page variables][pagevars].
-
- {{% note %}}
- It is important to note that all `_index.md` content files will render according to a *list* template and not according to a [single page template](/templates/single-page-templates/).
- {{% /note %}}
-
- ### Example project directory
+## Add content and front matter to list pages
+
- <!-- "{{ .Content }}" pulls from the markdown content of the corresponding _index.md -->
++Add content and front matter to list pages by creating an _index.md file for `home`, `section`, `taxonomy`, and `term` pages.
+
+The following is an example of a typical Hugo project directory's content:
+
+```txt
+.
+...
+├── content
+| ├── posts
+| | ├── _index.md
+| | ├── post-01.md
+| | └── post-02.md
+| └── quote
+| | ├── quote-01.md
+| | └── quote-02.md
+...
+```
+
+Using the above example, let's assume you have the following in `content/posts/_index.md`:
+
+{{< code file=content/posts/_index.md >}}
+---
+title: My Go Journey
+date: 2017-03-23
+publishdate: 2017-03-24
+---
+
+I decided to start learning Go in March 2017.
+
+Follow my journey through this new blog.
+{{< /code >}}
+
+You can now access this `_index.md`'s' content in your list template:
+
+{{< code file=layouts/_default/list.html >}}
+{{ define "main" }}
+ <main>
+ <article>
+ <header>
+ <h1>{{ .Title }}</h1>
+ </header>
- The default behavior of Hugo is to pluralize list titles; hence the inflection of the `quote` section to "Quotes" when called with the `.Title` [page variable](/variables/page/). You can change this via the `pluralizeListTitles` directive in your [site configuration](/getting-started/configuration/).
++ <!-- "{{ .Content }}" pulls from the Markdown content of the corresponding _index.md -->
+ {{ .Content }}
+ </article>
+ <ul>
+ <!-- Ranges through content/posts/*.md -->
+ {{ range .Pages }}
+ <li>
+ <a href="{{ .RelPermalink }}">{{ .Date.Format "2006-01-02" }} | {{ .LinkTitle }}</a>
+ </li>
+ {{ end }}
+ </ul>
+ </main>
+{{ end }}
+{{< /code >}}
+
+This above will output the following HTML:
+
+{{< code file=example.com/posts/index.html >}}
+<!--top of your baseof code-->
+<main>
+ <article>
+ <header>
+ <h1>My Go Journey</h1>
+ </header>
+ <p>I decided to start learning Go in March 2017.</p>
+ <p>Follow my journey through this new blog.</p>
+ </article>
+ <ul>
+ <li><a href="/posts/post-01/">Post 1</a></li>
+ <li><a href="/posts/post-02/">Post 2</a></li>
+ </ul>
+</main>
+<!--bottom of your baseof-->
+{{< /code >}}
+
+### List pages without `_index.md`
+
+You do *not* have to create an `_index.md` file for every list page (i.e. section, taxonomy, taxonomy terms, etc) or the homepage. If Hugo does not find an `_index.md` within the respective content section when rendering a list template, the page will be created but with no `{{ .Content }}` and only the default values for `.Title` etc.
+
+Using this same `layouts/_default/list.html` template and applying it to the `quotes` section above will render the following output. Note that `quotes` does not have an `_index.md` file to pull from:
+
+{{< code file=example.com/quote/index.html >}}
+<!--baseof-->
+<main>
+ <article>
+ <header>
+ <!-- Hugo assumes that .Title is the name of the section since there is no _index.md content file from which to pull a "title:" field -->
+ <h1>Quotes</h1>
+ </header>
+ </article>
+ <ul>
+ <li><a href="https://example.org/quote/quotes-01/">Quote 1</a></li>
+ <li><a href="https://example.org/quote/quotes-02/">Quote 2</a></li>
+ </ul>
+</main>
+<!--baseof-->
+{{< /code >}}
+
+{{% note %}}
- [date]: /methods/page/date
- [weight]: /methods/page/weight
- [linkTitle]: /methods/page/linktitle
- [title]: /methods/page/title
++By default, Hugo capitalizes and pluralizes automatic list titles including section, taxonomy, and term pages. You can disable these transformations by setting [`capitalizeListTitles`] and [`pluralizeListTitles`] in your site configuration.
++
++You can change the capitalization style in your site configuration to one of `ap`, `chicago`, `go`, `firstupper`, or `none`. See [details].
++
++[`capitalizeListTitles`]: /getting-started/configuration/#capitalizelisttitles
++[`pluralizeListTitles`]: /getting-started/configuration/#pluralizelisttitles
++[details]: /getting-started/configuration/#configure-title-case
+{{% /note %}}
+
+## Example list templates
+
+### Section template
+
+This list template has been modified slightly from a template originally used in [spf13.com](https://spf13.com/). It makes use of [partial templates][partials] for the chrome of the rendered page rather than using a [base template][base]. The examples that follow also use the [content view templates][views] `li.html` or `summary.html`.
+
+{{< code file=layouts/section/posts.html >}}
+{{ partial "header.html" . }}
+{{ partial "subheader.html" . }}
+<main>
+ <div>
+ <h1>{{ .Title }}</h1>
+ <ul>
+ <!-- Renders the li.html content view for each content/posts/*.md -->
+ {{ range .Pages }}
+ {{ .Render "li" }}
+ {{ end }}
+ </ul>
+ </div>
+</main>
+{{ partial "footer.html" . }}
+{{< /code >}}
+
+### Taxonomy template
+
+{{< code file=layouts/_default/taxonomy.html >}}
+{{ define "main" }}
+<main>
+ <div>
+ <h1>{{ .Title }}</h1>
+ <!-- ranges through each of the content files associated with a particular taxonomy term and renders the summary.html content view -->
+ {{ range .Pages }}
+ {{ .Render "summary" }}
+ {{ end }}
+ </div>
+</main>
+{{ end }}
+{{< /code >}}
+
+## Sort content
+
+By default, Hugo sorts page collections by:
+
+1. Page [weight]
+2. Page [date] (descending)
+3. Page [linkTitle], falling back to page [title]
+4. Page file path if the page is backed by a file
+
- [pagevars]: /variables/page/
++[date]: /methods/page/date/
++[weight]: /methods/page/weight/
++[linkTitle]: /methods/page/linktitle/
++[title]: /methods/page/title/
+
+Change the sort order using any of the methods below.
+
+{{< list-pages-in-section path=/methods/pages filter=methods_pages_sort filterType=include titlePrefix=. omitElementIDs=true >}}
+
+## Group content
+
+Group your content by field, parameter, or date using any of the methods below.
+
+{{< list-pages-in-section path=/methods/pages filter=methods_pages_group filterType=include titlePrefix=. omitElementIDs=true >}}
+
+## Filtering and limiting lists
+
+Sometimes you only want to list a subset of the available content. A
+common is to only display posts from [main sections]
+on the blog's homepage.
+
+See the documentation on [`where`] and
+[`first`] for further details.
+
+[base]: /templates/base/
+[bepsays]: https://bepsays.com/en/2016/12/19/hugo-018/
+[directorystructure]: /getting-started/directory-structure/
+[`Format` function]: /methods/time/format/
+[front matter]: /content-management/front-matter/
+[getpage]: /methods/page/getpage/
+[homepage]: /templates/homepage/
+[mentalmodel]: https://webstyleguide.com/wsg3/3-information-architecture/3-site-structure.html
- [sitevars]: /variables/site/
- [taxlists]: /templates/taxonomy-templates/#taxonomy-list-templates
- [taxterms]: /templates/taxonomy-templates/#taxonomy-terms-templates
- [taxvars]: /variables/taxonomy/
+[partials]: /templates/partials/
+[RSS 2.0]: https://cyber.harvard.edu/rss/rss.html
+[rss]: /templates/rss/
+[sections]: /content-management/sections/
+[sectiontemps]: /templates/section-templates/
- [`where`]: /functions/collections/where
++[taxlists]: /templates/taxonomy-templates/#taxonomy-templates
++[taxterms]: /templates/taxonomy-templates/#term-templates
++[taxvars]: /methods/taxonomy/
+[views]: /templates/views/
- [main sections]: /methods/site/mainsections
- [`time.Format`]: /functions/time/format
++[`where`]: /functions/collections/where/
+[`first`]: /functions/collections/first/
++[main sections]: /methods/site/mainsections/
++[`time.Format`]: /functions/time/format/
--- /dev/null
- description: Use menu variables and methods in your templates to render a menu.
+---
+title: Menu templates
- After [defining menu entries], use [menu variables and methods] to render a menu.
++description: Create templates to render one or more menus.
+categories: [templates]
+keywords: [lists,sections,menus]
+menu:
+ docs:
+ parent: templates
+ weight: 140
+weight: 140
+toc: true
+aliases: [/templates/menus/]
+---
+
+## Overview
+
- Regardless of how you [define menu entries], an entry associated with a page has access to page variables and methods.
++After [defining menu entries], use [menu methods] to render a menu.
+
+Three factors determine how to render a menu:
+
+1. The method used to define the menu entries: [automatic], [in front matter], or [in site configuration]
+1. The menu structure: flat or nested
+1. The method used to [localize the menu entries]: site configuration or translation tables
+
+The example below handles every combination.
+
+## Example
+
+This partial template recursively "walks" a menu structure, rendering a localized, accessible nested list.
+
+{{< code file=layouts/partials/menu.html copy=true >}}
+{{- $page := .page }}
+{{- $menuID := .menuID }}
+
+{{- with index site.Menus $menuID }}
+ <nav>
+ <ul>
+ {{- partial "inline/menu/walk.html" (dict "page" $page "menuEntries" .) }}
+ </ul>
+ </nav>
+{{- end }}
+
+{{- define "partials/inline/menu/walk.html" }}
+ {{- $page := .page }}
+ {{- range .menuEntries }}
+ {{- $attrs := dict "href" .URL }}
+ {{- if $page.IsMenuCurrent .Menu . }}
+ {{- $attrs = merge $attrs (dict "class" "active" "aria-current" "page") }}
+ {{- else if $page.HasMenuCurrent .Menu .}}
+ {{- $attrs = merge $attrs (dict "class" "ancestor" "aria-current" "true") }}
+ {{- end }}
+ {{- $name := .Name }}
+ {{- with .Identifier }}
+ {{- with T . }}
+ {{- $name = . }}
+ {{- end }}
+ {{- end }}
+ <li>
+ <a
+ {{- range $k, $v := $attrs }}
+ {{- with $v }}
+ {{- printf " %s=%q" $k $v | safeHTMLAttr }}
+ {{- end }}
+ {{- end -}}
+ >{{ $name }}</a>
+ {{- with .Children }}
+ <ul>
+ {{- partial "inline/menu/walk.html" (dict "page" $page "menuEntries" .) }}
+ </ul>
+ {{- end }}
+ </li>
+ {{- end }}
+{{- end }}
+{{< /code >}}
+
+Call the partial above, passing a menu ID and the current page in context.
+
+{{< code file=layouts/_default/single.html >}}
+{{ partial "menu.html" (dict "menuID" "main" "page" .) }}
+{{ partial "menu.html" (dict "menuID" "footer" "page" .) }}
+{{< /code >}}
+
+## Page references
+
- [menu variables and methods]: /variables/menu-entry/
++Regardless of how you [define menu entries], an entry associated with a page has access to page context.
+
+This simplistic example renders a page parameter named `version` next to each entry's `name`. Code defensively using `with` or `if` to handle entries where (a) the entry points to an external resource, or (b) the `version` parameter is not defined.
+
+{{< code file=layouts/_default/single.html >}}
+{{- range site.Menus.main }}
+ <a href="{{ .URL }}">
+ {{ .Name }}
+ {{- with .Page }}
+ {{- with .Params.version -}}
+ ({{ . }})
+ {{- end }}
+ {{- end }}
+ </a>
+{{- end }}
+{{< /code >}}
+
+## Menu entry parameters
+
+When you define menu entries [in site configuration] or [in front matter], you can include a `params` key as shown in these examples:
+
+- [Menu entry defined in site configuration]
+- [Menu entry defined in front matter]
+
+This simplistic example renders a `class` attribute for each anchor element. Code defensively using `with` or `if` to handle entries where `params.class` is not defined.
+
+{{< code file=layouts/partials/menu.html >}}
+{{- range site.Menus.main }}
+ <a {{ with .Params.class -}} class="{{ . }}" {{ end -}} href="{{ .URL }}">
+ {{ .Name }}
+ </a>
+{{- end }}
+{{< /code >}}
+
+## Localize
+
+Hugo provides two methods to localize your menu entries. See [multilingual].
+
+[automatic]: /content-management/menus/#define-automatically
+[define menu entries]: /content-management/menus/
+[defining menu entries]: /content-management/menus/
+[in front matter]: /content-management/menus/#define-in-front-matter
+[in site configuration]: /content-management/menus/#define-in-site-configuration
+[localize the menu entries]: /content-management/multilingual/#menus
+[menu entry defined in front matter]: /content-management/menus/#example-front-matter
+[menu entry defined in site configuration]: /content-management/menus/#example-site-configuration
++[menu and methods]: /methods/menu/
+[multilingual]: /content-management/multilingual/#menus
--- /dev/null
- {{< datatable "config" "outputFormats" "name" "mediaType" "path" "baseName" "rel" "protocol" "isPlainText" "isHTML" "noUgly" "permalinkable" >}}
+---
+title: Custom output formats
+description: Hugo can output content in multiple formats, including calendar events, e-book formats, Google AMP, and JSON search indexes, or any custom text format.
+categories: [templates,fundamentals]
+keywords: ["amp", "outputs", "rss"]
+menu:
+ docs:
+ parent: templates
+ weight: 210
+weight: 210
+toc: true
+aliases: [/templates/outputs/,/extras/output-formats/,/content-management/custom-outputs/]
+---
+
+This page describes how to properly configure your site with the media types and output formats, as well as where to create your templates for your custom outputs.
+
+## Media types
+
+A [media type] (formerly known as a MIME type) is a two-part identifier for file formats and format contents transmitted on the internet.
+
+This is the full set of built-in media types in Hugo:
+
+{{< datatable "config" "mediaTypes" "_key" "suffixes" >}}
+
+**Note:**
+
+- It is possible to add custom media types or change the defaults; e.g., if you want to change the suffix for `text/html` to `asp`.
+- `Suffixes` are the values that will be used for URLs and file names for that media type in Hugo.
+- The `Type` is the identifier that must be used when defining new/custom `Output Formats` (see below).
+- The full set of media types will be registered in Hugo's built-in development server to make sure they are recognized by the browser.
+
+To add or modify a media type, define it in a `mediaTypes` section in your [site configuration], either for all sites or for a given language.
+
+{{< code-toggle file=hugo >}}
+[mediaTypes]
+ [mediaTypes."text/enriched"]
+ suffixes = ["enr"]
+ [mediaTypes."text/html"]
+ suffixes = ["asp"]
+{{</ code-toggle >}}
+
+The above example adds one new media type, `text/enriched`, and changes the suffix for the built-in `text/html` media type.
+
+**Note:** these media types are configured for **your output formats**. If you want to redefine one of Hugo's default output formats (e.g. `HTML`), you also need to redefine the media type. So, if you want to change the suffix of the `HTML` output format from `html` (default) to `htm`:
+
+{{< code-toggle file=hugo >}}
+[mediaTypes]
+ [mediaTypes."text/html"]
+ suffixes = ["htm"]
+
+[outputFormats]
+ [outputFormats.html]
+ mediaType = "text/html"
+{{</ code-toggle >}}
+
+{{% note %}}
+For the above to work, you also need to add an `outputs` definition in your site configuration.
+{{% /note %}}
+
+## Output format definitions
+
+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:
+
- The following is the full list of configuration options for output formats and their default values:
++{{< 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.
+- You can define new output formats or redefine built-in output formats; e.g., if you want to put `amp` pages in a different path.
+
+To add or modify an output format, define it in an `outputFormats` section in your site's [configuration file](/getting-started/configuration/), either for all sites or for a given language.
+
+{{< code-toggle file=hugo >}}
+[outputFormats.MyEnrichedFormat]
+mediaType = "text/enriched"
+baseName = "myindex"
+isPlainText = true
+protocol = "bep://"
+{{</ code-toggle >}}
+
+The above example is fictional, but if used for the homepage on a site with `baseURL` `https://example.org`, it will produce a plain text homepage with the URL `bep://example.org/myindex.enr`.
+
+### Configure output formats
+
- mediaType
- : this must match the `Type` of a defined media type.
++Use these parameters when configuring an output format:
+
- path
- : sub path to save the output files.
++baseName
++: (`string`) The base name of the published file. Default is `index`.
+
- baseName
- : the base file name for the list file names (homepage, etc.). **Default:** `index`.
++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`.
+
- rel
- : can be used to create `rel` values in `link` tags. **Default:** `alternate`.
++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`.
+
- protocol
- : will replace the "http://" or "https://" in your `baseURL` for this output format.
++[html/template]: https://pkg.go.dev/html/template
++[text/template]: https://pkg.go.dev/text/template
+
- isPlainText
- : use Go's plain text templates parser for the templates. **Default:** `false`.
++mediaType
++: (`string`) The [media type] of the published file. This must match a defined media type, either [built-in](#media-types) or custom.
+
- isHTML
- : used in situations only relevant for `HTML`-type formats; e.g., page aliases. **Default:** `false`.
++[media type]: https://en.wikipedia.org/wiki/Media_type
+
- : used to turn off ugly URLs If `uglyURLs` is set to `true` in your site. **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
- 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`.
++: (`bool`) If `true`, disables ugly URLs for this output format when `uglyURLs` is `true` in your site configuration. Default is `false`.
+
- : 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`.
++path
++: (`string`) The path to the directory containing the published files, relative to the root of the publish directory.
+
+permalinkable
- : Setting this to a non-zero value will be used as the first sort criteria.
++: (`bool`) If `true`, the [`Permalink`] and [`RelPermalink`] methods on a `Page` object return the rendering output format rather than main output 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 output 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
- Every `Page` has a [`Kind`][page_kinds] attribute, and the default Output
++: (`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
+
+A `Page` in Hugo can be rendered to multiple _output formats_ on the file
+system.
+
+### Default output formats
+
- Each `Page` has both an `.OutputFormats` (all formats, including the current) and an `.AlternativeOutputFormats` variable, the latter of which is useful for creating a `link rel` list in your site's `<head>`:
++Every `Page` has a [`Kind`] attribute, and the default Output
+Formats are set based on that.
+
+{{< code-toggle config=outputs />}}
+
+### Customizing output formats
+
+This can be changed by defining an `outputs` list of output formats in either
+the `Page` front matter or in the site configuration (either for all sites or
+per language).
+
+Example from site configuration file:
+
+{{< code-toggle file=hugo >}}
+[outputs]
+ home = ["html", "amp", "rss"]
+ page = ["html"]
+{{</ code-toggle >}}
+
+Note that in the above examples, the _output formats_ for `section`,
+`taxonomy` and `term` will stay at their default value `['html','rss']`.
+
+* The `outputs` definition is per page [`Kind`][page_kinds].
+* The names (e.g. `html`, `amp`) must match the `name` of a defined output format, and can be overridden per page in front matter.
+
+The following is an example of front matter in a content file that defines output formats for the rendered `Page`:
+
+{{< code-toggle file=content/example.md fm=true >}}
+title: Example
+outputs:
+- html
+- amp
+- json
+{{< /code-toggle >}}
+
+## List 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.
++Each `Page` object has both an [`OutputFormats`] method (all formats, including the current) and an [`AlternativeOutputFormats`] method, the latter of which is useful for creating a `link rel` list in your site's `<head>`:
++
++[`OutputFormats`]: /methods/page/outputformats
++[`AlternativeOutputFormats`]: /methods/page/alternativeoutputformats
+
+```go-html-template
+{{ range .AlternativeOutputFormats -}}
+ <link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink | safeURL }}">
+{{ end }}
+```
+
+## Link to output formats
+
- From content files, you can use the [`ref` or `relref` shortcodes](/content-management/shortcodes/#ref-and-relref):
++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.
++
++[`Permalink`]: /methods/page/permalink
++[`RelPermalink`]: /methods/page/relpermalink
+
+__from `single.json.json`:__
+```go-html-template
+{{ .RelPermalink }} → /that-page/
+{{ with .OutputFormats.Get "json" }}
+ {{ .RelPermalink }} → /that-page/index.json
+{{ end }}
+```
+
+In order for them to return the output format of the current template file instead, the given output format should have its `permalinkable` setting set to true.
+
+**Same template file as above with json output format's `permalinkable` set to true:**
+
+```go-html-template
+{{ .RelPermalink }} → /that-page/index.json
+{{ with .OutputFormats.Get "html" }}
+ {{ .RelPermalink }} → /that-page/
+{{ end }}
+```
+
- [page_kinds]: /templates/section-templates/#page-kinds
++From content files, you can use the `ref` or `relref` shortcodes:
+
+```go-html-template
+[Neat]({{</* ref "blog/neat.md" "amp" */>}})
+[Who]({{</* relref "about.md#who" "amp" */>}})
+```
+
+## Templates for your output formats
+
+Each output format requires a corresponding template conforming to the [template lookup order](/templates/lookup-order/). Hugo considers both output format and suffix when selecting a template.
+
+For example, to generate a JSON file for the home page, the template with highest specificity is `layouts/index.json.json`.
+
+Hugo will now also detect the media type and output format of partials, if possible, and use that information to decide if the partial should be parsed as a plain text template or not.
+
+Hugo will look for the name given, so you can name it whatever you want. But if you want it treated as plain text, you should use the file suffix and, if needed, the name of the Output Format. The pattern is as follows:
+
+```go-html-template
+[partial name].[OutputFormat].[suffix]
+```
+
+The partial below is a plain text template . The output format is `csv`, and since this is the only output format with the suffix `csv`, we don't need to include the output format `name`):
+
+```go-html-template
+{{ partial "mytextpartial.csv" . }}
+```
+
+[base]: /templates/base/
+[site configuration]: /getting-started/configuration/
+[lookup order]: /templates/lookup-order/
+[media type]: https://en.wikipedia.org/wiki/Media_type
+[partials]: /templates/partials/
++[`kind`]: /methods/page/kind/
--- /dev/null
- The `.Paginator` contains enough information to build a paginator interface.
+---
+title: Pagination
+description: Hugo supports pagination for your homepage, section pages, and taxonomies.
+categories: [templates]
+keywords: [lists,sections,pagination]
+menu:
+ docs:
+ parent: templates
+ weight: 100
+weight: 100
+toc: true
+aliases: [/extras/pagination,/doc/pagination/]
+---
+
+The real power of Hugo pagination shines when combined with the [`where`] function and its SQL-like operators: [`first`], [`last`], and [`after`]. You can even [order the content][lists] the way you've become used to with Hugo.
+
+## Configure pagination
+
+Pagination can be configured in your [site configuration][configuration]:
+
+paginate
+: default = `10`. This setting can be overridden within the template.
+
+paginatePath
+: default = `page`. Allows you to set a different path for your pagination pages.
+
+Setting `paginate` to a positive value will split the list pages for the homepage, sections and taxonomies into chunks of that size. But note that the generation of the pagination pages for sections, taxonomies and homepage is *lazy* --- the pages will not be created if not referenced by a `.Paginator` (see below).
+
+`paginatePath` is used to adapt the `URL` to the pages in the paginator (the default setting will produce URLs on the form `/page/1/`.
+
+## List paginator pages
+
+{{% note %}}
+Paginate a page collection in list templates for these page kinds: `home`, `section`, `taxonomy`, or `term`. You cannot paginate a page collection in a template for the `page` page kind.
+{{% /note %}}
+
+There are two ways to configure and use a `.Paginator`:
+
+1. The simplest way is just to call `.Paginator.Pages` from a template. It will contain the pages for *that page*.
+2. Select another set of pages with the available template functions and ordering options, and pass the slice to `.Paginate`, e.g.
+ * `{{ range (.Paginate ( first 50 .Pages.ByTitle )).Pages }}` or
+ * `{{ range (.Paginate .RegularPagesRecursive).Pages }}`.
+
+For a given **Page**, it's one of the options above. The `.Paginator` is static and cannot change once created.
+
+If you call `.Paginator` or `.Paginate` multiple times on the same page, you should ensure all the calls are identical. Once *either* `.Paginator` or `.Paginate` is called while generating a page, its result is cached, and any subsequent similar call will reuse the cached result. This means that any such calls which do not match the first one will not behave as written.
+
+(Remember that function arguments are eagerly evaluated, so a call like `$paginator := cond x .Paginator (.Paginate .RegularPagesRecursive)` is an example of what you should *not* do. Use `if`/`else` instead to ensure exactly one evaluation.)
+
+The global page size setting (`Paginate`) can be overridden by providing a positive integer as the last argument. The examples below will give five items per page:
+
+* `{{ range (.Paginator 5).Pages }}`
+* `{{ $paginator := .Paginate (where .Pages "Type" "posts") 5 }}`
+
+It is also possible to use the `GroupBy` functions in combination with pagination:
+
+```go-html-template
+{{ range (.Paginate (.Pages.GroupByDate "2006")).PageGroups }}
+```
+
+## Build the navigation
+
- The easiest way to add this to your pages is to include the built-in template (with `Bootstrap`-compatible styles):
++{{% note %}}
++To override Hugo's embedded pagination 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 "pagination" . }}`
++
++[`partial`]: /functions/partials/include/
++[source code]: {{% eturl pagination %}}
++{{% /note %}}
+
- [`where`]: /functions/collections/where
++The easiest way to add this to your pages is to include the embedded template:
+
+```go-html-template
+{{ template "_internal/pagination.html" . }}
+```
+
+{{% note %}}
+If you use any filters or ordering functions to create your `.Paginator` *and* you want the navigation buttons to be shown before the page listing, you must create the `.Paginator` before it's used.
+{{% /note %}}
+
+The following example shows how to create `.Paginator` before its used:
+
+```go-html-template
+{{ $paginator := .Paginate (where .Pages "Type" "posts") }}
+{{ template "_internal/pagination.html" . }}
+{{ range $paginator.Pages }}
+ {{ .Title }}
+{{ end }}
+```
+
+Without the `where` filter, the above example is even simpler:
+
+```go-html-template
+{{ template "_internal/pagination.html" . }}
+{{ range .Paginator.Pages }}
+ {{ .Title }}
+{{ end }}
+```
+
+If you want to build custom navigation, you can do so using the `.Paginator` object, which includes the following properties:
+
+PageNumber
+: The current page's number in the pager sequence
+
+URL
+: The relative URL to the current pager
+
+Pages
+: The pages in the current pager
+
+NumberOfElements
+: The number of elements on this page
+
+HasPrev
+: Whether there are page(s) before the current
+
+Prev
+: The pager for the previous page
+
+HasNext
+: Whether there are page(s) after the current
+
+Next
+: The pager for the next page
+
+First
+: The pager for the first page
+
+Last
+: The pager for the last page
+
+Pagers
+: A list of pagers that can be used to build a pagination menu
+
+PageSize
+: Size of each pager
+
+TotalPages
+: The number of pages in the paginator
+
+TotalNumberOfElements
+: The number of elements on all pages in this paginator
+
+## Additional information
+
+The pages are built on the following form (`BLANK` means no value):
+
+```txt
+[SECTION/TAXONOMY/BLANK]/index.html
+[SECTION/TAXONOMY/BLANK]/page/1/index.html => redirect to [SECTION/TAXONOMY/BLANK]/index.html
+[SECTION/TAXONOMY/BLANK]/page/2/index.html
+....
+```
+
+[`first`]: /functions/collections/first/
+[`last`]: /functions/collections/last/
+[`after`]: /functions/collections/after/
+[configuration]: /getting-started/configuration/
+[lists]: /templates/lists/
++[`where`]: /functions/collections/where/
--- /dev/null
- This means the partial will *only* be able to access those variables. The partial is isolated and *has no access to the outer scope*. From within the partial, `$.Var` is equivalent to `.Var`.
+---
+title: Partial templates
+description: Partials are smaller, context-aware components in your list and page templates that can be used economically to keep your templating DRY.
+categories: [templates]
+keywords: [lists,sections,partials]
+menu:
+ docs:
+ parent: templates
+ weight: 120
+weight: 120
+toc: true
+aliases: [/templates/partial/,/layout/chrome/,/extras/analytics/]
+---
+
+{{< youtube pjS4pOLyB7c >}}
+
+## Partial template lookup order
+
+Partial templates---like [single page templates][singletemps] and [list page templates][listtemps]---have a specific [lookup order]. However, partials are simpler in that Hugo will only check in two places:
+
+1. `layouts/partials/<PARTIALNAME>.html`
+2. `themes/<THEME>/layouts/partials/<PARTIALNAME>.html`
+
+This allows a theme's end user to copy a partial's contents into a file of the same name for [further customization][customize].
+
+## Use partials in your templates
+
+All partials for your Hugo project are located in a single `layouts/partials` directory. For better organization, you can create multiple subdirectories within `partials` as well:
+
+```txt
+layouts/
+└── partials/
+ ├── footer/
+ │ ├── scripts.html
+ │ └── site-footer.html
+ ├── head/
+ │ ├── favicons.html
+ │ ├── metadata.html
+ │ ├── prerender.html
+ │ └── twitter.html
+ └── header/
+ ├── site-header.html
+ └── site-nav.html
+```
+
+All partials are called within your templates using the following pattern:
+
+```go-html-template
+{{ partial "<PATH>/<PARTIAL>.html" . }}
+```
+
+{{% note %}}
+One of the most common mistakes with new Hugo users is failing to pass a context to the partial call. In the pattern above, note how "the dot" (`.`) is required as the second argument to give the partial context. You can read more about "the dot" in the [Hugo templating introduction](/templates/introduction/).
+{{% /note %}}
+
+{{% note %}}
+`<PARTIAL>` including `baseof` is reserved. ([#5373](https://github.com/gohugoio/hugo/issues/5373))
+{{% /note %}}
+
+As shown in the above example directory structure, you can nest your directories within `partials` for better source organization. You only need to call the nested partial's path relative to the `partials` directory:
+
+```go-html-template
+{{ partial "header/site-header.html" . }}
+{{ partial "footer/scripts.html" . }}
+```
+
+### Variable scoping
+
+The second argument in a partial call is the variable being passed down. The above examples are passing the `.`, which tells the template receiving the partial to apply the current [context][context].
+
- [partialcached]: /functions/partials/includecached
++This means the partial will *only* be able to access those variables. The partial is isolated and cannot access the outer scope. From within the partial, `$.Var` is equivalent to `.Var`.
+
+## Returning a value from a partial
+
+In addition to outputting markup, partials can be used to return a value of any type. In order to return a value, a partial must include a lone `return` statement *at the end of the partial*.
+
+### Example GetFeatured
+
+```go-html-template
+{{/* layouts/partials/GetFeatured.html */}}
+{{ return first . (where site.RegularPages "Params.featured" true) }}
+```
+
+```go-html-template
+{{/* layouts/index.html */}}
+{{ range partial "GetFeatured.html" 5 }}
+ [...]
+{{ end }}
+```
+
+### Example GetImage
+
+```go-html-template
+{{/* layouts/partials/GetImage.html */}}
+{{ $image := false }}
+{{ with .Params.gallery }}
+ {{ $image = index . 0 }}
+{{ end }}
+{{ with .Params.image }}
+ {{ $image = . }}
+{{ end }}
+{{ return $image }}
+```
+
+```go-html-template
+{{/* layouts/_default/single.html */}}
+{{ with partial "GetImage.html" . }}
+ [...]
+{{ end }}
+```
+
+{{% note %}}
+Only one `return` statement is allowed per partial file.
+{{% /note %}}
+
+## Inline partials
+
+You can also define partials inline in the template. But remember that template namespace is global, so you need to make sure that the names are unique to avoid conflicts.
+
+```go-html-template
+Value: {{ partial "my-inline-partial.html" . }}
+
+{{ define "partials/my-inline-partial.html" }}
+{{ $value := 32 }}
+{{ return $value }}
+{{ end }}
+```
+
+## Cached partials
+
+The `partialCached` template function provides significant performance gains for complex templates that don't need to be re-rendered on every invocation. See [details][partialcached].
+
+## Examples
+
+### `header.html`
+
+The following `header.html` partial template is used for [spf13.com](https://spf13.com/):
+
+{{< code file=layouts/partials/header.html >}}
+<!DOCTYPE html>
+<html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#">
+<head>
+ <meta charset="utf-8">
+
+ {{ partial "meta.html" . }}
+
+ <base href="{{ .Site.BaseURL }}">
+ <title> {{ .Title }} : spf13.com </title>
+ <link rel="canonical" href="{{ .Permalink }}">
+ {{ if .RSSLink }}<link href="{{ .RSSLink }}" rel="alternate" type="application/rss+xml" title="{{ .Title }}" />{{ end }}
+
+ {{ partial "head_includes.html" . }}
+</head>
+{{< /code >}}
+
+{{% note %}}
+The `header.html` example partial was built before the introduction of block templates to Hugo. Read more on [base templates and blocks](/templates/base/) for defining the outer chrome or shell of your master templates (i.e., your site's head, header, and footer). You can even combine blocks and partials for added flexibility.
+{{% /note %}}
+
+### `footer.html`
+
+The following `footer.html` partial template is used for [spf13.com](https://spf13.com/):
+
+{{< code file=layouts/partials/footer.html >}}
+<footer>
+ <div>
+ <p>
+ © 2013-14 Steve Francia.
+ <a href="https://creativecommons.org/licenses/by/3.0/" title="Creative Commons Attribution">Some rights reserved</a>;
+ please attribute properly and link back.
+ </p>
+ </div>
+</footer>
+{{< /code >}}
+
+[context]: /templates/introduction/
+[customize]: /hugo-modules/theme-components/
+[listtemps]: /templates/lists/
+[lookup order]: /templates/lookup-order/
++[partialcached]: /functions/partials/includecached/
+[singletemps]: /templates/single-page-templates/
+[themes]: /themes/
--- /dev/null
- By default, Hugo generates robots.txt using an [internal template][internal].
+---
+title: Robots.txt file
+linkTitle: Robots.txt
+description: Hugo can generate a customized robots.txt in the same way as any other template.
+categories: [templates]
+keywords: [robots,search engines]
+menu:
+ docs:
+ parent: templates
+ weight: 230
+weight: 230
+aliases: [/extras/robots-txt/]
+---
+
+To generate a robots.txt file from a template, change the [site configuration]:
+
+{{< code-toggle file=hugo >}}
+enableRobotsTXT = true
+{{< /code-toggle >}}
+
- [internal]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/robots.txt
++By default, Hugo generates robots.txt using an [embedded template].
++
++[embedded template]: {{% eturl robots %}}
+
+```text
+User-agent: *
+```
+
+Search engines that honor the Robots Exclusion Protocol will interpret this as permission to crawl everything on the site.
+
+## robots.txt template lookup order
+
+You may overwrite the internal template with a custom template. Hugo selects the template using this lookup order:
+
+1. `/layouts/robots.txt`
+2. `/themes/<THEME>/layouts/robots.txt`
+
+## robots.txt template example
+
+{{< code file=layouts/robots.txt >}}
+User-agent: *
+{{ range .Pages }}
+Disallow: {{ .RelPermalink }}
+{{ end }}
+{{< /code >}}
+
+This template creates a robots.txt file with a `Disallow` directive for each page on the site. Search engines that honor the Robots Exclusion Protocol will not crawl any page on the site.
+
+{{% note %}}
+To create a robots.txt file without using a template:
+
+1. Set `enableRobotsTXT` to `false` in the site configuration.
+2. Create a robots.txt file in the `static` directory.
+
+Remember that Hugo copies everything in the [static directory][static] to the root of `publishDir` (typically `public`) when you build your site.
+
+[static]: /getting-started/directory-structure/
+{{% /note %}}
+
+[site configuration]: /getting-started/configuration/
--- /dev/null
- description: Use the built-in RSS template, or create your own.
+---
+title: RSS templates
- Override Hugo's [built-in RSS template] by creating one or more of your own, following the naming conventions as shown in the [template lookup order table].
++description: Use the embedded RSS template, or create your own.
+categories: [templates]
+keywords: [rss,xml,templates]
+menu:
+ docs:
+ parent: templates
+ weight: 160
+weight: 160
+toc: true
+---
+
+## Configuration
+
+By default, when you build your site, Hugo generates RSS feeds for home, section, taxonomy, and term pages. Control feed generation in your site configuration. For example, to generate feeds for home and section pages, but not for taxonomy and term pages:
+
+{{< code-toggle file=hugo >}}
+[outputs]
+home = ['html', 'rss']
+section = ['html', 'rss']
+taxonomy = ['html']
+term = ['html']
+{{< /code-toggle >}}
+
+To disable feed generation for all [page kinds]:
+
++[page kinds]: /getting-started/glossary/#page-kind
++
+{{< code-toggle file=hugo >}}
+disableKinds = ['rss']
+{{< /code-toggle >}}
+
+By default, the number of items in each feed is unlimited. Change this as needed in your site configuration:
+
+{{< code-toggle file=hugo >}}
+[services.rss]
+limit = 42
+{{< /code-toggle >}}
+
+Set `limit` to `-1` to generate an unlimited number of items per feed.
+
+The built-in RSS template will render the following values, if present, from your site configuration:
+
+{{< code-toggle file=hugo >}}
+copyright = '© 2023 ABC Widgets, Inc.'
+[params.author]
+name = 'John Doe'
+email = 'jdoe@example.org'
+{{< /code-toggle >}}
+
+## Include feed reference
+
+To include a feed reference in the `head` element of your rendered pages, place this within the `head` element of your templates:
+
+```go-html-template
+{{ with .OutputFormats.Get "rss" -}}
+ {{ printf `<link rel=%q type=%q href=%q title=%q>` .Rel .MediaType.Type .Permalink site.Title | safeHTML }}
+{{ end }}
+```
+
+Hugo will render this to:
+
+```html
+<link rel="alternate" type="application/rss+xml" href="https://example.org/index.xml" title="ABC Widgets">
+```
+
+## Custom templates
+
- [built-in RSS template]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/rss.xml
- [page kinds]: /getting-started/glossary/#page-kind
- [template lookup order table]: #template-lookup-order
-
++Override Hugo's [embedded RSS template] by creating one or more of your own, following the naming conventions as shown in the [template lookup order].
++
++[embedded RSS template]: {{% eturl rss %}}
++[template lookup order]: #template-lookup-order
+
+For example, to use different templates for home, section, taxonomy, and term pages:
+
+```text
+layouts/
+└── _default/
+ ├── home.rss.xml
+ ├── section.rss.xml
+ ├── taxonomy.rss.xml
+ └── term.rss.xml
+```
+
+RSS templates receive the `.Page` and `.Site` objects in context.
+
+## Template lookup order
+
+The table below shows the RSS template lookup order for the different page kinds. The first listing shows the lookup order when running with a theme (`demoTheme`).
+
+{{< datatable-filtered "output" "layouts" "OutputFormat == rss" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
--- /dev/null
- description: Templates used for section pages are **lists** and therefore have all the variables and methods available to list pages.
+---
+title: Section page templates
+linkTitle: Section templates
- ## Page kinds
-
- Every `Page` in Hugo has a `.Kind` attribute.
-
- {{% include "content-management/_common/page-kinds.md" %}}
-
- ## `.Site.GetPage` with sections
-
- `Kind` can easily be combined with the [`where`] function in your templates to create kind-specific lists of content. This method is ideal for creating lists, but there are times where you may want to fetch just the index page of a single section via the section's path.
-
- The [`.GetPage` function][getpage] looks up an index page of a given `Kind` and `path`.
-
- You can call `.Site.GetPage` with two arguments: `kind` (one of the valid values
- of `Kind` from above) and `kind value`.
-
- Examples:
-
- - `{{ .Site.GetPage "section" "posts" }}`
- - `{{ .Site.GetPage "page" "search" }}`
-
++description: Use section templates to list members of a section.
+categories: [templates]
+keywords: [lists,sections,templates]
+menu:
+ docs:
+ parent: templates
+ weight: 80
+weight: 80
+toc: true
+aliases: [/templates/sections/]
+---
+
+## Add content and front matter to section templates
+
+To effectively leverage section page templates, you should first understand Hugo's [content organization](/content-management/organization/) and, specifically, the purpose of `_index.md` for adding content and front matter to section and other list pages.
+
+## Section template lookup order
+
+See [Template Lookup](/templates/lookup-order/).
+
- │ ├── _index.md # "title: My Hugo Blog" in the front matter
+## Example: creating a default section template
+
+{{< code file=layouts/_default/section.html >}}
+{{ define "main" }}
+ <main>
+ {{ .Content }}
+ <ul class="contents">
+ {{ range .Paginator.Pages }}
+ <li>{{ .Title }}
+ <div>
+ {{ partial "summary.html" . }}
+ </div>
+ </li>
+ {{ end }}
+ </ul>
+ {{ partial "pagination.html" . }}
+ </main>
+{{ end }}
+{{< /code >}}
+
+### Example: using `.Site.GetPage`
+
+The `.Site.GetPage` example that follows assumes the following project directory structure:
+
+```txt
+.
+└── content
+ ├── blog
- └── events #Note there is no _index.md file in "events"
++ │ ├── _index.md <-- title: My Hugo Blog
+ │ ├── post-1.md
+ │ ├── post-2.md
+ │ └── post-3.md
- <h1>{{ with .Site.GetPage "section" "blog" }}{{ .Title }}{{ end }}</h1>
++ └── events
+ ├── event-1.md
+ └── event-2.md
+```
+
+`.Site.GetPage` will return `nil` if no `_index.md` page is found. Therefore, if `content/blog/_index.md` does not exist, the template will output the section name:
+
+```go-html-template
- <h1>{{ with .Site.GetPage "section" "events" }}{{ .Title }}{{ end }}</h1>
++<h1>{{ with .Site.GetPage "/blog" }}{{ .Title }}{{ end }}</h1>
+```
+
+Since `blog` has a section index page with front matter at `content/blog/_index.md`, the above code will return the following result:
+
+```html
+<h1>My Hugo Blog</h1>
+```
+
+If we try the same code with the `events` section, however, Hugo will default to the section title because there is no `content/events/_index.md` from which to pull content and front matter:
+
+```go-html-template
- [getpage]: /methods/page/getpage
++<h1>{{ with .Site.GetPage "/events" }}{{ .Title }}{{ end }}</h1>
+```
+
+Which then returns the following:
+
+```html
+<h1>Events</h1>
+```
+
+[contentorg]: /content-management/organization/
- [`where`]: /functions/collections/where
++[getpage]: /methods/page/getpage/
+[lists]: /templates/lists/
+[lookup]: /templates/lookup-order/
++[`where`]: /functions/collections/where/
+[sections]: /content-management/sections/
--- /dev/null
- description: You can extend Hugo's built-in shortcodes by creating your own using the same templating syntax as that for single and list pages.
+---
+title: Create your own shortcodes
+linkTitle: Shortcode templates
- Hugo also ships with built-in shortcodes for common use cases. (See [Content Management: Shortcodes](/content-management/shortcodes/).)
++description: You can extend Hugo's embedded shortcodes by creating your own using the same templating syntax as that for single and list pages.
+categories: [templates]
+keywords: [shortcodes,templates]
+menu:
+ docs:
+ parent: templates
+ weight: 130
+weight: 130
+aliases: [/functions/get]
+toc: true
+---
+
+Shortcodes are a means to consolidate templating into small, reusable snippets that you can embed directly inside your content.
+
+{{% note %}}
- Hugo's built-in shortcodes cover many common, but not all, use cases. Luckily, Hugo provides the ability to easily create custom shortcodes to meet your website's needs.
++Hugo also ships with embedded shortcodes for common use cases. (See [Content Management: Shortcodes](/content-management/shortcodes/).)
+{{% /note %}}
+
+## Create custom shortcodes
+
- To create a shortcode, place an HTML template in the `layouts/shortcodes` directory of your [source organization]. Consider the file name carefully since the shortcode name will mirror that of the file but without the `.html` extension. For example, `layouts/shortcodes/myshortcode.html` will be called with either `{{</* myshortcode /*/>}}` or `{{%/* myshortcode /*/%}}`.
++Hugo's embedded shortcodes cover many common, but not all, use cases. Luckily, Hugo provides the ability to easily create custom shortcodes to meet your website's needs.
+
+{{< youtube Eu4zSaKOY4A >}}
+
+### File location
+
- ### Positional vs. named parameters
++To create a shortcode, place an HTML template in the `layouts/shortcodes` directory. Consider the file name carefully since the shortcode name will mirror that of the file but without the `.html` extension. For example, `layouts/shortcodes/myshortcode.html` will be called with either `{{</* myshortcode /*/>}}` or `{{%/* myshortcode /*/%}}`.
+
+You can organize your shortcodes in subdirectories, e.g. in `layouts/shortcodes/boxes`. These shortcodes would then be accessible with their relative path, e.g:
+
+```go-html-template
+{{</* boxes/square */>}}
+```
+
+Note the forward slash.
+
+### Shortcode template lookup order
+
+Shortcode templates have a simple [lookup order]:
+
+1. `/layouts/shortcodes/<SHORTCODE>.html`
+2. `/themes/<THEME>/layouts/shortcodes/<SHORTCODE>.html`
+
- You can create shortcodes using the following types of parameters:
++### Positional vs. named arguments
+
- * Positional parameters
- * Named parameters
- * Positional *or* named parameters (i.e, "flexible")
++You can create shortcodes using the following types of arguments:
+
- In shortcodes with positional parameters, the order of the parameters is important. If a shortcode has a single required value (e.g., the `youtube` shortcode below), positional parameters work very well and require less typing from content authors.
++* Positional arguments
++* Named arguments
++* Positional *or* named arguments
+
- For more complex layouts with multiple or optional parameters, named parameters work best. While less terse, named parameters require less memorization from a content author and can be added in a shortcode declaration in any order.
++In shortcodes with positional arguments, the order of the arguments is important. If a shortcode has a single required value, positional arguments require less typing from content authors.
+
- Allowing both types of parameters (i.e., a "flexible" shortcode) is useful for complex layouts where you want to set default values that can be easily overridden by users.
++For more complex layouts with multiple or optional arguments, named arguments work best. While less terse, named arguments require less memorization from a content author and can be added in a shortcode declaration in any order.
+
- ### Access parameters
++Allowing both types of arguments is useful for complex layouts where you want to set default values that can be easily overridden by users.
+
- All shortcode parameters can be accessed via the `.Get` method. Whether you pass a key (i.e., string) or a number to the `.Get` method depends on whether you are accessing a named or positional parameter, respectively.
++### Access arguments
+
- To access a parameter by name, use the `.Get` method followed by the named parameter as a quoted string:
++All shortcode arguments can be accessed via the `.Get` method. Whether you pass a string or a number to the `.Get` method depends on whether you are accessing a named or positional argument, respectively.
+
- To access a parameter by position, use the `.Get` followed by a numeric position, keeping in mind that positional parameters are zero-indexed:
++To access an argument by name, use the `.Get` method followed by the named argument as a quoted string:
+
+```go-html-template
+{{ .Get "class" }}
+```
+
- `with` is great when the output depends on a parameter being set:
++To access an argument by position, use the `.Get` followed by a numeric position, keeping in mind that positional arguments are zero-indexed:
+
+```go-html-template
+{{ .Get 0 }}
+```
+
+For the second position, you would just use:
+
+```go-html-template
+{{ .Get 1 }}
+```
+
- `.Get` can also be used to check if a parameter has been provided. This is
++`with` is great when the output depends on a argument being set:
+
+```go-html-template
+{{ with .Get "class" }} class="{{ . }}"{{ end }}
+```
+
- If a closing shortcode is used, the `.Inner` variable will be populated with the content between the opening and closing shortcodes. To check if `.Inner` contains anything other than white space:
++`.Get` can also be used to check if a argument has been provided. This is
+most helpful when the condition depends on either of the values, or both:
+
+```go-html-template
+{{ if or (.Get "title") (.Get "alt") }} alt="{{ with .Get "alt" }}{{ . }}{{ else }}{{ .Get "title" }}{{ end }}"{{ end }}
+```
+
+#### `.Inner`
+
- A shortcode with content declared via the `.Inner` variable can also be declared without the content and without the closing tag by using the self-closing syntax:
++The `.Inner` method returns the content between the opening and closing shortcode tags. To check if `.Inner` returns anything other than whitespace:
+
+```go-html-template
+{{ if strings.ContainsNonSpace .Inner }}
+ Inner is not empty
+{{ end }}
+```
+
- {{% note %}}
- Any shortcode that refers to `.Inner` must be closed or self-closed.
-
++{{% note %}}
++Any shortcode that calls the `.Inner` method must be closed or self-closed. To call a shortcode using the self-closing sytax
+
+```go-html-template
+{{</* innershortcode /*/>}}
+```
+
- The `.Params` variable in shortcodes contains the list parameters passed to shortcode for more complicated use cases. You can also access higher-scoped parameters with the following logic:
+{{% /note %}}
+
+#### `.Params`
+
- : these are the parameters passed directly into the shortcode declaration (e.g., a YouTube video ID)
++The `.Params` method in shortcodes returns the arguments passed to the shortcode for more complicated use cases. You can also access higher-scoped arguments with the following logic:
+
+$.Params
- $.Page.Site.Params
- : refers to global variables as defined in your [site's configuration file][config].
++: these are the arguments passed directly into the shortcode declaration (e.g., a YouTube video ID)
+
+$.Page.Params
+: refers to the page's parameters; the "page" in this case refers to the content file in which the shortcode is declared (e.g., a `shortcode_color` field in a content's front matter could be accessed via `$.Page.Params.shortcode_color`).
+
- The `.IsNamedParams` variable checks whether the shortcode declaration uses named parameters and returns a boolean value.
++$.Site.Params
++: refers to parameters defined in your site configuration.
+
+#### `.IsNamedParams`
+
- For example, you could create an `image` shortcode that can take either a `src` named parameter or the first positional parameter, depending on the preference of the content's author. Let's assume the `image` shortcode is called as follows:
++The `.IsNamedParams` method checks whether the shortcode declaration uses named arguments and returns a boolean value.
+
- <img src="{{ .Get "src" }}" alt="">
++For example, you could create an `image` shortcode that can take either a `src` named argument or the first positional argument, depending on the preference of the content's author. Let's assume the `image` shortcode is called as follows:
+
+```go-html-template
+{{</* image src="images/my-image.jpg" */>}}
+```
+
+You could then include the following as part of your shortcode templating:
+
+```go-html-template
+{{ if .IsNamedParams }}
- <img src="{{ .Get 0 }}" alt="">
++ <img src="{{ .Get "src" }}" alt="">
+{{ else }}
- While you can create shortcode templates that accept both positional and named parameters, you *cannot* declare shortcodes in content with a mix of parameter types. Therefore, a shortcode declared like `{{</* image src="images/my-image.jpg" "This is my alt text" */>}}` will return an error.
++ <img src="{{ .Get 0 }}" alt="">
+{{ end }}
+```
+
+See the [example Vimeo shortcode][vimeoexample] below for `.IsNamedParams` in action.
+
+{{% note %}}
- You can also use the variable `.Page` to access all the normal [page variables][pagevars].
-
- Shortcodes can also be nested. In a nested shortcode, you can access the parent shortcode context with the [`.Parent`] shortcode method. This can be very useful for inheritance of common shortcode parameters from the root.
++While you can create shortcode templates that accept both positional and named arguments, you *cannot* declare shortcodes in content with a mix of argument types. Therefore, a shortcode declared like `{{</* image src="images/my-image.jpg" "This is my alt text" */>}}` will return an error.
+{{% /note %}}
+
- You can check if a specific shortcode is used on a page by calling `.HasShortcode` in that page template, providing the name of the shortcode. This is sometimes useful when you want to include specific scripts or styles in the header that are only used by that shortcode.
++Shortcodes can also be nested. In a nested shortcode, you can access the parent shortcode context with the [`.Parent`] shortcode method. This can be very useful for inheritance from the root.
+
+### Checking for existence
+
- Embedded videos are a common addition to Markdown content that can quickly become unsightly. The following is the code used by [Hugo's built-in YouTube shortcode][youtubeshortcode]:
++You can check if a specific shortcode is used on a page by calling `.HasShortcode` in that page template, providing the name of the shortcode. This is useful when you want to include specific scripts or styles in the header that are only used by that shortcode.
+
+## Custom shortcode examples
+
+The following are examples of the different types of shortcodes you can create via shortcode template files in `/layouts/shortcodes`.
+
+### Single-word example: `year`
+
+Let's assume you would like to keep mentions of your copyright year current in your content files without having to continually review your Markdown. Your goal is to be able to call the shortcode as follows:
+
+```go-html-template
+{{</* year */>}}
+```
+
+{{< code file=layouts/shortcodes/year.html >}}
+{{ now.Format "2006" }}
+{{< /code >}}
+
+### Single positional example: `youtube`
+
- Hugo's [`.Parent`] shortcode method provides access to the parent shortcode context when the shortcode in question is called within the context of a *parent* shortcode. This provides an inheritance model for common shortcode parameters.
++Embedded videos are a common addition to Markdown content. The following is the code used by [Hugo's built-in YouTube shortcode][youtubeshortcode]:
+
+```go-html-template
+{{</* youtube 09jf3ow9jfw */>}}
+```
+
+Would load the template at `/layouts/shortcodes/youtube.html`:
+
+{{< code file=layouts/shortcodes/youtube.html >}}
+<div class="embed video-player">
+<iframe class="youtube-player" type="text/html" width="640" height="385" src="https://www.youtube.com/embed/{{ index .Params 0 }}" allowfullscreen frameborder="0">
+</iframe>
+</div>
+{{< /code >}}
+
+{{< code file=youtube-embed.html >}}
+<div class="embed video-player">
+ <iframe class="youtube-player" type="text/html"
+ width="640" height="385"
+ src="https://www.youtube.com/embed/09jf3ow9jfw"
+ allowfullscreen frameborder="0">
+ </iframe>
+</div>
+{{< /code >}}
+
+### Single named example: `image`
+
+Let's say you want to create your own `img` shortcode rather than use Hugo's built-in [`figure` shortcode][figure]. Your goal is to be able to call the shortcode as follows in your content files:
+
+{{< code file=content-image.md >}}
+{{</* img src="/media/spf13.jpg" title="Steve Francia" */>}}
+{{< /code >}}
+
+You have created the shortcode at `/layouts/shortcodes/img.html`, which loads the following shortcode template:
+
+{{< code file=layouts/shortcodes/img.html >}}
+<!-- image -->
+<figure {{ with .Get "class" }}class="{{ . }}"{{ end }}>
+ {{ with .Get "link" }}<a href="{{ . }}">{{ end }}
+ <img src="{{ .Get "src" }}" {{ if or (.Get "alt") (.Get "caption") }}alt="{{ with .Get "alt" }}{{ . }}{{ else }}{{ .Get "caption" }}{{ end }}"{{ end }} />
+ {{ if .Get "link" }}</a>{{ end }}
+ {{ if or (or (.Get "title") (.Get "caption")) (.Get "attr") }}
+ <figcaption>{{ if isset .Params "title" }}
+ <h4>{{ .Get "title" }}</h4>{{ end }}
+ {{ if or (.Get "caption") (.Get "attr") }}<p>
+ {{ .Get "caption" }}
+ {{ with .Get "attrlink" }}<a href="{{ . }}"> {{ end }}
+ {{ .Get "attr" }}
+ {{ if .Get "attrlink" }}</a> {{ end }}
+ </p> {{ end }}
+ </figcaption>
+ {{ end }}
+</figure>
+<!-- image -->
+{{< /code >}}
+
+Would be rendered as:
+
+{{< code file=img-output.html >}}
+<figure>
+ <img src="/media/spf13.jpg" />
+ <figcaption>
+ <h4>Steve Francia</h4>
+ </figcaption>
+</figure>
+{{< /code >}}
+
+### Single flexible example: `vimeo`
+
+```go-html-template
+{{</* vimeo 49718712 */>}}
+{{</* vimeo id="49718712" class="flex-video" */>}}
+```
+
+Would load the template found at `/layouts/shortcodes/vimeo.html`:
+
+{{< code file=layouts/shortcodes/vimeo.html >}}
+{{ if .IsNamedParams }}
+ <div class="{{ if .Get "class" }}{{ .Get "class" }}{{ else }}vimeo-container{{ end }}">
+ <iframe src="https://player.vimeo.com/video/{{ .Get "id" }}" allowfullscreen></iframe>
+ </div>
+{{ else }}
+ <div class="{{ if len .Params | eq 2 }}{{ .Get 1 }}{{ else }}vimeo-container{{ end }}">
+ <iframe src="https://player.vimeo.com/video/{{ .Get 0 }}" allowfullscreen></iframe>
+ </div>
+{{ end }}
+{{< /code >}}
+
+Would be rendered as:
+
+{{< code file=vimeo-iframes.html >}}
+<div class="vimeo-container">
+ <iframe src="https://player.vimeo.com/video/49718712" allowfullscreen></iframe>
+</div>
+<div class="flex-video">
+ <iframe src="https://player.vimeo.com/video/49718712" allowfullscreen></iframe>
+</div>
+{{< /code >}}
+
+### Paired example: `highlight`
+
+The following is taken from `highlight`, which is a [built-in shortcode] that ships with Hugo.
+
+{{< code file=highlight-example.md >}}
+{{</* highlight html */>}}
+ <html>
+ <body> This HTML </body>
+ </html>
+{{</* /highlight */>}}
+{{< /code >}}
+
+The template for the `highlight` shortcode uses the following code, which is already included in Hugo:
+
+```go-html-template
+{{ .Get 0 | highlight .Inner }}
+```
+
+The rendered output of the HTML example code block will be as follows:
+
+{{< code file=syntax-highlighted.html >}}
+<div class="highlight" style="background: #272822"><pre style="line-height: 125%"><span style="color: #f92672"><html></span>
+ <span style="color: #f92672"><body></span> This HTML <span style="color: #f92672"></body></span>
+<span style="color: #f92672"></html></span>
+</pre></div>
+{{< /code >}}
+
+### Nested shortcode: image gallery
+
- The following example is contrived but demonstrates the concept. Assume you have a `gallery` shortcode that expects one named `class` parameter:
++Hugo's [`.Parent`] shortcode method provides access to the parent shortcode context when the shortcode in question is called within the context of a parent shortcode. This provides an inheritance model.
+
- You also have an `img` shortcode with a single named `src` parameter that you want to call inside of `gallery` and other shortcodes, so that the parent defines the context of each `img`:
++The following example is contrived but demonstrates the concept. Assume you have a `gallery` shortcode that expects one named `class` argument:
+
+{{< code file=layouts/shortcodes/gallery.html >}}
+<div class="{{ .Get "class" }}">
+ {{ .Inner }}
+</div>
+{{< /code >}}
+
- Use the [errorf](/functions/fmt/errorf) template function and [`.Position`] shortcode method to get useful error messages in shortcodes:
++You also have an `img` shortcode with a single named `src` argument that you want to call inside of `gallery` and other shortcodes, so that the parent defines the context of each `img`:
+
+{{< code file=layouts/shortcodes/img.html >}}
+{{- $src := .Get "src" -}}
+{{- with .Parent -}}
+ <img src="{{ $src }}" class="{{ .Get "class" }}-image">
+{{- else -}}
+ <img src="{{ $src }}">
+{{- end -}}
+{{< /code >}}
+
+You can then call your shortcode in your content as follows:
+
+```go-html-template
+{{</* gallery class="content-gallery" */>}}
+ {{</* img src="/images/one.jpg" */>}}
+ {{</* img src="/images/two.jpg" */>}}
+{{</* /gallery */>}}
+{{</* img src="/images/three.jpg" */>}}
+```
+
+This will output the following HTML. Note how the first two `img` shortcodes inherit the `class` value of `content-gallery` set with the call to the parent `gallery`, whereas the third `img` only uses `src`:
+
+```html
+<div class="content-gallery">
+ <img src="/images/one.jpg" class="content-gallery-image">
+ <img src="/images/two.jpg" class="content-gallery-image">
+</div>
+<img src="/images/three.jpg">
+```
+
+## Error handling in shortcodes
+
- ```sh
++Use the [`errorf`] template function with the [`Name`] and [`Position`] shortcode methods to generate useful error messages:
+
- {{ errorf "missing value for parameter 'name': %s" .Position }}
++{{< code file=layouts/shortcodes/greeting.html >}}
+{{ with .Get "name" }}
++ <p>Hello, my name is {{ . }}.</p>
+{{ else }}
- ```
++ {{ errorf "The %q shortcode requires a 'name' argument. See %s" .Name .Position }}
+{{ end }}
- When the above fails, you will see an `ERROR` log similar to the below:
++{{< /code >}}
+
- ERROR 2018/11/07 10:05:55 missing value for parameter name: "/Users/bep/dev/go/gohugoio/hugo/docs/content/en/variables/shortcodes.md:32:1"
++When the above fails, you will see an `ERROR` message such as:
+
+```sh
- Note that an inline shortcode's inner content is parsed and executed as a Go text template with the same context as a regular shortcode template.
++ERROR The "greeting" shortcode requires a 'name' argument. See "/home/user/project/content/_index.md:12:1"
+```
+
+## Inline shortcodes
+
+You can also implement your shortcodes inline -- e.g. where you use them in the content file. This can be useful for scripting that you only need in one place.
+
+This feature is disabled by default, but can be enabled in your site configuration:
+
+{{< code-toggle file=hugo >}}
+[security]
+enableInlineShortcodes = true
+{{< /code-toggle >}}
+
+It is disabled by default for security reasons. The security model used by Hugo's template handling assumes that template authors are trusted, but that the content files are not, so the templates are injection-safe from malformed input data. But in most situations you have full control over the content, too, and then `enableInlineShortcodes = true` would be considered safe. But it's something to be aware of: It allows ad-hoc [Go Text templates](https://golang.org/pkg/text/template/) to be executed from the content files.
+
+And once enabled, you can do this in your content files:
+
+ ```go-html-template
+ {{</* time.inline */>}}{{ now }}{{</* /time.inline */>}}
+ ```
+
+The above will print the current date and time.
+
- The same inline shortcode can be reused later in the same content file, with different parameters if needed, using the self-closing syntax:
++Note that an inline shortcode's inner content is parsed and executed as a Go text template with the same context as a regular shortcode template.
+
+This means that the current page can be accessed via `.Page.Title` etc. This also means that there are no concept of "nested inline shortcodes".
+
- [basic content files]: /content-management/formats/
++The same inline shortcode can be reused later in the same content file, with different arguments if needed, using the self-closing syntax:
+
+ ```go-html-template
+{{</* time.inline /*/>}}
+```
+
- [config]: /getting-started/configuration/
- [Content Management: Shortcodes]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes
- [source organization]: /getting-started/directory-structure/
- [docsshortcodes]: https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes
++[`.Parent`]: /methods/shortcode/parent/
++[`errorf`]: /functions/fmt/errorf/
++[`Name`]: /methods/shortcode/name/
++[`Position`]: /methods/shortcode/position/
+[built-in shortcode]: /content-management/shortcodes/
- [hugosc]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes
+[figure]: /content-management/shortcodes/#figure
- [pagevars]: /variables/page/
- [`.Parent`]: /methods/shortcode/parent/
- [`.Position`]: /methods/shortcode/position/
- [spfscs]: https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes
+[lookup order]: /templates/lookup-order/
++[source organization]: /getting-started/directory-structure/
+[vimeoexample]: #single-flexible-example-vimeo
+[youtubeshortcode]: /content-management/shortcodes/#youtube
--- /dev/null
- Content pages are of the type `page` and will therefore have all the [page variables][pagevars] and [site variables] available to use in their templates.
-
- ### `posts/single.html`
-
- This single page template makes use of Hugo [base templates], the [`.Format` function] for dates, the [`.WordCount` page variable][pagevars], and ranges through the single content's specific [taxonomies][pagetaxonomy]. [`with`] is also used to check whether the taxonomies are set in the front matter.
-
+---
+title: Single page templates
+description: The primary view of content in Hugo is the single view. Hugo will render every Markdown file provided with a corresponding single template.
+categories: [templates]
+keywords: [page, templates]
+menu:
+ docs:
+ parent: templates
+ weight: 50
+weight: 50
+toc: true
+aliases: [/layout/content/]
+---
+
+## Single page template lookup order
+
+See [Template Lookup](/templates/lookup-order/).
+
+## Example single page templates
+
- [pagevars]: /variables/page/
+{{< code file=layouts/posts/single.html >}}
+{{ define "main" }}
+ <section id="main">
+ <h1 id="title">{{ .Title }}</h1>
+ <div>
+ <article id="content">
+ {{ .Content }}
+ </article>
+ </div>
+ </section>
+ <aside id="meta">
+ <div>
+ <section>
+ <h4 id="date"> {{ .Date.Format "Mon Jan 2, 2006" }} </h4>
+ <h5 id="wordcount"> {{ .WordCount }} Words</h5>
+ </section>
+ {{ with .GetTerms "topics" }}
+ <ul id="topics">
+ {{ range . }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+ {{ end }}
+ {{ with .GetTerms "tags" }}
+ <ul id="tags">
+ {{ range . }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+ {{ end }}
+ </div>
+ <div>
+ {{ with .PrevInSection }}
+ <a class="previous" href="{{ .RelPermalink }}"> {{ .LinkTitle }}</a>
+ {{ end }}
+ {{ with .NextInSection }}
+ <a class="next" href="{{ .RelPermalink }}"> {{ .LinkTitle }}</a>
+ {{ end }}
+ </div>
+ </aside>
+{{ end }}
+{{< /code >}}
+
+To easily generate new instances of a content type (e.g., new `.md` files in a section like `project/`) with preconfigured front matter, use [content archetypes][archetypes].
+
+[archetypes]: /content-management/archetypes/
+[base templates]: /templates/base/
+[content type]: /content-management/types/
+[directory structure]: /getting-started/directory-structure/
+[dry]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
+[`.format` function]: /methods/time/format/
+[front matter]: /content-management/front-matter/
+[pagetaxonomy]: /templates/taxonomy-templates/#list-terms-assigned-to-a-page
- [site variables]: /variables/site/
+[partials]: /templates/partials/
+[section]: /content-management/sections/
+[spf13]: https://spf13.com/
+[`with`]: /functions/go-template/with/
--- /dev/null
- Hugo's built-in sitemap templates conform to v0.9 of the [sitemap protocol].
+---
+title: Sitemap templates
+description: Hugo provides built-in sitemap templates.
+categories: [templates]
+keywords: [sitemap,xml,templates]
+menu:
+ docs:
+ parent: templates
+ weight: 170
+weight: 170
+toc: true
+aliases: [/layout/sitemap/,/templates/sitemap/]
+---
+
+## Overview
+
- With a monolingual project, Hugo generates a sitemap.xml file in the root of the [`publishDir`] using the built-in [sitemap.xml] template.
++Hugo's embedded sitemap templates conform to v0.9 of the [sitemap protocol].
+
- - A sitemap.xml file in the root of each site (language) using the built-in [sitemap.xml] template
- - A sitemap.xml file in the root of the [`publishDir`] using the built-in [sitemapindex.xml] template
++With a monolingual project, Hugo generates a sitemap.xml file in the root of the [`publishDir`] using the [embedded sitemap template].
+
+With a multilingual project, Hugo generates:
+
- Set the default values for [change frequency] and [priority], and the name of the generated file, in your site configuration.
++- A sitemap.xml file in the root of each site (language) using the [embedded sitemap template]
++- A sitemap.xml file in the root of the [`publishDir`] using the [embedded sitemapindex template]
++
++[embedded sitemap template]: {{% eturl sitemap %}}
++[embedded sitemapindex template]: {{% eturl sitemapindex %}}
+
+## Configuration
+
- : 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).
++These are the default sitemap configuration values. They apply to all pages unless overridden in front matter.
+
+{{< code-toggle config=sitemap />}}
+
+changefreq
- : The name of the generated file. Default is `sitemap.xml`.
++: (`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).
++
++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.
+
+filename
- : 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).
++: (`string`) The name of the generated file. Default is `sitemap.xml`.
+
+priority
- [change frequency]: <https://www.sitemaps.org/protocol.html#changefreqdef>
- [priority]: <https://www.sitemaps.org/protocol.html#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).
+
+## Override default values
+
+Override the default values for a given page in front matter.
+
+{{< code-toggle file=news.md fm=true >}}
+title = 'News'
+[sitemap]
+ changefreq = 'weekly'
++ disable = true
+ priority = 0.8
+{{</ code-toggle >}}
+
+## Override built-in templates
+
+To override the built-in sitemap.xml template, create a new file in either of these locations:
+
+- layouts/sitemap.xml
+- layouts/_default/sitemap.xml
+
+When ranging through the page collection, access the _change frequency_ and _priority_ with `.Sitemap.ChangeFreq` and `.Sitemap.Priority` respectively.
+
+To override the built-in sitemapindex.xml template, create a new file in either of these locations:
+
+- layouts/sitemapindex.xml
+- layouts/_default/sitemapindex.xml
+
+## Disable sitemap generation
+
+You may disable sitemap generation in your site configuration:
+
+{{< code-toggle file=hugo >}}
+disableKinds = ['sitemap']
+{{</ code-toggle >}}
+
+[`publishDir`]: /getting-started/configuration#publishdir
- [sitemap.xml]: <https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/sitemap.xml>
- [sitemapindex.xml]: <https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/sitemapindex.xml>
+[sitemap protocol]: <https://www.sitemaps.org/protocol.html>
--- /dev/null
- * Order the way content associated with a taxonomy term is displayed in a [taxonomy list template](#taxonomy-list-templates)
- * Order the way the terms for a taxonomy are displayed in a [taxonomy terms template](#taxonomy-terms-templates)
+---
+title: Taxonomy templates
+description: Taxonomy templating includes taxonomy list pages, taxonomy terms pages, and using taxonomies in your single page templates.
+categories: [templates]
+keywords: [taxonomies,metadata,front matter,terms,templates]
+menu:
+ docs:
+ parent: templates
+ weight: 90
+weight: 90
+toc: true
+aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy/]
+---
+
+Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications that demonstrate logical relationships between content. See [Taxonomies under Content Management](/content-management/taxonomies) if you are unfamiliar with how Hugo leverages this powerful feature.
+
+Hugo provides multiple ways to use taxonomies throughout your project templates:
+
- ## Taxonomy list templates
++* Order the way content associated with a taxonomy term is displayed in a [taxonomy template](#taxonomy-templates)
++* Order the way the terms for a taxonomy are displayed in a [term template](#term-templates)
+* List a single content's taxonomy terms within a [single page template]
+
- Taxonomy list page templates are lists and therefore have all the variables and methods available to [list pages][lists].
++## Taxonomy templates
+
- ### Taxonomy list template lookup order
++Taxonomy list page templates are lists and therefore have all the methods available to [list pages][lists].
+
- ## Taxonomy terms templates
++### Taxonomy template lookup order
+
+See [Template Lookup](/templates/lookup-order/).
+
- ### Taxonomy terms templates lookup order
++## Term templates
+
- A Taxonomy is a `map[string]WeightedPages`.
++### Term template lookup order
+
+See [Template Lookup](/templates/lookup-order/).
+
+### Taxonomy methods
+
- .Get TERM
- : Returns the WeightedPages for a given term. For example: ;
- `site.Taxonomies.tags.Get "tag-a"`.
-
- .Count TERM
- : The number of pieces of content assigned to the given term. For example: \
- `site.Taxonomies.tags.Count "tag-a"`.
-
- .Alphabetical
- : Returns an OrderedTaxonomy (slice) ordered by term.
-
- .ByCount
- : Returns an OrderedTaxonomy (slice) ordered by number of entries.
-
- .Reverse
- : Returns an OrderedTaxonomy (slice) in reverse order. Must be used with an OrderedTaxonomy.
++{{< list-pages-in-section path=/methods/taxonomy/ >}}
+
- If you need to display custom metadata for each taxonomy term, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in its front matter, [as explained in the taxonomies documentation](/content-management/taxonomies/#add-custom-metadata-to-a-taxonomy-or-term). Based on the Actors taxonomy example shown there, within your taxonomy terms template, you may access your custom fields by iterating through the variable `.Pages` as such:
+
+### OrderedTaxonomy
+
+Since Maps are unordered, an OrderedTaxonomy is a special structure that has a defined order.
+
+```go
+[]struct {
+ Name string
+ WeightedPages WeightedPages
+}
+```
+
+Each element of the slice has:
+
+.Term
+: The Term used.
+
+.WeightedPages
+: A slice of Weighted Pages.
+
+.Count
+: The number of pieces of content assigned to this term.
+
+.Page
+: Returns a page reference for this term.
+
+.Pages
+: All Pages assigned to this term. All [list methods][renderlists] are available to this.
+
+## WeightedPages
+
+WeightedPages is simply a slice of WeightedPage.
+
+```go
+type WeightedPages []WeightedPage
+```
+
+.Count
+: The number of pieces of content assigned to this term.
+
+.Page
+: Returns a page reference for this term.
+
+.Pages
+: Returns a slice of pages, which then can be ordered using any of the [list methods][renderlists].
+
+## Displaying custom metadata in taxonomy terms templates
+
- If you are using a taxonomy for something like a series of posts, you can list individual pages associated with the same taxonomy. This is also a quick and dirty method for showing related content:
++If you need to display custom metadata for each taxonomy term, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in its front matter, [as explained in the taxonomies documentation](/content-management/taxonomies/#add-custom-metadata-to-a-taxonomy-or-term). Based on the Actors taxonomy example shown there, within your taxonomy terms template, you may access your custom fields by ranging over the page collection returned by the [`Pages`] method:
+
+```go-html-template
+<ul>
+ {{ range .Pages }}
+ <li>
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+ {{ .Params.wikipedia }}
+ </li>
+ {{ end }}
+</ul>
+```
+
+## Order taxonomies
+
+Taxonomies can be ordered by either alphabetical key or by the number of content pieces assigned to that key.
+
+### Order alphabetically example
+
+```go-html-template
+<ul>
+ {{ range .Data.Terms.Alphabetical }}
+ <li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li>
+ {{ end }}
+</ul>
+```
+
+## Order content within taxonomies
+
+Hugo uses both `date` and `weight` to order content within taxonomies.
+
+Each piece of content in Hugo can optionally be assigned a date. It can also be assigned a weight for each taxonomy it is assigned to.
+
+When iterating over content within taxonomies, the default sort is the same as that used for section and list pages: first by weight, then by date. This means that if the weights for two pieces of content are the same, then the more recent content will be displayed first.
+
+The default weight for any piece of content is 0. Zero means "does not have a weight", not "has a weight of numerical value zero".
+
+Weights of zero are thus treated specially: if two pages have unequal weights, and one of them is zero, then the zero-weighted page will always appear after the other one, regardless of the other's weight. Zero weights should thus be used with care: for example, if both positive and negative weights are used to extend a sequence in both directions, a zero-weighted page will appear not in the middle of the list, but at the end.
+
+### Assign weight
+
+Content can be assigned weight for each taxonomy that it's assigned to.
+
+{{< code-toggle file=content/example.md fm=true >}}
+tags = [ "a", "b", "c" ]
+tags_weight = 22
+categories = ["d"]
+title = "Example"
+categories_weight = 44
+{{< /code-toggle >}}
+
+The convention is `taxonomyname_weight`.
+
+In the above example, this piece of content has a weight of 22 which applies to the sorting when rendering the pages assigned to the "a", "b" and "c" values of the 'tag' taxonomy.
+
+It has also been assigned the weight of 44 when rendering the 'd' category.
+
+With this the same piece of content can appear in different positions in different taxonomies.
+
+Currently taxonomies only support the default ordering of content which is weight -> date.
+
+There are two different templates that the use of taxonomies will require you to provide.
+
+Both templates are covered in detail in the templates section.
+
+A [list template](/templates/lists/) is any template that will be used to render multiple pieces of content in a single html page. This template will be used to generate all the automatically created taxonomy pages.
+
+A [taxonomy template](/templates/taxonomy-templates/) is a template used to
+generate the list of terms for a given template.
+
+There are four common ways you can display the data in your
+taxonomies in addition to the automatic taxonomy pages created by hugo
+using the [list templates](/templates/lists/):
+
+1. For a given piece of content, you can list the terms attached
+2. For a given piece of content, you can list other content with the same
+ term
+3. You can list all terms for a taxonomy
+4. You can list all taxonomies (with their terms)
+
+## List terms assigned to a page
+
+List the terms assigned to a page using the `.Page.GetTerms` method.
+
+To render an unordered list:
+
+```go-html-template
+{{ $taxonomy := "tags" }}
+{{ with .GetTerms $taxonomy }}
+ <p>{{ (site.GetPage $taxonomy).LinkTitle }}:</p>
+ <ul>
+ {{ range . }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+To render a comma-delimited list:
+
+```go-html-template
+{{ $taxonomy := "tags" }}
+{{ with .GetTerms $taxonomy }}
+ <p>
+ {{ (site.GetPage $taxonomy).LinkTitle }}:
+ {{ range $k, $_ := . -}}
+ {{ if $k }}, {{ end }}
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+ {{- end }}
+ </p>
+{{ end }}
+```
+
+## List content with the same taxonomy term
+
- ### Example: showing content in same series
++If you are using a taxonomy for something like a series of posts, you can list individual pages associated with the same term. For example:
++
+
- ### Example: grouping "featured" content
-
+
+```go-html-template
+<ul>
+ {{ range .Site.Taxonomies.series.golang }}
+ <li><a href="{{ .Page.RelPermalink }}">{{ .Page.Title }}</a></li>
+ {{ end }}
+</ul>
+```
+
+## List all content in a given taxonomy
+
+This would be very useful in a sidebar as “featured content”. You could even have different sections of “featured content” by assigning different terms to the content.
+
- {{ range $key, $taxonomy := .Site.Taxonomies.featured }}
- <li>{{ $key }}</li>
+```go-html-template
+<section id="menu">
+ <ul>
- If you wish to display the list of all keys for your site's taxonomy, you can retrieve them from the [`.Site` variable][sitevars] available on every page.
-
- This may take the form of a tag cloud, a menu, or simply a list.
-
++ {{ range $term, $taxonomy := .Site.Taxonomies.featured }}
++ <li>{{ $term }}</li>
+ <ul>
+ {{ range $taxonomy.Pages }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+ {{ end }}
+ </ul>
+</section>
+```
+
+## Render a site's taxonomies
+
- ### Example: list all site tags
-
+The following example displays all terms in a site's tags taxonomy:
+
-
- ### Example: list all taxonomies, terms, and assigned content
-
+```go-html-template
+<ul>
+ {{ range .Site.Taxonomies.tags }}
+ <li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li>
+ {{ end }}
+</ul>
+```
- <ul>
- {{ range $taxonomy, $terms := site.Taxonomies }}
- <li>
- {{ with site.GetPage $taxonomy }}
- <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
- {{ end }}
- <ul>
- {{ range $term, $weightedPages := $terms }}
+This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms.
+
+{{< code file=layouts/partials/all-taxonomies.html >}}
- {{ range $weightedPages }}
- <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
++{{ with .Site.Taxonomies }}
++ {{ $numberOfTerms := 0 }}
++ {{ range $taxonomy, $terms := . }}
++ {{ $numberOfTerms = len . | add $numberOfTerms }}
++ {{ end }}
++
++ {{ if gt $numberOfTerms 0 }}
++ <ul>
++ {{ range $taxonomy, $terms := . }}
++ {{ with $terms }}
+ <li>
+ <a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a>
+ <ul>
- </ul>
- </li>
- {{ end }}
- </ul>
- {{< /code >}}
-
- ## `.Site.GetPage` for taxonomies
-
- Because taxonomies are lists, the [`.GetPage` function][getpage] can be used to get all the pages associated with a particular taxonomy term using a terse syntax. The following ranges over the full list of tags on your site and links to each of the individual taxonomy pages for each term without having to use the more fragile URL construction of the ["List All Site Tags" example above](#example-list-all-site-tags):
-
- {{< code file=links-to-all-tags.html >}}
- {{ $taxo := "tags" }}
- <ul class="{{ $taxo }}">
- {{ with ($.Site.GetPage (printf "/%s" $taxo)) }}
- {{ range .Pages }}
- <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
- {{ end }}
++ {{ range $term, $weightedPages := . }}
++ <li>
++ <a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a>
++ <ul>
++ {{ range $weightedPages }}
++ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
++ {{ end }}
++ </ul>
++ </li>
+ {{ end }}
+ </ul>
+ </li>
+ {{ end }}
- </ul>
++ {{ end }}
++ </ul>
+ {{ end }}
- [getpage]: /methods/page/getpage
++{{ end }}
+{{< /code >}}
+
- [sitevars]: /variables/site/
++[`Pages`]: /methods/page/pages/
++[getpage]: /methods/page/getpage/
+[lists]: /templates/lists/
+[renderlists]: /templates/lists/
+[single page template]: /templates/single-page-templates/
--- /dev/null
- Hugo also has support for a default content template to be used in the event that a specific content view template has not been provided for that type. Content views can also be defined in the `_default` directory and will work the same as list and single templates who eventually trickle down to the `_default` directory as a matter of the lookup order.
+---
+title: Content view templates
+description: Hugo can render alternative views of your content, useful in list and summary views.
+categories: [templates]
+keywords: [views]
+menu:
+ docs:
+ parent: templates
+ weight: 110
+weight: 110
+toc: true
+---
+
+These alternative **content views** are especially useful in [list templates][lists].
+
+The following are common use cases for content views:
+
+* You want content of every type to be shown on the homepage but only with limited [summary views][summaries].
+* You only want a bulleted list of your content on a [taxonomy list page][taxonomylists]. Views make this very straightforward by delegating the rendering of each different type of content to the content itself.
+
+## Create a content view
+
+To create a new view, create a template in each of your different content type directories with the view name. The following example contains an "li" view and a "summary" view for the `posts` and `project` content types. As you can see, these sit next to the [single content view][single] template, `single.html`. You can even provide a specific view for a given type and continue to use the `_default/single.html` for the primary view.
+
+```txt
+ ▾ layouts/
+ ▾ posts/
+ li.html
+ single.html
+ summary.html
+ ▾ project/
+ li.html
+ single.html
+ summary.html
+```
+
- The following is the [lookup order][lookup] for content views:
++Hugo also has support for a default content view template to be used in the event that a specific content view template has not been provided for that type. Content views can also be defined in the `_default` directory and will work the same as list and single templates who eventually trickle down to the `_default` directory as a matter of the lookup order.
+
+```txt
+▾ layouts/
+ ▾ _default/
+ li.html
+ single.html
+ summary.html
+```
+
+## Which template will be rendered?
+
- Hugo will pass the entire page object to the following `summary.html` view template. (See [Page Variables][pagevars] for a complete list.)
++The following is the [lookup order] for content views:
+
+1. `/layouts/<TYPE>/<VIEW>.html`
+2. `/layouts/_default/<VIEW>.html`
+3. `/themes/<THEME>/layouts/<TYPE>/<VIEW>.html`
+4. `/themes/<THEME>/layouts/_default/<VIEW>.html`
+
+## Example: content view inside a list
+
+The following example demonstrates how to use content views inside your [list templates][lists].
+
+### `list.html`
+
+In this example, `.Render` is passed into the template to call the [render function][render]. `.Render` is a special function that instructs content to render itself with the view template provided as the first argument. In this case, the template is going to render the `summary.html` view that follows:
+
+{{< code file=layouts/_default/list.html >}}
+<main id="main">
+ <div>
+ <h1 id="title">{{ .Title }}</h1>
+ {{ range .Pages }}
+ {{ .Render "summary" }}
+ {{ end }}
+ </div>
+</main>
+{{< /code >}}
+
+### `summary.html`
+
- [lookup]: /templates/lookup-order/
- [pagevars]: /variables/page/
++Hugo passes the page object to the following `summary.html` view template.
+
+{{< code file=layouts/_default/summary.html >}}
+<article class="post">
+ <header>
+ <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
+ <div class="post-meta">{{ .Date.Format "Mon, Jan 2, 2006" }} - {{ .FuzzyWordCount }} Words </div>
+ </header>
+ {{ .Summary }}
+ <footer>
+ <a href='{{ .RelPermalink }}'>Read more »</a>
+ </footer>
+</article>
+{{< /code >}}
+
+### `li.html`
+
+Continuing on the previous example, we can change our render function to use a smaller `li.html` view by changing the argument in the call to the `.Render` function (i.e., `{{ .Render "li" }}`).
+
+{{< code file=layouts/_default/li.html >}}
+<li>
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+</li>
+{{< /code >}}
+
+[lists]: /templates/lists/
- [spf]: https://spf13.com
- [spfsourceli]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/li.html
- [spfsourcesection]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/section.html
- [spfsourcesummary]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/summary.html
+[render]: /methods/page/render/
+[single]: /templates/single-page-templates/
+[summaries]: /content-management/summaries/
+[taxonomylists]: /templates/taxonomy-templates/
--- /dev/null
- linkTitle: Overview
+---
+title: Developer tools
- identifier: developer-tools-overview
++linkTitle: In this section
+description: In addition to Hugo's powerful CLI, there is a large number of community-developed tool chains for Hugo developers.
+categories: []
+keywords: []
+menu:
+ docs:
++ identifier: developer-tools-in-this-section
+ parent: developer-tools
+ weight: 10
+weight: 10
+---
+
+One of Hugo's greatest strengths is its passionate---and always evolving---developer community. With the exception of the `highlight` shortcode mentioned in [Syntax Highlighting][syntax], the tools and other projects featured in this section are offerings from both commercial services and open-source projects, many of which are developed by Hugo developers just like you.
+
+[See the popularity of Hugo compared with other static site generators.][staticgen]
+
+[staticgen]: https://staticgen.com
+[syntax]: /content-management/syntax-highlighting/
--- /dev/null
- [xxx]: xxx
-
+---
+title: Editor plugins
+linkTitle: Editor plugins
+description: The Hugo community uses a wide range of tools and has developed plugins for some of the most popular text editors to help automate parts of your workflow.
+categories: [developer tools]
+keywords: [editor,plugin]
+menu:
+ docs:
+ parent: developer-tools
+ weight: 20
+weight: 20
+toc: true
+---
+
+## Visual Studio Code
+
+[Front Matter](https://marketplace.visualstudio.com/items?itemName=eliostruyf.vscode-front-matter)
+: Once you go for a static site, you need to think about how you are going to manage your articles. Front matter is a tool that helps you maintain the metadata/front matter of your articles like: creation date, modified date, slug, tile, SEO check, and more.
+
+[Hugo Helper](https://marketplace.visualstudio.com/items?itemName=rusnasonov.vscode-hugo)
+: Hugo Helper is a plugin for Visual Studio Code that has some useful commands for Hugo. The source code can be found [here](https://github.com/rusnasonov/vscode-hugo).
+
+[Hugo Language and Syntax Support](https://marketplace.visualstudio.com/items?itemName=budparr.language-hugo-vscode)
+: Hugo Language and Syntax Support is a Visual Studio Code plugin for Hugo syntax highlighting and snippets. The source code can be found [here](https://github.com/budparr/language-hugo-vscode).
+
+[Hugo Themer](https://marketplace.visualstudio.com/items?itemName=eliostruyf.vscode-hugo-themer)
+: Hugo Themer is an extension to help you while developing themes. It allows you to easily navigate through your theme files.
+
+[Hugofy](https://marketplace.visualstudio.com/items?itemName=akmittal.hugofy)
+: Hugofy is a plugin for Visual Studio Code to "make life easier" when developing with Hugo. The source code can be found [here](https://github.com/akmittal/hugofy-vscode).
+
+[Prettier Plugin for Go Templates](https://github.com/NiklasPor/prettier-plugin-go-template)
+: Format Hugo templates using this [Prettier](https://prettier.io/) plugin. See [installation instructions](https://discourse.gohugo.io/t/38403).
+
+[Syntax Highlighting for Hugo Shortcodes](https://marketplace.visualstudio.com/items?itemName=kaellarkin.hugo-shortcode-syntax)
+: This extension adds some syntax highlighting for Shortcodes, making visual identification of individual pieces easier.
+
+## Emacs
+
+[emacs-easy-hugo](https://github.com/masasam/emacs-easy-hugo)
+: Emacs major mode for managing hugo blogs. Note that Hugo also supports [Org-mode][formats].
+
+[ox-hugo.el](https://ox-hugo.scripter.co)
+: Native Org-mode exporter that exports to Blackfriday Markdown with Hugo front-matter. `ox-hugo` supports two common Org blogging flows --- exporting multiple Org subtrees in a single file to multiple Hugo posts, and exporting a single Org file to a single Hugo post. It also leverages the Org tag and property inheritance features. See [*Why ox-hugo?*](https://ox-hugo.scripter.co/doc/why-ox-hugo/) for more.
+
+## Sublime Text
+
+[Hugofy](https://github.com/akmittal/Hugofy)
+: Hugofy is a plugin for Sublime Text 3 to make life easier to use Hugo static site generator.
+
+[Hugo Snippets](https://packagecontrol.io/packages/Hugo%20Snippets)
+: Hugo Snippets is a useful plugin for adding automatic snippets to Sublime Text 3.
+
+## Vim
+
+[Vim Hugo Helper]: https://github.com/robertbasic/vim-hugo-helper
+
+[Vim Hugo Helper]
+: A small Vim plugin that facilitates authoring pages and blog posts with Hugo.
+
+[vim-hugo](https://github.com/phelipetls/vim-hugo)
+: A Vim plugin with syntax highlighting for templates and a few other features.
+
+[formats]: /content-management/formats/
--- /dev/null
- ## Open source
+---
+title: Front-end interfaces
+linkTitle: Front-ends
+description: Do you prefer a graphical user interface over a text editor? Give these front-ends a try.
+categories: [developer tools]
+keywords: [frontend, gui]
+menu:
+ docs:
+ parent: developer-tools
+ weight: 30
+weight: 30
+toc: true
+aliases: [/tools/frontends/]
+---
+
+## Commercial
+
+[CloudCannon](https://cloudcannon.com/hugo-cms/)
+: The intuitive Git-based CMS for your Hugo website. CloudCannon syncs changes from your Git repository and pushes content changes back, so your development and content teams are always in sync. Edit all of your content on the page with visual editing, build entire pages with reusable custom components and then publish confidently.
+
+[DatoCMS](https://www.datocms.com)
+: DatoCMS is a fully customizable administrative area for your static websites. Use your favorite website generator, let your clients publish new content independently, and the host the site anywhere you like.
+
++[PubCrank](https://www.pubcrank.com/)
++: PubCrank is a static site editor which lets you define templates for different front matter layouts in your site. This gives writers an easy-to-use visual interface to create and edit content while maintaining the guardrails that the developer has created. PubCrank is free for local editing.
++
++## Open-source
+
+[Decap CMS](https://decapcms.org/)
+: Decap CMS is an open-source, serverless solution for managing Git based content in static sites, and it works on any platform that can host static sites. A [Hugo/Decap CMS starter](https://github.com/decaporg/one-click-hugo-cms) is available to get new projects running quickly.
+
++[Quiqr Desktop](https://quiqr.org/)
++: Quiqr Desktop is a open-source, cross-platform, offline desktop CMS for Hugo with built-in Git functionality for deploying static sites to any hosting server.
++
+[Sveltia CMS](https://github.com/sveltia/sveltia-cms/)
+: Sveltia CMS is a drop-in replacement for Decap CMS which is built from the ground up with powerful and performant modern UI library Svelte. Sveltia CMS incorporates i18n into every corner of the product, while striving to radically improve UX, performance and productivity.
--- /dev/null
- : A one-click WordPress plugin that converts all posts, pages, taxonomies, metadata, and settings to Markdown and YAML which can be dropped into Hugo. (Note: If you have trouble using this plugin, you - \s-\scan [export your site for Jekyll](https://wordpress.org/plugins/jekyll-exporter/) and use Hugo's built in Jekyll converter listed above.)
+---
+title: Migrate to Hugo
+linkTitle: Migrations
+description: A list of community-developed tools for migrating from your existing static site generator or content management system to Hugo.
+categories: [developer tools]
+keywords: [migrations,jekyll,wordpress,drupal,ghost,contentful]
+menu:
+ docs:
+ parent: developer-tools
+ weight: 50
+weight: 50
+toc: true
+aliases: [/developer-tools/migrations/, /developer-tools/migrated/]
+---
+
+This section highlights some projects around Hugo that are independently developed. These tools try to extend the functionality of our static site generator or help you to get started.
+
+Take a look at this list of migration tools if you currently use other blogging tools like Jekyll or WordPress but intend to switch to Hugo instead. They'll take care to export your content into Hugo-friendly formats.
+
+## Jekyll
+
+Alternatively, you can use the [Jekyll import command](/commands/hugo_import_jekyll/).
+
+[JekyllToHugo](https://github.com/fredrikloch/JekyllToHugo)
+: A Small script for converting Jekyll blog posts to a Hugo site.
+
+[ConvertToHugo](https://github.com/coderzh/ConvertToHugo)
+: Convert your blog from Jekyll to Hugo.
+
+## Octopress
+
+[octohug](https://github.com/codebrane/octohug)
+: Octopress to Hugo migrator.
+
+## DokuWiki
+
+[dokuwiki-to-hugo](https://github.com/wgroeneveld/dokuwiki-to-hugo)
+: Migrates your DokuWiki source pages from [DokuWiki syntax](https://www.dokuwiki.org/wiki:syntax) to Hugo Markdown syntax. Includes extra's like the TODO plugin. Written with extensibility in mind using python 3. Also generates a TOML header for each page. Designed to copypaste the wiki directory into your /content directory.
+
+## WordPress
+
+[wordpress-to-hugo-exporter](https://github.com/SchumacherFM/wordpress-to-hugo-exporter)
++: A one-click WordPress plugin that converts all posts, pages, taxonomies, metadata, and settings to Markdown and YAML which can be dropped into Hugo. (Note: If you have trouble using this plugin, you can [export your site for Jekyll](https://wordpress.org/plugins/jekyll-exporter/) and use Hugo's built in Jekyll converter listed above.)
+
+[blog2md](https://github.com/palaniraja/blog2md)
+: Works with [exported xml](https://en.support.wordpress.com/export/) file of your free YOUR-TLD.wordpress.com website. It also saves approved comments to `YOUR-POST-NAME-comments.md` file along with posts.
+
+[wordhugopress](https://github.com/nantipov/wordhugopress)
+: A small utility written in Java, exports the entire WordPress site from the database and resource (e.g. images) files stored locally or remotely. Therefore, migration from the backup files is possible. Supports merging of the multiple WordPress sites into a single Hugo one.
+
++[wp2hugo](https://github.com/ashishb/wp2hugo)
++: A Go-based CLI tool to migrate WordPress website to Hugo while preserving original URLs, GUIDs (for feeds), image URLs, code highlights, table of contents, YouTube embeds, Google Maps embeds, and original WordPress navigation categories.
++
+## Medium
+
+[medium2md](https://github.com/gautamdhameja/medium-2-md)
+: A simple Medium to Hugo exporter able to import stories in one command, including front matter.
+
+[medium-to-hugo](https://github.com/bgadrian/medium-to-hugo)
+: CLI tool written in Go to export medium posts into a Hugo compatible Markdown format. Tags and images are included. All images will be downloaded locally and linked appropriately.
+
+## Tumblr
+
+[tumblr-importr](https://github.com/carlmjohnson/tumblr-importr)
+: An importer that uses the Tumblr API to create a Hugo static site.
+
+[tumblr2hugomarkdown](https://github.com/Wysie/tumblr2hugomarkdown)
+: Export all your Tumblr content to Hugo Markdown files with preserved original formatting.
+
+[Tumblr to Hugo](https://github.com/jipiboily/tumblr-to-hugo)
+: A migration tool that converts each of your Tumblr posts to a content file with a proper title and path. Furthermore, "Tumblr to Hugo" creates a CSV file with the original URL and the new path on Hugo, to help you setup the redirections.
+
+## Drupal
+
+[drupal2hugo](https://github.com/danapsimer/drupal2hugo)
+: Convert a Drupal site to Hugo.
+
+## Joomla
+
+[hugojoomla](https://github.com/davetcc/hugojoomla)
+: This utility written in Java takes a Joomla database and converts all the content into Markdown files. It changes any URLs that are in Joomla's internal format and converts them to a suitable form.
+
+## Blogger
+
+[blogimport](https://github.com/natefinch/blogimport)
+: A tool to import from Blogger posts to Hugo.
+
+[blogger-to-hugo](https://pypi.org/project/blogger-to-hugo/)
+: Another tool to import Blogger posts to Hugo. It also downloads embedded images so they will be stored locally.
+
+[blog2md](https://github.com/palaniraja/blog2md)
+: Works with [exported xml](https://support.google.com/blogger/answer/41387?hl=en) file of your YOUR-TLD.blogspot.com website. It also saves comments to `YOUR-POST-NAME-comments.md` file along with posts.
+
+[BloggerToHugo](https://github.com/huanlin/blogger-to-hugo)
+: Yet another tool to import Blogger posts to Hugo. For Windows platform only, and .NET Framework 4.5 is required. See README.md before using this tool.
+
+## Contentful
+
+[contentful-hugo](https://github.com/ModiiMedia/contentful-hugo)
+: A tool to create content-files for Hugo from content on [Contentful](https://www.contentful.com/).
+
+## BlogML
+
+[BlogML2Hugo](https://github.com/jijiechen/BlogML2Hugo)
+: A tool that helps you convert BlogML xml file to Hugo Markdown files. Users need to take care of links to attachments and images by themselves. This helps the blogs that export BlogML files (e.g. BlogEngine.NET) transform to hugo sites easily.
--- /dev/null
- And for all the other small things around Hugo:
+---
+title: Other community projects
+linkTitle: Other projects
+description: Some interesting projects developed by the Hugo community that don't quite fit into our other developer tool categories.
+categories: [developer tools]
+keywords: [frontend,gui]
+menu:
+ docs:
+ parent: developer-tools
+ weight: 60
+weight: 60
+---
+
- - [hugo-gallery](https://github.com/icecreammatt/hugo-gallery) lets you create an image gallery for Hugo sites.
- - [flickr-hugo-embed](https://github.com/nikhilm/flickr-hugo-embed) prints shortcodes to embed a set of images from an album on Flickr into Hugo.
- - [hugo-openapispec-shortcode](https://github.com/tenfourty/hugo-openapispec-shortcode) A shortcode that allows you to include [Open API Spec](https://openapis.org) (formerly known as Swagger Spec) in a page.
- - [HugoPhotoSwipe](https://github.com/GjjvdBurg/HugoPhotoSwipe) makes it easy to create image galleries using PhotoSwipe.
- - [Hugo SFTP Upload](https://github.com/thomasmey/HugoSftpUpload) Syncs the local build of your Hugo website with your remote web server via SFTP.
- - [Emacs Easy Hugo](https://github.com/masasam/emacs-easy-hugo) Emacs package for writing blog posts in markdown or org-mode and building your site with Hugo.
- - [JAMStack Themes](https://jamstackthemes.dev/ssg/hugo/). JAMStack themes is a collection of site themes filterable by static site generator and supported CMS to help build CMS-connected sites using Hugo (linking to Hugo-specific themes).
- - [plausible-hugo](https://github.com/divinerites/plausible-hugo). Easy Hugo integration for Plausible Analytics, a simple, open-source, lightweight and privacy-friendly web analytics alternative to Google Analytics.
++And for all the other community projects around Hugo:
+
++- [diego](https://github.com/ttybitnik/diego) - A CLI tool that integrates with Hugo to assist in importing and utilizing exported social media data from popular services on Hugo websites.
++- [Emacs Easy Hugo](https://github.com/masasam/emacs-easy-hugo) - Emacs package for writing blog posts in Markdown or org-mode and building your site with Hugo.
++- [Hugo SFTP Upload](https://github.com/thomasmey/HugoSftpUpload) - Sync the local build of your Hugo website with your remote web server via SFTP.
++- [HugoPhotoSwipe](https://github.com/GjjvdBurg/HugoPhotoSwipe) - Make it easy to create image galleries using PhotoSwipe.
++- [JAMStack Themes](https://jamstackthemes.dev/ssg/hugo/) - A collection of site themes filterable by static site generator and supported CMS to help build CMS-connected sites using Hugo (linking to Hugo-specific themes).
++- [flickr-hugo-embed](https://github.com/nikhilm/flickr-hugo-embed) - Print shortcodes to embed a set of images from an album on Flickr into Hugo.
++- [hugo-gallery](https://github.com/icecreammatt/hugo-gallery) - Create an image gallery for Hugo sites.
++- [hugo-openapispec-shortcode](https://github.com/tenfourty/hugo-openapispec-shortcode) - A shortcode that allows you to include [Open API Spec](https://openapis.org) (formerly known as Swagger Spec) in a page.
++- [plausible-hugo](https://github.com/divinerites/plausible-hugo) - Easy Hugo integration for Plausible Analytics, a simple, open-source, lightweight and privacy-friendly web analytics alternative to Google Analytics.
--- /dev/null
- ## Open source
+---
+title: Search tools
+linkTitle: Search
+description: See some of the open-source and commercial search options for your newly created Hugo website.
+categories: [developer tools]
+keywords: [search]
+menu:
+ docs:
+ parent: developer-tools
+ weight: 40
+weight: 40
+toc: true
+---
+
+A static website with a dynamic search function? Yes, Hugo provides an alternative to embeddable scripts from Google or other search engines for static websites. Hugo allows you to provide your visitors with a custom search function by indexing your content files directly.
+
- : A library containing Gulp tasks and a prebuilt browser script that implements search. Gulp generates a search index from project markdown files.
++## Open-source
+
+[Pagefind](https://github.com/cloudcannon/pagefind)
+: A fully static search library that aims to perform well on large sites, while using as little of your users' bandwidth as possible.
+
+[GitHub Gist for Hugo Workflow](https://gist.github.com/sebz/efddfc8fdcb6b480f567)
+: This gist contains a simple workflow to create a search index for your static website. It uses a simple Grunt script to index all your content files and [lunr.js](https://lunrjs.com/) to serve the search results.
+
+[hugo-lunr](https://www.npmjs.com/package/hugo-lunr)
+: A simple way to add site search to your static Hugo site using [lunr.js](https://lunrjs.com/). Hugo-lunr will create an index file of any HTML and Markdown documents in your Hugo project.
+
+[hugo-lunr-zh](https://www.npmjs.com/package/hugo-lunr-zh)
+: A bit like Hugo-lunr, but Hugo-lunr-zh can help you separate the Chinese keywords.
+
+[GitHub Gist for Fuse.js integration](https://gist.github.com/eddiewebb/735feb48f50f0ddd65ae5606a1cb41ae)
+: This gist demonstrates how to leverage Hugo's existing build time processing to generate a searchable JSON index used by [Fuse.js](https://fusejs.io/) on the client-side. Although this gist uses Fuse.js for fuzzy matching, any client-side search tool capable of reading JSON indexes will work. Does not require npm, grunt, or other build-time tools except Hugo!
+
+[hugo-search-index](https://www.npmjs.com/package/hugo-search-index)
++: A library containing Gulp tasks and a prebuilt browser script that implements search. Gulp generates a search index from project Markdown files.
+
+[hugofastsearch](https://gist.github.com/cmod/5410eae147e4318164258742dd053993)
+: A usability and speed update to "GitHub Gist for Fuse.js integration" — global, keyboard-optimized search.
+
+[JS & Fuse.js tutorial](https://makewithhugo.com/add-search-to-a-hugo-site/)
+: A simple client-side search solution, using FuseJS (does not require jQuery).
+
+[Hugo Lyra](https://github.com/paolomainardi/hugo-lyra)
+: Hugo-Lyra is a JavaScript module to integrate [Lyra](https://github.com/LyraSearch/lyra) into a Hugo website. It contains the server-side part to generate the index and the client-side library (optional) to bootstrap the search engine easily.
+
+## Commercial
+
+[Algolia](https://www.algolia.com/)
+: Algolia's Search API makes it easy to deliver a great search experience in your apps and websites. Algolia Search provides hosted full-text, numerical, faceted, and geolocalized search.
+
+[Bonsai](https://www.bonsai.io)
+: Bonsai is a fully-managed hosted Elasticsearch service that is fast, reliable, and simple to set up. Easily ingest your docs from Hugo into Elasticsearch following [this guide from the docs](https://bonsai.io/docs/hugo).
+
+[ExpertRec](https://www.expertrec.com/)
+: ExpertRec is a hosted search-as-a-service solution that is fast and scalable. Set-up and integration is extremely easy and takes only a few minutes. The search settings can be modified without coding using a dashboard.
--- /dev/null
- linkTitle: Overview
+---
+title: Troubleshooting
- identifier: troubleshooting-overview
++linkTitle: In this section
+description: Use these techniques when troubleshooting your site.
+categories: []
+keywords: []
+menu:
+ docs:
++ identifier: troubleshooting-in-this-section
+ parent: troubleshooting
+ weight: 10
+weight: 10
+aliases: [/templates/template-debugging/]
+---
+
+Use these techniques when troubleshooting your site.
--- /dev/null
- : By default, Hugo strips raw HTML from your markdown prior to rendering, and leaves this HTML comment in its place.
+---
+title: Site audit
+linkTitle: Audit
+description: Run this audit before deploying your production site.
+categories: [troubleshooting]
+keywords: []
+menu:
+ docs:
+ parent: troubleshooting
+ weight: 20
+weight: 20
+---
+
+There are several conditions that can produce errors in your published site which are not detected during the build. Run this audit before your final build.
+
+{{< code copy=true >}}
+HUGO_MINIFY_TDEWOLFF_HTML_KEEPCOMMENTS=true HUGO_ENABLEMISSINGTRANSLATIONPLACEHOLDERS=true hugo && grep -inorE "<\!-- raw HTML omitted -->|ZgotmplZ|\[i18n\]|\(<nil>\)|(<nil>)|hahahugo" public/
+{{< /code >}}
+
+_Tested with GNU Bash 5.1 and GNU grep 3.7._
+
+## Example output
+
+
+
+## Explanation
+
+### Environment variables
+
+`HUGO_MINIFY_TDEWOLFF_HTML_KEEPCOMMENTS=true`
+: Retain HTML comments even if minification is enabled. This takes precedence over `minify.tdewolff.html.keepComments` in the site configuration. If you minify without keeping HTML comments when performing this audit, you will not be able to detect when raw HTML has been omitted.
+
+`HUGO_ENABLEMISSINGTRANSLATIONPLACEHOLDERS=true`
+: Show a placeholder instead of the default value or an empty string if a translation is missing. This takes precedence over `enableMissingTranslationPlaceholders` in the site configuration.
+
+### Grep options
+
+`-i, --ignore-case`
+: Ignore case distinctions in patterns and input data, so that characters that differ only in case match each other.
+
+`-n, --line-number`
+: Prefix each line of output with the 1-based line number within its input file.
+
+`-o, --only-matching`
+: Print only the matched (non-empty) parts of a matching line, with each such part on a separate output line.
+
+`-r, --recursive`
+: Read all files under each directory, recursively, following symbolic links only if they are on the command line.
+
+`-E, --extended-regexp`
+: Interpret PATTERNS as extended regular expressions.
+
+### Patterns
+
+`<!-- raw HTML omitted -->`
++: By default, Hugo strips raw HTML from your Markdown prior to rendering, and leaves this HTML comment in its place.
+
+`ZgotmplZ`
+: ZgotmplZ is a special value that indicates that unsafe content reached a CSS or URL context at runtime. See [details].
+
+[details]: https://pkg.go.dev/html/template
+
+`[i18n]`
+: This is the placeholder produced instead of the default value or an empty string if a translation is missing.
+
+`(<nil>)`
+: This string will appear in the rendered HTML when passing a nil value to the `printf` function.
+
+`(<nil>)`
+: Same as above when the value returned from the `printf` function has not been passed through `safeHTML`.
+
+`HAHAHUGO`
+: Under certain conditions a rendered shortcode may include all or a portion of the string HAHAHUGOSHORTCODE in either uppercase or lowercase. This is difficult to detect in all circumstances, but a case-insensitive search of the output for `HAHAHUGO` is likely to catch the majority of cases without producing false positives.
--- /dev/null
- ###### Why is a given section not published?
-
- In the content/section/_index.md file:
-
- - Is `draft` set to `true`?
- - Is the `date` in the future?
- - Is the `publishDate` in the future?
- - Is the `expiryDate` in the past?
-
- If the answer to any of these questions is yes, either change the field values, or use one of these command line flags: `--buildDrafts`, `--buildFuture`, or `--buildExpired`.
-
+---
+title: Frequently asked questions
+linkTitle: FAQs
+description: These questions are frequently asked by new users.
+categories: [troubleshooting]
+keywords: [faq]
+menu:
+ docs:
+ parent: troubleshooting
+ weight: 70
+weight: 70
+# Use level 6 headings for each question.
+---
+
+Hugo’s [forum] is an active community of users and developers who answer questions, share knowledge, and provide examples. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question.
+
+These are just a few of the questions most frequently asked by new users.
+
+###### An error message indicates that a feature is not available. Why?
+
+Hugo is available in two editions: standard and extended. With the extended edition you can (a) encode to the WebP format when processing images, and (b) transpile Sass to CSS using the embedded LibSass transpiler. The extended edition is not required to use the Dart Sass transpiler.
+
+When you attempt to perform either of the operations above with the standard edition, Hugo throws this error:
+
+```go-html-template
+Error: this feature is not available in your current Hugo version
+```
+
+To resolve, uninstall the standard edition, then install the extended edition. See the [installation] section for details.
+
+###### Why do I see "Page Not Found" when visiting the home page?
+
+In the content/_index.md file:
+
+ - Is `draft` set to `true`?
+ - Is the `date` in the future?
+ - Is the `publishDate` in the future?
+ - Is the `expiryDate` in the past?
+
+If the answer to any of these questions is yes, either change the field values, or use one of these command line flags: `--buildDrafts`, `--buildFuture`, or `--buildExpired`.
+
- Use the `{{%/* shortcode */%}}` notation if the shortcode template, or the content between the opening and closing shortcode tags, contains markdown. Otherwise use the\
+###### Why is a given page not published?
+
+In the content/section/page.md file, or in the content/section/page/index.md file:
+
+ - Is `draft` set to `true`?
+ - Is the `date` in the future?
+ - Is the `publishDate` in the future?
+ - Is the `expiryDate` in the past?
+
+If the answer to any of these questions is yes, either change the field values, or use one of these command line flags: `--buildDrafts`, `--buildFuture`, or `--buildExpired`.
+
+###### Why can't I see any of a page's descendants?
+
+You may have an index.md file instead of an _index.md file. See [details](/content-management/page-bundles/).
+
+###### What is the difference between an index.md file and an _index.md file?
+
+A directory with an index.md file is a [leaf bundle]. A directory with an _index.md file is a [branch bundle]. See [details](/content-management/page-bundles/).
+
+[branch bundle]: /getting-started/glossary/#branch-bundle
+[leaf bundle]: /getting-started/glossary/#leaf-bundle
+
+###### Why is my partial template not rendered as expected? {#foo}
+
+You may have neglected to pass the required [context] when calling the partial. For example:
+
+```go-html-template
+{{/* incorrect */}}
+{{ partial "_internal/pagination.html" }}
+
+{{/* correct */}}
+{{ partial "_internal/pagination.html" . }}
+```
+
+###### In a template, what's the difference between `:=` and `=` when assigning values to variables?
+
+Use `:=` to initialize a variable, and use `=` to assign a value to a variable that has been previously initialized. See [details](https://pkg.go.dev/text/template#hdr-Variables).
+
+###### When I paginate a list page, why is the page collection not filtered as specified?
+
+You are probably invoking the [`Paginate`] or [`Paginator`] method more than once on the same page. See [details](/templates/pagination/#list-paginator-pages).
+
+###### Why are there two ways to call a shortcode?
+
- [`Paginate`]: /methods/page/paginate
- [`Paginator`]: /methods/page/paginator
++Use the `{{%/* shortcode */%}}` notation if the shortcode template, or the content between the opening and closing shortcode tags, contains Markdown. Otherwise use the\
+`{{</* shortcode */>}}` notation. See [details](/content-management/shortcodes/).
+
+###### Can I use environment variables to control configuration?
+
+Yes. See [details](/getting-started/configuration/#configure-with-environment-variables).
+
+###### Why am I seeing inconsistent output from one build to the next?
+
+The most common causes are page collisions (publishing two pages to the same path) and the effects of concurrency. Use the `--printPathWarnings` command line flag to check for page collisions, and create a topic on the [forum] if you suspect concurrency problems.
+
++###### Why isn't Hugo's development server detecting file changes?
++
++In its default configuration, Hugo's file watcher may not be able detect file changes when:
++
++- Running Hugo within Windows Subsystem for Linux (WSL/WSL2) with project files on a Windows partition
++- Running Hugo locally with project files on a removable drive
++- Running Hugo locally with project files on a storage server accessed via the NFS, SMB, or CIFS protocols
++
++In these cases, instead of monitoring native file system events, use the `--poll` command line flag. For example, to poll the project files every 700 milliseconds, use `--poll 700ms`.
++
++###### Why is my page Scratch or Store missing a value?
++
++The [`Scratch`] and [`Store`] methods on a `Page` object allow you to create a [scratch pad] on the given page to store and manipulate data. Values are often set within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are not determinate until Hugo renders the page content.
++
++[scratch pad]: /getting-started/glossary/#scratch-pad
++
++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 trigger content rendering with other methods as well. See next FAQ.
++
++[`Scratch`]: /methods/page/scratch
++[`Store`]: /methods/page/store
++
+###### Which page methods trigger content rendering?
+
+The following methods on a `Page` object trigger content rendering: `Content`, `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount`.
+
+{{% note %}}
+For other questions please visit the [forum]. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question.
+
+[forum]: https://discourse.gohugo.io
+[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132
+{{% /note %}}
+
- [installation]: /installation
++[`Paginate`]: /methods/page/paginate/
++[`Paginator`]: /methods/page/paginator/
+[context]: /getting-started/glossary/#context
+[forum]: https://discourse.gohugo.io
++[installation]: /installation/
+[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132
--- /dev/null
- Use the [`jsonify`] function to inspect a data structure:
+---
+title: Data inspection
+linkTitle: Inspection
+description: Use template functions to inspect values and data structures.
+categories: [troubleshooting]
+keywords: []
+menu:
+ docs:
+ parent: troubleshooting
+ weight: 40
+weight: 40
+---
+
- <pre>{{ jsonify (dict "indent" " ") .Params }}</pre>
++Use the [`debug.Dump`] function to inspect a data structure:
+
+```go-html-template
- {{% note %}}
- Hugo will throw an error if you attempt to use the construct above to display context that includes a page collection. For example, in a home page template, this will fail:
-
- `{{ jsonify (dict "indent" " ") . }}`
- {{% /note %}}
-
- Use the [`debug.Dump`] function to inspect data types:
-
- ```go-html-template
- <pre>{{ debug.Dump .Params }}</pre>
- ```
-
- ```text
- maps.Params{
- "date": time.Time{},
- "draft": false,
- "iscjklanguage": false,
- "lastmod": time.Time{},
- "publishdate": time.Time{},
- "tags": []string{
- "foo",
- "bar",
- },
- "title": "My first post",
- }
- ```
-
++<pre>{{ debug.Dump .Params }}</pre>
+```
+
+```text
+{
+ "date": "2023-11-10T15:10:42-08:00",
+ "draft": false,
+ "iscjklanguage": false,
+ "lastmod": "2023-11-10T15:10:42-08:00",
+ "publishdate": "2023-11-10T15:10:42-08:00",
+ "tags": [
+ "foo",
+ "bar"
+ ],
+ "title": "My first post"
+}
+```
+
- [`jsonify`]: /functions/encoding/jsonify
- [`debug.Dump`]: /functions/debug/dump
- [`printf`]: /functions/fmt/printf
- [`warnf`]: /functions/fmt/warnf
+Use the [`printf`] function (render) or [`warnf`] function (log to console) to inspect simple data structures. The layout string below displays both value and data type.
+
+```go-html-template
+{{ $value := 42 }}
+{{ printf "%[1]v (%[1]T)" $value }} → 42 (int)
+```
+
++[`debug.Dump`]: /functions/debug/dump/
++[`printf`]: /functions/fmt/printf/
++[`warnf`]: /functions/fmt/warnf/
--- /dev/null
+---
+title: Logging
+description: Enable logging to inspect events while building your site.
+categories: [troubleshooting]
+keywords: []
+menu:
+ docs:
+ parent: troubleshooting
+ weight: 30
+weight: 30
+toc: true
+---
+
+## Command line
+
+Enable console logging with the `--logLevel` command line flag.
+
+Hugo has four logging levels:
+
+error
+: Display error messages only.
+
+```sh
+hugo --logLevel error
+```
+
+warn
+: Display warning and error messages.
+
+```sh
+hugo --logLevel warn
+```
+
+info
+: Display information, warning, and error messages.
+
+```sh
+hugo --logLevel info
+```
+
+debug
+: Display debug, information, warning, and error messages.
+
+```sh
+hugo --logLevel debug
+```
+
+{{% note %}}
+If you do not specify a logging level with the `--logLevel` flag, warnings and errors are always displayed.
+{{% /note %}}
+
+## Template functions
+
+You can also use template functions to print warnings or errors to the console. These functions are typically used to report data validation errors, missing files, etc.
+
+{{< list-pages-in-section path=/functions/fmt filter=functions_fmt_logging filterType=include >}}
++
++## LiveReload
++
++To log Hugo's LiveReload requests in your browser, add this query string to the URL when running Hugo's development server:
++
++```text
++debug=LR-verbose
++```
++
++For example:
++
++```text
++http://localhost:1313/?debug=LR-verbose
++```
++
++Then monitor the reload requests in your browser's dev tools console. Make sure the dev tools "preserve log" option is enabled.
--- /dev/null
- description: Use template metrics and timers to identify opportunities to improve performance.
+---
+title: Performance
- [`partial`]: /functions/partials/include
- [`partialCached`]: /functions/partials/includecached
++description: Tools and suggestions for evaluating and improving performance.
+categories: [troubleshooting]
+keywords: []
+menu:
+ docs:
+ parent: troubleshooting
+ weight: 60
+weight: 60
+toc: true
+aliases: [/troubleshooting/build-performance/]
+---
+
++## Virus scanning
++
++Virus scanners are an essential component of system protection, but the performance impact can be severe for applications like Hugo that frequently read and write to disk. For example, with Microsoft Defender Antivirus, build times for some sites may increase by 400% or more.
++
++Before building a site, your virus scanner has already evaluated the files in your project directory. Scanning them again while building the site is superfluous. To improve performance, add Hugo's executable to your virus scanner's process exclusion list.
++
++For example, with Microsoft Defender Antivirus:
++
++**Start** > **Settings** > **Privacy & security** > **Windows Security** > **Open Windows Security** > **Virus & threat protection** > **Manage settings** > **Add or remove exclusions** > **Add an exclusion** > **Process**
++
++Then type `hugo.exe` add press the **Add** button.
++
++{{% note %}}
++Virus scanning exclusions are common, but use caution when changing these settings. See the [Microsoft Defender Antivirus documentation](https://support.microsoft.com/en-us/topic/how-to-add-a-file-type-or-process-exclusion-to-windows-security-e524cbc2-3975-63c2-f9d1-7c2eb5331e53) for details.
++{{% /note %}}
++
++Other virus scanners have similar exclusion mechanisms. See their respective documentation.
++
+## Template metrics
+
+Hugo is fast, but inefficient templates impede performance. Enable template metrics to determine which templates take the most time, and to identify caching opportunities:
+
+```sh
+hugo --templateMetrics --templateMetricsHints
+```
+
+The result will look something like this:
+
+```text
+Template Metrics:
+
+ cumulative average maximum cache percent cached total
+ duration duration duration potential cached count count template
+ ---------- -------- -------- --------- ------- ------ ----- --------
+ 36.037476822s 135.990478ms 225.765245ms 11 0 0 265 partials/head.html
+ 35.920040902s 164.018451ms 233.475072ms 0 0 0 219 articles/single.html
+ 34.163268129s 128.917992ms 224.816751ms 23 0 0 265 partials/head/meta/opengraph.html
+ 1.041227437s 3.92916ms 186.303376ms 47 0 0 265 partials/head/meta/schema.html
+ 805.628827ms 27.780304ms 114.678523ms 0 0 0 29 _default/list.html
+ 624.08354ms 15.221549ms 108.420729ms 8 0 0 41 partials/utilities/render-page-collection.html
+ 545.968801ms 775.523µs 105.045775ms 0 0 0 704 _default/summary.html
+ 334.680981ms 1.262947ms 127.412027ms 100 0 0 265 partials/head/js.html
+ 272.763205ms 2.050851ms 24.371757ms 0 0 0 133 _default/_markup/render-codeblock.html
+ 230.490038ms 8.865001ms 177.4615ms 0 0 0 26 shortcodes/template.html
+ 176.921913ms 176.921913ms 176.921913ms 0 0 0 1 examples.tmpl
+ 163.951469ms 14.904679ms 70.267953ms 0 0 0 11 articles/list.html
+ 153.07021ms 577.623µs 73.593597ms 100 0 0 265 partials/head/init.html
+ 150.910984ms 150.910984ms 150.910984ms 0 0 0 1 _default/single.html
+ 146.785804ms 146.785804ms 146.785804ms 0 0 0 1 _default/contact.html
+ 115.364617ms 115.364617ms 115.364617ms 0 0 0 1 authors/term.html
+ 87.392071ms 329.781µs 10.687132ms 100 0 0 265 partials/head/css.html
+ 86.803122ms 86.803122ms 86.803122ms 0 0 0 1 _default/home.html
+```
+
+From left to right, the columns represent:
+
+cumulative duration
+: The cumulative time spent executing the template.
+
+average duration
+: The average time spent executing the template.
+
+maximum duration
+: The maximum time spent executing the template.
+
+cache potential
+: Displayed as a percentage, any partial template with a 100% cache potential should be called with the [`partialCached`] function instead of the [`partial`] function. See the [caching](#caching) section below.
+
+percent cached
+: The number of times the rendered templated was cached divided by the number of times the template was executed.
+
+cached count
+: The number of times the rendered templated was cached.
+
+total count
+: The number of times the template was executed.
+
+template
+: The path to the template, relative to the layouts directory.
+
- Note that you can create cached variants of each partial by passing additional parameters to `partialCached` beyond the initial context. See the `partialCached` documentation for more details.
++[`partial`]: /functions/partials/include/
++[`partialCached`]: /functions/partials/includecached/
+
+{{% note %}}
+Hugo builds pages in parallel where multiple pages are generated simultaneously. Because of this parallelism, the sum of "cumulative duration" values is usually greater than the actual time it takes to build a site.
+{{% /note %}}
+
+## Caching
+
+Some partial templates such as sidebars or menus are executed many times during a site build. Depending on the content within the partial template and the desired output, the template may benefit from caching to reduce the number of executions. The [`partialCached`] template function provides caching capabilities for partial templates.
+
+{{% note %}}
++Note that you can create cached variants of each partial by passing additional arguments to `partialCached` beyond the initial context. See the `partialCached` documentation for more details.
+{{% /note %}}
+
+## Timers
+
+Use the `debug.Timer` function to determine execution time for a block of code, useful for finding performance bottle necks in templates. See [details](/functions/debug/timer/).
--- /dev/null
- - Aliases:
- - gleam>
- Name: Gleam
+chroma:
+ lexers:
+ - Aliases:
+ - abap
+ Name: ABAP
+ - Aliases:
+ - abnf
+ Name: ABNF
+ - Aliases:
+ - as
+ - actionscript
+ Name: ActionScript
+ - Aliases:
+ - as3
+ - actionscript3
+ Name: ActionScript 3
+ - Aliases:
+ - ada
+ - ada95
+ - ada2005
+ Name: Ada
+ - Aliases:
+ - agda
+ Name: Agda
+ - Aliases:
+ - al
+ Name: AL
+ - Aliases:
+ - alloy
+ Name: Alloy
+ - Aliases:
+ - ng2
+ Name: Angular2
+ - Aliases:
+ - antlr
+ Name: ANTLR
+ - Aliases:
+ - apacheconf
+ - aconf
+ - apache
+ Name: ApacheConf
+ - Aliases:
+ - apl
+ Name: APL
+ - Aliases:
+ - applescript
+ Name: AppleScript
+ - Aliases:
+ - aql
+ Name: ArangoDB AQL
+ - Aliases:
+ - arduino
+ Name: Arduino
+ - Aliases:
+ - armasm
+ Name: ArmAsm
+ - Aliases:
+ - autohotkey
+ - ahk
+ Name: AutoHotkey
+ - Aliases:
+ - autoit
+ Name: AutoIt
+ - Aliases:
+ - awk
+ - gawk
+ - mawk
+ - nawk
+ Name: Awk
+ - Aliases:
+ - ballerina
+ Name: Ballerina
+ - Aliases:
+ - bash
+ - sh
+ - ksh
+ - zsh
+ - shell
+ Name: Bash
+ - Aliases:
+ - bash-session
+ - console
+ - shell-session
+ Name: Bash Session
+ - Aliases:
+ - bat
+ - batch
+ - dosbatch
+ - winbatch
+ Name: Batchfile
+ - Aliases:
+ - bib
+ - bibtex
+ Name: BibTeX
+ - Aliases:
+ - bicep
+ Name: Bicep
+ - Aliases:
+ - blitzbasic
+ - b3d
+ - bplus
+ Name: BlitzBasic
+ - Aliases:
+ - bnf
+ Name: BNF
+ - Aliases:
+ - bqn
+ Name: BQN
+ - Aliases:
+ - brainfuck
+ - bf
+ Name: Brainfuck
+ - Aliases:
+ - c
+ Name: C
+ - Aliases:
+ - csharp
+ - c#
+ Name: C#
+ - Aliases:
+ - cpp
+ - c++
+ Name: C++
+ - Aliases:
+ - caddyfile
+ - caddy
+ Name: Caddyfile
+ - Aliases:
+ - caddyfile-directives
+ - caddyfile-d
+ - caddy-d
+ Name: Caddyfile Directives
+ - Aliases:
+ - capnp
+ Name: Cap'n Proto
+ - Aliases:
+ - cassandra
+ - cql
+ Name: Cassandra CQL
+ - Aliases:
+ - ceylon
+ Name: Ceylon
+ - Aliases:
+ - cfengine3
+ - cf3
+ Name: CFEngine3
+ - Aliases:
+ - cfs
+ Name: cfstatement
+ - Aliases:
+ - chai
+ - chaiscript
+ Name: ChaiScript
+ - Aliases:
+ - chapel
+ - chpl
+ Name: Chapel
+ - Aliases:
+ - cheetah
+ - spitfire
+ Name: Cheetah
+ - Aliases:
+ - clojure
+ - clj
+ - edn
+ Name: Clojure
+ - Aliases:
+ - cmake
+ Name: CMake
+ - Aliases:
+ - cobol
+ Name: COBOL
+ - Aliases:
+ - coffee-script
+ - coffeescript
+ - coffee
+ Name: CoffeeScript
+ - Aliases:
+ - common-lisp
+ - cl
+ - lisp
+ Name: Common Lisp
+ - Aliases:
+ - coq
+ Name: Coq
+ - Aliases:
+ - cr
+ - crystal
+ Name: Crystal
+ - Aliases:
+ - css
+ Name: CSS
+ - Aliases:
+ - cue
+ Name: CUE
+ - Aliases:
+ - cython
+ - pyx
+ - pyrex
+ Name: Cython
+ - Aliases:
+ - d
+ Name: D
+ - Aliases:
+ - dart
+ Name: Dart
+ - Aliases:
+ - dax
+ Name: Dax
+ - Aliases:
+ - desktop
+ - desktop_entry
+ Name: Desktop file
+ - Aliases:
+ - diff
+ - udiff
+ Name: Diff
+ - Aliases:
+ - django
+ - jinja
+ Name: Django/Jinja
+ - Aliases:
+ - zone
+ - bind
+ Name: dns
+ - Aliases:
+ - docker
+ - dockerfile
+ Name: Docker
+ - Aliases:
+ - dtd
+ Name: DTD
+ - Aliases:
+ - dylan
+ Name: Dylan
+ - Aliases:
+ - ebnf
+ Name: EBNF
+ - Aliases:
+ - elixir
+ - ex
+ - exs
+ Name: Elixir
+ - Aliases:
+ - elm
+ Name: Elm
+ - Aliases:
+ - emacs
+ - elisp
+ - emacs-lisp
+ Name: EmacsLisp
+ - Aliases:
+ - erlang
+ Name: Erlang
+ - Aliases:
+ - factor
+ Name: Factor
+ - Aliases:
+ - fennel
+ - fnl
+ Name: Fennel
+ - Aliases:
+ - fish
+ - fishshell
+ Name: Fish
+ - Aliases:
+ - forth
+ Name: Forth
+ - Aliases:
+ - fortran
+ - f90
+ Name: Fortran
+ - Aliases:
+ - fortranfixed
+ Name: FortranFixed
+ - Aliases:
+ - fsharp
+ Name: FSharp
+ - Aliases:
+ - gas
+ - asm
+ Name: GAS
+ - Aliases:
+ - gdscript
+ - gd
+ Name: GDScript
+ - Aliases:
+ - gdscript3
+ - gd3
+ Name: GDScript3
+ - Aliases:
+ - genshi
+ - kid
+ - xml+genshi
+ - xml+kid
+ Name: Genshi
+ - Aliases:
+ - html+genshi
+ - html+kid
+ Name: Genshi HTML
+ - Aliases:
+ - genshitext
+ Name: Genshi Text
+ - Aliases:
+ - cucumber
+ - Cucumber
+ - gherkin
+ - Gherkin
+ Name: Gherkin
- delete:
- enable: false
+ - Aliases:
+ - glsl
+ Name: GLSL
+ - Aliases:
+ - gnuplot
+ Name: Gnuplot
+ - Aliases:
+ - go
+ - golang
+ Name: Go
+ - Aliases:
+ - go-html-template
+ Name: Go HTML Template
+ - Aliases:
+ - go-template
+ Name: Go Template
+ - Aliases:
+ - go-text-template
+ Name: Go Text Template
+ - Aliases:
+ - graphql
+ - graphqls
+ - gql
+ Name: GraphQL
+ - Aliases:
+ - groff
+ - nroff
+ - man
+ Name: Groff
+ - Aliases:
+ - groovy
+ Name: Groovy
+ - Aliases:
+ - handlebars
+ - hbs
+ Name: Handlebars
+ - Aliases:
+ - hare
+ Name: Hare
+ - Aliases:
+ - haskell
+ - hs
+ Name: Haskell
+ - Aliases:
+ - hx
+ - haxe
+ - hxsl
+ Name: Haxe
+ - Aliases:
+ - hcl
+ Name: HCL
+ - Aliases:
+ - hexdump
+ Name: Hexdump
+ - Aliases:
+ - hlb
+ Name: HLB
+ - Aliases:
+ - hlsl
+ Name: HLSL
+ - Aliases:
+ - holyc
+ Name: HolyC
+ - Aliases:
+ - html
+ Name: HTML
+ - Aliases:
+ - http
+ Name: HTTP
+ - Aliases:
+ - hylang
+ Name: Hy
+ - Aliases:
+ - idris
+ - idr
+ Name: Idris
+ - Aliases:
+ - igor
+ - igorpro
+ Name: Igor
+ - Aliases:
+ - ini
+ - cfg
+ - dosini
+ Name: INI
+ - Aliases:
+ - io
+ Name: Io
+ - Aliases:
+ - iscdhcpd
+ Name: ISCdhcpd
+ - Aliases:
+ - j
+ Name: J
+ - Aliases:
+ - java
+ Name: Java
+ - Aliases:
+ - js
+ - javascript
+ Name: JavaScript
+ - Aliases:
+ - json
+ Name: JSON
+ - Aliases:
+ - julia
+ - jl
+ Name: Julia
+ - Aliases:
+ - jungle
+ Name: Jungle
+ - Aliases:
+ - kotlin
+ Name: Kotlin
+ - Aliases:
+ - lighty
+ - lighttpd
+ Name: Lighttpd configuration file
+ - Aliases:
+ - llvm
+ Name: LLVM
+ - Aliases:
+ - lua
+ Name: Lua
+ - Aliases:
+ - make
+ - makefile
+ - mf
+ - bsdmake
+ Name: Makefile
+ - Aliases:
+ - mako
+ Name: Mako
+ - Aliases:
+ - md
+ - mkd
+ Name: markdown
+ - Aliases:
+ - mason
+ Name: Mason
+ - Aliases:
+ - materialize
+ - mzsql
+ Name: Materialize SQL dialect
+ - Aliases:
+ - mathematica
+ - mma
+ - nb
+ Name: Mathematica
+ - Aliases:
+ - matlab
+ Name: Matlab
+ - Aliases:
+ - mcfunction
+ Name: mcfunction
+ - Aliases:
+ - meson
+ - meson.build
+ Name: Meson
+ - Aliases:
+ - metal
+ Name: Metal
+ - Aliases:
+ - minizinc
+ - MZN
+ - mzn
+ Name: MiniZinc
+ - Aliases:
+ - mlir
+ Name: MLIR
+ - Aliases:
+ - modula2
+ - m2
+ Name: Modula-2
+ - Aliases:
+ - monkeyc
+ Name: MonkeyC
+ - Aliases:
+ - morrowind
+ - mwscript
+ Name: MorrowindScript
+ - Aliases:
+ - myghty
+ Name: Myghty
+ - Aliases:
+ - mysql
+ - mariadb
+ Name: MySQL
+ - Aliases:
+ - nasm
+ Name: NASM
+ - Aliases:
+ - natural
+ Name: Natural
+ - Aliases:
+ - ndisasm
+ Name: NDISASM
+ - Aliases:
+ - newspeak
+ Name: Newspeak
+ - Aliases:
+ - nginx
+ Name: Nginx configuration file
+ - Aliases:
+ - nim
+ - nimrod
+ Name: Nim
+ - Aliases:
+ - nixos
+ - nix
+ Name: Nix
+ - Aliases:
+ - objective-c
+ - objectivec
+ - obj-c
+ - objc
+ Name: Objective-C
+ - Aliases:
+ - objectpascal
+ Name: ObjectPascal
+ - Aliases:
+ - ocaml
+ Name: OCaml
+ - Aliases:
+ - octave
+ Name: Octave
+ - Aliases:
+ - odin
+ Name: Odin
+ - Aliases:
+ - ones
+ - onesenterprise
+ - 1S
+ - 1S:Enterprise
+ Name: OnesEnterprise
+ - Aliases:
+ - openedge
+ - abl
+ - progress
+ - openedgeabl
+ Name: OpenEdge ABL
+ - Aliases:
+ - openscad
+ Name: OpenSCAD
+ - Aliases:
+ - org
+ - orgmode
+ Name: Org Mode
+ - Aliases:
+ - pacmanconf
+ Name: PacmanConf
+ - Aliases:
+ - perl
+ - pl
+ Name: Perl
+ - Aliases:
+ - php
+ - php3
+ - php4
+ - php5
+ Name: PHP
+ - Aliases:
+ - phtml
+ Name: PHTML
+ - Aliases:
+ - pig
+ Name: Pig
+ - Aliases:
+ - pkgconfig
+ Name: PkgConfig
+ - Aliases:
+ - plpgsql
+ Name: PL/pgSQL
+ - Aliases:
+ - text
+ - plain
+ - no-highlight
+ Name: plaintext
+ - Aliases:
+ - plutus-core
+ - plc
+ Name: Plutus Core
+ - Aliases:
+ - pony
+ Name: Pony
+ - Aliases:
+ - postgresql
+ - postgres
+ Name: PostgreSQL SQL dialect
+ - Aliases:
+ - postscript
+ - postscr
+ Name: PostScript
+ - Aliases:
+ - pov
+ Name: POVRay
+ - Aliases:
+ - powerquery
+ - pq
+ Name: PowerQuery
+ - Aliases:
+ - powershell
+ - posh
+ - ps1
+ - psm1
+ - psd1
+ - pwsh
+ Name: PowerShell
+ - Aliases:
+ - prolog
+ Name: Prolog
+ - Aliases:
+ - promela
+ Name: Promela
+ - Aliases:
+ - promql
+ Name: PromQL
+ - Aliases:
+ - java-properties
+ Name: properties
+ - Aliases:
+ - protobuf
+ - proto
+ Name: Protocol Buffer
+ - Aliases:
+ - prql
+ Name: PRQL
+ - Aliases:
+ - psl
+ Name: PSL
+ - Aliases:
+ - puppet
+ Name: Puppet
+ - Aliases:
+ - python
+ - py
+ - sage
+ - python3
+ - py3
+ Name: Python
+ - Aliases:
+ - python2
+ - py2
+ Name: Python 2
+ - Aliases:
+ - qbasic
+ - basic
+ Name: QBasic
+ - Aliases:
+ - qml
+ - qbs
+ Name: QML
+ - Aliases:
+ - splus
+ - s
+ - r
+ Name: R
+ - Aliases:
+ - racket
+ - rkt
+ Name: Racket
+ - Aliases:
+ - ragel
+ Name: Ragel
+ - Aliases:
+ - perl6
+ - pl6
+ - raku
+ Name: Raku
+ - Aliases:
+ - jsx
+ - react
+ Name: react
+ - Aliases:
+ - reason
+ - reasonml
+ Name: ReasonML
+ - Aliases:
+ - registry
+ Name: reg
+ - Aliases:
+ - rego
+ Name: Rego
+ - Aliases:
+ - rst
+ - rest
+ - restructuredtext
+ Name: reStructuredText
+ - Aliases:
+ - rexx
+ - arexx
+ Name: Rexx
+ - Aliases:
+ - spec
+ Name: RPMSpec
+ - Aliases:
+ - rb
+ - ruby
+ - duby
+ Name: Ruby
+ - Aliases:
+ - rust
+ - rs
+ Name: Rust
+ - Aliases:
+ - sas
+ Name: SAS
+ - Aliases:
+ - sass
+ Name: Sass
+ - Aliases:
+ - scala
+ Name: Scala
+ - Aliases:
+ - scheme
+ - scm
+ Name: Scheme
+ - Aliases:
+ - scilab
+ Name: Scilab
+ - Aliases:
+ - scss
+ Name: SCSS
+ - Aliases:
+ - sed
+ - gsed
+ - ssed
+ Name: Sed
+ - Aliases:
+ - sieve
+ Name: Sieve
+ - Aliases:
+ - smali
+ Name: Smali
+ - Aliases:
+ - smalltalk
+ - squeak
+ - st
+ Name: Smalltalk
+ - Aliases:
+ - smarty
+ Name: Smarty
+ - Aliases:
+ - snobol
+ Name: Snobol
+ - Aliases:
+ - sol
+ - solidity
+ Name: Solidity
+ - Aliases:
+ - sp
+ Name: SourcePawn
+ - Aliases:
+ - sparql
+ Name: SPARQL
+ - Aliases:
+ - sql
+ Name: SQL
+ - Aliases:
+ - squidconf
+ - squid.conf
+ - squid
+ Name: SquidConf
+ - Aliases:
+ - sml
+ Name: Standard ML
+ - Aliases: null
+ Name: stas
+ - Aliases:
+ - stylus
+ Name: Stylus
+ - Aliases:
+ - svelte
+ Name: Svelte
+ - Aliases:
+ - swift
+ Name: Swift
+ - Aliases:
+ - systemd
+ Name: SYSTEMD
+ - Aliases:
+ - systemverilog
+ - sv
+ Name: systemverilog
+ - Aliases:
+ - tablegen
+ Name: TableGen
+ - Aliases:
+ - tal
+ - uxntal
+ Name: Tal
+ - Aliases:
+ - tasm
+ Name: TASM
+ - Aliases:
+ - tcl
+ Name: Tcl
+ - Aliases:
+ - tcsh
+ - csh
+ Name: Tcsh
+ - Aliases:
+ - termcap
+ Name: Termcap
+ - Aliases:
+ - terminfo
+ Name: Terminfo
+ - Aliases:
+ - terraform
+ - tf
+ Name: Terraform
+ - Aliases:
+ - tex
+ - latex
+ Name: TeX
+ - Aliases:
+ - thrift
+ Name: Thrift
+ - Aliases:
+ - toml
+ Name: TOML
+ - Aliases:
+ - tradingview
+ - tv
+ Name: TradingView
+ - Aliases:
+ - tsql
+ - t-sql
+ Name: Transact-SQL
+ - Aliases:
+ - turing
+ Name: Turing
+ - Aliases:
+ - turtle
+ Name: Turtle
+ - Aliases:
+ - twig
+ Name: Twig
+ - Aliases:
+ - ts
+ - tsx
+ - typescript
+ Name: TypeScript
+ - Aliases:
+ - typoscript
+ Name: TypoScript
+ - Aliases:
+ - typoscriptcssdata
+ Name: TypoScriptCssData
+ - Aliases:
+ - typoscripthtmldata
+ Name: TypoScriptHtmlData
+ - Aliases: null
+ Name: ucode
+ - Aliases:
+ - v
+ - vlang
+ Name: V
+ - Aliases:
+ - vsh
+ - vshell
+ Name: V shell
+ - Aliases:
+ - vala
+ - vapi
+ Name: Vala
+ - Aliases:
+ - vb.net
+ - vbnet
+ Name: VB.net
+ - Aliases:
+ - verilog
+ - v
+ Name: verilog
+ - Aliases:
+ - vhdl
+ Name: VHDL
+ - Aliases:
+ - vhs
+ - tape
+ - cassette
+ Name: VHS
+ - Aliases:
+ - vim
+ Name: VimL
+ - Aliases:
+ - vue
+ - vuejs
+ Name: vue
+ - Aliases: null
+ Name: WDTE
+ - Aliases:
+ - wgsl
+ Name: WebGPU Shading Language
+ - Aliases:
+ - whiley
+ Name: Whiley
+ - Aliases:
+ - xml
+ Name: XML
+ - Aliases:
+ - xorg.conf
+ Name: Xorg
+ - Aliases:
+ - yaml
+ Name: YAML
+ - Aliases:
+ - yang
+ Name: YANG
+ - Aliases:
+ - z80
+ Name: Z80 Assembly
+ - Aliases:
+ - zed
+ Name: Zed
+ - Aliases:
+ - zig
+ Name: Zig
+config:
+ HTTPCache:
+ cache:
+ for:
+ excludes:
+ - '**'
+ includes: null
+ polls:
+ - disable: true
+ for:
+ excludes: null
+ includes:
+ - '**'
+ high: 0s
+ low: 0s
+ archeTypeDir: archetypes
+ assetDir: assets
+ author: {}
+ baseURL: ""
+ build:
+ buildStats:
+ disableClasses: false
+ disableIDs: false
+ disableTags: false
+ enable: false
+ cacheBusters:
+ - source: (postcss|tailwind)\.config\.js
+ target: (css|styles|scss|sass)
+ noJSConfigInAssets: false
+ useResourceCacheWhen: fallback
+ buildDrafts: false
+ buildExpired: false
+ buildFuture: false
+ cacheDir: ""
+ caches:
+ assets:
+ dir: :resourceDir/_gen
+ maxAge: -1
+ getcsv:
+ dir: :cacheDir/:project
+ maxAge: -1
+ getjson:
+ dir: :cacheDir/:project
+ maxAge: -1
+ getresource:
+ dir: :cacheDir/:project
+ maxAge: -1
+ images:
+ dir: :resourceDir/_gen
+ maxAge: -1
+ modules:
+ dir: :cacheDir/modules
+ maxAge: -1
+ canonifyURLs: false
+ capitalizeListTitles: true
+ cascade: []
+ cleanDestinationDir: false
+ contentDir: content
+ copyright: ""
+ dataDir: data
+ defaultContentLanguage: en
+ defaultContentLanguageInSubdir: false
+ deployment:
+ confirm: false
+ dryRun: false
+ force: false
+ invalidateCDN: true
+ matchers: null
+ maxDeletes: 256
+ order: null
+ target: ""
+ targets: null
+ workers: 10
+ disableAliases: false
+ disableHugoGeneratorInject: false
+ disableKinds: null
+ disableLanguages: null
+ disableLiveReload: false
+ disablePathToLower: false
+ enableEmoji: false
+ enableGitInfo: false
+ enableMissingTranslationPlaceholders: false
+ enableRobotsTXT: false
+ environment: production
+ frontmatter:
+ date:
+ - date
+ - publishdate
+ - pubdate
+ - published
+ - lastmod
+ - modified
+ expiryDate:
+ - expirydate
+ - unpublishdate
+ lastmod:
+ - :git
+ - lastmod
+ - modified
+ - date
+ - publishdate
+ - pubdate
+ - published
+ publishDate:
+ - publishdate
+ - pubdate
+ - published
+ - date
+ hasCJKLanguage: false
+ i18nDir: i18n
+ ignoreCache: false
+ ignoreFiles: []
+ ignoreLogs: null
+ ignoreVendorPaths: ""
+ imaging:
+ bgColor: '#ffffff'
+ hint: photo
+ quality: 75
+ resampleFilter: box
+ languageCode: ""
+ languages:
+ en:
+ disabled: false
+ languageCode: ""
+ languageDirection: ""
+ languageName: ""
+ title: ""
+ weight: 0
+ layoutDir: layouts
+ mainSections: null
+ markup:
+ asciidocExt:
+ attributes: {}
+ backend: html5
+ extensions: []
+ failureLevel: fatal
+ noHeaderOrFooter: true
+ preserveTOC: false
+ safeMode: unsafe
+ sectionNumbers: false
+ trace: false
+ verbose: false
+ workingFolderCurrent: false
+ defaultMarkdownHandler: goldmark
+ goldmark:
+ duplicateResourceFiles: false
+ extensions:
+ cjk:
+ eastAsianLineBreaks: false
+ eastAsianLineBreaksStyle: simple
+ enable: false
+ escapedSpace: false
+ definitionList: true
+ extras:
- paginate: 0
- paginatePath: ""
- pagination:
- disableAliases: false
- pagerSize: 10
- path: page
+ insert:
+ enable: false
+ mark:
+ enable: false
+ subscript:
+ enable: false
+ superscript:
+ enable: false
+ footnote: true
+ linkify: true
+ linkifyProtocol: https
+ passthrough:
+ delimiters:
+ block: []
+ inline: []
+ enable: false
+ strikethrough: true
+ table: true
+ taskList: true
+ typographer:
+ apostrophe: '’'
+ disable: false
+ ellipsis: '…'
+ emDash: '—'
+ enDash: '–'
+ leftAngleQuote: '«'
+ leftDoubleQuote: '“'
+ leftSingleQuote: '‘'
+ rightAngleQuote: '»'
+ rightDoubleQuote: '”'
+ rightSingleQuote: '’'
+ parser:
+ attribute:
+ block: false
+ title: true
+ autoHeadingID: true
+ autoHeadingIDType: github
+ wrapStandAloneImageWithinParagraph: true
+ renderHooks:
+ image:
+ enableDefault: false
+ link:
+ enableDefault: false
+ renderer:
+ hardWraps: false
+ unsafe: false
+ xhtml: false
+ highlight:
+ anchorLineNos: false
+ codeFences: true
+ guessSyntax: false
+ hl_Lines: ""
+ hl_inline: false
+ lineAnchors: ""
+ lineNoStart: 1
+ lineNos: false
+ lineNumbersInTable: true
+ noClasses: true
+ noHl: false
+ style: monokai
+ tabWidth: 4
+ tableOfContents:
+ endLevel: 3
+ ordered: false
+ startLevel: 2
+ mediaTypes:
+ application/json:
+ delimiter: .
+ suffixes:
+ - json
+ application/manifest+json:
+ delimiter: .
+ suffixes:
+ - webmanifest
+ application/octet-stream:
+ delimiter: .
+ application/pdf:
+ delimiter: .
+ suffixes:
+ - pdf
+ application/rss+xml:
+ delimiter: .
+ suffixes:
+ - xml
+ - rss
+ application/toml:
+ delimiter: .
+ suffixes:
+ - toml
+ application/wasm:
+ delimiter: .
+ suffixes:
+ - wasm
+ application/xml:
+ delimiter: .
+ suffixes:
+ - xml
+ application/yaml:
+ delimiter: .
+ suffixes:
+ - yaml
+ - yml
+ font/otf:
+ delimiter: .
+ suffixes:
+ - otf
+ font/ttf:
+ delimiter: .
+ suffixes:
+ - ttf
+ image/bmp:
+ delimiter: .
+ suffixes:
+ - bmp
+ image/gif:
+ delimiter: .
+ suffixes:
+ - gif
+ image/jpeg:
+ delimiter: .
+ suffixes:
+ - jpg
+ - jpeg
+ - jpe
+ - jif
+ - jfif
+ image/png:
+ delimiter: .
+ suffixes:
+ - png
+ image/svg+xml:
+ delimiter: .
+ suffixes:
+ - svg
+ image/tiff:
+ delimiter: .
+ suffixes:
+ - tif
+ - tiff
+ image/webp:
+ delimiter: .
+ suffixes:
+ - webp
+ text/asciidoc:
+ delimiter: .
+ suffixes:
+ - adoc
+ - asciidoc
+ - ad
+ text/calendar:
+ delimiter: .
+ suffixes:
+ - ics
+ text/css:
+ delimiter: .
+ suffixes:
+ - css
+ text/csv:
+ delimiter: .
+ suffixes:
+ - csv
+ text/html:
+ delimiter: .
+ suffixes:
+ - html
+ - htm
+ text/javascript:
+ delimiter: .
+ suffixes:
+ - js
+ - jsm
+ - mjs
+ text/jsx:
+ delimiter: .
+ suffixes:
+ - jsx
+ text/markdown:
+ delimiter: .
+ suffixes:
+ - md
+ - mdown
+ - markdown
+ text/org:
+ delimiter: .
+ suffixes:
+ - org
+ text/pandoc:
+ delimiter: .
+ suffixes:
+ - pandoc
+ - pdc
+ text/plain:
+ delimiter: .
+ suffixes:
+ - txt
+ text/rst:
+ delimiter: .
+ suffixes:
+ - rst
+ text/tsx:
+ delimiter: .
+ suffixes:
+ - tsx
+ text/typescript:
+ delimiter: .
+ suffixes:
+ - ts
+ text/x-sass:
+ delimiter: .
+ suffixes:
+ - sass
+ text/x-scss:
+ delimiter: .
+ suffixes:
+ - scss
+ video/3gpp:
+ delimiter: .
+ suffixes:
+ - 3gpp
+ - 3gp
+ video/mp4:
+ delimiter: .
+ suffixes:
+ - mp4
+ video/mpeg:
+ delimiter: .
+ suffixes:
+ - mpg
+ - mpeg
+ video/ogg:
+ delimiter: .
+ suffixes:
+ - ogv
+ video/webm:
+ delimiter: .
+ suffixes:
+ - webm
+ video/x-msvideo:
+ delimiter: .
+ suffixes:
+ - avi
+ menus: {}
+ minify:
+ disableCSS: false
+ disableHTML: false
+ disableJS: false
+ disableJSON: false
+ disableSVG: false
+ disableXML: false
+ minifyOutput: false
+ tdewolff:
+ css:
+ keepCSS2: true
+ precision: 0
+ html:
+ keepComments: false
+ keepConditionalComments: false
+ keepDefaultAttrVals: true
+ keepDocumentTags: true
+ keepEndTags: true
+ keepQuotes: false
+ keepSpecialComments: true
+ keepWhitespace: false
+ templateDelims:
+ - ""
+ - ""
+ js:
+ keepVarNames: false
+ precision: 0
+ version: 2022
+ json:
+ keepNumbers: false
+ precision: 0
+ svg:
+ keepComments: false
+ precision: 0
+ xml:
+ keepWhitespace: false
+ module:
+ hugoVersion:
+ extended: false
+ max: ""
+ min: ""
+ imports: null
+ mounts:
+ - excludeFiles: null
+ includeFiles: null
+ lang: ""
+ source: content
+ target: content
+ - excludeFiles: null
+ includeFiles: null
+ lang: ""
+ source: data
+ target: data
+ - excludeFiles: null
+ includeFiles: null
+ lang: ""
+ source: layouts
+ target: layouts
+ - excludeFiles: null
+ includeFiles: null
+ lang: ""
+ source: i18n
+ target: i18n
+ - excludeFiles: null
+ includeFiles: null
+ lang: ""
+ source: archetypes
+ target: archetypes
+ - excludeFiles: null
+ includeFiles: null
+ lang: ""
+ source: assets
+ target: assets
+ - excludeFiles: null
+ includeFiles: null
+ lang: ""
+ source: static
+ target: static
+ noProxy: none
+ noVendor: ""
+ params: null
+ private: '*.*'
+ proxy: direct
+ replacements: null
+ vendorClosest: false
+ workspace: "off"
+ newContentEditor: ""
+ noBuildLock: false
+ noChmod: false
+ noTimes: false
+ outputFormats:
+ amp:
+ baseName: index
+ isHTML: true
+ isPlainText: false
+ mediaType: text/html
+ noUgly: false
+ notAlternative: false
+ path: amp
+ permalinkable: true
+ protocol: ""
+ rel: amphtml
+ root: false
+ ugly: false
+ weight: 0
+ calendar:
+ baseName: index
+ isHTML: false
+ isPlainText: true
+ mediaType: text/calendar
+ noUgly: false
+ notAlternative: false
+ path: ""
+ permalinkable: false
+ protocol: webcal://
+ rel: alternate
+ root: false
+ ugly: false
+ weight: 0
+ css:
+ baseName: styles
+ isHTML: false
+ isPlainText: true
+ mediaType: text/css
+ noUgly: false
+ notAlternative: true
+ path: ""
+ permalinkable: false
+ protocol: ""
+ rel: stylesheet
+ root: false
+ ugly: false
+ weight: 0
+ csv:
+ baseName: index
+ isHTML: false
+ isPlainText: true
+ mediaType: text/csv
+ noUgly: false
+ notAlternative: false
+ path: ""
+ permalinkable: false
+ protocol: ""
+ rel: alternate
+ root: false
+ ugly: false
+ weight: 0
+ html:
+ baseName: index
+ isHTML: true
+ isPlainText: false
+ mediaType: text/html
+ noUgly: false
+ notAlternative: false
+ path: ""
+ permalinkable: true
+ protocol: ""
+ rel: canonical
+ root: false
+ ugly: false
+ weight: 10
+ json:
+ baseName: index
+ isHTML: false
+ isPlainText: true
+ mediaType: application/json
+ noUgly: false
+ notAlternative: false
+ path: ""
+ permalinkable: false
+ protocol: ""
+ rel: alternate
+ root: false
+ ugly: false
+ weight: 0
+ markdown:
+ baseName: index
+ isHTML: false
+ isPlainText: true
+ mediaType: text/markdown
+ noUgly: false
+ notAlternative: false
+ path: ""
+ permalinkable: false
+ protocol: ""
+ rel: alternate
+ root: false
+ ugly: false
+ weight: 0
+ robots:
+ baseName: robots
+ isHTML: false
+ isPlainText: true
+ mediaType: text/plain
+ noUgly: false
+ notAlternative: false
+ path: ""
+ permalinkable: false
+ protocol: ""
+ rel: alternate
+ root: true
+ ugly: false
+ weight: 0
+ rss:
+ baseName: index
+ isHTML: false
+ isPlainText: false
+ mediaType: application/rss+xml
+ noUgly: true
+ notAlternative: false
+ path: ""
+ permalinkable: false
+ protocol: ""
+ rel: alternate
+ root: false
+ ugly: false
+ weight: 0
+ sitemap:
+ baseName: sitemap
+ isHTML: false
+ isPlainText: false
+ mediaType: application/xml
+ noUgly: false
+ notAlternative: false
+ path: ""
+ permalinkable: false
+ protocol: ""
+ rel: sitemap
+ root: false
+ ugly: true
+ weight: 0
+ webappmanifest:
+ baseName: manifest
+ isHTML: false
+ isPlainText: true
+ mediaType: application/manifest+json
+ noUgly: false
+ notAlternative: true
+ path: ""
+ permalinkable: false
+ protocol: ""
+ rel: manifest
+ root: false
+ ugly: false
+ weight: 0
+ outputs:
+ home:
+ - html
+ - rss
+ page:
+ - html
+ rss:
+ - rss
+ section:
+ - html
+ - rss
+ taxonomy:
+ - html
+ - rss
+ term:
+ - html
+ - rss
- pagination:
- _merge: none
++ paginate: 10
++ paginatePath: page
+ panicOnWarning: false
+ params: {}
+ permalinks:
+ page: {}
+ section: {}
+ taxonomy: {}
+ term: {}
+ pluralizeListTitles: true
+ printI18nWarnings: false
+ printPathWarnings: false
+ printUnusedTemplates: false
+ privacy:
+ disqus:
+ disable: false
+ googleAnalytics:
+ disable: false
+ respectDoNotTrack: false
+ instagram:
+ disable: false
+ simple: false
+ twitter:
+ disable: false
+ enableDNT: false
+ simple: false
+ vimeo:
+ disable: false
+ enableDNT: false
+ simple: false
+ youTube:
+ disable: false
+ privacyEnhanced: false
+ publishDir: public
+ refLinksErrorLevel: ""
+ refLinksNotFoundURL: ""
+ related:
+ includeNewer: false
+ indices:
+ - applyFilter: false
+ cardinalityThreshold: 0
+ name: keywords
+ pattern: ""
+ toLower: false
+ type: basic
+ weight: 100
+ - applyFilter: false
+ cardinalityThreshold: 0
+ name: date
+ pattern: ""
+ toLower: false
+ type: basic
+ weight: 10
+ - applyFilter: false
+ cardinalityThreshold: 0
+ name: tags
+ pattern: ""
+ toLower: false
+ type: basic
+ weight: 80
+ threshold: 80
+ toLower: false
+ relativeURLs: false
+ removePathAccents: false
+ renderSegments: null
+ resourceDir: resources
+ sectionPagesMenu: ""
+ security:
+ enableInlineShortcodes: false
+ exec:
+ allow:
+ - ^(dart-)?sass(-embedded)?$
+ - ^go$
+ - ^npx$
+ - ^postcss$
+ osEnv:
+ - (?i)^((HTTPS?|NO)_PROXY|PATH(EXT)?|APPDATA|TE?MP|TERM|GO\w+|(XDG_CONFIG_)?HOME|USERPROFILE|SSH_AUTH_SOCK|DISPLAY|LANG|SYSTEMDRIVE)$
+ funcs:
+ getenv:
+ - ^HUGO_
+ - ^CI$
+ http:
+ mediaTypes: null
+ methods:
+ - (?i)GET|POST
+ urls:
+ - .*
+ segments: {}
+ server:
+ headers: null
+ redirects:
+ - force: false
+ from: '**'
+ status: 404
+ to: /404.html
+ services:
+ disqus:
+ shortname: ""
+ googleAnalytics:
+ id: ""
+ instagram:
+ accessToken: ""
+ disableInlineCSS: false
+ rss:
+ limit: -1
+ twitter:
+ disableInlineCSS: false
+ sitemap:
+ changeFreq: ""
+ disable: false
+ filename: sitemap.xml
+ priority: -1
+ social: null
+ staticDir:
+ - static
+ staticDir0: null
+ staticDir1: null
+ staticDir2: null
+ staticDir3: null
+ staticDir4: null
+ staticDir5: null
+ staticDir6: null
+ staticDir7: null
+ staticDir8: null
+ staticDir9: null
+ staticDir10: null
+ summaryLength: 70
+ taxonomies:
+ category: categories
+ tag: tags
+ templateMetrics: false
+ templateMetricsHints: false
+ theme: null
+ themesDir: themes
+ timeZone: ""
+ timeout: 30s
+ title: ""
+ titleCaseStyle: AP
+ uglyURLs: false
+ workingDir: ""
+config_helpers:
+ mergeStrategy:
+ build:
+ _merge: none
+ caches:
+ _merge: none
+ cascade:
+ _merge: none
+ deployment:
+ _merge: none
+ frontmatter:
+ _merge: none
+ httpcache:
+ _merge: none
+ imaging:
+ _merge: none
+ languages:
+ _merge: none
+ en:
+ _merge: none
+ menus:
+ _merge: shallow
+ params:
+ _merge: deep
+ markup:
+ _merge: none
+ mediatypes:
+ _merge: shallow
+ menus:
+ _merge: shallow
+ minify:
+ _merge: none
+ module:
+ _merge: none
+ outputformats:
+ _merge: shallow
+ outputs:
+ _merge: none
+ params:
+ _merge: deep
+ permalinks:
+ _merge: none
+ privacy:
+ _merge: none
+ related:
+ _merge: none
+ security:
+ _merge: none
+ segments:
+ _merge: none
+ server:
+ _merge: none
+ services:
+ _merge: none
+ sitemap:
+ _merge: none
+ taxonomies:
+ _merge: none
+output:
+ layouts:
+ - Example: Single page in "posts" section
+ Kind: page
+ OutputFormat: html
+ Suffix: html
+ Template Lookup Order:
+ - layouts/posts/single.html.html
+ - layouts/posts/single.html
+ - layouts/_default/single.html.html
+ - layouts/_default/single.html
+ - Example: Base template for single page in "posts" section
+ Kind: page
+ OutputFormat: html
+ Suffix: html
+ Template Lookup Order:
+ - layouts/posts/single-baseof.html.html
+ - layouts/posts/baseof.html.html
+ - layouts/posts/single-baseof.html
+ - layouts/posts/baseof.html
+ - layouts/_default/single-baseof.html.html
+ - layouts/_default/baseof.html.html
+ - layouts/_default/single-baseof.html
+ - layouts/_default/baseof.html
+ - Example: Single page in "posts" section with layout set to "demolayout"
+ Kind: page
+ OutputFormat: html
+ Suffix: html
+ Template Lookup Order:
+ - layouts/posts/demolayout.html.html
+ - layouts/posts/single.html.html
+ - layouts/posts/demolayout.html
+ - layouts/posts/single.html
+ - layouts/_default/demolayout.html.html
+ - layouts/_default/single.html.html
+ - layouts/_default/demolayout.html
+ - layouts/_default/single.html
+ - Example: Base template for single page in "posts" section with layout set to "demolayout"
+ Kind: page
+ OutputFormat: html
+ Suffix: html
+ Template Lookup Order:
+ - layouts/posts/demolayout-baseof.html.html
+ - layouts/posts/single-baseof.html.html
+ - layouts/posts/baseof.html.html
+ - layouts/posts/demolayout-baseof.html
+ - layouts/posts/single-baseof.html
+ - layouts/posts/baseof.html
+ - layouts/_default/demolayout-baseof.html.html
+ - layouts/_default/single-baseof.html.html
+ - layouts/_default/baseof.html.html
+ - layouts/_default/demolayout-baseof.html
+ - layouts/_default/single-baseof.html
+ - layouts/_default/baseof.html
+ - Example: AMP single page
+ Kind: page
+ OutputFormat: amp
+ Suffix: html
+ Template Lookup Order:
+ - layouts/posts/single.amp.html
+ - layouts/posts/single.html
+ - layouts/_default/single.amp.html
+ - layouts/_default/single.html
+ - Example: AMP single page, French language
+ Kind: page
+ OutputFormat: html
+ Suffix: html
+ Template Lookup Order:
+ - layouts/posts/single.fr.html.html
+ - layouts/posts/single.html.html
+ - layouts/posts/single.fr.html
+ - layouts/posts/single.html
+ - layouts/_default/single.fr.html.html
+ - layouts/_default/single.html.html
+ - layouts/_default/single.fr.html
+ - layouts/_default/single.html
+ - Example: Home page
+ Kind: home
+ OutputFormat: html
+ Suffix: html
+ Template Lookup Order:
+ - layouts/index.html.html
+ - layouts/home.html.html
+ - layouts/list.html.html
+ - layouts/index.html
+ - layouts/home.html
+ - layouts/list.html
+ - layouts/_default/index.html.html
+ - layouts/_default/home.html.html
+ - layouts/_default/list.html.html
+ - layouts/_default/index.html
+ - layouts/_default/home.html
+ - layouts/_default/list.html
+ - Example: Base template for home page
+ Kind: home
+ OutputFormat: html
+ Suffix: html
+ Template Lookup Order:
+ - layouts/index-baseof.html.html
+ - layouts/home-baseof.html.html
+ - layouts/list-baseof.html.html
+ - layouts/baseof.html.html
+ - layouts/index-baseof.html
+ - layouts/home-baseof.html
+ - layouts/list-baseof.html
+ - layouts/baseof.html
+ - layouts/_default/index-baseof.html.html
+ - layouts/_default/home-baseof.html.html
+ - layouts/_default/list-baseof.html.html
+ - layouts/_default/baseof.html.html
+ - layouts/_default/index-baseof.html
+ - layouts/_default/home-baseof.html
+ - layouts/_default/list-baseof.html
+ - layouts/_default/baseof.html
+ - Example: Home page with type set to "demotype"
+ Kind: home
+ OutputFormat: html
+ Suffix: html
+ Template Lookup Order:
+ - layouts/demotype/index.html.html
+ - layouts/demotype/home.html.html
+ - layouts/demotype/list.html.html
+ - layouts/demotype/index.html
+ - layouts/demotype/home.html
+ - layouts/demotype/list.html
+ - layouts/index.html.html
+ - layouts/home.html.html
+ - layouts/list.html.html
+ - layouts/index.html
+ - layouts/home.html
+ - layouts/list.html
+ - layouts/_default/index.html.html
+ - layouts/_default/home.html.html
+ - layouts/_default/list.html.html
+ - layouts/_default/index.html
+ - layouts/_default/home.html
+ - layouts/_default/list.html
+ - Example: Base template for home page with type set to "demotype"
+ Kind: home
+ OutputFormat: html
+ Suffix: html
+ Template Lookup Order:
+ - layouts/demotype/index-baseof.html.html
+ - layouts/demotype/home-baseof.html.html
+ - layouts/demotype/list-baseof.html.html
+ - layouts/demotype/baseof.html.html
+ - layouts/demotype/index-baseof.html
+ - layouts/demotype/home-baseof.html
+ - layouts/demotype/list-baseof.html
+ - layouts/demotype/baseof.html
+ - layouts/index-baseof.html.html
+ - layouts/home-baseof.html.html
+ - layouts/list-baseof.html.html
+ - layouts/baseof.html.html
+ - layouts/index-baseof.html
+ - layouts/home-baseof.html
+ - layouts/list-baseof.html
+ - layouts/baseof.html
+ - layouts/_default/index-baseof.html.html
+ - layouts/_default/home-baseof.html.html
+ - layouts/_default/list-baseof.html.html
+ - layouts/_default/baseof.html.html
+ - layouts/_default/index-baseof.html
+ - layouts/_default/home-baseof.html
+ - layouts/_default/list-baseof.html
+ - layouts/_default/baseof.html
+ - Example: Home page with layout set to "demolayout"
+ Kind: home
+ OutputFormat: html
+ Suffix: html
+ Template Lookup Order:
+ - layouts/demolayout.html.html
+ - layouts/index.html.html
+ - layouts/home.html.html
+ - layouts/list.html.html
+ - layouts/demolayout.html
+ - layouts/index.html
+ - layouts/home.html
+ - layouts/list.html
+ - layouts/_default/demolayout.html.html
+ - layouts/_default/index.html.html
+ - layouts/_default/home.html.html
+ - layouts/_default/list.html.html
+ - layouts/_default/demolayout.html
+ - layouts/_default/index.html
+ - layouts/_default/home.html
+ - layouts/_default/list.html
+ - Example: AMP home, French language
+ Kind: home
+ OutputFormat: amp
+ Suffix: html
+ Template Lookup Order:
+ - layouts/index.fr.amp.html
+ - layouts/home.fr.amp.html
+ - layouts/list.fr.amp.html
+ - layouts/index.amp.html
+ - layouts/home.amp.html
+ - layouts/list.amp.html
+ - layouts/index.fr.html
+ - layouts/home.fr.html
+ - layouts/list.fr.html
+ - layouts/index.html
+ - layouts/home.html
+ - layouts/list.html
+ - layouts/_default/index.fr.amp.html
+ - layouts/_default/home.fr.amp.html
+ - layouts/_default/list.fr.amp.html
+ - layouts/_default/index.amp.html
+ - layouts/_default/home.amp.html
+ - layouts/_default/list.amp.html
+ - layouts/_default/index.fr.html
+ - layouts/_default/home.fr.html
+ - layouts/_default/list.fr.html
+ - layouts/_default/index.html
+ - layouts/_default/home.html
+ - layouts/_default/list.html
+ - Example: JSON home
+ Kind: home
+ OutputFormat: json
+ Suffix: json
+ Template Lookup Order:
+ - layouts/index.json.json
+ - layouts/home.json.json
+ - layouts/list.json.json
+ - layouts/index.json
+ - layouts/home.json
+ - layouts/list.json
+ - layouts/_default/index.json.json
+ - layouts/_default/home.json.json
+ - layouts/_default/list.json.json
+ - layouts/_default/index.json
+ - layouts/_default/home.json
+ - layouts/_default/list.json
+ - Example: RSS home
+ Kind: home
+ OutputFormat: rss
+ Suffix: xml
+ Template Lookup Order:
+ - layouts/index.rss.xml
+ - layouts/home.rss.xml
+ - layouts/rss.xml
+ - layouts/list.rss.xml
+ - layouts/index.xml
+ - layouts/home.xml
+ - layouts/list.xml
+ - layouts/_default/index.rss.xml
+ - layouts/_default/home.rss.xml
+ - layouts/_default/rss.xml
+ - layouts/_default/list.rss.xml
+ - layouts/_default/index.xml
+ - layouts/_default/home.xml
+ - layouts/_default/list.xml
+ - layouts/_internal/_default/rss.xml
+ - Example: Section list for "posts"
+ Kind: section
+ OutputFormat: html
+ Suffix: html
+ Template Lookup Order:
+ - layouts/posts/posts.html.html
+ - layouts/posts/section.html.html
+ - layouts/posts/list.html.html
+ - layouts/posts/posts.html
+ - layouts/posts/section.html
+ - layouts/posts/list.html
+ - layouts/section/posts.html.html
+ - layouts/section/section.html.html
+ - layouts/section/list.html.html
+ - layouts/section/posts.html
+ - layouts/section/section.html
+ - layouts/section/list.html
+ - layouts/_default/posts.html.html
+ - layouts/_default/section.html.html
+ - layouts/_default/list.html.html
+ - layouts/_default/posts.html
+ - layouts/_default/section.html
+ - layouts/_default/list.html
+ - Example: Section list for "posts" with type set to "blog"
+ Kind: section
+ OutputFormat: html
+ Suffix: html
+ Template Lookup Order:
+ - layouts/blog/posts.html.html
+ - layouts/blog/section.html.html
+ - layouts/blog/list.html.html
+ - layouts/blog/posts.html
+ - layouts/blog/section.html
+ - layouts/blog/list.html
+ - layouts/posts/posts.html.html
+ - layouts/posts/section.html.html
+ - layouts/posts/list.html.html
+ - layouts/posts/posts.html
+ - layouts/posts/section.html
+ - layouts/posts/list.html
+ - layouts/section/posts.html.html
+ - layouts/section/section.html.html
+ - layouts/section/list.html.html
+ - layouts/section/posts.html
+ - layouts/section/section.html
+ - layouts/section/list.html
+ - layouts/_default/posts.html.html
+ - layouts/_default/section.html.html
+ - layouts/_default/list.html.html
+ - layouts/_default/posts.html
+ - layouts/_default/section.html
+ - layouts/_default/list.html
+ - Example: Section list for "posts" with layout set to "demolayout"
+ Kind: section
+ OutputFormat: html
+ Suffix: html
+ Template Lookup Order:
+ - layouts/posts/demolayout.html.html
+ - layouts/posts/posts.html.html
+ - layouts/posts/section.html.html
+ - layouts/posts/list.html.html
+ - layouts/posts/demolayout.html
+ - layouts/posts/posts.html
+ - layouts/posts/section.html
+ - layouts/posts/list.html
+ - layouts/section/demolayout.html.html
+ - layouts/section/posts.html.html
+ - layouts/section/section.html.html
+ - layouts/section/list.html.html
+ - layouts/section/demolayout.html
+ - layouts/section/posts.html
+ - layouts/section/section.html
+ - layouts/section/list.html
+ - layouts/_default/demolayout.html.html
+ - layouts/_default/posts.html.html
+ - layouts/_default/section.html.html
+ - layouts/_default/list.html.html
+ - layouts/_default/demolayout.html
+ - layouts/_default/posts.html
+ - layouts/_default/section.html
+ - layouts/_default/list.html
+ - Example: Section list for "posts"
+ Kind: section
+ OutputFormat: rss
+ Suffix: xml
+ Template Lookup Order:
+ - layouts/posts/section.rss.xml
+ - layouts/posts/rss.xml
+ - layouts/posts/list.rss.xml
+ - layouts/posts/section.xml
+ - layouts/posts/list.xml
+ - layouts/section/section.rss.xml
+ - layouts/section/rss.xml
+ - layouts/section/list.rss.xml
+ - layouts/section/section.xml
+ - layouts/section/list.xml
+ - layouts/_default/section.rss.xml
+ - layouts/_default/rss.xml
+ - layouts/_default/list.rss.xml
+ - layouts/_default/section.xml
+ - layouts/_default/list.xml
+ - layouts/_internal/_default/rss.xml
+ - Example: Taxonomy list for "categories"
+ Kind: taxonomy
+ OutputFormat: html
+ Suffix: html
+ Template Lookup Order:
+ - layouts/categories/category.terms.html.html
+ - layouts/categories/terms.html.html
+ - layouts/categories/taxonomy.html.html
+ - layouts/categories/list.html.html
+ - layouts/categories/category.terms.html
+ - layouts/categories/terms.html
+ - layouts/categories/taxonomy.html
+ - layouts/categories/list.html
+ - layouts/category/category.terms.html.html
+ - layouts/category/terms.html.html
+ - layouts/category/taxonomy.html.html
+ - layouts/category/list.html.html
+ - layouts/category/category.terms.html
+ - layouts/category/terms.html
+ - layouts/category/taxonomy.html
+ - layouts/category/list.html
+ - layouts/taxonomy/category.terms.html.html
+ - layouts/taxonomy/terms.html.html
+ - layouts/taxonomy/taxonomy.html.html
+ - layouts/taxonomy/list.html.html
+ - layouts/taxonomy/category.terms.html
+ - layouts/taxonomy/terms.html
+ - layouts/taxonomy/taxonomy.html
+ - layouts/taxonomy/list.html
+ - layouts/_default/category.terms.html.html
+ - layouts/_default/terms.html.html
+ - layouts/_default/taxonomy.html.html
+ - layouts/_default/list.html.html
+ - layouts/_default/category.terms.html
+ - layouts/_default/terms.html
+ - layouts/_default/taxonomy.html
+ - layouts/_default/list.html
+ - Example: Taxonomy list for "categories"
+ Kind: taxonomy
+ OutputFormat: rss
+ Suffix: xml
+ Template Lookup Order:
+ - layouts/categories/category.terms.rss.xml
+ - layouts/categories/terms.rss.xml
+ - layouts/categories/taxonomy.rss.xml
+ - layouts/categories/rss.xml
+ - layouts/categories/list.rss.xml
+ - layouts/categories/category.terms.xml
+ - layouts/categories/terms.xml
+ - layouts/categories/taxonomy.xml
+ - layouts/categories/list.xml
+ - layouts/category/category.terms.rss.xml
+ - layouts/category/terms.rss.xml
+ - layouts/category/taxonomy.rss.xml
+ - layouts/category/rss.xml
+ - layouts/category/list.rss.xml
+ - layouts/category/category.terms.xml
+ - layouts/category/terms.xml
+ - layouts/category/taxonomy.xml
+ - layouts/category/list.xml
+ - layouts/taxonomy/category.terms.rss.xml
+ - layouts/taxonomy/terms.rss.xml
+ - layouts/taxonomy/taxonomy.rss.xml
+ - layouts/taxonomy/rss.xml
+ - layouts/taxonomy/list.rss.xml
+ - layouts/taxonomy/category.terms.xml
+ - layouts/taxonomy/terms.xml
+ - layouts/taxonomy/taxonomy.xml
+ - layouts/taxonomy/list.xml
+ - layouts/_default/category.terms.rss.xml
+ - layouts/_default/terms.rss.xml
+ - layouts/_default/taxonomy.rss.xml
+ - layouts/_default/rss.xml
+ - layouts/_default/list.rss.xml
+ - layouts/_default/category.terms.xml
+ - layouts/_default/terms.xml
+ - layouts/_default/taxonomy.xml
+ - layouts/_default/list.xml
+ - layouts/_internal/_default/rss.xml
+ - Example: Term list for "categories"
+ Kind: term
+ OutputFormat: html
+ Suffix: html
+ Template Lookup Order:
+ - layouts/categories/term.html.html
+ - layouts/categories/category.html.html
+ - layouts/categories/taxonomy.html.html
+ - layouts/categories/list.html.html
+ - layouts/categories/term.html
+ - layouts/categories/category.html
+ - layouts/categories/taxonomy.html
+ - layouts/categories/list.html
+ - layouts/term/term.html.html
+ - layouts/term/category.html.html
+ - layouts/term/taxonomy.html.html
+ - layouts/term/list.html.html
+ - layouts/term/term.html
+ - layouts/term/category.html
+ - layouts/term/taxonomy.html
+ - layouts/term/list.html
+ - layouts/taxonomy/term.html.html
+ - layouts/taxonomy/category.html.html
+ - layouts/taxonomy/taxonomy.html.html
+ - layouts/taxonomy/list.html.html
+ - layouts/taxonomy/term.html
+ - layouts/taxonomy/category.html
+ - layouts/taxonomy/taxonomy.html
+ - layouts/taxonomy/list.html
+ - layouts/category/term.html.html
+ - layouts/category/category.html.html
+ - layouts/category/taxonomy.html.html
+ - layouts/category/list.html.html
+ - layouts/category/term.html
+ - layouts/category/category.html
+ - layouts/category/taxonomy.html
+ - layouts/category/list.html
+ - layouts/_default/term.html.html
+ - layouts/_default/category.html.html
+ - layouts/_default/taxonomy.html.html
+ - layouts/_default/list.html.html
+ - layouts/_default/term.html
+ - layouts/_default/category.html
+ - layouts/_default/taxonomy.html
+ - layouts/_default/list.html
+ - Example: Term list for "categories"
+ Kind: term
+ OutputFormat: rss
+ Suffix: xml
+ Template Lookup Order:
+ - layouts/categories/term.rss.xml
+ - layouts/categories/category.rss.xml
+ - layouts/categories/taxonomy.rss.xml
+ - layouts/categories/rss.xml
+ - layouts/categories/list.rss.xml
+ - layouts/categories/term.xml
+ - layouts/categories/category.xml
+ - layouts/categories/taxonomy.xml
+ - layouts/categories/list.xml
+ - layouts/term/term.rss.xml
+ - layouts/term/category.rss.xml
+ - layouts/term/taxonomy.rss.xml
+ - layouts/term/rss.xml
+ - layouts/term/list.rss.xml
+ - layouts/term/term.xml
+ - layouts/term/category.xml
+ - layouts/term/taxonomy.xml
+ - layouts/term/list.xml
+ - layouts/taxonomy/term.rss.xml
+ - layouts/taxonomy/category.rss.xml
+ - layouts/taxonomy/taxonomy.rss.xml
+ - layouts/taxonomy/rss.xml
+ - layouts/taxonomy/list.rss.xml
+ - layouts/taxonomy/term.xml
+ - layouts/taxonomy/category.xml
+ - layouts/taxonomy/taxonomy.xml
+ - layouts/taxonomy/list.xml
+ - layouts/category/term.rss.xml
+ - layouts/category/category.rss.xml
+ - layouts/category/taxonomy.rss.xml
+ - layouts/category/rss.xml
+ - layouts/category/list.rss.xml
+ - layouts/category/term.xml
+ - layouts/category/category.xml
+ - layouts/category/taxonomy.xml
+ - layouts/category/list.xml
+ - layouts/_default/term.rss.xml
+ - layouts/_default/category.rss.xml
+ - layouts/_default/taxonomy.rss.xml
+ - layouts/_default/rss.xml
+ - layouts/_default/list.rss.xml
+ - layouts/_default/term.xml
+ - layouts/_default/category.xml
+ - layouts/_default/taxonomy.xml
+ - layouts/_default/list.xml
+ - layouts/_internal/_default/rss.xml
+tpl:
+ funcs:
+ cast:
+ ToFloat:
+ Aliases:
+ - float
+ Args:
+ - v
+ Description: ToFloat converts v to a float.
+ Examples:
+ - - '{{ "1234" | float | printf "%T" }}'
+ - float64
+ ToInt:
+ Aliases:
+ - int
+ Args:
+ - v
+ Description: ToInt converts v to an int.
+ Examples:
+ - - '{{ "1234" | int | printf "%T" }}'
+ - int
+ ToString:
+ Aliases:
+ - string
+ Args:
+ - v
+ Description: ToString converts v to a string.
+ Examples:
+ - - '{{ 1234 | string | printf "%T" }}'
+ - string
+ collections:
+ After:
+ Aliases:
+ - after
+ Args:
+ - "n"
+ - l
+ Description: After returns all the items after the first n items in list l.
+ Examples: []
+ Append:
+ Aliases:
+ - append
+ Args:
+ - args
+ Description: "Append appends args up to the last one to the slice in the last
+ argument.\nThis construct allows template constructs like this:\n\n\t{{
+ $pages = $pages | append $p2 $p1 }}\n\nNote that with 2 arguments where
+ both are slices of the same type,\nthe first slice will be appended to the
+ second:\n\n\t{{ $pages = $pages | append .Site.RegularPages }}"
+ Examples: []
+ Apply:
+ Aliases:
+ - apply
+ Args:
+ - ctx
+ - c
+ - fname
+ - args
+ Description: Apply takes an array or slice c and returns a new slice with
+ the function fname applied over it.
+ Examples: []
+ Complement:
+ Aliases:
+ - complement
+ Args:
+ - ls
+ Description: "Complement gives the elements in the last element of ls that
+ are not in\nany of the others.\n\nAll elements of ls must be slices or arrays
+ of comparable types.\n\nThe reasoning behind this rather clumsy API is so
+ we can do this in the templates:\n\n\t{{ $c := .Pages | complement $last4
+ }}"
+ Examples:
+ - - '{{ slice "a" "b" "c" "d" "e" "f" | complement (slice "b" "c") (slice
+ "d" "e") }}'
+ - '[a f]'
+ Delimit:
+ Aliases:
+ - delimit
+ Args:
+ - ctx
+ - l
+ - sep
+ - last
+ Description: |-
+ Delimit takes a given list l and returns a string delimited by sep.
+ If last is passed to the function, it will be used as the final delimiter.
+ Examples:
+ - - '{{ delimit (slice "A" "B" "C") ", " " and " }}'
+ - A, B and C
+ Dictionary:
+ Aliases:
+ - dict
+ Args:
+ - values
+ Description: |-
+ Dictionary creates a new map from the given parameters by
+ treating values as key-value pairs. The number of values must be even.
+ The keys can be string slices, which will create the needed nested structure.
+ Examples: []
+ EchoParam:
+ Aliases:
+ - echoParam
+ Args:
+ - c
+ - k
+ Description: |-
+ EchoParam returns the value in the collection c with key k if is set; otherwise, it returns an
+ empty string.
+ Deprecated: Use the index function instead.
+ Examples:
+ - - '{{ echoParam .Params "langCode" }}'
+ - en
+ First:
+ Aliases:
+ - first
+ Args:
+ - limit
+ - l
+ Description: First returns the first limit items in list l.
+ Examples: []
+ Group:
+ Aliases:
+ - group
+ Args:
+ - key
+ - items
+ Description: |-
+ Group groups a set of items by the given key.
+ This is currently only supported for Pages.
+ Examples: []
+ In:
+ Aliases:
+ - in
+ Args:
+ - l
+ - v
+ Description: In returns whether v is in the list l. l may be an array or
+ slice.
+ Examples:
+ - - '{{ if in "this string contains a substring" "substring" }}Substring found!{{
+ end }}'
+ - Substring found!
+ Index:
+ Aliases:
+ - index
+ Args:
+ - item
+ - args
+ Description: |-
+ Index returns the result of indexing its first argument by the following
+ arguments. Thus "index x 1 2 3" is, in Go syntax, x[1][2][3]. Each
+ indexed item must be a map, slice, or array.
+
+ Adapted from Go stdlib src/text/template/funcs.go.
+
+ We deviate from the stdlib mostly because of https://github.com/golang/go/issues/14751.
+ Examples: []
+ Intersect:
+ Aliases:
+ - intersect
+ Args:
+ - l1
+ - l2
+ Description: |-
+ Intersect returns the common elements in the given sets, l1 and l2. l1 and
+ l2 must be of the same type and may be either arrays or slices.
+ Examples: []
+ IsSet:
+ Aliases:
+ - isSet
+ - isset
+ Args:
+ - c
+ - key
+ Description: |-
+ IsSet returns whether a given array, channel, slice, or map in c has the given key
+ defined.
+ Examples: []
+ KeyVals:
+ Aliases:
+ - keyVals
+ Args:
+ - key
+ - values
+ Description: KeyVals creates a key and values wrapper.
+ Examples:
+ - - '{{ keyVals "key" "a" "b" }}'
+ - 'key: [a b]'
+ Last:
+ Aliases:
+ - last
+ Args:
+ - limit
+ - l
+ Description: Last returns the last limit items in the list l.
+ Examples: []
+ Merge:
+ Aliases:
+ - merge
+ Args:
+ - params
+ Description: |-
+ Merge creates a copy of the final parameter in params and merges the preceding
+ parameters into it in reverse order.
+
+ Currently only maps are supported. Key handling is case insensitive.
+ Examples:
+ - - '{{ dict "title" "Hugo Rocks!" | collections.Merge (dict "title" "Default
+ Title" "description" "Yes, Hugo Rocks!") | sort }}'
+ - '[Yes, Hugo Rocks! Hugo Rocks!]'
+ - - '{{ merge (dict "title" "Default Title" "description" "Yes, Hugo Rocks!")
+ (dict "title" "Hugo Rocks!") | sort }}'
+ - '[Yes, Hugo Rocks! Hugo Rocks!]'
+ - - '{{ merge (dict "title" "Default Title" "description" "Yes, Hugo Rocks!")
+ (dict "title" "Hugo Rocks!") (dict "extra" "For reals!") | sort }}'
+ - '[Yes, Hugo Rocks! For reals! Hugo Rocks!]'
+ NewScratch:
+ Aliases:
+ - newScratch
+ Args: null
+ Description: |-
+ NewScratch creates a new Scratch which can be used to store values in a
+ thread safe way.
+ Examples:
+ - - '{{ $scratch := newScratch }}{{ $scratch.Add "b" 2 }}{{ $scratch.Add "b"
+ 2 }}{{ $scratch.Get "b" }}'
+ - "4"
+ Querify:
+ Aliases:
+ - querify
+ Args:
+ - params
+ Description: Querify encodes the given params in URL-encoded form ("bar=baz&foo=quux")
+ sorted by key.
+ Examples:
+ - - '{{ (querify "foo" 1 "bar" 2 "baz" "with spaces" "qux" "this&that=those")
+ | safeHTML }}'
+ - bar=2&baz=with+spaces&foo=1&qux=this%26that%3Dthose
+ - - <a href="https://www.google.com?{{ (querify "q" "test" "page" 3) | safeURL
+ }}">Search</a>
+ - <a href="https://www.google.com?page=3&q=test">Search</a>
+ - - '{{ slice "foo" 1 "bar" 2 | querify | safeHTML }}'
+ - bar=2&foo=1
+ Reverse:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Seq:
+ Aliases:
+ - seq
+ Args:
+ - args
+ Description: "Seq creates a sequence of integers from args. It's named and
+ used as GNU's seq.\n\nExamples:\n\n\t3 => 1, 2, 3\n\t1 2 4 => 1, 3\n\t-3
+ => -1, -2, -3\n\t1 4 => 1, 2, 3, 4\n\t1 -2 => 1, 0, -1, -2"
+ Examples:
+ - - '{{ seq 3 }}'
+ - '[1 2 3]'
+ Shuffle:
+ Aliases:
+ - shuffle
+ Args:
+ - l
+ Description: Shuffle returns list l in a randomized order.
+ Examples: []
+ Slice:
+ Aliases:
+ - slice
+ Args:
+ - args
+ Description: Slice returns a slice of all passed arguments.
+ Examples:
+ - - '{{ slice "B" "C" "A" | sort }}'
+ - '[A B C]'
+ Sort:
+ Aliases:
+ - sort
+ Args:
+ - ctx
+ - l
+ - args
+ Description: Sort returns a sorted copy of the list l.
+ Examples: []
+ SymDiff:
+ Aliases:
+ - symdiff
+ Args:
+ - s2
+ - s1
+ Description: |-
+ SymDiff returns the symmetric difference of s1 and s2.
+ Arguments must be either a slice or an array of comparable types.
+ Examples:
+ - - '{{ slice 1 2 3 | symdiff (slice 3 4) }}'
+ - '[1 2 4]'
+ Union:
+ Aliases:
+ - union
+ Args:
+ - l1
+ - l2
+ Description: |-
+ Union returns the union of the given sets, l1 and l2. l1 and
+ l2 must be of the same type and may be either arrays or slices.
+ If l1 and l2 aren't of the same type then l1 will be returned.
+ If either l1 or l2 is nil then the non-nil list will be returned.
+ Examples:
+ - - '{{ union (slice 1 2 3) (slice 3 4 5) }}'
+ - '[1 2 3 4 5]'
+ Uniq:
+ Aliases:
+ - uniq
+ Args:
+ - l
+ Description: Uniq returns a new list with duplicate elements in the list l
+ removed.
+ Examples:
+ - - '{{ slice 1 2 3 2 | uniq }}'
+ - '[1 2 3]'
+ Where:
+ Aliases:
+ - where
+ Args:
+ - ctx
+ - c
+ - key
+ - args
+ Description: Where returns a filtered subset of collection c.
+ Examples: []
+ compare:
+ Conditional:
+ Aliases:
+ - cond
+ Args:
+ - cond
+ - v1
+ - v2
+ Description: |-
+ Conditional can be used as a ternary operator.
+
+ It returns v1 if cond is true, else v2.
+ Examples:
+ - - '{{ cond (eq (add 2 2) 4) "2+2 is 4" "what?" | safeHTML }}'
+ - 2+2 is 4
+ Default:
+ Aliases:
+ - default
+ Args:
+ - defaultv
+ - givenv
+ Description: |-
+ Default checks whether a givenv is set and returns the default value defaultv if it
+ is not. "Set" in this context means non-zero for numeric types and times;
+ non-zero length for strings, arrays, slices, and maps;
+ any boolean or struct value; or non-nil for any other types.
+ Examples:
+ - - '{{ "Hugo Rocks!" | default "Hugo Rules!" }}'
+ - Hugo Rocks!
+ - - '{{ "" | default "Hugo Rules!" }}'
+ - Hugo Rules!
+ Eq:
+ Aliases:
+ - eq
+ Args:
+ - first
+ - others
+ Description: Eq returns the boolean truth of arg1 == arg2 || arg1 == arg3
+ || arg1 == arg4.
+ Examples:
+ - - '{{ if eq .Section "blog" }}current-section{{ end }}'
+ - current-section
+ Ge:
+ Aliases:
+ - ge
+ Args:
+ - first
+ - others
+ Description: Ge returns the boolean truth of arg1 >= arg2 && arg1 >= arg3
+ && arg1 >= arg4.
+ Examples:
+ - - '{{ if ge hugo.Version "0.80" }}Reasonable new Hugo version!{{ end }}'
+ - Reasonable new Hugo version!
+ Gt:
+ Aliases:
+ - gt
+ Args:
+ - first
+ - others
+ Description: Gt returns the boolean truth of arg1 > arg2 && arg1 > arg3 &&
+ arg1 > arg4.
+ Examples: []
+ Le:
+ Aliases:
+ - le
+ Args:
+ - first
+ - others
+ Description: Le returns the boolean truth of arg1 <= arg2 && arg1 <= arg3
+ && arg1 <= arg4.
+ Examples: []
+ Lt:
+ Aliases:
+ - lt
+ Args:
+ - first
+ - others
+ Description: Lt returns the boolean truth of arg1 < arg2 && arg1 < arg3 &&
+ arg1 < arg4.
+ Examples: []
+ LtCollate:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Ne:
+ Aliases:
+ - ne
+ Args:
+ - first
+ - others
+ Description: Ne returns the boolean truth of arg1 != arg2 && arg1 != arg3
+ && arg1 != arg4.
+ Examples: []
+ crypto:
+ FNV32a:
+ Aliases: null
+ Args:
+ - v
+ Description: |-
+ FNV32a hashes v using fnv32a algorithm.
+ <docsmeta>{"newIn": "0.98.0" }</docsmeta>
+ Examples:
+ - - '{{ crypto.FNV32a "Hugo Rocks!!" }}'
+ - "1515779328"
+ HMAC:
+ Aliases:
+ - hmac
+ Args:
+ - h
+ - k
+ - m
+ - e
+ Description: HMAC returns a cryptographic hash that uses a key to sign a message.
+ Examples:
+ - - '{{ hmac "sha256" "Secret key" "Hello world, gophers!" }}'
+ - b6d11b6c53830b9d87036272ca9fe9d19306b8f9d8aa07b15da27d89e6e34f40
+ MD5:
+ Aliases:
+ - md5
+ Args:
+ - v
+ Description: MD5 hashes the v and returns its MD5 checksum.
+ Examples:
+ - - '{{ md5 "Hello world, gophers!" }}'
+ - b3029f756f98f79e7f1b7f1d1f0dd53b
+ - - '{{ crypto.MD5 "Hello world, gophers!" }}'
+ - b3029f756f98f79e7f1b7f1d1f0dd53b
+ SHA1:
+ Aliases:
+ - sha1
+ Args:
+ - v
+ Description: SHA1 hashes v and returns its SHA1 checksum.
+ Examples:
+ - - '{{ sha1 "Hello world, gophers!" }}'
+ - c8b5b0e33d408246e30f53e32b8f7627a7a649d4
+ SHA256:
+ Aliases:
+ - sha256
+ Args:
+ - v
+ Description: SHA256 hashes v and returns its SHA256 checksum.
+ Examples:
+ - - '{{ sha256 "Hello world, gophers!" }}'
+ - 6ec43b78da9669f50e4e422575c54bf87536954ccd58280219c393f2ce352b46
+ css:
+ Quoted:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Unquoted:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ data:
+ GetCSV:
+ Aliases:
+ - getCSV
+ Args:
+ - sep
+ - args
+ Description: |-
+ GetCSV expects the separator sep and one or n-parts of a URL to a resource which
+ can either be a local or a remote one.
+ The data separator can be a comma, semi-colon, pipe, etc, but only one character.
+ If you provide multiple parts for the URL they will be joined together to the final URL.
+ GetCSV returns nil or a slice slice to use in a short code.
+ Examples: []
+ GetJSON:
+ Aliases:
+ - getJSON
+ Args:
+ - args
+ Description: |-
+ GetJSON expects one or n-parts of a URL in args to a resource which can either be a local or a remote one.
+ If you provide multiple parts they will be joined together to the final URL.
+ GetJSON returns nil or parsed JSON to use in a short code.
+ Examples: []
+ debug:
+ Dump:
+ Aliases: null
+ Args:
+ - val
+ Description: |-
+ Dump returns a object dump of val as a string.
+ Note that not every value passed to Dump will print so nicely, but
+ we'll improve on that.
+
+ We recommend using the "go" Chroma lexer to format the output
+ nicely.
+
+ Also note that the output from Dump may change from Hugo version to the next,
+ so don't depend on a specific output.
+ Examples:
+ - - |-
+ {{ $m := newScratch }}
+ {{ $m.Set "Hugo" "Rocks!" }}
+ {{ $m.Values | debug.Dump | safeHTML }}
+ - |-
+ {
+ "Hugo": "Rocks!"
+ }
+ TestDeprecationErr:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ TestDeprecationInfo:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ TestDeprecationWarn:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Timer:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ VisualizeSpaces:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ diagrams:
+ Goat:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ encoding:
+ Base64Decode:
+ Aliases:
+ - base64Decode
+ Args:
+ - content
+ Description: Base64Decode returns the base64 decoding of the given content.
+ Examples:
+ - - '{{ "SGVsbG8gd29ybGQ=" | base64Decode }}'
+ - Hello world
+ - - '{{ 42 | base64Encode | base64Decode }}'
+ - "42"
+ Base64Encode:
+ Aliases:
+ - base64Encode
+ Args:
+ - content
+ Description: Base64Encode returns the base64 encoding of the given content.
+ Examples:
+ - - '{{ "Hello world" | base64Encode }}'
+ - SGVsbG8gd29ybGQ=
+ Jsonify:
+ Aliases:
+ - jsonify
+ Args:
+ - args
+ Description: |-
+ Jsonify encodes a given object to JSON. To pretty print the JSON, pass a map
+ or dictionary of options as the first value in args. Supported options are
+ "prefix" and "indent". Each JSON element in the output will begin on a new
+ line beginning with prefix followed by one or more copies of indent according
+ to the indentation nesting.
+ Examples:
+ - - '{{ (slice "A" "B" "C") | jsonify }}'
+ - '["A","B","C"]'
+ - - '{{ (slice "A" "B" "C") | jsonify (dict "indent" " ") }}'
+ - |-
+ [
+ "A",
+ "B",
+ "C"
+ ]
+ fmt:
+ Errorf:
+ Aliases:
+ - errorf
+ Args:
+ - format
+ - args
+ Description: |-
+ Errorf formats args according to a format specifier and logs an ERROR.
+ It returns an empty string.
+ Examples:
+ - - '{{ errorf "%s." "failed" }}'
+ - ""
+ Erroridf:
+ Aliases:
+ - erroridf
+ Args:
+ - id
+ - format
+ - args
+ Description: |-
+ Erroridf formats args according to a format specifier and logs an ERROR and
+ an information text that the error with the given id can be suppressed in config.
+ It returns an empty string.
+ Examples:
+ - - '{{ erroridf "my-err-id" "%s." "failed" }}'
+ - ""
+ Errormf:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Print:
+ Aliases:
+ - print
+ Args:
+ - args
+ Description: Print returns a string representation of args.
+ Examples:
+ - - '{{ print "works!" }}'
+ - works!
+ Printf:
+ Aliases:
+ - printf
+ Args:
+ - format
+ - args
+ Description: Printf returns string representation of args formatted with the
+ layout in format.
+ Examples:
+ - - '{{ printf "%s!" "works" }}'
+ - works!
+ Println:
+ Aliases:
+ - println
+ Args:
+ - args
+ Description: Println returns string representation of args ending with a
+ newline.
+ Examples:
+ - - '{{ println "works!" }}'
+ - |
+ works!
+ Warnf:
+ Aliases:
+ - warnf
+ Args:
+ - format
+ - args
+ Description: |-
+ Warnf formats args according to a format specifier and logs a WARNING.
+ It returns an empty string.
+ Examples:
+ - - '{{ warnf "%s." "warning" }}'
+ - ""
+ Warnidf:
+ Aliases:
+ - warnidf
+ Args:
+ - id
+ - format
+ - args
+ Description: |-
+ Warnidf formats args according to a format specifier and logs an WARNING and
+ an information text that the warning with the given id can be suppressed in config.
+ It returns an empty string.
+ Examples:
+ - - '{{ warnidf "my-warn-id" "%s." "warning" }}'
+ - ""
+ Warnmf:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ hugo:
+ Deps:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Generator:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ IsDevelopment:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ IsExtended:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ IsMultiHost:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ IsMultihost:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ IsMultilingual:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ IsProduction:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ IsServer:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Version:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ WorkingDir:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ images:
+ AutoOrient:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Brightness:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ ColorBalance:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Colorize:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Config:
+ Aliases:
+ - imageConfig
+ Args:
+ - path
+ Description: |-
+ Config returns the image.Config for the specified path relative to the
+ working directory.
+ Examples: []
+ Contrast:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Dither:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Filter:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Gamma:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ GaussianBlur:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Grayscale:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Hue:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Invert:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Opacity:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Overlay:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Padding:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Pixelate:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Process:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Saturation:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Sepia:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Sigmoid:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Text:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ UnsharpMask:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ inflect:
+ Humanize:
+ Aliases:
+ - humanize
+ Args:
+ - v
+ Description: |-
+ Humanize returns the humanized form of v.
+
+ If v is either an integer or a string containing an integer
+ value, the behavior is to add the appropriate ordinal.
+ Examples:
+ - - '{{ humanize "my-first-post" }}'
+ - My first post
+ - - '{{ humanize "myCamelPost" }}'
+ - My camel post
+ - - '{{ humanize "52" }}'
+ - 52nd
+ - - '{{ humanize 103 }}'
+ - 103rd
+ Pluralize:
+ Aliases:
+ - pluralize
+ Args:
+ - v
+ Description: Pluralize returns the plural form of the single word in v.
+ Examples:
+ - - '{{ "cat" | pluralize }}'
+ - cats
+ Singularize:
+ Aliases:
+ - singularize
+ Args:
+ - v
+ Description: Singularize returns the singular form of a single word in v.
+ Examples:
+ - - '{{ "cats" | singularize }}'
+ - cat
+ js:
+ Build:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ lang:
+ FormatAccounting:
+ Aliases: null
+ Args:
+ - precision
+ - currency
+ - number
+ Description: |-
+ FormatAccounting returns the currency representation of number for the given currency and precision
+ for the current language in accounting notation.
+
+ The return value is formatted with at least two decimal places.
+ Examples:
+ - - '{{ 512.5032 | lang.FormatAccounting 2 "NOK" }}'
+ - NOK512.50
+ FormatCurrency:
+ Aliases: null
+ Args:
+ - precision
+ - currency
+ - number
+ Description: |-
+ FormatCurrency returns the currency representation of number for the given currency and precision
+ for the current language.
+
+ The return value is formatted with at least two decimal places.
+ Examples:
+ - - '{{ 512.5032 | lang.FormatCurrency 2 "USD" }}'
+ - $512.50
+ FormatNumber:
+ Aliases: null
+ Args:
+ - precision
+ - number
+ Description: FormatNumber formats number with the given precision for the
+ current language.
+ Examples:
+ - - '{{ 512.5032 | lang.FormatNumber 2 }}'
+ - "512.50"
+ FormatNumberCustom:
+ Aliases: null
+ Args:
+ - precision
+ - number
+ - options
+ Description: |-
+ FormatNumberCustom formats a number with the given precision. The first
+ options parameter is a space-delimited string of characters to represent
+ negativity, the decimal point, and grouping. The default value is `- . ,`.
+ The second options parameter defines an alternate delimiting character.
+
+ Note that numbers are rounded up at 5 or greater.
+ So, with precision set to 0, 1.5 becomes `2`, and 1.4 becomes `1`.
+
+ For a simpler function that adapts to the current language, see FormatNumber.
+ Examples:
+ - - '{{ lang.FormatNumberCustom 2 12345.6789 }}'
+ - 12,345.68
+ - - '{{ lang.FormatNumberCustom 2 12345.6789 "- , ." }}'
+ - 12.345,68
+ - - '{{ lang.FormatNumberCustom 6 -12345.6789 "- ." }}'
+ - "-12345.678900"
+ - - '{{ lang.FormatNumberCustom 0 -12345.6789 "- . ," }}'
+ - -12,346
+ - - '{{ lang.FormatNumberCustom 0 -12345.6789 "-|.| " "|" }}'
+ - -12 346
+ - - '{{ -98765.4321 | lang.FormatNumberCustom 2 }}'
+ - -98,765.43
+ FormatPercent:
+ Aliases: null
+ Args:
+ - precision
+ - number
+ Description: |-
+ FormatPercent formats number with the given precision for the current language.
+ Note that the number is assumed to be a percentage.
+ Examples:
+ - - '{{ 512.5032 | lang.FormatPercent 2 }}'
+ - 512.50%
+ Merge:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ NumFmt:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Translate:
+ Aliases:
+ - i18n
+ - T
+ Args:
+ - ctx
+ - id
+ - args
+ Description: Translate returns a translated string for id.
+ Examples: []
+ math:
+ Abs:
+ Aliases: null
+ Args:
+ - "n"
+ Description: Abs returns the absolute value of n.
+ Examples:
+ - - '{{ math.Abs -2.1 }}'
+ - "2.1"
+ Add:
+ Aliases:
+ - add
+ Args:
+ - inputs
+ Description: Add adds the multivalued addends n1 and n2 or more values.
+ Examples:
+ - - '{{ add 1 2 }}'
+ - "3"
+ Ceil:
+ Aliases: null
+ Args:
+ - "n"
+ Description: Ceil returns the least integer value greater than or equal to
+ n.
+ Examples:
+ - - '{{ math.Ceil 2.1 }}'
+ - "3"
+ Counter:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Div:
+ Aliases:
+ - div
+ Args:
+ - inputs
+ Description: Div divides n1 by n2.
+ Examples:
+ - - '{{ div 6 3 }}'
+ - "2"
+ Floor:
+ Aliases: null
+ Args:
+ - "n"
+ Description: Floor returns the greatest integer value less than or equal to
+ n.
+ Examples:
+ - - '{{ math.Floor 1.9 }}'
+ - "1"
+ Log:
+ Aliases: null
+ Args:
+ - "n"
+ Description: Log returns the natural logarithm of the number n.
+ Examples:
+ - - '{{ math.Log 1 }}'
+ - "0"
+ Max:
+ Aliases: null
+ Args:
+ - inputs
+ Description: Max returns the greater of all numbers in inputs. Any slices
+ in inputs are flattened.
+ Examples:
+ - - '{{ math.Max 1 2 }}'
+ - "2"
+ Min:
+ Aliases: null
+ Args:
+ - inputs
+ Description: Min returns the smaller of all numbers in inputs. Any slices
+ in inputs are flattened.
+ Examples:
+ - - '{{ math.Min 1 2 }}'
+ - "1"
+ Mod:
+ Aliases:
+ - mod
+ Args:
+ - n1
+ - n2
+ Description: Mod returns n1 % n2.
+ Examples:
+ - - '{{ mod 15 3 }}'
+ - "0"
+ ModBool:
+ Aliases:
+ - modBool
+ Args:
+ - n1
+ - n2
+ Description: ModBool returns the boolean of n1 % n2. If n1 % n2 == 0, return
+ true.
+ Examples:
+ - - '{{ modBool 15 3 }}'
+ - "true"
+ Mul:
+ Aliases:
+ - mul
+ Args:
+ - inputs
+ Description: Mul multiplies the multivalued numbers n1 and n2 or more values.
+ Examples:
+ - - '{{ mul 2 3 }}'
+ - "6"
+ Pow:
+ Aliases:
+ - pow
+ Args:
+ - n1
+ - n2
+ Description: Pow returns n1 raised to the power of n2.
+ Examples:
+ - - '{{ math.Pow 2 3 }}'
+ - "8"
+ Product:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Rand:
+ Aliases: null
+ Args: null
+ Description: Rand returns, as a float64, a pseudo-random number in the half-open
+ interval [0.0,1.0).
+ Examples:
+ - - '{{ math.Rand }}'
+ - "0.6312770459590062"
+ Round:
+ Aliases: null
+ Args:
+ - "n"
+ Description: Round returns the integer nearest to n, rounding half away from
+ zero.
+ Examples:
+ - - '{{ math.Round 1.5 }}'
+ - "2"
+ Sqrt:
+ Aliases: null
+ Args:
+ - "n"
+ Description: Sqrt returns the square root of the number n.
+ Examples:
+ - - '{{ math.Sqrt 81 }}'
+ - "9"
+ Sub:
+ Aliases:
+ - sub
+ Args:
+ - inputs
+ Description: Sub subtracts multivalued.
+ Examples:
+ - - '{{ sub 3 2 }}'
+ - "1"
+ Sum:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ openapi3:
+ Unmarshal:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: []
+ os:
+ FileExists:
+ Aliases:
+ - fileExists
+ Args:
+ - i
+ Description: FileExists checks whether a file exists under the given path.
+ Examples:
+ - - '{{ fileExists "foo.txt" }}'
+ - "false"
+ Getenv:
+ Aliases:
+ - getenv
+ Args:
+ - key
+ Description: |-
+ Getenv retrieves the value of the environment variable named by the key.
+ It returns the value, which will be empty if the variable is not present.
+ Examples: []
+ ReadDir:
+ Aliases:
+ - readDir
+ Args:
+ - i
+ Description: ReadDir lists the directory contents relative to the configured
+ WorkingDir.
+ Examples:
+ - - '{{ range (readDir "files") }}{{ .Name }}{{ end }}'
+ - README.txt
+ ReadFile:
+ Aliases:
+ - readFile
+ Args:
+ - i
+ Description: |-
+ ReadFile reads the file named by filename relative to the configured WorkingDir.
+ It returns the contents as a string.
+ There is an upper size limit set at 1 megabytes.
+ Examples:
+ - - '{{ readFile "files/README.txt" }}'
+ - Hugo Rocks!
+ Stat:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ partials:
+ Include:
+ Aliases:
+ - partial
+ Args:
+ - ctx
+ - name
+ - contextList
+ Description: |-
+ Include executes the named partial.
+ If the partial contains a return statement, that value will be returned.
+ Else, the rendered output will be returned:
+ A string if the partial is a text/template, or template.HTML when html/template.
+ Note that ctx is provided by Hugo, not the end user.
+ Examples:
+ - - '{{ partial "header.html" . }}'
+ - <title>Hugo Rocks!</title>
+ IncludeCached:
+ Aliases:
+ - partialCached
+ Args:
+ - ctx
+ - name
+ - context
+ - variants
+ Description: |-
+ IncludeCached executes and caches partial templates. The cache is created with name+variants as the key.
+ Note that ctx is provided by Hugo, not the end user.
+ Examples: []
+ path:
+ Base:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ BaseName:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Clean:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Dir:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Ext:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Join:
+ Aliases: null
+ Args:
+ - elements
+ Description: |-
+ Join joins any number of path elements into a single path, adding a
+ separating slash if necessary. All the input
+ path elements are passed into filepath.ToSlash converting any Windows slashes
+ to forward slashes.
+ The result is Cleaned; in particular,
+ all empty strings are ignored.
+ Examples:
+ - - '{{ slice "my/path" "filename.txt" | path.Join }}'
+ - my/path/filename.txt
+ - - '{{ path.Join "my" "path" "filename.txt" }}'
+ - my/path/filename.txt
+ - - '{{ "my/path/filename.txt" | path.Ext }}'
+ - .txt
+ - - '{{ "my/path/filename.txt" | path.Base }}'
+ - filename.txt
+ - - '{{ "my/path/filename.txt" | path.Dir }}'
+ - my/path
+ Split:
+ Aliases: null
+ Args:
+ - path
+ Description: |-
+ Split splits path immediately following the final slash,
+ separating it into a directory and file name component.
+ If there is no slash in path, Split returns an empty dir and
+ file set to path.
+ The input path is passed into filepath.ToSlash converting any Windows slashes
+ to forward slashes.
+ The returned values have the property that path = dir+file.
+ Examples:
+ - - '{{ "/my/path/filename.txt" | path.Split }}'
+ - /my/path/|filename.txt
+ - - '{{ "/my/path/filename.txt" | path.Split }}'
+ - /my/path/|filename.txt
+ reflect:
+ IsMap:
+ Aliases: null
+ Args:
+ - v
+ Description: IsMap reports whether v is a map.
+ Examples:
+ - - '{{ if reflect.IsMap (dict "a" 1) }}Map{{ end }}'
+ - Map
+ IsSlice:
+ Aliases: null
+ Args:
+ - v
+ Description: IsSlice reports whether v is a slice.
+ Examples:
+ - - '{{ if reflect.IsSlice (slice 1 2 3) }}Slice{{ end }}'
+ - Slice
+ resources:
+ Babel:
+ Aliases:
+ - babel
+ Args:
+ - args
+ Description: Babel processes the given Resource with Babel.
+ Examples: []
+ ByType:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Concat:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Copy:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ ExecuteAsTemplate:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Fingerprint:
+ Aliases:
+ - fingerprint
+ Args:
+ - args
+ Description: |-
+ Fingerprint transforms the given Resource with a MD5 hash of the content in
+ the RelPermalink and Permalink.
+ Examples: []
+ FromString:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Get:
+ Aliases: null
+ Args:
+ - filename
+ Description: |-
+ Get locates the filename given in Hugo's assets filesystem
+ and creates a Resource object that can be used for further transformations.
+ Examples: []
+ GetMatch:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ GetRemote:
+ Aliases: null
+ Args:
+ - args
+ Description: |-
+ GetRemote gets the URL (via HTTP(s)) in the first argument in args and creates Resource object that can be used for
+ further transformations.
+
+ A second argument may be provided with an option map.
+
+ Note: This method does not return any error as a second return value,
+ for any error situations the error can be checked in .Err.
+ Examples: []
+ Match:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Minify:
+ Aliases:
+ - minify
+ Args:
+ - r
+ Description: |-
+ Minify minifies the given Resource using the MediaType to pick the correct
+ minifier.
+ Examples: []
+ PostCSS:
+ Aliases:
+ - postCSS
+ Args:
+ - args
+ Description: PostCSS processes the given Resource with PostCSS
+ Examples: []
+ PostProcess:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ ToCSS:
+ Aliases:
+ - toCSS
+ Args:
+ - args
+ Description: |-
+ ToCSS converts the given Resource to CSS. You can optional provide an Options object
+ as second argument. As an option, you can e.g. specify e.g. the target path (string)
+ for the converted CSS resource.
+ Examples: []
+ safe:
+ CSS:
+ Aliases:
+ - safeCSS
+ Args:
+ - s
+ Description: CSS returns the string s as html/template CSS content.
+ Examples:
+ - - '{{ "Bat&Man" | safeCSS | safeCSS }}'
+ - Bat&Man
+ HTML:
+ Aliases:
+ - safeHTML
+ Args:
+ - s
+ Description: HTML returns the string s as html/template HTML content.
+ Examples:
+ - - '{{ "Bat&Man" | safeHTML | safeHTML }}'
+ - Bat&Man
+ - - '{{ "Bat&Man" | safeHTML }}'
+ - Bat&Man
+ HTMLAttr:
+ Aliases:
+ - safeHTMLAttr
+ Args:
+ - s
+ Description: HTMLAttr returns the string s as html/template HTMLAttr content.
+ Examples: []
+ JS:
+ Aliases:
+ - safeJS
+ Args:
+ - s
+ Description: JS returns the given string as a html/template JS content.
+ Examples:
+ - - '{{ "(1*2)" | safeJS | safeJS }}'
+ - (1*2)
+ JSStr:
+ Aliases:
+ - safeJSStr
+ Args:
+ - s
+ Description: JSStr returns the given string as a html/template JSStr content.
+ Examples: []
+ URL:
+ Aliases:
+ - safeURL
+ Args:
+ - s
+ Description: URL returns the string s as html/template URL content.
+ Examples:
+ - - '{{ "http://gohugo.io" | safeURL | safeURL }}'
+ - http://gohugo.io
+ site:
+ AllPages:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Author:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Authors:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ BaseURL:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ BuildDrafts:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Config:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Copyright:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Current:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Data:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ DisqusShortname:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ ForEeachIdentityByName:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ GetPage:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ GoogleAnalytics:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Home:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Hugo:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ IsMultiLingual:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ IsServer:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Key:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Language:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ LanguageCode:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ LanguagePrefix:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Languages:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ LastChange:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Lastmod:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ MainSections:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Menus:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Pages:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Param:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Params:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ RSSLink:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ RegularPages:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Sections:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ ServerPort:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Sites:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Social:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Taxonomies:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Title:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ strings:
+ Chomp:
+ Aliases:
+ - chomp
+ Args:
+ - s
+ Description: Chomp returns a copy of s with all trailing newline characters
+ removed.
+ Examples:
+ - - '{{ chomp "<p>Blockhead</p>\n" | safeHTML }}'
+ - <p>Blockhead</p>
+ Contains:
+ Aliases: null
+ Args:
+ - s
+ - substr
+ Description: Contains reports whether substr is in s.
+ Examples:
+ - - '{{ strings.Contains "abc" "b" }}'
+ - "true"
+ - - '{{ strings.Contains "abc" "d" }}'
+ - "false"
+ ContainsAny:
+ Aliases: null
+ Args:
+ - s
+ - chars
+ Description: ContainsAny reports whether any Unicode code points in chars
+ are within s.
+ Examples:
+ - - '{{ strings.ContainsAny "abc" "bcd" }}'
+ - "true"
+ - - '{{ strings.ContainsAny "abc" "def" }}'
+ - "false"
+ ContainsNonSpace:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Count:
+ Aliases: null
+ Args:
+ - substr
+ - s
+ Description: |-
+ Count counts the number of non-overlapping instances of substr in s.
+ If substr is an empty string, Count returns 1 + the number of Unicode code points in s.
+ Examples:
+ - - '{{ "aabab" | strings.Count "a" }}'
+ - "3"
+ CountRunes:
+ Aliases:
+ - countrunes
+ Args:
+ - s
+ Description: CountRunes returns the number of runes in s, excluding whitespace.
+ Examples: []
+ CountWords:
+ Aliases:
+ - countwords
+ Args:
+ - s
+ Description: CountWords returns the approximate word count in s.
+ Examples: []
+ Diff:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ FindRE:
+ Aliases:
+ - findRE
+ Args:
+ - expr
+ - content
+ - limit
+ Description: |-
+ FindRE returns a list of strings that match the regular expression. By default all matches
+ will be included. The number of matches can be limited with an optional third parameter.
+ Examples:
+ - - '{{ findRE "[G|g]o" "Hugo is a static side generator written in Go." 1
+ }}'
+ - '[go]'
+ FindRESubmatch:
+ Aliases:
+ - findRESubmatch
+ Args:
+ - expr
+ - content
+ - limit
+ Description: |-
+ FindRESubmatch returns a slice of all successive matches of the regular
+ expression in content. Each element is a slice of strings holding the text
+ of the leftmost match of the regular expression and the matches, if any, of
+ its subexpressions.
+
+ By default all matches will be included. The number of matches can be
+ limited with the optional limit parameter. A return value of nil indicates
+ no match.
+ Examples:
+ - - '{{ findRESubmatch `<a\s*href="(.+?)">(.+?)</a>` `<li><a href="#foo">Foo</a></li>
+ <li><a href="#bar">Bar</a></li>` | print | safeHTML }}'
+ - '[[<a href="#foo">Foo</a> #foo Foo] [<a href="#bar">Bar</a> #bar Bar]]'
+ FirstUpper:
+ Aliases: null
+ Args:
+ - s
+ Description: FirstUpper converts s making the first character upper case.
+ Examples:
+ - - '{{ "hugo rocks!" | strings.FirstUpper }}'
+ - Hugo rocks!
+ HasPrefix:
+ Aliases:
+ - hasPrefix
+ Args:
+ - s
+ - prefix
+ Description: HasPrefix tests whether the input s begins with prefix.
+ Examples:
+ - - '{{ hasPrefix "Hugo" "Hu" }}'
+ - "true"
+ - - '{{ hasPrefix "Hugo" "Fu" }}'
+ - "false"
+ HasSuffix:
+ Aliases:
+ - hasSuffix
+ Args:
+ - s
+ - suffix
+ Description: HasSuffix tests whether the input s begins with suffix.
+ Examples:
+ - - '{{ hasSuffix "Hugo" "go" }}'
+ - "true"
+ - - '{{ hasSuffix "Hugo" "du" }}'
+ - "false"
+ Repeat:
+ Aliases: null
+ Args:
+ - "n"
+ - s
+ Description: Repeat returns a new string consisting of n copies of the string
+ s.
+ Examples:
+ - - '{{ "yo" | strings.Repeat 4 }}'
+ - yoyoyoyo
+ Replace:
+ Aliases:
+ - replace
+ Args:
+ - s
+ - old
+ - new
+ - limit
+ Description: |-
+ Replace returns a copy of the string s with all occurrences of old replaced
+ with new. The number of replacements can be limited with an optional fourth
+ parameter.
+ Examples:
+ - - '{{ replace "Batman and Robin" "Robin" "Catwoman" }}'
+ - Batman and Catwoman
+ - - '{{ replace "aabbaabb" "a" "z" 2 }}'
+ - zzbbaabb
+ ReplaceRE:
+ Aliases:
+ - replaceRE
+ Args:
+ - pattern
+ - repl
+ - s
+ - "n"
+ Description: |-
+ ReplaceRE returns a copy of s, replacing all matches of the regular
+ expression pattern with the replacement text repl. The number of replacements
+ can be limited with an optional fourth parameter.
+ Examples:
+ - - '{{ replaceRE "a+b" "X" "aabbaabbab" }}'
+ - XbXbX
+ - - '{{ replaceRE "a+b" "X" "aabbaabbab" 1 }}'
+ - Xbaabbab
+ RuneCount:
+ Aliases: null
+ Args:
+ - s
+ Description: RuneCount returns the number of runes in s.
+ Examples: []
+ SliceString:
+ Aliases:
+ - slicestr
+ Args:
+ - a
+ - startEnd
+ Description: |-
+ SliceString slices a string by specifying a half-open range with
+ two indices, start and end. 1 and 4 creates a slice including elements 1 through 3.
+ The end index can be omitted, it defaults to the string's length.
+ Examples:
+ - - '{{ slicestr "BatMan" 0 3 }}'
+ - Bat
+ - - '{{ slicestr "BatMan" 3 }}'
+ - Man
+ Split:
+ Aliases:
+ - split
+ Args:
+ - a
+ - delimiter
+ Description: Split slices an input string into all substrings separated by
+ delimiter.
+ Examples: []
+ Substr:
+ Aliases:
+ - substr
+ Args:
+ - a
+ - nums
+ Description: |-
+ Substr extracts parts of a string, beginning at the character at the specified
+ position, and returns the specified number of characters.
+
+ It normally takes two parameters: start and length.
+ It can also take one parameter: start, i.e. length is omitted, in which case
+ the substring starting from start until the end of the string will be returned.
+
+ To extract characters from the end of the string, use a negative start number.
+
+ In addition, borrowing from the extended behavior described at http://php.net/substr,
+ if length is given and is negative, then that many characters will be omitted from
+ the end of string.
+ Examples:
+ - - '{{ substr "BatMan" 0 -3 }}'
+ - Bat
+ - - '{{ substr "BatMan" 3 3 }}'
+ - Man
+ Title:
+ Aliases:
+ - title
+ Args:
+ - s
+ Description: |-
+ Title returns a copy of the input s with all Unicode letters that begin words
+ mapped to their title case.
+ Examples:
+ - - '{{ title "Bat man" }}'
+ - Bat Man
+ - - '{{ title "somewhere over the rainbow" }}'
+ - Somewhere Over the Rainbow
+ ToLower:
+ Aliases:
+ - lower
+ Args:
+ - s
+ Description: |-
+ ToLower returns a copy of the input s with all Unicode letters mapped to their
+ lower case.
+ Examples:
+ - - '{{ lower "BatMan" }}'
+ - batman
+ ToUpper:
+ Aliases:
+ - upper
+ Args:
+ - s
+ Description: |-
+ ToUpper returns a copy of the input s with all Unicode letters mapped to their
+ upper case.
+ Examples:
+ - - '{{ upper "BatMan" }}'
+ - BATMAN
+ Trim:
+ Aliases:
+ - trim
+ Args:
+ - s
+ - cutset
+ Description: |-
+ Trim returns converts the strings s removing all leading and trailing characters defined
+ contained.
+ Examples:
+ - - '{{ trim "++Batman--" "+-" }}'
+ - Batman
+ TrimLeft:
+ Aliases: null
+ Args:
+ - cutset
+ - s
+ Description: |-
+ TrimLeft returns a slice of the string s with all leading characters
+ contained in cutset removed.
+ Examples:
+ - - '{{ "aabbaa" | strings.TrimLeft "a" }}'
+ - bbaa
+ TrimPrefix:
+ Aliases: null
+ Args:
+ - prefix
+ - s
+ Description: |-
+ TrimPrefix returns s without the provided leading prefix string. If s doesn't
+ start with prefix, s is returned unchanged.
+ Examples:
+ - - '{{ "aabbaa" | strings.TrimPrefix "a" }}'
+ - abbaa
+ - - '{{ "aabbaa" | strings.TrimPrefix "aa" }}'
+ - bbaa
+ TrimRight:
+ Aliases: null
+ Args:
+ - cutset
+ - s
+ Description: |-
+ TrimRight returns a slice of the string s with all trailing characters
+ contained in cutset removed.
+ Examples:
+ - - '{{ "aabbaa" | strings.TrimRight "a" }}'
+ - aabb
+ TrimSuffix:
+ Aliases: null
+ Args:
+ - suffix
+ - s
+ Description: |-
+ TrimSuffix returns s without the provided trailing suffix string. If s
+ doesn't end with suffix, s is returned unchanged.
+ Examples:
+ - - '{{ "aabbaa" | strings.TrimSuffix "a" }}'
+ - aabba
+ - - '{{ "aabbaa" | strings.TrimSuffix "aa" }}'
+ - aabb
+ Truncate:
+ Aliases:
+ - truncate
+ Args:
+ - s
+ - options
+ Description: Truncate truncates the string in s to the specified length.
+ Examples:
+ - - '{{ "this is a very long text" | truncate 10 " ..." }}'
+ - this is a ...
+ - - '{{ "With [Markdown](/markdown) inside." | markdownify | truncate 14 }}'
+ - With <a href="/markdown">Markdown …</a>
+ templates:
+ Exists:
+ Aliases: null
+ Args:
+ - name
+ Description: |-
+ Exists returns whether the template with the given name exists.
+ Note that this is the Unix-styled relative path including filename suffix,
+ e.g. partials/header.html
+ Examples:
+ - - '{{ if (templates.Exists "partials/header.html") }}Yes!{{ end }}'
+ - Yes!
+ - - '{{ if not (templates.Exists "partials/doesnotexist.html") }}No!{{ end
+ }}'
+ - No!
+ time:
+ AsTime:
+ Aliases: null
+ Args:
+ - v
+ - args
+ Description: |-
+ AsTime converts the textual representation of the datetime string into
+ a time.Time interface.
+ Examples:
+ - - '{{ (time "2015-01-21").Year }}'
+ - "2015"
+ Duration:
+ Aliases:
+ - duration
+ Args:
+ - unit
+ - number
+ Description: |-
+ Duration converts the given number to a time.Duration.
+ Unit is one of nanosecond/ns, microsecond/us/µs, millisecond/ms, second/s, minute/m or hour/h.
+ Examples:
+ - - '{{ mul 60 60 | duration "second" }}'
+ - 1h0m0s
+ Format:
+ Aliases:
+ - dateFormat
+ Args:
+ - layout
+ - v
+ Description: |-
+ Format converts the textual representation of the datetime string in v into
+ time.Time if needed and formats it with the given layout.
+ Examples:
+ - - 'dateFormat: {{ dateFormat "Monday, Jan 2, 2006" "2015-01-21" }}'
+ - 'dateFormat: Wednesday, Jan 21, 2015'
+ Now:
+ Aliases:
+ - now
+ Args: null
+ Description: Now returns the current local time or `clock` time
+ Examples: []
+ ParseDuration:
+ Aliases: null
+ Args:
+ - s
+ Description: |-
+ ParseDuration parses the duration string s.
+ A duration string is a possibly signed sequence of
+ decimal numbers, each with optional fraction and a unit suffix,
+ such as "300ms", "-1.5h" or "2h45m".
+ Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
+ See https://golang.org/pkg/time/#ParseDuration
+ Examples:
+ - - '{{ "1h12m10s" | time.ParseDuration }}'
+ - 1h12m10s
+ transform:
+ CanHighlight:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Emojify:
+ Aliases:
+ - emojify
+ Args:
+ - s
+ Description: |-
+ Emojify returns a copy of s with all emoji codes replaced with actual emojis.
+
+ See http://www.emoji-cheat-sheet.com/
+ Examples:
+ - - '{{ "I :heart: Hugo" | emojify }}'
+ - I ❤️ Hugo
+ HTMLEscape:
+ Aliases:
+ - htmlEscape
+ Args:
+ - s
+ Description: HTMLEscape returns a copy of s with reserved HTML characters
+ escaped.
+ Examples:
+ - - '{{ htmlEscape "Cathal Garvey & The Sunshine Band <cathal@foo.bar>" |
+ safeHTML }}'
+ - Cathal Garvey & The Sunshine Band <cathal@foo.bar>
+ - - '{{ htmlEscape "Cathal Garvey & The Sunshine Band <cathal@foo.bar>" }}'
+ - Cathal Garvey &amp; The Sunshine Band &lt;cathal@foo.bar&gt;
+ - - '{{ htmlEscape "Cathal Garvey & The Sunshine Band <cathal@foo.bar>" |
+ htmlUnescape | safeHTML }}'
+ - Cathal Garvey & The Sunshine Band <cathal@foo.bar>
+ HTMLUnescape:
+ Aliases:
+ - htmlUnescape
+ Args:
+ - s
+ Description: |-
+ HTMLUnescape returns a copy of s with HTML escape requences converted to plain
+ text.
+ Examples:
+ - - '{{ htmlUnescape "Cathal Garvey & The Sunshine Band <cathal@foo.bar>"
+ | safeHTML }}'
+ - Cathal Garvey & The Sunshine Band <cathal@foo.bar>
+ - - '{{ "Cathal Garvey &amp; The Sunshine Band &lt;cathal@foo.bar&gt;"
+ | htmlUnescape | htmlUnescape | safeHTML }}'
+ - Cathal Garvey & The Sunshine Band <cathal@foo.bar>
+ - - '{{ "Cathal Garvey &amp; The Sunshine Band &lt;cathal@foo.bar&gt;"
+ | htmlUnescape | htmlUnescape }}'
+ - Cathal Garvey & The Sunshine Band <cathal@foo.bar>
+ - - '{{ htmlUnescape "Cathal Garvey & The Sunshine Band <cathal@foo.bar>"
+ | htmlEscape | safeHTML }}'
+ - Cathal Garvey & The Sunshine Band <cathal@foo.bar>
+ Highlight:
+ Aliases:
+ - highlight
+ Args:
+ - s
+ - lang
+ - opts
+ Description: |-
+ Highlight returns a copy of s as an HTML string with syntax
+ highlighting applied.
+ Examples: []
+ HighlightCodeBlock:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Markdownify:
+ Aliases:
+ - markdownify
+ Args:
+ - ctx
+ - s
+ Description: Markdownify renders s from Markdown to HTML.
+ Examples:
+ - - '{{ .Title | markdownify }}'
+ - <strong>BatMan</strong>
+ Plainify:
+ Aliases:
+ - plainify
+ Args:
+ - s
+ Description: Plainify returns a copy of s with all HTML tags removed.
+ Examples:
+ - - '{{ plainify "Hello <strong>world</strong>, gophers!" }}'
+ - Hello world, gophers!
+ Remarshal:
+ Aliases: null
+ Args:
+ - format
+ - data
+ Description: |-
+ Remarshal is used in the Hugo documentation to convert configuration
+ examples from YAML to JSON, TOML (and possibly the other way around).
+ The is primarily a helper for the Hugo docs site.
+ It is not a general purpose YAML to TOML converter etc., and may
+ change without notice if it serves a purpose in the docs.
+ Format is one of json, yaml or toml.
+ Examples:
+ - - '{{ "title = \"Hello World\"" | transform.Remarshal "json" | safeHTML
+ }}'
+ - |
+ {
+ "title": "Hello World"
+ }
+ Unmarshal:
+ Aliases:
+ - unmarshal
+ Args:
+ - args
+ Description: |-
+ Unmarshal unmarshals the data given, which can be either a string, json.RawMessage
+ or a Resource. Supported formats are JSON, TOML, YAML, and CSV.
+ You can optionally provide an options map as the first argument.
+ Examples:
+ - - '{{ "hello = \"Hello World\"" | transform.Unmarshal }}'
+ - map[hello:Hello World]
+ - - '{{ "hello = \"Hello World\"" | resources.FromString "data/greetings.toml"
+ | transform.Unmarshal }}'
+ - map[hello:Hello World]
+ XMLEscape:
+ Aliases: null
+ Args:
+ - s
+ Description: |-
+ XMLEscape returns the given string, removing disallowed characters then
+ escaping the result to its XML equivalent.
+ Examples:
+ - - '{{ transform.XMLEscape "<p>abc</p>" }}'
+ - '<p>abc</p>'
+ urls:
+ AbsLangURL:
+ Aliases:
+ - absLangURL
+ Args:
+ - s
+ Description: |-
+ AbsLangURL the string s and converts it to an absolute URL according
+ to a page's position in the project directory structure and the current
+ language.
+ Examples: []
+ AbsURL:
+ Aliases:
+ - absURL
+ Args:
+ - s
+ Description: AbsURL takes the string s and converts it to an absolute URL.
+ Examples: []
+ Anchorize:
+ Aliases:
+ - anchorize
+ Args:
+ - s
+ Description: |-
+ Anchorize creates sanitized anchor name version of the string s that is compatible
+ with how your configured markdown renderer does it.
+ Examples:
+ - - '{{ "This is a title" | anchorize }}'
+ - this-is-a-title
+ JoinPath:
+ Aliases: null
+ Args:
+ - elements
+ Description: |-
+ JoinPath joins the provided elements into a URL string and cleans the result
+ of any ./ or ../ elements. If the argument list is empty, JoinPath returns
+ an empty string.
+ Examples:
+ - - '{{ urls.JoinPath "https://example.org" "foo" }}'
+ - https://example.org/foo
+ - - '{{ urls.JoinPath (slice "a" "b") }}'
+ - a/b
+ Parse:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
+ Ref:
+ Aliases:
+ - ref
+ Args:
+ - p
+ - args
+ Description: Ref returns the absolute URL path to a given content item from
+ Page p.
+ Examples: []
+ RelLangURL:
+ Aliases:
+ - relLangURL
+ Args:
+ - s
+ Description: |-
+ RelLangURL takes the string s and prepends the relative path according to a
+ page's position in the project directory structure and the current language.
+ Examples: []
+ RelRef:
+ Aliases:
+ - relref
+ Args:
+ - p
+ - args
+ Description: RelRef returns the relative URL path to a given content item
+ from Page p.
+ Examples: []
+ RelURL:
+ Aliases:
+ - relURL
+ Args:
+ - s
+ Description: |-
+ RelURL takes the string s and prepends the relative path according to a
+ page's position in the project directory structure.
+ Examples: []
+ URLize:
+ Aliases:
+ - urlize
+ Args:
+ - s
+ Description: URLize returns the strings s formatted as an URL.
+ Examples: []
--- /dev/null
--- /dev/null
++# Used by the embedded template URL (eturl.html) shortcode.
++# Quoted all keys because some are not valid identifiers.
++
++# BaseURL
++'base_url' = 'https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates'
++
++# Templates
++'alias' = 'alias.html'
++'disqus' = 'disqus.html'
++'google_analytics' = 'google_analytics.html'
++'opengraph' = 'opengraph.html'
++'pagination' = 'pagination.html'
++'schema' = 'schema.html'
++'twitter_cards' = 'twitter_cards.html'
++
++'robots' = '_default/robots.txt'
++'rss' = '_default/rss.xml'
++'sitemap' = '_default/sitemap.xml'
++'sitemapindex' = '_default/sitemapindex.xml'
++
++# Render hooks
++'render-image' = '_default/_markup/render-image.html'
++'render-link' = '_default/_markup/render-link.html'
++'render-codeblock-goat' = '_default/_markup/render-codeblock-goat.html'
++
++# Shortcodes
++'figure' = 'shortcodes/figure.html'
++'gist' = 'shortcodes/gist.html'
++'highlight' = 'shortcodes/highlight.html'
++'instagram' = 'shortcodes/instagram.html'
++'param' = 'shortcodes/param.html'
++'ref' = 'shortcodes/ref.html'
++'relref' = 'shortcodes/relref.html'
++'twitter' = 'shortcodes/twitter.html'
++'vimeo' = 'shortcodes/vimeo.html'
++'youtube' = 'shortcodes/youtube.html'
--- /dev/null
- link = "https://twitter.com/heinrichhartman/status/1199736512264462341"
+[[tweet]]
+name = "Heinrich Hartmann"
+twitter_handle = "@heinrichhartman"
+quote = "Working with @GoHugoIO is such a joy. Having worked with #Jekyll in the past, the near instant preview is a big win! Did not expect this to make such a huge difference."
- quote = "Can't overstate how much I enjoy <a href='https://twitter.com/gohugoio' target='_blank'>@GoHugoIO</a>. My site is relatively small, but *18 ms* to build the whole thing made template development and proofing a breeze."
- link = "https://twitter.com/jscarto/status/1039648827815485440"
++link = "https://x.com/heinrichhartman/status/1199736512264462341"
+date = 2019-11-12T00:00:00Z
+
+[[tweet]]
+name = "Joshua Steven"
+twitter_handle = "@jscarto"
- quote = "The more I use <a href='https://gohugo.io' target='_blank'>gohugo.io</a>, the more I really like it. Super intuitive/powerful static site generator...great job <a href='https://twitter.com/gohugoio' target='_blank'>@GoHugoIO</a>"
- link = "https://twitter.com/spcrngr_/status/870863020905435136"
++quote = "Can't overstate how much I enjoy <a href='https://x.com/gohugoio' target='_blank'>@GoHugoIO</a>. My site is relatively small, but *18 ms* to build the whole thing made template development and proofing a breeze."
++link = "https://x.com/jscarto/status/1039648827815485440"
+date = 2018-09-12T00:00:00Z
+
+[[tweet]]
+name = "Christophe Diericx"
+twitter_handle = "@spcrngr_"
- quote = "Blog migrated from <a href='https://twitter.com/WordPress' target='_blank'>@WordPress</a> to <a href='https://twitter.com/GoHugoIO' target='_blank'>@GoHugoIO</a>, with a little refresh of my theme, Vim shortcuts and a full featured deploy script <a href='https://twitter.com/hashtag/gohugo?src=hash' target='_blank'>#gohugo</a>"
- link = "https://twitter.com/marcoscan/status/869661175960752129"
++quote = "The more I use <a href='https://gohugo.io' target='_blank'>gohugo.io</a>, the more I really like it. Super intuitive/powerful static site generator...great job <a href='https://x.com/gohugoio' target='_blank'>@GoHugoIO</a>"
++link = "https://x.com/spcrngr_/status/870863020905435136"
+date = 2017-06-03T00:00:00Z
+
+[[tweet]]
+name = "marcoscan"
+twitter_handle = "@marcoscan"
- quote = "Who knew static site building could be fun 🤔 Learning <a href='https://twitter.com/hashtag/gohugo?src=hash'>#gohugo</a> today"
- link = "https://twitter.com/SKuipersDesign/status/868796256902029312"
++quote = "Blog migrated from <a href='https://x.com/WordPress' target='_blank'>@WordPress</a> to <a href='https://x.com/GoHugoIO' target='_blank'>@GoHugoIO</a>, with a little refresh of my theme, Vim shortcuts and a full featured deploy script <a href='https://x.com/hashtag/gohugo?src=hash' target='_blank'>#gohugo</a>"
++link = "https://x.com/marcoscan/status/869661175960752129"
+date = 2017-05-30T00:00:00Z
+
+[[tweet]]
+name = "Sandra Kuipers"
+twitter_handle = "@SKuipersDesign"
- quote = "Top Ten Static Site Generators of 2017. Congrats to the top 3: 1. <a href='https://twitter.com/jekyllrb'>@Jekyllrb</a> 2. <a href='https://twitter.com/GoHugoIO'>@GoHugoIO</a> 3. <a href='https://twitter.com/hexojs'>@hexojs</a>"
- link = "https://twitter.com/Netlify/status/868122279221362688"
++quote = "Who knew static site building could be fun 🤔 Learning <a href='https://x.com/hashtag/gohugo?src=hash'>#gohugo</a> today"
++link = "https://x.com/SKuipersDesign/status/868796256902029312"
+date = 2017-05-28T00:00:00Z
+
+[[tweet]]
+name = "Netlify"
+twitter_handle = "@Netlify"
- quote = "I've been keen on <a href='https://twitter.com/hashtag/JAMStack?src=hash' target='_blank'>#JAMStack</a> for some time, but <a href='https://twitter.com/gohugoio' target='_blank'>@GoHugoIO</a> is wooing me all over again. Great fun to build with. And speeeeedy."
- link = "https://twitter.com/philhawksworth/status/866684170512326657"
++quote = "Top Ten Static Site Generators of 2017. Congrats to the top 3: 1. <a href='https://x.com/jekyllrb'>@Jekyllrb</a> 2. <a href='https://x.com/GoHugoIO'>@GoHugoIO</a> 3. <a href='https://x.com/hexojs'>@hexojs</a>"
++link = "https://x.com/Netlify/status/868122279221362688"
+date = 2017-05-26T00:00:00Z
+
+[[tweet]]
+name = "Phil Hawksworth"
+twitter_handle = "@philhawksworth"
- quote = "I've probably said it before...but having Hugo rebuild the whole website in 300ms is amazing. <a href='https://gohugo.io' target='_blank'>gohugo.io</a>, <a href='https://twitter.com/hashtag/gohugo' target='_blank'>#gohugo</a>"
- link = "https://twitter.com/aras_p/status/861157286823288832"
++quote = "I've been keen on <a href='https://x.com/hashtag/JAMStack?src=hash' target='_blank'>#JAMStack</a> for some time, but <a href='https://x.com/gohugoio' target='_blank'>@GoHugoIO</a> is wooing me all over again. Great fun to build with. And speeeeedy."
++link = "https://x.com/philhawksworth/status/866684170512326657"
+date = 2017-05-22T00:00:00Z
+
+[[tweet]]
+name = "Aras Pranckevicius"
+twitter_handle = "@aras_p"
- quote = "Diving deeper into <a href='https://twitter.com/GoHugoIO' target='_blank' rel='noopener noreferrer'>@GoHugoIO</a>. A lot of docs there, top work! But I've the impressed that <a href='https://twitter.com/hashtag/gohugo' target='_blank' rel='noopener noreferrer'>#gohugo</a> is far easier than its feels from the docs!"
- link = "https://twitter.com/EnrichedGamesHB/status/836854762440130560"
++quote = "I've probably said it before...but having Hugo rebuild the whole website in 300ms is amazing. <a href='https://gohugo.io' target='_blank'>gohugo.io</a>, <a href='https://x.com/hashtag/gohugo' target='_blank'>#gohugo</a>"
++link = "https://x.com/aras_p/status/861157286823288832"
+date = 2017-05-07T00:00:00Z
+
+[[tweet]]
+name = "Hans Beck"
+twitter_handle = "@EnrichedGamesHB"
- quote = "I migrated the <a href='https://twitter.com/BlackOpsTesting' target='_blank' rel='noopener noreferrer'> @BlackOpsTesting </a>.com website from docpad to Hugo last weekend. http://gohugo.io/ Super Fast HTML Generation <a href='https://twitter.com/spf13' target='_blank' rel='noopener noreferrer'> @spf13 </a>"
- link = "https://twitter.com/eviltester/status/553520335115808768"
++quote = "Diving deeper into <a href='https://x.com/GoHugoIO' target='_blank' rel='noopener noreferrer'>@GoHugoIO</a>. A lot of docs there, top work! But I've the impressed that <a href='https://x.com/hashtag/gohugo' target='_blank' rel='noopener noreferrer'>#gohugo</a> is far easier than its feels from the docs!"
++link = "https://x.com/EnrichedGamesHB/status/836854762440130560"
+date = 2017-03-01T00:00:00Z
+
+[[tweet]]
+name = "Alan Richardson"
+twitter_handle = "@eviltester"
- quote = "Building <a href='https://twitter.com/garazaFRI' target='_blank' rel='noopener noreferrer'>@garazaFRI</a> website in <a href='https://twitter.com/hashtag/hugo' target='_blank' rel='noopener noreferrer'>#hugo</a>. This static site generator is soooo damn fast! <a href='https://twitter.com/hashtag/gohugo' target='_blank' rel='noopener noreferrer'>#gohugo</a> <a href='https://twitter.com/hashtag/golang' target='_blank' rel='noopener noreferrer'>#golang</a>"
- link = "https://twitter.com/jamziSLO/status/817720283977183234"
++quote = "I migrated the <a href='https://x.com/BlackOpsTesting' target='_blank' rel='noopener noreferrer'> @BlackOpsTesting </a>.com website from docpad to Hugo last weekend. http://gohugo.io/ Super Fast HTML Generation <a href='https://x.com/spf13' target='_blank' rel='noopener noreferrer'> @spf13 </a>"
++link = "https://x.com/eviltester/status/553520335115808768"
+date = 2015-01-09T00:00:00Z
+
+[[tweet]]
+name = "Janez Čadež"
+twitter_handle = "@jamziSLO"
- quote = "Hah, <a href='https://twitter.com/hashtag/gohugo' target='_blank' rel='noopener noreferrer'>#gohugo</a>. I was working with <a href='https://twitter.com/hashtag/gohugo' target='_blank' rel='noopener noreferrer'>#gohugo</a> on <a href='https://twitter.com/hashtag/linux' target='_blank' rel='noopener noreferrer'>#linux</a> but now I realised how easy is to set-up it on <a href='https://twitter.com/hashtag/windows' target='_blank' rel='noopener noreferrer'>#windows</a>. Just need to add binary to <a href='https://twitter.com/hashtag/path' target='_blank' rel='noopener noreferrer'>#path</a>!"
- link = "https://twitter.com/executerun/status/809753145270272005"
++quote = "Building <a href='https://x.com/garazaFRI' target='_blank' rel='noopener noreferrer'>@garazaFRI</a> website in <a href='https://x.com/hashtag/hugo' target='_blank' rel='noopener noreferrer'>#hugo</a>. This static site generator is soooo damn fast! <a href='https://x.com/hashtag/gohugo' target='_blank' rel='noopener noreferrer'>#gohugo</a> <a href='https://x.com/hashtag/golang' target='_blank' rel='noopener noreferrer'>#golang</a>"
++link = "https://x.com/jamziSLO/status/817720283977183234"
+date = 2017-01-07T00:00:00Z
+
+[[tweet]]
+name = "Execute"
+twitter_handle = "@executerun"
- quote = "Hugo is impressively capable. It's a static site generator by <a href='https://twitter.com/spf13'> @spf13 </a> written in <a href='https://twitter.com/hashtag/golang?src=hash'> #golang </a> . Just upgraded to latest release; very powerful. "
- link = "https://twitter.com/xaprb/status/556894866488455169"
++quote = "Hah, <a href='https://x.com/hashtag/gohugo' target='_blank' rel='noopener noreferrer'>#gohugo</a>. I was working with <a href='https://x.com/hashtag/gohugo' target='_blank' rel='noopener noreferrer'>#gohugo</a> on <a href='https://x.com/hashtag/linux' target='_blank' rel='noopener noreferrer'>#linux</a> but now I realised how easy is to set-up it on <a href='https://x.com/hashtag/windows' target='_blank' rel='noopener noreferrer'>#windows</a>. Just need to add binary to <a href='https://x.com/hashtag/path' target='_blank' rel='noopener noreferrer'>#path</a>!"
++link = "https://x.com/executerun/status/809753145270272005"
+date = 2016-12-16T00:00:00Z
+
+[[tweet]]
+name = "Baron Schwartz"
+twitter_handle = "@xaprb"
- link = "https://twitter.com/dch__/status/460158115498176512"
++quote = "Hugo is impressively capable. It's a static site generator by <a href='https://x.com/spf13'> @spf13 </a> written in <a href='https://x.com/hashtag/golang?src=hash'> #golang </a> . Just upgraded to latest release; very powerful. "
++link = "https://x.com/xaprb/status/556894866488455169"
+date = 2015-01-18T00:00:00Z
+
+[[tweet]]
+name = "Dave Cottlehuber"
+twitter_handle = "@dch__"
+quote = "I just fell in love with #hugo, a static site/blog engine written by @spf13 in #golang + stellar docs"
- link = "https://twitter.com/dcaunt/statuses/406466996277374976"
++link = "https://x.com/dch__/status/460158115498176512"
+date = 2014-04-26T00:00:00Z
+
+[[tweet]]
+name = "David Caunt"
+twitter_handle = "@dcaunt"
+quote = "I had a play with Hugo and it was good, uses Markdown files for content"
- link = "https://twitter.com/oddshocks/statuses/405083217893421056"
++link = "https://x.com/dcaunt/statuses/406466996277374976"
+date = 2013-11-29T00:00:00Z
+
+[[tweet]]
+name = "David Gay"
+twitter_handle = "@oddshocks"
+quote = "Hugo is super-rad."
- link = "https://twitter.com/DitiPengi/status/472470974051676160"
++link = "https://x.com/oddshocks/statuses/405083217893421056"
+date = 2013-11-25T00:00:00Z
+
+[[tweet]]
+name = "Diti"
+twitter_handle = "@DitiPengi"
+quote = "The dev version of Hugo is AWESOME! <3 I promise, I will try to learn go ASAP and help contribute to the project! Just too great!"
- link = "https://twitter.com/DougStephenJr/statuses/364512471660249088"
++link = "https://x.com/DitiPengi/status/472470974051676160"
+date = 2014-05-30T00:00:00Z
+
+[[tweet]]
+name = "Douglas Stephen "
+twitter_handle = "@DougStephenJr"
+quote = "Even as a long-time Octopress fan, I’ve gotta admit that this project Hugo looks very very cool"
- link = "https://twitter.com/hugorodgerbrown/statuses/364417910153818112"
++link = "https://x.com/DougStephenJr/statuses/364512471660249088"
+date = 2013-08-05T00:00:00Z
+
+[[tweet]]
+name = "Hugo Rodger-Brown"
+twitter_handle = "@hugorodgerbrown"
+quote = "Finally someone builds me my own static site generator"
- link = "https://twitter.com/hugoroyd/status/501704796727173120"
++link = "https://x.com/hugorodgerbrown/statuses/364417910153818112"
+date = 2013-05-08T00:00:00Z
+
+[[tweet]]
+name = "Hugo Roy"
+twitter_handle = "@hugoroyd"
+quote = "Finally the answer to the question my parents have been asking: What does Hugo do?"
- link = "https://twitter.com/DanielMiessler/status/704703841673957376"
++link = "https://x.com/hugoroyd/status/501704796727173120"
+date = 2014-08-19T00:00:00Z
+
+[[tweet]]
+name = "Daniel Miessler"
+twitter_handle = "@DanielMiessler"
+quote = "Websites for named vulnerabilities should run on static site generator platforms like Hugo. Read-only + burst traffic = static."
- link = "https://twitter.com/jsegura/status/465978434154659841"
++link = "https://x.com/DanielMiessler/status/704703841673957376"
+date = 2016-03-01T00:00:00Z
+
+[[tweet]]
+name = "Javier Segura"
+twitter_handle = "@jsegura"
+quote = "Another site generated with Hugo here! I'm getting in love with it."
- link = "https://twitter.com/jimbiancolo/statuses/408678420348813314"
++link = "https://x.com/jsegura/status/465978434154659841"
+date = 2014-05-12T00:00:00Z
+
+[[tweet]]
+name = "Jim Biancolo"
+twitter_handle = "@jimbiancolo"
+quote = "I’m loving the static site generator renaissance we are currently enjoying. Hugo is new, looks great, written in Go"
- link = "https://twitter.com/jipjdekker/status/413783548735152131"
++link = "https://x.com/jimbiancolo/statuses/408678420348813314"
+date = 2013-05-12T00:00:00Z
+
+[[tweet]]
+name = "Jip J. Dekker"
+twitter_handle = "@jipjdekker"
+quote = "Building a personal website in Hugo. Works like a charm. And written in @golang!"
- link = "https://twitter.com/jgonzalvo/statuses/408177855819173888"
++link = "https://x.com/jipjdekker/status/413783548735152131"
+date = 2013-12-19T00:00:00Z
+
+[[tweet]]
+name = "Jose Gonzalvo"
+twitter_handle = "@jgonzalvo"
+quote = "Checking out Hugo; Loving it so far. Like Jekyll but not so blog-oriented and written in go"
- link = "https://twitter.com/joshmatz/statuses/364437436870696960"
++link = "https://x.com/jgonzalvo/statuses/408177855819173888"
+date = 2013-12-04T00:00:00Z
+
+[[tweet]]
+name = "Josh Matz"
+twitter_handle = "@joshmatz"
+quote = "A static site generator without the long build times? Yes, please!"
- link = "https://twitter.com/kjhealy/status/437349384809115648"
++link = "https://x.com/joshmatz/statuses/364437436870696960"
+date = 2013-08-05T00:00:00Z
+
+[[tweet]]
+name = "Kieran Healy"
+twitter_handle = "@kjhealy"
+quote = "OK, so in today's speed battle of static site generators, @spf13's hugo is kicking everyone's ass, by miles."
- link = "https://twitter.com/ludovicchabant/statuses/408806199602053120"
++link = "https://x.com/kjhealy/status/437349384809115648"
+date = 2014-02-22T00:00:00Z
+
+[[tweet]]
+name = "Ludovic Chabant"
+twitter_handle = "@ludovicchabant"
+quote = "Good work on Hugo, I’m impressed with the speed!"
- link = "https://twitter.com/lukeholder/status/430352287936946176"
++link = "https://x.com/ludovicchabant/statuses/408806199602053120"
+date = 2013-12-06T00:00:00Z
+
+[[tweet]]
+name = "Luke Holder"
+twitter_handle = "@lukeholder"
+quote = "this is AWESOME. a single little executable and so fast."
- link = "https://twitter.com/markuseliasson/status/501594865877008384"
++link = "https://x.com/lukeholder/status/430352287936946176"
+date = 2014-02-03T00:00:00Z
+
+[[tweet]]
+name = "Markus Eliasson"
+twitter_handle = "@markuseliasson"
+quote = "Hugo is fast, dead simple to setup and well documented"
- link = "https://twitter.com/mercime_one/status/500547145087205377"
++link = "https://x.com/markuseliasson/status/501594865877008384"
+date = 2014-08-19T00:00:00Z
+
+[[tweet]]
+name = "mercime"
+twitter_handle = "@mercime_one"
+quote = "Hugo: Makes the Web Fun Again"
- link = "https://twitter.com/mdwhatcott/status/469980686531571712"
++link = "https://x.com/mercime_one/status/500547145087205377"
+date = 2014-08-16T00:00:00Z
+
+[[tweet]]
+name = "Michael Whatcott"
+twitter_handle = "@mdwhatcott"
+quote = "One more satisfied #Hugo blogger. Thanks @spf13 and friends!"
- link = "https://twitter.com/rojoroboto/status/423439915620106242"
++link = "https://x.com/mdwhatcott/status/469980686531571712"
+date = 2014-05-23T00:00:00Z
+
+[[tweet]]
+name = "Nathan Toups"
+twitter_handle = "@rojoroboto"
+quote = "I love Hugo! My site is generated with it now http://rjrbt.io"
- link = "https://twitter.com/messo85/status/472825062027182081"
++link = "https://x.com/rojoroboto/status/423439915620106242"
+date = 2014-01-15T00:00:00Z
+
+[[tweet]]
+name = "Ruben Solvang"
+twitter_handle = "@messo85"
+quote = "#Hugo is the new @jekyllrb / @middlemanapp! Faster, easier and runs everywhere."
- link = "https://twitter.com/popthestack/status/549972754125307904"
++link = "https://x.com/messo85/status/472825062027182081"
+date = 2014-05-31T00:00:00Z
+
+[[tweet]]
+name = "Ryan Martinsen"
+twitter_handle = "@popthestack"
+quote = "Also, I re-launched my blog (it looks the same as before) using Hugo, a *fast* static engine. Very happy with it. <a href='http://gohugo.io/'>gohugo.io</a>"
- link = "https://twitter.com/TheLoneCuber/status/495716684456398848"
++link = "https://x.com/popthestack/status/549972754125307904"
+date = 2014-12-30T00:00:00Z
+
+[[tweet]]
+name = "The Lone Cuber"
+twitter_handle = "@TheLoneCuber"
+quote = "Jekyll is dead to me these days though... long live Hugo! Hugo is *by far* the best in its field. Thanks for making it happen."
- link = "https://twitter.com/TheLoneCuber/status/495731334711488512"
++link = "https://x.com/TheLoneCuber/status/495716684456398848"
+date = 2014-08-02T00:00:00Z
+
+[[tweet]]
+name = "The Lone Cuber"
+twitter_handle = "@TheLoneCuber"
+quote = "Finally, a publishing platform that's a joy to use. #NoMoreBarriers"
- quote = "<a href='https://twitter.com/hashtag/Hugo?src=hash'> #Hugo </a> A very good alternative for <a href='https://twitter.com/hashtag/wordpress?src=hash'> #wordpress </a> !!! A fast and modern static website engine <a href='http://gohugo.io/'> gohugo.io </a>"
- link = "https://twitter.com/workhtml/status/563064361301053440"
++link = "https://x.com/TheLoneCuber/status/495731334711488512"
+date = 2014-08-02T00:00:00Z
+
+[[tweet]]
+name = "WorkHTML"
+twitter_handle = "@workhtml"
++quote = "<a href='https://x.com/hashtag/Hugo?src=hash'> #Hugo </a> A very good alternative for <a href='https://x.com/hashtag/wordpress?src=hash'> #wordpress </a> !!! A fast and modern static website engine <a href='http://gohugo.io/'> gohugo.io </a>"
++link = "https://x.com/workhtml/status/563064361301053440"
+date = 2015-02-04T00:00:00Z
--- /dev/null
+# Do not delete. Required for layouts/shortcodes/list-pages-in-section.html.
+#
+# When calling the list-pages-in-section shortcode, you can specify a page
+# filter, and whether the pages in the filter should be included or excluded
+# from the list.
+#
+# For example:
+#
+# {{< list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude >}}
+
+functions_fmt_logging:
+ - /functions/fmt/errorf
+ - /functions/fmt/erroridf
+ - /functions/fmt/warnf
++ - /functions/fmt/warnidf
+functions_images_no_filters:
+ - /functions/images/filter
+ - /functions/images/config
+methods_site_multilingual:
+ - /methods/site/ismultilingual
+ - /methods/site/language
+ - /methods/site/languageprefix
+ - /methods/site/languages
+methods_site_page_collections:
++ - /methods/site/allpages
+ - /methods/site/pages
+ - /methods/site/regularpages
+ - /methods/site/sections
+methods_page_dates:
+ - /methods/page/date
+ - /methods/page/expirydate
+ - /methods/page/lastmod
+ - /methods/page/publishdate
+methods_page_menu:
+ - /methods/page/hasmenucurrent
+ - /methods/page/ismenucurrent
+methods_page_multilingual:
+ - /methods/page/alltranslations
+ - /methods/page/istranslated
+ - /methods/page/language
+ - /methods/page/translationkey
+ - /methods/page/translations
+methods_page_page_collections:
+ - /methods/page/pages
+ - /methods/page/regularpages
+ - /methods/page/regularpagesrecursive
+ - /methods/page/sections
+methods_page_parameters:
+ - /methods/page/param
+ - /methods/page/params
+methods_page_sections:
+ - /methods/page/ancestors
+ - /methods/page/currentsection
+ - /methods/page/firstsection
+ - /methods/page/insection
+ - /methods/page/isancestor
+ - /methods/page/isdescendant
+ - /methods/page/parent
+ - /methods/page/sections
+ - /methods/page/section
+methods_pages_sort:
+ - /methods/pages/bydate
+ - /methods/pages/byexpirydate
+ - /methods/pages/bylanguage
+ - /methods/pages/bylastmod
+ - /methods/pages/bylength
+ - /methods/pages/bylinktitle
+ - /methods/pages/byparam
+ - /methods/pages/bypublishdate
+ - /methods/pages/bytitle
+ - /methods/pages/byweight
+ - /methods/pages/reverse
+methods_pages_group:
+ - /methods/pages/groupby
+ - /methods/pages/groupbydate
+ - /methods/pages/groupbyexpirydate
+ - /methods/pages/groupbylastmod
+ - /methods/pages/groupbyparam
+ - /methods/pages/groupbyparamdate
+ - /methods/pages/groupbypublishdate
+ - /methods/pages/groupbydate
+ - /methods/pages/groupbydate
+ - /methods/pages/groupbydate
+ - /methods/pages/groupbydate
+ - /methods/pages/groupbydate
+ - /methods/pages/groupbydate
+ - /methods/pages/reverse
+methods_pages_navigation:
+ - /methods/pages/next
+ - /methods/pages/prev
+methods_page_navigation:
+ - /methods/page/next
+ - /methods/page/nextinsection
+ - /methods/page/prev
+ - /methods/page/previnsection
--- /dev/null
- require github.com/gohugoio/gohugoioTheme v0.0.0-20240201183016-8e648a3b5342 // indirect
+module github.com/gohugoio/hugoDocs
+
+go 1.16
+
++require github.com/gohugoio/gohugoioTheme v0.0.0-20240619093131-b595d5fb8c52 // indirect
--- /dev/null
- github.com/gohugoio/gohugoioTheme v0.0.0-20240201183016-8e648a3b5342 h1:jQaO+i2osHeIZ+V7Dvo7CPqN6jPwMRjt7b9QaX7HXE4=
- github.com/gohugoio/gohugoioTheme v0.0.0-20240201183016-8e648a3b5342/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM=
++github.com/gohugoio/gohugoioTheme v0.0.0-20240426212330-f38e99e0d88d h1:EaFz80Aqh3Ej20VmUSNe3K+F0NbT8UueXLP/VqkK9Dw=
++github.com/gohugoio/gohugoioTheme v0.0.0-20240426212330-f38e99e0d88d/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM=
++github.com/gohugoio/gohugoioTheme v0.0.0-20240508091825-b23e8e2d2419 h1:cQ/44eDHK0tVImTtSx/9sWWZv+RynH/oB4R7ASbQNAE=
++github.com/gohugoio/gohugoioTheme v0.0.0-20240508091825-b23e8e2d2419/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM=
++github.com/gohugoio/gohugoioTheme v0.0.0-20240619093131-b595d5fb8c52 h1:dPJxUU4SevIZ7OS1DIVOrJ7p8I/QM00pXGRfAtKgQmU=
++github.com/gohugoio/gohugoioTheme v0.0.0-20240619093131-b595d5fb8c52/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM=
--- /dev/null
- section = ["HTML", "RSS"]
+# This his the main configuration file. There are also environment specific configuration stored in the /config directory.
+
+baseURL = "https://gohugo.io/"
+defaultContentLanguage = "en"
+enableEmoji = true
+ignoreErrors = ["error-remote-getjson", "error-missing-instagram-accesstoken"]
+languageCode = "en-us"
+paginate = 100
+pluralizeListTitles = false
+timeZone = "Europe/Oslo"
+title = "Hugo"
+
+# We do redirects via Netlify's _redirects file, generated by Hugo (see "outputs" below).
+disableAliases = true
+
+[services.googleAnalytics]
+ID = 'G-MBZGKNMDWC'
+
+[minify]
+ [minify.tdewolff]
+ [minify.tdewolff.html]
+ keepWhitespace = true
+
+[module]
+ [module.hugoVersion]
+ min = "0.56.0"
+ [[module.imports]]
+ path = "github.com/gohugoio/gohugoioTheme"
+
+[outputs]
+ home = ["HTML", "RSS", "REDIR", "HEADERS"]
++ section = ["HTML"]
+
+[mediaTypes]
+ [mediaTypes."text/netlify"]
+ delimiter = ""
+
+[outputFormats]
+ [outputFormats.REDIR]
+ mediatype = "text/netlify"
+ baseName = "_redirects"
+ isPlainText = true
+ notAlternative = true
+ [outputFormats.HEADERS]
+ mediatype = "text/netlify"
+ baseName = "_headers"
+ isPlainText = true
+ notAlternative = true
+
+[caches]
+ [caches.getjson]
+ dir = ":cacheDir/:project"
+ maxAge = -1
+ [caches.getcsv]
+ dir = ":cacheDir/:project"
+ maxAge = -1
+ [caches.images]
+ dir = ":cacheDir/images"
+ maxAge = "1440h"
+ [caches.assets]
+ dir = ":resourceDir/_gen"
+ maxAge = -1
+ [caches.getresource]
+ dir = ":cacheDir/:project"
+ maxage = '1h'
+
+[related]
+ threshold = 80
+ includeNewer = true
+ toLower = false
+ [[related.indices]]
+ name = "keywords"
+ weight = 60
+ [[related.indices]]
+ # Can be used as a front matter slice to link to other page fragments (headings) using their ID.
+ # This isn't particular useful in the current docs, but we're planning on getting a auto generated
+ # reference section with a better ID setup.
+ # For now, we just use it to give pages with same headings some similarity score.
+ name = "fragmentrefs"
+ type = "fragments"
+ applyFilter = false
+ weight = 60
+ cardinalityThreshold = 50
+
+[imaging]
+ # See https://github.com/disintegration/imaging
+ # CatmullRom is a sharp bicubic filter which should fit the docs site well with its many screenshots.
+ # Note that you can also set this per image processing.
+ resampleFilter = "CatmullRom"
+ # Default JPEG quality setting. Default is 75.
+ quality = 75
+ anchor = "smart"
+
+[taxonomies]
+ category = "categories"
+
+[[cascade]]
+categories = ['commands']
+[cascade._target]
+path = '/commands/**'
--- /dev/null
- HUGO_VERSION = "0.122.0"
+[build]
+ publish = "public"
+ command = "hugo --gc --minify"
+
+ [build.environment]
++ HUGO_VERSION = "0.127.0"
+
+[context.production.environment]
+ HUGO_ENV = "production"
+ HUGO_ENABLEGITINFO = "true"
+
+[context.split1]
+ command = "hugo --gc --minify --enableGitInfo"
+
+ [context.split1.environment]
+ HUGO_ENV = "production"
+
+[context.deploy-preview]
+ command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL"
+
+[context.branch-deploy]
+ command = "hugo --gc --minify -b $DEPLOY_PRIME_URL"
+
+[context.next.environment]
+ HUGO_ENABLEGITINFO = "true"
+
+[[redirects]]
+ from = "/npmjs/*"
+ to = "/npmjs/"
+ status = 200
--- /dev/null
--- /dev/null
++[
++ {
++ "author": "Victor Hugo",
++ "cover": "https://gohugo.io/shared/examples/images/the-hunchback-of-notre-dame.webp",
++ "date": "2024-05-06",
++ "isbn": "978-0140443530",
++ "rating": 4,
++ "summary": "In the vaulted Gothic towers of **Notre-Dame Cathedral** lives Quasimodo, the hunchbacked bellringer. Mocked and shunned for his appearance, he is pitied only by Esmerelda, a beautiful gypsy dancer to whom he becomes completely devoted. Esmerelda, however, has also attracted the attention of the sinister archdeacon Claude Frollo, and when she rejects his lecherous approaches, Frollo hatches a plot to destroy her, that only Quasimodo can prevent. Victor Hugo's sensational, evocative novel brings life to the medieval Paris he loved, and mourns its passing in one of the greatest historical romances of the nineteenth century.",
++ "tags": [
++ "fiction",
++ "historical"
++ ],
++ "title": "The Hunchback of Notre Dame"
++ },
++ {
++ "author": "Victor Hugo",
++ "cover": "https://gohugo.io/shared/examples/images/les-misérables.webp",
++ "date": "2022-12-30",
++ "isbn": "978-0451419439",
++ "rating": 5,
++ "summary": "Introducing one of the most **famous characters** in literature, Jean Valjean—the noble peasant imprisoned for stealing a loaf of bread—Les Misérables ranks among the greatest novels of all time. In it, Victor Hugo takes readers deep into the Parisian underworld, immerses them in a battle between good and evil, and carries them to the barricades during the uprising of 1832 with a breathtaking realism that is unsurpassed in modern prose.",
++ "tags": [
++ "fiction",
++ "historical",
++ "revolution"
++ ],
++ "title": "Les Misérables"
++ },
++ {
++ "author": "Alexis de Tocqueville",
++ "cover": "https://gohugo.io/shared/examples/images/the-ancien-régime-and-the-revolution.webp",
++ "date": "2023-04-01",
++ "isbn": "978-0141441641",
++ "rating": 3,
++ "summary": "The Ancien Régime and the Revolution is a comparison of **revolutionary France** and the despotic rule it toppled. Alexis de Tocqueville (1805–59) is an objective observer of both periods – providing a merciless critique of the ancien régime, with its venality, oppression and inequality, yet acknowledging the reforms introduced under Louis XVI, and claiming that the post-Revolution state was in many ways as tyrannical as that of the King; its once lofty and egalitarian ideals corrupted and forgotten. Writing in the 1850s, Tocqueville wished to expose the return to despotism he witnessed in his own time under Napoleon III, by illuminating the grand, but ultimately doomed, call to liberty made by the French people in 1789. His eloquent and instructive study raises questions about liberty, nationalism and justice that remain urgent today.",
++ "tags": [
++ "nonfiction",
++ "revolution"
++ ],
++ "title": "The Ancien Régime and the Revolution"
++ },
++ {
++ "author": "François Furet",
++ "cover": "https://gohugo.io/shared/examples/images/interpreting-the-french-revolution.webp",
++ "date": "2024-01-12",
++ "isbn": "978-0521280495",
++ "rating": 5,
++ "summary": "The French Revolution is an historical event **unlike any other**. It is more than just a topic of intellectual interest: it has become part of a moral and political heritage. But after two centuries, this central event in French history has usually been thought of in much the same terms as it was by its contemporaries. There have been many accounts of the French Revolution, and though their opinions differ, they have often been commemorative or anniversary interpretations of the original event. The dividing line of revolutionary historiography, in intellectual terms, is therefore not between the right and the left, but between commemorative and conceptual history, as exemplified respectively in the works of Michelet and Tocquevifle. In this book, François Furet analyses how an event like the French Revolution can be conceptualised, and identifies the radically new changes the Revolution produced as well as the continuity it provided, albeit under the appearance of change. This question has become a riddle for the European left, answered neither by Marx nor by the theorists of our own century. In his analysis of the tragic relevance of the Revolution, Furet both refers to contemporary experience and discusses various elements in the work of Alexis de Tocclueville and that of Augustin Cochin, which has never been systematically applied by historians of the Revolution. Furet's book is based on the complementary ideas of these two writers in an attempt to cut through the apparent and misleading clarity of various contradictory views of the Revolution, and to help decipher some of the enigmatic problems of revolutionary ideology. It will be of value to historians of modern Europe and their students; to political, social and economic historians; to sociologists; and to students of political thought.",
++ "tags": [
++ "nonfiction",
++ "revolution"
++ ],
++ "title": "Interpreting the French Revolution"
++ }
++]
projects / brevno-suite / hugo / commitdiff
