mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-20 21:31:32 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit 'e509cac533600cf4fa8382c9cdab78ddd82db688'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2023-10-20 09:43:56 +02:00
parent fd38171810 e509cac533
commit e2dd4cd05f
298 changed files with 4568 additions and 1991 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
docs/content/en/templates/data-templates.md
View File

@@ -20,7 +20,7 @@ Hugo supports loading data from YAML, JSON, XML, and TOML files located in the `
## The data folder
The `data` folder should store additional data for Hugo to use when generating your site.
The `data` folder should store additional data for Hugo to use when generating your site.
Data files are not for generating standalone pages. They should supplement content files by:
@@ -37,7 +37,7 @@ To access the data using the `site.Data.filename` notation, the file name must b
- `x123.json` - Valid
- `_123.json` - Valid
To access the data using the [`index`](/functions/index-function/) function, the file name is irrelevant. For example:
To access the data using the [`index`](/functions/collections/indexfunction) function, the file name is irrelevant. For example:
Data file|Template code
:--|:--
@@ -130,8 +130,7 @@ You can use the following code to render the `Short Description` in your layout:
<div>Short Description of {{ .Site.Data.User0123.Name }}: <p>{{ index .Site.Data.User0123 "Short Description" | markdownify }}</p></div>
```
Note the use of the [`markdownify` template function][markdownify]. This will send the description through the Markdown rendering engine.
Note the use of the [`markdownify`] function. This will send the description through the Markdown rendering engine.
## Get remote data
@@ -255,10 +254,10 @@ If you change any local file and the LiveReload is triggered, Hugo will read the
[config]: /getting-started/configuration/
[csv]: https://tools.ietf.org/html/rfc4180
[customize]: /hugo-modules/theme-components/
[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation"
[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf
[LiveReload]: /getting-started/usage/#livereload
[lookup]: /templates/lookup-order/
[markdownify]: /functions/markdownify/
[`markdownify`]: /functions/transform/markdownify
[OAuth]: https://en.wikipedia.org/wiki/OAuth
[partials]: /templates/partials/
[toml]: https://toml.io/en/latest

13
docs/content/en/templates/files.md
View File

@@ -14,11 +14,11 @@ toc: true
## Traverse local files
With Hugo's [`readDir`][readDir] and [`readFile`][readFile] template functions, you can traverse your website's files on your server.
With Hugo's [`readDir`] and [`readFile`] template functions, you can traverse your website's files on your server.
## Use `readDir`
The [`readDir` function][readDir] returns an array of [`os.FileInfo`][osfileinfo]. It takes the file's `path` as a single string argument. This path can be to any directory of your website (i.e., as found on your server's file system).
The [`readDir`] function returns an array of [`os.FileInfo`] structures. It takes the file's `path` as a single string argument. This path can be to any directory of your website (i.e., as found on your server's file system).
Whether the path is absolute or relative does not matter because---at least for `readDir`---the root of your website (typically `./public/`) in effect becomes both:
@@ -27,7 +27,7 @@ Whether the path is absolute or relative does not matter because---at least for
## Use `readFile`
The [`readfile` function][readFile] reads a file from disk and converts it into a string to be manipulated by other Hugo functions or added as-is. `readFile` takes the file, including path, as an argument passed to the function.
The [`readfile`] function reads a file from disk and converts it into a string to be manipulated by other Hugo functions or added as-is. `readFile` takes the file, including path, as an argument passed to the function.
To use the `readFile` function in your templates, make sure the path is relative to your *Hugo project's root directory*:
@@ -48,10 +48,9 @@ If you are going to create [custom shortcodes](/templates/shortcode-templates/)
{{% /note %}}
[called directly in the Hugo docs]: https://github.com/gohugoio/hugoDocs/blob/master/content/en/templates/files.md
[osfileinfo]: https://golang.org/pkg/os/#FileInfo
[readDir]: /functions/readdir/
[readFile]: /functions/readfile/
[`os.FileInfo`]: https://pkg.go.dev/io/fs#FileInfo
[`readDir`]: /functions/os/readdir
[`readFile`]: /functions/os/readfile
[sc]: /content-management/shortcodes/
[sct]: /templates/shortcode-templates/
[readfilesource]: https://github.com/gohugoio/hugoDocs/blob/master/layouts/shortcodes/readfile.html
[testfile]: https://github.com/gohugoio/hugoDocs/blob/master/content/en/readfiles/testing.txt

21
docs/content/en/templates/introduction.md
View File

@@ -301,7 +301,7 @@ Below example is "Example 1" rewritten using `if`:
#### Example 4: `if` .. `else`
Below example is "Example 2" rewritten using `if` .. `else`, and using
[`isset` function][isset] + `.Params` variable (different from the
[`isset`] + `.Params` variable (different from the
[`.Param` **function**][param]) instead:
```go-html-template
@@ -355,7 +355,7 @@ The following two examples are functionally the same:
### Example 2: `index`
The following accesses the page parameter called "disqus_url" and escapes the HTML. This example also uses the [`index` function](/functions/index-function/), which is built into Go Templates:
The following accesses the page parameter called "disqus_url" and escapes the HTML. This example also uses the [`index`] function, which is built into Go Templates:
```go-html-template
{{ index .Params "disqus_url" | html }}
@@ -569,7 +569,7 @@ params:
sidebarrecentlimit: 5
{{< /code >}}
Within a footer layout, you might then declare a `<footer>` that is only rendered if the `copyrighthtml` parameter is provided. If it *is* provided, you will then need to declare the string is safe to use via the [`safeHTML` function][safehtml] so that the HTML entity is not escaped again. This would let you easily update just your top-level configuration file each January 1st, instead of hunting through your templates.
Within a footer layout, you might then declare a `<footer>` that is only rendered if the `copyrighthtml` parameter is provided. If it *is* provided, you will then need to declare the string is safe to use via the [`safeHTML`] function so that the HTML entity is not escaped again. This would let you easily update just your top-level configuration file each January 1st, instead of hunting through your templates.
```go-html-template
{{ if .Site.Params.copyrighthtml }}
@@ -579,7 +579,7 @@ Within a footer layout, you might then declare a `<footer>` that is only rendere
{{ end }}
```
An alternative way of writing the "`if`" and then referencing the same value is to use [`with`][with] instead. `with` rebinds the context (`.`) within its scope and skips the block if the variable is absent:
An alternative way of writing the "`if`" and then referencing the same value is to use [`with`] instead. `with` rebinds the context (`.`) within its scope and skips the block if the variable is absent:
{{< code file="layouts/partials/twitter.html" >}}
{{ with .Site.Params.twitteruser }}
@@ -590,7 +590,7 @@ An alternative way of writing the "`if`" and then referencing the same value is
{{ end }}
{{< /code >}}
Finally, you can pull "magic constants" out of your layouts as well. The following uses the [`first`][first] function, as well as the [`.RelPermalink`][relpermalink] page variable and the [`.Site.Pages`][sitevars] site variable.
Finally, you can pull "magic constants" out of your layouts as well. The following uses the [`first`] function, as well as the [`.RelPermalink`][relpermalink] page variable and the [`.Site.Pages`][sitevars] site variable.
```go-html-template
<nav>
@@ -653,19 +653,20 @@ If you restrict front matter to the TOML format, and omit quotation marks surrou
</ul>
{{< /code >}}
[dotdoc]: https://golang.org/pkg/text/template/#hdr-Variables
[`first`]: /functions/collections/first
[`index`]: /functions/collections/indexfunction
[`isset`]: /functions/collections/isset
[config]: /getting-started/configuration
[first]: /functions/first
[dotdoc]: https://golang.org/pkg/text/template/#hdr-Variables
[front matter]: /content-management/front-matter
[functions]: /functions
[internal templates]: /templates/internal
[isset]: /functions/isset
[math]: /functions/math
[pagevars]: /variables/page
[param]: /functions/param
[partials]: /templates/partials
[relpermalink]: /variables/page#page-variables
[safehtml]: /functions/safehtml
[`safehtml`]: /functions/safe/html
[sitevars]: /variables/site
[variables]: /variables
[with]: /functions/with
[`with`]: /functions/go-template/with

25
docs/content/en/templates/lists/index.md
View File

@@ -418,7 +418,7 @@ In the above example, you may want `{{ .Title }}` to point the `title` field you
{{ end }}
{{< /code >}}
{{< new-in "0.97.0" >}} `GroupByDate` accepts the same time layouts as in [time.Format](/functions/dateformat/) and The `.Key` in the result will be localized for the current language.
{{< new-in "0.97.0" >}} `GroupByDate` accepts the same time layouts as in [`time.Format`] and the `.Key` in the result will be localized for the current language.
### By publish date
@@ -437,8 +437,7 @@ In the above example, you may want `{{ .Title }}` to point the `title` field you
{{ end }}
{{< /code >}}
{{< new-in "0.97.0" >}} `GroupByDate` accepts the same time layouts as in [time.Format](/functions/dateformat/) and The `.Key` in the result will be localized for the current language.
{{< new-in "0.97.0" >}} `GroupByDate` accepts the same time layouts as in [`time.Format`] and the `.Key` in the result will be localized for the current language.
### By expiration date
@@ -457,7 +456,7 @@ In the above example, you may want `{{ .Title }}` to point the `title` field you
{{ end }}
{{< /code >}}
{{< new-in "0.97.0" >}} `GroupByDate` accepts the same time layouts as in [time.Format](/functions/dateformat/) and The `.Key` in the result will be localized for the current language.
{{< new-in "0.97.0" >}} `GroupByDate` accepts the same time layouts as in [`time.Format`] and the `.Key` in the result will be localized for the current language.
### By last modified date
@@ -476,7 +475,7 @@ In the above example, you may want `{{ .Title }}` to point the `title` field you
{{ end }}
{{< /code >}}
{{< new-in "0.97.0" >}} `GroupByDate` accepts the same time layouts as in [time.Format](/functions/dateformat/) and The `.Key` in the result will be localized for the current language.
{{< new-in "0.97.0" >}} `GroupByDate` accepts the same time layouts as in [`time.Format`] and the `.Key` in the result will be localized for the current language.
### By page parameter
@@ -567,11 +566,11 @@ Here is the ordering for the example that follows:
## Filtering and limiting lists
Sometimes you only want to list a subset of the available content. A
common is to only display posts from [**main sections**][mainsections]
common is to only display posts from [main sections]
on the blog's homepage.
See the documentation on [`where` function][wherefunction] and
[`first` function][firstfunction] for further details.
See the documentation on [`where`] and
[`first`] for further details.
[base]: /templates/base/
[bepsays]: https://bepsays.com/en/2016/12/19/hugo-018/
@@ -580,11 +579,10 @@ See the documentation on [`where` function][wherefunction] and
[front matter]: /content-management/front-matter/
[getpage]: /functions/getpage/
[homepage]: /templates/homepage/
[homepage]: /templates/homepage/
[mentalmodel]: https://webstyleguide.com/wsg3/3-information-architecture/3-site-structure.html
[pagevars]: /variables/page/
[partials]: /templates/partials/
[RSS 2.0]: https://cyber.harvard.edu/rss/rss.html "RSS 2.0 Specification"
[RSS 2.0]: https://cyber.harvard.edu/rss/rss.html
[rss]: /templates/rss/
[sections]: /content-management/sections/
[sectiontemps]: /templates/section-templates/
@@ -593,6 +591,7 @@ See the documentation on [`where` function][wherefunction] and
[taxterms]: /templates/taxonomy-templates/#taxonomy-terms-templates
[taxvars]: /variables/taxonomy/
[views]: /templates/views/
[wherefunction]: /functions/where/
[firstfunction]: /functions/first/
[mainsections]: /functions/where/#mainsections
[`where`]: /functions/collections/where
[`first]: /functions/first/
[main sections]: /functions/collections/where#mainsections
[`time.Format`]: /functions/time/format

60
docs/content/en/templates/lookup-order.md
View File

@@ -39,6 +39,66 @@ Section
Templates can live in either the project's or the themes' layout folders, and the most specific templates will be chosen. Hugo will interleave the lookups listed below, finding the most specific one either in the project or themes.
{{% /note %}}
## Target a template
You cannot change the lookup order to target a content page, but you can change a content page to target a template. Specify `type`, `layout`, or both in front matter.
Consider this content structure:
```text
content/
├── about.md
└── contact.md
```
Files in the root of the content directory have a [content type] of `page`. To render these pages with a unique template, create a matching subdirectory:
[content type]: /getting-started/glossary/#content-type
```text
layouts/
└── page/
└── single.html
```
But the contact page probably has a form and requires a different template. In the front matter specify `layout`:
{{< code-toggle file=content/contact.md copy=false >}}
title = 'Contact'
layout = 'contact'
{{< /code-toggle >}}
Then create the template for the contact page:
```text
layouts/
└── page/
└── contact.html <-- renders contact.md
└── single.html <-- renders about.md
```
As a content type, the word `page` is vague. Perhaps `miscellaneous` would be better. Add `type` to the front matter of each page:
{{< code-toggle file=content/about.md copy=false >}}
title = 'About'
type = 'miscellaneous'
{{< /code-toggle >}}
{{< code-toggle file=content/contact.md copy=false >}}
title = 'Contact'
type = 'miscellaneous'
layout = 'contact'
{{< /code-toggle >}}
Now place the layouts in the corresponding directory:
```text
layouts/
└── miscellaneous/
└── contact.html <-- renders contact.md
└── single.html <-- renders about.md
```
## Home page
{{< datatable-filtered "output" "layouts" "Kind == home" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}

8
docs/content/en/templates/menu-templates.md
View File

@@ -49,6 +49,12 @@ This partial template recursively "walks" a menu structure, rendering a localize
{{- else if $page.HasMenuCurrent .Menu .}}
{{- $attrs = merge $attrs (dict "class" "ancestor" "aria-current" "true") }}
{{- end }}
{{- $name := .Name }}
{{- with .Identifier }}
{{- with T . }}
{{- $name = . }}
{{- end }}
{{- end }}
<li>
<a
{{- range $k, $v := $attrs }}
@@ -56,7 +62,7 @@ This partial template recursively "walks" a menu structure, rendering a localize
{{- printf " %s=%q" $k $v | safeHTMLAttr }}
{{- end }}
{{- end -}}
>{{ or (T .Identifier) .Name | safeHTML }}</a>
>{{ $name }}</a>
{{- with .Children }}
<ul>
{{- partial "inline/menu/walk.html" (dict "page" $page "menuEntries" .) }}

10
docs/content/en/templates/pagination.md
View File

@@ -12,7 +12,7 @@ aliases: [/extras/pagination,/doc/pagination/]
toc: true
---
The real power of Hugo pagination shines when combined with the [`where` function][where] and its SQL-like operators: [`first`], [`last`], and [`after`]. You can even [order the content][lists] the way you've become used to with Hugo.
The real power of Hugo pagination shines when combined with the [`where`] function and its SQL-like operators: [`first`], [`last`], and [`after`]. You can even [order the content][lists] the way you've become used to with Hugo.
## Configure pagination
@@ -146,9 +146,9 @@ The pages are built on the following form (`BLANK` means no value):
....
```
[`first`]: /functions/first/
[`last`]: /functions/last/
[`after`]: /functions/after/
[`first`]: /functions/collections/first/
[`last`]: /functions/collections/last/
[`after`]: /functions/collections/after/
[configuration]: /getting-started/configuration/
[lists]: /templates/lists/
[where]: /functions/where/
[`where`]: /functions/collections/where

2
docs/content/en/templates/partials.md
View File

@@ -177,6 +177,6 @@ The following `footer.html` partial template is used for [spf13.com](https://spf
[customize]: /hugo-modules/theme-components/
[listtemps]: /templates/lists/
[lookup order]: /templates/lookup-order/
[partialcached]: /functions/partialcached/
[partialcached]: /functions/partials/includecached
[singletemps]: /templates/single-page-templates/
[themes]: /themes/

4
docs/content/en/templates/section-templates.md
View File

@@ -29,7 +29,7 @@ Every `Page` in Hugo has a `.Kind` attribute.
## `.Site.GetPage` with sections
`Kind` can easily be combined with the [`where` function][where] in your templates to create kind-specific lists of content. This method is ideal for creating lists, but there are times where you may want to fetch just the index page of a single section via the section's path.
`Kind` can easily be combined with the [`where`] function in your templates to create kind-specific lists of content. This method is ideal for creating lists, but there are times where you may want to fetch just the index page of a single section via the section's path.
The [`.GetPage` function][getpage] looks up an index page of a given `Kind` and `path`.
@@ -106,5 +106,5 @@ Which then returns the following:
[getpage]: /functions/getpage/
[lists]: /templates/lists/
[lookup]: /templates/lookup-order/
[where]: /functions/where/
[`where`]: /functions/collections/where
[sections]: /content-management/sections/

8
docs/content/en/templates/shortcode-templates.md
View File

@@ -12,7 +12,7 @@ weight: 130
toc: true
---
Shortcodes are a means to consolidate templating into small, reusable snippets that you can embed directly inside your content. In this sense, you can think of shortcodes as the intermediary between [page and list templates][templates] and [basic content files].
Shortcodes are a means to consolidate templating into small, reusable snippets that you can embed directly inside your content.
{{% note %}}
Hugo also ships with built-in shortcodes for common use cases. (See [Content Management: Shortcodes](/content-management/shortcodes/).)
@@ -349,7 +349,7 @@ This will output the following HTML. Note how the first two `img` shortcodes inh
## Error handling in shortcodes
Use the [errorf](/functions/errorf) template func and [.Position](/variables/shortcodes/) variable to get useful error messages in shortcodes:
Use the [errorf](/functions/fmt/errorf) template func and [.Position](/variables/shortcodes/) variable to get useful error messages in shortcodes:
```bash
{{ with .Get "name" }}
@@ -402,7 +402,7 @@ The same inline shortcode can be reused later in the same content file, with dif
[built-in shortcode]: /content-management/shortcodes/
[config]: /getting-started/configuration/
[Content Management: Shortcodes]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes
[source organization]: /getting-started/directory-structure/#directory-structure-explained
[source organization]: /getting-started/directory-structure/
[docsshortcodes]: https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes
[figure]: /content-management/shortcodes/#figure
[hugosc]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes
@@ -410,6 +410,6 @@ The same inline shortcode can be reused later in the same content file, with dif
[pagevars]: /variables/page/
[parent]: /variables/shortcodes/
[shortcodesvars]: /variables/shortcodes/
[spfscs]: https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes
[spfscs]: https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes
[vimeoexample]: #single-flexible-example-vimeo
[youtubeshortcode]: /content-management/shortcodes/#youtube

2
docs/content/en/templates/single-page-templates.md
View File

@@ -82,4 +82,4 @@ To easily generate new instances of a content type (e.g., new `.md` files in a s
[section]: /content-management/sections/
[site variables]: /variables/site/
[spf13]: https://spf13.com/
[`with`]: /functions/with/
[`with`]: /functions/go-template/with/

9
docs/content/en/templates/taxonomy-templates.md
View File

@@ -269,7 +269,7 @@ This may take the form of a tag cloud, a menu, or simply a list.
The following example displays all terms in a site's tags taxonomy:
### Example: list all site tags
### Example: list all site tags
```go-html-template
<ul>
@@ -322,12 +322,7 @@ Because taxonomies are lists, the [`.GetPage` function][getpage] can be used to
</ul>
{{< /code >}}
<!-- TODO: ### `.Site.GetPage` Taxonomy List Example -->
<!-- TODO: ### `.Site.GetPage` Taxonomy Terms Example -->
[delimit]: /functions/delimit/
[delimit]: /functions/collections/delimit/
[getpage]: /functions/getpage/
[lists]: /templates/lists/
[renderlists]: /templates/lists/