From: Bjørn Erik Pedersen Date: Fri, 21 Jun 2024 07:41:24 +0000 (+0200) Subject: Merge commit '8b9803425e63e1b1801f8d5d676e96368d706722' X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=af0cb57aaf668278551454678eac60b17348b13c;p=brevno-suite%2Fhugo Merge commit '8b9803425e63e1b1801f8d5d676e96368d706722' --- af0cb57aaf668278551454678eac60b17348b13c diff --cc docs/.cspell.json index de66ff601,000000000..95e3ed5ce mode 100644,000000..100644 --- a/docs/.cspell.json +++ b/docs/.cspell.json @@@ -1,139 -1,0 +1,171 @@@ +{ + "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", - "^(\\s*`{3,}).*[\\s\\S]*?^\\1", ++ "^(\\s*`{3,}).*[\\s\\S]*?^\\1$", + "# cspell: ignore words joined with dot", + "\\w+\\.\\w+", + "# cspell: ignore strings within backticks", + "`.+`", - "# cspell: ignore strings within single quotes", - "'.+'", + "# 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": [ - "antialiasing", - "codeowners", + "composability", + "configurators", + "defang", + "deindent", + "downscale", - "downscaled", + "downscaling", + "exif", + "geolocalized", + "grayscale", + "marshal", + "marshaling", + "multihost", ++ "multiplatfom", + "performantly", + "preconfigured", + "prerendering", + "redirection", + "redirections", - "shortcode", - "shortcodes", + "subexpression", - "subexpressions", - "suppressable", ++ "suppressible", + "templating", + "transpile", - "transpiles", + "unmarshal", - "unmarshals", + "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", - "miesięcy", ++ "miesiąca", ++ "miesiące", + "miesięcy", + "misérables", ++ "mittwoch", ++ "muchos", ++ "novembre", ++ "otro", ++ "pocos", ++ "produkte", + "projekt", ++ "prywatność", ++ "referenz", + "régime", + "# ----------------------------------------------------------------------", - "# cspell: ignore proper nouns", ++ "# 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", - "gohugoio", + "goldmark", - "KaTeX", ++ "katex", + "kubuntu", + "lubuntu", - "MathJax", ++ "mathjax", + "nosql", + "pandoc", + "pkgin", + "rclone", + "xubuntu", + "# ----------------------------------------------------------------------", + "# cspell: ignore miscellaneous", + "# ----------------------------------------------------------------------", ++ "achristie", ++ "ddmaurier", + "dring", - "getenv", - "gohugo", + "inor", ++ "jausten", + "jdoe", ++ "jsmith", + "milli", + "rgba", + "rsmith", - "stringifier", - "struct", + "tdewolff", + "tjones", - "toclevels", - "vals", - "xfeff", - "zgotmplz" ++ "wcag", ++ "xfeff" + ] +} diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/data/sponsors.toml index c8986a8c6,000000000..8e485b2a4 mode 100644,000000..100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/data/sponsors.toml +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/data/sponsors.toml @@@ -1,22 -1,0 +1,22 @@@ +[[banners]] + name = "Linode" + link = "https://www.linode.com/" + logo = "images/sponsors/linode-logo.svg" + utm_campaign = "hugosponsor" + bgcolor = "#ffffff" + +[[banners]] - 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" ++ 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'" diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/_markup/render-link.html index 5583d53d7,000000000..9b6cad114 mode 100644,000000..100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/_markup/render-link.html +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/_markup/render-link.html @@@ -1,250 -1,0 +1,250 @@@ - {{- /* 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. */ -}} +{{ .Text | safeHTML }} + +{{- 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 -}} diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/index.rss.xml index 1d3498a1e,000000000..26afc1816 mode 100644,000000..100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/index.rss.xml +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/index.rss.xml @@@ -1,38 -1,0 +1,68 @@@ ++{{- printf "" | safeHTML }} + + - {{ .Site.Title }} – {{ .Title }} ++ Hugo News ++ Recent news about Hugo, a static site generator written in Go, optimized for speed and designed for flexibility. + {{ .Permalink }} - Recent Hugo news from gohugo.io - Hugo -- gohugo.io{{ with .Site.LanguageCode }} - {{.}}{{end}}{{ with .Site.Author.email }} - {{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}{{end}}{{ with .Site.Author.email }} - {{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}{{end}}{{ with .Site.Copyright }} - {{.}}{{end}}{{ if not .Date.IsZero }} - {{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}{{ end }} - - {{ "img/hugo.png" | absURL }} - GoHugo.io - {{ .Permalink }} - - {{ with .OutputFormats.Get "RSS" }} - {{ printf "" .Permalink .MediaType | safeHTML }} - {{ end }} - {{ range first 50 (where .Site.RegularPages "Type" "in" (slice "news" "showcase")) }} - - {{ .Section | title }}: {{ .Title }} - {{ .Permalink }} - {{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }} - {{ with .Site.Author.email }}{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}{{end}} - {{ .Permalink }} - - {{ $img := (.Resources.ByType "image").GetMatch "*featured*" }} - {{ with $img }} - {{ $img := .Resize "640x" }} - {{ printf "]]>" $img.Permalink $img.Width $img.Height | safeHTML }} - {{ end }} - {{ .Content | html }} - - - {{ end }} ++ Hugo {{ hugo.Version }} ++ {{ or site.Language.LanguageCode site.Language.Lang }} ++ {{- with site.Copyright }} ++ {{ . }} ++ {{- end }} ++ {{- with .OutputFormats.Get "RSS" }} ++ {{ printf "" .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 }} ++ {{ (index $news_items 0).PublishDate.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }} ++ ++ {{- /* Render items. */}} ++ {{- range $news_items }} ++ ++ {{ .Title }} ++ {{ .Permalink }} ++ {{ .PublishDate.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }} ++ {{ .Permalink }} ++ {{ .Summary | transform.XMLEscape | safeHTML }} ++ ++ {{- end }} + - ++ diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/news/list.html index 5165c8a13,000000000..a41e45a2c mode 100644,000000..100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/news/list.html +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/news/list.html @@@ -1,70 -1,0 +1,57 @@@ +{{ define "main" }} +
+ +
+

+ {{ .Title }} +

+
+ {{ .Content }} +
+
+ +
+ {{ $interior_classes := $.Site.Params.flex_box_interior_classes }} +
+ + {{ $news_items := slice }} + + {{/* Get releases from GitHub. */}} + {{ $u := "https://api.github.com/repos/gohugoio/hugo/releases" }} - {{ $releases := partial "inline/get-remote-data.html" $u }} ++ {{ $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 }} + +
+
+ +
+{{ end }} - - {{ 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 }} diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/news/list.xml index 000000000,000000000..40bca59eb new file mode 100644 --- /dev/null +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/news/list.xml @@@ -1,0 -1,0 +1,68 @@@ ++{{- printf "" | safeHTML }} ++ ++ ++ Hugo News ++ Recent news about Hugo, a static site generator written in Go, optimized for speed and designed for flexibility. ++ {{ .Permalink }} ++ Hugo {{ hugo.Version }} ++ {{ or site.Language.LanguageCode site.Language.Lang }} ++ {{- with site.Copyright }} ++ {{ . }} ++ {{- end }} ++ {{- with .OutputFormats.Get "RSS" }} ++ {{ printf "" .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 }} ++ {{ (index $news_items 0).PublishDate.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }} ++ ++ {{- /* Render items. */}} ++ {{- range $news_items }} ++ ++ {{ .Title }} ++ {{ .Permalink }} ++ {{ .PublishDate.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }} ++ {{ .Permalink }} ++ {{ .Summary | transform.XMLEscape | safeHTML }} ++ ++ {{- end }} ++ ++ diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/open-source-involvement.html index 5300fb7a8,000000000..865a5161e mode 100644,000000..100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/open-source-involvement.html +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/open-source-involvement.html @@@ -1,59 -1,0 +1,59 @@@ +
+
- Github Logo ++ Github Logo +
+
+ +
+ +
+

We welcome all contributions

+ + +
+ + +
+
+ +

Hugo is open-source and completely free.

+

Our hundreds of contributors make Hugo great.

+
+
+ + +
+

More ways to contribute

+ +
+ + + + + +
diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/sponsors.html index 6838ce36a,000000000..3b7f6bfef mode 100644,000000..100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/sponsors.html +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/sponsors.html @@@ -1,53 -1,0 +1,57 @@@ +{{ $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 }} + +
+
+

Hugo Sponsors

+
+ {{ range .banners }} +
+ {{ $query_params := .query_params | default "" }} + {{ $url := printf "%s?%s%s" .link $query_params (querify "utm_source" (.utm_source | default $utmSource ) "utm_medium" "banner" "utm_campaign" (.utm_campaign | default "hugosponsor") "utm_content" (.utm_content | default "gohugoio")) | safeURL }} + {{ $logo := resources.Get .logo }} - {{ if hugo.IsProduction }} - {{ $gtagID := printf "Sponsor %s %s" .name $gtag | title }} - - {{ with $logo }}{{ .Content | safeHTML }}{{ end }} - ++ {{ $gtagID := printf "Sponsor %s %s" .name $gtag | title }} ++ {{ $classes := "" }} ++ {{ if .show_on_hover }} ++ {{ $classes = printf "%s show-on-hover" $classes }} ++ {{ end }} ++ {{ if $isFooter }} ++ {{ $classes = printf "%s f3" $classes }} + {{ else }} - - {{ with $logo }}{{ .Content | safeHTML }}{{ end }} - ++ {{ $classes = printf "%s f1" $classes }} + {{ end }} ++ ++ {{ with $logo }} ++ {{ .Content | safeHTML }} ++ {{ else }} ++ {{ .name }} ++ {{ end }} ++ +
+ {{ end }} +
+
+
+{{ end }} diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/utilities/get-remote-data.html index 000000000,000000000..69ac41da4 new file mode 100644 --- /dev/null +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/utilities/get-remote-data.html @@@ -1,0 -1,0 +1,23 @@@ ++{{/* ++Parses the serialized data from the given URL and returns a map or an array. ++ ++Supports CSV, JSON, TOML, YAML, and XML. ++ ++@param {string} . The URL from which to retrieve the serialized data. ++@returns {any} ++ ++@example {{ partial "get-remote-data.html" "https://example.org/foo.json" }} ++*/}} ++ ++{{ $url := . }} ++{{ $data := dict }} ++{{ with resources.GetRemote $url }} ++ {{ with .Err }} ++ {{ errorf "%s" . }} ++ {{ else }} ++ {{ $data = .Content | transform.Unmarshal }} ++ {{ end }} ++{{ else }} ++ {{ errorf "Unable to get remote resource %q" $url }} ++{{ end }} ++{{ return $data }} diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/eturl.html index 000000000,000000000..c0cf30aec new file mode 100644 --- /dev/null +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/eturl.html @@@ -1,0 -1,0 +1,36 @@@ ++{{- /* ++Renders an absolute URL to the source code for an embedded template. ++ ++Accepts either positional or named parameters, and depends on the ++embedded_templates.toml file in the data directory. ++ ++@param {string} filename The embedded template's file name, excluding extension. ++ ++@returns template.HTML ++ ++@example {{% et robots.txt %}} ++@example {{% et filename=robots.txt %}} ++*/}} ++ ++{{- /* Get parameters. */}} ++{{- $filename := "" -}} ++{{- if .IsNamedParams -}} ++ {{- $filename = .Get "filename" -}} ++{{- else -}} ++ {{- $filename = .Get 0 -}} ++{{- end -}} ++ ++{{- /* Render. */}} ++{{- with $filename -}} ++ {{- with site.Data.embedded_template_urls -}} ++ {{- with index . $filename -}} ++ {{- urls.JoinPath site.Data.embedded_template_urls.base_url . -}} ++ {{- else -}} ++ {{- errorf "The %q shortcode was unable to find a URL for the embedded template named %q. Check the name. See %s" $.Name $filename $.Position -}} ++ {{- end -}} ++ {{- else -}} ++ {{- errorf "The %q shortcode was unable to find the embedded_template_urls data file in the site's data directory. See %s" $.Name $.Position -}} ++ {{- end -}} ++{{- else -}} ++ {{- errorf "The %q shortcodes requires a named or positional parameter, the file name of the embedded template, excluding its extension. See %s" .Name .Position -}} ++{{- end -}} diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/img.html index 50d4da9ed,000000000..dd8c60e18 mode 100644,000000..100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/img.html +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/img.html @@@ -1,379 -1,0 +1,381 @@@ +{{- /* +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 - "autoorient" "brightness" "colorbalance" "colorize" "contrast" "gamma" - "gaussianblur" "grayscale" "hue" "invert" "none" "opacity" "overlay" ++ "autoorient" "brightness" "colorbalance" "colorize" "contrast" "dither" ++ "gamma" "gaussianblur" "grayscale" "hue" "invert" "none" "opacity" "overlay" + "padding" "pixelate" "process" "saturation" "sepia" "sigmoid" "text" + "unsharpmask" +}} + +{{- 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 }} +

Original

+ {{ $alt }} +

Processed

+ {{ $alt }} +{{- else -}} + {{ $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" }} ++ {{- 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 -}} diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/new-in.html index e22a91f3d,000000000..606d2219c mode 100644,000000..100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/new-in.html +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/new-in.html @@@ -1,36 -1,0 +1,34 @@@ +{{- /* +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 }} - ++ New in v{{ $version }} + {{- end }} +{{- else }} + {{- errorf "The %q shortcode requires a positional parameter (version). See %s" .Name .Position }} +{{- end -}} diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/static/images/Github.svg index 000000000,000000000..f202ff878 new file mode 100644 --- /dev/null +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/static/images/Github.svg @@@ -1,0 -1,0 +1,1 @@@ ++ diff --cc docs/_vendor/modules.txt index a63ac09b9,000000000..100c6fc6f mode 100644,000000..100644 --- a/docs/_vendor/modules.txt +++ b/docs/_vendor/modules.txt @@@ -1,1 -1,0 +1,1 @@@ - # github.com/gohugoio/gohugoioTheme v0.0.0-20240201183016-8e648a3b5342 ++# github.com/gohugoio/gohugoioTheme v0.0.0-20240619093131-b595d5fb8c52 diff --cc docs/config/_default/menus/menus.en.toml index cd337cbee,000000000..b0da48817 mode 100644,000000..100644 --- a/docs/config/_default/menus/menus.en.toml +++ b/docs/config/_default/menus/menus.en.toml @@@ -1,152 -1,0 +1,152 @@@ +[[docs]] +identifier = 'about' - name = 'About Hugo' ++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 = 40 ++weight = 50 +identifier = 'content-management' +post = 'expanded' +pageRef = '/content-management/' + +[[docs]] +name = 'Templates' - weight = 50 ++weight = 60 +identifier = 'templates' +pageRef = '/templates/' + +[[docs]] +name = 'Functions' - weight = 60 ++weight = 70 +identifier = 'functions' +pageRef = '/functions/' + +[[docs]] +name = 'Methods' - weight = 70 ++weight = 80 +identifier = 'methods' +pageRef = '/methods/' + +[[docs]] - name = 'Quick reference' - weight = 80 - identifier = 'quick-reference' - pageRef = '/quick-reference/' - - [[docs]] - name = 'Variables' - weight = 85 - identifier = 'variables' - pageRef = '/variables/' ++name = 'Render hooks' ++weight = 90 ++identifier = 'render-hooks' ++pageRef = '/render-hooks/' + +[[docs]] +name = 'Hugo Modules' - weight = 90 ++weight = 100 +identifier = 'modules' +pageRef = '/hugo-modules/' + +[[docs]] +name = 'Hugo Pipes' - weight = 100 ++weight = 110 +identifier = 'hugo-pipes' +pageRef = '/hugo-pipes/' + +[[docs]] +name = 'CLI' - weight = 110 ++weight = 120 +post = 'break' +identifier = 'commands' +pageRef = '/commands/' + +# Low level items + +[[docs]] +name = 'Troubleshooting' - weight = 120 ++weight = 130 +identifier = 'troubleshooting' +pageRef = '/troubleshooting/' + +[[docs]] +name = 'Developer tools' - weight = 130 ++weight = 140 +identifier = 'developer-tools' +pageRef = '/tools/' + +[[docs]] +name = 'Hosting and deployment' - weight = 140 ++weight = 150 +identifier = 'hosting-and-deployment' +pageRef = '/hosting-and-deployment/' + +[[docs]] +name = 'Contribute' - weight = 150 ++weight = 160 +post = 'break' +identifier = 'contribute' +pageRef = '/contribute/' + +######## 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' diff --cc docs/content/en/_index.md index 69d40ebcf,000000000..96ba0c413 mode 100644,000000..100644 --- a/docs/content/en/_index.md +++ b/docs/content/en/_index.md @@@ -1,49 -1,0 +1,49 @@@ +--- +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. ++ 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. diff --cc docs/content/en/about/_index.md index 3a8319029,000000000..333a9ba36 mode 100644,000000..100644 --- a/docs/content/en/about/_index.md +++ b/docs/content/en/about/_index.md @@@ -1,16 -1,0 +1,16 @@@ +--- +title: About Hugo - linkTitle: Overview - description: Hugo's features, roadmap, license, and motivation. ++linkTitle: In this section ++description: Learn about Hugo and its features, security model, and privacy protections. +categories: [] +keywords: [] +menu: + docs: - identifier: about-hugo-overview ++ identifier: about-hugo-in-this-section + parent: about + weight: 10 +weight: 10 +aliases: [/about-hugo/,/docs/] +--- + - Hugo is not your average static site generator. ++Learn about Hugo and its features, privacy protections, and security model. diff --cc docs/content/en/about/features.md index a94ce5526,000000000..ff7e9ce13 mode 100644,000000..100644 --- a/docs/content/en/about/features.md +++ b/docs/content/en/about/features.md @@@ -1,80 -1,0 +1,136 @@@ +--- - title: Hugo features - description: Hugo boasts blistering speed, robust content management, and a powerful templating language making it a great fit for all kinds of static websites. ++title: Features ++description: Hugo's rich and powerful feature set provides the framework and tools to create static sites that build in seconds, often less. +categories: [about] +keywords: [] +menu: + docs: + parent: about + weight: 30 +weight: 30 +toc: true +--- + - ## General - - * [Extremely fast] build times (< 1 ms per page) - * Completely cross platform, with [easy installation][install] on macOS, Linux, Windows, and more - * Renders changes on the fly with [LiveReload] as you develop - * [Powerful theming] - * [Host your site anywhere][hostanywhere] - - ## Organization - - * Straightforward [organization for your projects], including website sections - * Customizable [URLs] - * Support for configurable [taxonomies], including categories and tags - * [Sort content] as you desire through powerful template [functions] - * Automatic [table of contents] generation - * [Dynamic menu] creation - * [Pretty URLs] support - * [Permalink] pattern support - * Redirects via [aliases] - - ## Content - - * Native Markdown and Emacs Org-Mode support, as well as other languages via *external helpers* (see [supported formats]) - * TOML, YAML, and JSON metadata support in [front matter] - * Customizable [homepage] - * Multiple [content types] - * Automatic and user defined [content summaries] - * [Shortcodes] to enable rich content inside of Markdown - * ["Minutes to Read"][pagevars] functionality - * ["WordCount"][pagevars] functionality - - ## Additional features - - * Integrated [Disqus] comment support - * Integrated [Google Analytics] support - * Automatic [RSS] creation - * Support for [Go] HTML templates - * [Syntax highlighting] powered by [Chroma] - - [aliases]: /content-management/urls/#aliases - [Chroma]: https://github.com/alecthomas/chroma - [content summaries]: /content-management/summaries/ - [content types]: /content-management/types/ - [Disqus]: https://disqus.com/ - [Dynamic menu]: /templates/menu-templates/ - [Extremely fast]: https://github.com/bep/hugo-benchmark - [front matter]: /content-management/front-matter/ - [functions]: /functions/ - [Go]: https://pkg.go.dev/html/template - [Google Analytics]: https://google-analytics.com/ - [homepage]: /templates/homepage/ - [hostanywhere]: /hosting-and-deployment/ - [install]: /installation/ - [LiveReload]: /getting-started/usage/ - [organization for your projects]: /getting-started/directory-structure/ - [pagevars]: /variables/page/ - [Permalink]: /content-management/urls/#permalinks - [Powerful theming]: /hugo-modules/theme-components/ - [Pretty URLs]: /content-management/urls/ - [RSS]: /templates/rss/ ++## Framework ++ ++[Multiplatform] ++: Install Hugo's single executable on Linux, macOS, Windows, and more. ++ ++[Multilingual] ++: Localize your project for each language and region, including translations, images, dates, currencies, numbers, percentages, and collation sequence. Hugo's multilingual framework supports single-host and multihost configurations. ++ ++[Output formats] ++: Render each page of your site to one or more output formats, with granular control by page kind, section, and path. While HTML is the default output format, you can add JSON, RSS, CSV, and more. For example, create a REST API to access content. ++ ++[Templates] ++: Create templates usings variables, functions, and methods to transform your content, resources, and data into a published page. While HTML templates are the most common, you can create templates for any output format. ++ ++[Themes] ++: Reduce development time and cost by using one of the hundreds of themes contributed by the Hugo community. Themes are available for corporate sites, documentation projects, image portfolios, landing pages, personal and professional blogs, resumes, CVs, and more. ++ ++[Modules] ++: Reduce development time and cost by creating or importing packaged combinations of archetypes, assets, content, data, templates, translation tables, static files, or configuration settings. A module may serve as the basis for a new site, or to augment an existing site. ++ ++[Privacy] ++: Configure the behavior of Hugo's embedded templates and shortcodes to facilitate compliance with regional privacy regulations, including the [GDPR] and [CCPA]. ++ ++[Security] ++: Hugo's security model is based on the premise that template and configuration authors are trusted, but content authors are not. This model enables generation of HTML output safe against code injection. Other protections prevent "shelling out" to arbitrary applications, limit access to specific environment variables, prevent connections to arbitrary remote data sources, and more. ++ ++## Content authoring ++ ++[Content formats] ++: Create your content using Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, or reStructuredText. Markdown is the default content format, conforming to the [CommonMark] and [GitHub Flavored Markdown] specifications. ++ ++[Markdown attributes] ++: Apply HTML attributes such as `class` and `id` to Markdown images and block elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables. ++ ++[Markdown extensions] ++: Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more. ++ ++[Markdown render hooks] ++: Override the conversion of Markdown to HTML when rendering fenced code blocks, headings, images, and links. For example, render every standalone image as an HTML `figure` element. ++ ++[Diagrams] ++: Use fenced code blocks and Markdown render hooks to include diagrams in your content. ++ ++[Mathematics] ++: Include mathematical equations and expressions in Markdown using LaTeX or TeX typesetting syntax. ++ ++[Syntax highlighting] ++: Syntactically highlight code examples using Hugo's embedded syntax highlighter, enabled by default for fenced code blocks in Markdown. The syntax highlighter supports hundreds of code languages and dozens of styles. ++ ++[Shortcodes] ++: Use Hugo's embedded shortcodes, or create your own, to insert complex content. For example, use shortcodes to include `audio` and `video` elements, render tables from local or remote data sources, insert snippets from other pages, and more. ++ ++## Content management ++ ++[Content adapters] ++: Create content adapters to dynamically add content when building your site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML. ++ ++[Taxonomies] ++: Classify content to establish simple or complex logical relationships between pages. For example, create an authors taxonomy, and assign one or more authors to each page. Among other uses, the taxonomy system provides an inverted, weighted index to render a list of related pages, ordered by relevance. ++ ++[Data] ++: Augment your content using local or remote data sources including CSV, JSON, TOML, YAML, and XML. For example, create a shortcode to render an HTML table from a remote CSV file. ++ ++[Menus] ++: Provide rapid access to content via Hugo's menu system, configured automatically, globally, or on a page-by-page basis. The menu system is a key component of Hugo's multilingual architecture. ++ ++[URL management] ++: Serve any page from any path via global configuration or on a page-by-page basis. ++ ++ ++## Asset pipelines ++ ++[CSS bundling] ++: Transpile Sass to CSS, bundle, tree shake, minify, create source maps, perform SRI hashing, and integrate with PostCSS. ++ ++[JavaScript bundling] ++: Transpile TypeScript and JSX to JavaScript, bundle, tree shake, minify, create source maps, and perform SRI hashing. ++ ++[Image processing] ++: Convert, resize, crop, rotate, adjust colors, apply filters, overlay text and images, and extract EXIF data. ++ ++## Performance ++ ++[Caching] ++: Reduce build time and cost by rendering a partial template once then cache the result, either globally or within a given context. For example, cache the result of an asset pipeline to prevent reprocessing on every rendered page. ++ ++[Segmentation] ++: Reduce build time and cost by partitioning your sites into segments. For example, render the home page and the "news section" every hour, and render the entire site once a week. ++ ++[Minification] ++: Minify HTML, CSS, and JavaScript to reduce file size, bandwidth consumption, and loading times. ++ ++[CCPA]: https://en.wikipedia.org/wiki/California_Consumer_Privacy_Act ++[CSS bundling]: /functions/resources/tocss/ ++[Caching]: /functions/partials/includecached/ ++[CommonMark]: https://spec.commonmark.org/current/ ++[Content adapters]: /content-management/content-adapters/ ++[Content formats]: /content-management/formats/ ++[Data]: /content-management/data-sources/ ++[Diagrams]: /content-management/diagrams/ ++[GDPR]: https://en.wikipedia.org/wiki/General_Data_Protection_Regulation ++[GitHub Flavored Markdown]: https://github.github.com/gfm/ ++[Image processing]: /content-management/image-processing/ ++[JavaScript bundling]: /functions/js/build/ ++[Markdown attributes]: /content-management/markdown-attributes/ ++[Markdown extensions]: /getting-started/configuration-markup/#goldmark-extensions ++[Markdown render hooks]: /render-hooks/introduction/ ++[Mathematics]: /content-management/mathematics/ ++[Menus]: /content-management/menus/ ++[Minification]: /getting-started/configuration/#configure-minify ++[Modules]: https://gohugo.io/hugo-modules/ ++[Multilingual]: /content-management/multilingual/ ++[Multiplatform]: /installation/ ++[Output formats]: /templates/output-formats/ ++[Privacy]: /about/privacy/ ++[Security]: /about/security/ ++[Segmentation]: /getting-started/configuration/#configure-segments +[Shortcodes]: /content-management/shortcodes/ - [sort content]: /templates/ - [supported formats]: /content-management/formats/ +[Syntax highlighting]: /content-management/syntax-highlighting/ - [table of contents]: /content-management/toc/ - [taxonomies]: /content-management/taxonomies/ - [URLs]: /content-management/urls/ ++[Taxonomies]: /content-management/taxonomies/ ++[Templates]: templates/introduction/ ++[Themes]: https://themes.gohugo.io/ ++[URL management]: /content-management/urls/ diff --cc docs/content/en/about/introduction.md index 000000000,000000000..d89938eed new file mode 100644 --- /dev/null +++ b/docs/content/en/about/introduction.md @@@ -1,0 -1,0 +1,39 @@@ ++--- ++title: Introduction ++description: Hugo is a static site generator written in Go, optimized for speed and designed for flexibility. ++categories: [about] ++keywords: [] ++menu: ++ docs: ++ identifier: about-introduction ++ parent: about ++ weight: 20 ++weight: 20 ++aliases: [/about/what-is-hugo/,/about/benefits/] ++--- ++ ++Hugo is a [static site generator] written in [Go], optimized for speed and designed for flexibility. With its advanced templating system and fast asset pipelines, Hugo renders a complete site in seconds, often less. ++ ++Due to its flexible framework, multilingual support, and powerful taxonomy system, Hugo is widely used to create: ++ ++- Corporate, government, nonprofit, education, news, event, and project sites ++- Documentation sites ++- Image portfolios ++- Landing pages ++- Business, professional, and personal blogs ++- Resumes and CVs ++ ++Use Hugo's embedded web server during development to instantly see changes to content, structure, behavior, and presentation. Then deploy the site to your host, or push changes to your Git provider for automated builds and deployment. ++ ++And with [Hugo Modules], you can share content, assets, data, translations, themes, templates, and configuration with other projects via public or private Git repositories. ++ ++Learn more about Hugo's [features], [privacy protections], and [security model]. ++ ++[Go]: https://go.dev ++[Hugo Modules]: /hugo-modules/ ++[static site generator]: https://en.wikipedia.org/wiki/Static_site_generator ++[features]: /about/features ++[security model]: /about/security ++[privacy protections]: /about/privacy ++ ++{{< youtube 0RKpf3rK57I >}} diff --cc docs/content/en/about/license.md index e488bb87a,000000000..f434b233e mode 100644,000000..100644 --- a/docs/content/en/about/license.md +++ b/docs/content/en/about/license.md @@@ -1,80 -1,0 +1,80 @@@ +--- +title: License +description: Hugo is released under the Apache 2.0 license. +categories: [about] - keywords: [license,apache] ++keywords: [apache] +menu: + docs: + parent: about - weight: 70 - weight: 70 ++ weight: 60 ++weight: 60 +--- + +## Apache License + + +_Version 2.0, January 2004_ +__ + +### 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. diff --cc docs/content/en/about/privacy.md index 000000000,000000000..dcc3b3439 new file mode 100644 --- /dev/null +++ b/docs/content/en/about/privacy.md @@@ -1,0 -1,0 +1,122 @@@ ++--- ++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. diff --cc docs/content/en/about/security.md index 000000000,000000000..29f2c7ed1 new file mode 100644 --- /dev/null +++ b/docs/content/en/about/security.md @@@ -1,0 -1,0 +1,72 @@@ ++--- ++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: ++ ++ ++ ++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. diff --cc docs/content/en/commands/hugo.md index cbc1ea0ec,000000000..cfbe66053 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo.md +++ b/docs/content/en/commands/hugo.md @@@ -1,85 -1,0 +1,85 @@@ +--- +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) - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --templateMetrics display metrics about template executions + --templateMetricsHints calculate some improvement hints when combined with --templateMetrics + -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 + diff --cc docs/content/en/commands/hugo_completion.md index a09b03985,000000000..21635e81e mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_completion.md +++ b/docs/content/en/commands/hugo_completion.md @@@ -1,47 -1,0 +1,47 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### 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 + diff --cc docs/content/en/commands/hugo_completion_bash.md index 802fcf0a4,000000000..bface97c6 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_completion_bash.md +++ b/docs/content/en/commands/hugo_completion_bash.md @@@ -1,66 -1,0 +1,66 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell + diff --cc docs/content/en/commands/hugo_completion_fish.md index ce0020e86,000000000..3a9cf0df2 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_completion_fish.md +++ b/docs/content/en/commands/hugo_completion_fish.md @@@ -1,57 -1,0 +1,57 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell + diff --cc docs/content/en/commands/hugo_completion_powershell.md index 80dd231f1,000000000..593573cee mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_completion_powershell.md +++ b/docs/content/en/commands/hugo_completion_powershell.md @@@ -1,54 -1,0 +1,54 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell + diff --cc docs/content/en/commands/hugo_completion_zsh.md index 04d304421,000000000..c227c6125 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_completion_zsh.md +++ b/docs/content/en/commands/hugo_completion_zsh.md @@@ -1,68 -1,0 +1,68 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell + diff --cc docs/content/en/commands/hugo_config.md index 873b7179b,000000000..fac513dce mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_config.md +++ b/docs/content/en/commands/hugo_config.md @@@ -1,53 -1,0 +1,53 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo](/commands/hugo/) - hugo builds your site +* [hugo config mounts](/commands/hugo_config_mounts/) - Print the configured file mounts + diff --cc docs/content/en/commands/hugo_config_mounts.md index 4e430c4e7,000000000..42c8b29aa mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_config_mounts.md +++ b/docs/content/en/commands/hugo_config_mounts.md @@@ -1,46 -1,0 +1,46 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo config](/commands/hugo_config/) - Print the site configuration + diff --cc docs/content/en/commands/hugo_convert.md index 39761f7d1,000000000..7b18ee6f8 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_convert.md +++ b/docs/content/en/commands/hugo_convert.md @@@ -1,48 -1,0 +1,48 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### 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 + diff --cc docs/content/en/commands/hugo_convert_toJSON.md index 8756c20a6,000000000..1dfb33aa0 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_convert_toJSON.md +++ b/docs/content/en/commands/hugo_convert_toJSON.md @@@ -1,48 -1,0 +1,48 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + --unsafe enable less safe operations, please backup first + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats + diff --cc docs/content/en/commands/hugo_convert_toTOML.md index e360233a4,000000000..ddd6b8270 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_convert_toTOML.md +++ b/docs/content/en/commands/hugo_convert_toTOML.md @@@ -1,48 -1,0 +1,48 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + --unsafe enable less safe operations, please backup first + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats + diff --cc docs/content/en/commands/hugo_convert_toYAML.md index c6bec1e8d,000000000..bddbb88a5 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_convert_toYAML.md +++ b/docs/content/en/commands/hugo_convert_toYAML.md @@@ -1,48 -1,0 +1,48 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + --unsafe enable less safe operations, please backup first + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats + diff --cc docs/content/en/commands/hugo_deploy.md index 37610441d,000000000..a606083fc mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_deploy.md +++ b/docs/content/en/commands/hugo_deploy.md @@@ -1,56 -1,0 +1,56 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo](/commands/hugo/) - hugo builds your site + diff --cc docs/content/en/commands/hugo_env.md index 947a4325c,000000000..9b73cea5f mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_env.md +++ b/docs/content/en/commands/hugo_env.md @@@ -1,45 -1,0 +1,45 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo](/commands/hugo/) - hugo builds your site + diff --cc docs/content/en/commands/hugo_gen.md index d350638da,000000000..ea1696db9 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_gen.md +++ b/docs/content/en/commands/hugo_gen.md @@@ -1,40 -1,0 +1,40 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### 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 + diff --cc docs/content/en/commands/hugo_gen_chromastyles.md index 6ecb00bd0,000000000..cc244878c mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_gen_chromastyles.md +++ b/docs/content/en/commands/hugo_gen_chromastyles.md @@@ -1,51 -1,0 +1,51 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators. + diff --cc docs/content/en/commands/hugo_gen_doc.md index f2d733112,000000000..84493ab98 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_gen_doc.md +++ b/docs/content/en/commands/hugo_gen_doc.md @@@ -1,51 -1,0 +1,51 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators. + diff --cc docs/content/en/commands/hugo_gen_man.md index f1e355c6c,000000000..40267def2 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_gen_man.md +++ b/docs/content/en/commands/hugo_gen_man.md @@@ -1,48 -1,0 +1,48 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators. + diff --cc docs/content/en/commands/hugo_import.md index db4d19df3,000000000..71af58f8b mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_import.md +++ b/docs/content/en/commands/hugo_import.md @@@ -1,44 -1,0 +1,44 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo](/commands/hugo/) - hugo builds your site +* [hugo import jekyll](/commands/hugo_import_jekyll/) - hugo import from Jekyll + diff --cc docs/content/en/commands/hugo_import_jekyll.md index 11f87ab12,000000000..729413671 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_import_jekyll.md +++ b/docs/content/en/commands/hugo_import_jekyll.md @@@ -1,48 -1,0 +1,48 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo import](/commands/hugo_import/) - Import your site from others. + diff --cc docs/content/en/commands/hugo_list.md index 24b75678a,000000000..9fab42ca9 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_list.md +++ b/docs/content/en/commands/hugo_list.md @@@ -1,47 -1,0 +1,48 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo](/commands/hugo/) - hugo builds your site - * [hugo list all](/commands/hugo_list_all/) - List all posts - * [hugo list drafts](/commands/hugo_list_drafts/) - List all drafts - * [hugo list expired](/commands/hugo_list_expired/) - List all posts already expired - * [hugo list future](/commands/hugo_list_future/) - List all posts dated in the future ++* [hugo list all](/commands/hugo_list_all/) - List all content ++* [hugo list drafts](/commands/hugo_list_drafts/) - List draft content ++* [hugo list expired](/commands/hugo_list_expired/) - List expired content ++* [hugo list future](/commands/hugo_list_future/) - List future content ++* [hugo list published](/commands/hugo_list_published/) - List published content + diff --cc docs/content/en/commands/hugo_list_all.md index 50f6bfe73,000000000..d8dc10c9e mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_list_all.md +++ b/docs/content/en/commands/hugo_list_all.md @@@ -1,45 -1,0 +1,45 @@@ +--- +title: "hugo list all" +slug: hugo_list_all +url: /commands/hugo_list_all/ +--- +## hugo list all + - List all posts ++List all content + +### Synopsis + - List all of the posts in your content directory, include drafts, future and expired pages. ++List all content including draft, future, and expired. + +``` +hugo list all [flags] [args] +``` + +### 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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo list](/commands/hugo_list/) - Listing out various types of content + diff --cc docs/content/en/commands/hugo_list_drafts.md index 5ab308a76,000000000..f1015bbb5 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_list_drafts.md +++ b/docs/content/en/commands/hugo_list_drafts.md @@@ -1,45 -1,0 +1,45 @@@ +--- +title: "hugo list drafts" +slug: hugo_list_drafts +url: /commands/hugo_list_drafts/ +--- +## hugo list drafts + - List all drafts ++List draft content + +### Synopsis + - List all of the drafts in your content directory. ++List draft content. + +``` +hugo list drafts [flags] [args] +``` + +### 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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo list](/commands/hugo_list/) - Listing out various types of content + diff --cc docs/content/en/commands/hugo_list_expired.md index 19aaf667d,000000000..35f6636e1 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_list_expired.md +++ b/docs/content/en/commands/hugo_list_expired.md @@@ -1,45 -1,0 +1,45 @@@ +--- +title: "hugo list expired" +slug: hugo_list_expired +url: /commands/hugo_list_expired/ +--- +## hugo list expired + - List all posts already expired ++List expired content + +### Synopsis + - List all of the posts in your content directory which has already expired. ++List content with a past expiration date. + +``` +hugo list expired [flags] [args] +``` + +### 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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo list](/commands/hugo_list/) - Listing out various types of content + diff --cc docs/content/en/commands/hugo_list_future.md index 3a3e11cc5,000000000..bef162441 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_list_future.md +++ b/docs/content/en/commands/hugo_list_future.md @@@ -1,45 -1,0 +1,45 @@@ +--- +title: "hugo list future" +slug: hugo_list_future +url: /commands/hugo_list_future/ +--- +## hugo list future + - List all posts dated in the future ++List future content + +### Synopsis + - List all of the posts in your content directory which will be posted in the future. ++List content with a future publication date. + +``` +hugo list future [flags] [args] +``` + +### 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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo list](/commands/hugo_list/) - Listing out various types of content + diff --cc docs/content/en/commands/hugo_list_published.md index 000000000,000000000..d53f6d941 new file mode 100644 --- /dev/null +++ b/docs/content/en/commands/hugo_list_published.md @@@ -1,0 -1,0 +1,45 @@@ ++--- ++title: "hugo list published" ++slug: hugo_list_published ++url: /commands/hugo_list_published/ ++--- ++## hugo list published ++ ++List published content ++ ++### Synopsis ++ ++List content that is not draft, future, or expired. ++ ++``` ++hugo list published [flags] [args] ++``` ++ ++### Options ++ ++``` ++ -h, --help help for published ++``` ++ ++### Options inherited from parent commands ++ ++``` ++ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 ++ --config string config file (default is hugo.yaml|json|toml) ++ --configDir string config dir (default "config") ++ --debug debug output ++ -d, --destination string filesystem path to write files to ++ -e, --environment string build environment ++ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern ++ --logLevel string log level (debug|info|warn|error) ++ --quiet build in quiet mode ++ -M, --renderToMemory render to memory (mostly useful when running the server) ++ -s, --source string filesystem path to read files relative from ++ --themesDir string filesystem path to themes directory ++ -v, --verbose verbose output ++``` ++ ++### SEE ALSO ++ ++* [hugo list](/commands/hugo_list/) - Listing out various types of content ++ diff --cc docs/content/en/commands/hugo_mod.md index c3f1230b3,000000000..7fe9dc18d mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_mod.md +++ b/docs/content/en/commands/hugo_mod.md @@@ -1,60 -1,0 +1,60 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### 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. + diff --cc docs/content/en/commands/hugo_mod_clean.md index 459269b66,000000000..e7d933da7 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_mod_clean.md +++ b/docs/content/en/commands/hugo_mod_clean.md @@@ -1,52 -1,0 +1,52 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers. + diff --cc docs/content/en/commands/hugo_mod_get.md index 84177da18,000000000..0b8a622f6 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_mod_get.md +++ b/docs/content/en/commands/hugo_mod_get.md @@@ -1,76 -1,0 +1,76 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers. + diff --cc docs/content/en/commands/hugo_mod_graph.md index 50b8168df,000000000..506bff278 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_mod_graph.md +++ b/docs/content/en/commands/hugo_mod_graph.md @@@ -1,53 -1,0 +1,53 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers. + diff --cc docs/content/en/commands/hugo_mod_init.md index ead95c9af,000000000..dcea44b4b mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_mod_init.md +++ b/docs/content/en/commands/hugo_mod_init.md @@@ -1,57 -1,0 +1,57 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers. + diff --cc docs/content/en/commands/hugo_mod_npm.md index ea80b42e6,000000000..763b3c247 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_mod_npm.md +++ b/docs/content/en/commands/hugo_mod_npm.md @@@ -1,46 -1,0 +1,46 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### 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. + diff --cc docs/content/en/commands/hugo_mod_npm_pack.md index fbc81606c,000000000..47d3e28b9 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_mod_npm_pack.md +++ b/docs/content/en/commands/hugo_mod_npm_pack.md @@@ -1,60 -1,0 +1,60 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo mod npm](/commands/hugo_mod_npm/) - Various npm helpers. + diff --cc docs/content/en/commands/hugo_mod_tidy.md index f2df47565,000000000..6d024564f mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_mod_tidy.md +++ b/docs/content/en/commands/hugo_mod_tidy.md @@@ -1,46 -1,0 +1,46 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers. + diff --cc docs/content/en/commands/hugo_mod_vendor.md index 49aaf3f2f,000000000..6f96caec2 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_mod_vendor.md +++ b/docs/content/en/commands/hugo_mod_vendor.md @@@ -1,52 -1,0 +1,52 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers. + diff --cc docs/content/en/commands/hugo_mod_verify.md index d67d9b0bf,000000000..d3f639fea mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_mod_verify.md +++ b/docs/content/en/commands/hugo_mod_verify.md @@@ -1,51 -1,0 +1,51 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers. + diff --cc docs/content/en/commands/hugo_new.md index ac3a58154,000000000..2146f85fc mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_new.md +++ b/docs/content/en/commands/hugo_new.md @@@ -1,51 -1,0 +1,51 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### 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) + diff --cc docs/content/en/commands/hugo_new_content.md index e50f341f7,000000000..f0ea64ab7 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_new_content.md +++ b/docs/content/en/commands/hugo_new_content.md @@@ -1,60 -1,0 +1,60 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo new](/commands/hugo_new/) - Create new content for your site + diff --cc docs/content/en/commands/hugo_new_site.md index 2c4e12a02,000000000..a79e6f85a mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_new_site.md +++ b/docs/content/en/commands/hugo_new_site.md @@@ -1,49 -1,0 +1,49 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo new](/commands/hugo_new/) - Create new content for your site + diff --cc docs/content/en/commands/hugo_new_theme.md index 0526fed3f,000000000..c3003200d mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_new_theme.md +++ b/docs/content/en/commands/hugo_new_theme.md @@@ -1,48 -1,0 +1,48 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo new](/commands/hugo_new/) - Create new content for your site + diff --cc docs/content/en/commands/hugo_server.md index 1159e4706,000000000..dada8c43e mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_server.md +++ b/docs/content/en/commands/hugo_server.md @@@ -1,99 -1,0 +1,99 @@@ +--- +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.) - --navigateToChanged navigate to changed content file on live browser reload ++ -N, --navigateToChanged navigate to changed content file on live browser reload + --noBuildLock don't create .hugo_build.lock file + --noChmod don't sync permission mode of files + --noHTTPCache prevent HTTP caching + --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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### 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. + diff --cc docs/content/en/commands/hugo_server_trust.md index 2f2f30abb,000000000..c4cf750fa mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_server_trust.md +++ b/docs/content/en/commands/hugo_server_trust.md @@@ -1,42 -1,0 +1,42 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo server](/commands/hugo_server/) - A high performance webserver + diff --cc docs/content/en/commands/hugo_version.md index 35015dd4e,000000000..471edd2bb mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_version.md +++ b/docs/content/en/commands/hugo_version.md @@@ -1,45 -1,0 +1,45 @@@ +--- +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 - --renderToMemory render to memory (mostly useful when running the server) ++ -M, --renderToMemory render to memory (mostly useful when running the server) + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output +``` + +### SEE ALSO + +* [hugo](/commands/hugo/) - hugo builds your site + diff --cc docs/content/en/content-management/_common/_index.md index 47d5812fb,000000000..4328d4d14 mode 100644,000000..100644 --- a/docs/content/en/content-management/_common/_index.md +++ b/docs/content/en/content-management/_common/_index.md @@@ -1,13 -1,0 +1,13 @@@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + + diff --cc docs/content/en/content-management/_index.md index 66af24681,000000000..8fb0cf25e mode 100644,000000..100644 --- a/docs/content/en/content-management/_index.md +++ b/docs/content/en/content-management/_index.md @@@ -1,16 -1,0 +1,16 @@@ +--- +title: Content management - linkTitle: Overview ++linkTitle: In this section +description: Hugo makes managing large static sites easy with support for archetypes, content types, menus, cross references, summaries, and more. +categories: [] +keywords: [] +menu: + docs: - identifier: content-management-overview ++ identifier: content-management-in-this-section + parent: content-management + weight: 10 +weight: 10 +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. diff --cc docs/content/en/content-management/archetypes.md index 94f038848,000000000..f89c3f6b3 mode 100644,000000..100644 --- a/docs/content/en/content-management/archetypes.md +++ b/docs/content/en/content-management/archetypes.md @@@ -1,184 -1,0 +1,203 @@@ +--- +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 + - A content file consists of [front matter] and markup. The markup is typically markdown, but Hugo also supports other [content formats]. Front matter can be TOML, YAML, or JSON. ++A content file consists of [front matter] and markup. The markup is typically Markdown, but Hugo also supports other [content formats]. Front matter can be TOML, YAML, or JSON. + +The `hugo new content` command creates a new file in the `content` directory, using an archetype as a template. This is the default archetype: + +{{< 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. + - Archetypes receive the following objects and values in [context]: ++Archetypes receive the following [context]: + - - `.Date` - - `.Type` - - `.Site` (see [details](/variables/site/)) - - `.File` (see [details](/variables/file/)) ++Date ++: (`string`) The current date and time, formatted in compliance with RFC3339. + - As shown above, the default archetype passes `.File.ContentBaseName` as the argument to the `replace` function when populating the title in front matter. ++File ++: (`hugolib.fileInfo`) Returns file information for the current page. See [details](/methods/page/file). ++ ++Type ++: (`string`) The [content type] inferred from the top-level directory name, or as specified by the `--kind` flag passed to the `hugo new content` command. ++ ++[content type]: /getting-started/glossary#content-type ++ ++Site ++: (`page.Site`) The current site object. See [details](/methods/site/). ++ ++## Alternate date format ++ ++To insert date and time with an alternate format, use the [`time.Now`] function: ++ ++[`time.Now`]: /functions/time/now/ ++ ++{{< code-toggle file=archetypes/default.md fm=true >}} ++title = '{{ replace .File.ContentBaseName `-` ` ` | title }}' ++date = '{{ time.Now.Format "2006-01-02" }}' ++draft = true ++{{< /code-toggle >}} + +## Include content + +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 diff --cc docs/content/en/content-management/build-options.md index e8b3354bf,000000000..a279fb651 mode 100644,000000..100644 --- a/docs/content/en/content-management/build-options.md +++ b/docs/content/en/content-management/build-options.md @@@ -1,321 -1,0 +1,321 @@@ +--- +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 options are stored in a reserved front matter object named `_build` with these defaults: ++Build options are stored in a reserved front matter object named `build` with these defaults: + +{{< code-toggle file=content/example/index.md fm=true >}} - [_build] ++[build] +list = 'always' +publishResources = true +render = 'always' +{{< /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 bundles]: content-management/page-bundles - [page resources]: /content-management/page-resources - [`Permalink`]: /methods/resource/permalink - [`RelPermalink`]: /methods/resource/relpermalink - [`Publish`]: /methods/resource/publish ++[page bundles]: /content-management/page-bundles/ ++[page resources]: /content-management/page-resources/ ++[`Permalink`]: /methods/resource/permalink/ ++[`RelPermalink`]: /methods/resource/relpermalink/ ++[`Publish`]: /methods/resource/publish/ + +{{% note %}} +Any page, regardless of its build options, will always be available by using the [`.Page.GetPage`] or [`.Site.GetPage`] method. + - [`.Page.GetPage`]: /methods/page/getpage - [`.Site.GetPage`]: /methods/site/getpage ++[`.Page.GetPage`]: /methods/page/getpage/ ++[`.Site.GetPage`]: /methods/site/getpage/ +{{% /note %}} + +## Example -- headless page + +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' - [_build] ++[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" }} + + {{ 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. + - [branch bundle]: /content-management/page-bundles ++[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]] - [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" }} + + {{ 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' - [_build] ++[build] +render = 'always' +[[cascade]] - [cascade._build] ++[cascade.build] + list = 'local' + publishResources = false + render = 'never' +{{< /code-toggle >}} + +To render the glossary: + +{{< code file=layouts/glossary/list.html >}} +
+ {{ range .Pages }} +
{{ .Title }}
+
{{ .Content }}
+ {{ end }} +
+{{< /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' - [_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] ++[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 +``` diff --cc docs/content/en/content-management/comments.md index 6e58b36e4,000000000..8f55c413c mode 100644,000000..100644 --- a/docs/content/en/content-management/comments.md +++ b/docs/content/en/content-management/comments.md @@@ -1,74 -1,0 +1,78 @@@ +--- +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' +{{}} + +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 + - Disqus has its own [internal template](/templates/internal/#disqus) available, to render it add the following code where you want comments to appear: ++Disqus has its own [internal template](/templates/embedded/#disqus) available, to render it add the following code where you want comments to appear: + +```go-html-template +{{ template "_internal/disqus.html" . }} +``` + +## Alternatives + - These are some alternatives to Disqus: - - * [Cactus Comments](https://cactus.chat/docs/integrations/hugo/) (Open Source, Matrix appservice, Docker install) - * [Comentario](https://gitlab.com/comentario/comentario) (Open Source, self-hosted, Go/Angular, run locally, in Docker or Kubernetes) - * [Commento](https://commento.io/) (Open Source, available as a service, local install, or docker image) - * [Giscus](https://giscus.app/) (Open source, comments system powered by GitHub Discussions) - * [Graph Comment](https://graphcomment.com/) - * [Hyvor Talk](https://talk.hyvor.com/) (Available as a service) - * [IntenseDebate](https://intensedebate.com/) - * [Isso](https://isso-comments.de/) (Self-hosted, Python) ([tutorial][issotutorial]) - * [Muut](https://muut.com/) - * [Remark42](https://remark42.com/) (Open source, Golang, Easy to run docker) - * [ReplyBox](https://getreplybox.com/) - * [Staticman](https://staticman.net/) - * [Talkyard](https://blog-comments.talkyard.io/) (Open source, & serverless hosting) - * [Utterances](https://utteranc.es/) (Open source, GitHub comments widget built on GitHub issues) ++Commercial commenting systems: ++ ++- [Emote](https://emote.com/) ++- [Graph Comment](https://graphcomment.com/) ++- [Hyvor Talk](https://talk.hyvor.com/) ++- [IntenseDebate](https://intensedebate.com/) ++- [ReplyBox](https://getreplybox.com/) ++ ++Open-source commenting systems: ++ ++- [Cactus Comments](https://cactus.chat/docs/integrations/hugo/) ++- [Comentario](https://gitlab.com/comentario/comentario/) ++- [Comma](https://github.com/Dieterbe/comma/) ++- [Commento](https://commento.io/) ++- [Discourse](https://meta.discourse.org/t/embed-discourse-comments-on-another-website-via-javascript/31963) ++- [Giscus](https://giscus.app/) ++- [Isso](https://isso-comments.de/) ++- [Remark42](https://remark42.com/) ++- [Staticman](https://staticman.net/) ++- [Talkyard](https://blog-comments.talkyard.io/) ++- [Utterances](https://utteranc.es/) + +[configuration]: /getting-started/configuration/ - [disquspartial]: /templates/internal/#disqus ++[disquspartial]: /templates/embedded/#disqus +[disqussetup]: https://disqus.com/profile/signup/ +[forum]: https://discourse.gohugo.io +[front matter]: /content-management/front-matter/ +[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/ - [tweet]: https://twitter.com/spf13 diff --cc docs/content/en/content-management/content-adapters.md index 000000000,000000000..11257b895 new file mode 100644 --- /dev/null +++ b/docs/content/en/content-management/content-adapters.md @@@ -1,0 -1,0 +1,355 @@@ ++--- ++title: Content adapters ++description: Create content adapters to dynamically add content when building your site. ++categories: [content management] ++keywords: [] ++menu: ++ docs: ++ parent: content-management ++ weight: 290 ++weight: 290 ++toc: true ++--- ++ ++{{< new-in 0.126.0 >}} ++ ++## Overview ++ ++A content adapter is a template that dynamically creates pages when building a site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML. ++ ++Unlike templates that reside in the layouts directory, content adapters reside in the content directory, no more than one per directory per language. When a content adapter creates a page, the page's [logical path] will be relative to the content adapter. ++ ++```text ++content/ ++├── articles/ ++│ ├── _index.md ++│ ├── article-1.md ++│ └── article-2.md ++├── books/ ++│ ├── _content.gotmpl <-- content adapter ++│ └── _index.md ++└── films/ ++ ├── _content.gotmpl <-- content adapter ++ └── _index.md ++``` ++ ++Each content adapter is named _content.gotmpl and uses the same [syntax] as templates in the layouts directory. You can use any of the [template functions] within a content adapter, as well as the methods described below. ++ ++## Methods ++ ++Use these methods within a content adapter. ++ ++###### AddPage ++ ++Adds a page to the site. ++ ++{{< code file=content/books/_content.gotmpl >}} ++{{ $content := dict ++ "mediaType" "text/markdown" ++ "value" "The _Hunchback of Notre Dame_ was written by Victor Hugo." ++}} ++{{ $page := dict ++ "content" $content ++ "kind" "page" ++ "path" "the-hunchback-of-notre-dame" ++ "title" "The Hunchback of Notre Dame" ++}} ++{{ .AddPage $page }} ++{{< /code >}} ++ ++###### AddResource ++ ++Adds a page resource to the site. ++ ++{{< code file=content/books/_content.gotmpl >}} ++{{ with resources.Get "images/a.jpg" }} ++ {{ $content := dict ++ "mediaType" .MediaType.Type ++ "value" . ++ }} ++ {{ $resource := dict ++ "content" $content ++ "path" "the-hunchback-of-notre-dame/cover.jpg" ++ }} ++ {{ $.AddResource $resource }} ++{{ end }} ++{{< /code >}} ++ ++Then retrieve the new page resource with something like: ++ ++{{< code file=layouts/_default/single.html >}} ++{{ with .Resources.Get "cover.jpg" }} ++ ++{{ end }} ++{{< /code >}} ++ ++###### Site ++ ++Returns the `Site` to which the pages will be added. ++ ++{{< code file=content/books/_content.gotmpl >}} ++{{ .Site.Title }} ++{{< /code >}} ++ ++###### Store ++ ++Returns a persistent “scratch pad” to store and manipulate data. The main use case for this is to transfer values between executions when [EnableAllLanguages](#enablealllanguages) is set. See [examples](/methods/page/store/). ++ ++{{< code file=content/books/_content.gotmpl >}} ++{{ .Store.Set "key" "value" }} ++{{ .Store.Get "key" }} ++{{< /code >}} ++ ++###### EnableAllLanguages ++ ++By default, Hugo executes the content adapter for the language defined by the _content.gotmpl file . Use this method to activate the content adapter for all languages. ++ ++{{< code file=content/books/_content.gotmpl >}} ++{{ .EnableAllLanguages }} ++{{ $content := dict ++ "mediaType" "text/markdown" ++ "value" "The _Hunchback of Notre Dame_ was written by Victor Hugo." ++}} ++{{ $page := dict ++ "content" $content ++ "kind" "page" ++ "path" "the-hunchback-of-notre-dame" ++ "title" "The Hunchback of Notre Dame" ++}} ++{{ .AddPage $page }} ++{{< /code >}} ++ ++## Page map ++ ++Set any [front matter field] in the map passed to the [`AddPage`](#addpage) method, excluding `markup`. Instead of setting the `markup` field, specify the `content.mediaType` as described below. ++ ++This table describes the fields most commonly passed to the `AddPage` method. ++ ++Key|Descripion|Required ++:--|:--|:-: ++`content.mediaType`|The content [media type]. Default is `text/markdown`. See [content formats] for examples.|  ++`content.value`|The content value as a string.|  ++`dates.date`|The page creation date as a `time.Time` value.|  ++`dates.expiryDate`|The page expiry date as a `time.Time` value.|  ++`dates.lastmod`|The page last modification date as a `time.Time` value.|  ++`dates.publishDate`|The page publication date as a `time.Time` value.|  ++`kind`|The [page kind]. Default is `page`.|  ++`params`|A map of page parameters.|  ++`path`|The page's [logical path] relative to the content adapter. Do not include a leading slash or file extension.|:heavy_check_mark: ++`title`|The page title.|  ++ ++{{% note %}} ++While `path` is the only required field, we recommend setting `title` as well. ++ ++When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C` produces a logical path of `/section/a-b-c`. ++{{% /note %}} ++ ++## Resource map ++ ++Construct the map passed to the [`AddResource`](#addresource) method using the fields below. ++ ++Key|Descripion|Required ++:--|:--|:-: ++`content.mediaType`|The content [media type].|:heavy_check_mark: ++`content.value`|The content value as a string or resource.|:heavy_check_mark: ++`name`|The resource name.|  ++`params`|A map of resource parameters.|  ++`path`|The resources's [logical path] relative to the content adapter. Do not include a leading slash.|:heavy_check_mark: ++`title`|The resource title.|  ++ ++{{% note %}} ++If the `content.value` is a string Hugo creates a new resource. If the `content.value` is a resource, Hugo obtains the value from the existing resource. ++ ++When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C/cover.jpg` produces a logical path of `/section/a-b-c/cover.jpg`. ++{{% /note %}} ++ ++## Example ++ ++Create pages from remote data, where each page represents a book review. ++ ++Step 1 ++: Create the content structure. ++ ++```text ++content/ ++└── books/ ++ ├── _content.gotmpl <-- content adapter ++ └── _index.md ++``` ++ ++Step 2 ++: Inspect the remote data to determine how to map key-value pairs to front matter fields. ++ ++: ++ ++Step 3 ++: Create the content adapter. ++ ++{{< code file=content/books/_content.gotmpl copy=true >}} ++{{/* Get remote data. */}} ++{{ $data := dict }} ++{{ $url := "https://gohugo.io/shared/examples/data/books.json" }} ++{{ with resources.GetRemote $url }} ++ {{ with .Err }} ++ {{ errorf "Unable to get remote resource %s: %s" $url . }} ++ {{ else }} ++ {{ $data = . | transform.Unmarshal }} ++ {{ end }} ++{{ else }} ++ {{ errorf "Unable to get remote resource %s" $url }} ++{{ end }} ++ ++{{/* Add pages and page resources. */}} ++{{ range $data }} ++ ++ {{/* Add page. */}} ++ {{ $content := dict "mediaType" "text/markdown" "value" .summary }} ++ {{ $dates := dict "date" (time.AsTime .date) }} ++ {{ $params := dict "author" .author "isbn" .isbn "rating" .rating "tags" .tags }} ++ {{ $page := dict ++ "content" $content ++ "dates" $dates ++ "kind" "page" ++ "params" $params ++ "path" .title ++ "title" .title ++ }} ++ {{ $.AddPage $page }} ++ ++ {{/* Add page resource. */}} ++ {{ $item := . }} ++ {{ with $url := $item.cover }} ++ {{ with resources.GetRemote $url }} ++ {{ with .Err }} ++ {{ errorf "Unable to get remote resource %s: %s" $url . }} ++ {{ else }} ++ {{ $content := dict "mediaType" .MediaType.Type "value" .Content }} ++ {{ $params := dict "alt" $item.title }} ++ {{ $resource := dict ++ "content" $content ++ "params" $params ++ "path" (printf "%s/cover.%s" $item.title .MediaType.SubType) ++ }} ++ {{ $.AddResource $resource }} ++ {{ end }} ++ {{ else }} ++ {{ errorf "Unable to get remote resource %s" $url }} ++ {{ end }} ++ {{ end }} ++ ++{{ end }} ++{{< /code >}} ++ ++Step 4 ++: Create a single page template to render each book review. ++ ++{{< code file=layouts/books/single.html copy=true >}} ++{{ define "main" }} ++

{{ .Title }}

++ ++ {{ with .Resources.GetMatch "cover.*" }} ++ {{ .Params.alt }} ++ {{ end }} ++ ++

Author: {{ .Params.author }}

++ ++

++ ISBN: {{ .Params.isbn }}
++ Rating: {{ .Params.rating }}
++ Review date: {{ .Date | time.Format ":date_long" }} ++

++ ++ {{ with .GetTerms "tags" }} ++

Tags:

++ ++ {{ end }} ++ ++ {{ .Content }} ++{{ end }} ++{{< /code >}} ++ ++## Multilingual sites ++ ++With multilingual sites you can: ++ ++1. Create one content adapter for all languages using the [`EnableAllLanguages`](#enablealllanguages) method as described above. ++2. Create content adapters unique to each language. See the examples below. ++ ++### Translations by file name ++ ++With this site configuration: ++ ++{{< code-toggle file=hugo >}} ++[languages.en] ++weight = 1 ++ ++[languages.de] ++weight = 2 ++{{< /code-toggle >}} ++ ++Include a language designator in the content adapter's file name. ++ ++```text ++content/ ++└── books/ ++ ├── _content.de.gotmpl ++ ├── _content.en.gotmpl ++ ├── _index.de.md ++ └── _index.en.md ++``` ++ ++### Translations by content directory ++ ++With this site configuration: ++ ++{{< code-toggle file=hugo >}} ++[languages.en] ++contentDir = 'content/en' ++weight = 1 ++ ++[languages.de] ++contentDir = 'content/de' ++weight = 2 ++{{< /code-toggle >}} ++ ++Create a single content adapter in each directory: ++ ++```text ++content/ ++├── de/ ++│ └── books/ ++│ ├── _content.gotmpl ++│ └── _index.md ++└── en/ ++ └── books/ ++ ├── _content.gotmpl ++ └── _index.md ++``` ++ ++## Page collisions ++ ++Two or more pages collide when they have the same publication path. Due to concurrency, the content of the published page is indeterminate. Consider this example: ++ ++```text ++content/ ++└── books/ ++ ├── _content.gotmpl <-- content adapter ++ ├── _index.md ++ └── the-hunchback-of-notre-dame.md ++``` ++ ++If the content adapter also creates books/the-hunchback-of-notre-dame, the content of the published page is indeterminate. You can not define the processing order. ++ ++To detect page collisions, use the `--printPathWarnings` flag when building your site. ++ ++[content formats]: /content-management/formats/#classification ++[front matter field]: /content-management/front-matter/#fields ++[logical path]: /getting-started/glossary/#logical-path ++[media type]: https://en.wikipedia.org/wiki/Media_type ++[page kind]: /getting-started/glossary/#page-kind ++[syntax]: /templates/introduction/ ++[template functions]: /functions/ diff --cc docs/content/en/content-management/cross-references.md index 500e388a4,000000000..24da0bfda mode 100644,000000..100644 --- a/docs/content/en/content-management/cross-references.md +++ b/docs/content/en/content-management/cross-references.md @@@ -1,150 -1,0 +1,152 @@@ +--- +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` + - The `ref` and `relref` shortcodes require a single parameter: the path to a content document, with or without a file extension, with or without an anchor. Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site. ++The `ref` and `relref` shortcodes require a single argument: the path to a content document, with or without a file extension, with or without an anchor. Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site. + +```text +. +└── 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 +{{}} // <- From pages/document1.md, relative path +{{}} +{{}} +{{}} +{{}} // <- From pages/document2.md +{{}} // <- From anywhere, absolute path +{{}} +{{}} +{{}} +{{}} +{{}} +``` + +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 +{{}} // <- References /about/_index.md +{{}} // Raises REF_NOT_FOUND error +{{}} // <- References /about/credits.md + +{{}} // <- References /products/index.md +{{}} // <- References /products/index.md +``` + - To generate a hyperlink using `ref` or `relref` in markdown: ++To generate a hyperlink using `ref` or `relref` in Markdown: + +```text +[About]({{}} "About Us") +``` + +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 +{{}} +``` + +### Get another output format + +To link to another Output Format of a document, use this syntax: + - ```go-html-template ++```text +{{}} +``` + +### Heading IDs + +When using Markdown document types, Hugo generates element IDs for every heading on a page. For example: + - ```md ++```text +## Reference +``` + +produces this HTML: + +```html +

Reference

+``` + +Get the permalink to a heading by appending the ID to the path when using the `ref` or `relref` shortcodes: + - ```go-html-template ++```text +{{}} +{{}} +``` + +Generate a custom heading ID by including an attribute. For example: + - ```md ++```text +## Reference A {#foo} +## Reference B {id="bar"} +``` + +produces this HTML: + +```html +

Reference A

+

Reference B

+``` + +Hugo will generate unique element IDs if the same heading appears more than once on a page. For example: + - ```md ++```text +## Reference +## Reference +## Reference +``` + +produces this HTML: + +```html +

Reference

+

Reference

+

Reference

+``` + +## 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/ diff --cc docs/content/en/content-management/data-sources.md index 000000000,000000000..40634acef new file mode 100644 --- /dev/null +++ b/docs/content/en/content-management/data-sources.md @@@ -1,0 -1,0 +1,126 @@@ ++--- ++title: Data sources ++description: Use local and remote data sources to augment or create content. ++categories: [content management] ++keywords: [data,json,toml,yaml,xml] ++menu: ++ docs: ++ parent: content-management ++ weight: 280 ++weight: 280 ++toc: true ++aliases: [/extras/datafiles/,/extras/datadrivencontent/,/doc/datafiles/,/templates/data-templates/] ++--- ++ ++Hugo can access and [unmarshal] local and remote data sources including CSV, JSON, TOML, YAML, and XML. Use this data to augment existing content or to create new content. ++ ++[unmarshal]: /getting-started/glossary/#unmarshal ++ ++A data source might be a file in the data directory, a [global resource], a [page resource], or a [remote resource]. ++ ++[global resource]: /getting-started/glossary/#global-resource ++[page resource]: /getting-started/glossary/#page-resource ++[remote resource]: /getting-started/glossary/#remote-resource ++ ++## Data directory ++ ++The data directory in the root of your project may contain one or more data files, in either a flat or nested tree. Hugo merges the data files to create a single data structure, accessible with the `Data` method on a `Site` object. ++ ++Hugo also merges data directories from themes and modules into this single data structure, where the data directory in the root of your project takes precedence. ++ ++{{% note %}} ++Hugo reads the combined data structure into memory and keeps it there for the entire build. For data that is infrequently accessed, use global or page resources instead. ++{{% /note %}} ++ ++Theme and module authors may wish to namespace their data files to prevent collisions. For example: ++ ++```text ++project/ ++└── data/ ++ └── mytheme/ ++ └── foo.json ++``` ++ ++{{% note %}} ++Do not place CSV files in the data directory. Access CSV files as page, global, or remote resources. ++{{% /note %}} ++ ++See the documentation for the [`Data`] method on `Page` object for details and examples. ++ ++[`Data`]: /methods/site/data/ ++ ++## Global resources ++ ++Use the `resources.Get` and `transform.Unmarshal` functions to access data files that exist as global resources. ++ ++See the [`transform.Unmarshal`](/functions/transform/unmarshal/#global-resource) documentation for details and examples. ++ ++## Page resources ++ ++Use the `Resources.Get` method on a `Page` object combined with the `transform.Unmarshal` function to access data files that exist as page resources. ++ ++See the [`transform.Unmarshal`](/functions/transform/unmarshal/#page-resource) documentation for details and examples. ++ ++## Remote resources ++ ++Use the `resources.GetRemote` and `transform.Unmarshal` functions to access remote data. ++ ++See the [`transform.Unmarshal`](/functions/transform/unmarshal/#remote-resource) documentation for details and examples. ++ ++## Augment existing content ++ ++Use data sources to augment existing content. For example, create a shortcode to render an HTML table from a global CSV resource. ++ ++{{< code file=assets/pets.csv >}} ++"name","type","breed","age" ++"Spot","dog","Collie","3" ++"Felix","cat","Malicious","7" ++{{< /code >}} ++ ++{{< code file=content/example.md lang=text >}} ++{{}} ++{{< /code >}} ++ ++{{< code file=layouts/shortcodes/csv-to-table.html >}} ++{{ with $file := .Get 0 }} ++ {{ with resources.Get $file }} ++ {{ with . | transform.Unmarshal }} ++ ++ ++ ++ {{ range index . 0 }} ++ ++ {{ end }} ++ ++ ++ ++ {{ range after 1 . }} ++ ++ {{ range . }} ++ ++ {{ end }} ++ ++ {{ end }} ++ ++
{{ . }}
{{ . }}
++ {{ end }} ++ {{ else }} ++ {{ errorf "The %q shortcode was unable to find %s. See %s" $.Name $file $.Position }} ++ {{ end }} ++{{ else }} ++ {{ errorf "The %q shortcode requires one positional argument, the path to the CSV file relative to the assets directory. See %s" .Name .Position }} ++{{ end }} ++{{< /code >}} ++ ++Hugo renders this to: ++ ++name|type|breed|age ++:--|:--|:--|:-- ++Spot|dog|Collie|3 ++Felix|cat|Malicious|7 ++ ++## Create new content ++ ++Use [content adapters] to create new content. ++ ++[content adapters]: /content-management/content-adapters/ diff --cc docs/content/en/content-management/diagrams.md index 17407098f,000000000..8851034c6 mode 100644,000000..100644 --- a/docs/content/en/content-management/diagrams.md +++ b/docs/content/en/content-management/diagrams.md @@@ -1,263 -1,0 +1,267 @@@ +--- +title: Diagrams - description: Use fenced code blocks and markdown render hooks to display diagrams. ++description: Use fenced code blocks and Markdown render hooks to include diagrams in your content. +categories: [content management] +keywords: [diagrams,drawing] +menu: + docs: + parent: content-management - weight: 50 - weight: 50 ++ weight: 260 ++weight: 260 +toc: true +--- - {{< new-in 0.93.0 >}} + +## GoAT diagrams (ASCII) + - Hugo supports [GoAT](https://github.com/bep/goat) natively. This means that this code block: ++Hugo natively supports [GoAT] diagrams with an [embedded code block render hook]. This means that this code block: ++ ++[GoAT]: https://github.com/bep/goat ++[embedded code block render hook]: {{% eturl render-codeblock-goat %}} + +````txt +```goat + . . . .--- 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 + - Hugo currently does not provide default templates for Mermaid diagrams. But you can easily add your own. One way to do it would be to create `layouts/_default/_markup/render-codeblock-mermaid.html`: ++Hugo does not provide a built-in template for Mermaid diagrams. Create your own using a [code block render hook]: + - ```go-html-template ++[code block render hook]: /render-hooks/code-blocks/ ++ ++{{< code file=layouts/_default/_markup/render-codeblock-mermaid.html >}} +
 +  {{- .Inner | safeHTML }}
 +
+{{ .Page.Store.Set "hasMermaid" true }} - ``` ++{{< /code >}} + - And then include this snippet at the bottom of the content template (**Note**: below `.Content` as the render hook is not processed until `.Content` is executed): ++And then include this snippet at the bottom of the content template: + +```go-html-template - {{ if .Page.Store.Get "hasMermaid" }} ++{{ if .Store.Get "hasMermaid" }} + +{{ 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
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 + +```goat { width=300 color="orange" } +───Linux─┬─Android + ├─Debian─┬─Ubuntu─┬─Lubuntu + │ │ ├─Kubuntu + │ │ ├─Xubuntu + │ │ └─Xubuntu + │ └─Mint + ├─Centos + └─Fedora +``` + +### Sequence diagram + + + +```goat { class="w-40" } +┌─────┐ ┌───┐ +│Alice│ │Bob│ +└──┬──┘ └─┬─┘ + │ │ + │ Hello Bob! │ + │───────────>│ + │ │ + │Hello Alice!│ + │<───────────│ +┌──┴──┐ ┌─┴─┐ +│Alice│ │Bob│ +└─────┘ └───┘ + +``` + +### 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 + + + +```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 } """" .│ +└────────────────────────────────────────────────┘ +``` diff --cc docs/content/en/content-management/formats.md index 76c8102b5,000000000..e96bc5af3 mode 100644,000000..100644 --- a/docs/content/en/content-management/formats.md +++ b/docs/content/en/content-management/formats.md @@@ -1,93 -1,0 +1,137 @@@ +--- +title: Content formats - description: Both HTML and Markdown are supported content formats. ++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/] +--- + - 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.: ++## Introduction + - * Markdown converted to HTML - * [Shortcodes](/content-management/shortcodes/) processed - * Layout applied ++You may mix content formats throughout your site. For example: + - ## List of content formats ++```text ++content/ ++└── posts/ ++ ├── post-1.md ++ ├── post-2.adoc ++ ├── post-3.org ++ ├── post-4.pandoc ++ ├── post-5.rst ++ └── post-6.html ++``` + - The current list of content formats in Hugo: ++Regardless of content format, all content must have [front matter], preferably including both `title` and `date`. + - | 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.| ++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. + - 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/). ++## Formats + - ## External helpers ++### Markdown + - 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. ++Create your content in [Markdown] preceded by front matter. + - Hugo passes reasonable default arguments to these external helpers by default: ++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. + - - `asciidoctor`: `--no-header-footer -` - - `rst2html`: `--leave-comments --initial-header-level=2` - - `pandoc`: `--mathjax` ++Hugo provides custom Markdown features including: + - {{% 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 %}} ++[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. + - ### Asciidoctor ++[Extensions] ++: Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more. + - 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. ++[Mathematics] ++: Include mathematical equations and expressions in Markdown using LaTeX or TeX typesetting syntax. + - {{% 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 %}} ++[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. + - Some Asciidoctor parameters can be customized in Hugo. See [details]. ++### HTML + - [details]: /getting-started/configuration-markup/#asciidoc ++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. + - ## Learn markdown ++### Emacs Org Mode + - Markdown syntax is simple enough to learn in a single sitting. The following are excellent resources to get you up and running: ++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)). + - * [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] ++### AsciiDoc + - [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/ ++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 diff --cc docs/content/en/content-management/front-matter.md index 7dee78db2,000000000..2c01f7854 mode 100644,000000..100644 --- a/docs/content/en/content-management/front-matter.md +++ b/docs/content/en/content-management/front-matter.md @@@ -1,241 -1,0 +1,430 @@@ +--- +title: Front matter - description: Hugo allows you to add front matter in yaml, toml, or json to your content files. ++description: Use front matter to add metadata to your content. +categories: [content management] +keywords: [front matter,yaml,toml,json,metadata,archetypes] +menu: + docs: + parent: content-management + weight: 60 +weight: 60 +toc: true +aliases: [/content/front-matter/] +--- + - **Front matter** allows you to keep metadata attached to an instance of a [content type]---i.e., embedded inside a content file---and is one of the many features that gives Hugo its strength. ++## Overview + - {{< youtube Yh2xKRJGff4 >}} ++The front matter at the top of each content file is metadata that: + - ## Front matter formats ++- Describes the content ++- Augments the content ++- Establishes relationships with other content ++- Controls the published structure of your site ++- Determines template selection + - Hugo supports four formats for front matter, each with their own identifying tokens. ++Provide front matter using a serialization format, one of [JSON], [TOML], or [YAML]. Hugo determines the front matter format by examining the delimiters that separate the front matter from the page content. + - TOML - : identified by opening and closing `+++`. ++[json]: https://www.json.org/ ++[toml]: https://toml.io/ ++[yaml]: https://yaml.org/ + - YAML - : identified by opening and closing `---`. ++See examples of front matter delimiters by toggling between the serialization formats below. + - JSON - : a single JSON object surrounded by '`{`' and '`}`', followed by a new line. ++{{< 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 >}} + - 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`). ++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. + - ### Example ++[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 + - {{< 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 >}} ++## Fields + - ## Front matter variables ++The most common front matter fields are `date`, `draft`, `title`, and `weight`, but you can specify metadata using any of fields below. + - ### Predefined ++{{% 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. + - 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. ++[parameters]: #parameters ++{{% /note %}} + - aliases - : An array of one or more aliases (e.g., old published paths of renamed content) that will be created in the output directory structure . See [Aliases][aliases] for details. ++###### aliases + - audio - : An array of paths to audio files related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:audio`. ++(`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. + - 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. ++[`aliases`]: /methods/page/aliases/ ++[aliases]: /content-management/urls/#aliases + - date - : The datetime assigned to this page. This is usually fetched from the `date` field in front matter, but this behavior is configurable. ++###### build + - description - : The description for the content. ++(`map`) A map of [build options]. + - draft - : If `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command. ++[build options]: /content-management/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. ++###### cascade {#cascade-field} + - headless - : If `true`, sets a leaf bundle to be [headless][headless-bundle]. ++(`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. + - images - : An array of paths to images related to the page; used by [internal templates](/templates/internal) such as `_internal/twitter_cards.html`. ++[cascade]: #cascade + - isCJKLanguage - : If `true`, Hugo will explicitly treat the content as a CJK language; both `.Summary` and `.WordCount` work properly in CJK languages. ++###### date + - keywords - : The meta keywords for the content. ++(`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. + - 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]. ++[`date`]: /methods/page/date/ + - lastmod - : The datetime at which the content was last modified. ++###### description + - linkTitle - : Used for creating links to content; if set, Hugo defaults to using the `linkTitle` before the `title`. ++(`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. + - markup - : **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown. ++[`description`]: /methods/page/description/ + - outputs - : Allows you to specify output formats specific to the content. See [output formats][outputs]. ++###### draft + - publishDate - : If in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`. ++(`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. + - resources - : Used for configuring page bundle resources. See [Page Resources][page-resources]. ++[`draft`]: /methods/page/draft/ + - series - : An array of series this page belongs to, as a subset of the `series` [taxonomy](/content-management/taxonomies/); used by the `opengraph` [internal template](/templates/internal) to populate `og:see_also`. ++###### expiryDate + - slug - : Overrides the last segment of the URL path. Not applicable to section pages. See [URL Management](/content-management/urls/#slug) for details. ++(`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. + - 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. ++[`expirydate`]: /methods/page/expirydate/ + - title - : The title for the content. ++###### headless + - 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. ++(`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]. + - url - : Overrides the entire URL path. Applicable to regular pages and section pages. See [URL Management](/content-management/urls/#url) for details. ++[leaf bundles]: /content-management/page-bundles/#leaf-bundles ++[page resources]: /content-management/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`. ++###### isCJKLanguage + - 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. ++(`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. + - {{% 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 %}} ++[`fuzzywordcount`]: /methods/page/wordcount/ ++[`readingtime`]: /methods/page/readingtime/ ++[`summary`]: /methods/page/summary/ ++[`wordcount`]: /methods/page/wordcount/ ++[cjk]: /getting-started/glossary/#cjk + - ### User-defined ++###### keywords + - 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. ++(`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. + - 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. ++[`keywords`]: /methods/page/keywords/ ++[taxonomy]: /getting-started/glossary/#taxonomy + - {{< code-toggle >}} - include_toc: true - show_comments: false - {{}} ++ ++ ++ ++ ++ ++ ++###### lastmod ++ ++(`string`) The date that the page was last modified. Note that the TOML format also supports date/time values using unquoted strings. Access this value from a template using the [`Lastmod`] method on a `Page` object. ++ ++[`lastmod`]: /methods/page/date/ ++ ++###### layout ++ ++(`string`) Provide a template name to [target a specific template], overriding the default [template lookup order]. Set the value to the base file name of the template, excluding its extension. Access this value from a template using the [`Layout`] method on a `Page` object. ++ ++[`layout`]: /methods/page/layout/ ++[template lookup order]: /templates/lookup-order/ ++[target a specific template]: templates/lookup-order/#target-a-template ++ ++###### linkTitle ++ ++(`string`) Typically a shorter version of the `title`. Access this value from a template using the [`LinkTitle`] method on a `Page` object. ++ ++[`linktitle`]: /methods/page/linktitle/ ++ ++###### markup ++ ++(`string`) 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/ ++ ++ ++ ++ ++###### 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 + - ## Front matter cascade ++(`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. + - 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. ++[`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" }} ++

Tags

++ ++{{ 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 + - The `cascade` block can be a slice with a optional `_target` keyword, allowing for multiple `cascade` values targeting different page sets. ++The `cascade` block can be an array with an optional `_target` keyword, allowing you to target different page sets while cascading values. + - {{< code-toggle >}} - title ="Blog" ++{{< code-toggle file=content/_index.md fm=true >}} ++title ="Home" +[[cascade]] ++[cascade.params] +background = "yosemite.jpg" +[cascade._target] - path="/blog/**" ++path="/articles/**" +lang="en" +kind="page" +[[cascade]] ++[cascade.params] +background = "goldenbridge.jpg" +[cascade._target] +kind="section" +{{}} + - Keywords available for `_target`: ++Use any combination of these keywords to target a set of pages: + - path - : A [Glob](https://github.com/gobwas/glob) pattern matching the content path below /content. Expects Unix-styled slashes. Note that this is the virtual path, so it starts at the mount root. The matching supports double-asterisks so you can match for patterns like `/blog/*/**` to match anything from the third level and down. ++###### path {#cascade-path} + - kind - : A Glob pattern matching the Page's Kind(s), e.g. "{home,section}". ++(`string`) A [Glob](https://github.com/gobwas/glob) pattern matching the content path below /content. Expects Unix-styled slashes. Note that this is the virtual path, so it starts at the mount root. The matching supports double-asterisks so you can match for patterns like `/blog/*/**` to match anything from the third level and down. + - lang - : A Glob pattern matching the Page's language, e.g. "{en,sv}". ++###### kind {#cascade-kind} ++ ++(`string`) A Glob pattern matching the Page's Kind(s), e.g. "{home,section}". ++ ++###### lang {#cascade-lang} + - environment - : A Glob pattern matching the build environment, e.g. "{production,development}" ++(`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 %}} - When making a site that supports multiple languages, defining a `[[cascade]]` is recommended to be done in [Site Config](../../getting-started/configuration/#cascade) to prevent duplication. ++With a multilingual site it may be more efficient to define the `cascade` values in your site configuration to avoid duplicating the `cascade` values on the section, taxonomy, or term page for each language. + - If you instead define a `[[cascade]]` in front matter for multiple languages, an `content/XX/foo/_index.md` file needs to be made on a per-language basis, with `XX` the glob pattern matching the Page's language. In this case, the **lang** keyword is ignored. ++With a multilingual site, if you choose to define the `cascade` values in front matter, you must create a section, taxonomy, or term page for each language; the `lang` keyword is ignored. +{{% /note %}} + +### Example + - In `content/blog/_index.md` - - {{< code-toggle >}} - title: Blog - cascade: - banner: images/typewriter.jpg ++{{< code-toggle file=content/posts/_index.md fm=true >}} ++date = 2024-02-01T21:25:36-08:00 ++title = 'Posts' ++[cascade] ++ [cascade.params] ++ banner = 'images/typewriter.jpg' +{{}} + - With the above example the Blog section page and its descendants will return `images/typewriter.jpg` when `.Params.banner` is invoked unless: ++With the above example the posts section page and its descendants will return `images/typewriter.jpg` when `.Params.banner` is invoked unless: + +- Said descendant has its own `banner` value set +- Or a closer ancestor node has its own `cascade.banner` value set. + - ## Order content through front matter ++## Emacs Org Mode + - You can assign content-specific `weight` in the front matter of your content. These values are especially useful for [ordering][ordering] in list views. You can use `weight` for ordering of content and the convention of [`_weight`][taxweight] for ordering content within a taxonomy. See [Ordering and Grouping Hugo Lists][lists] to see how `weight` can be used to organize your content in list views. ++If your [content format] is [Emacs Org Mode], you may provide front matter using Org Mode keywords. For example: + - ## Override global markdown configuration ++{{< 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 >}} + - 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]. ++Note that you can also specify array elements on a single line: + - ## Front matter format specs ++{{< code file=content/example.org lang=text >}} ++#+TAGS[]: red blue ++{{< /code >}} + - - [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/ ++[content format]: /content-management/formats/ ++[emacs org mode]: https://orgmode.org/ diff --cc docs/content/en/content-management/image-processing/index.md index 9a4f55da1,000000000..292aa8a4d mode 100644,000000..100644 --- a/docs/content/en/content-management/image-processing/index.md +++ b/docs/content/en/content-management/image-processing/index.md @@@ -1,521 -1,0 +1,523 @@@ +--- +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" }} + +``` + +Example 2: Skips image rendering if the resource is not found. + +```go-html-template +{{ $image := .Resources.GetMatch "sunset.jpg" }} +{{ with $image }} + +{{ 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" }} + +{{ 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 }} + + {{ 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 }} +
    + {{ with .Date }}
  • Date: {{ .Format "January 02, 2006" }}
    • {{ end }} + {{ with .Tags.ApertureValue }}
  • Aperture: {{ lang.FormatNumber 2 . }}
    • {{ end }} + {{ with .Tags.BrightnessValue }}
  • Brightness: {{ lang.FormatNumber 2 . }}
    • {{ end }} + {{ with .Tags.ExposureTime }}
  • Exposure Time: {{ . }}
    • {{ end }} + {{ with .Tags.FNumber }}
  • F Number: {{ . }}
    • {{ end }} + {{ with .Tags.FocalLength }}
  • Focal Length: {{ . }}
    • {{ end }} + {{ with .Tags.ISOSpeedRatings }}
  • ISO Speed Ratings: {{ . }}
    • {{ end }} + {{ with .Tags.LensModel }}
  • Lens Model: {{ . }}
    • {{ end }} +
+{{ end }} +``` + - #### EXIF variables ++#### EXIF methods + - .Date - : Image creation date/time. Format with the [time.Format] function. ++Date ++: (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`]function. + - .Lat - : GPS latitude in degrees. ++[time.Format]: /functions/time/format/ + - .Long - : GPS longitude in degrees. ++Lat ++: (`float64`) Returns the GPS latitude in degrees. + - .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). ++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) }} + + {{ 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) }} + + {{ 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 +{{}} +``` + +{{% 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 +``` + - [time.Format]: /functions/time/format ++ +[`anchor`]: /content-management/image-processing#anchor +[mounted]: /hugo-modules/configuration#module-configuration-mounts - [page bundle]: /content-management/page-bundles - [`lang.FormatNumber`]: /functions/lang/formatnumber ++[page bundle]: /content-management/page-bundles/ ++[`lang.FormatNumber`]: /functions/lang/formatnumber/ +[filters]: /functions/images/filter/#image-filters +[github.com/disintegration/imaging]: +[Smartcrop]: +[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/ diff --cc docs/content/en/content-management/markdown-attributes.md index 000000000,000000000..9c62c4fba new file mode 100644 --- /dev/null +++ b/docs/content/en/content-management/markdown-attributes.md @@@ -1,0 -1,0 +1,115 @@@ ++--- ++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 ++

This is a paragraph.

++``` ++ ++## 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 ++ ++``` ++ ++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). diff --cc docs/content/en/content-management/mathematics.md index b4dca75b1,000000000..a01a166dc mode 100644,000000..100644 --- a/docs/content/en/content-management/mathematics.md +++ b/docs/content/en/content-management/mathematics.md @@@ -1,227 -1,0 +1,228 @@@ +--- - title: Mathematics in markdown ++title: Mathematics in Markdown +linkTitle: Mathematics - description: Include mathematical equations and expressions in your markdown using LaTeX or TeX typesetting syntax. ++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 - weight: 250 - weight: 250 ++ 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 + - Follow these instructions to include mathematical equations and expressions in your markdown using LaTeX or TeX typesetting syntax. ++Follow these instructions to include mathematical equations and expressions in your Markdown using LaTeX or TeX typesetting syntax. + +###### Step 1 + - Enable and configure the Goldmark [passthrough extension] in your site configuration. The passthrough extension preserves raw markdown within delimited snippets of text, including the delimiters themselves. ++Enable and configure the Goldmark [passthrough extension] in your 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 >}} + + +{{< /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 >}} + + ... + {{ if .Param "math" }} + {{ partialCached "math.html" . }} + {{ end }} + ... + +{{< /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 + - Include mathematical equations and expressions in your markdown using LaTeX or TeX typesetting syntax. ++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' - math = true +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 >}} + + + + +{{< /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 diff --cc docs/content/en/content-management/menus.md index 1f5d1ef71,000000000..1f8595816 mode 100644,000000..100644 --- a/docs/content/en/content-management/menus.md +++ b/docs/content/en/content-management/menus.md @@@ -1,232 -1,0 +1,233 @@@ +--- +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 + - To automatically define menu entries for each top-level section of your site, enable the section pages menu in your site configuration. ++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 = '' +[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 file path of the target page, relative to the `content` directory. Omit language code and file extension. Required for *internal* links. ++: (`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 = '' +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/ diff --cc docs/content/en/content-management/multilingual.md index ea9f71787,000000000..22e2c186a mode 100644,000000..100644 --- a/docs/content/en/content-management/multilingual.md +++ b/docs/content/en/content-management/multilingual.md @@@ -1,716 -1,0 +1,634 @@@ +--- +title: Multilingual mode +linkTitle: Multilingual - description: Hugo supports the creation of websites with multiple languages side by side. ++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/] +--- + - You should define the available languages in a `languages` section in your site configuration. - - Also See [Hugo Multilingual Part 1: Content translation]. - +## 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 - : (`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: ++: (`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` - - `en-gb` - - `pt-br` ++- `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 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: ++: (`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 - : (`string`) The language title. When set, this overrides the site title for this language. ++: (`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 - [RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646 ++[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 + - From **Hugo 0.31** we support multiple languages in a multihost configuration. See [this issue](https://github.com/gohugoio/hugo/issues/4027) for details. + - This means that you can now configure a `baseURL` per `language`: ++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] - [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" ++ [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 +{{}} + +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 }} +

{{ i18n "translations" }}

+ +{{ 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 >}} + +{{< /code >}} + +## Translation of strings + - 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//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 ++See the [`lang.Translate`] template function. + - ```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") }} - ``` ++[`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 }}` + - 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). ++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 +``` + - [`abslangurl`]: /functions/urls/abslangurl ++[`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/ - [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 ++[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 - [`rellangurl`]: /functions/urls/rellangurl - [RFC 5646]: https://tools.ietf.org/html/rfc5646 ++[`rellangurl`]: /functions/urls/rellangurl/ +[single page templates]: /templates/single-page-templates/ - [`time.Format`]: /functions/time/format ++[`time.Format`]: /functions/time/format/ diff --cc docs/content/en/content-management/organization/index.md index 22b341fcf,000000000..e286462d7 mode 100644,000000..100644 --- a/docs/content/en/content-management/organization/index.md +++ b/docs/content/en/content-management/organization/index.md @@@ -1,154 -1,0 +1,169 @@@ +--- +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. + - {{< 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 >}} ++```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 ++``` + - {{% note %}} - The bundle documentation is a **work in progress**. We will publish more comprehensive docs about this soon. - {{% /note %}} ++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/`) 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 + - The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseURL = "https://example.org"` in your [site's configuration file][config]. ++The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseURL = "https://example.org/"` in your [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 +. ⊢--^-⊣⊢---^---⊣ - . filepath ++. 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 ++[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/ diff --cc docs/content/en/content-management/page-bundles.md index 860fff2bb,000000000..af7c2ce14 mode 100644,000000..100644 --- a/docs/content/en/content-management/page-bundles.md +++ b/docs/content/en/content-management/page-bundles.md @@@ -1,183 -1,0 +1,157 @@@ +--- +title: Page bundles - description: Content organization using Page Bundles ++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 +--- + - Page Bundles are a way to group [Page Resources](/content-management/page-resources/). ++## Introduction + - A Page Bundle can be one of: ++A page bundle is a directory that encapsulates both content and associated resources. + - - Leaf Bundle (leaf means it has no children) - - Branch Bundle (home page, section, taxonomy terms, taxonomy list) ++By way of example, this site has an "about" page and a "privacy" page: + - | | 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 | ++```text ++content/ ++├── about/ ++│ ├── index.md ++│ └── welcome.jpg ++└── privacy.md ++``` + - ## Leaf bundles ++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 %}} + - A _Leaf Bundle_ is a directory at any hierarchy within the `content/` - directory, that contains an **`index.md`** file. ++## Comparison + - ### Examples of leaf bundle organization {#examples-of-leaf-bundle-organization} ++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 - │ ├── index.md ++│ └── index.md +├── posts +│ ├── my-post - │ │ ├── content1.md - │ │ ├── content2.md - │ │ ├── image1.jpg - │ │ ├── image2.png ++│ │ ├── 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 - ├── .. ++ ├── bar.md + └── another-leaf-bundle + └── index.md +``` + - In the above example `content/` directory, there are four leaf - bundles: ++There are four leaf bundles in the example above: + +about - : This leaf bundle is at the root level (directly under - `content` directory) and has only the `index.md`. ++: This leaf bundle does not contain any page resources. + +my-post - : This leaf bundle has the `index.md`, two other content - Markdown files and two image files. ++: This leaf bundle contains an index file, two resources of [resource type] `page`, and two resources of resource type `image`. + - - image1, image2: - These images are page resources of `my-post` - and only available in `my-post/index.md` resources. ++- content-1, content-2 + - - 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. ++ 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 has only the `index.md`. ++: This leaf bundle does not contain any page resources. + +another-leaf-bundle - : 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. + +{{% note %}} - The hierarchy depth at which a leaf bundle is created does not matter, - as long as it is not inside another **leaf** bundle. ++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 %}} + - ### 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*" }} -

Authors

- {{ range $reusablePages }} -

{{ .Title }}

- {{ .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" - +## Branch bundles + - 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 ++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-1 - │ ├── branch-content1.md - │ ├── branch-content2.md - │ ├── image1.jpg - │ ├── image2.png ++├── 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 - └── branch-bundle-2 - ├── _index.md - └── a-leaf-bundle - └── index.md ++└── _index.md +``` + - In the above example `content/` directory, there are two branch - bundles (and a leaf bundle): ++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`, two - other content Markdown files and two image files. ++: This branch bundle contains an index file, two resources of [resource type] `page`, and two resources of resource type `image`. + +branch-bundle-2 - : This branch bundle has the `_index.md` and a - nested leaf bundle. ++: This branch bundle contains an index file and a leaf bundle. + +{{% note %}} - The hierarchy depth at which a branch bundle is created does not - matter. ++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 %}} + - [^fn:1]: The `.md` extension is just an example. The extension can be `.html`, `.json` or any valid MIME type. ++ ++## 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/ diff --cc docs/content/en/content-management/page-resources.md index f141510bb,000000000..6f746488c mode 100644,000000..100644 --- a/docs/content/en/content-management/page-resources.md +++ b/docs/content/en/content-management/page-resources.md @@@ -1,203 -1,0 +1,309 @@@ +--- +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" }} + +{{ end }} + +{{ with .Resources.GetMatch "style.css" }} + +{{ end }} + +{{ with .Resources.GetMatch "img.png" }} + +{{ 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" 🚫 +``` + - ## Page resources metadata ++## 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/values. ++: 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" +{{}} + +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" +{{}} + +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 >}} diff --cc docs/content/en/content-management/related.md index e73dfc32a,000000000..478b55a99 mode 100644,000000..100644 --- a/docs/content/en/content-management/related.md +++ b/docs/content/en/content-management/related.md @@@ -1,178 -1,0 +1,178 @@@ +--- +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 }} +

See Also

+ +{{ 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 }} +

See Also

+
    + {{ range $i, $p := . }} +
  • + {{ .LinkTitle }} + {{ with .HeadingsFiltered }} +
      + {{ range . }} + {{ $link := printf "%s#%s" $p.RelPermalink .ID | safeURL }} +
    • + {{ .Title }} +
      • + {{ end }} +
    + {{ end }} +
    • + {{ end }} +
+{{ 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`) 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`. ++: (`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 %}} diff --cc docs/content/en/content-management/sections.md index 1b694ce44,000000000..0c2f8f0e2 mode 100644,000000..100644 --- a/docs/content/en/content-management/sections.md +++ b/docs/content/en/content-management/sections.md @@@ -1,161 -1,0 +1,164 @@@ +--- +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` collection instead of the `.Pages` collection in the list template. See [details](/variables/page/#page-collections). ++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 >}} + +{{< /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 diff --cc docs/content/en/content-management/shortcodes.md index bbc2b0cc8,000000000..87c9f0825 mode 100644,000000..100644 --- a/docs/content/en/content-management/shortcodes.md +++ b/docs/content/en/content-management/shortcodes.md @@@ -1,404 -1,0 +1,477 @@@ +--- +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 ` + +{{< /code >}} + +{{< code file=youtube-embed.html >}} +
+ +
+{{< /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 >}} +{{}} +{{< /code >}} + +You have created the shortcode at `/layouts/shortcodes/img.html`, which loads the following shortcode template: + +{{< code file=layouts/shortcodes/img.html >}} + +
+ {{ with .Get "link" }}{{ end }} + + {{ if .Get "link" }}{{ end }} + {{ if or (or (.Get "title") (.Get "caption")) (.Get "attr") }} +
{{ if isset .Params "title" }} +

{{ .Get "title" }}

{{ end }} + {{ if or (.Get "caption") (.Get "attr") }}

+ {{ .Get "caption" }} + {{ with .Get "attrlink" }} {{ end }} + {{ .Get "attr" }} + {{ if .Get "attrlink" }} {{ end }} +

{{ end }} +
+ {{ end }} +
+ +{{< /code >}} + +Would be rendered as: + +{{< code file=img-output.html >}} +
+ +
+

Steve Francia

+
+
+{{< /code >}} + +### Single flexible example: `vimeo` + +```go-html-template +{{}} +{{}} +``` + +Would load the template found at `/layouts/shortcodes/vimeo.html`: + +{{< code file=layouts/shortcodes/vimeo.html >}} +{{ if .IsNamedParams }} +
+ +
+{{ else }} +
+ +
+{{ end }} +{{< /code >}} + +Would be rendered as: + +{{< code file=vimeo-iframes.html >}} +
+ +
+
+ +
+{{< /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 >}} +{{}} + + This HTML + +{{}} +{{< /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 >}} +
<html>
 +    <body> This HTML </body>
 +</html>
 +
+{{< /code >}} + +### Nested shortcode: image gallery + - 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. ++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. + - The following example is contrived but demonstrates the concept. Assume you have a `gallery` shortcode that expects one named `class` parameter: ++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 >}} +
+ {{ .Inner }} +
+{{< /code >}} + - 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`: ++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 -}} + +{{- else -}} + +{{- end -}} +{{< /code >}} + +You can then call your shortcode in your content as follows: + +```go-html-template +{{}} + {{}} + {{}} +{{}} +{{}} +``` + +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 +
+ + +
+ +``` + +## Error handling in shortcodes + - Use the [errorf](/functions/fmt/errorf) template function and [`.Position`] shortcode method to get useful error messages in shortcodes: ++Use the [`errorf`] template function with the [`Name`] and [`Position`] shortcode methods to generate useful error messages: + - ```sh ++{{< code file=layouts/shortcodes/greeting.html >}} +{{ with .Get "name" }} ++

Hello, my name is {{ . }}.

+{{ else }} - {{ errorf "missing value for parameter 'name': %s" .Position }} ++ {{ errorf "The %q shortcode requires a 'name' argument. See %s" .Name .Position }} +{{ end }} - ``` ++{{< /code >}} + - When the above fails, you will see an `ERROR` log similar to the below: ++When the above fails, you will see an `ERROR` message such as: + +```sh - 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" ++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 + {{}}{{ now }}{{}} + ``` + +The above will print the current date and time. + - 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. ++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". + - The same inline shortcode can be reused later in the same content file, with different parameters if needed, using the self-closing syntax: ++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 +{{}} +``` + - [basic content files]: /content-management/formats/ ++[`.Parent`]: /methods/shortcode/parent/ ++[`errorf`]: /functions/fmt/errorf/ ++[`Name`]: /methods/shortcode/name/ ++[`Position`]: /methods/shortcode/position/ +[built-in shortcode]: /content-management/shortcodes/ - [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 +[figure]: /content-management/shortcodes/#figure - [hugosc]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes +[lookup order]: /templates/lookup-order/ - [pagevars]: /variables/page/ - [`.Parent`]: /methods/shortcode/parent/ - [`.Position`]: /methods/shortcode/position/ - [spfscs]: https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes ++[source organization]: /getting-started/directory-structure/ +[vimeoexample]: #single-flexible-example-vimeo +[youtubeshortcode]: /content-management/shortcodes/#youtube diff --cc docs/content/en/templates/single-page-templates.md index cd8a2715c,000000000..9546486f8 mode 100644,000000..100644 --- a/docs/content/en/templates/single-page-templates.md +++ b/docs/content/en/templates/single-page-templates.md @@@ -1,85 -1,0 +1,77 @@@ +--- +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 + - 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. - +{{< code file=layouts/posts/single.html >}} +{{ define "main" }} +
+

{{ .Title }}

+
+
+ {{ .Content }} +
+
+
+ +{{ 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 - [pagevars]: /variables/page/ +[partials]: /templates/partials/ +[section]: /content-management/sections/ - [site variables]: /variables/site/ +[spf13]: https://spf13.com/ +[`with`]: /functions/go-template/with/ diff --cc docs/content/en/templates/sitemap-template.md index 07acfdb63,000000000..64609f0b9 mode 100644,000000..100644 --- a/docs/content/en/templates/sitemap-template.md +++ b/docs/content/en/templates/sitemap-template.md @@@ -1,79 -1,0 +1,82 @@@ +--- +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 + - Hugo's built-in sitemap templates conform to v0.9 of the [sitemap protocol]. ++Hugo's embedded sitemap templates conform to v0.9 of the [sitemap protocol]. + - With a monolingual project, Hugo generates a sitemap.xml file in the root of the [`publishDir`] using the built-in [sitemap.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: + - - 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 ++- 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 + - Set the default values for [change frequency] and [priority], and the name of the generated file, in your site configuration. ++These are the default sitemap configuration values. They apply to all pages unless overridden in front matter. + +{{< code-toggle config=sitemap />}} + +changefreq - : 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). ++: (`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 name of the generated file. Default is `sitemap.xml`. ++: (`string`) The name of the generated file. Default is `sitemap.xml`. + +priority - : 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). ++: (`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 +{{}} + +## 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'] +{{}} + +[`publishDir`]: /getting-started/configuration#publishdir - [change frequency]: - [priority]: +[sitemap protocol]: - [sitemap.xml]: - [sitemapindex.xml]: diff --cc docs/content/en/templates/taxonomy-templates.md index ff149e940,000000000..e83231a5c mode 100644,000000..100644 --- a/docs/content/en/templates/taxonomy-templates.md +++ b/docs/content/en/templates/taxonomy-templates.md @@@ -1,318 -1,0 +1,285 @@@ +--- +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: + - * 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) ++* 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 templates ++## Taxonomy templates + - Taxonomy list page templates are lists and therefore have all the variables and methods available to [list pages][lists]. ++Taxonomy list page templates are lists and therefore have all the methods available to [list pages][lists]. + - ### Taxonomy list template lookup order ++### Taxonomy template lookup order + +See [Template Lookup](/templates/lookup-order/). + - ## Taxonomy terms templates ++## Term templates + - ### Taxonomy terms templates lookup order ++### Term template lookup order + +See [Template Lookup](/templates/lookup-order/). + +### Taxonomy methods + - A Taxonomy is a `map[string]WeightedPages`. ++{{< list-pages-in-section path=/methods/taxonomy/ >}} + - .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. + +### 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 need to display custom metadata for each taxonomy term, you will need to create a page for that term at `/content///_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: ++If you need to display custom metadata for each taxonomy term, you will need to create a page for that term at `/content///_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 +
    + {{ range .Pages }} +
  • + {{ .LinkTitle }} + {{ .Params.wikipedia }} +
    • + {{ end }} +
+``` + +## 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 +
    + {{ range .Data.Terms.Alphabetical }} +
  • {{ .Page.Title }} {{ .Count }}
    • + {{ end }} +
+``` + +## 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 }} +

{{ (site.GetPage $taxonomy).LinkTitle }}:

+ +{{ end }} +``` + +To render a comma-delimited list: + +```go-html-template +{{ $taxonomy := "tags" }} +{{ with .GetTerms $taxonomy }} +

+ {{ (site.GetPage $taxonomy).LinkTitle }}: + {{ range $k, $_ := . -}} + {{ if $k }}, {{ end }} + {{ .LinkTitle }} + {{- end }} +

+{{ end }} +``` + +## List content with the same taxonomy term + - 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 are using a taxonomy for something like a series of posts, you can list individual pages associated with the same term. For example: ++ + - ### Example: showing content in same series + +```go-html-template + +``` + +## 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. + - ### Example: grouping "featured" content - +```go-html-template + +``` + +## Render a site's taxonomies + - 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. - +The following example displays all terms in a site's tags taxonomy: + - ### Example: list all site tags - +```go-html-template + +``` - - ### Example: list all taxonomies, terms, and assigned content - +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 $taxonomy, $terms := site.Taxonomies }} -
  • - {{ with site.GetPage $taxonomy }} - {{ .LinkTitle }} - {{ end }} -
      - {{ range $term, $weightedPages := $terms }} ++{{ with .Site.Taxonomies }} ++ {{ $numberOfTerms := 0 }} ++ {{ range $taxonomy, $terms := . }} ++ {{ $numberOfTerms = len . | add $numberOfTerms }} ++ {{ end }} ++ ++ {{ if gt $numberOfTerms 0 }} ++ - - {{ end }} -
    - {{< /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" }} -
      - {{ with ($.Site.GetPage (printf "/%s" $taxo)) }} - {{ range .Pages }} -
    • {{ .LinkTitle }}
      • - {{ end }} ++ {{ end }} ++
    + {{ end }} -
++{{ end }} +{{< /code >}} + - [getpage]: /methods/page/getpage ++[`Pages`]: /methods/page/pages/ ++[getpage]: /methods/page/getpage/ +[lists]: /templates/lists/ +[renderlists]: /templates/lists/ +[single page template]: /templates/single-page-templates/ - [sitevars]: /variables/site/ diff --cc docs/content/en/templates/views.md index e49f1debb,000000000..4170196b6 mode 100644,000000..100644 --- a/docs/content/en/templates/views.md +++ b/docs/content/en/templates/views.md @@@ -1,113 -1,0 +1,107 @@@ +--- +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 +``` + - 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. ++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? + - The following is the [lookup order][lookup] for content views: ++The following is the [lookup order] for content views: + +1. `/layouts//.html` +2. `/layouts/_default/.html` +3. `/themes//layouts//.html` +4. `/themes//layouts/_default/.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 >}} +
+
+

{{ .Title }}

+ {{ range .Pages }} + {{ .Render "summary" }} + {{ end }} +
+
+{{< /code >}} + +### `summary.html` + - Hugo will pass the entire page object to the following `summary.html` view template. (See [Page Variables][pagevars] for a complete list.) ++Hugo passes the page object to the following `summary.html` view template. + +{{< code file=layouts/_default/summary.html >}} + +{{< /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 >}} +
  • + {{ .LinkTitle }} +
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    +
    • +{{< /code >}} + +[lists]: /templates/lists/ - [lookup]: /templates/lookup-order/ - [pagevars]: /variables/page/ +[render]: /methods/page/render/ +[single]: /templates/single-page-templates/ - [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 +[summaries]: /content-management/summaries/ +[taxonomylists]: /templates/taxonomy-templates/ diff --cc docs/content/en/tools/_index.md index 006bed053,000000000..9cd72853a mode 100644,000000..100644 --- a/docs/content/en/tools/_index.md +++ b/docs/content/en/tools/_index.md @@@ -1,20 -1,0 +1,20 @@@ +--- +title: Developer tools - linkTitle: 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-overview ++ 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/ diff --cc docs/content/en/tools/editors.md index d94b7af0f,000000000..b2e2cc47b mode 100644,000000..100644 --- a/docs/content/en/tools/editors.md +++ b/docs/content/en/tools/editors.md @@@ -1,66 -1,0 +1,64 @@@ +--- +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. + - [xxx]: xxx - +[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/ diff --cc docs/content/en/tools/front-ends.md index acce84d8d,000000000..217f96e2c mode 100644,000000..100644 --- a/docs/content/en/tools/front-ends.md +++ b/docs/content/en/tools/front-ends.md @@@ -1,30 -1,0 +1,36 @@@ +--- +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. + - ## Open source ++[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. diff --cc docs/content/en/tools/migrations.md index 0e61274c4,000000000..3a2cdac35 mode 100644,000000..100644 --- a/docs/content/en/tools/migrations.md +++ b/docs/content/en/tools/migrations.md @@@ -1,102 -1,0 +1,105 @@@ +--- +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 - \s-\scan [export your site for Jekyll](https://wordpress.org/plugins/jekyll-exporter/) and use Hugo's built in Jekyll converter listed above.) ++: 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. diff --cc docs/content/en/tools/other.md index f5243632c,000000000..8edfc4258 mode 100644,000000..100644 --- a/docs/content/en/tools/other.md +++ b/docs/content/en/tools/other.md @@@ -1,23 -1,0 +1,24 @@@ +--- +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 +--- + - And for all the other small things around Hugo: ++And for all the other community projects around Hugo: + - - [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. ++- [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. diff --cc docs/content/en/tools/search.md index c3db0dc98,000000000..921d52f82 mode 100644,000000..100644 --- a/docs/content/en/tools/search.md +++ b/docs/content/en/tools/search.md @@@ -1,55 -1,0 +1,55 @@@ +--- +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. + - ## Open source ++## 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. ++: 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. diff --cc docs/content/en/troubleshooting/_index.md index 65263ab32,000000000..92ba6bc6d mode 100644,000000..100644 --- a/docs/content/en/troubleshooting/_index.md +++ b/docs/content/en/troubleshooting/_index.md @@@ -1,16 -1,0 +1,16 @@@ +--- +title: Troubleshooting - linkTitle: Overview ++linkTitle: In this section +description: Use these techniques when troubleshooting your site. +categories: [] +keywords: [] +menu: + docs: - identifier: troubleshooting-overview ++ identifier: troubleshooting-in-this-section + parent: troubleshooting + weight: 10 +weight: 10 +aliases: [/templates/template-debugging/] +--- + +Use these techniques when troubleshooting your site. diff --cc docs/content/en/troubleshooting/audit/index.md index f00ed8f8d,000000000..e0de0d5df mode 100644,000000..100644 --- a/docs/content/en/troubleshooting/audit/index.md +++ b/docs/content/en/troubleshooting/audit/index.md @@@ -1,73 -1,0 +1,73 @@@ +--- +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>)|hahahugo" public/ +{{< /code >}} + +_Tested with GNU Bash 5.1 and GNU grep 3.7._ + +## Example output + +![site audit terminal output](screen-capture.png) + +## 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 + +`` - : By default, Hugo strips raw HTML from your markdown prior to rendering, and leaves this HTML comment in its place. ++: 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. + +`()` +: 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. diff --cc docs/content/en/troubleshooting/faq.md index 0425ca277,000000000..f8106a7db mode 100644,000000..100644 --- a/docs/content/en/troubleshooting/faq.md +++ b/docs/content/en/troubleshooting/faq.md @@@ -1,124 -1,0 +1,143 @@@ +--- +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`. + - ###### 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`. - +###### 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? + - Use the `{{%/* shortcode */%}}` notation if the shortcode template, or the content between the opening and closing shortcode tags, contains markdown. Otherwise use the\ ++Use the `{{%/* shortcode */%}}` notation if the shortcode template, or the content between the opening and closing shortcode tags, contains Markdown. Otherwise use the\ +`{{}}` 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 %}} + - [`Paginate`]: /methods/page/paginate - [`Paginator`]: /methods/page/paginator ++[`Paginate`]: /methods/page/paginate/ ++[`Paginator`]: /methods/page/paginator/ +[context]: /getting-started/glossary/#context +[forum]: https://discourse.gohugo.io - [installation]: /installation ++[installation]: /installation/ +[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132 diff --cc docs/content/en/troubleshooting/inspection.md index 826229153,000000000..e9fc8ed0f mode 100644,000000..100644 --- a/docs/content/en/troubleshooting/inspection.md +++ b/docs/content/en/troubleshooting/inspection.md @@@ -1,72 -1,0 +1,44 @@@ +--- +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 +--- + - Use the [`jsonify`] function to inspect a data structure: ++Use the [`debug.Dump`] function to inspect a data structure: + +```go-html-template - 
    {{ jsonify (dict "indent" "  ") .Params }}
    ++
    {{ debug.Dump .Params }}
    +``` + +```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" +} +``` + - {{% 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 - 
    {{ debug.Dump .Params }}
    - ``` - - ```text - maps.Params{ - "date": time.Time{}, - "draft": false, - "iscjklanguage": false, - "lastmod": time.Time{}, - "publishdate": time.Time{}, - "tags": []string{ - "foo", - "bar", - }, - "title": "My first post", - } - ``` - +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) +``` + - [`jsonify`]: /functions/encoding/jsonify - [`debug.Dump`]: /functions/debug/dump - [`printf`]: /functions/fmt/printf - [`warnf`]: /functions/fmt/warnf ++[`debug.Dump`]: /functions/debug/dump/ ++[`printf`]: /functions/fmt/printf/ ++[`warnf`]: /functions/fmt/warnf/ diff --cc docs/content/en/troubleshooting/logging.md index 8879c1846,000000000..fc6838069 mode 100644,000000..100644 --- a/docs/content/en/troubleshooting/logging.md +++ b/docs/content/en/troubleshooting/logging.md @@@ -1,56 -1,0 +1,72 @@@ +--- +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. diff --cc docs/content/en/troubleshooting/performance.md index 174d6cfd9,000000000..a2df1b08e mode 100644,000000..100644 --- a/docs/content/en/troubleshooting/performance.md +++ b/docs/content/en/troubleshooting/performance.md @@@ -1,94 -1,0 +1,112 @@@ +--- +title: Performance - description: Use template metrics and timers to identify opportunities to improve performance. ++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. + - [`partial`]: /functions/partials/include - [`partialCached`]: /functions/partials/includecached ++[`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 parameters to `partialCached` beyond the initial context. See the `partialCached` documentation for more details. ++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/). diff --cc docs/data/docs.yaml index 476d374a1,000000000..603519d76 mode 100644,000000..100644 --- a/docs/data/docs.yaml +++ b/docs/data/docs.yaml @@@ -1,4646 -1,0 +1,4635 @@@ +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 - - Aliases: - - gleam> - Name: Gleam + - 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: - delete: - enable: false + 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 - paginate: 0 - paginatePath: "" - pagination: - disableAliases: false - pagerSize: 10 - path: page ++ 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 - pagination: - _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 + - - Search + - Search + - - '{{ 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. + {"newIn": "0.98.0" } + 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" . }}' + - Hugo Rocks! + 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 "

    Blockhead

    \n" | safeHTML }}' + -

    Blockhead

    + 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 `(.+?)` `
  • Foo
    • +
  • Bar
    • ` | print | safeHTML }}' + - '[[Foo #foo Foo] [Bar #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 Markdown … + 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 " | + safeHTML }}' + - Cathal Garvey & The Sunshine Band <cathal@foo.bar> + - - '{{ htmlEscape "Cathal Garvey & The Sunshine Band " }}' + - Cathal Garvey &amp; The Sunshine Band &lt;cathal@foo.bar&gt; + - - '{{ htmlEscape "Cathal Garvey & The Sunshine Band " | + htmlUnescape | safeHTML }}' + - Cathal Garvey & The Sunshine Band + 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 Garvey &amp; The Sunshine Band &lt;cathal@foo.bar&gt;" + | htmlUnescape | htmlUnescape | safeHTML }}' + - Cathal Garvey & The Sunshine Band + - - '{{ "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 }}' + - BatMan + Plainify: + Aliases: + - plainify + Args: + - s + Description: Plainify returns a copy of s with all HTML tags removed. + Examples: + - - '{{ plainify "Hello world, 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 "

    abc

    " }}' + - '<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: [] diff --cc docs/data/embedded_template_urls.toml index 000000000,000000000..7bb2e4eee new file mode 100644 --- /dev/null +++ b/docs/data/embedded_template_urls.toml @@@ -1,0 -1,0 +1,36 @@@ ++# 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' diff --cc docs/data/homepagetweets.toml index cde241f01,000000000..b440c21df mode 100644,000000..100644 --- a/docs/data/homepagetweets.toml +++ b/docs/data/homepagetweets.toml @@@ -1,265 -1,0 +1,265 @@@ +[[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." - link = "https://twitter.com/heinrichhartman/status/1199736512264462341" ++link = "https://x.com/heinrichhartman/status/1199736512264462341" +date = 2019-11-12T00:00:00Z + +[[tweet]] +name = "Joshua Steven‏‏" +twitter_handle = "@jscarto" - quote = "Can't overstate how much I enjoy @GoHugoIO. 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" ++quote = "Can't overstate how much I enjoy @GoHugoIO. 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 = "The more I use gohugo.io, the more I really like it. Super intuitive/powerful static site generator...great job @GoHugoIO" - link = "https://twitter.com/spcrngr_/status/870863020905435136" ++quote = "The more I use gohugo.io, the more I really like it. Super intuitive/powerful static site generator...great job @GoHugoIO" ++link = "https://x.com/spcrngr_/status/870863020905435136" +date = 2017-06-03T00:00:00Z + +[[tweet]] +name = "marcoscan" +twitter_handle = "@marcoscan" - quote = "Blog migrated from @WordPress to @GoHugoIO, with a little refresh of my theme, Vim shortcuts and a full featured deploy script #gohugo" - link = "https://twitter.com/marcoscan/status/869661175960752129" ++quote = "Blog migrated from @WordPress to @GoHugoIO, with a little refresh of my theme, Vim shortcuts and a full featured deploy script #gohugo" ++link = "https://x.com/marcoscan/status/869661175960752129" +date = 2017-05-30T00:00:00Z + +[[tweet]] +name = "Sandra Kuipers" +twitter_handle = "@SKuipersDesign" - quote = "Who knew static site building could be fun 🤔 Learning #gohugo today" - link = "https://twitter.com/SKuipersDesign/status/868796256902029312" ++quote = "Who knew static site building could be fun 🤔 Learning #gohugo today" ++link = "https://x.com/SKuipersDesign/status/868796256902029312" +date = 2017-05-28T00:00:00Z + +[[tweet]] +name = "Netlify" +twitter_handle = "@Netlify" - quote = "Top Ten Static Site Generators of 2017. Congrats to the top 3: 1. @Jekyllrb 2. @GoHugoIO 3. @hexojs" - link = "https://twitter.com/Netlify/status/868122279221362688" ++quote = "Top Ten Static Site Generators of 2017. Congrats to the top 3: 1. @Jekyllrb 2. @GoHugoIO 3. @hexojs" ++link = "https://x.com/Netlify/status/868122279221362688" +date = 2017-05-26T00:00:00Z + +[[tweet]] +name = "Phil Hawksworth" +twitter_handle = "@philhawksworth" - quote = "I've been keen on #JAMStack for some time, but @GoHugoIO is wooing me all over again. Great fun to build with. And speeeeedy." - link = "https://twitter.com/philhawksworth/status/866684170512326657" ++quote = "I've been keen on #JAMStack for some time, but @GoHugoIO 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 = "I've probably said it before...but having Hugo rebuild the whole website in 300ms is amazing. gohugo.io, #gohugo" - link = "https://twitter.com/aras_p/status/861157286823288832" ++quote = "I've probably said it before...but having Hugo rebuild the whole website in 300ms is amazing. gohugo.io, #gohugo" ++link = "https://x.com/aras_p/status/861157286823288832" +date = 2017-05-07T00:00:00Z + +[[tweet]] +name = "Hans Beck" +twitter_handle = "@EnrichedGamesHB" - quote = "Diving deeper into @GoHugoIO. A lot of docs there, top work! But I've the impressed that #gohugo is far easier than its feels from the docs!" - link = "https://twitter.com/EnrichedGamesHB/status/836854762440130560" ++quote = "Diving deeper into @GoHugoIO. A lot of docs there, top work! But I've the impressed that #gohugo 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 = "I migrated the @BlackOpsTesting .com website from docpad to Hugo last weekend. http://gohugo.io/ Super Fast HTML Generation @spf13 " - link = "https://twitter.com/eviltester/status/553520335115808768" ++quote = "I migrated the @BlackOpsTesting .com website from docpad to Hugo last weekend. http://gohugo.io/ Super Fast HTML Generation @spf13 " ++link = "https://x.com/eviltester/status/553520335115808768" +date = 2015-01-09T00:00:00Z + +[[tweet]] +name = "Janez Čadež‏" +twitter_handle = "@jamziSLO" - quote = "Building @garazaFRI website in #hugo. This static site generator is soooo damn fast! #gohugo #golang" - link = "https://twitter.com/jamziSLO/status/817720283977183234" ++quote = "Building @garazaFRI website in #hugo. This static site generator is soooo damn fast! #gohugo #golang" ++link = "https://x.com/jamziSLO/status/817720283977183234" +date = 2017-01-07T00:00:00Z + +[[tweet]] +name = "Execute‏‏" +twitter_handle = "@executerun" - quote = "Hah, #gohugo. I was working with #gohugo on #linux but now I realised how easy is to set-up it on #windows. Just need to add binary to #path!" - link = "https://twitter.com/executerun/status/809753145270272005" ++quote = "Hah, #gohugo. I was working with #gohugo on #linux but now I realised how easy is to set-up it on #windows. Just need to add binary to #path!" ++link = "https://x.com/executerun/status/809753145270272005" +date = 2016-12-16T00:00:00Z + +[[tweet]] +name = "Baron Schwartz" +twitter_handle = "@xaprb" - quote = "Hugo is impressively capable. It's a static site generator by @spf13 written in #golang . Just upgraded to latest release; very powerful. " - link = "https://twitter.com/xaprb/status/556894866488455169" ++quote = "Hugo is impressively capable. It's a static site generator by @spf13 written in #golang . 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/dch__/status/460158115498176512" ++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/dcaunt/statuses/406466996277374976" ++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/oddshocks/statuses/405083217893421056" ++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/DitiPengi/status/472470974051676160" ++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/DougStephenJr/statuses/364512471660249088" ++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/hugorodgerbrown/statuses/364417910153818112" ++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/hugoroyd/status/501704796727173120" ++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/DanielMiessler/status/704703841673957376" ++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/jsegura/status/465978434154659841" ++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/jimbiancolo/statuses/408678420348813314" ++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/jipjdekker/status/413783548735152131" ++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/jgonzalvo/statuses/408177855819173888" ++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/joshmatz/statuses/364437436870696960" ++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/kjhealy/status/437349384809115648" ++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/ludovicchabant/statuses/408806199602053120" ++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/lukeholder/status/430352287936946176" ++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/markuseliasson/status/501594865877008384" ++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/mercime_one/status/500547145087205377" ++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/mdwhatcott/status/469980686531571712" ++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/rojoroboto/status/423439915620106242" ++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/messo85/status/472825062027182081" ++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. gohugo.io" - link = "https://twitter.com/popthestack/status/549972754125307904" ++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/495716684456398848" ++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" - link = "https://twitter.com/TheLoneCuber/status/495731334711488512" ++link = "https://x.com/TheLoneCuber/status/495731334711488512" +date = 2014-08-02T00:00:00Z + +[[tweet]] +name = "WorkHTML" +twitter_handle = "@workhtml" - quote = " #Hugo A very good alternative for #wordpress !!! A fast and modern static website engine gohugo.io " - link = "https://twitter.com/workhtml/status/563064361301053440" ++quote = " #Hugo A very good alternative for #wordpress !!! A fast and modern static website engine gohugo.io " ++link = "https://x.com/workhtml/status/563064361301053440" +date = 2015-02-04T00:00:00Z diff --cc docs/data/page_filters.yaml index 2a3a8625d,000000000..a4969e9b7 mode 100644,000000..100644 --- a/docs/data/page_filters.yaml +++ b/docs/data/page_filters.yaml @@@ -1,93 -1,0 +1,95 @@@ +# 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 diff --cc docs/go.mod index e3420f6ae,000000000..ca0acd79f mode 100644,000000..100644 --- a/docs/go.mod +++ b/docs/go.mod @@@ -1,5 -1,0 +1,5 @@@ +module github.com/gohugoio/hugoDocs + +go 1.16 + - require github.com/gohugoio/gohugoioTheme v0.0.0-20240201183016-8e648a3b5342 // indirect ++require github.com/gohugoio/gohugoioTheme v0.0.0-20240619093131-b595d5fb8c52 // indirect diff --cc docs/go.sum index e6a4fcd6c,000000000..a1664d320 mode 100644,000000..100644 --- a/docs/go.sum +++ b/docs/go.sum @@@ -1,2 -1,0 +1,6 @@@ - 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= diff --cc docs/hugo.toml index 209231663,000000000..63cc32798 mode 100644,000000..100644 --- a/docs/hugo.toml +++ b/docs/hugo.toml @@@ -1,100 -1,0 +1,100 @@@ +# 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", "RSS"] ++ 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/**' diff --cc docs/netlify.toml index c65cd903e,000000000..54f157413 mode 100644,000000..100644 --- a/docs/netlify.toml +++ b/docs/netlify.toml @@@ -1,30 -1,0 +1,30 @@@ +[build] + publish = "public" + command = "hugo --gc --minify" + + [build.environment] - HUGO_VERSION = "0.122.0" ++ 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 diff --cc docs/static/shared/branding/hugo-tall.png index 000000000,000000000..001ce5eb3 new file mode 100644 Binary files differ diff --cc docs/static/shared/branding/made-with-hugo-dark.png index 000000000,000000000..c6cadf283 new file mode 100644 Binary files differ diff --cc docs/static/shared/branding/made-with-hugo-long-dark.png index 000000000,000000000..1e49995fb new file mode 100644 Binary files differ diff --cc docs/static/shared/branding/made-with-hugo-long.png index 000000000,000000000..c5df534cf new file mode 100644 Binary files differ diff --cc docs/static/shared/branding/made-with-hugo.png index 000000000,000000000..52dfd19e5 new file mode 100644 Binary files differ diff --cc docs/static/shared/branding/powered-by-hugo-dark.png index 000000000,000000000..a8e2ebc80 new file mode 100644 Binary files differ diff --cc docs/static/shared/branding/powered-by-hugo-long-dark.png index 000000000,000000000..1b760b1bf new file mode 100644 Binary files differ diff --cc docs/static/shared/branding/powered-by-hugo-long.png index 000000000,000000000..37131359d new file mode 100644 Binary files differ diff --cc docs/static/shared/branding/powered-by-hugo.png index 000000000,000000000..27ff099d5 new file mode 100644 Binary files differ diff --cc docs/static/shared/examples/data/books.json index 000000000,000000000..ae2f36db2 new file mode 100644 --- /dev/null +++ b/docs/static/shared/examples/data/books.json @@@ -1,0 -1,0 +1,55 @@@ ++[ ++ { ++ "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" ++ } ++] diff --cc docs/static/shared/examples/images/interpreting-the-french-revolution.webp index 000000000,000000000..4004b6613 new file mode 100644 Binary files differ diff --cc "docs/static/shared/examples/images/les-mis\303\251rables.webp" index 000000000,000000000..e336a5f16 new file mode 100644 Binary files differ diff --cc "docs/static/shared/examples/images/the-ancien-r\303\251gime-and-the-revolution.webp" index 000000000,000000000..f35183945 new file mode 100644 Binary files differ diff --cc docs/static/shared/examples/images/the-hunchback-of-notre-dame.webp index 000000000,000000000..f13e2224a new file mode 100644 Binary files differ