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

Merge commit '41bc6f702aa54200530efbf4267e5c823df3028d'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2022-12-20 11:04:41 +01:00
parent eda1e720cd 41bc6f702a
commit 9a215d6950
71 changed files with 292 additions and 256 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -18,23 +18,31 @@ toc: true
<!-- begin data files -->
Hugo supports loading data from YAML, JSON, XML, and TOML files located in the `data` directory in the root of your Hugo project.
Hugo supports loading data from YAML, JSON, XML, and TOML files located in the `data` directory at the root of your Hugo project.
{{< youtube FyPgSuwIMWQ >}}
## The Data Folder
The `data` folder is where you can store additional data for Hugo to use when generating your site. Data files aren't used to generate standalone pages; rather, they're meant to be supplemental to content files. This feature can extend the content in case your front matter fields grow out of control. Or perhaps you want to show a larger dataset in a template (see example below). In both cases, it's a good idea to outsource the data in their own files.
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:
- extending the content when the front matter fields grow out of control, or
- showing a larger dataset in a template (see the example below).
In both cases, it's a good idea to outsource the data in their (own) files.
These files must be YAML, JSON, XML, or TOML files (using the `.yml`, `.yaml`, `.json`, `.xml`, or `.toml` extension). The data will be accessible as a `map` in the `.Site.Data` variable.
If you wish to access the data using the `.Site.Data.filename` notation, the filename must begin with an underscore or a Unicode letter, followed by zero or more underscores, Unicode letters, or Unicode digits. eg:
To access the data using the `site.Data.filename` notation, the filename must begin with an underscore or a Unicode letter, followed by zero or more underscores, Unicode letters, or Unicode digits. For example:
- `123.json` - Invalid
- `x123.json` - Valid
- `_123.json` - Valid
If you wish to access the data using the [`index`](/functions/index-function/) function, the filename is irrelevant. For example:
To access the data using the [`index`](/functions/index-function/) function, the filename is irrelevant. For example:
Data file|Template code
:--|:--
`123.json`|`{{ index .Site.Data "123" }}`
@@ -44,11 +52,13 @@ Data file|Template code
## Data Files in Themes
Data Files can also be used in [Hugo themes][themes] but note that theme data files are merged with the project directory taking precedence (i.e., given two files with the same name and relative path, the data in the file in the root project `data` directory will override the data from the file in the `themes/<THEME>/data` directory *for keys that are duplicated*).
Data Files can also be used in [Hugo themes][themes].
Therefore, theme authors should take care to not include data files that could be easily overwritten by a user who decides to [customize a theme][customize]. For theme-specific data items that shouldn't be overridden, it can be wise to prefix the folder structure with a namespace; e.g. `mytheme/data/<THEME>/somekey/...`. To check if any such duplicate exists, run hugo with the `-v` flag.
However, note that the theme data files are merged with the project directory taking precedence. That is, Given two files with the same name and relative path, the data in the file in the root project `data` directory will override the data from the file in the `themes/<THEME>/data` directory *for keys that are duplicated*).
The keys in the map created with data templates from data files will be a dot-chained set of `path`, `filename`, and `key` in file (if applicable).
Therefore, theme authors should be careful not to include data files that could be easily overwritten by a user who decides to [customize a theme][customize]. For theme-specific data items that shouldn't be overridden, it can be wise to prefix the folder structure with a namespace; e.g. `mytheme/data/<THEME>/somekey/...`. To check if any such duplicate exists, run hugo with the `-v` flag.
The keys in the map created with data templates from data files will be a dot-chained set of `path`, `filename`, and `key` in the file (if applicable).
This is best explained with an example:
@@ -213,7 +223,7 @@ If you don't like caching at all, you can fully disable caching with the command
### Authentication When Using REST URLs
Currently, you can only use those authentication methods that can be put into an URL. [OAuth][] and other authentication methods are not implemented.
Currently, you can only use those authentication methods that can be put into an URL. [OAuth] and other authentication methods are not implemented.
## Load Local files
@@ -227,7 +237,7 @@ The local CSV files to be loaded using `getCSV` must be located **outside** the
## LiveReload with Data Files
There is no chance to trigger a [LiveReload][] when the content of a URL changes. However, when a *local* file changes (i.e., `data/*` and `themes/<THEME>/data/*`), a LiveReload will be triggered. Symlinks are not supported. Note too that because downloading of data takes a while, Hugo stops processing your Markdown files until the data download has completed.
There is no chance to trigger a [LiveReload] when the content of a URL changes. However, when a *local* file changes (i.e., `data/*` and `themes/<THEME>/data/*`), a LiveReload will be triggered. Symlinks are not supported. Note too that because downloading data takes a while, Hugo stops processing your Markdown files until the data download has been completed.
{{% warning "URL Data and LiveReload" %}}
If you change any local file and the LiveReload is triggered, Hugo will read the data-driven (URL) content from the cache. If you have disabled the cache (i.e., by running the server with `hugo server --ignoreCache`), Hugo will re-download the content every time LiveReload triggers. This can create *huge* traffic. You may reach API limits quickly.

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

@@ -38,7 +38,7 @@ See the homepage template below or [Content Organization][contentorg] for more i
## Example Homepage Template
The following is an example of a homepage template that uses [partial][partials], [base][] templates, and a content file at `content/_index.md` to populate the `{{.Title}}` and `{{.Content}}` [page variables][pagevars].
The following is an example of a homepage template that uses [partial][partials], [base] templates, and a content file at `content/_index.md` to populate the `{{.Title}}` and `{{.Content}}` [page variables][pagevars].
{{< code file="layouts/index.html" download="index.html" >}}
{{ define "main" }}

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

@@ -29,7 +29,7 @@ While the following internal templates are called similar to partials, they do *
Hugo ships with internal templates supporting Google Analytics, both [Google Analytics 4][GA4] (GA4) and Universal Analytics.
**Note:** Universal Analytics are deprecated. For details, see [Universal Analytics will be going away][].
**Note:** Universal Analytics are deprecated. For details, see [Universal Analytics will be going away].
[GA4]: https://support.google.com/analytics/answer/10089681
[Universal Analytics will be going away]: https://support.google.com/analytics/answer/11583528

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

@@ -55,7 +55,7 @@ The following example calls the `add` function with inputs of `1` and `2`:
#### Methods and Fields are Accessed via dot Notation
Accessing the Page Parameter `bar` defined in a piece of content's [front matter][].
Accessing the Page Parameter `bar` defined in a piece of content's [front matter].
```go-html-template
{{ .Params.bar }}
@@ -519,11 +519,11 @@ The templating engine will strip the content within the HTML comment, but will f
## Hugo Parameters
Hugo provides the option of passing values to your template layer through your [site configuration][config] (i.e. for site-wide values) or through the metadata of each specific piece of content (i.e. the [front matter][]). You can define any values of any type and use them however you want in your templates, as long as the values are supported by the [front matter format]({{< ref "front-matter.md#front-matter-formats" >}}).
Hugo provides the option of passing values to your template layer through your [site configuration][config] (i.e. for site-wide values) or through the metadata of each specific piece of content (i.e. the [front matter]). You can define any values of any type and use them however you want in your templates, as long as the values are supported by the [front matter format]({{< ref "front-matter.md#front-matter-formats" >}}).
## Use Content (`Page`) Parameters
You can provide variables to be used by templates in individual content's [front matter][].
You can provide variables to be used by templates in individual content's [front matter].
An example of this is used in the Hugo docs. Most of the pages benefit from having the table of contents provided, but sometimes the table of contents doesn't make a lot of sense. We've defined a `notoc` variable in our front matter that will prevent a table of contents from rendering when specifically set to `true`.

4
docs/content/en/templates/lists.md
View File

@@ -199,7 +199,7 @@ This list template has been modified slightly from a template originally used in
## Order Content
Hugo lists render the content based on metadata you provide in [front matter][]. In addition to sane defaults, Hugo also ships with multiple methods to make quick work of ordering content inside list templates:
Hugo lists render the content based on metadata you provide in [front matter]. In addition to sane defaults, Hugo also ships with multiple methods to make quick work of ordering content inside list templates:
### Default: Weight > Date > LinkTitle > FilePath
@@ -499,7 +499,7 @@ In the above example, you may want `{{.Title}}` to point the `title` field you h
### By Page Parameter in Date Format
The following template takes grouping by `date` a step further and uses Go's layout string. See the [`Format` function][] for more examples of how to use Go's layout string to format dates in Hugo.
The following template takes grouping by `date` a step further and uses Go's layout string. See the [`Format` function] for more examples of how to use Go's layout string to format dates in Hugo.
{{< code file="layouts/partials/by-page-param-as-date.html" >}}
<!-- Groups content by month according to the "param_key" field in front matter -->

4
docs/content/en/templates/output-formats.md
View File

@@ -22,7 +22,7 @@ This page describes how to properly configure your site with the media types and
## Media Types
A [media type][] (also known as _MIME type_ and _content type_) is a two-part identifier for file formats and format contents transmitted on the internet.
A [media type] (also known as _MIME type_ and _content type_) is a two-part identifier for file formats and format contents transmitted on the internet.
This is the full set of built-in media types in Hugo:
@@ -228,7 +228,7 @@ A new output format needs a corresponding template in order to render anything u
The key distinction for Hugo versions 0.20 and newer is that Hugo looks at an output format's `Name` and MediaType's `Suffixes` when choosing the template used to render a given `Page`.
{{% /note %}}
The following table shows examples of different output formats, the suffix used, and Hugo's respective template [lookup order][]. All the examples in the table can:
The following table shows examples of different output formats, the suffix used, and Hugo's respective template [lookup order]. All the examples in the table can:
* Use a [base template][base].
* Include [partial templates][partials]

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

@@ -16,7 +16,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][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.
## Configure Pagination

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

@@ -22,7 +22,7 @@ toc: true
## Partial Template Lookup Order
Partial templates---like [single page templates][singletemps] and [list page templates][listtemps]---have a specific [lookup order][]. However, partials are simpler in that Hugo will only check in two places:
Partial templates---like [single page templates][singletemps] and [list page templates][listtemps]---have a specific [lookup order]. However, partials are simpler in that Hugo will only check in two places:
1. `layouts/partials/*<PARTIALNAME>.html`
2. `themes/<THEME>/layouts/partials/*<PARTIALNAME>.html`

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

@@ -18,7 +18,7 @@ aliases: []
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. In this sense, you can think of shortcodes as the intermediary between [page and list templates][templates] and [basic content files].
{{% note %}}
Hugo also ships with built-in shortcodes for common use cases. (See [Content Management: Shortcodes](/content-management/shortcodes/).)
@@ -32,7 +32,7 @@ Hugo's built-in shortcodes cover many common, but not all, use cases. Luckily, H
### File Location
To create a shortcode, place an HTML template in the `layouts/shortcodes` directory of your [source organization][]. Consider the file name carefully since the shortcode name will mirror that of the file but without the `.html` extension. For example, `layouts/shortcodes/myshortcode.html` will be called with either `{{</* myshortcode /*/>}}` or `{{%/* myshortcode /*/%}}` depending on the type of parameters you choose.
To create a shortcode, place an HTML template in the `layouts/shortcodes` directory of your [source organization]. Consider the file name carefully since the shortcode name will mirror that of the file but without the `.html` extension. For example, `layouts/shortcodes/myshortcode.html` will be called with either `{{</* myshortcode /*/>}}` or `{{%/* myshortcode /*/%}}` depending on the type of parameters you choose.
You can organize your shortcodes in subfolders, e.g. in `layouts/shortcodes/boxes`. These shortcodes would then be accessible with their relative path, e.g:
@@ -44,7 +44,7 @@ Note the forward slash.
### Shortcode Template Lookup Order
Shortcode templates have a simple [lookup order][]:
Shortcode templates have a simple [lookup order]:
1. `/layouts/shortcodes/<SHORTCODE>.html`
2. `/themes/<THEME>/layouts/shortcodes/<SHORTCODE>.html`
@@ -279,7 +279,7 @@ Would be rendered as:
### Paired Example: `highlight`
The following is taken from `highlight`, which is a [built-in shortcode][] that ships with Hugo.
The following is taken from `highlight`, which is a [built-in shortcode] that ships with Hugo.
{{< code file="highlight-example.md" >}}
{{</* highlight html */>}}

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

@@ -24,11 +24,11 @@ See [Template Lookup](/templates/lookup-order/).
## Example Single Page Templates
Content pages are of the type `page` and will therefore have all the [page variables][pagevars] and [site variables][] available to use in their templates.
Content pages are of the type `page` and will therefore have all the [page variables][pagevars] and [site variables] available to use in their templates.
### `posts/single.html`
This single page template makes use of Hugo [base templates][], the [`.Format` function][] for dates, the [`.WordCount` page variable][pagevars], and ranges through the single content's specific [taxonomies][pagetaxonomy]. [`with`][] is also used to check whether the taxonomies are set in the front matter.
This single page template makes use of Hugo [base templates], the [`.Format` function] for dates, the [`.WordCount` page variable][pagevars], and ranges through the single content's specific [taxonomies][pagetaxonomy]. [`with`] is also used to check whether the taxonomies are set in the front matter.
{{< code file="layouts/posts/single.html" download="single.html" >}}
{{ define "main" }}

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

@@ -27,7 +27,7 @@ Hugo provides multiple ways to use taxonomies throughout your project templates:
* Order the way content associated with a taxonomy term is displayed in a [taxonomy list template](#taxonomy-list-templates)
* Order the way the terms for a taxonomy are displayed in a [taxonomy terms template](#taxonomy-terms-templates)
* List a single content's taxonomy terms within a [single page template][]
* List a single content's taxonomy terms within a [single page template]
## Taxonomy List Templates

2
docs/content/en/templates/template-debugging.md
View File

@@ -40,7 +40,7 @@ This will print out a list of all the variables scoped to the current context
{{ printf "%#v" . }}
```
When developing a [homepage][], what does one of the pages you're looping through look like?
When developing a [homepage], what does one of the pages you're looping through look like?
```go-html-template
{{ range .Pages }}