mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-21 20:46:30 -05:00
Merge commit '8b9803425e63e1b1801f8d5d676e96368d706722'
This commit is contained in:
Bjørn Erik Pedersen
commit
af0cb57aaf
475 changed files with 7408 additions and 4720 deletions
|
|
@ -20,13 +20,11 @@
|
|||
],
|
||||
"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",
|
||||
|
|
@ -42,14 +40,11 @@
|
|||
],
|
||||
"language": "en",
|
||||
"words": [
|
||||
"antialiasing",
|
||||
"codeowners",
|
||||
"composability",
|
||||
"configurators",
|
||||
"defang",
|
||||
"deindent",
|
||||
"downscale",
|
||||
"downscaled",
|
||||
"downscaling",
|
||||
"exif",
|
||||
"geolocalized",
|
||||
|
|
@ -57,60 +52,99 @@
|
|||
"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",
|
||||
|
|
@ -119,21 +153,19 @@
|
|||
"# ----------------------------------------------------------------------",
|
||||
"# 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"
|
||||
]
|
||||
}
|
||||
|
|
|
|||
|
|
@ -6,13 +6,12 @@
|
|||
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?"
|
||||
|
|
@ -20,3 +19,4 @@
|
|||
utm_campaign = "hugosponsor"
|
||||
show_on_hover = true
|
||||
bgcolor = "#4e4f4f"
|
||||
link_attr = "style='color: #ffffff; font-weight: bold; text-decoration: none; text-align: center'"
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
{{- /* Last modified: 2023-09-04T09:23:04-07:00 */}}
|
||||
{{- /* Last modified: 2024-04-26T13:54:00-07:00 */}}
|
||||
|
||||
{{- /*
|
||||
Copyright 2023 Veriphor LLC
|
||||
|
|
@ -118,7 +118,7 @@ either of these shortcodes in conjunction with this render hook.
|
|||
{{- $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 }}
|
||||
|
|
@ -137,7 +137,7 @@ either of these shortcodes in conjunction with this render hook.
|
|||
{{- 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 }}
|
||||
|
|
@ -185,14 +185,14 @@ either of these shortcodes in conjunction with this render hook.
|
|||
{{- end }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
{{- with .Title }}
|
||||
{{- $attrs = merge $attrs (dict "title" .) }}
|
||||
{{- end -}}
|
||||
{{- $attrs = merge $attrs (dict "title" (.Title | transform.HTMLEscape)) }}
|
||||
|
||||
{{- /* Render anchor element. */ -}}
|
||||
<a
|
||||
{{- range $k, $v := $attrs }}
|
||||
{{- printf " %s=%q" $k $v | safeHTMLAttr }}
|
||||
{{- if $v }}
|
||||
{{- printf " %s=%q" $k $v | safeHTMLAttr }}
|
||||
{{- end }}
|
||||
{{- end -}}
|
||||
>{{ .Text | safeHTML }}</a>
|
||||
|
||||
|
|
|
|||
|
|
@ -1,38 +1,68 @@
|
|||
{{- printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>" | safeHTML }}
|
||||
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
|
||||
<channel>
|
||||
<title>{{ .Site.Title }} – {{ .Title }}</title>
|
||||
<title>Hugo News</title>
|
||||
<description>Recent news about Hugo, a static site generator written in Go, optimized for speed and designed for flexibility.</description>
|
||||
<link>{{ .Permalink }}</link>
|
||||
<description>Recent Hugo news from gohugo.io</description>
|
||||
<generator>Hugo -- gohugo.io</generator>{{ with .Site.LanguageCode }}
|
||||
<language>{{.}}</language>{{end}}{{ with .Site.Author.email }}
|
||||
<managingEditor>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</managingEditor>{{end}}{{ with .Site.Author.email }}
|
||||
<webMaster>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</webMaster>{{end}}{{ with .Site.Copyright }}
|
||||
<copyright>{{.}}</copyright>{{end}}{{ if not .Date.IsZero }}
|
||||
<lastBuildDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</lastBuildDate>{{ end }}
|
||||
<image>
|
||||
<url>{{ "img/hugo.png" | absURL }}</url>
|
||||
<title>GoHugo.io</title>
|
||||
<link>{{ .Permalink }}</link>
|
||||
</image>
|
||||
{{ with .OutputFormats.Get "RSS" }}
|
||||
{{ printf "<atom:link href=%q rel=\"self\" type=%q />" .Permalink .MediaType | safeHTML }}
|
||||
{{ end }}
|
||||
{{ range first 50 (where .Site.RegularPages "Type" "in" (slice "news" "showcase")) }}
|
||||
<item>
|
||||
<title>{{ .Section | title }}: {{ .Title }}</title>
|
||||
<link>{{ .Permalink }}</link>
|
||||
<pubDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</pubDate>
|
||||
{{ with .Site.Author.email }}<author>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</author>{{end}}
|
||||
<guid>{{ .Permalink }}</guid>
|
||||
<description>
|
||||
{{ $img := (.Resources.ByType "image").GetMatch "*featured*" }}
|
||||
{{ with $img }}
|
||||
{{ $img := .Resize "640x" }}
|
||||
{{ printf "<![CDATA[<img src=\"%s\" width=\"%d\" height=\"%d\"/>]]>" $img.Permalink $img.Width $img.Height | safeHTML }}
|
||||
{{ end }}
|
||||
{{ .Content | html }}
|
||||
</description>
|
||||
</item>
|
||||
{{ end }}
|
||||
<generator>Hugo {{ hugo.Version }}</generator>
|
||||
<language>{{ or site.Language.LanguageCode site.Language.Lang }}</language>
|
||||
{{- with site.Copyright }}
|
||||
<copyright>{{ . }}</copyright>
|
||||
{{- end }}
|
||||
{{- with .OutputFormats.Get "RSS" }}
|
||||
{{ printf "<atom:link href=%q rel=\"self\" type=%q />" .Permalink .MediaType | safeHTML }}
|
||||
{{- end }}
|
||||
|
||||
{{- $news_items := slice }}
|
||||
|
||||
{{- /* Get releases from GitHub. */}}
|
||||
{{- $u := "https://api.github.com/repos/gohugoio/hugo/releases" }}
|
||||
{{- $releases := partial "utilities/get-remote-data.html" $u }}
|
||||
{{- $releases = where $releases "draft" false }}
|
||||
{{- $releases = where $releases "prerelease" false }}
|
||||
{{- range $releases | first 20 }}
|
||||
{{- $summary := printf
|
||||
"Hugo %s was released on %s. See [release notes](%s) for details."
|
||||
.tag_name
|
||||
(.published_at | time.AsTime | time.Format "2 Jan 2006")
|
||||
.html_url
|
||||
}}
|
||||
{{- $ctx := dict
|
||||
"PublishDate" (.published_at | time.AsTime)
|
||||
"Title" (printf "Release %s" .name)
|
||||
"Permalink" .html_url
|
||||
"Section" "news"
|
||||
"Summary" ($summary | $.Page.RenderString)
|
||||
}}
|
||||
{{- $news_items = $news_items | append $ctx }}
|
||||
{{- end }}
|
||||
|
||||
{{- /* Get content pages from news section. */}}
|
||||
{{- range where site.RegularPages "Section" "news" }}
|
||||
{{- $ctx := dict
|
||||
"PublishDate" .PublishDate
|
||||
"Title" .Title
|
||||
"RelPermalink" .RelPermalink
|
||||
"Section" "news"
|
||||
"Summary" .Summary
|
||||
"Params" (dict "description" .Description)
|
||||
}}
|
||||
{{- $news_items = $news_items | append $ctx }}
|
||||
{{- end }}
|
||||
{{- /* Sort, limit, and render lastBuildDate. */}}
|
||||
{{- $limit := cond (gt site.Config.Services.RSS.Limit 1) site.Config.Services.RSS.Limit 999 }}
|
||||
{{- $news_items = sort $news_items "PublishDate" "desc" | first $limit }}
|
||||
<lastBuildDate>{{ (index $news_items 0).PublishDate.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</lastBuildDate>
|
||||
|
||||
{{- /* Render items. */}}
|
||||
{{- range $news_items }}
|
||||
<item>
|
||||
<title>{{ .Title }}</title>
|
||||
<link>{{ .Permalink }}</link>
|
||||
<pubDate>{{ .PublishDate.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</pubDate>
|
||||
<guid>{{ .Permalink }}</guid>
|
||||
<description>{{ .Summary | transform.XMLEscape | safeHTML }}</description>
|
||||
</item>
|
||||
{{- end }}
|
||||
</channel>
|
||||
</rss>
|
||||
|
|
@ -18,7 +18,7 @@
|
|||
|
||||
{{/* 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 }}
|
||||
|
|
@ -55,16 +55,3 @@
|
|||
|
||||
</div>
|
||||
{{ 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 }}
|
||||
|
|
|
|||
68
docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/news/list.xml
generated
Normal file
68
docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/news/list.xml
generated
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
{{- printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>" | safeHTML }}
|
||||
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
|
||||
<channel>
|
||||
<title>Hugo News</title>
|
||||
<description>Recent news about Hugo, a static site generator written in Go, optimized for speed and designed for flexibility.</description>
|
||||
<link>{{ .Permalink }}</link>
|
||||
<generator>Hugo {{ hugo.Version }}</generator>
|
||||
<language>{{ or site.Language.LanguageCode site.Language.Lang }}</language>
|
||||
{{- with site.Copyright }}
|
||||
<copyright>{{ . }}</copyright>
|
||||
{{- end }}
|
||||
{{- with .OutputFormats.Get "RSS" }}
|
||||
{{ printf "<atom:link href=%q rel=\"self\" type=%q />" .Permalink .MediaType | safeHTML }}
|
||||
{{- end }}
|
||||
|
||||
{{- $news_items := slice }}
|
||||
|
||||
{{- /* Get releases from GitHub. */}}
|
||||
{{- $u := "https://api.github.com/repos/gohugoio/hugo/releases" }}
|
||||
{{- $releases := partial "utilities/get-remote-data.html" $u }}
|
||||
{{- $releases = where $releases "draft" false }}
|
||||
{{- $releases = where $releases "prerelease" false }}
|
||||
{{- range $releases | first 20 }}
|
||||
{{- $summary := printf
|
||||
"Hugo %s was released on %s. See [release notes](%s) for details."
|
||||
.tag_name
|
||||
(.published_at | time.AsTime | time.Format "2 Jan 2006")
|
||||
.html_url
|
||||
}}
|
||||
{{- $ctx := dict
|
||||
"PublishDate" (.published_at | time.AsTime)
|
||||
"Title" (printf "Release %s" .name)
|
||||
"Permalink" .html_url
|
||||
"Section" "news"
|
||||
"Summary" ($summary | $.Page.RenderString)
|
||||
}}
|
||||
{{- $news_items = $news_items | append $ctx }}
|
||||
{{- end }}
|
||||
|
||||
{{- /* Get content pages from news section. */}}
|
||||
{{- range .Pages }}
|
||||
{{- $ctx := dict
|
||||
"PublishDate" .PublishDate
|
||||
"Title" .Title
|
||||
"RelPermalink" .RelPermalink
|
||||
"Section" "news"
|
||||
"Summary" .Summary
|
||||
"Params" (dict "description" .Description)
|
||||
}}
|
||||
{{- $news_items = $news_items | append $ctx }}
|
||||
{{- end }}
|
||||
{{- /* Sort, limit, and render lastBuildDate. */}}
|
||||
{{- $limit := cond (gt site.Config.Services.RSS.Limit 1) site.Config.Services.RSS.Limit 999 }}
|
||||
{{- $news_items = sort $news_items "PublishDate" "desc" | first $limit }}
|
||||
<lastBuildDate>{{ (index $news_items 0).PublishDate.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</lastBuildDate>
|
||||
|
||||
{{- /* Render items. */}}
|
||||
{{- range $news_items }}
|
||||
<item>
|
||||
<title>{{ .Title }}</title>
|
||||
<link>{{ .Permalink }}</link>
|
||||
<pubDate>{{ .PublishDate.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</pubDate>
|
||||
<guid>{{ .Permalink }}</guid>
|
||||
<description>{{ .Summary | transform.XMLEscape | safeHTML }}</description>
|
||||
</item>
|
||||
{{- end }}
|
||||
</channel>
|
||||
</rss>
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
<div class="w-100 center pt5">
|
||||
<div class="w-100 w-40-l tc center">
|
||||
<img src="/images/GitHub-Mark-64px.png" alt="Github Logo" class="tc center">
|
||||
<img src="/images/Github.svg" alt="Github Logo" class="tc center">
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
|
|
|||
|
|
@ -25,26 +25,30 @@
|
|||
{{ $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 }}
|
||||
<a
|
||||
href="{{ $url }}"
|
||||
onclick="trackOutboundLink({{ printf "'%s', '%s'" $gtagID $url | safeJS }});"
|
||||
class="w-100 grow pa3{{ if .show_on_hover }}
|
||||
show-on-hover
|
||||
{{ end }}"
|
||||
style="">
|
||||
{{ with $logo }}{{ .Content | safeHTML }}{{ end }}
|
||||
</a>
|
||||
{{ else }}
|
||||
<a
|
||||
href="{{ $url }}"
|
||||
class="w-100 grow pa3{{ if .show_on_hover }}
|
||||
show-on-hover
|
||||
{{ end }}">
|
||||
{{ with $logo }}{{ .Content | safeHTML }}{{ end }}
|
||||
</a>
|
||||
{{ $gtagID := printf "Sponsor %s %s" .name $gtag | title }}
|
||||
{{ $classes := "" }}
|
||||
{{ if .show_on_hover }}
|
||||
{{ $classes = printf "%s show-on-hover" $classes }}
|
||||
{{ end }}
|
||||
{{ if $isFooter }}
|
||||
{{ $classes = printf "%s f3" $classes }}
|
||||
{{ else }}
|
||||
{{ $classes = printf "%s f1" $classes }}
|
||||
{{ end }}
|
||||
<a
|
||||
href="{{ $url }}"
|
||||
title="{{ .title | default .name }}"
|
||||
{{ if hugo.IsProduction }}
|
||||
onclick="trackOutboundLink({{ printf "'%s', '%s'" $gtagID $url | safeJS }});"
|
||||
{{ end }}
|
||||
class="w-100 grow pa3 {{ $classes }}"
|
||||
{{ with .link_attr }}{{ . | safeHTMLAttr }}{{ end }}>
|
||||
{{ with $logo }}
|
||||
{{ .Content | safeHTML }}
|
||||
{{ else }}
|
||||
{{ .name }}
|
||||
{{ end }}
|
||||
</a>
|
||||
</div>
|
||||
{{ end }}
|
||||
</div>
|
||||
|
|
|
|||
23
docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/utilities/get-remote-data.html
generated
Normal file
23
docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/utilities/get-remote-data.html
generated
Normal file
|
|
@ -0,0 +1,23 @@
|
|||
{{/*
|
||||
Parses the serialized data from the given URL and returns a map or an array.
|
||||
|
||||
Supports CSV, JSON, TOML, YAML, and XML.
|
||||
|
||||
@param {string} . The URL from which to retrieve the serialized data.
|
||||
@returns {any}
|
||||
|
||||
@example {{ partial "get-remote-data.html" "https://example.org/foo.json" }}
|
||||
*/}}
|
||||
|
||||
{{ $url := . }}
|
||||
{{ $data := dict }}
|
||||
{{ with resources.GetRemote $url }}
|
||||
{{ with .Err }}
|
||||
{{ errorf "%s" . }}
|
||||
{{ else }}
|
||||
{{ $data = .Content | transform.Unmarshal }}
|
||||
{{ end }}
|
||||
{{ else }}
|
||||
{{ errorf "Unable to get remote resource %q" $url }}
|
||||
{{ end }}
|
||||
{{ return $data }}
|
||||
36
docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/eturl.html
generated
Normal file
36
docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/eturl.html
generated
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
{{- /*
|
||||
Renders an absolute URL to the source code for an embedded template.
|
||||
|
||||
Accepts either positional or named parameters, and depends on the
|
||||
embedded_templates.toml file in the data directory.
|
||||
|
||||
@param {string} filename The embedded template's file name, excluding extension.
|
||||
|
||||
@returns template.HTML
|
||||
|
||||
@example {{% et robots.txt %}}
|
||||
@example {{% et filename=robots.txt %}}
|
||||
*/}}
|
||||
|
||||
{{- /* Get parameters. */}}
|
||||
{{- $filename := "" -}}
|
||||
{{- if .IsNamedParams -}}
|
||||
{{- $filename = .Get "filename" -}}
|
||||
{{- else -}}
|
||||
{{- $filename = .Get 0 -}}
|
||||
{{- end -}}
|
||||
|
||||
{{- /* Render. */}}
|
||||
{{- with $filename -}}
|
||||
{{- with site.Data.embedded_template_urls -}}
|
||||
{{- with index . $filename -}}
|
||||
{{- urls.JoinPath site.Data.embedded_template_urls.base_url . -}}
|
||||
{{- else -}}
|
||||
{{- errorf "The %q shortcode was unable to find a URL for the embedded template named %q. Check the name. See %s" $.Name $filename $.Position -}}
|
||||
{{- end -}}
|
||||
{{- else -}}
|
||||
{{- errorf "The %q shortcode was unable to find the embedded_template_urls data file in the site's data directory. See %s" $.Name $.Position -}}
|
||||
{{- end -}}
|
||||
{{- else -}}
|
||||
{{- errorf "The %q shortcodes requires a named or positional parameter, the file name of the embedded template, excluding its extension. See %s" .Name .Position -}}
|
||||
{{- end -}}
|
||||
|
|
@ -119,8 +119,8 @@ Renders the given image using the given filter, if any.
|
|||
{{- end }}
|
||||
|
||||
{{- $validFilters := slice
|
||||
"autoorient" "brightness" "colorbalance" "colorize" "contrast" "gamma"
|
||||
"gaussianblur" "grayscale" "hue" "invert" "none" "opacity" "overlay"
|
||||
"autoorient" "brightness" "colorbalance" "colorize" "contrast" "dither"
|
||||
"gamma" "gaussianblur" "grayscale" "hue" "invert" "none" "opacity" "overlay"
|
||||
"padding" "pixelate" "process" "saturation" "sepia" "sigmoid" "text"
|
||||
"unsharpmask"
|
||||
}}
|
||||
|
|
@ -198,6 +198,8 @@ Renders the given image using the given filter, if any.
|
|||
{{- $ctx = merge $ctx (dict "argName" "percentage" "argValue" (index $filterArgs 0) "min" -100 "max" 100) }}
|
||||
{{- template "validate-arg-value" $ctx }}
|
||||
{{- $f = images.Contrast (index $filterArgs 0) }}
|
||||
{{- else if eq $filter "dither" }}
|
||||
{{- $f = images.Dither }}
|
||||
{{- else if eq $filter "gamma" }}
|
||||
{{- $ctx = merge $ctx (dict "argsRequired" 1) }}
|
||||
{{- template "validate-arg-count" $ctx }}
|
||||
|
|
@ -354,7 +356,7 @@ Renders the given image using the given filter, if any.
|
|||
{{- if $u.IsAbs }}
|
||||
{{- with resources.GetRemote $u.String }}
|
||||
{{- with .Err }}
|
||||
{{- errorf "%s" }}
|
||||
{{- errorf "%s" . }}
|
||||
{{- else }}
|
||||
{{- /* This is a remote resource. */}}
|
||||
{{- $r = . }}
|
||||
|
|
|
|||
|
|
@ -27,9 +27,7 @@ button will be hidden if any of the following conditions is true:
|
|||
{{- 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 }}
|
||||
<button class="bg-white hover:bg-gray-100 text-gray-800 font-semibold py-2 mr2 px-4 border border-gray-400 rounded shadow">
|
||||
<a href="{{ printf "https://github.com/gohugoio/hugo/releases/tag/v%s" $version }}">New in v{{ $version }}</a>
|
||||
</button>
|
||||
<a class="dib f5 fw6 ba bw1 b--gray ph2 mt1" href="{{ printf "https://github.com/gohugoio/hugo/releases/tag/v%s" $version }}">New in v{{ $version }}</a>
|
||||
{{- end }}
|
||||
{{- else }}
|
||||
{{- errorf "The %q shortcode requires a positional parameter (version). See %s" .Name .Position }}
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 924 B |
1
docs/_vendor/github.com/gohugoio/gohugoioTheme/static/images/Github.svg
generated
Normal file
1
docs/_vendor/github.com/gohugoio/gohugoioTheme/static/images/Github.svg
generated
Normal file
|
|
@ -0,0 +1 @@
|
|||
<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 24 24"><path d="M12 0C5.374 0 0 5.373 0 12c0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23A11.5 11.5 0 0 1 12 5.803c1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576C20.566 21.797 24 17.3 24 12c0-6.627-5.373-12-12-12"/></svg>
|
||||
|
After Width: | Height: | Size: 795 B |
|
|
@ -1 +1 @@
|
|||
# github.com/gohugoio/gohugoioTheme v0.0.0-20240201183016-8e648a3b5342
|
||||
# github.com/gohugoio/gohugoioTheme v0.0.0-20240619093131-b595d5fb8c52
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 42 KiB |
|
|
@ -1,6 +1,6 @@
|
|||
[[docs]]
|
||||
identifier = 'about'
|
||||
name = 'About Hugo'
|
||||
name = 'About'
|
||||
pageRef = '/about/'
|
||||
weight = 10
|
||||
|
||||
|
|
@ -15,60 +15,60 @@ name = 'Getting started'
|
|||
weight = 30
|
||||
identifier = 'getting-started'
|
||||
pageRef = '/getting-started/'
|
||||
|
||||
[[docs]]
|
||||
name = 'Quick reference'
|
||||
weight = 40
|
||||
identifier = 'quick-reference'
|
||||
pageRef = '/quick-reference/'
|
||||
post = 'break'
|
||||
|
||||
[[docs]]
|
||||
name = 'Content management'
|
||||
weight = 40
|
||||
weight = 50
|
||||
identifier = 'content-management'
|
||||
post = 'expanded'
|
||||
pageRef = '/content-management/'
|
||||
|
||||
[[docs]]
|
||||
name = 'Templates'
|
||||
weight = 50
|
||||
weight = 60
|
||||
identifier = 'templates'
|
||||
pageRef = '/templates/'
|
||||
|
||||
[[docs]]
|
||||
name = 'Functions'
|
||||
weight = 60
|
||||
weight = 70
|
||||
identifier = 'functions'
|
||||
pageRef = '/functions/'
|
||||
|
||||
[[docs]]
|
||||
name = 'Methods'
|
||||
weight = 70
|
||||
weight = 80
|
||||
identifier = 'methods'
|
||||
pageRef = '/methods/'
|
||||
|
||||
[[docs]]
|
||||
name = 'Quick reference'
|
||||
weight = 80
|
||||
identifier = 'quick-reference'
|
||||
pageRef = '/quick-reference/'
|
||||
|
||||
[[docs]]
|
||||
name = 'Variables'
|
||||
weight = 85
|
||||
identifier = 'variables'
|
||||
pageRef = '/variables/'
|
||||
name = 'Render hooks'
|
||||
weight = 90
|
||||
identifier = 'render-hooks'
|
||||
pageRef = '/render-hooks/'
|
||||
|
||||
[[docs]]
|
||||
name = 'Hugo Modules'
|
||||
weight = 90
|
||||
weight = 100
|
||||
identifier = 'modules'
|
||||
pageRef = '/hugo-modules/'
|
||||
|
||||
[[docs]]
|
||||
name = 'Hugo Pipes'
|
||||
weight = 100
|
||||
weight = 110
|
||||
identifier = 'hugo-pipes'
|
||||
pageRef = '/hugo-pipes/'
|
||||
|
||||
[[docs]]
|
||||
name = 'CLI'
|
||||
weight = 110
|
||||
weight = 120
|
||||
post = 'break'
|
||||
identifier = 'commands'
|
||||
pageRef = '/commands/'
|
||||
|
|
@ -77,25 +77,25 @@ pageRef = '/commands/'
|
|||
|
||||
[[docs]]
|
||||
name = 'Troubleshooting'
|
||||
weight = 120
|
||||
weight = 130
|
||||
identifier = 'troubleshooting'
|
||||
pageRef = '/troubleshooting/'
|
||||
|
||||
[[docs]]
|
||||
name = 'Developer tools'
|
||||
weight = 130
|
||||
weight = 140
|
||||
identifier = 'developer-tools'
|
||||
pageRef = '/tools/'
|
||||
|
||||
[[docs]]
|
||||
name = 'Hosting and deployment'
|
||||
weight = 140
|
||||
weight = 150
|
||||
identifier = 'hosting-and-deployment'
|
||||
pageRef = '/hosting-and-deployment/'
|
||||
|
||||
[[docs]]
|
||||
name = 'Contribute'
|
||||
weight = 150
|
||||
weight = 160
|
||||
post = 'break'
|
||||
identifier = 'contribute'
|
||||
pageRef = '/contribute/'
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ features:
|
|||
- heading: Shortcodes
|
||||
image_path: /images/icon-shortcodes.svg
|
||||
tagline: Hugo's shortcodes are Markdown's hidden superpower.
|
||||
copy: We love the beautiful simplicity of markdown’s syntax, but there are times when we want more flexibility. Hugo shortcodes allow for both beauty and flexibility.
|
||||
copy: We love the beautiful simplicity of Markdown’s syntax, but there are times when we want more flexibility. Hugo shortcodes allow for both beauty and flexibility.
|
||||
|
||||
- heading: Built-in Templates
|
||||
image_path: /images/icon-built-in-templates.svg
|
||||
|
|
|
|||
|
|
@ -1,16 +1,16 @@
|
|||
---
|
||||
title: About Hugo
|
||||
linkTitle: Overview
|
||||
description: Hugo's features, roadmap, license, and motivation.
|
||||
linkTitle: In this section
|
||||
description: Learn about Hugo and its features, security model, and privacy protections.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
identifier: about-hugo-overview
|
||||
identifier: about-hugo-in-this-section
|
||||
parent: about
|
||||
weight: 10
|
||||
weight: 10
|
||||
aliases: [/about-hugo/,/docs/]
|
||||
---
|
||||
|
||||
Hugo is not your average static site generator.
|
||||
Learn about Hugo and its features, privacy protections, and security model.
|
||||
|
|
|
|||
|
|
@ -1,36 +0,0 @@
|
|||
---
|
||||
title: Benefits of static site generators
|
||||
linkTitle: Static site generators
|
||||
description: Improved performance, security and ease of use are just a few of the reasons static site generators are so appealing.
|
||||
categories: [about]
|
||||
keywords: [ssg,static,performance,security]
|
||||
menu:
|
||||
docs:
|
||||
parent: about
|
||||
weight: 40
|
||||
weight: 40
|
||||
---
|
||||
|
||||
The purpose of website generators is to render content into HTML files. Most are "dynamic site generators." That means the HTTP server---i.e., the program that sends files to the browser to be viewed---runs the generator to create a new HTML file every time an end user requests a page.
|
||||
|
||||
Over time, dynamic site generators were programmed to cache their HTML files to prevent unnecessary delays in delivering pages to end users. A cached page is a static version of a web page.
|
||||
|
||||
Hugo takes caching a step further and all HTML files are rendered on your computer. You can review the files locally before copying them to the computer hosting the HTTP server. Since the HTML files aren't generated dynamically, we say that Hugo is a *static site generator*.
|
||||
|
||||
This has many benefits. The most noticeable is performance. HTTP servers are *very* good at sending files---so good, in fact, that you can effectively serve the same number of pages with a fraction of the memory and CPU needed for a dynamic site.
|
||||
|
||||
## More on static site generators
|
||||
|
||||
* ["An Introduction to Static Site Generators", David Walsh]
|
||||
* ["Hugo vs. WordPress page load speed comparison: Hugo leaves WordPress in its dust", GettingThingsTech][hugovwordpress]
|
||||
* ["Static Site Generators", O'Reilly]
|
||||
* [StaticGen: Top Open-Source Static Site Generators (GitHub Stars)]
|
||||
* ["Top 10 Static Website Generators", Netlify blog]
|
||||
* ["The Resurgence of Static", dotCMS][dotcms]
|
||||
|
||||
["An Introduction to Static Site Generators", David Walsh]: https://davidwalsh.name/introduction-static-site-generators
|
||||
["Static Site Generators", O'Reilly]: https://github.com/gohugoio/hugoDocs/files/1242701/static-site-generators.pdf
|
||||
["Top 10 Static Website Generators", Netlify blog]: https://www.netlify.com/blog/2016/05/02/top-ten-static-website-generators/
|
||||
[hugovwordpress]: https://gettingthingstech.com/hugo-vs.-wordpress-page-load-speed-comparison-hugo-leaves-wordpress-in-its-dust/
|
||||
[StaticGen: Top Open-Source Static Site Generators (GitHub Stars)]: https://www.staticgen.com/
|
||||
[dotcms]: https://dotcms.com/blog/post/the-resurgence-of-static
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: Hugo features
|
||||
description: Hugo boasts blistering speed, robust content management, and a powerful templating language making it a great fit for all kinds of static websites.
|
||||
title: Features
|
||||
description: Hugo's rich and powerful feature set provides the framework and tools to create static sites that build in seconds, often less.
|
||||
categories: [about]
|
||||
keywords: []
|
||||
menu:
|
||||
|
|
@ -11,70 +11,126 @@ weight: 30
|
|||
toc: true
|
||||
---
|
||||
|
||||
## General
|
||||
## Framework
|
||||
|
||||
* [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]
|
||||
[Multiplatform]
|
||||
: Install Hugo's single executable on Linux, macOS, Windows, and more.
|
||||
|
||||
## Organization
|
||||
[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.
|
||||
|
||||
* 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]
|
||||
[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.
|
||||
|
||||
## 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.
|
||||
|
||||
* 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
|
||||
[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.
|
||||
|
||||
## Additional features
|
||||
[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.
|
||||
|
||||
* Integrated [Disqus] comment support
|
||||
* Integrated [Google Analytics] support
|
||||
* Automatic [RSS] creation
|
||||
* Support for [Go] HTML templates
|
||||
* [Syntax highlighting] powered by [Chroma]
|
||||
[Privacy]
|
||||
: Configure the behavior of Hugo's embedded templates and shortcodes to facilitate compliance with regional privacy regulations, including the [GDPR] and [CCPA].
|
||||
|
||||
[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/
|
||||
[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/
|
||||
|
|
|
|||
39
docs/content/en/about/introduction.md
Normal file
39
docs/content/en/about/introduction.md
Normal file
|
|
@ -0,0 +1,39 @@
|
|||
---
|
||||
title: Introduction
|
||||
description: Hugo is a static site generator written in Go, optimized for speed and designed for flexibility.
|
||||
categories: [about]
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
identifier: about-introduction
|
||||
parent: about
|
||||
weight: 20
|
||||
weight: 20
|
||||
aliases: [/about/what-is-hugo/,/about/benefits/]
|
||||
---
|
||||
|
||||
Hugo is a [static site generator] written in [Go], optimized for speed and designed for flexibility. With its advanced templating system and fast asset pipelines, Hugo renders a complete site in seconds, often less.
|
||||
|
||||
Due to its flexible framework, multilingual support, and powerful taxonomy system, Hugo is widely used to create:
|
||||
|
||||
- Corporate, government, nonprofit, education, news, event, and project sites
|
||||
- Documentation sites
|
||||
- Image portfolios
|
||||
- Landing pages
|
||||
- Business, professional, and personal blogs
|
||||
- Resumes and CVs
|
||||
|
||||
Use Hugo's embedded web server during development to instantly see changes to content, structure, behavior, and presentation. Then deploy the site to your host, or push changes to your Git provider for automated builds and deployment.
|
||||
|
||||
And with [Hugo Modules], you can share content, assets, data, translations, themes, templates, and configuration with other projects via public or private Git repositories.
|
||||
|
||||
Learn more about Hugo's [features], [privacy protections], and [security model].
|
||||
|
||||
[Go]: https://go.dev
|
||||
[Hugo Modules]: /hugo-modules/
|
||||
[static site generator]: https://en.wikipedia.org/wiki/Static_site_generator
|
||||
[features]: /about/features
|
||||
[security model]: /about/security
|
||||
[privacy protections]: /about/privacy
|
||||
|
||||
{{< youtube 0RKpf3rK57I >}}
|
||||
|
|
@ -2,12 +2,12 @@
|
|||
title: License
|
||||
description: Hugo is released under the Apache 2.0 license.
|
||||
categories: [about]
|
||||
keywords: [license,apache]
|
||||
keywords: [apache]
|
||||
menu:
|
||||
docs:
|
||||
parent: about
|
||||
weight: 70
|
||||
weight: 70
|
||||
weight: 60
|
||||
weight: 60
|
||||
---
|
||||
|
||||
## Apache License
|
||||
|
|
|
|||
|
|
@ -1,16 +1,16 @@
|
|||
---
|
||||
title: Hugo and the General Data Protection Regulation
|
||||
linkTitle: Hugo and the GDPR
|
||||
description: About how to configure your Hugo site to meet the new regulations.
|
||||
title: Privacy
|
||||
linkTitle: Privacy
|
||||
description: Configure your site to facilitate compliance with regional privacy regulations.
|
||||
categories: [about]
|
||||
keywords: ["GDPR", "Privacy", "Data Protection"]
|
||||
menu:
|
||||
docs:
|
||||
parent: about
|
||||
weight: 60
|
||||
weight: 60
|
||||
weight: 40
|
||||
weight: 40
|
||||
toc: true
|
||||
aliases: [/privacy/,/gdpr/]
|
||||
aliases: [/gdpr/,/about/hugo-and-gdpr/]
|
||||
---
|
||||
|
||||
General Data Protection Regulation ([GDPR](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation)) is a regulation in EU law on data protection and privacy for all individuals within the European Union and the European Economic Area. It became enforceable on 25 May 2018.
|
||||
|
|
@ -22,7 +22,7 @@ aliases: [/privacy/,/gdpr/]
|
|||
Note that:
|
||||
|
||||
* These settings have their defaults setting set to _off_, i.e. how it worked before Hugo `0.41`. You must do your own evaluation of your site and apply the appropriate settings.
|
||||
* These settings work with the [internal templates](/templates/internal/). Some theme may contain custom templates for embedding services like Google Analytics. In that case these options have no effect.
|
||||
* These settings work with the [embedded templates](/templates/embedded/). Some theme may contain custom templates for embedding services like Google Analytics. In that case these options have no effect.
|
||||
* We will continue this work and improve this further in future Hugo versions.
|
||||
|
||||
## All privacy settings
|
||||
|
|
@ -36,8 +36,6 @@ disable = false
|
|||
[privacy.googleAnalytics]
|
||||
disable = false
|
||||
respectDoNotTrack = false
|
||||
anonymizeIP = false
|
||||
useSessionStorage = false
|
||||
[privacy.instagram]
|
||||
disable = false
|
||||
simple = false
|
||||
|
|
@ -78,19 +76,9 @@ disable = true
|
|||
|
||||
### GoogleAnalytics
|
||||
|
||||
anonymizeIP
|
||||
: Enabling this will make it so the users' IP addresses are anonymized within Google Analytics.
|
||||
|
||||
respectDoNotTrack
|
||||
: Enabling this will make the GA templates respect the "Do Not Track" HTTP header.
|
||||
|
||||
useSessionStorage
|
||||
: Enabling this will disable the use of Cookies and use Session Storage to Store the GA Client ID.
|
||||
|
||||
{{% note %}}
|
||||
`useSessionStorage` is not supported when using Google Analytics v4 (gtag.js).
|
||||
{{% /note %}}
|
||||
|
||||
### Instagram
|
||||
|
||||
simple
|
||||
|
|
@ -1,5 +1,6 @@
|
|||
---
|
||||
title: Hugo's security model
|
||||
title: Security model
|
||||
linkTitle: Security
|
||||
description: A summary of Hugo's security model.
|
||||
categories: [about]
|
||||
keywords: [security,privacy]
|
||||
|
|
@ -9,7 +10,7 @@ menu:
|
|||
weight: 50
|
||||
weight: 50
|
||||
toc: true
|
||||
aliases: [/security/]
|
||||
aliases: [/about/security-model/]
|
||||
---
|
||||
|
||||
## Runtime security
|
||||
|
|
@ -21,9 +22,8 @@ But when developing and building your site, the runtime is the `hugo` executable
|
|||
**Hugo's main approach is that of sandboxing and a security policy with strict defaults:**
|
||||
|
||||
* Hugo has a virtual file system and only the main project (not third-party components) is allowed to mount directories or files outside the project root.
|
||||
* Only the main project can walk symbolic links.
|
||||
* User-defined components have read-only access to the filesystem.
|
||||
* We shell out to some external binaries to support [Asciidoctor](/content-management/formats/#list-of-content-formats) and similar, but those binaries and their flags are predefined and disabled by default (see [Security Policy](#security-policy)). General functions to run arbitrary external OS commands have been [discussed](https://github.com/gohugoio/hugo/issues/796), but not implemented because of security concerns.
|
||||
* We shell out to some external binaries to support [Asciidoctor](/content-management/formats/#formats) and similar, but those binaries and their flags are predefined and disabled by default (see [Security Policy](#security-policy)). General functions to run arbitrary external OS commands have been [discussed](https://github.com/gohugoio/hugo/issues/796), but not implemented because of security concerns.
|
||||
|
||||
## Security policy
|
||||
|
||||
|
|
@ -33,7 +33,16 @@ The default configuration is listed below. Any build using features not in the a
|
|||
|
||||
{{< code-toggle config=security />}}
|
||||
|
||||
Note that these and other configuration settings in Hugo can be overridden by the OS environment. If you want to block all remote HTTP fetching of data:
|
||||
By default, Hugo permits the [`resources.GetRemote`] function to download files with media types corresponding to an internal allow list. To add media types to the allow list:
|
||||
|
||||
[`resources.GetRemote`]: /functions/resources/getremote
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[security.http]
|
||||
mediaTypes = ['^image/avif$']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Note that these and other configuration settings in Hugo can be overridden by the OS environment. For example, if you want to block all remote HTTP fetching of data:
|
||||
|
||||
```txt
|
||||
HUGO_SECURITY_HTTP_URLS=none hugo
|
||||
|
|
@ -1,57 +0,0 @@
|
|||
---
|
||||
title: What is Hugo
|
||||
description: Hugo is a fast and modern static site generator written in Go, and designed to make website creation fun again.
|
||||
categories: [about]
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: about
|
||||
weight: 20
|
||||
weight: 20
|
||||
toc: true
|
||||
aliases: [/overview/introduction/,/about/why-i-built-hugo/]
|
||||
---
|
||||
|
||||
Hugo is a general-purpose website framework. Technically speaking, Hugo is a [static site generator]. Unlike systems that dynamically build a page with each visitor request, Hugo builds pages when you create or update your content. Since websites are viewed far more often than they are edited, Hugo is designed to provide an optimal viewing experience for your website's end users and an ideal writing experience for website authors.
|
||||
|
||||
Websites built with Hugo are extremely fast and secure. Hugo sites can be hosted anywhere, including [Netlify], [Heroku], [GoDaddy], [DreamHost], [GitHub Pages], [GitLab Pages], [Surge], [Firebase], [Google Cloud Storage], [Amazon S3], [Rackspace], [Azure], and [CloudFront] and work well with CDNs. Hugo sites run without the need for a database or dependencies on expensive runtimes like Ruby, Python, or PHP.
|
||||
|
||||
We think of Hugo as the ideal website creation tool with nearly instant build times, able to rebuild whenever a change is made.
|
||||
|
||||
## How fast is Hugo?
|
||||
|
||||
{{< youtube "CdiDYZ51a2o" >}}
|
||||
|
||||
## What does Hugo do?
|
||||
|
||||
In technical terms, Hugo takes a source directory of files and templates and uses these as input to create a complete website.
|
||||
|
||||
## Who should use Hugo?
|
||||
|
||||
Hugo is for people that prefer writing in a text editor over a browser.
|
||||
|
||||
Hugo is for people who want to hand code their own website without worrying about setting up complicated runtimes, dependencies and databases.
|
||||
|
||||
Hugo is for people building a blog, a company site, a portfolio site, documentation, a single landing page, or a website with thousands of pages.
|
||||
|
||||
[@spf13]: https://twitter.com/spf13
|
||||
[Amazon S3]: https://aws.amazon.com/s3/
|
||||
[Azure]: https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website
|
||||
[CloudFront]: https://aws.amazon.com/cloudfront/
|
||||
[DreamHost]: https://www.dreamhost.com/
|
||||
[Firebase]: https://firebase.google.com/docs/hosting/
|
||||
[GitHub Pages]: https://pages.github.com/
|
||||
[GitLab Pages]: https://about.gitlab.com/features/pages/
|
||||
[Go language]: https://go.dev/
|
||||
[GoDaddy]: https://www.godaddy.com/
|
||||
[Google Cloud Storage]: https://cloud.google.com/storage/
|
||||
[Heroku]: https://www.heroku.com/
|
||||
[Jekyll]: https://jekyllrb.com/
|
||||
[Middleman]: https://middlemanapp.com/
|
||||
[Nanoc]: https://nanoc.ws/
|
||||
[Netlify]: https://netlify.com
|
||||
[Rackspace]: https://www.rackspace.com/cloud/files
|
||||
[Surge]: https://surge.sh
|
||||
[contributing to it]: https://github.com/gohugoio/hugo
|
||||
[rackspace]: https://www.rackspace.com/openstack/public/files
|
||||
[static site generator]: /about/benefits/
|
||||
|
|
@ -57,7 +57,7 @@ hugo [flags]
|
|||
--printUnusedTemplates print warnings on unused templates.
|
||||
--quiet build in quiet mode
|
||||
--renderSegments strings named segments to render (configured in the segments config)
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--templateMetrics display metrics about template executions
|
||||
--templateMetricsHints calculate some improvement hints when combined with --templateMetrics
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ See each sub-command's help for details on how to use the generated script.
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -54,7 +54,7 @@ hugo completion bash
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -45,7 +45,7 @@ hugo completion fish [flags]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -42,7 +42,7 @@ hugo completion powershell [flags]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -56,7 +56,7 @@ hugo completion zsh [flags]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@ hugo config [command] [flags]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -34,7 +34,7 @@ hugo config mounts [flags] [args]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ See convert's subcommands toJSON, toTOML and toYAML for more information.
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -35,7 +35,7 @@ hugo convert toJSON [flags] [args]
|
|||
--logLevel string log level (debug|info|warn|error)
|
||||
-o, --output string filesystem path to write files to
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
--unsafe enable less safe operations, please backup first
|
||||
|
|
|
|||
|
|
@ -35,7 +35,7 @@ hugo convert toTOML [flags] [args]
|
|||
--logLevel string log level (debug|info|warn|error)
|
||||
-o, --output string filesystem path to write files to
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
--unsafe enable less safe operations, please backup first
|
||||
|
|
|
|||
|
|
@ -35,7 +35,7 @@ hugo convert toYAML [flags] [args]
|
|||
--logLevel string log level (debug|info|warn|error)
|
||||
-o, --output string filesystem path to write files to
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
--unsafe enable less safe operations, please backup first
|
||||
|
|
|
|||
|
|
@ -44,7 +44,7 @@ hugo deploy [flags] [args]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ hugo env [flags] [args]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -25,7 +25,7 @@ A collection of several useful generators.
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ hugo gen chromastyles [flags] [args]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ hugo gen doc [flags] [args]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -36,7 +36,7 @@ hugo gen man [flags] [args]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ Import requires a subcommand, e.g. `hugo import jekyll jekyll_root_path target_p
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -36,7 +36,7 @@ hugo import jekyll [flags] [args]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ List requires a subcommand, e.g. hugo list drafts
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
@ -40,8 +40,9 @@ List requires a subcommand, e.g. hugo list drafts
|
|||
### SEE ALSO
|
||||
|
||||
* [hugo](/commands/hugo/) - hugo builds your site
|
||||
* [hugo list all](/commands/hugo_list_all/) - List all posts
|
||||
* [hugo list drafts](/commands/hugo_list_drafts/) - List all drafts
|
||||
* [hugo list expired](/commands/hugo_list_expired/) - List all posts already expired
|
||||
* [hugo list future](/commands/hugo_list_future/) - List all posts dated in the future
|
||||
* [hugo list all](/commands/hugo_list_all/) - List all content
|
||||
* [hugo list drafts](/commands/hugo_list_drafts/) - List draft content
|
||||
* [hugo list expired](/commands/hugo_list_expired/) - List expired content
|
||||
* [hugo list future](/commands/hugo_list_future/) - List future content
|
||||
* [hugo list published](/commands/hugo_list_published/) - List published content
|
||||
|
||||
|
|
|
|||
|
|
@ -5,11 +5,11 @@ url: /commands/hugo_list_all/
|
|||
---
|
||||
## hugo list all
|
||||
|
||||
List all posts
|
||||
List all content
|
||||
|
||||
### Synopsis
|
||||
|
||||
List all of the posts in your content directory, include drafts, future and expired pages.
|
||||
List all content including draft, future, and expired.
|
||||
|
||||
```
|
||||
hugo list all [flags] [args]
|
||||
|
|
@ -33,7 +33,7 @@ hugo list all [flags] [args]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -5,11 +5,11 @@ url: /commands/hugo_list_drafts/
|
|||
---
|
||||
## hugo list drafts
|
||||
|
||||
List all drafts
|
||||
List draft content
|
||||
|
||||
### Synopsis
|
||||
|
||||
List all of the drafts in your content directory.
|
||||
List draft content.
|
||||
|
||||
```
|
||||
hugo list drafts [flags] [args]
|
||||
|
|
@ -33,7 +33,7 @@ hugo list drafts [flags] [args]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -5,11 +5,11 @@ url: /commands/hugo_list_expired/
|
|||
---
|
||||
## hugo list expired
|
||||
|
||||
List all posts already expired
|
||||
List expired content
|
||||
|
||||
### Synopsis
|
||||
|
||||
List all of the posts in your content directory which has already expired.
|
||||
List content with a past expiration date.
|
||||
|
||||
```
|
||||
hugo list expired [flags] [args]
|
||||
|
|
@ -33,7 +33,7 @@ hugo list expired [flags] [args]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -5,11 +5,11 @@ url: /commands/hugo_list_future/
|
|||
---
|
||||
## hugo list future
|
||||
|
||||
List all posts dated in the future
|
||||
List future content
|
||||
|
||||
### Synopsis
|
||||
|
||||
List all of the posts in your content directory which will be posted in the future.
|
||||
List content with a future publication date.
|
||||
|
||||
```
|
||||
hugo list future [flags] [args]
|
||||
|
|
@ -33,7 +33,7 @@ hugo list future [flags] [args]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
45
docs/content/en/commands/hugo_list_published.md
Normal file
45
docs/content/en/commands/hugo_list_published.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
---
|
||||
title: "hugo list published"
|
||||
slug: hugo_list_published
|
||||
url: /commands/hugo_list_published/
|
||||
---
|
||||
## hugo list published
|
||||
|
||||
List published content
|
||||
|
||||
### Synopsis
|
||||
|
||||
List content that is not draft, future, or expired.
|
||||
|
||||
```
|
||||
hugo list published [flags] [args]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-h, --help help for published
|
||||
```
|
||||
|
||||
### Options inherited from parent commands
|
||||
|
||||
```
|
||||
--clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
|
||||
--config string config file (default is hugo.yaml|json|toml)
|
||||
--configDir string config dir (default "config")
|
||||
--debug debug output
|
||||
-d, --destination string filesystem path to write files to
|
||||
-e, --environment string build environment
|
||||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
```
|
||||
|
||||
### SEE ALSO
|
||||
|
||||
* [hugo list](/commands/hugo_list/) - Listing out various types of content
|
||||
|
||||
|
|
@ -40,7 +40,7 @@ See https://gohugo.io/hugo-modules/ for more information.
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@ hugo mod clean [flags] [args]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -64,7 +64,7 @@ hugo mod get [flags] [args]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -41,7 +41,7 @@ hugo mod graph [flags] [args]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -45,7 +45,7 @@ hugo mod init [flags] [args]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ hugo mod npm [command] [flags]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -48,7 +48,7 @@ hugo mod npm pack [flags] [args]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -34,7 +34,7 @@ hugo mod tidy [flags] [args]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@ hugo mod vendor [flags] [args]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ hugo mod verify [flags] [args]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -36,7 +36,7 @@ Ensure you run this within the root directory of your site.
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -48,7 +48,7 @@ hugo new content [path] [flags]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -37,7 +37,7 @@ hugo new site [path] [flags]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -36,7 +36,7 @@ hugo new theme [name] [flags]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -49,7 +49,7 @@ hugo server [command] [flags]
|
|||
-l, --layoutDir string filesystem path to layout directory
|
||||
--liveReloadPort int port for live reloading (i.e. 443 in HTTPS proxy situations) (default -1)
|
||||
--minify minify any supported output format (HTML, XML etc.)
|
||||
--navigateToChanged navigate to changed content file on live browser reload
|
||||
-N, --navigateToChanged navigate to changed content file on live browser reload
|
||||
--noBuildLock don't create .hugo_build.lock file
|
||||
--noChmod don't sync permission mode of files
|
||||
--noHTTPCache prevent HTTP caching
|
||||
|
|
@ -86,7 +86,7 @@ hugo server [command] [flags]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ hugo server trust [flags] [args]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ hugo version [flags] [args]
|
|||
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
|
||||
--logLevel string log level (debug|info|warn|error)
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (mostly useful when running the server)
|
||||
-M, --renderToMemory render to memory (mostly useful when running the server)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--themesDir string filesystem path to themes directory
|
||||
-v, --verbose verbose output
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ cascade:
|
|||
---
|
||||
|
||||
<!--
|
||||
Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
|
||||
Include the rendered content using the "include" shortcode.
|
||||
-->
|
||||
|
|
|
|||
|
|
@ -1,12 +1,12 @@
|
|||
---
|
||||
title: Content management
|
||||
linkTitle: Overview
|
||||
linkTitle: In this section
|
||||
description: Hugo makes managing large static sites easy with support for archetypes, content types, menus, cross references, summaries, and more.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
identifier: content-management-overview
|
||||
identifier: content-management-in-this-section
|
||||
parent: content-management
|
||||
weight: 10
|
||||
weight: 10
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ aliases: [/content/archetypes/]
|
|||
|
||||
## Overview
|
||||
|
||||
A content file consists of [front matter] and markup. The markup is typically markdown, but Hugo also supports other [content formats]. Front matter can be TOML, YAML, or JSON.
|
||||
A content file consists of [front matter] and markup. The markup is typically Markdown, but Hugo also supports other [content formats]. Front matter can be TOML, YAML, or JSON.
|
||||
|
||||
The `hugo new content` command creates a new file in the `content` directory, using an archetype as a template. This is the default archetype:
|
||||
|
||||
|
|
@ -70,14 +70,33 @@ If none of these exists, Hugo uses a built-in default archetype.
|
|||
|
||||
You can use any [template function] within an archetype. As shown above, the default archetype uses the [`replace`](/functions/strings/replace) function to replace hyphens with spaces when populating the title in front matter.
|
||||
|
||||
Archetypes receive the following objects and values in [context]:
|
||||
Archetypes receive the following [context]:
|
||||
|
||||
- `.Date`
|
||||
- `.Type`
|
||||
- `.Site` (see [details](/variables/site/))
|
||||
- `.File` (see [details](/variables/file/))
|
||||
Date
|
||||
: (`string`) The current date and time, formatted in compliance with RFC3339.
|
||||
|
||||
As shown above, the default archetype passes `.File.ContentBaseName` as the argument to the `replace` function when populating the title in front matter.
|
||||
File
|
||||
: (`hugolib.fileInfo`) Returns file information for the current page. See [details](/methods/page/file).
|
||||
|
||||
Type
|
||||
: (`string`) The [content type] inferred from the top-level directory name, or as specified by the `--kind` flag passed to the `hugo new content` command.
|
||||
|
||||
[content type]: /getting-started/glossary#content-type
|
||||
|
||||
Site
|
||||
: (`page.Site`) The current site object. See [details](/methods/site/).
|
||||
|
||||
## Alternate date format
|
||||
|
||||
To insert date and time with an alternate format, use the [`time.Now`] function:
|
||||
|
||||
[`time.Now`]: /functions/time/now/
|
||||
|
||||
{{< code-toggle file=archetypes/default.md fm=true >}}
|
||||
title = '{{ replace .File.ContentBaseName `-` ` ` | title }}'
|
||||
date = '{{ time.Now.Format "2006-01-02" }}'
|
||||
draft = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## Include content
|
||||
|
||||
|
|
|
|||
|
|
@ -12,10 +12,10 @@ toc: true
|
|||
aliases: [/content/build-options/]
|
||||
---
|
||||
|
||||
Build options are stored in a reserved front matter object named `_build` with these defaults:
|
||||
Build options are stored in a reserved front matter object named `build` with these defaults:
|
||||
|
||||
{{< code-toggle file=content/example/index.md fm=true >}}
|
||||
[_build]
|
||||
[build]
|
||||
list = 'always'
|
||||
publishResources = true
|
||||
render = 'always'
|
||||
|
|
@ -55,17 +55,17 @@ render
|
|||
- `never`
|
||||
: Never render the page to disk, and exclude it from all page collections.
|
||||
|
||||
[page bundles]: content-management/page-bundles
|
||||
[page resources]: /content-management/page-resources
|
||||
[`Permalink`]: /methods/resource/permalink
|
||||
[`RelPermalink`]: /methods/resource/relpermalink
|
||||
[`Publish`]: /methods/resource/publish
|
||||
[page bundles]: /content-management/page-bundles/
|
||||
[page resources]: /content-management/page-resources/
|
||||
[`Permalink`]: /methods/resource/permalink/
|
||||
[`RelPermalink`]: /methods/resource/relpermalink/
|
||||
[`Publish`]: /methods/resource/publish/
|
||||
|
||||
{{% note %}}
|
||||
Any page, regardless of its build options, will always be available by using the [`.Page.GetPage`] or [`.Site.GetPage`] method.
|
||||
|
||||
[`.Page.GetPage`]: /methods/page/getpage
|
||||
[`.Site.GetPage`]: /methods/site/getpage
|
||||
[`.Page.GetPage`]: /methods/page/getpage/
|
||||
[`.Site.GetPage`]: /methods/site/getpage/
|
||||
{{% /note %}}
|
||||
|
||||
## Example -- headless page
|
||||
|
|
@ -85,7 +85,7 @@ Set the build options in front matter:
|
|||
|
||||
{{< code-toggle file=content/headless/index.md fm=true >}}
|
||||
title = 'Headless page'
|
||||
[_build]
|
||||
[build]
|
||||
list = 'never'
|
||||
publishResources = false
|
||||
render = 'never'
|
||||
|
|
@ -121,7 +121,7 @@ In the example above, note that:
|
|||
|
||||
Create a unpublished section whose content and resources can be included in other pages.
|
||||
|
||||
[branch bundle]: /content-management/page-bundles
|
||||
[branch bundle]: /content-management/page-bundles/
|
||||
|
||||
```text
|
||||
content/
|
||||
|
|
@ -143,7 +143,7 @@ Set the build options in front matter, using the `cascade` keyword to "cascade"
|
|||
{{< code-toggle file=content/headless/_index.md fm=true >}}
|
||||
title = 'Headless section'
|
||||
[[cascade]]
|
||||
[cascade._build]
|
||||
[cascade.build]
|
||||
list = 'local'
|
||||
publishResources = false
|
||||
render = 'never'
|
||||
|
|
@ -201,10 +201,10 @@ Set the build options in front matter, using the `cascade` keyword to "cascade"
|
|||
|
||||
{{< code-toggle file=content/glossary/_index.md fm=true >}}
|
||||
title = 'Glossary'
|
||||
[_build]
|
||||
[build]
|
||||
render = 'always'
|
||||
[[cascade]]
|
||||
[cascade._build]
|
||||
[cascade.build]
|
||||
list = 'local'
|
||||
publishResources = false
|
||||
render = 'never'
|
||||
|
|
@ -247,7 +247,7 @@ Set the build options in front matter:
|
|||
|
||||
{{< code-toggle file=content/books/_index.md fm=true >}}
|
||||
title = 'Books'
|
||||
[_build]
|
||||
[build]
|
||||
render = 'never'
|
||||
list = 'never'
|
||||
{{< /code-toggle >}}
|
||||
|
|
@ -294,7 +294,7 @@ Set the build options in front matter, using the `cascade` keyword to "cascade"
|
|||
{{< code-toggle file=content/internal/_index.md >}}
|
||||
title = 'Internal'
|
||||
[[cascade]]
|
||||
[cascade._build]
|
||||
[cascade.build]
|
||||
render = 'never'
|
||||
list = 'never'
|
||||
[cascade._target]
|
||||
|
|
|
|||
|
|
@ -37,7 +37,7 @@ For many websites, this is enough configuration. However, you also have the opti
|
|||
|
||||
### Render Hugo's built-in Disqus partial template
|
||||
|
||||
Disqus has its own [internal template](/templates/internal/#disqus) available, to render it add the following code where you want comments to appear:
|
||||
Disqus has its own [internal template](/templates/embedded/#disqus) available, to render it add the following code where you want comments to appear:
|
||||
|
||||
```go-html-template
|
||||
{{ template "_internal/disqus.html" . }}
|
||||
|
|
@ -45,25 +45,30 @@ Disqus has its own [internal template](/templates/internal/#disqus) available, t
|
|||
|
||||
## Alternatives
|
||||
|
||||
These are some alternatives to Disqus:
|
||||
Commercial commenting systems:
|
||||
|
||||
* [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)
|
||||
- [Emote](https://emote.com/)
|
||||
- [Graph Comment](https://graphcomment.com/)
|
||||
- [Hyvor Talk](https://talk.hyvor.com/)
|
||||
- [IntenseDebate](https://intensedebate.com/)
|
||||
- [ReplyBox](https://getreplybox.com/)
|
||||
|
||||
Open-source commenting systems:
|
||||
|
||||
- [Cactus Comments](https://cactus.chat/docs/integrations/hugo/)
|
||||
- [Comentario](https://gitlab.com/comentario/comentario/)
|
||||
- [Comma](https://github.com/Dieterbe/comma/)
|
||||
- [Commento](https://commento.io/)
|
||||
- [Discourse](https://meta.discourse.org/t/embed-discourse-comments-on-another-website-via-javascript/31963)
|
||||
- [Giscus](https://giscus.app/)
|
||||
- [Isso](https://isso-comments.de/)
|
||||
- [Remark42](https://remark42.com/)
|
||||
- [Staticman](https://staticman.net/)
|
||||
- [Talkyard](https://blog-comments.talkyard.io/)
|
||||
- [Utterances](https://utteranc.es/)
|
||||
|
||||
[configuration]: /getting-started/configuration/
|
||||
[disquspartial]: /templates/internal/#disqus
|
||||
[disquspartial]: /templates/embedded/#disqus
|
||||
[disqussetup]: https://disqus.com/profile/signup/
|
||||
[forum]: https://discourse.gohugo.io
|
||||
[front matter]: /content-management/front-matter/
|
||||
|
|
@ -71,4 +76,3 @@ These are some alternatives to Disqus:
|
|||
[issotutorial]: https://stiobhart.net/2017-02-24-isso-comments/
|
||||
[partials]: /templates/partials/
|
||||
[MongoDB]: https://www.mongodb.com/
|
||||
[tweet]: https://twitter.com/spf13
|
||||
|
|
|
|||
355
docs/content/en/content-management/content-adapters.md
Normal file
355
docs/content/en/content-management/content-adapters.md
Normal file
|
|
@ -0,0 +1,355 @@
|
|||
---
|
||||
title: Content adapters
|
||||
description: Create content adapters to dynamically add content when building your site.
|
||||
categories: [content management]
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: content-management
|
||||
weight: 290
|
||||
weight: 290
|
||||
toc: true
|
||||
---
|
||||
|
||||
{{< new-in 0.126.0 >}}
|
||||
|
||||
## Overview
|
||||
|
||||
A content adapter is a template that dynamically creates pages when building a site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML.
|
||||
|
||||
Unlike templates that reside in the layouts directory, content adapters reside in the content directory, no more than one per directory per language. When a content adapter creates a page, the page's [logical path] will be relative to the content adapter.
|
||||
|
||||
```text
|
||||
content/
|
||||
├── articles/
|
||||
│ ├── _index.md
|
||||
│ ├── article-1.md
|
||||
│ └── article-2.md
|
||||
├── books/
|
||||
│ ├── _content.gotmpl <-- content adapter
|
||||
│ └── _index.md
|
||||
└── films/
|
||||
├── _content.gotmpl <-- content adapter
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
Each content adapter is named _content.gotmpl and uses the same [syntax] as templates in the layouts directory. You can use any of the [template functions] within a content adapter, as well as the methods described below.
|
||||
|
||||
## Methods
|
||||
|
||||
Use these methods within a content adapter.
|
||||
|
||||
###### AddPage
|
||||
|
||||
Adds a page to the site.
|
||||
|
||||
{{< code file=content/books/_content.gotmpl >}}
|
||||
{{ $content := dict
|
||||
"mediaType" "text/markdown"
|
||||
"value" "The _Hunchback of Notre Dame_ was written by Victor Hugo."
|
||||
}}
|
||||
{{ $page := dict
|
||||
"content" $content
|
||||
"kind" "page"
|
||||
"path" "the-hunchback-of-notre-dame"
|
||||
"title" "The Hunchback of Notre Dame"
|
||||
}}
|
||||
{{ .AddPage $page }}
|
||||
{{< /code >}}
|
||||
|
||||
###### AddResource
|
||||
|
||||
Adds a page resource to the site.
|
||||
|
||||
{{< code file=content/books/_content.gotmpl >}}
|
||||
{{ with resources.Get "images/a.jpg" }}
|
||||
{{ $content := dict
|
||||
"mediaType" .MediaType.Type
|
||||
"value" .
|
||||
}}
|
||||
{{ $resource := dict
|
||||
"content" $content
|
||||
"path" "the-hunchback-of-notre-dame/cover.jpg"
|
||||
}}
|
||||
{{ $.AddResource $resource }}
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
Then retrieve the new page resource with something like:
|
||||
|
||||
{{< code file=layouts/_default/single.html >}}
|
||||
{{ with .Resources.Get "cover.jpg" }}
|
||||
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
###### Site
|
||||
|
||||
Returns the `Site` to which the pages will be added.
|
||||
|
||||
{{< code file=content/books/_content.gotmpl >}}
|
||||
{{ .Site.Title }}
|
||||
{{< /code >}}
|
||||
|
||||
###### Store
|
||||
|
||||
Returns a persistent “scratch pad” to store and manipulate data. The main use case for this is to transfer values between executions when [EnableAllLanguages](#enablealllanguages) is set. See [examples](/methods/page/store/).
|
||||
|
||||
{{< code file=content/books/_content.gotmpl >}}
|
||||
{{ .Store.Set "key" "value" }}
|
||||
{{ .Store.Get "key" }}
|
||||
{{< /code >}}
|
||||
|
||||
###### EnableAllLanguages
|
||||
|
||||
By default, Hugo executes the content adapter for the language defined by the _content.gotmpl file . Use this method to activate the content adapter for all languages.
|
||||
|
||||
{{< code file=content/books/_content.gotmpl >}}
|
||||
{{ .EnableAllLanguages }}
|
||||
{{ $content := dict
|
||||
"mediaType" "text/markdown"
|
||||
"value" "The _Hunchback of Notre Dame_ was written by Victor Hugo."
|
||||
}}
|
||||
{{ $page := dict
|
||||
"content" $content
|
||||
"kind" "page"
|
||||
"path" "the-hunchback-of-notre-dame"
|
||||
"title" "The Hunchback of Notre Dame"
|
||||
}}
|
||||
{{ .AddPage $page }}
|
||||
{{< /code >}}
|
||||
|
||||
## Page map
|
||||
|
||||
Set any [front matter field] in the map passed to the [`AddPage`](#addpage) method, excluding `markup`. Instead of setting the `markup` field, specify the `content.mediaType` as described below.
|
||||
|
||||
This table describes the fields most commonly passed to the `AddPage` method.
|
||||
|
||||
Key|Descripion|Required
|
||||
:--|:--|:-:
|
||||
`content.mediaType`|The content [media type]. Default is `text/markdown`. See [content formats] for examples.|
|
||||
`content.value`|The content value as a string.|
|
||||
`dates.date`|The page creation date as a `time.Time` value.|
|
||||
`dates.expiryDate`|The page expiry date as a `time.Time` value.|
|
||||
`dates.lastmod`|The page last modification date as a `time.Time` value.|
|
||||
`dates.publishDate`|The page publication date as a `time.Time` value.|
|
||||
`kind`|The [page kind]. Default is `page`.|
|
||||
`params`|A map of page parameters.|
|
||||
`path`|The page's [logical path] relative to the content adapter. Do not include a leading slash or file extension.|:heavy_check_mark:
|
||||
`title`|The page title.|
|
||||
|
||||
{{% note %}}
|
||||
While `path` is the only required field, we recommend setting `title` as well.
|
||||
|
||||
When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C` produces a logical path of `/section/a-b-c`.
|
||||
{{% /note %}}
|
||||
|
||||
## Resource map
|
||||
|
||||
Construct the map passed to the [`AddResource`](#addresource) method using the fields below.
|
||||
|
||||
Key|Descripion|Required
|
||||
:--|:--|:-:
|
||||
`content.mediaType`|The content [media type].|:heavy_check_mark:
|
||||
`content.value`|The content value as a string or resource.|:heavy_check_mark:
|
||||
`name`|The resource name.|
|
||||
`params`|A map of resource parameters.|
|
||||
`path`|The resources's [logical path] relative to the content adapter. Do not include a leading slash.|:heavy_check_mark:
|
||||
`title`|The resource title.|
|
||||
|
||||
{{% note %}}
|
||||
If the `content.value` is a string Hugo creates a new resource. If the `content.value` is a resource, Hugo obtains the value from the existing resource.
|
||||
|
||||
When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C/cover.jpg` produces a logical path of `/section/a-b-c/cover.jpg`.
|
||||
{{% /note %}}
|
||||
|
||||
## Example
|
||||
|
||||
Create pages from remote data, where each page represents a book review.
|
||||
|
||||
Step 1
|
||||
: Create the content structure.
|
||||
|
||||
```text
|
||||
content/
|
||||
└── books/
|
||||
├── _content.gotmpl <-- content adapter
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
Step 2
|
||||
: Inspect the remote data to determine how to map key-value pairs to front matter fields.
|
||||
|
||||
: <https://gohugo.io/shared/examples/data/books.json>
|
||||
|
||||
Step 3
|
||||
: Create the content adapter.
|
||||
|
||||
{{< code file=content/books/_content.gotmpl copy=true >}}
|
||||
{{/* Get remote data. */}}
|
||||
{{ $data := dict }}
|
||||
{{ $url := "https://gohugo.io/shared/examples/data/books.json" }}
|
||||
{{ with resources.GetRemote $url }}
|
||||
{{ with .Err }}
|
||||
{{ errorf "Unable to get remote resource %s: %s" $url . }}
|
||||
{{ else }}
|
||||
{{ $data = . | transform.Unmarshal }}
|
||||
{{ end }}
|
||||
{{ else }}
|
||||
{{ errorf "Unable to get remote resource %s" $url }}
|
||||
{{ end }}
|
||||
|
||||
{{/* Add pages and page resources. */}}
|
||||
{{ range $data }}
|
||||
|
||||
{{/* Add page. */}}
|
||||
{{ $content := dict "mediaType" "text/markdown" "value" .summary }}
|
||||
{{ $dates := dict "date" (time.AsTime .date) }}
|
||||
{{ $params := dict "author" .author "isbn" .isbn "rating" .rating "tags" .tags }}
|
||||
{{ $page := dict
|
||||
"content" $content
|
||||
"dates" $dates
|
||||
"kind" "page"
|
||||
"params" $params
|
||||
"path" .title
|
||||
"title" .title
|
||||
}}
|
||||
{{ $.AddPage $page }}
|
||||
|
||||
{{/* Add page resource. */}}
|
||||
{{ $item := . }}
|
||||
{{ with $url := $item.cover }}
|
||||
{{ with resources.GetRemote $url }}
|
||||
{{ with .Err }}
|
||||
{{ errorf "Unable to get remote resource %s: %s" $url . }}
|
||||
{{ else }}
|
||||
{{ $content := dict "mediaType" .MediaType.Type "value" .Content }}
|
||||
{{ $params := dict "alt" $item.title }}
|
||||
{{ $resource := dict
|
||||
"content" $content
|
||||
"params" $params
|
||||
"path" (printf "%s/cover.%s" $item.title .MediaType.SubType)
|
||||
}}
|
||||
{{ $.AddResource $resource }}
|
||||
{{ end }}
|
||||
{{ else }}
|
||||
{{ errorf "Unable to get remote resource %s" $url }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
Step 4
|
||||
: Create a single page template to render each book review.
|
||||
|
||||
{{< code file=layouts/books/single.html copy=true >}}
|
||||
{{ define "main" }}
|
||||
<h1>{{ .Title }}</h1>
|
||||
|
||||
{{ with .Resources.GetMatch "cover.*" }}
|
||||
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="{{ .Params.alt }}">
|
||||
{{ end }}
|
||||
|
||||
<p>Author: {{ .Params.author }}</p>
|
||||
|
||||
<p>
|
||||
ISBN: {{ .Params.isbn }}<br>
|
||||
Rating: {{ .Params.rating }}<br>
|
||||
Review date: {{ .Date | time.Format ":date_long" }}
|
||||
</p>
|
||||
|
||||
{{ with .GetTerms "tags" }}
|
||||
<p>Tags:</p>
|
||||
<ul>
|
||||
{{ range . }}
|
||||
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
|
||||
{{ .Content }}
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
## Multilingual sites
|
||||
|
||||
With multilingual sites you can:
|
||||
|
||||
1. Create one content adapter for all languages using the [`EnableAllLanguages`](#enablealllanguages) method as described above.
|
||||
2. Create content adapters unique to each language. See the examples below.
|
||||
|
||||
### Translations by file name
|
||||
|
||||
With this site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[languages.en]
|
||||
weight = 1
|
||||
|
||||
[languages.de]
|
||||
weight = 2
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Include a language designator in the content adapter's file name.
|
||||
|
||||
```text
|
||||
content/
|
||||
└── books/
|
||||
├── _content.de.gotmpl
|
||||
├── _content.en.gotmpl
|
||||
├── _index.de.md
|
||||
└── _index.en.md
|
||||
```
|
||||
|
||||
### Translations by content directory
|
||||
|
||||
With this site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[languages.en]
|
||||
contentDir = 'content/en'
|
||||
weight = 1
|
||||
|
||||
[languages.de]
|
||||
contentDir = 'content/de'
|
||||
weight = 2
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Create a single content adapter in each directory:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── de/
|
||||
│ └── books/
|
||||
│ ├── _content.gotmpl
|
||||
│ └── _index.md
|
||||
└── en/
|
||||
└── books/
|
||||
├── _content.gotmpl
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
## Page collisions
|
||||
|
||||
Two or more pages collide when they have the same publication path. Due to concurrency, the content of the published page is indeterminate. Consider this example:
|
||||
|
||||
```text
|
||||
content/
|
||||
└── books/
|
||||
├── _content.gotmpl <-- content adapter
|
||||
├── _index.md
|
||||
└── the-hunchback-of-notre-dame.md
|
||||
```
|
||||
|
||||
If the content adapter also creates books/the-hunchback-of-notre-dame, the content of the published page is indeterminate. You can not define the processing order.
|
||||
|
||||
To detect page collisions, use the `--printPathWarnings` flag when building your site.
|
||||
|
||||
[content formats]: /content-management/formats/#classification
|
||||
[front matter field]: /content-management/front-matter/#fields
|
||||
[logical path]: /getting-started/glossary/#logical-path
|
||||
[media type]: https://en.wikipedia.org/wiki/Media_type
|
||||
[page kind]: /getting-started/glossary/#page-kind
|
||||
[syntax]: /templates/introduction/
|
||||
[template functions]: /functions/
|
||||
|
|
@ -16,7 +16,7 @@ The `ref` and `relref` shortcodes display the absolute and relative permalinks t
|
|||
|
||||
## Use of `ref` and `relref`
|
||||
|
||||
The `ref` and `relref` shortcodes require a single parameter: the path to a content document, with or without a file extension, with or without an anchor. Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site.
|
||||
The `ref` and `relref` shortcodes require a single argument: the path to a content document, with or without a file extension, with or without an anchor. Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site.
|
||||
|
||||
```text
|
||||
.
|
||||
|
|
@ -60,7 +60,7 @@ index.md can be reference either by its path or by its containing folder without
|
|||
{{</* ref "/products/index" */>}} // <- 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]({{</* ref "/about" */>}} "About Us")
|
||||
|
|
@ -70,9 +70,11 @@ Hugo emits an error or warning if a document cannot be uniquely resolved. The er
|
|||
|
||||
### Link to another language version
|
||||
|
||||
Using `ref` or `relref` without specifying a language, will make the reference resolve to the language of the current content page.
|
||||
|
||||
To link to another language version of a document, use this syntax:
|
||||
|
||||
```go-html-template
|
||||
```text
|
||||
{{</* relref path="document.md" lang="ja" */>}}
|
||||
```
|
||||
|
||||
|
|
@ -80,7 +82,7 @@ To link to another language version of a document, use this syntax:
|
|||
|
||||
To link to another Output Format of a document, use this syntax:
|
||||
|
||||
```go-html-template
|
||||
```text
|
||||
{{</* relref path="document.md" outputFormat="rss" */>}}
|
||||
```
|
||||
|
||||
|
|
@ -88,7 +90,7 @@ To link to another Output Format of a document, use this syntax:
|
|||
|
||||
When using Markdown document types, Hugo generates element IDs for every heading on a page. For example:
|
||||
|
||||
```md
|
||||
```text
|
||||
## Reference
|
||||
```
|
||||
|
||||
|
|
@ -100,14 +102,14 @@ produces this HTML:
|
|||
|
||||
Get the permalink to a heading by appending the ID to the path when using the `ref` or `relref` shortcodes:
|
||||
|
||||
```go-html-template
|
||||
```text
|
||||
{{</* ref "document.md#reference" */>}}
|
||||
{{</* relref "document.md#reference" */>}}
|
||||
```
|
||||
|
||||
Generate a custom heading ID by including an attribute. For example:
|
||||
|
||||
```md
|
||||
```text
|
||||
## Reference A {#foo}
|
||||
## Reference B {id="bar"}
|
||||
```
|
||||
|
|
@ -121,7 +123,7 @@ produces this HTML:
|
|||
|
||||
Hugo will generate unique element IDs if the same heading appears more than once on a page. For example:
|
||||
|
||||
```md
|
||||
```text
|
||||
## Reference
|
||||
## Reference
|
||||
## Reference
|
||||
|
|
|
|||
126
docs/content/en/content-management/data-sources.md
Normal file
126
docs/content/en/content-management/data-sources.md
Normal file
|
|
@ -0,0 +1,126 @@
|
|||
---
|
||||
title: Data sources
|
||||
description: Use local and remote data sources to augment or create content.
|
||||
categories: [content management]
|
||||
keywords: [data,json,toml,yaml,xml]
|
||||
menu:
|
||||
docs:
|
||||
parent: content-management
|
||||
weight: 280
|
||||
weight: 280
|
||||
toc: true
|
||||
aliases: [/extras/datafiles/,/extras/datadrivencontent/,/doc/datafiles/,/templates/data-templates/]
|
||||
---
|
||||
|
||||
Hugo can access and [unmarshal] local and remote data sources including CSV, JSON, TOML, YAML, and XML. Use this data to augment existing content or to create new content.
|
||||
|
||||
[unmarshal]: /getting-started/glossary/#unmarshal
|
||||
|
||||
A data source might be a file in the data directory, a [global resource], a [page resource], or a [remote resource].
|
||||
|
||||
[global resource]: /getting-started/glossary/#global-resource
|
||||
[page resource]: /getting-started/glossary/#page-resource
|
||||
[remote resource]: /getting-started/glossary/#remote-resource
|
||||
|
||||
## Data directory
|
||||
|
||||
The data directory in the root of your project may contain one or more data files, in either a flat or nested tree. Hugo merges the data files to create a single data structure, accessible with the `Data` method on a `Site` object.
|
||||
|
||||
Hugo also merges data directories from themes and modules into this single data structure, where the data directory in the root of your project takes precedence.
|
||||
|
||||
{{% note %}}
|
||||
Hugo reads the combined data structure into memory and keeps it there for the entire build. For data that is infrequently accessed, use global or page resources instead.
|
||||
{{% /note %}}
|
||||
|
||||
Theme and module authors may wish to namespace their data files to prevent collisions. For example:
|
||||
|
||||
```text
|
||||
project/
|
||||
└── data/
|
||||
└── mytheme/
|
||||
└── foo.json
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
Do not place CSV files in the data directory. Access CSV files as page, global, or remote resources.
|
||||
{{% /note %}}
|
||||
|
||||
See the documentation for the [`Data`] method on `Page` object for details and examples.
|
||||
|
||||
[`Data`]: /methods/site/data/
|
||||
|
||||
## Global resources
|
||||
|
||||
Use the `resources.Get` and `transform.Unmarshal` functions to access data files that exist as global resources.
|
||||
|
||||
See the [`transform.Unmarshal`](/functions/transform/unmarshal/#global-resource) documentation for details and examples.
|
||||
|
||||
## Page resources
|
||||
|
||||
Use the `Resources.Get` method on a `Page` object combined with the `transform.Unmarshal` function to access data files that exist as page resources.
|
||||
|
||||
See the [`transform.Unmarshal`](/functions/transform/unmarshal/#page-resource) documentation for details and examples.
|
||||
|
||||
## Remote resources
|
||||
|
||||
Use the `resources.GetRemote` and `transform.Unmarshal` functions to access remote data.
|
||||
|
||||
See the [`transform.Unmarshal`](/functions/transform/unmarshal/#remote-resource) documentation for details and examples.
|
||||
|
||||
## Augment existing content
|
||||
|
||||
Use data sources to augment existing content. For example, create a shortcode to render an HTML table from a global CSV resource.
|
||||
|
||||
{{< code file=assets/pets.csv >}}
|
||||
"name","type","breed","age"
|
||||
"Spot","dog","Collie","3"
|
||||
"Felix","cat","Malicious","7"
|
||||
{{< /code >}}
|
||||
|
||||
{{< code file=content/example.md lang=text >}}
|
||||
{{</* csv-to-table "pets.csv" */>}}
|
||||
{{< /code >}}
|
||||
|
||||
{{< code file=layouts/shortcodes/csv-to-table.html >}}
|
||||
{{ with $file := .Get 0 }}
|
||||
{{ with resources.Get $file }}
|
||||
{{ with . | transform.Unmarshal }}
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
{{ range index . 0 }}
|
||||
<th>{{ . }}</th>
|
||||
{{ end }}
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{{ range after 1 . }}
|
||||
<tr>
|
||||
{{ range . }}
|
||||
<td>{{ . }}</td>
|
||||
{{ end }}
|
||||
</tr>
|
||||
{{ end }}
|
||||
</tbody>
|
||||
</table>
|
||||
{{ end }}
|
||||
{{ else }}
|
||||
{{ errorf "The %q shortcode was unable to find %s. See %s" $.Name $file $.Position }}
|
||||
{{ end }}
|
||||
{{ else }}
|
||||
{{ errorf "The %q shortcode requires one positional argument, the path to the CSV file relative to the assets directory. See %s" .Name .Position }}
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
Hugo renders this to:
|
||||
|
||||
name|type|breed|age
|
||||
:--|:--|:--|:--
|
||||
Spot|dog|Collie|3
|
||||
Felix|cat|Malicious|7
|
||||
|
||||
## Create new content
|
||||
|
||||
Use [content adapters] to create new content.
|
||||
|
||||
[content adapters]: /content-management/content-adapters/
|
||||
|
|
@ -1,20 +1,22 @@
|
|||
---
|
||||
title: Diagrams
|
||||
description: Use fenced code blocks and markdown render hooks to display diagrams.
|
||||
description: Use fenced code blocks and Markdown render hooks to include diagrams in your content.
|
||||
categories: [content management]
|
||||
keywords: [diagrams,drawing]
|
||||
menu:
|
||||
docs:
|
||||
parent: content-management
|
||||
weight: 50
|
||||
weight: 50
|
||||
weight: 260
|
||||
weight: 260
|
||||
toc: true
|
||||
---
|
||||
{{< new-in 0.93.0 >}}
|
||||
|
||||
## GoAT diagrams (ASCII)
|
||||
|
||||
Hugo supports [GoAT](https://github.com/bep/goat) natively. This means that this code block:
|
||||
Hugo natively supports [GoAT] diagrams with an [embedded code block render hook]. This means that this code block:
|
||||
|
||||
[GoAT]: https://github.com/bep/goat
|
||||
[embedded code block render hook]: {{% eturl render-codeblock-goat %}}
|
||||
|
||||
````txt
|
||||
```goat
|
||||
|
|
@ -44,19 +46,21 @@ Will be rendered as:
|
|||
|
||||
## Mermaid diagrams
|
||||
|
||||
Hugo currently does not provide default templates for Mermaid diagrams. But you can easily add your own. One way to do it would be to create `layouts/_default/_markup/render-codeblock-mermaid.html`:
|
||||
Hugo does not provide a built-in template for Mermaid diagrams. Create your own using a [code block render hook]:
|
||||
|
||||
```go-html-template
|
||||
[code block render hook]: /render-hooks/code-blocks/
|
||||
|
||||
{{< code file=layouts/_default/_markup/render-codeblock-mermaid.html >}}
|
||||
<pre class="mermaid">
|
||||
{{- .Inner | safeHTML }}
|
||||
</pre>
|
||||
{{ .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" }}
|
||||
<script type="module">
|
||||
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
|
||||
mermaid.initialize({ startOnLoad: true });
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
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:
|
||||
|
|
@ -12,82 +12,126 @@ 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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: Front matter
|
||||
description: Hugo allows you to add front matter in yaml, toml, or json to your content files.
|
||||
description: Use front matter to add metadata to your content.
|
||||
categories: [content management]
|
||||
keywords: [front matter,yaml,toml,json,metadata,archetypes]
|
||||
menu:
|
||||
|
|
@ -12,230 +12,419 @@ 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.
|
||||
|
||||
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`).
|
||||
|
||||
### Example
|
||||
|
||||
{{< 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 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 >}}
|
||||
|
||||
## Front matter variables
|
||||
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.
|
||||
|
||||
### Predefined
|
||||
[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
|
||||
|
||||
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.
|
||||
## Fields
|
||||
|
||||
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.
|
||||
|
||||
audio
|
||||
: An array of paths to audio files related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:audio`.
|
||||
|
||||
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.
|
||||
|
||||
date
|
||||
: The datetime assigned to this page. This is usually fetched from the `date` field in front matter, but this behavior is configurable.
|
||||
|
||||
description
|
||||
: The description for the content.
|
||||
|
||||
draft
|
||||
: If `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command.
|
||||
|
||||
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.
|
||||
|
||||
headless
|
||||
: If `true`, sets a leaf bundle to be [headless][headless-bundle].
|
||||
|
||||
images
|
||||
: An array of paths to images related to the page; used by [internal templates](/templates/internal) such as `_internal/twitter_cards.html`.
|
||||
|
||||
isCJKLanguage
|
||||
: If `true`, Hugo will explicitly treat the content as a CJK language; both `.Summary` and `.WordCount` work properly in CJK languages.
|
||||
|
||||
keywords
|
||||
: The meta keywords for the content.
|
||||
|
||||
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].
|
||||
|
||||
lastmod
|
||||
: The datetime at which the content was last modified.
|
||||
|
||||
linkTitle
|
||||
: Used for creating links to content; if set, Hugo defaults to using the `linkTitle` before the `title`.
|
||||
|
||||
markup
|
||||
: **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown.
|
||||
|
||||
outputs
|
||||
: Allows you to specify output formats specific to the content. See [output formats][outputs].
|
||||
|
||||
publishDate
|
||||
: If in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`.
|
||||
|
||||
resources
|
||||
: Used for configuring page bundle resources. See [Page Resources][page-resources].
|
||||
|
||||
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`.
|
||||
|
||||
slug
|
||||
: Overrides the last segment of the URL path. Not applicable to section pages. See [URL Management](/content-management/urls/#slug) for details.
|
||||
|
||||
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.
|
||||
|
||||
title
|
||||
: The title for the content.
|
||||
|
||||
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.
|
||||
|
||||
url
|
||||
: Overrides the entire URL path. Applicable to regular pages and section pages. See [URL Management](/content-management/urls/#url) for details.
|
||||
|
||||
videos
|
||||
: An array of paths to videos related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:video`.
|
||||
|
||||
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.
|
||||
The most common front matter fields are `date`, `draft`, `title`, and `weight`, but you can specify metadata using any of fields below.
|
||||
|
||||
{{% 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.
|
||||
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.
|
||||
|
||||
[parameters]: #parameters
|
||||
{{% /note %}}
|
||||
|
||||
### User-defined
|
||||
###### aliases
|
||||
|
||||
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 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.
|
||||
|
||||
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.
|
||||
[`aliases`]: /methods/page/aliases/
|
||||
[aliases]: /content-management/urls/#aliases
|
||||
|
||||
{{< code-toggle >}}
|
||||
include_toc: true
|
||||
show_comments: false
|
||||
{{</ code-toggle >}}
|
||||
###### build
|
||||
|
||||
## Front matter cascade
|
||||
(`map`) A map of [build options].
|
||||
|
||||
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.
|
||||
[build options]: /content-management/build-options/
|
||||
|
||||
###### cascade {#cascade-field}
|
||||
|
||||
(`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.
|
||||
|
||||
[cascade]: #cascade
|
||||
|
||||
###### date
|
||||
|
||||
(`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.
|
||||
|
||||
[`date`]: /methods/page/date/
|
||||
|
||||
###### description
|
||||
|
||||
(`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.
|
||||
|
||||
[`description`]: /methods/page/description/
|
||||
|
||||
###### draft
|
||||
|
||||
(`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.
|
||||
|
||||
[`draft`]: /methods/page/draft/
|
||||
|
||||
###### expiryDate
|
||||
|
||||
(`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.
|
||||
|
||||
[`expirydate`]: /methods/page/expirydate/
|
||||
|
||||
###### headless
|
||||
|
||||
(`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].
|
||||
|
||||
[leaf bundles]: /content-management/page-bundles/#leaf-bundles
|
||||
[page resources]: /content-management/page-resources/
|
||||
|
||||
###### isCJKLanguage
|
||||
|
||||
(`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.
|
||||
|
||||
[`fuzzywordcount`]: /methods/page/wordcount/
|
||||
[`readingtime`]: /methods/page/readingtime/
|
||||
[`summary`]: /methods/page/summary/
|
||||
[`wordcount`]: /methods/page/wordcount/
|
||||
[cjk]: /getting-started/glossary/#cjk
|
||||
|
||||
###### keywords
|
||||
|
||||
(`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.
|
||||
|
||||
[`keywords`]: /methods/page/keywords/
|
||||
[taxonomy]: /getting-started/glossary/#taxonomy
|
||||
|
||||
<!-- Added in v0.123.0 but purposefully omitted from documentation. -->
|
||||
<!--
|
||||
kind
|
||||
: The kind of page, e.g. "page", "section", "home" etc. This is usually derived from the content path.
|
||||
-->
|
||||
|
||||
<!-- Added in v0.123.0 but purposefully omitted from documentation. -->
|
||||
<!--
|
||||
lang
|
||||
: The language code for this page. This is usually derived from the module mount or filename.
|
||||
-->
|
||||
|
||||
###### lastmod
|
||||
|
||||
(`string`) The date that the page was last modified. Note that the TOML format also supports date/time values using unquoted strings. Access this value from a template using the [`Lastmod`] method on a `Page` object.
|
||||
|
||||
[`lastmod`]: /methods/page/date/
|
||||
|
||||
###### layout
|
||||
|
||||
(`string`) Provide a template name to [target a specific template], overriding the default [template lookup order]. Set the value to the base file name of the template, excluding its extension. Access this value from a template using the [`Layout`] method on a `Page` object.
|
||||
|
||||
[`layout`]: /methods/page/layout/
|
||||
[template lookup order]: /templates/lookup-order/
|
||||
[target a specific template]: templates/lookup-order/#target-a-template
|
||||
|
||||
###### linkTitle
|
||||
|
||||
(`string`) Typically a shorter version of the `title`. Access this value from a template using the [`LinkTitle`] method on a `Page` object.
|
||||
|
||||
[`linktitle`]: /methods/page/linktitle/
|
||||
|
||||
###### markup
|
||||
|
||||
(`string`) An identifier corresponding to one of the supported [content formats]. If not provided, Hugo determines the content renderer based on the file extension.
|
||||
|
||||
[content formats]: /content-management/formats/#classification
|
||||
|
||||
###### menus
|
||||
|
||||
(`string`,`string array`, or `map`) If set, Hugo adds the page to the given menu or menus. See the [menus] page for details.
|
||||
|
||||
[menus]: /content-management/menus/#define-in-front-matter
|
||||
|
||||
###### outputs
|
||||
|
||||
(`string array`) The [output formats] to render.
|
||||
|
||||
[output formats]: /templates/output-formats/
|
||||
|
||||
<!-- Added in v0.123.0 but purposefully omitted from documentation. -->
|
||||
<!--
|
||||
path
|
||||
: The canonical page path.
|
||||
-->
|
||||
|
||||
###### params
|
||||
|
||||
{{< new-in 0.123.0 >}}
|
||||
|
||||
(`map`) A map of custom [page parameters].
|
||||
|
||||
[page parameters]: #parameters
|
||||
|
||||
###### publishDate
|
||||
|
||||
(`string`) The page publication date. Before the publication date, the page will not be rendered unless you pass the `--buildFuture` flag to the `hugo` command. Note that the TOML format also supports date/time values using unquoted strings. Access this value from a template using the [`PublishDate`] method on a `Page` object.
|
||||
|
||||
[`publishdate`]: /methods/page/publishdate/
|
||||
|
||||
###### resources
|
||||
|
||||
(`map array`) An array of maps to provide metadata for [page resources].
|
||||
|
||||
[page-resources]: /content-management/page-resources/#page-resources-metadata
|
||||
|
||||
###### sitemap
|
||||
|
||||
(`map`) A map of sitemap options. See the [sitemap templates] page for details. Access these values from a template using the [`Sitemap`] method on a `Page` object.
|
||||
|
||||
[sitemap templates]: /templates/sitemap-template/
|
||||
[`sitemap`]: /methods/page/sitemap/
|
||||
|
||||
###### slug
|
||||
|
||||
(`string`) Overrides the last segment of the URL path. Not applicable to section pages. See the [URL management] page for details. Access this value from a template using the [`Slug`] method on a `Page` object.
|
||||
|
||||
[`slug`]: /methods/page/slug/
|
||||
[URL management]: /content-management/urls/#slug
|
||||
|
||||
###### summary
|
||||
|
||||
(`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.
|
||||
|
||||
[`Summary`]: /methods/page/summary/
|
||||
|
||||
###### title
|
||||
|
||||
(`string`) The page title. Access this value from a template using the [`Title`] method on a `Page` object.
|
||||
|
||||
[`title`]: /methods/page/title/
|
||||
|
||||
###### translationKey
|
||||
|
||||
(`string`) An arbitrary value used to relate two or more translations of the same page, useful when the translated pages do not share a common path. Access this value from a template using the [`TranslationKey`] method on a `Page` object.
|
||||
|
||||
[`translationkey`]: /methods/page/translationkey/
|
||||
|
||||
###### type
|
||||
|
||||
(`string`) The [content type], overriding the value derived from the top level section in which the page resides. Access this value from a template using the [`Type`] method on a `Page` object.
|
||||
|
||||
[content type]: /getting-started/glossary/#content-type
|
||||
[`type`]: /methods/page/type/
|
||||
|
||||
###### url
|
||||
|
||||
(`string`) Overrides the entire URL path. Applicable to regular pages and section pages. See the [URL management] page for details.
|
||||
|
||||
###### weight
|
||||
(`int`) The page [weight], used to order the page within a [page collection]. Access this value from a template using the [`Weight`] method on a `Page` object.
|
||||
|
||||
[page collection]: /getting-started/glossary/#page-collection
|
||||
[weight]: /getting-started/glossary/#weight
|
||||
[`weight`]: /methods/page/weight/
|
||||
|
||||
## Parameters
|
||||
|
||||
{{< new-in 0.123.0 >}}
|
||||
|
||||
Specify custom page parameters under the `params` key in front matter:
|
||||
|
||||
{{< code-toggle file=content/example.md fm=true >}}
|
||||
title = 'Example'
|
||||
date = 2024-02-02T04:14:54-08:00
|
||||
draft = false
|
||||
weight = 10
|
||||
[params]
|
||||
author = 'John Smith'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Access these values from a template using the [`Params`] or [`Param`] method on a `Page` object.
|
||||
|
||||
[`param`]: /methods/page/param/
|
||||
[`params`]: /methods/page/params/
|
||||
|
||||
Hugo provides [embedded templates] to optionally insert meta data within the `head` element of your rendered pages. These embedded templates expect the following front matter parameters:
|
||||
|
||||
Parameter|Data type|Used by these embedded templates
|
||||
:--|:--|:--
|
||||
`audio`|`[]string`|[`opengraph.html`]
|
||||
`images`|`[]string`|[`opengraph.html`], [`schema.html`], [`twitter_cards.html`]
|
||||
`videos`|`[]string`|[`opengraph.html`]
|
||||
|
||||
The embedded templates will skip a parameter if not provided in front matter, but will throw an error if the data type is unexpected.
|
||||
|
||||
[`opengraph.html`]: {{% eturl opengraph %}}
|
||||
[`schema.html`]: {{% eturl schema %}}
|
||||
[`twitter_cards.html`]: {{% eturl twitter_cards %}}
|
||||
[embedded templates]: /templates/embedded/
|
||||
|
||||
## Taxonomies
|
||||
|
||||
Classify content by adding taxonomy terms to front matter. For example, with this site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[taxonomies]
|
||||
tag = 'tags'
|
||||
genre = 'genres'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Add taxonomy terms as shown below:
|
||||
|
||||
{{< code-toggle file=content/example.md fm=true >}}
|
||||
title = 'Example'
|
||||
date = 2024-02-02T04:14:54-08:00
|
||||
draft = false
|
||||
weight = 10
|
||||
tags = ['red','blue']
|
||||
genres = ['mystery','romance']
|
||||
[params]
|
||||
author = 'John Smith'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
You can add taxonomy terms to the front matter of any these [page kinds]:
|
||||
|
||||
- `home`
|
||||
- `page`
|
||||
- `section`
|
||||
- `taxonomy`
|
||||
- `term`
|
||||
|
||||
[page kinds]: /getting-started/glossary/#page-kind
|
||||
|
||||
Access taxonomy terms from a template using the [`Params`] or [`GetTerms`] method on a `Page` object. For example:
|
||||
|
||||
{{< code file=layouts/_default/single.html >}}
|
||||
{{ with .GetTerms "tags" }}
|
||||
<p>Tags</p>
|
||||
<ul>
|
||||
{{ range . }}
|
||||
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
[`Params`]: /methods/page/params/
|
||||
[`GetTerms`]: /methods/page/getterms/
|
||||
|
||||
## Cascade
|
||||
|
||||
Any [node] can pass down to its descendants a set of front matter values.
|
||||
|
||||
[node]: /getting-started/glossary/#node
|
||||
|
||||
### Target specific pages
|
||||
|
||||
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"
|
||||
{{</ code-toggle >}}
|
||||
|
||||
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}
|
||||
|
||||
environment
|
||||
: A Glob pattern matching the build environment, e.g. "{production,development}"
|
||||
(`string`) A Glob pattern matching the Page's Kind(s), e.g. "{home,section}".
|
||||
|
||||
###### lang {#cascade-lang}
|
||||
|
||||
(`string`) A Glob pattern matching the Page's language, e.g. "{en,sv}".
|
||||
|
||||
###### environment {#cascade-environment}
|
||||
|
||||
(`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'
|
||||
{{</ code-toggle >}}
|
||||
|
||||
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 [`<TAXONOMY>_weight`][taxweight] for ordering content within a taxonomy. See [Ordering and Grouping Hugo Lists][lists] to see how `weight` can be used to organize your content in list views.
|
||||
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/
|
||||
|
|
|
|||
|
|
@ -249,19 +249,21 @@ You may also access EXIF fields individually, using the [`lang.FormatNumber`] fu
|
|||
{{ 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
|
||||
|
||||
|
|
@ -500,11 +502,11 @@ If you change image processing methods or options, or if you rename or remove im
|
|||
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]: <https://github.com/disintegration/imaging#image-resizing>
|
||||
[Smartcrop]: <https://github.com/muesli/smartcrop#smartcrop>
|
||||
|
|
|
|||
115
docs/content/en/content-management/markdown-attributes.md
Normal file
115
docs/content/en/content-management/markdown-attributes.md
Normal file
|
|
@ -0,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
|
||||
<p class="foo bar" id="baz">This is a paragraph.</p>
|
||||
```
|
||||
|
||||
## Block elements
|
||||
|
||||
Update your site configuration to enable Markdown attributes for block-level elements.
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.goldmark.parser.attribute]
|
||||
title = true # default is true
|
||||
block = true # default is false
|
||||
{{< /code-toggle >}}
|
||||
|
||||
|
||||
## Standalone images
|
||||
|
||||
By default, when the [Goldmark] Markdown renderer encounters a standalone image element (no other elements or text on the same line), it wraps the image element within a paragraph element per the [CommonMark specification].
|
||||
|
||||
[CommonMark specification]: https://spec.commonmark.org/current/
|
||||
[Goldmark]: https://github.com/yuin/goldmark
|
||||
|
||||
If you were to place an attribute list beneath an image element, Hugo would apply the attributes to the surrounding paragraph, not the image.
|
||||
|
||||
To apply attributes to a standalone image element, you must disable the default wrapping behavior:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.goldmark.parser]
|
||||
wrapStandAloneImageWithinParagraph = false # default is true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## Usage
|
||||
|
||||
You may add [global HTML attributes], or HTML attributes specific to the current element type. Consistent with its content security model, Hugo removes HTML event attributes such as `onclick` and `onmouseover`.
|
||||
|
||||
[global HTML attributes]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes
|
||||
|
||||
The attribute list consists of one or more key-value pairs, separated by spaces or commas, wrapped by braces. You must quote string values that contain spaces. Unlike HTML, boolean attributes must have both key and value.
|
||||
|
||||
For example:
|
||||
|
||||
```text
|
||||
> This is a blockquote.
|
||||
{class="foo bar" hidden=hidden}
|
||||
```
|
||||
|
||||
Hugo renders this to:
|
||||
|
||||
```html
|
||||
<blockquote class="foo bar" hidden="hidden">
|
||||
<p>This is a blockquote.</p>
|
||||
</blockquote>
|
||||
```
|
||||
|
||||
In most cases, place the attribute list beneath the markup element. For headings and fenced code blocks, place the attribute list on the right.
|
||||
|
||||
Element|Position of attribute list
|
||||
:--|:--
|
||||
blockquote | bottom
|
||||
fenced code block | right
|
||||
heading | right
|
||||
horizontal rule | bottom
|
||||
image | bottom
|
||||
list | bottom
|
||||
paragraph | bottom
|
||||
table | bottom
|
||||
|
||||
For example:
|
||||
|
||||
````text
|
||||
## Section 1 {class=foo}
|
||||
|
||||
```bash {class=foo linenos=inline}
|
||||
declare a=1
|
||||
echo "${a}"
|
||||
```
|
||||
|
||||
This is a paragraph.
|
||||
{class=foo}
|
||||
````
|
||||
|
||||
As shown above, the attribute list for fenced code blocks is not limited to HTML attributes. You can also configure syntax highlighting by passing one or more of [these options](/functions/transform/highlight/#options).
|
||||
|
|
@ -1,14 +1,14 @@
|
|||
---
|
||||
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
|
||||
---
|
||||
|
|
@ -45,11 +45,11 @@ The approach described below avoids reliance on platform-specific features like
|
|||
|
||||
## 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]
|
||||
|
|
@ -122,7 +122,7 @@ The example above loads the partial template if you have set the `math` paramete
|
|||
|
||||
###### 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.
|
||||
|
|
@ -152,8 +152,9 @@ If you set the `math` parameter to `false` in your site configuration, you must
|
|||
|
||||
{{< code-toggle file=content/math-examples.md fm=true >}}
|
||||
title = 'Math examples'
|
||||
math = true
|
||||
date = 2024-01-24T18:09:49-08:00
|
||||
[params]
|
||||
math = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## Inline delimiters
|
||||
|
|
|
|||
|
|
@ -34,7 +34,7 @@ Although you can use these methods in combination when defining a menu, the menu
|
|||
|
||||
## 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"
|
||||
|
|
@ -167,7 +167,7 @@ Each menu entry defined in site configuration requires two or more properties:
|
|||
- 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
|
||||
:--|:--
|
||||
|
|
@ -229,4 +229,5 @@ 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/
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
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:
|
||||
|
|
@ -13,16 +13,24 @@ 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 >}}
|
||||
|
|
@ -55,11 +63,11 @@ 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`.
|
||||
|
|
@ -71,7 +79,7 @@ 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`
|
||||
|
|
@ -84,7 +92,7 @@ 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.
|
||||
|
|
@ -92,7 +100,7 @@ weight
|
|||
[`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
|
||||
|
|
@ -150,9 +158,8 @@ 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.
|
||||
|
|
@ -162,17 +169,16 @@ 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
|
||||
{{</ code-toggle >}}
|
||||
|
||||
With the above, the two sites will be generated into `public` with their own root:
|
||||
|
|
@ -309,7 +315,7 @@ To create a list of links to translated content, use a template similar to the f
|
|||
<ul>
|
||||
{{ range .Translations }}
|
||||
<li>
|
||||
<a href="{{ .RelPermalink }}">{{ .Lang }}: {{ .LinkTitle }}{{ if .IsPage }} ({{ i18n "wordCount" . }}){{ end }}</a>
|
||||
<a href="{{ .RelPermalink }}">{{ .Language.Lang }}: {{ .LinkTitle }}{{ if .IsPage }} ({{ i18n "wordCount" . }}){{ end }}</a>
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
|
|
@ -334,96 +340,9 @@ The above also uses the [`i18n` function][i18func] described in the next section
|
|||
|
||||
## 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.
|
||||
See the [`lang.Translate`] template function.
|
||||
|
||||
Translations are collected from the `themes/<THEME>/i18n/` folder (built into the theme), as well as translations present in `i18n/` at the root of your project. In the `i18n`, the translations will be merged and take precedence over what is in the theme folder. Language files should be named according to [RFC 5646] with names such as `en-US.toml`, `fr.toml`, etc.
|
||||
|
||||
Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7](https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7) are also supported. You may omit the `art-x-` prefix for brevity. For example:
|
||||
|
||||
```text
|
||||
art-x-hugolang
|
||||
hugolang
|
||||
```
|
||||
|
||||
Private use subtags must not exceed 8 alphanumeric characters.
|
||||
|
||||
### Query basic translation
|
||||
|
||||
From within your templates, use the [`i18n`] function like this:
|
||||
|
||||
[`i18n`]: /functions/lang/translate
|
||||
|
||||
```go-html-template
|
||||
{{ i18n "home" }}
|
||||
```
|
||||
|
||||
The function will search for the `"home"` id:
|
||||
|
||||
{{< code-toggle file=i18n/en-US >}}
|
||||
[home]
|
||||
other = "Home"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The result will be
|
||||
|
||||
```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
|
||||
|
||||
|
|
@ -676,7 +595,7 @@ To support Multilingual mode in your themes, some considerations must be taken f
|
|||
* 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`
|
||||
|
||||
|
|
@ -694,23 +613,22 @@ 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/
|
||||
|
|
|
|||
|
|
@ -19,13 +19,28 @@ Hugo `0.32` announced page-relative images and other resources packaged into `Pa
|
|||
|
||||
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
|
||||
|
||||
|
|
@ -52,7 +67,7 @@ Without any additional configuration, the following will automatically work:
|
|||
|
||||
## 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`
|
||||
|
||||
|
|
@ -69,7 +84,7 @@ You can create one `_index.md` for your homepage and one in each of your content
|
|||
. ⊢--^-⊣
|
||||
. path slug
|
||||
. ⊢--^-⊣⊢---^---⊣
|
||||
. filepath
|
||||
. file path
|
||||
. ⊢------^------⊣
|
||||
content/posts/_index.md
|
||||
```
|
||||
|
|
@ -140,7 +155,7 @@ The `url` is the entire URL path, defined by the file path and optionally overri
|
|||
[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/
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
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 :
|
||||
|
|
@ -11,173 +11,147 @@ 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
|
||||
```
|
||||
|
||||
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 %}}
|
||||
|
||||
## Comparison
|
||||
|
||||
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 at any hierarchy within the `content/`
|
||||
directory, that contains an **`index.md`** file.
|
||||
|
||||
### Examples of leaf bundle organization {#examples-of-leaf-bundle-organization}
|
||||
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*" }}
|
||||
<h2>Authors</h2>
|
||||
{{ range $reusablePages }}
|
||||
<h3>{{ .Title }}</h3>
|
||||
{{ .Content }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
_In this example, we are assuming the `some-headless-bundle` to be a headless
|
||||
bundle containing one or more **page** resources whose `.Name` matches
|
||||
`"author*"`._
|
||||
|
||||
Explanation of the above example:
|
||||
|
||||
1. Get the `some-headless-bundle` Page "object".
|
||||
2. Collect a _slice_ of resources in this _Page Bundle_ that matches
|
||||
`"author*"` using `.Resources.Match`.
|
||||
3. Loop through that _slice_ of nested pages, and output their `.Title` and
|
||||
`.Content`.
|
||||
|
||||
---
|
||||
|
||||
A leaf bundle can be made headless by adding below in the front matter
|
||||
(in the `index.md`):
|
||||
|
||||
{{< code-toggle file=content/headless/index.md fm=true >}}
|
||||
headless = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
There are many use cases of such headless page bundles:
|
||||
|
||||
- Shared media galleries
|
||||
- Reusable page content "snippets"
|
||||
|
||||
## 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/
|
||||
|
|
|
|||
|
|
@ -10,6 +10,7 @@ menu:
|
|||
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.
|
||||
|
|
@ -114,7 +115,7 @@ GetMatch
|
|||
.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).
|
||||
|
||||
|
|
@ -133,7 +134,7 @@ title
|
|||
: Sets the value returned in `Title`
|
||||
|
||||
params
|
||||
: A map of custom key/values.
|
||||
: A map of custom key-value pairs.
|
||||
|
||||
### Resources metadata example
|
||||
|
||||
|
|
@ -201,3 +202,108 @@ the `Name` and `Title` will be assigned to the resource files as follows:
|
|||
| 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 >}}
|
||||
|
|
|
|||
|
|
@ -150,7 +150,7 @@ 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.
|
||||
|
|
|
|||
|
|
@ -77,7 +77,10 @@ With the file structure from the [example above](#overview):
|
|||
|
||||
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -27,9 +27,9 @@ In addition to cleaner Markdown, shortcodes can be updated any time to reflect n
|
|||
|
||||
{{< youtube 2xkNJL4gJ9E >}}
|
||||
|
||||
In your content files, a shortcode can be called by calling `{{%/* shortcodename parameters */%}}`. Shortcode parameters are space delimited, and parameters with internal spaces can be quoted.
|
||||
In your content files, a shortcode can be called by calling `{{%/* shortcodename arguments */%}}`. Shortcode arguments are space delimited, and arguments with internal spaces must be quoted.
|
||||
|
||||
The first word in the shortcode declaration is always the name of the shortcode. Parameters follow the name. Depending upon how the shortcode is defined, the parameters may be named, positional, or both, although you can't mix parameter types in a single call. The format for named parameters models that of HTML with the format `name="value"`.
|
||||
The first word in the shortcode declaration is always the name of the shortcode. Arguments follow the name. Depending upon how the shortcode is defined, the arguments may be named, positional, or both, although you can't mix argument types in a single call. The format for named arguments models that of HTML with the format `name="value"`.
|
||||
|
||||
Some shortcodes use or require closing shortcodes. Again like HTML, the opening and closing shortcodes match (name only) with the closing declaration, which is prepended with a slash.
|
||||
|
||||
|
|
@ -45,20 +45,20 @@ Here are two examples of paired shortcodes:
|
|||
|
||||
The examples above use two different delimiters, the difference being the `%` character in the first and the `<>` characters in the second.
|
||||
|
||||
### Shortcodes with raw string parameters
|
||||
### Shortcodes with raw string arguments
|
||||
|
||||
You can pass multiple lines as parameters to a shortcode by using raw string literals:
|
||||
You can pass multiple lines as arguments to a shortcode by using raw string literals:
|
||||
|
||||
```go-html-template
|
||||
{{</* myshortcode `This is some <b>HTML</b>,
|
||||
and a new line with a "quoted string".` */>}}
|
||||
```
|
||||
|
||||
### Shortcodes with markdown
|
||||
### Shortcodes with Markdown
|
||||
|
||||
Shortcodes using the `%` as the outer-most delimiter will be fully rendered when sent to the content renderer. This means that the rendered output from a shortcode can be part of the page's table of contents, footnotes, etc.
|
||||
|
||||
### Shortcodes without markdown
|
||||
### Shortcodes without Markdown
|
||||
|
||||
The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without Markdown include internal HTML:
|
||||
|
||||
|
|
@ -68,17 +68,21 @@ The `<` character indicates that the shortcode's inner content does *not* need f
|
|||
|
||||
### Nested shortcodes
|
||||
|
||||
You can call shortcodes within other shortcodes by creating your own templates that leverage the `.Parent` variable. `.Parent` allows you to check the context in which the shortcode is being called. See [Shortcode templates][sctemps].
|
||||
You can call shortcodes within other shortcodes by creating your own templates that leverage the `.Parent` method. `.Parent` allows you to check the context in which the shortcode is being called. See [Shortcode templates][sctemps].
|
||||
|
||||
## Use Hugo's built-in shortcodes
|
||||
## Embedded shortcodes
|
||||
|
||||
Hugo ships with a set of predefined shortcodes that represent very common usage. These shortcodes are provided for author convenience and to keep your Markdown content clean.
|
||||
Use these embedded shortcodes as needed.
|
||||
|
||||
### `figure`
|
||||
### figure
|
||||
|
||||
`figure` is an extension of the image syntax in Markdown, which does not provide a shorthand for the more semantic [HTML5 `<figure>` element][figureelement].
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `figure` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
The `figure` shortcode can use the following named parameters:
|
||||
[source code]: {{% eturl figure %}}
|
||||
{{% /note %}}
|
||||
|
||||
The `figure` shortcode can use the following named arguments:
|
||||
|
||||
src
|
||||
: URL of the image to be displayed.
|
||||
|
|
@ -87,10 +91,10 @@ link
|
|||
: If the image needs to be hyperlinked, URL of the destination.
|
||||
|
||||
target
|
||||
: Optional `target` attribute for the URL if `link` parameter is set.
|
||||
: Optional `target` attribute for the URL if `link` argument is set.
|
||||
|
||||
rel
|
||||
: Optional `rel` attribute for the URL if `link` parameter is set.
|
||||
: Optional `rel` attribute for the URL if `link` argument is set.
|
||||
|
||||
alt
|
||||
: Alternate text for the image if the image cannot be displayed.
|
||||
|
|
@ -119,13 +123,13 @@ attr
|
|||
attrlink
|
||||
: If the attribution text needs to be hyperlinked, URL of the destination.
|
||||
|
||||
#### Example `figure` input
|
||||
Example usage:
|
||||
|
||||
{{< code file=figure-input-example.md >}}
|
||||
```text
|
||||
{{</* figure src="elephant.jpg" title="An elephant at sunset" */>}}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
#### Example `figure` output
|
||||
Rendered:
|
||||
|
||||
```html
|
||||
<figure>
|
||||
|
|
@ -134,7 +138,13 @@ attrlink
|
|||
</figure>
|
||||
```
|
||||
|
||||
### `gist`
|
||||
### gist
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `gist` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
[source code]: {{% eturl gist %}}
|
||||
{{% /note %}}
|
||||
|
||||
To display a GitHub [gist] with this URL:
|
||||
|
||||
|
|
@ -144,7 +154,7 @@ To display a GitHub [gist] with this URL:
|
|||
https://gist.github.com/user/50a7482715eac222e230d1e64dd9a89b
|
||||
```
|
||||
|
||||
Include this in your markdown:
|
||||
Include this in your Markdown:
|
||||
|
||||
```text
|
||||
{{</* gist user 50a7482715eac222e230d1e64dd9a89b */>}}
|
||||
|
|
@ -164,7 +174,13 @@ Rendered:
|
|||
|
||||
{{< gist jmooring 23932424365401ffa5e9d9810102a477 list.html >}}
|
||||
|
||||
### `highlight`
|
||||
### highlight
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `highlight` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
[source code]: {{% eturl highlight %}}
|
||||
{{% /note %}}
|
||||
|
||||
To display a highlighted code sample:
|
||||
|
||||
|
|
@ -204,113 +220,148 @@ Rendered:
|
|||
{{ end }}
|
||||
{{< /highlight >}}
|
||||
|
||||
### `instagram`
|
||||
|
||||
The `instagram` shortcode uses Facebook's **oEmbed Read** feature. The Facebook [developer documentation] states:
|
||||
|
||||
- This permission or feature requires successful completion of the App Review process before your app can access live data. [Learn More]
|
||||
- This permission or feature is only available with business verification. You may also need to sign additional contracts before your app can access data. [Learn More Here]
|
||||
|
||||
[developer documentation]: https://developers.facebook.com/docs/features-reference/oembed-read
|
||||
[Learn More]: https://developers.facebook.com/docs/app-review
|
||||
[Learn More Here]: https://developers.facebook.com/docs/development/release/business-verification
|
||||
|
||||
You must obtain an Access Token to use the `instagram` shortcode.
|
||||
|
||||
If your site configuration is private:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[services.instagram]
|
||||
accessToken = 'xxx'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
If your site configuration is _not_ private, set the Access Token with an environment variable:
|
||||
|
||||
```sh
|
||||
HUGO_SERVICES_INSTAGRAM_ACCESSTOKEN=xxx hugo --gc --minify
|
||||
```
|
||||
### instagram
|
||||
|
||||
{{% note %}}
|
||||
If you are using a Client Access Token, you must combine the Access Token with your App ID using a pipe symbol (`APPID|ACCESSTOKEN`).
|
||||
To override Hugo's embedded `instagram` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
[source code]: {{% eturl instagram %}}
|
||||
{{% /note %}}
|
||||
|
||||
To display an Instagram post with this URL:
|
||||
|
||||
```text
|
||||
https://www.instagram.com/p/BWNjjyYFxVx/
|
||||
https://www.instagram.com/p/CxOWiQNP2MO/
|
||||
```
|
||||
|
||||
Include this in your markdown:
|
||||
Include this in your Markdown:
|
||||
|
||||
```text
|
||||
{{</* instagram BWNjjyYFxVx */>}}
|
||||
```
|
||||
|
||||
### `param`
|
||||
|
||||
Gets a value from the current `Page's` parameters set in front matter, with a fallback to the site parameter value. It will log an `ERROR` if the parameter with the given key could not be found in either.
|
||||
|
||||
```sh
|
||||
{{</* param testparam */>}}
|
||||
```
|
||||
|
||||
Since `testparam` is a parameter defined in front matter of this page with the value `Hugo Rocks!`, the above will print:
|
||||
|
||||
{{< param testparam >}}
|
||||
|
||||
To access deeply nested parameters, use "dot syntax", e.g:
|
||||
|
||||
```sh
|
||||
{{</* param "my.nested.param" */>}}
|
||||
```
|
||||
|
||||
### `ref` and `relref`
|
||||
|
||||
These shortcodes will look up the pages by their relative path (e.g., `blog/post.md`) or their logical name (`post.md`) and return the permalink (`ref`) or relative permalink (`relref`) for the found page.
|
||||
|
||||
`ref` and `relref` also make it possible to make fragmentary links that work for the header links generated by Hugo.
|
||||
|
||||
{{% note %}}
|
||||
Read a more extensive description of `ref` and `relref` in the [cross references](/content-management/cross-references/) documentation.
|
||||
{{% /note %}}
|
||||
|
||||
`ref` and `relref` take exactly one required parameter of _reference_, quoted and in position `0`.
|
||||
|
||||
#### Example `ref` and `relref` input
|
||||
|
||||
```go-html-template
|
||||
[Neat]({{</* ref "blog/neat.md" */>}})
|
||||
[Who]({{</* relref "about.md#who" */>}})
|
||||
```
|
||||
|
||||
#### Example `ref` and `relref` output
|
||||
|
||||
Assuming that standard Hugo pretty URLs are turned on.
|
||||
|
||||
```html
|
||||
<a href="https://example.org/blog/neat">Neat</a>
|
||||
<a href="/about/#who">Who</a>
|
||||
```
|
||||
|
||||
### `tweet`
|
||||
|
||||
To display a Twitter post with this URL:
|
||||
|
||||
```txt
|
||||
https://twitter.com/SanDiegoZoo/status/1453110110599868418
|
||||
```
|
||||
|
||||
Include this in your markdown:
|
||||
|
||||
```text
|
||||
{{</* tweet user="SanDiegoZoo" id="1453110110599868418" */>}}
|
||||
{{</* instagram CxOWiQNP2MO */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< tweet user="SanDiegoZoo" id="1453110110599868418" >}}
|
||||
{{< instagram CxOWiQNP2MO >}}
|
||||
|
||||
### `vimeo`
|
||||
### param
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `param` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
[source code]: {{% eturl param %}}
|
||||
{{% /note %}}
|
||||
|
||||
The `param` shortcode renders a parameter from the page's front matter, falling back to a site parameter of the same name. The shortcode throws an error if the parameter does not exist.
|
||||
|
||||
Example usage:
|
||||
|
||||
```text
|
||||
{{</* param testparam */>}}
|
||||
```
|
||||
|
||||
Access nested values by [chaining] the [identifiers]:
|
||||
|
||||
[chaining]: /getting-started/glossary/#chain
|
||||
[identifiers]: /getting-started/glossary/#identifier
|
||||
|
||||
```text
|
||||
{{</* param my.nested.param */>}}
|
||||
```
|
||||
|
||||
### ref
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `ref` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
Always use the `{{%/* */%}}` notation when calling this shortcode.
|
||||
|
||||
[source code]: {{% eturl ref %}}
|
||||
{{% /note %}}
|
||||
|
||||
The `ref` shortcode returns the permalink of the given page reference.
|
||||
|
||||
Example usage:
|
||||
|
||||
```text
|
||||
[Post 1]({{%/* ref "/posts/post-1" */%}})
|
||||
[Post 1]({{%/* ref "/posts/post-1.md" */%}})
|
||||
[Post 1]({{%/* ref "/posts/post-1#foo" */%}})
|
||||
[Post 1]({{%/* ref "/posts/post-1.md#foo" */%}})
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
```html
|
||||
<a href="http://example.org/posts/post-1/">Post 1</a>
|
||||
<a href="http://example.org/posts/post-1/">Post 1</a>
|
||||
<a href="http://example.org/posts/post-1/#foo">Post 1</a>
|
||||
<a href="http://example.org/posts/post-1/#foo">Post 1</a>
|
||||
```
|
||||
|
||||
### relref
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `relref` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
Always use the `{{%/* */%}}` notation when calling this shortcode.
|
||||
|
||||
[source code]: {{% eturl relref %}}
|
||||
{{% /note %}}
|
||||
|
||||
The `relref` shortcode returns the permalink of the given page reference.
|
||||
|
||||
Example usage:
|
||||
|
||||
```text
|
||||
[Post 1]({{%/* relref "/posts/post-1" */%}})
|
||||
[Post 1]({{%/* relref "/posts/post-1.md" */%}})
|
||||
[Post 1]({{%/* relref "/posts/post-1#foo" */%}})
|
||||
[Post 1]({{%/* relref "/posts/post-1.md#foo" */%}})
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
```html
|
||||
<a href="/posts/post-1/">Post 1</a>
|
||||
<a href="/posts/post-1/">Post 1</a>
|
||||
<a href="/posts/post-1/#foo">Post 1</a>
|
||||
<a href="/posts/post-1/#foo">Post 1</a>
|
||||
```
|
||||
|
||||
### twitter
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `twitter` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
You may call the `twitter` shortcode by using its `tweet` alias.
|
||||
|
||||
[source code]: {{% eturl twitter %}}
|
||||
{{% /note %}}
|
||||
|
||||
To display a Twitter post with this URL:
|
||||
|
||||
```txt
|
||||
https://x.com/SanDiegoZoo/status/1453110110599868418
|
||||
```
|
||||
|
||||
Include this in your Markdown:
|
||||
|
||||
```text
|
||||
{{</* twitter user="SanDiegoZoo" id="1453110110599868418" */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< twitter user="SanDiegoZoo" id="1453110110599868418" >}}
|
||||
|
||||
### vimeo
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `vimeo` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
[source code]: {{% eturl vimeo %}}
|
||||
{{% /note %}}
|
||||
|
||||
To display a Vimeo video with this URL:
|
||||
|
||||
|
|
@ -318,7 +369,7 @@ To display a Vimeo video with this URL:
|
|||
https://vimeo.com/channels/staffpicks/55073825
|
||||
```
|
||||
|
||||
Include this in your markdown:
|
||||
Include this in your Markdown:
|
||||
|
||||
```text
|
||||
{{</* vimeo 55073825 */>}}
|
||||
|
|
@ -329,76 +380,98 @@ Rendered:
|
|||
{{< vimeo 55073825 >}}
|
||||
|
||||
{{% note %}}
|
||||
If you want to further customize the visual styling of the YouTube or Vimeo output, add a `class` named parameter when calling the shortcode. The new `class` will be added to the `<div>` that wraps the `<iframe>` *and* will remove the inline styles. Note that you will need to call the `id` as a named parameter as well. You can also give the vimeo video a descriptive title with `title`.
|
||||
If you want to further customize the visual styling, add a `class` argument when calling the shortcode. The new `class` will be added to the `<div>` that wraps the `<iframe>` *and* will remove the inline styles. Note that you will need to call the `id` as a named argument as well. You can also give the vimeo video a descriptive title with `title`.
|
||||
|
||||
```go
|
||||
{{</* vimeo id="146022717" class="my-vimeo-wrapper-class" title="My vimeo video" */>}}
|
||||
```
|
||||
{{% /note %}}
|
||||
|
||||
### `youtube`
|
||||
### youtube
|
||||
|
||||
The `youtube` shortcode embeds a responsive video player for [YouTube videos]. Only the ID of the video is required, e.g.:
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `youtube` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
```txt
|
||||
https://www.youtube.com/watch?v=w7Ft2ymGmfc
|
||||
[source code]: {{% eturl youtube %}}
|
||||
{{% /note %}}
|
||||
|
||||
To display a YouTube video with this URL:
|
||||
|
||||
```text
|
||||
https://www.youtube.com/watch?v=0RKpf3rK57I
|
||||
```
|
||||
|
||||
#### Example `youtube` input
|
||||
Include this in your Markdown:
|
||||
|
||||
Copy the YouTube video ID that follows `v=` in the video's URL and pass it to the `youtube` shortcode:
|
||||
```text
|
||||
{{</* youtube 0RKpf3rK57I */>}}
|
||||
```
|
||||
|
||||
{{< code file=example-youtube-input.md >}}
|
||||
{{</* youtube w7Ft2ymGmfc */>}}
|
||||
{{< /code >}}
|
||||
Rendered:
|
||||
|
||||
Furthermore, you can automatically start playback of the embedded video by setting the `autoplay` parameter to `true`. Remember that you can't mix named and unnamed parameters, so you'll need to assign the yet unnamed video ID to the parameter `id`:
|
||||
{{< youtube 0RKpf3rK57I >}}
|
||||
|
||||
{{< code file=example-youtube-input-with-autoplay.md >}}
|
||||
{{</* youtube id="w7Ft2ymGmfc" autoplay="true" */>}}
|
||||
{{< /code >}}
|
||||
The youtube shortcode accepts these named arguments:
|
||||
|
||||
For [accessibility reasons](https://dequeuniversity.com/tips/provide-iframe-titles), it's best to provide a title for your YouTube video. You can do this using the shortcode by providing a `title` parameter. If no title is provided, a default of "YouTube Video" will be used.
|
||||
id
|
||||
: (`string`) The video `id`. Optional if the `id` is provided as a positional argument as shown in the example above.
|
||||
|
||||
{{< code file=example-youtube-input-with-title.md >}}
|
||||
{{</* youtube id="w7Ft2ymGmfc" title="A New Hugo Site in Under Two Minutes" */>}}
|
||||
{{< /code >}}
|
||||
allowFullScreen
|
||||
{{< new-in 0.125.0 >}}
|
||||
: (`bool`) Whether the `iframe` element can activate full screen mode. Default is `true`.
|
||||
|
||||
#### Example `youtube` output
|
||||
autoplay
|
||||
{{< new-in 0.125.0 >}}
|
||||
: (`bool`) Whether to automatically play the video. Forces `mute` to `true`. Default is `false`.
|
||||
|
||||
Using the preceding `youtube` example, the following HTML will be added to your rendered website's markup:
|
||||
class
|
||||
: (`string`) The `class` attribute of the wrapping `div` element. When specified, removes the `style` attributes from the `iframe` element and its wrapping `div` element.
|
||||
|
||||
{{< code file=example-youtube-output.html >}}
|
||||
{{< youtube id="w7Ft2ymGmfc" autoplay="true" >}}
|
||||
{{< /code >}}
|
||||
controls
|
||||
{{< new-in 0.125.0 >}}
|
||||
: (`bool`) Whether to display the video controls. Default is `true`.
|
||||
|
||||
#### Example `youtube` display
|
||||
end
|
||||
{{< new-in 0.125.0 >}}
|
||||
: (`int`) The time, measured in seconds from the start of the video, when the player should stop playing the video.
|
||||
|
||||
Using the preceding `youtube` example (without `autoplay="true"`), the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your style sheets and surrounding markup. The video is also include in the [Quick Start of the Hugo documentation][quickstart].
|
||||
loading
|
||||
{{< new-in 0.125.0 >}}
|
||||
: (`string`) The loading attribute of the `iframe` element, either `eager` or `lazy`. Default is `eager`.
|
||||
|
||||
{{< youtube w7Ft2ymGmfc >}}
|
||||
loop
|
||||
{{< new-in 0.125.0 >}}
|
||||
: (`bool`) Whether to indefinitely repeat the video. Ignores the `start` and `end` arguments after the first play. Default is `false`.
|
||||
|
||||
mute
|
||||
{{< new-in 0.125.0 >}}
|
||||
: (`bool`) Whether to mute the video. Always `true` when `autoplay` is `true`. Default is `false`.
|
||||
|
||||
start
|
||||
{{< new-in 0.125.0 >}}
|
||||
: (`int`) The time, measured in seconds from the start of the video, when the player should start playing the video.
|
||||
|
||||
title
|
||||
: (`string`) The `title` attribute of the `iframe` element. Defaults to "YouTube video".
|
||||
|
||||
Example using some of the above:
|
||||
|
||||
```text
|
||||
{{</* youtube id=0RKpf3rK57I start=30 end=60 loading=lazy */>}}
|
||||
```
|
||||
|
||||
## Privacy configuration
|
||||
|
||||
To learn how to configure your Hugo site to meet the new EU privacy regulation, see [Hugo and the GDPR].
|
||||
To learn how to configure your Hugo site to meet the new EU privacy regulation, see [privacy protections].
|
||||
|
||||
## Create custom shortcodes
|
||||
|
||||
To learn more about creating custom shortcodes, see the [shortcode template documentation].
|
||||
|
||||
[`figure` shortcode]: #figure
|
||||
[contentmanagementsection]: /content-management/formats/
|
||||
[examplegist]: https://gist.github.com/spf13/7896402
|
||||
[figureelement]: https://html5doctor.com/the-figure-figcaption-elements/
|
||||
[Hugo and the GDPR]: /about/hugo-and-gdpr/
|
||||
[Instagram]: https://www.instagram.com/
|
||||
[pagevariables]: /variables/page/
|
||||
[privacy protections]: /about/privacy/
|
||||
[partials]: /templates/partials/
|
||||
[quickstart]: /getting-started/quick-start/
|
||||
[sctemps]: /templates/shortcode-templates/
|
||||
[scvars]: /variables/shortcode/
|
||||
[shortcode template documentation]: /templates/shortcode-templates/
|
||||
[templatessection]: /templates/
|
||||
[Vimeo]: https://vimeo.com/
|
||||
[YouTube Videos]: https://www.youtube.com/
|
||||
[YouTube Input shortcode]: #youtube
|
||||
|
|
|
|||
|
|
@ -1,68 +0,0 @@
|
|||
---
|
||||
title: Static files
|
||||
description: Files that get served **statically** (as-is, no modification) on the site root.
|
||||
categories: [content management]
|
||||
keywords: [source, directories]
|
||||
menu:
|
||||
docs:
|
||||
parent: content-management
|
||||
weight: 200
|
||||
weight: 200
|
||||
toc: true
|
||||
aliases: [/static-files]
|
||||
---
|
||||
|
||||
By default, the `static/` directory in the site project is used for
|
||||
all **static files** (e.g. stylesheets, JavaScript, images). The static files are served on the site root path (eg. if you have the file `static/image.png` you can access it using `http://{server-url}/image.png`, to include it in a document you can use ` )`.
|
||||
|
||||
Hugo can be configured to look into a different directory, or even
|
||||
**multiple directories** for such static files by configuring the
|
||||
`staticDir` parameter in the [site configuration]. All the files in all the
|
||||
static directories will form a union filesystem.
|
||||
|
||||
This union filesystem will be served from your site root. So a file
|
||||
`<SITE PROJECT>/static/me.png` will be accessible as
|
||||
`<MY_BASEURL>/me.png`.
|
||||
|
||||
Here's an example of setting `staticDir` and `staticDir2` for a
|
||||
multi-language site:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
staticDir = ["static1", "static2"]
|
||||
|
||||
[languages]
|
||||
[languages.en]
|
||||
staticDir2 = "static_en"
|
||||
baseURL = "https://example.org/"
|
||||
languageName = "English"
|
||||
weight = 2
|
||||
title = "In English"
|
||||
[languages.no]
|
||||
staticDir = ["staticDir_override", "static_no"]
|
||||
baseURL = "https://example.no"
|
||||
languageName = "Norsk"
|
||||
weight = 1
|
||||
title = "På norsk"
|
||||
{{</ code-toggle >}}
|
||||
|
||||
In the above, with no theme used:
|
||||
|
||||
- The English site will get its static files as a union of "static1",
|
||||
"static2" and "static_en". On file duplicates, the right-most
|
||||
version will win.
|
||||
- The Norwegian site will get its static files as a union of
|
||||
"staticDir_override" and "static_no".
|
||||
|
||||
Note 1
|
||||
: The **2** (can be a number between 0 and 10) in `staticDir2` is
|
||||
added to tell Hugo that you want to **add** this directory to the
|
||||
global set of static directories defined using `staticDir`. Using
|
||||
`staticDir` on the language level would replace the global value (as
|
||||
can be seen in the Norwegian site case).
|
||||
|
||||
Note 2
|
||||
: The example above is a [multihost setup]. In a regular setup, all
|
||||
the static directories will be available to all sites.
|
||||
|
||||
[site configuration]: /getting-started/configuration/#all-configuration-settings
|
||||
[multihost setup]: /content-management/multilingual/#configure-multilingual-multihost
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
title: Content summaries
|
||||
linkTitle: Summaries
|
||||
description: Hugo generates summaries of your content.
|
||||
description: Create and render content summaries.
|
||||
categories: [content management]
|
||||
keywords: [summaries,abstracts,read more]
|
||||
menu:
|
||||
|
|
@ -13,98 +13,105 @@ toc: true
|
|||
aliases: [/content/summaries/,/content-management/content-summaries/]
|
||||
---
|
||||
|
||||
<!-- Do not remove the manual summary divider below. -->
|
||||
<!-- If you do, you will break its first literal usage on this page. -->
|
||||
<!--more-->
|
||||
|
||||
With the use of the `.Summary` [page variable][pagevariables], Hugo generates summaries of content to use as a short version in summary views.
|
||||
You can define a content summary manually, in front matter, or automatically. A manual content summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary.
|
||||
|
||||
## Summary splitting options
|
||||
Review the [comparison table](#comparison) below to understand the characteristics of each summary type.
|
||||
|
||||
* Automatic Summary Split
|
||||
* Manual Summary Split
|
||||
* Front Matter Summary
|
||||
## Manual summary
|
||||
|
||||
It is natural to accompany the summary with links to the original content, and a common design pattern is to see this link in the form of a "Read More ..." button. See the `.RelPermalink`, `.Permalink`, and `.Truncated` [page variables][pagevariables].
|
||||
Use a `<!--more-->` divider to indicate the end of the content summary. Hugo will not render the summary divider itself.
|
||||
|
||||
### Automatic summary splitting
|
||||
{{< code file=content/sample.md >}}
|
||||
+++
|
||||
title: 'Example'
|
||||
date: 2024-05-26T09:10:33-07:00
|
||||
+++
|
||||
|
||||
By default, Hugo automatically takes the first 70 words of your content as its summary and stores it into the `.Summary` page variable for use in your templates. You may customize the summary length by setting `summaryLength` in your [site configuration](/getting-started/configuration/).
|
||||
Thénardier was not mistaken. The man was sitting there, and letting
|
||||
Cosette get somewhat rested.
|
||||
|
||||
{{% note %}}
|
||||
You can customize how HTML tags in the summary are loaded using functions such as `plainify` and `safeHTML`.
|
||||
{{% /note %}}
|
||||
<!--more-->
|
||||
|
||||
{{% note %}}
|
||||
The Hugo-defined summaries are set to use word count calculated by splitting the text by one or more consecutive whitespace characters. If you are creating content in a `CJK` language and want to use Hugo's automatic summary splitting, set `hasCJKLanguage` to `true` in your [site configuration](/getting-started/configuration/).
|
||||
{{% /note %}}
|
||||
|
||||
### Manual summary splitting
|
||||
|
||||
Alternatively, you may add the `<!--more-->` summary divider where you want to split the article.
|
||||
|
||||
For [Org mode content][org], use `# more` where you want to split the article.
|
||||
|
||||
Content that comes before the summary divider will be used as that content's summary and stored in the `.Summary` page variable with all HTML formatting intact.
|
||||
|
||||
{{% note %}}
|
||||
The concept of a *summary divider* is not unique to Hugo. It is also called the "more tag" or "excerpt separator" in other literature.
|
||||
{{% /note %}}
|
||||
|
||||
Pros
|
||||
: Freedom, precision, and improved rendering. All HTML tags and formatting are preserved.
|
||||
|
||||
Cons
|
||||
: Extra work for content authors, since they need to remember to type `<!--more-->` (or `# more` for [org content][org]) in each content file. This can be automated by adding the summary divider below the front matter of an [archetype](/content-management/archetypes/).
|
||||
|
||||
{{% note %}}
|
||||
Be careful to enter `<!--more-->` exactly; i.e., all lowercase and with no whitespace.
|
||||
{{% /note %}}
|
||||
|
||||
### Front matter summary
|
||||
|
||||
You might want your summary to be something other than the text that starts the article. In this case you can provide a separate summary in the `summary` variable of the article front matter.
|
||||
|
||||
Pros
|
||||
: Complete freedom of text independent of the content of the article. Markup can be used within the summary.
|
||||
|
||||
Cons
|
||||
: Extra work for content authors as they need to write an entirely separate piece of text as the summary of the article.
|
||||
|
||||
## Summary selection order
|
||||
|
||||
Because there are multiple ways in which a summary can be specified it is useful to understand the order of selection Hugo follows when deciding on the text to be returned by `.Summary`. It is as follows:
|
||||
|
||||
1. If there is a `<!--more-->` summary divider present in the article, the text up to the divider will be provided as per the manual summary split method
|
||||
2. If there is a `summary` variable in the article front matter the value of the variable will be provided as per the front matter summary method
|
||||
3. The text at the start of the article will be provided as per the automatic summary split method
|
||||
|
||||
{{% note %}}
|
||||
Hugo uses the _first_ of the above steps that returns text. So if, for example, your article has both `summary` variable in its front matter and a `<!--more-->` summary divider Hugo will use the manual summary split method.
|
||||
{{% /note %}}
|
||||
|
||||
## Example: first 10 articles with summaries
|
||||
|
||||
You can show content summaries with the following code. You could use the following snippet, for example, in a [section template].
|
||||
|
||||
{{< code file=page-list-with-summaries.html >}}
|
||||
{{ range first 10 .Pages }}
|
||||
<article>
|
||||
<!-- this <div> includes the title summary -->
|
||||
<div>
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
|
||||
{{ .Summary }}
|
||||
</div>
|
||||
{{ if .Truncated }}
|
||||
<!-- This <div> includes a read more link, but only if the summary is truncated... -->
|
||||
<div>
|
||||
<a href="{{ .RelPermalink }}">Read More…</a>
|
||||
</div>
|
||||
{{ end }}
|
||||
</article>
|
||||
{{ end }}
|
||||
The inn-keeper walked round the brushwood and presented himself
|
||||
abruptly to the eyes of those whom he was in search of.
|
||||
{{< /code >}}
|
||||
|
||||
Note how the `.Truncated` boolean variable value may be used to hide the "Read More..." link when the content is not truncated; i.e., when the summary contains the entire article.
|
||||
When using the Emacs Org Mode [content format], use a `# more` divider to indicate the end of the content summary.
|
||||
|
||||
[org]: /content-management/formats/
|
||||
[pagevariables]: /variables/page/
|
||||
[section template]: /templates/section-templates/
|
||||
[content format]: /content-management/formats/
|
||||
|
||||
## Front matter summary
|
||||
|
||||
Use front matter to define a summary independent of content.
|
||||
|
||||
{{< code file=content/sample.md >}}
|
||||
+++
|
||||
title: 'Example'
|
||||
date: 2024-05-26T09:10:33-07:00
|
||||
summary: 'Learn more about _Les Misérables_ by Victor Hugo.'
|
||||
+++
|
||||
|
||||
Thénardier was not mistaken. The man was sitting there, and letting
|
||||
Cosette get somewhat rested. The inn-keeper walked round the
|
||||
brushwood and presented himself abruptly to the eyes of those whom
|
||||
he was in search of.
|
||||
{{< /code >}}
|
||||
|
||||
## Automatic summary
|
||||
|
||||
If you have not defined the summary manually or in front matter, Hugo automatically defines the summary based on the [`summaryLength`] in your site configuration.
|
||||
|
||||
[`summaryLength`]: /getting-started/configuration/#summarylength
|
||||
|
||||
{{< code file=content/sample.md >}}
|
||||
+++
|
||||
title: 'Example'
|
||||
date: 2024-05-26T09:10:33-07:00
|
||||
+++
|
||||
|
||||
Thénardier was not mistaken. The man was sitting there, and letting
|
||||
Cosette get somewhat rested. The inn-keeper walked round the
|
||||
brushwood and presented himself abruptly to the eyes of those whom
|
||||
he was in search of.
|
||||
{{< /code >}}
|
||||
|
||||
For example, with a `summaryLength` of 10, the automatic summary will be:
|
||||
|
||||
```text
|
||||
Thénardier was not mistaken. The man was sitting there, and letting
|
||||
Cosette get somewhat rested.
|
||||
```
|
||||
|
||||
Note that the `summaryLength` is an approximate number of words.
|
||||
|
||||
## Comparison
|
||||
|
||||
Each summary type has different characteristics:
|
||||
|
||||
Type|Precedence|Renders markdown|Renders shortcodes|Strips HTML tags|Wraps single lines with `<p>`
|
||||
:--|:-:|:-:|:-:|:-:|:-:
|
||||
Manual|1|:heavy_check_mark:|:heavy_check_mark:|:x:|:heavy_check_mark:
|
||||
Front matter|2|:heavy_check_mark:|:x:|:x:|:x:
|
||||
Automatic|3|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:x:
|
||||
|
||||
## Rendering
|
||||
|
||||
Render the summary in a template by calling the [`Summary`] method on a `Page` object.
|
||||
|
||||
[`Summary`]: /methods/page/summary
|
||||
|
||||
```go-html-template
|
||||
{{ range site.RegularPages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
<div class="summary">
|
||||
{{ .Summary }}
|
||||
{{ if .Truncated }}
|
||||
<a href="{{ .RelPermalink }}">More ...</a>
|
||||
{{ end }}
|
||||
</div>
|
||||
{{ end }}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -6,8 +6,8 @@ keywords: [highlighting,chroma,code blocks,syntax]
|
|||
menu:
|
||||
docs:
|
||||
parent: content-management
|
||||
weight: 240
|
||||
weight: 240
|
||||
weight: 250
|
||||
weight: 250
|
||||
toc: true
|
||||
aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/]
|
||||
---
|
||||
|
|
@ -20,7 +20,7 @@ See [Configure Highlight](/getting-started/configuration-markup#highlight).
|
|||
|
||||
## Generate syntax highlighter CSS
|
||||
|
||||
If you run with `markup.highlight.noClasses=false` in your site configuration, you need a style sheet.
|
||||
If you run with `markup.highlight.noClasses=false` in your site configuration, you need a style sheet. The style sheet will override the style specified in [`markup.highlight.style`](/functions/transform/highlight/#options).
|
||||
|
||||
You can generate one with Hugo:
|
||||
|
||||
|
|
@ -32,7 +32,7 @@ Run `hugo gen chromastyles -h` for more options. See https://xyproto.github.io/s
|
|||
|
||||
## Highlight shortcode
|
||||
|
||||
Highlighting is carried out via the built-in [`highlight` shortcode](/content-management/shortcodes/#highlight). It takes exactly one required parameter for the programming language to be highlighted and requires a closing shortcode.
|
||||
Highlighting is carried out via the built-in [`highlight` shortcode](/content-management/shortcodes/#highlight). It takes exactly one required argument for the programming language to be highlighted and requires a closing tag.
|
||||
|
||||
Options:
|
||||
|
||||
|
|
|
|||
|
|
@ -130,26 +130,15 @@ If you want to disable all taxonomies altogether, see the use of `disableKinds`
|
|||
You can add content and front matter to your taxonomy list and taxonomy terms pages. See [Content Organization](/content-management/organization/) for more information on how to add an `_index.md` for this purpose.
|
||||
{{% /note %}}
|
||||
|
||||
## Add taxonomies to content
|
||||
## Assign terms to content
|
||||
|
||||
Once a taxonomy is defined at the site level, any piece of content can be assigned to it, regardless of [content type] or [content section].
|
||||
|
||||
Assigning content to a taxonomy is done in the [front matter]. Simply create a variable with the *plural* name of the taxonomy and assign all terms you want to apply to the instance of the content type.
|
||||
|
||||
{{% note %}}
|
||||
If you would like the ability to quickly generate content files with preconfigured taxonomies or terms, read the docs on [Hugo archetypes](/content-management/archetypes/).
|
||||
{{% /note %}}
|
||||
|
||||
### Example: front matter with taxonomies
|
||||
To assign one or more terms to a page, create a front matter field using the plural name of the taxonomy, then add terms to the corresponding array. For example:
|
||||
|
||||
{{< code-toggle file=content/example.md fm=true >}}
|
||||
title = "Hugo: A fast and flexible static site generator"
|
||||
tags = [ "Development", "Go", "fast", "Blogging" ]
|
||||
categories = [ "Development" ]
|
||||
series = [ "Go Web Dev" ]
|
||||
slug = "hugo"
|
||||
project_url = "https://github.com/gohugoio/hugo"
|
||||
{{</ code-toggle >}}
|
||||
title = 'Example'
|
||||
tags = ['Tag A','Tag B']
|
||||
categories = ['Category A','Category B']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## Order taxonomies
|
||||
|
||||
|
|
@ -182,7 +171,7 @@ wikipedia: "https://en.wikipedia.org/wiki/Bruce_Willis"
|
|||
[content type]: /content-management/types/
|
||||
[documentation on archetypes]: /content-management/archetypes/
|
||||
[front matter]: /content-management/front-matter/
|
||||
[taxonomy list templates]: /templates/taxonomy-templates/#taxonomy-list-templates
|
||||
[taxonomy list templates]: /templates/taxonomy-templates/#taxonomy-templates
|
||||
[taxonomy templates]: /templates/taxonomy-templates/
|
||||
[terms within the taxonomy]: /templates/taxonomy-templates/#taxonomy-terms-templates
|
||||
[terms within the taxonomy]: /templates/taxonomy-templates/#term-templates
|
||||
[site configuration]: /getting-started/configuration/
|
||||
|
|
|
|||
|
|
@ -1,117 +0,0 @@
|
|||
---
|
||||
title: Table of contents
|
||||
description: Hugo can automatically parse Markdown content and create a Table of Contents you can use in your templates.
|
||||
categories: [content management]
|
||||
keywords: [table of contents, toc]
|
||||
menu:
|
||||
docs:
|
||||
parent: content-management
|
||||
weight: 210
|
||||
weight: 210
|
||||
toc: true
|
||||
aliases: [/extras/toc/]
|
||||
---
|
||||
|
||||
{{% note %}}
|
||||
|
||||
Previously, there was no out-of-the-box way to specify which heading levels you want the TOC to render. [See the related GitHub discussion (#1778)](https://github.com/gohugoio/hugo/issues/1778). As such, the resulting `<nav id="TableOfContents"><ul></ul></nav>` was going to start at `<h1>` when pulling from `{{ .Content }}`.
|
||||
|
||||
Hugo [v0.60.0](https://github.com/gohugoio/hugo/releases/tag/v0.60.0) made a switch to [Goldmark](https://github.com/yuin/goldmark/) as the default library for Markdown which has improved and configurable implementation of TOC. Take a look at [how to configure TOC](/getting-started/configuration-markup/#table-of-contents) for Goldmark renderer.
|
||||
|
||||
{{% /note %}}
|
||||
|
||||
## Usage
|
||||
|
||||
Create your Markdown the way you normally would with the appropriate headings. Here is some example content:
|
||||
|
||||
```md
|
||||
<!-- Your front matter up here -->
|
||||
|
||||
## Introduction
|
||||
|
||||
One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin.
|
||||
|
||||
## My Heading
|
||||
|
||||
He lay on his armour-like back, and if he lifted his head a little he could see his brown belly, slightly domed and divided by arches into stiff sections. The bedding was hardly able to cover it and seemed ready to slide off any moment.
|
||||
|
||||
### My Subheading
|
||||
|
||||
A collection of textile samples lay spread out on the table - Samsa was a traveling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops
|
||||
```
|
||||
|
||||
Hugo will take this Markdown and create a table of contents from `## Introduction`, `## My Heading`, and `### My Subheading` and then store it in the [page variable][pagevars]`.TableOfContents`.
|
||||
|
||||
The built-in `.TableOfContents` variables outputs a `<nav id="TableOfContents">` element with a child `<ul>`, whose child `<li>` elements begin with appropriate HTML headings. See [the available settings](/getting-started/configuration-markup/#table-of-contents) to configure what heading levels you want to include in TOC.
|
||||
|
||||
## Template example: basic TOC
|
||||
|
||||
The following is an example of a very basic [single page template]:
|
||||
|
||||
{{< code file=layout/_default/single.html >}}
|
||||
{{ define "main" }}
|
||||
<main>
|
||||
<article>
|
||||
<header>
|
||||
<h1>{{ .Title }}</h1>
|
||||
</header>
|
||||
{{ .Content }}
|
||||
</article>
|
||||
<aside>
|
||||
{{ .TableOfContents }}
|
||||
</aside>
|
||||
</main>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
## Template example: TOC partial
|
||||
|
||||
The following is a [partial template][partials] that adds slightly more logic for page-level control over your table of contents. It assumes you are using a `toc` field in your content's [front matter] that, unless specifically set to `false`, will add a TOC to any page with a `.WordCount` (see [Page Variables][pagevars]) greater than 400. This example also demonstrates how to use [conditionals] in your templating:
|
||||
|
||||
{{< code file=layouts/partials/toc.html >}}
|
||||
{{ if and (gt .WordCount 400 ) (.Params.toc) }}
|
||||
<aside>
|
||||
<header>
|
||||
<h2>{{ .Title }}</h2>
|
||||
</header>
|
||||
{{ .TableOfContents }}
|
||||
</aside>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
{{% note %}}
|
||||
With the preceding example, even pages with > 400 words *and* `toc` not set to `false` will not render a table of contents if there are no headings in the page for the `{{ .TableOfContents }}` variable to pull from.
|
||||
{{% /note %}}
|
||||
|
||||
## Usage with AsciiDoc
|
||||
|
||||
Hugo supports table of contents with AsciiDoc content format.
|
||||
|
||||
In the header of your content file, specify the AsciiDoc TOC directives necessary to ensure that the table of contents is generated. Hugo will use the generated TOC to populate the page variable `.TableOfContents` in the same way as described for Markdown. See example below:
|
||||
|
||||
```asciidoc
|
||||
// <!-- Your front matter up here -->
|
||||
:toc:
|
||||
// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] configuration key
|
||||
:toclevels: 4
|
||||
|
||||
== Introduction
|
||||
|
||||
One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin.
|
||||
|
||||
== My Heading
|
||||
|
||||
He lay on his armour-like back, and if he lifted his head a little he could see his brown belly, slightly domed and divided by arches into stiff sections. The bedding was hardly able to cover it and seemed ready to slide off any moment.
|
||||
|
||||
=== My Subheading
|
||||
|
||||
A collection of textile samples lay spread out on the table - Samsa was a traveling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops
|
||||
```
|
||||
|
||||
Hugo will take this AsciiDoc and create a table of contents store it in the page variable `.TableOfContents`, in the same as described for Markdown.
|
||||
|
||||
[conditionals]: /templates/introduction/#conditionals
|
||||
[front matter]: /content-management/front-matter/
|
||||
[pagevars]: /variables/page/
|
||||
[partials]: /templates/partials/
|
||||
[single page template]: /templates/single-page-templates/
|
||||
|
|
@ -89,12 +89,10 @@ If you set both `slug` and `url` in front matter, the `url` value takes preceden
|
|||
|
||||
### Permalinks
|
||||
|
||||
In your site configuration, define a URL pattern for each top-level section. Each URL pattern can target a given language and/or [page kind].
|
||||
In your site configuration, define a URL pattern for each top-level section. Each URL pattern can target a given language and/or page kind.
|
||||
|
||||
Front matter `url` values override the URL patterns defined in the `permalinks` section of your site configuration.
|
||||
|
||||
[page kind]: /templates/section-templates/#page-kinds
|
||||
|
||||
#### Monolingual examples {#permalinks-monolingual-examples}
|
||||
|
||||
With this content structure:
|
||||
|
|
@ -235,46 +233,46 @@ public/
|
|||
|
||||
#### Tokens
|
||||
|
||||
Use these tokens when defining the URL pattern. The `date` field in front matter determines the value of time-related tokens.
|
||||
Use these tokens when defining the URL pattern.
|
||||
|
||||
`:year`
|
||||
: the 4-digit year
|
||||
: The 4-digit year as defined in the front matter `date` field.
|
||||
|
||||
`:month`
|
||||
: the 2-digit month
|
||||
: The 2-digit month as defined in the front matter `date` field.
|
||||
|
||||
`:monthname`
|
||||
: the name of the month
|
||||
: The name of the month as defined in the front matter `date` field.
|
||||
|
||||
`:day`
|
||||
: the 2-digit day
|
||||
: The 2-digit day as defined in the front matter `date` field.
|
||||
|
||||
`:weekday`
|
||||
: the 1-digit day of the week (Sunday = 0)
|
||||
: The 1-digit day of the week as defined in the front matter `date` field (Sunday = 0).
|
||||
|
||||
`:weekdayname`
|
||||
: the name of the day of the week
|
||||
: The name of the day of the week as defined in the front matter `date` field.
|
||||
|
||||
`:yearday`
|
||||
: the 1- to 3-digit day of the year
|
||||
: The 1- to 3-digit day of the year as defined in the front matter `date` field.
|
||||
|
||||
`:section`
|
||||
: the content's section
|
||||
: The content's section.
|
||||
|
||||
`:sections`
|
||||
: the content's sections hierarchy. You can use a selection of the sections using _slice syntax_: `:sections[1:]` includes all but the first, `:sections[:last]` includes all but the last, `:sections[last]` includes only the last, `:sections[1:2]` includes section 2 and 3. Note that this slice access will not throw any out-of-bounds errors, so you don't have to be exact.
|
||||
: The content's sections hierarchy. You can use a selection of the sections using _slice syntax_: `:sections[1:]` includes all but the first, `:sections[:last]` includes all but the last, `:sections[last]` includes only the last, `:sections[1:2]` includes section 2 and 3. Note that this slice access will not throw any out-of-bounds errors, so you don't have to be exact.
|
||||
|
||||
`:title`
|
||||
: the content's title
|
||||
: The title as defined in front matter, else the automatic title. Hugo generates titles automatically for section, taxonomy, and term pages that are not backed by a file.
|
||||
|
||||
`:slug`
|
||||
: the content's slug (or title if no slug is provided in the front matter)
|
||||
|
||||
`:slugorfilename`
|
||||
: the content's slug (or file name if no slug is provided in the front matter)
|
||||
: The slug as defined in front matter, else the title as defined in front matter, else the automatic title. Hugo generates titles automatically for section, taxonomy, and term pages that are not backed by a file.
|
||||
|
||||
`:filename`
|
||||
: the content's file name (without extension)
|
||||
: The content's file name without extension, applicable to the `page` page kind.
|
||||
|
||||
`:slugorfilename`
|
||||
: The slug as defined in front matter, else the content's file name without extension, applicable to the `page` page kind.
|
||||
|
||||
For time-related values, you can also use the layout string components defined in Go's [time package]. For example:
|
||||
|
||||
|
|
@ -307,7 +305,7 @@ Hugo provides two mutually exclusive configuration options to alter URLs _after_
|
|||
#### Canonical URLs
|
||||
|
||||
{{% note %}}
|
||||
This is a legacy configuration option, superseded by template functions and markdown render hooks, and will likely be [removed in a future release].
|
||||
This is a legacy configuration option, superseded by template functions and Markdown render hooks, and will likely be [removed in a future release].
|
||||
|
||||
[removed in a future release]: https://github.com/gohugoio/hugo/issues/4733
|
||||
{{% /note %}}
|
||||
|
|
@ -423,10 +421,12 @@ Hugo renders alias files before rendering pages. A new page with the previous fi
|
|||
|
||||
### Customize
|
||||
|
||||
Create a new template (`layouts/alias.html`) to customize the content of the alias files. The template receives the following context:
|
||||
To override Hugo's embedded `alias` template, copy the [source code] to a file with the same name in the layouts directory. The template receives the following context:
|
||||
|
||||
Permalink
|
||||
: the link to the page being aliased
|
||||
: The link to the page being aliased.
|
||||
|
||||
Page
|
||||
: the Page data for the page being aliased
|
||||
: The Page data for the page being aliased.
|
||||
|
||||
[source code]: {{% eturl alias %}}
|
||||
|
|
|
|||
|
|
@ -1,12 +1,12 @@
|
|||
---
|
||||
title: Contribute to the Hugo project
|
||||
linkTitle: Overview
|
||||
linkTitle: In this section
|
||||
description: Contribute to Hugo development, documentation, and themes.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
identifier: contribute-overview
|
||||
identifier: contribute-in-this-section
|
||||
parent: contribute
|
||||
weight: 10
|
||||
weight: 10
|
||||
|
|
|
|||
|
|
@ -11,8 +11,6 @@ weight: 20
|
|||
toc: true
|
||||
---
|
||||
|
||||
|
||||
|
||||
## Introduction
|
||||
|
||||
You can contribute to the Hugo project by:
|
||||
|
|
@ -146,3 +144,31 @@ Step 9
|
|||
|
||||
Step 10
|
||||
: A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR.
|
||||
|
||||
## Building from source
|
||||
|
||||
You can build, install, and test Hugo at any point in its development history. The examples below build and install the extended version of Hugo.
|
||||
|
||||
To build and install the latest release:
|
||||
|
||||
```sh
|
||||
CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@latest
|
||||
```
|
||||
|
||||
To build and install a specific release:
|
||||
|
||||
```sh
|
||||
CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@v0.126.0
|
||||
```
|
||||
|
||||
To build and install at the latest commit on the master branch:
|
||||
|
||||
```sh
|
||||
CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@master
|
||||
```
|
||||
|
||||
To build and install at a specific commit:
|
||||
|
||||
```sh
|
||||
CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@0851c17
|
||||
```
|
||||
|
|
|
|||
|
|
@ -24,13 +24,13 @@ For documentation related to a new feature, please include the documentation cha
|
|||
|
||||
### Markdown
|
||||
|
||||
Please follow these markdown guidelines:
|
||||
Please follow these guidelines:
|
||||
|
||||
- Use [ATX] headings, not [setext] headings, levels 2 through 4
|
||||
- Use [fenced code blocks], not [indented code blocks]
|
||||
- Use hyphens, not asterisks, with unordered [list items]
|
||||
- Use the [note shortcode] instead of blockquotes
|
||||
- Do not mix [raw HTML] within markdown
|
||||
- Do not mix [raw HTML] within Markdown
|
||||
- Do not use bold text instead of a heading or description term (`dt`)
|
||||
- Remove consecutive blank lines (maximum of two)
|
||||
- Remove trailing spaces
|
||||
|
|
@ -44,15 +44,18 @@ Although we do not strictly adhere to the [Microsoft Writing Style Guide], it is
|
|||
Please link to the [glossary of terms] when necessary, and use the terms consistently throughout the documentation. Of special note:
|
||||
|
||||
- The term "front matter" is two words unless you are referring to the configuration key
|
||||
- The term "standalone" is one word, not hyphenated
|
||||
- Use the word "map" instead of "dictionary"
|
||||
- Use the word "flag" instead of "option" when referring to a command line flag
|
||||
- Capitalize the word "Markdown"
|
||||
- Hyphenate the term "open-source" when used an adjective.
|
||||
|
||||
#### Page titles and headings
|
||||
|
||||
Please follow these guidelines for page titles and headings:
|
||||
|
||||
- Use sentence-style capitalization
|
||||
- Avoid markdown in headings and page titles
|
||||
- Avoid formatted strings in headings and page titles
|
||||
- Shorter is better
|
||||
|
||||
#### Use active voice with present tense
|
||||
|
|
@ -92,11 +95,11 @@ Other guidelines to consider:
|
|||
- When including code samples, use short snippets that demonstrate the concept.
|
||||
- The Hugo user community is global; use [basic english](https://simple.wikipedia.org/wiki/Basic_English) when possible.
|
||||
|
||||
#### Level 6 markdown headings
|
||||
#### Level 6 headings
|
||||
|
||||
Level 6 markdown headings are styled as `dt` elements. This was implemented to support a [glossary] with linkable terms.
|
||||
Level 6 headings are styled as `dt` elements. This was implemented to support a [glossary] with linkable terms.
|
||||
|
||||
[glossary]: /getting-started/glossary
|
||||
[glossary]: /getting-started/glossary/
|
||||
|
||||
## Code examples
|
||||
|
||||
|
|
@ -202,26 +205,6 @@ Rendered:
|
|||
|
||||
These shortcodes are commonly used throughout the documentation. Other shortcodes are available for specialized use.
|
||||
|
||||
### deprecated-in
|
||||
|
||||
Use the “deprecated-in” shortcode to indicate that a feature is deprecated:
|
||||
|
||||
```text
|
||||
{{%/* deprecated-in 0.120.0 */%}}
|
||||
Use [`hugo.IsServer`] instead.
|
||||
|
||||
[`hugo.IsServer`]: /functions/hugo/isserver
|
||||
{{%/* /deprecated-in */%}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{% deprecated-in 0.120.0 %}}
|
||||
Use [`hugo.IsServer`] instead.
|
||||
|
||||
[`hugo.IsServer`]: /functions/hugo/isserver
|
||||
{{% /deprecated-in %}}
|
||||
|
||||
### code
|
||||
|
||||
Use the "code" shortcode for other code examples that require a file name. See the [code examples] above. This shortcode takes these arguments:
|
||||
|
|
@ -233,7 +216,7 @@ file
|
|||
: (`string`) The file name to display.
|
||||
|
||||
lang
|
||||
: (`string`) The code language. If you do not provide a `lang` argument, the code language is determined by the file extension. If the file extension is "html", sets the code language to `go-html-template`. Default is `text`.
|
||||
: (`string`) The code language. If you do not provide a `lang` argument, the code language is determined by the file extension. If the file extension is `html`, sets the code language to `go-html-template`. Default is `text`.
|
||||
|
||||
### code-toggle
|
||||
|
||||
|
|
@ -248,17 +231,54 @@ file
|
|||
fm
|
||||
: (`bool`) Whether the example is front matter. Default is `false`.
|
||||
|
||||
|
||||
### deprecated-in
|
||||
|
||||
Use the “deprecated-in” shortcode to indicate that a feature is deprecated:
|
||||
|
||||
```text
|
||||
{{%/* deprecated-in 0.127.0 */%}}
|
||||
Use [`hugo.IsServer`] instead.
|
||||
|
||||
[`hugo.IsServer`]: /functions/hugo/isserver/
|
||||
{{%/* /deprecated-in */%}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{% deprecated-in 0.127.0 %}}
|
||||
Use [`hugo.IsServer`] instead.
|
||||
|
||||
[`hugo.IsServer`]: /functions/hugo/isserver/
|
||||
{{% /deprecated-in %}}
|
||||
|
||||
### eturl
|
||||
|
||||
Use the embedded template URL (eturl) shortcode to insert an absolute URL to the source code for an embedded template. The shortcode takes a single argument, the base file name of the template (omit the file extension).
|
||||
|
||||
```text
|
||||
This is a link to the [embedded alias template].
|
||||
|
||||
[embedded alias template]: {{%/* eturl alias */%}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
This is a link to the [embedded alias template].
|
||||
|
||||
[embedded alias template]: {{% eturl alias %}}
|
||||
|
||||
### new-in
|
||||
|
||||
Use the "new-in" shortcode to indicate a new feature:
|
||||
|
||||
```text
|
||||
{{</* new-in 0.120.0 */>}}
|
||||
{{</* new-in 0.127.0 */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< new-in 0.120.0 >}}
|
||||
{{< new-in 0.127.0 >}}
|
||||
|
||||
### note
|
||||
|
||||
|
|
@ -288,7 +308,7 @@ Use the "new-in" shortcode to indicate a new feature:
|
|||
{{</* new-in 0.120.0 */>}}
|
||||
{{< /code >}}
|
||||
|
||||
The "new in" label will be hidden if the specified version is older than a predefined threshold, based on differences in major and minor versions. See [details](https://github.com/gohugoio/hugoDocs/blob/master/layouts/shortcodes/new-in.html).
|
||||
The "new in" label will be hidden if the specified version is older than a predefined threshold, based on differences in major and minor versions. See [details](https://github.com/gohugoio/hugoDocs/blob/master/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/new-in.html).
|
||||
|
||||
## Deprecated features
|
||||
|
||||
|
|
@ -298,7 +318,7 @@ Use the "deprecated-in" shortcode to indicate that a feature is deprecated:
|
|||
{{%/* deprecated-in 0.120.0 */%}}
|
||||
Use [`hugo.IsServer`] instead.
|
||||
|
||||
[`hugo.IsServer`]: /functions/hugo/isserver
|
||||
[`hugo.IsServer`]: /functions/hugo/isserver/
|
||||
{{%/* /deprecated-in */%}}
|
||||
{{< /code >}}
|
||||
|
||||
|
|
|
|||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Reference in a new issue