From: Bjørn Erik Pedersen Date: Thu, 23 Feb 2023 06:52:04 +0000 (+0100) Subject: Merge commit 'cf591b7c0c598d34896709db6d28598da37e3ff6' X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=7e539cb39;p=brevno-suite%2Fhugo Merge commit 'cf591b7c0c598d34896709db6d28598da37e3ff6' --- 7e539cb398d8fa3cb17eba7b8ab4ba88b8e9c2ef diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/bep-consulting.svg index 000000000,000000000..5b1170f9b new file mode 100644 --- /dev/null +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/bep-consulting.svg @@@ -1,0 -1,0 +1,3 @@@ ++ ++ ++ diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/butter-dark.svg index 000000000,000000000..657b75c50 new file mode 100644 --- /dev/null +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/butter-dark.svg @@@ -1,0 -1,0 +1,1 @@@ ++ diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/butter-light.svg index 000000000,000000000..a0697df08 new file mode 100644 --- /dev/null +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/butter-light.svg @@@ -1,0 -1,0 +1,1 @@@ ++ diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/esolia-logo.svg index 000000000,000000000..3f5344c61 new file mode 100644 --- /dev/null +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/esolia-logo.svg @@@ -1,0 -1,0 +1,67 @@@ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/graitykit-dark.svg index 000000000,000000000..fd7d12f5c new file mode 100644 --- /dev/null +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/graitykit-dark.svg @@@ -1,0 -1,0 +1,3 @@@ ++ ++ ++ diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/linode-logo.svg index 000000000,000000000..7060e856f new file mode 100644 --- /dev/null +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/linode-logo.svg @@@ -1,0 -1,0 +1,1 @@@ ++ diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/linode-logo_standard_light_medium.png index 000000000,000000000..269e6af84 new file mode 100644 Binary files differ diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/your-company-dark.svg index 000000000,000000000..1793cb644 new file mode 100644 --- /dev/null +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/your-company-dark.svg @@@ -1,0 -1,0 +1,4 @@@ ++ ++ ++ ++ diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/your-company.svg index 000000000,000000000..6f3082b54 new file mode 100644 --- /dev/null +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/images/sponsors/your-company.svg @@@ -1,0 -1,0 +1,4 @@@ ++ ++ ++ ++ diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/data/sponsors.toml index adf26ecdb,000000000..c31178c92 mode 100644,000000..100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/data/sponsors.toml +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/data/sponsors.toml @@@ -1,23 -1,0 +1,24 @@@ +[[banners]] + name = "Linode" + link = "https://www.linode.com/" - logo = "/images/sponsors/linode-logo_standard_light_medium.png" ++ logo = "images/sponsors/linode-logo.svg" + utm_campaign = "hugosponsor" + +[[banners]] + name = "ButterCMS" + link = "https://buttercms.com/hugo-cms/" - logo = "/images/sponsors/butter-light.svg" ++ logo = "images/sponsors/butter-light.svg" + utm_campaign = "sponsorship" + bgcolor = "#131A3E" + +[[banners]] - name = "Your Company?" - link = "https://bep.is/en/hugo-sponsor-2023-01/" - logo = "/images/sponsors/your-company.svg" ++ name = "Gravity Kit" ++ link = "https://www.gravitykit.com/" ++ logo = "images/sponsors/graitykit-dark.svg" ++ query_params = "ref=532&campaign=hugo&" + utm_campaign = "hugosponsor" - bgcolor = "#004887" ++ bgcolor = "#e0ecf3" + + #hugohome + #hugofooter + #hugogithub diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/installation.html index a23cae11d,000000000..cf2989ddb mode 100644,000000..100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/installation.html +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/installation.html @@@ -1,38 -1,0 +1,38 @@@ +
+ + +
+
+

Install in seconds, build in milliseconds.

+

Hugo works on macOS, Windows, Linux, FreeBSD, and others.

+

Host on any server or your favorite CDN.

+
+
+ + +
+
+ Hugo Gopher +
+

macOS

+
+ $ brew install hugo
+
+

Windows

+
- $ choco install hugo -confirm
++ $ choco install hugo-extended
+
+

Linux

+
- $ snap install hugo
++ $ sudo snap install hugo
+
- ++ + +

See the Getting Started Guide for other methods. {{ partial "svg/link-ext.svg" (dict "fill" "#333" "size" "14") }}

+
+ + + + + +
diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/sponsors.html index e0f6670be,000000000..b2915e109 mode 100644,000000..100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/sponsors.html +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/sponsors.html @@@ -1,41 -1,0 +1,38 @@@ +{{ $classes_box := "ba b--dark-gray bg-light-gray br3 flex flex-column flex-wrap items-center justify-center ph3 pv4 mb4 w-100 w-30-l " }} +{{ $gtag := .gtag | default "unknown" }} +{{ $classes_box := "ba b--dark-gray bg-light-gray br3 flex flex-column flex-wrap items-center justify-center ph3 pv4 mb4 w-100 w-30-l " }} +{{ $gtag := .gtag | default "unknown" }} - {{ $utmSource := cond (eq $gtag "footer") "hugofooter" "hugohome" }} ++{{ $isFooter := (eq $gtag "footer") }} ++{{ $utmSource := cond $isFooter "hugofooter" "hugohome" }} +{{ with .cx.Site.Data.sponsors }} +
+
+

Hugo Sponsors

+
+ {{ range .banners }} +
- {{ $url := printf "%s?%s" .link (querify "utm_source" $utmSource "utm_medium" "banner" "utm_campaign" (.utm_campaign | default "hugosponsor")) | safeURL }} - {{ if eq (getenv "HUGO_ENV") "production" | or (eq $.cx.Site.Params.env "production") }} ++ style="background-color: {{ .bgcolor }};"> ++ {{ $query_params := .query_params | default "" }} ++ {{ $url := printf "%s?%s%s" .link $query_params (querify "utm_source" $utmSource "utm_medium" "banner" "utm_campaign" (.utm_campaign | default "hugosponsor")) | safeURL }} ++ {{ $logo := resources.Get .logo }} ++ {{ if hugo.IsProduction }} + {{ $gtagID := printf "Sponsor %s %s" .name $gtag | title }} + - Logo for {{ .name }} ++ class="w-100 grow pa3"> ++ {{ $logo.Content | safeHTML }} + + {{ else }} - - Logo for {{ .name }} ++ ++ {{ $logo.Content | safeHTML }} ++ + {{ end }} +
+ {{ end }} +
+
+
+{{ end }} diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/static/images/icon-h/hugo-h-1.svg index 000000000,000000000..a3a3ba35b new file mode 100644 --- /dev/null +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/static/images/icon-h/hugo-h-1.svg @@@ -1,0 -1,0 +1,11 @@@ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/static/images/icon-h/hugo-h-2.svg index 000000000,000000000..d587f9a1f new file mode 100644 --- /dev/null +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/static/images/icon-h/hugo-h-2.svg @@@ -1,0 -1,0 +1,62 @@@ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/static/images/icon-h/hugo-h-3.svg index 000000000,000000000..c5c3af884 new file mode 100644 --- /dev/null +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/static/images/icon-h/hugo-h-3.svg @@@ -1,0 -1,0 +1,62 @@@ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/static/images/icon-h/hugo-h-4.svg index 000000000,000000000..181bc14b0 new file mode 100644 --- /dev/null +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/static/images/icon-h/hugo-h-4.svg @@@ -1,0 -1,0 +1,62 @@@ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ diff --cc docs/_vendor/modules.txt index 21e85264c,000000000..9e5b08998 mode 100644,000000..100644 --- a/docs/_vendor/modules.txt +++ b/docs/_vendor/modules.txt @@@ -1,1 -1,0 +1,1 @@@ - # github.com/gohugoio/gohugoioTheme v0.0.0-20230109120406-12694c4a9456 ++# github.com/gohugoio/gohugoioTheme v0.0.0-20230124135550-462d5fe4a87f diff --cc docs/content/en/functions/dict.md index 5c8ad9d8a,000000000..dd1e2cd5b mode 100644,000000..100644 --- a/docs/content/en/functions/dict.md +++ b/docs/content/en/functions/dict.md @@@ -1,48 -1,0 +1,48 @@@ +--- +title: dict +description: Creates a dictionary from a list of key and value pairs. +date: 2017-02-01 +publishdate: 2017-02-01 +categories: [functions] +menu: + docs: + parent: "functions" +keywords: [dictionary] +signature: ["dict KEY VALUE [KEY VALUE]..."] +workson: [] +hugoversion: +relatedfuncs: [] +deprecated: false +aliases: [] +--- + +`dict` is especially useful for passing more than one value to a partial template. + +Note that the `key` can be either a `string` or a `string slice`. The latter is useful to create a deeply nested structure, e.g.: + +```go-text-template +{{ $m := dict (slice "a" "b" "c") "value" }} +``` + +## Example: Using `dict` to pass multiple values to a `partial` + +The partial below creates an SVG and expects `fill`, `height` and `width` from the caller: + +### Partial definition + +{{< code file="layouts/partials/svgs/external-links.svg" download="external-links.svg" >}} - + + +{{< /code >}} + +### Partial call + +The `fill`, `height` and `width` values can be stored in one object with `dict` and passed to the partial: + +{{< code file="layouts/_default/list.html" >}} +{{ partial "svgs/external-links.svg" (dict "fill" "#01589B" "width" 10 "height" 20 ) }} +{{< /code >}} + +[partials]: /templates/partials/ diff --cc docs/content/en/functions/findRe.md index 8e08bfc0d,000000000..13d43f896 mode 100644,000000..100644 --- a/docs/content/en/functions/findRe.md +++ b/docs/content/en/functions/findRe.md @@@ -1,40 -1,0 +1,59 @@@ +--- +title: findRE +description: Returns a slice of strings that match the regular expression. +categories: [functions] +menu: + docs: + parent: functions +keywords: [regex] +signature: + - "findRE PATTERN INPUT [LIMIT]" + - "strings.FindRE PATTERN INPUT [LIMIT]" +relatedfuncs: [replaceRE] +aliases: [] +--- +By default, the `findRE` function finds all matches. You can limit the number of matches with an optional LIMIT parameter. + +When specifying the regular expression, use a raw [string literal] (backticks) instead of an interpreted string literal (double quotes) to simplify the syntax. With an interpreted string literal you must escape backslashes. + +The syntax of the regular expression is the same general syntax used by Perl, Python, and other languages. More precisely, it is the syntax accepted by [RE2] except for `\C`. + +This example returns a slice of all second level headings (`h2` elements) within the rendered `.Content`: + +```go-html-template +{{ findRE `(?s).*?` .Content }} +``` + +The `s` flag causes `.` to match `\n` as well, allowing us to find an `h2` element that contains newlines. + +To limit the number of matches to one: + +```go-html-template +{{ findRE `(?s).*?` .Content 1 }} +``` + +{{% note %}} +You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin. +{{% /note %}} + ++## findRESubmatch ++ ++In Hugo 0.110.0 we added a variant of `findRe` that returns a slice of strings holding the text of the leftmost match of the regular expression in s and the matches, if any, of its subexpressions. ++ ++This: ++ ++```go-html-template ++{{ findRESubmatch §§(.+?)§§ §§
  • Foo
  • Bar
    • §§ | print | safeHTML }} ++``` ++ ++Will print: ++ ++``` ++[[Foo #foo Foo] [Bar #bar Bar]] ++``` ++ ++{{< new-in "0.110.0" >}} ++ ++ +[RE2]: https://github.com/google/re2/wiki/Syntax +[string literal]: https://go.dev/ref/spec#String_literals diff --cc docs/content/en/functions/format.md index e2f93f1fc,000000000..5c86714fe mode 100644,000000..100644 --- a/docs/content/en/functions/format.md +++ b/docs/content/en/functions/format.md @@@ -1,126 -1,0 +1,126 @@@ +--- +title: .Format +description: Formats built-in Hugo dates---`.Date`, `.PublishDate`, and `.Lastmod`---according to Go's layout string. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [functions] +menu: + docs: + parent: "functions" +keywords: [dates,time] +signature: [".Format FORMAT"] +workson: [times] +hugoversion: +relatedfuncs: [dateFormat,now,Unix,time] +deprecated: false +aliases: [] +toc: true +--- + +`.Format` will format date values defined in your front matter and can be used as a property on the following [page variables][pagevars]: + +* `.PublishDate` +* `.Date` +* `.Lastmod` + +Assuming a key-value of `date: 2017-03-03` in a content file's front matter, your can run the date through `.Format` followed by a layout string for your desired output at build time: + +``` +{{ .PublishDate.Format "January 2, 2006" }} => March 3, 2017 +``` + +For formatting *any* string representations of dates defined in your front matter, see the [`dateFormat` function][dateFormat], which will still leverage the Go layout string explained below but uses a slightly different syntax. + +## Go's Layout String + +Hugo templates [format your dates][time] via layout strings that point to a specific reference time: + +``` +Mon Jan 2 15:04:05 MST 2006 +``` + +While this may seem arbitrary, the numerical value of `MST` is `07`, thus making the layout string a sequence of numbers. + +Here is a visual explanation [taken directly from the Go docs][gdex]: + +``` + Jan 2 15:04:05 2006 MST +=> 1 2 3 4 5 6 -7 +``` + +### Hugo Date and Time Templating Reference + +The following examples show the layout string followed by the rendered output. + +The examples were rendered and tested in [CST] and all point to the same field in a content file's front matter: + +``` +date: 2017-03-03T14:15:59-06:00 +``` + +`.Date` (i.e. called via [page variable][pagevars]) +: **Returns**: `2017-03-03 14:15:59 -0600 CST` + +`"Monday, January 2, 2006"` +: **Returns**: `Friday, March 3, 2017` + +`"Mon Jan 2 2006"` +: **Returns**: `Fri Mar 3 2017` + +`"January 2006"` +: **Returns**: `March 2017` + +`"2006-01-02"` +: **Returns**: `2017-03-03` + +`"Monday"` +: **Returns**: `Friday` + +`"02 Jan 06 15:04 MST"` (RFC822) +: **Returns**: `03 Mar 17 14:15 CST` + +`"02 Jan 06 15:04 -0700"` (RFC822Z) +: **Returns**: `03 Mar 17 14:15 -0600` + +`"Mon, 02 Jan 2006 15:04:05 MST"` (RFC1123) +: **Returns**: `Fri, 03 Mar 2017 14:15:59 CST` + +`"Mon, 02 Jan 2006 15:04:05 -0700"` (RFC1123Z) +: **Returns**: `Fri, 03 Mar 2017 14:15:59 -0600` + +More examples can be found in Go's [documentation for the time package][timeconst]. + +### Cardinal Numbers and Ordinal Abbreviations + +Spelled-out cardinal numbers (e.g. "one", "two", and "three") are not currently supported. + - Ordinal abbreviations (i.e., with shorted suffixes like "1st", "2nd", and "3rd") are not currently directly supported. By using `{{.Date.Format "Jan 2nd 2006"}}`, Hugo assumes you want to append `nd` as a string to the day of the month. However, you can chain functions together to create something like this: ++Use the [`humanize`](/functions/humanize) function to render the day of the month as an ordinal number: + +``` - {{ .Date.Format "2" }}{{ if in (slice 1 21 31) .Date.Day}}st{{ else if in (slice 2 22) .Date.Day}}nd{{ else if in (slice 3 23) .Date.Day}}rd{{ else }}th{{ end }} of {{ .Date.Format "January 2006" }} ++{{ humanize .Date.Day }} of {{ .Date.Format "January 2006" }} +``` + +This will output: + +``` +5th of March 2017 +``` + + +### Use `.Local` and `.UTC` + +In conjunction with the [`dateFormat` function][dateFormat], you can also convert your dates to `UTC` or to local timezones: + +`{{ dateFormat "02 Jan 06 15:04 MST" .Date.UTC }}` +: **Returns**: `03 Mar 17 20:15 UTC` + +`{{ dateFormat "02 Jan 06 15:04 MST" .Date.Local }}` +: **Returns**: `03 Mar 17 14:15 CST` + +[CST]: https://en.wikipedia.org/wiki/Central_Time_Zone +[dateFormat]: /functions/dateformat/ +[gdex]: https://golang.org/pkg/time/#example_Time_Format +[pagevars]: /variables/page/ +[time]: https://golang.org/pkg/time/ +[timeconst]: https://golang.org/pkg/time/#ANSIC diff --cc docs/content/en/functions/highlight.md index 8324edb81,000000000..10b1c2d90 mode 100644,000000..100644 --- a/docs/content/en/functions/highlight.md +++ b/docs/content/en/functions/highlight.md @@@ -1,108 -1,0 +1,108 @@@ +--- +title: highlight +linktitle: highlight +description: Renders code with a syntax highlighter. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2021-12-06 +categories: [functions] +menu: + docs: + parent: "functions" +keywords: [highlighting,code blocks,syntax] +signature: ["transform.Highlight INPUT LANG [OPTIONS]","highlight INPUT LANG [OPTIONS]"] +relatedfuncs: [] +deprecated: false +toc: true +--- +The `highlight` function uses the [Chroma] syntax highlighter, supporting over 200 languages with more than 40 available styles. + +## Parameters + +INPUT +: The code to highlight. + +LANG +: The language of the code to highlight. Choose from one of the [supported languages]. Case-insensitive. + +OPTIONS +: An optional, comma-separated list of zero or more [options]. Set default values in [site configuration]. + +## Options + +lineNos +: Boolean. Default is `false`.\ +Display a number at the beginning of each line. + +lineNumbersInTable +: Boolean. Default is `true`.\ - Render the highlighted code in an HTML table with two cells. The left table cell contains the line numbers. The right table cell contains the code, allowing a user to select and copy the code without line numbers. Irrelevant if `lineNos` is false. ++Render the highlighted code in an HTML table with two cells. The left table cell contains the line numbers. The right table cell contains the code, allowing a user to select and copy the code without line numbers. Irrelevant if `lineNos` is `false`. + +anchorLineNos +: Boolean. Default is `false`.\ - Render each line number as an HTML anchor element, and set the `id` attribute of the surrounding `` to the line number. Irrelevant if `lineNos` is false. ++Render each line number as an HTML anchor element, and set the `id` attribute of the surrounding `` to the line number. Irrelevant if `lineNos` is `false`. + +lineAnchors +: String. Default is `""`.\ - When rendering a line number as an HTML anchor element, prepend this value to the `id` attribute of the surrounding ``. This provides unique `id` attributes when a page contains two or more code blocks. Irrelevant if `lineNos` or `anchorLineNos` is false. ++When rendering a line number as an HTML anchor element, prepend this value to the `id` attribute of the surrounding ``. This provides unique `id` attributes when a page contains two or more code blocks. Irrelevant if `lineNos` or `anchorLineNos` is `false`. + +lineNoStart +: Integer. Default is `1`.\ - The number to display at the beginning of the first line. Irrelevant if `lineNos` is false. ++The number to display at the beginning of the first line. Irrelevant if `lineNos` is `false`. + +hl_Lines +: String. Default is `""`.\ +A space-separated list of lines to emphasize within the highlighted code. To emphasize lines 2, 3, 4, and 7, set this value to `2-4 7`. This option is independent of the `lineNoStart` option. + +hl_inline +: Boolean. Default is `false`.\ +Render the highlighted code without a wrapping container. + +style +: String. Default is `monokai`.\ +The CSS styles to apply to the highlighted code. See the [style gallery] for examples. Case-sensitive. + +noClasses +: Boolean. Default is `true`.\ +Use inline CSS styles instead of an external CSS file. To use an external CSS file, set this value to `false` and [generate the file with the hugo client][hugo client]. + +tabWidth +: Integer. Default is `4`.\ - Substitute this number of spaces for each tab character in your highlighted code. ++Substitute this number of spaces for each tab character in your highlighted code. Irrelevant if `noClasses` is `false`. + +guessSyntax +: Boolean. Default is `false`.\ +If the `LANG` parameter is blank or an unrecognized language, auto-detect the language if possible, otherwise use a fallback language. + +{{% note %}} +Instead of specifying both `lineNos` and `lineNumbersInTable`, you can use the following shorthand notation: + +`lineNos=inline` +: equivalent to `lineNos=true` and `lineNumbersInTable=false` + +`lineNos=table` +: equivalent to `lineNos=true` and `lineNumbersInTable=true` +{{% /note %}} + +## Examples + +```go-html-template +{{ $input := `fmt.Println("Hello World!")` }} +{{ transform.Highlight $input "go" }} + +{{ $input := `console.log('Hello World!');` }} +{{ $lang := "js" }} +{{ transform.Highlight $input $lang "lineNos=table, style=api" }} + +{{ $input := `echo "Hello World!"` }} +{{ $lang := "bash" }} +{{ $options := slice "lineNos=table" "style=dracula" }} +{{ transform.Highlight $input $lang (delimit $options ",") }} +``` + +[Chroma]: https://github.com/alecthomas/chroma +[hugo client]: {{< relref "commands/hugo_gen_chromastyles" >}} +[options]: {{< relref "#options" >}} +[site configuration]: {{< relref "getting-started/configuration-markup#highlight">}} +[style gallery]: https://xyproto.github.io/splash/docs/ +[supported languages]: {{< relref "content-management/syntax-highlighting#list-of-chroma-highlighting-languages" >}} diff --cc docs/content/en/functions/markdownify.md index b42e045e7,000000000..8d8726cff mode 100644,000000..100644 --- a/docs/content/en/functions/markdownify.md +++ b/docs/content/en/functions/markdownify.md @@@ -1,28 -1,0 +1,29 @@@ +--- +title: markdownify +linktitle: markdownify +description: Runs the provided string through the Markdown processor. +date: 2017-02-01 +publishdate: 2017-02-01 - lastmod: 2017-02-01 ++lastmod: 2023-02-09 +keywords: [markdown,content] +categories: [functions] +menu: + docs: + parent: "functions" +signature: ["markdownify INPUT"] +workson: [] +hugoversion: +relatedfuncs: [] +deprecated: false +aliases: [] +--- + + +``` +{{ .Title | markdownify }} +``` + - {{< new-in "0.93.0" >}} **Note**: `markdownify` now supports [Render Hooks] just like [.RenderString](/functions/renderstring/). ++{{< new-in "0.93.0" >}} **Note**: `markdownify` now supports [Render Hooks] just like [`.Page.RenderString`]. However, if you use more complicated [Render Hooks] relying on page context, use [`.Page.RenderString`] instead. See [GitHub issue #9692](https://github.com/gohugoio/hugo/issues/9692) for more details. + +[Render Hooks]: /templates/render-hooks/ ++[`.Page.RenderString`]: /functions/renderstring/ diff --cc docs/content/en/functions/uniq.md index eec55e5c3,000000000..73ca32488 mode 100644,000000..100644 --- a/docs/content/en/functions/uniq.md +++ b/docs/content/en/functions/uniq.md @@@ -1,25 -1,0 +1,18 @@@ +--- +title: uniq +linktitle: uniq - description: Takes in a slice or array and returns a slice with subsequent duplicate elements removed. - date: 2017-02-01 - publishdate: 2017-02-01 - lastmod: 2017-02-01 ++description: Takes in a slice or array and returns a slice with duplicate elements removed. +categories: [functions] +menu: + docs: - parent: "functions" ++ parent: functions +keywords: [multilingual,i18n,urls] - signature: ["uniq SET"] - workson: [] - hugoversion: - relatedfuncs: [] - deprecated: false ++signature: [uniq SET] +aliases: [] +--- + ++ +``` - {{ uniq (slice 1 2 3 2) }} - {{ slice 1 2 3 2 | uniq }} - ++{{ slice 1 3 2 1 | uniq }} --> [1 3 2] ++ +``` diff --cc docs/content/en/functions/urls.Parse.md index 676734210,000000000..988ecb3ac mode 100644,000000..100644 --- a/docs/content/en/functions/urls.Parse.md +++ b/docs/content/en/functions/urls.Parse.md @@@ -1,31 -1,0 +1,31 @@@ +--- +title: urls.Parse - description: Parse parses a given url, which may be relative or absolute, into a URL structure. ++description: Parse parses a given URL, which may be relative or absolute, into a URL structure. +date: 2017-09-25 +publishdate: 2017-09-25 +lastmod: 2017-09-25 +categories: [functions] +menu: + docs: + parent: "functions" +keywords: [urls] +signature: ["urls.Parse URL"] +workson: [] +hugoversion: +deprecated: false +aliases: [] +--- + +`urls.Parse` takes a url as input + + +```go-html-template +{{ $url := urls.Parse "http://www.gohugo.io" }} +``` + +and returns a [URL](https://godoc.org/net/url#URL) structure. The struct fields are accessed via the `.` notation: + +```go-html-template +{{ $url.Scheme }} → "http" +{{ $url.Host }} → "www.gohugo.io" +``` diff --cc docs/content/en/getting-started/configuration-markup.md index b55bd79c4,000000000..d1d237b2a mode 100644,000000..100644 --- a/docs/content/en/getting-started/configuration-markup.md +++ b/docs/content/en/getting-started/configuration-markup.md @@@ -1,113 -1,0 +1,113 @@@ +--- +title: Configure Markup +description: How to handle Markdown and other markup related configuration. +date: 2019-11-15 +categories: [getting started,fundamentals] +keywords: [configuration,highlighting] +weight: 65 +sections_weight: 65 +slug: configuration-markup +toc: true +--- + +## Configure Markup + +See [Goldmark](#goldmark) for settings related to the default Markdown handler in Hugo. + +Below are all markup related configuration in Hugo with their default settings: + +{{< code-toggle config="markup" />}} + +**See each section below for details.** + +### Goldmark + +[Goldmark](https://github.com/yuin/goldmark/) is from Hugo 0.60 the default library used for Markdown. It's fast, it's [CommonMark](https://spec.commonmark.org/0.29/) compliant and it's very flexible. + +This is the default configuration: + +{{< code-toggle config="markup.goldmark" />}} + +For details on the extensions, refer to [this section](https://github.com/yuin/goldmark/#built-in-extensions) of the Goldmark documentation + +Some settings explained: + - hardWrap ++hardWraps +: By default, Goldmark ignores newlines within a paragraph. Set to `true` to render newlines as `
    ` elements. + +unsafe +: By default, Goldmark does not render raw HTMLs and potentially dangerous links. If you have lots of inline HTML and/or JavaScript, you may need to turn this on. + +typographer +: This extension substitutes punctuations with typographic entities like [smartypants](https://daringfireball.net/projects/smartypants/). + +attribute +: Enable custom attribute support for titles and blocks by adding attribute lists inside single curly brackets (`{.myclass class="class1 class2" }`) and placing it _after the Markdown element it decorates_, on the same line for titles and on a new line directly below for blocks. + +Hugo supports adding attributes (e.g. CSS classes) to Markdown blocks, e.g. tables, lists, paragraphs etc. + +A blockquote with a CSS class: + +```md +> foo +> bar +{.myclass} +``` + +There are some current limitations: For tables you can currently only apply it to the full table, and for lists the `ul`/`ol`-nodes only, e.g.: + +```md +* Fruit + * Apple + * Orange + * Banana + {.fruits} +* Dairy + * Milk + * Cheese + {.dairies} +{.list} +``` + +Note that attributes in [code fences](/content-management/syntax-highlighting/#highlighting-in-code-fences) must come after the opening tag, with any other highlighting processing instruction, e.g.: + +````txt +```go {.myclass linenos=table,hl_lines=[8,"15-17"],linenostart=199} +// ... code +``` +```` + +autoHeadingIDType ("github") +: The strategy used for creating auto IDs (anchor names). Available types are `github`, `github-ascii` and `blackfriday`. `github` produces GitHub-compatible IDs, `github-ascii` will drop any non-Ascii characters after accent normalization, and `blackfriday` will make the IDs compatible with Blackfriday, the default Markdown engine before Hugo 0.60. Note that if Goldmark is your default Markdown engine, this is also the strategy used in the [anchorize](/functions/anchorize/) template func. + +### Highlight + +This is the default `highlight` configuration. Note that some of these settings can be set per code block, see [Syntax Highlighting](/content-management/syntax-highlighting/). + +{{< code-toggle config="markup.highlight" />}} + +For `style`, see these galleries: + +* [Short snippets](https://xyproto.github.io/splash/docs/all.html) +* [Long snippets](https://xyproto.github.io/splash/docs/longer/all.html) + +For CSS, see [Generate Syntax Highlighter CSS](/content-management/syntax-highlighting/#generate-syntax-highlighter-css). + +### Table Of Contents + +{{< code-toggle config="markup.tableOfContents" />}} + +These settings only works for the Goldmark renderer: + +startLevel +: The heading level, values starting at 1 (`h1`), to start render the table of contents. + +endLevel +: The heading level, inclusive, to stop render the table of contents. + +ordered +: Whether or not to generate an ordered list instead of an unordered list. + +## Markdown Render Hooks + +See [Markdown Render Hooks](/templates/render-hooks/). diff --cc docs/content/en/getting-started/configuration.md index 3c9b42678,000000000..99d11fbb1 mode 100644,000000..100644 --- a/docs/content/en/getting-started/configuration.md +++ b/docs/content/en/getting-started/configuration.md @@@ -1,786 -1,0 +1,791 @@@ +--- +title: Configure Hugo +linktitle: Configuration +description: How to configure your Hugo site. +date: 2013-07-01 +publishdate: 2017-01-02 +categories: [getting started,fundamentals] +keywords: [configuration,toml,yaml,json] +menu: + docs: + parent: "getting-started" + weight: 60 +weight: 60 +sections_weight: 60 +aliases: [/overview/source-directory/,/overview/configuration/] +toc: true +--- + +## Configuration File + +Hugo uses the `config.toml`, `config.yaml`, or `config.json` (if found in the +site root) as the default site config file. + +The user can choose to override that default with one or more site config files +using the command-line `--config` switch. + +Examples: + +```txt +hugo --config debugconfig.toml +hugo --config a.toml,b.toml,c.toml +``` + +{{% note %}} +Multiple site config files can be specified as a comma-separated string to the `--config` switch. +{{% /note %}} + +{{< todo >}}TODO: distinct config.toml and others (the root object files){{< /todo >}} + ++## hugo.toml vs config.toml ++ ++In Hugo 0.110.0 we changed the default config base filename to `hugo`, e.g. `hugo.toml`. We will still look for `config.toml` etc., but we recommend you eventually rename it (but you need to wait if you want to support older Hugo versions). The main reason we're doing this is to make it easier code editors and build tools to identify this as a Hugo configuration file and project. ++ ++{{< new-in "0.110.0" >}} ++ +## Configuration Directory + +In addition to using a single site config file, one can use the `configDir` directory (default to `config/`) to maintain easier organization and environment specific settings. + +- Each file represents a configuration root object, such as `params.toml` for `[Params]`, `menu(s).toml` for `[Menu]`, `languages.toml` for `[Languages]` etc... +- Each file's content must be top-level, for example: + +{{< code-toggle file="config" >}} +[Params] + foo = "bar" +{{< /code-toggle >}} + +{{< code-toggle file="params" >}} +foo = "bar" +{{< /code-toggle >}} + +- Each directory holds a group of files containing settings unique to an environment. +- Files can be localized to become language specific. + + +```txt +├── config +│ ├── _default +│ │ ├── config.toml +│ │ ├── languages.toml +│ │ ├── menus.en.toml +│ │ ├── menus.zh.toml +│ │ └── params.toml +│ ├── production +│ │ ├── config.toml +│ │ └── params.toml +│ └── staging +│ ├── config.toml +│ └── params.toml +``` + +Considering the structure above, when running `hugo --environment staging`, Hugo will use every setting from `config/_default` and merge `staging`'s on top of those. + +Let's take an example to understand this better. Let's say you are using Google Analytics for your website. This requires you to specify `googleAnalytics = "G-XXXXXXXX"` in `config.toml`. Now consider the following scenario: +- You don't want the Analytics code to be loaded in development i.e. in your `localhost` +- You want to use separate googleAnalytics IDs for your production & staging environments (say): + - `G-PPPPPPPP` for production + - `G-SSSSSSSS` for staging + +This is how you need to configure your `config.toml` files considering the above scenario: +1. In `_default/config.toml` you don't need to mention `googleAnalytics` parameter at all. This ensures that no Google Analytics code is loaded in your development server i.e. when you run `hugo serve`. This works since, by default Hugo sets `Environment=development` when you run `hugo serve` which uses the config files from `_default` folder +2. In `production/config.toml` you just need to have one line: + + ```googleAnalytics = "G-PPPPPPPP"``` + + You don't need to mention all other parameters like `title`, `baseURL`, `theme` etc. again in this config file. You need to mention only those parameters which are different or new for the production environment. This is due to the fact that Hugo is going to __merge__ this on top of `_default/config.toml`. Now when you run `hugo` (build command), by default hugo sets `Environment=production`, so the `G-PPPPPPPP` analytics code will be there in your production website +3. Similarly in `staging/config.toml` you just need to have one line: + + ```googleAnalytics = "G-SSSSSSSS"``` + + Now you need to tell Hugo that you are using the staging environment. So your build command should be `hugo --environment staging` which will load the `G-SSSSSSSS` analytics code in your staging website + +{{% note %}} +Default environments are __development__ with `hugo server` and __production__ with `hugo`. +{{%/ note %}} + +## Merge Configuration from Themes + +The configuration value for `_merge` can be one of: + +none +: No merge. + +shallow +: Only add values for new keys. + +deep +: Add values for new keys, merge existing. + +Note that you don't need to be so verbose as in the default setup below; a `_merge` value higher up will be inherited if not set. + +{{< code-toggle config="mergeStrategy" skipHeader=true />}} + +## All Configuration Settings + - The following is the full list of Hugo-defined variables with their default - value in parentheses. Users may choose to override those values in their site ++The following is the full list of Hugo-defined variables. Users may choose to override those values in their site +config file(s). + +### archetypeDir + +**Default value:** "archetypes" + +The directory where Hugo finds archetype files (content templates). {{% module-mounts-note %}} + +### assetDir + +**Default value:** "assets" + +The directory where Hugo finds asset files used in [Hugo Pipes](/hugo-pipes/). {{% module-mounts-note %}} + +### baseURL + +Hostname (and path) to the root, e.g. https://bep.is/ + +### build + +See [Configure Build](#configure-build) + +### buildDrafts (false) + +**Default value:** false + +Include drafts when building. + +### buildExpired + +**Default value:** false + +Include content already expired. + +### buildFuture + +**Default value:** false + +Include content with publishdate in the future. + +### caches + +See [Configure File Caches](#configure-file-caches) + +### cascade + +Pass down default configuration values (front matter) to pages in the content tree. The options in site config is the same as in page front matter, see [Front Matter Cascade](/content-management/front-matter#front-matter-cascade). + +### canonifyURLs + +**Default value:** false + +Enable to turn relative URLs into absolute. + +### cleanDestinationDir + +**Default value:** false + +When building, removes files from destination not found in static directories. + +### contentDir + +**Default value:** "content" + +The directory from where Hugo reads content files. {{% module-mounts-note %}} + +### copyright + +**Default value:** "" + +Copyright notice for your site, typically displayed in the footer. + +### dataDir + +**Default value:** "data" + +The directory from where Hugo reads data files. {{% module-mounts-note %}} + +### defaultContentLanguage + +**Default value:** "en" + +Content without language indicator will default to this language. + +### defaultContentLanguageInSubdir + +**Default value:** false + +Render the default content language in subdir, e.g. `content/en/`. The site root `/` will then redirect to `/en/`. + +### disableAliases + +**Default value:** false + +Will disable generation of alias redirects. Note that even if `disableAliases` is set, the aliases themselves are preserved on the page. The motivation with this is to be able to generate 301 redirects in an `.htaccess`, a Netlify `_redirects` file or similar using a custom output format. + +### disableHugoGeneratorInject + +**Default value:** false + +Hugo will, by default, inject a generator meta tag in the HTML head on the _home page only_. You can turn it off, but we would really appreciate if you don't, as this is a good way to watch Hugo's popularity on the rise. + +### disableKinds + +**Default value:** [] + +Enable disabling of all pages of the specified *Kinds*. Allowed values in this list: `"page"`, `"home"`, `"section"`, `"taxonomy"`, `"term"`, `"RSS"`, `"sitemap"`, `"robotsTXT"`, `"404"`. + +### disableLiveReload + +**Default value:** false + +Disable automatic live reloading of browser window. + +### disablePathToLower + +**Default value:** false + +Do not convert the url/path to lowercase. + +### enableEmoji + +**Default value:** false + +Enable Emoji emoticons support for page content; see the [Emoji Cheat Sheet](https://www.webpagefx.com/tools/emoji-cheat-sheet/). + +### enableGitInfo + +**Default value:** false + +Enable `.GitInfo` object for each page (if the Hugo site is versioned by Git). This will then update the `Lastmod` parameter for each page using the last git commit date for that content file. + +### enableInlineShortcodes + +**Default value:** false + +Enable inline shortcode support. See [Inline Shortcodes](/templates/shortcode-templates/#inline-shortcodes). + +### enableMissingTranslationPlaceholders + +**Default value:** false + +Show a placeholder instead of the default value or an empty string if a translation is missing. + +### enableRobotsTXT + +**Default value:** false + +Enable generation of `robots.txt` file. + +### frontmatter + +See [Front matter Configuration](#configure-front-matter). + +### googleAnalytics + +**Default value:** "" + +Google Analytics tracking ID. + +### hasCJKLanguage + +**Default value:** false + +If true, auto-detect Chinese/Japanese/Korean Languages in the content. This will make `.Summary` and `.WordCount` behave correctly for CJK languages. + +### imaging + +See [Image Processing Config](/content-management/image-processing/#imaging-configuration). + +### languageCode + +**Default value:** "" + +A language tag as defined by [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646). This value is used to populate: + +- The `` element in the internal [RSS template](https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/rss.xml) +- The `lang` attribute of the `` element in the internal [alias template](https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/alias.html) + +### languages + +See [Configure Languages](/content-management/multilingual/#configure-languages). + +### disableLanguages + +See [Disable a Language](/content-management/multilingual/#disable-a-language) + +### markup + +See [Configure Markup](/getting-started/configuration-markup). + +### mediaTypes + +See [Configure Media Types](/templates/output-formats/#media-types). + +### menus + +See [Add Non-content Entries to a Menu](/content-management/menus/#add-non-content-entries-to-a-menu). + +### minify + +See [Configure Minify](#configure-minify) + +### module + +Module config see [Module Config](/hugo-modules/configuration/). + +### newContentEditor + +**Default value:** "" + +The editor to use when creating new content. + +### noChmod + +**Default value:** false + +Don't sync permission mode of files. + +### noTimes + +**Default value:** false + +Don't sync modification time of files. + +### outputFormats + +See [Configure Output Formats](#configure-additional-output-formats). + +### paginate + +**Default value:** 10 + +Default number of elements per page in [pagination](/templates/pagination/). + +### paginatePath + +**Default value:** "page" + +The path element used during pagination (`https://example.com/page/2`). + +### permalinks + +See [Content Management](/content-management/urls/#permalinks). + +### pluralizeListTitles + +**Default value:** true + +Pluralize titles in lists. + +### publishDir + +**Default value:** "public" + +The directory to where Hugo will write the final static site (the HTML files etc.). + +### related + +: See [Related Content](/content-management/related/#configure-related-content). + +### relativeURLs + +**Default value:** false + +Enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs. + +### refLinksErrorLevel + +**Default value:** "ERROR" + +When using `ref` or `relref` to resolve page links and a link cannot be resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`). + +### refLinksNotFoundURL + +URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is. + +### removePathAccents + +**Default value:** false + +Removes [non-spacing marks](https://www.compart.com/en/unicode/category/Mn) from [composite characters](https://en.wikipedia.org/wiki/Precomposed_character) in content paths. + +```text +content/post/hügó.md --> https://example.org/post/hugo/ +``` + +### rssLimit + +**Default value:** -1 (unlimited) + +Maximum number of items in the RSS feed. + +### sectionPagesMenu + +See ["Section Menu for Lazy Bloggers"](/templates/menu-templates/#section-menu-for-lazy-bloggers). + +### security + +See [Security Policy](/about/security-model/#security-policy) + +### sitemap + +Default [sitemap configuration](/templates/sitemap-template/#configuration). + +### summaryLength + +**Default value:** 70 + +The length of text in words to show in a [`.Summary`](/content-management/summaries/#automatic-summary-splitting). + +### taxonomies + +See [Configure Taxonomies](/content-management/taxonomies#configure-taxonomies). + +### theme + +: See [Module Config](/hugo-modules/configuration/#module-config-imports) for how to import a theme. + +### themesDir + +**Default value:** "themes" + +The directory where Hugo reads the themes from. + +### timeout + +**Default value:** "30s" + +Timeout for generating page contents, specified as a [duration](https://pkg.go.dev/time#Duration) or in milliseconds. *Note:* this is used to bail out of recursive content generation. You might need to raise this limit if your pages are slow to generate (e.g., because they require large image processing or depend on remote contents). + +### timeZone + +The time zone (or location), e.g. `Europe/Oslo`, used to parse front matter dates without such information and in the [`time` function](/functions/time/). The list of valid values may be system dependent, but should include `UTC`, `Local`, and any location in the [IANA Time Zone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). + +### title + +Site title. + +### titleCaseStyle + +**Default value:** "AP" + +See [Configure Title Case](#configure-title-case) + +### uglyURLs + +**Default value:** false + +When enabled, creates URL of the form `/filename.html` instead of `/filename/`. + +### watch + +**Default value:** false + +Watch filesystem for changes and recreate as needed. + +{{% note %}} +If you are developing your site on a \*nix machine, here is a handy shortcut for finding a configuration option from the command line: +```txt +cd ~/sites/yourhugosite +hugo config | grep emoji +``` + +which shows output like + +```txt +enableemoji: true +``` +{{% /note %}} + +## Configure Build + +The `build` configuration section contains global build-related configuration options. + +{{< code-toggle file="config">}} +[build] +useResourceCacheWhen="fallback" +writeStats = false +noJSConfigInAssets = false +{{< /code-toggle >}} + + +useResourceCacheWhen +: When to use the cached resources in `/resources/_gen` for PostCSS and ToCSS. Valid values are `never`, `always` and `fallback`. The last value means that the cache will be tried if PostCSS/extended version is not available. + +writeStats +: When enabled, a file named `hugo_stats.json` will be written to your project root with some aggregated data about the build, e.g. list of HTML entities published to be used to do [CSS pruning](/hugo-pipes/postprocess/#css-purging-with-postcss). If you're only using this for the production build, you should consider placing it below [config/production](/getting-started/configuration/#configuration-directory). It's also worth mentioning that, due to the nature of the partial server builds, new HTML entities will be added when you add or change them while the server is running, but the old values will not be removed until you restart the server or run a regular `hugo` build. + +**Note** that the prime use case for this is purging of unused CSS; it is built for speed and there may be false positives (e.g., detection of HTML elements that are not HTML elements). + +noJSConfigInAssets +: Turn off writing a `jsconfig.json` into your `/assets` folder with mapping of imports from running [js.Build](https://gohugo.io/hugo-pipes/js). This file is intended to help with intellisense/navigation inside code editors such as [VS Code](https://code.visualstudio.com/). Note that if you do not use `js.Build`, no file will be written. + +## Configure Server + +This is only relevant when running `hugo server`, and it allows to set HTTP headers during development, which allows you to test out your Content Security Policy and similar. The configuration format matches [Netlify's](https://docs.netlify.com/routing/headers/#syntax-for-the-netlify-configuration-file) with slightly more powerful [Glob matching](https://github.com/gobwas/glob): + + +{{< code-toggle file="config">}} +[server] +[[server.headers]] +for = "/**" + +[server.headers.values] +X-Frame-Options = "DENY" +X-XSS-Protection = "1; mode=block" +X-Content-Type-Options = "nosniff" +Referrer-Policy = "strict-origin-when-cross-origin" +Content-Security-Policy = "script-src localhost:1313" +{{< /code-toggle >}} + +Since this is "development only", it may make sense to put it below the `development` environment: + + +{{< code-toggle file="config/development/server">}} +[[headers]] +for = "/**" + +[headers.values] +X-Frame-Options = "DENY" +X-XSS-Protection = "1; mode=block" +X-Content-Type-Options = "nosniff" +Referrer-Policy = "strict-origin-when-cross-origin" +Content-Security-Policy = "script-src localhost:1313" +{{< /code-toggle >}} + +You can also specify simple redirects rules for the server. The syntax is again similar to Netlify's. + +Note that a `status` code of 200 will trigger a [URL rewrite](https://docs.netlify.com/routing/redirects/rewrites-proxies/), which is what you want in SPA situations, e.g: + +{{< code-toggle file="config/development/server">}} +[[redirects]] +from = "/myspa/**" +to = "/myspa/" +status = 200 +force = false +{{< /code-toggle >}} + +Setting `force=true` will make a redirect even if there is existing content in the path. Note that before Hugo 0.76 `force` was the default behavior, but this is inline with how Netlify does it. + +## 404 Server Error Page {#_404-server-error-page} + +{{< new-in "0.103.0" >}} + +Hugo will, by default, render all 404 errors when running `hugo server` with the `404.html` template. Note that if you have already added one or more redirects to your [Server Config](#configure-server), you need to add the 404 redirect explicitly, e.g: + +```toml +[[redirects]] + from = "/**" + to = "/404.html" + status = 404 +``` + +## Configure Title Case + +Set `titleCaseStyle` to specify the title style used by the [title](/functions/title/) template function and the automatic section titles in Hugo. It defaults to [AP Stylebook](https://www.apstylebook.com/) for title casing, but you can also set it to `Chicago` or `Go` (every word starts with a capital letter). + +## Configuration Environment Variables + +HUGO_NUMWORKERMULTIPLIER +: Can be set to increase or reduce the number of workers used in parallel processing in Hugo. If not set, the number of logical CPUs will be used. + +## Configuration Lookup Order + +Similar to the template [lookup order], Hugo has a default set of rules for searching for a configuration file in the root of your website's source directory as a default behavior: + +1. `./config.toml` +2. `./config.yaml` +3. `./config.json` + +In your `config` file, you can direct Hugo as to how you want your website rendered, control your website's menus, and arbitrarily define site-wide parameters specific to your project. + + +## Example Configuration + +The following is a typical example of a configuration file. The values nested under `params:` will populate the [`.Site.Params`] variable for use in [templates]: + +{{< code-toggle file="config">}} +baseURL: "https://yoursite.example.com/" +title: "My Hugo Site" +permalinks: + posts: /:year/:month/:title/ +params: + Subtitle: "Hugo is Absurdly Fast!" + AuthorName: "Jon Doe" + GitHubUser: "spf13" + ListOfFoo: + - "foo1" + - "foo2" + SidebarRecentLimit: 5 +{{< /code-toggle >}} + +## Configure with Environment Variables + +In addition to the 3 config options already mentioned, configuration key-values can be defined through operating system environment variables. + +For example, the following command will effectively set a website's title on Unix-like systems: + +```txt +$ env HUGO_TITLE="Some Title" hugo +``` + +This is really useful if you use a service such as Netlify to deploy your site. Look at the Hugo docs [Netlify configuration file](https://github.com/gohugoio/hugoDocs/blob/master/netlify.toml) for an example. + +{{% note "Setting Environment Variables" %}} +Names must be prefixed with `HUGO_` and the configuration key must be set in uppercase when setting operating system environment variables. + +To set config params, prefix the name with `HUGO_PARAMS_` +{{% /note %}} + +If you are using snake_cased variable names, the above will not work. Hugo determines the delimiter to use by the first character after `HUGO`. This allows you to define environment variables on the form `HUGOxPARAMSxAPI_KEY=abcdefgh`, using any [allowed](https://stackoverflow.com/questions/2821043/allowed-characters-in-linux-environment-variable-names#:~:text=So%20names%20may%20contain%20any,not%20begin%20with%20a%20digit.) delimiter. + +{{< todo >}} +Test and document setting params via JSON env var. +{{< /todo >}} + +## Ignore Content and Data Files when Rendering + +**Note:** This works, but we recommend you use the newer and more powerful [includeFiles and excludeFiles](https://gohugo.io/hugo-modules/configuration/#module-config-mounts) mount options. + +To exclude specific files from the `content` and `data` directories when rendering your site, set `ignoreFiles` to one or more regular expressions to match against the absolute file path. + +To ignore files ending with `.foo` or `.boo`: + +{{< code-toggle copy="false" >}} +ignoreFiles = ['\.foo$', '\.boo$'] +{{< /code-toggle >}} + +To ignore a file using the absolute file path: + +{{< code-toggle copy="false" >}} +ignoreFiles = ['^/home/user/project/content/test\.md$'] +{{< /code-toggle >}} + +## Configure Front Matter + +### Configure Dates + +Dates are important in Hugo, and you can configure how Hugo assigns dates to your content pages. You do this by adding a `frontmatter` section to your `config.toml`. + +The default configuration is: + +{{< code-toggle file="config" >}} +[frontmatter] +date = ["date", "publishDate", "lastmod"] +lastmod = [":git", "lastmod", "date", "publishDate"] +publishDate = ["publishDate", "date"] +expiryDate = ["expiryDate"] +{{< /code-toggle >}} + +If you, as an example, have a non-standard date parameter in some of your content, you can override the setting for `date`: + +{{< code-toggle file="config" >}} +[frontmatter] +date = ["myDate", ":default"] +{{< /code-toggle >}} + +The `:default` is a shortcut to the default settings. The above will set `.Date` to the date value in `myDate` if present, if not we will look in `date`,`publishDate`, `lastmod` and pick the first valid date. + +In the list to the right, values starting with ":" are date handlers with a special meaning (see below). The others are just names of date parameters (case insensitive) in your front matter configuration. Also note that Hugo have some built-in aliases to the above: `lastmod` => `modified`, `publishDate` => `pubdate`, `published` and `expiryDate` => `unpublishdate`. With that, as an example, using `pubDate` as a date in front matter, will, by default, be assigned to `.PublishDate`. + +The special date handlers are: + + +`:fileModTime` +: Fetches the date from the content file's last modification timestamp. + +An example: + +{{< code-toggle file="config" >}} +[frontmatter] +lastmod = ["lastmod", ":fileModTime", ":default"] +{{< /code-toggle >}} + + +The above will try first to extract the value for `.Lastmod` starting with the `lastmod` front matter parameter, then the content file's modification timestamp. The last, `:default` should not be needed here, but Hugo will finally look for a valid date in `:git`, `date` and then `publishDate`. + + +`:filename` +: Fetches the date from the content file's filename. For example, `2018-02-22-mypage.md` will extract the date `2018-02-22`. Also, if `slug` is not set, `mypage` will be used as the value for `.Slug`. + +An example: + +{{< code-toggle file="config" >}} +[frontmatter] +date = [":filename", ":default"] +{{< /code-toggle >}} + +The above will try first to extract the value for `.Date` from the filename, then it will look in front matter parameters `date`, `publishDate` and lastly `lastmod`. + + +`:git` +: This is the Git author date for the last revision of this content file. This will only be set if `--enableGitInfo` is set or `enableGitInfo = true` is set in site config. + +## Configure Additional Output Formats + +Hugo v0.20 introduced the ability to render your content to multiple output formats (e.g., to JSON, AMP html, or CSV). See [Output Formats] for information on how to add these values to your Hugo project's configuration file. + +## Configure Minify + +Default configuration: + +{{< code-toggle config="minify" />}} + +## Configure File Caches + +Since Hugo 0.52 you can configure more than just the `cacheDir`. This is the default configuration: + +{{< code-toggle >}} +[caches] +[caches.getjson] +dir = ":cacheDir/:project" +maxAge = -1 +[caches.getcsv] +dir = ":cacheDir/:project" +maxAge = -1 +[caches.getresource] +dir = ":cacheDir/:project" +maxAge = -1 +[caches.images] +dir = ":resourceDir/_gen" +maxAge = -1 +[caches.assets] +dir = ":resourceDir/_gen" +maxAge = -1 +[caches.modules] +dir = ":cacheDir/modules" +maxAge = -1 +{{< /code-toggle >}} + +You can override any of these cache settings in your own `config.toml`. + +### The keywords explained + +`:cacheDir` +: This is the value of the `cacheDir` config option if set (can also be set via OS env variable `HUGO_CACHEDIR`). It will fall back to `/opt/build/cache/hugo_cache/` on Netlify, or a `hugo_cache` directory below the OS temp dir for the others. This means that if you run your builds on Netlify, all caches configured with `:cacheDir` will be saved and restored on the next build. For other CI vendors, please read their documentation. For an CircleCI example, see [this configuration](https://github.com/bep/hugo-sass-test/blob/6c3960a8f4b90e8938228688bc49bdcdd6b2d99e/.circleci/config.yml). + +`:project` +: The base directory name of the current Hugo project. This means that, in its default setting, every project will have separated file caches, which means that when you do `hugo --gc` you will not touch files related to other Hugo projects running on the same PC. + +`:resourceDir` +: This is the value of the `resourceDir` config option. + +maxAge +: This is the duration before a cache entry will be evicted, -1 means forever and 0 effectively turns that particular cache off. Uses Go's `time.Duration`, so valid values are `"10s"` (10 seconds), `"10m"` (10 minutes) and `"10h"` (10 hours). + +dir +: The absolute path to where the files for this cache will be stored. Allowed starting placeholders are `:cacheDir` and `:resourceDir` (see above). + +## Configuration Format Specs + +- [TOML Spec][toml] +- [YAML Spec][yaml] +- [JSON Spec][json] + +[`.Site.Params`]: /variables/site/ +[directory structure]: /getting-started/directory-structure +[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation" +[lookup order]: /templates/lookup-order/ +[Output Formats]: /templates/output-formats/ +[templates]: /templates/ +[toml]: https://github.com/toml-lang/toml +[yaml]: https://yaml.org/spec/ +[static-files]: /content-management/static-files/ diff --cc docs/content/en/getting-started/external-learning-resources/index.md index 7102e0831,000000000..61e7ed649 mode 100644,000000..100644 --- a/docs/content/en/getting-started/external-learning-resources/index.md +++ b/docs/content/en/getting-started/external-learning-resources/index.md @@@ -1,43 -1,0 +1,43 @@@ +--- +title: External Learning Resources +linktitle: External Learning Resources +description: A list of tutorials and books on Hugo. +date: 2019-10-20 +publishdate: 2019-10-20 +lastmod: 2019-10-20 +keywords: [books, tutorials, learning, usage] +menu: + docs: + parent: "getting-started" + weight: 70 +weight: 70 +sections_weight: 70 +draft: false +toc: false +--- + +## Books + +### Hugo In Action + +[![Hugo In Action](hia.jpg)](https://www.manning.com/books/hugo-in-action) + +Hugo in Action is a step-by-step guide to using Hugo to create static websites. Working with a complete example website and source code samples, you’ll learn how to build and host a low-maintenance, high-performance site that will wow your users and stay stable without relying on a third-party server. + +[Hugo In Action Home Page](https://www.manning.com/books/hugo-in-action) + +### Build Websites with Hugo + +[Build Websites with Hugo - Fast Web Development with Markdown (2020)](https://pragprog.com/titles/bhhugo/) by Brian P. Hogan. + +## Beginner tutorials + +### Hugo tutorial by CloudCannon + - [Step-by-step written tutorial](https://cloudcannon.com/community/learn/hugo-101/) to teach you the basics of creating a Hugo site. ++[Step-by-step written tutorial](https://cloudcannon.com/community/learn/hugo-beginner-tutorial/) to teach you the basics of creating a Hugo site. + +## Video tutorials + +* Mike Dane explains the various features of Hugo via dedicated tutorials on [YouTube](https://www.youtube.com/watch?list=PLLAZ4kZ9dFpOnyRlyS-liKL5ReHDcj4G3&v=qtIqKaDlqXo). + +* [Introduction to building your first Hugo site](https://cloudcannon.com/community/learn/hugo-beginner-tutorial/) by Mike Neumegen. diff --cc docs/content/en/hugo-pipes/js.md index c95688e68,000000000..6905a6555 mode 100644,000000..100644 --- a/docs/content/en/hugo-pipes/js.md +++ b/docs/content/en/hugo-pipes/js.md @@@ -1,163 -1,0 +1,163 @@@ +--- +title: JavaScript Building +description: Hugo Pipes can process JavaScript files with [ESBuild](https://github.com/evanw/esbuild). +date: 2020-07-20 +publishdate: 2020-07-20 +categories: [asset management] +keywords: [] +menu: + docs: + parent: "pipes" + weight: 45 +weight: 45 +sections_weight: 45 +--- + +Any JavaScript resource file can be transpiled and "tree shaken" using `js.Build` which takes for argument either a string for the filepath or a dict of options listed below. + +### Options + +targetPath [string] +: If not set, the source path will be used as the base target path. +Note that the target path's extension may change if the target MIME type is different, e.g. when the source is TypeScript. + +params [map or slice] +: Params that can be imported as JSON in your JS files, e.g.: + +```go-html-template +{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }} +``` +And then in your JS file: + +```js +import * as params from '@params'; +``` + +Note that this is meant for small data sets, e.g. config settings. For larger data, please put/mount the files into `/assets` and import them directly. + +minify [bool] +: Let `js.Build` handle the minification. + +inject [slice] +: This option allows you to automatically replace a global variable with an import from another file. The path names must be relative to `assets`. See https://esbuild.github.io/api/#inject + - shims ++shims [map] +: This option allows swapping out a component with another. A common use case is to load dependencies like React from a CDN (with _shims_) when in production, but running with the full bundled `node_modules` dependency during development: + +```go-html-template +{{ $shims := dict "react" "js/shims/react.js" "react-dom" "js/shims/react-dom.js" }} +{{ $js = $js | js.Build dict "shims" $shims }} +``` + +The _shim_ files may look like these: + +```js +// js/shims/react.js +module.exports = window.React; +``` + +```js +// js/shims/react-dom.js +module.exports = window.ReactDOM; +``` + +With the above, these imports should work in both scenarios: + +```js +import * as React from 'react' +import * as ReactDOM from 'react-dom'; +``` + +target [string] +: The language target. + One of: `es5`, `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020` or `esnext`. + Default is `esnext`. + +externals [slice] +: External dependencies. Use this to trim dependencies you know will never be executed. See https://esbuild.github.io/api/#external + + +defines [map] +: Allow to define a set of string replacement to be performed when building. Should be a map where each key is to be replaced by its value. + +```go-html-template +{{ $defines := dict "process.env.NODE_ENV" `"development"` }} +``` + - format [string] ++format [string] +: The output format. + One of: `iife`, `cjs`, `esm`. + Default is `iife`, a self-executing function, suitable for inclusion as a +``` diff --cc docs/content/en/templates/404.md index 81c4c38bd,000000000..f0d2ecd9a mode 100644,000000..100644 --- a/docs/content/en/templates/404.md +++ b/docs/content/en/templates/404.md @@@ -1,66 -1,0 +1,66 @@@ +--- +title: Custom 404 Page +linktitle: 404 Page +description: If you know how to create a single page template, you have unlimited options for creating a custom 404. +date: 2017-02-01 +publishdate: 2017-02-01 +categories: [templates] +keywords: [404, page not found] +menu: + docs: + parent: "templates" + weight: 120 +weight: 120 #rem +draft: false +aliases: [] +toc: false +--- + - When using Hugo with [GitHub Pages](https://pages.github.com/), you can provide your own template for a [custom 404 error page](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-custom-404-page-for-your-github-pages-site) by creating a 404.html template file in your `/layouts` folder. When Hugo generates your site, the `404.html` file will be placed in the root. ++When using Hugo with [GitHub Pages](https://pages.github.com/), you can provide your own template for a [custom 404 error page](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-custom-404-page-for-your-github-pages-site) by creating a 404.html template file in the root of your `layouts` folder. When Hugo generates your site, the `404.html` file will be placed in the root. + +404 pages will have all the regular [page variables][pagevars] available to use in the templates. + +In addition to the standard page variables, the 404 page has access to all site content accessible from `.Pages`. + +```txt +▾ layouts/ + 404.html +``` + +## 404.html + +This is a basic example of a 404.html template: + +{{< code file="layouts/404.html" download="404.html" >}} +{{ define "main"}} +
    +
    +

    Go Home

    +
    +
    +{{ end }} +{{< /code >}} + +## Automatic Loading + +Your 404.html file can be set to load automatically when a visitor enters a mistaken URL path, dependent upon the web serving environment you are using. For example: + +* [GitHub Pages](/hosting-and-deployment/hosting-on-github/) and [GitLab Pages](/hosting-and-deployment/hosting-on-gitlab/). The 404 page is automatic. +* Apache. You can specify `ErrorDocument 404 /404.html` in an `.htaccess` file in the root of your site. +* Nginx. You might specify `error_page 404 /404.html;` in your `nginx.conf` file. [Details here](https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page). +* Amazon AWS S3. When setting a bucket up for static web serving, you can specify the error file from within the S3 GUI. +* Amazon CloudFront. You can specify the page in the Error Pages section in the CloudFront Console. [Details here](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/custom-error-pages.html) +* Caddy Server. Use the `handle_errors` directive to specify error pages for one or more status codes. [Details here](https://caddyserver.com/docs/caddyfile/directives/handle_errors) +* Netlify. Add `/* /404.html 404` to `content/_redirects`. [Details Here](https://www.netlify.com/docs/redirects/#custom-404) +* Azure Static Web App. set `responseOverrides.404.rewrite` and `responseOverrides.404.statusCode` in configfile `staticwebapp.config.json`. [Details here](https://docs.microsoft.com/en-us/azure/static-web-apps/configuration#response-overrides) +* Azure Storage as Static Web Site Hosting. You can specify the `Error document path` in the Static website configuration page of the Azure portal. [Details here](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website). +* DigitalOcean App Platform. You can specify `error_document` in your app specification file or use control panel to set up error document. [Details here](https://docs.digitalocean.com/products/app-platform/how-to/manage-static-sites/#configure-a-static-site). +* [Firebase Hosting](https://firebase.google.com/docs/hosting/full-config#404): `/404.html` automatically gets used as the 404 page. + +{{% note %}} +`hugo server` will not automatically load your custom `404.html` file, but you +can test the appearance of your custom "not found" page by navigating your +browser to `/404.html`. +{{% /note %}} + +[pagevars]: /variables/page/ diff --cc docs/content/en/templates/introduction.md index 87b7cab35,000000000..5145b04be mode 100644,000000..100644 --- a/docs/content/en/templates/introduction.md +++ b/docs/content/en/templates/introduction.md @@@ -1,671 -1,0 +1,681 @@@ +--- +title: Introduction to Hugo Templating +linktitle: Templating +description: Hugo uses Go's `html/template` and `text/template` libraries as the basis for the templating. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2022-09-20 +categories: [templates,fundamentals] +keywords: [go] +menu: + docs: + parent: "templates" + weight: 10 +weight: 10 +sections_weight: 10 +draft: false +aliases: [/layouts/introduction/,/layout/introduction/, /templates/go-templates/] +toc: true +--- + +{{% note %}} +The following is only a primer on Go Templates. For an in-depth look into Go Templates, check the official [Go docs](https://golang.org/pkg/text/template/). +{{% /note %}} + +Go Templates provide an extremely simple template language that adheres to the belief that only the most basic of logic belongs in the template or view layer. + +## Basic Syntax + +Go Templates are HTML files with the addition of [variables][variables] and [functions][functions]. Go Template variables and functions are accessible within `{{ }}`. + +### Access a Predefined Variable + +A _predefined variable_ could be a variable already existing in the +current scope (like the `.Title` example in the [Variables]({{< relref +"#variables" >}}) section below) or a custom variable (like the +`$address` example in that same section). + + +```go-html-template +{{ .Title }} +{{ $address }} +``` + +Parameters for functions are separated using spaces. The general syntax is: + +```go-html-template +{{ FUNCTION ARG1 ARG2 .. }} +``` + +The following example calls the `add` function with inputs of `1` and `2`: + +```go-html-template +{{ add 1 2 }} +``` + +#### Methods and Fields are Accessed via dot Notation + +Accessing the Page Parameter `bar` defined in a piece of content's [front matter]. + +```go-html-template +{{ .Params.bar }} +``` + +#### Parentheses Can be Used to Group Items Together + +```go-html-template +{{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }} +``` + +#### A Single Statement Can be Split over Multiple Lines + +```go-html-template +{{ if or + (isset .Params "alt") + (isset .Params "caption") +}} +``` + +#### Raw String Literals Can Include Newlines + +```go-html-template +{{ $msg := `Line one. +Line two.` }} +``` + +## Variables {#variables} + +Each Go Template gets a data object. In Hugo, each template is passed +a `Page`. In the below example, `.Title` is one of the elements +accessible in that [`Page` variable][pagevars]. + +With the `Page` being the default scope of a template, the `Title` +element in current scope (`.` -- "the **dot**") is accessible simply +by the dot-prefix (`.Title`): + +```go-html-template +{{ .Title }} +``` + +Values can also be stored in custom variables and referenced later: + +{{% note %}} +The custom variables need to be prefixed with `$`. +{{% /note %}} + +```go-html-template +{{ $address := "123 Main St." }} +{{ $address }} +``` + +Variables can be re-defined using the `=` operator. The example below +prints "Var is Hugo Home" on the home page, and "Var is Hugo Page" on +all other pages: + +```go-html-template +{{ $var := "Hugo Page" }} +{{ if .IsHome }} + {{ $var = "Hugo Home" }} +{{ end }} +Var is {{ $var }} +``` + +## Functions + +Go Templates only ship with a few basic functions but also provide a mechanism for applications to extend the original set. + +[Hugo template functions][functions] provide additional functionality specific to building websites. Functions are called by using their name followed by the required parameters separated by spaces. Template functions cannot be added without recompiling Hugo. + +### Example 1: Adding Numbers + +```go-html-template +{{ add 1 2 }} + +``` + +### Example 2: Comparing Numbers + +```go-html-template +{{ lt 1 2 }} + +``` + +Note that both examples make use of Go Template's [math][math] functions. + +{{% note "Additional Boolean Operators" %}} +There are more boolean operators than those listed in the Hugo docs in the [Go Template documentation](https://golang.org/pkg/text/template/#hdr-Functions). +{{% /note %}} + +## Includes + +When including another template, you will need to pass it the data that it would +need to access. + +{{% note %}} +To pass along the current context, please remember to include a trailing **dot**. +{{% /note %}} + +The templates location will always be starting at the `layouts/` directory +within Hugo. + +### Partial + +The [`partial`][partials] function is used to include _partial_ templates using +the syntax `{{ partial "/." . }}`. + +Example of including a `layouts/partials/header.html` partial: + +```go-html-template +{{ partial "header.html" . }} +``` + +### Template + +The `template` function was used to include _partial_ templates +in much older Hugo versions. Now it's useful only for calling +[_internal_ templates][internal templates]. The syntax is `{{ template +"_internal/