diff options
author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2022-12-20 11:04:41 +0100 |
---|---|---|
committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2022-12-20 11:04:41 +0100 |
commit | 41bc6f702aa54200530efbf4267e5c823df3028d (patch) | |
tree | 64aee58373ff8918bb0cc96676b85e04359698ff /content/en/templates | |
parent | da670c38ee63a7fef25e2b9f42519232055b60dc (diff) |
2c0125b52 Remove .Site.Author
2cf8841b3 Update partialCached.md (#1924)
385487191 Update data-templates.md (#1926)
ce207e141 Remove redundant markdown and fix a few typos (#1936)
3687c2953 Make heading id linkable, take 2
45c79bea7 Make heading id linkable
b22079344 Delete duplicates the lines 557-569 and 570-582. (#1934)
0a90dc122 Rework the taxonomy variables page (#1935)
7f8979c50 Update theme
26e682a3a Update multilingual.md
d40e7693f Update postcss.md
375d75c01 Update postcss npm instructions (#1931)
63020094a Emphasize Window shell selection (#1930)
56824be2c Update configuration.md
b7b8f16b3 Docu 'Theme components': minor fix (#1929)
09dc81a05 Remove Docker from BSD page (#1927)
205fea204 netlify: Hugo 0.108.0
6abe49c28 Merge commit 'da670c38ee63a7fef25e2b9f42519232055b60dc'
12b59a4c5 docs: Add basic doc for wrapStandAloneImageWithinParagraph etc.
ba07bd970 dartsass: Add sourceMapIncludeSources option
git-subtree-dir: docs
git-subtree-split: 2c0125b5290494d49334606c451446ebd9df3c21
Diffstat (limited to 'content/en/templates')
-rw-r--r-- | content/en/templates/data-templates.md | 28 | ||||
-rw-r--r-- | content/en/templates/homepage.md | 2 | ||||
-rw-r--r-- | content/en/templates/internal.md | 2 | ||||
-rw-r--r-- | content/en/templates/introduction.md | 6 | ||||
-rw-r--r-- | content/en/templates/lists.md | 4 | ||||
-rw-r--r-- | content/en/templates/output-formats.md | 4 | ||||
-rw-r--r-- | content/en/templates/pagination.md | 2 | ||||
-rw-r--r-- | content/en/templates/partials.md | 2 | ||||
-rw-r--r-- | content/en/templates/render-hooks.md | 11 | ||||
-rw-r--r-- | content/en/templates/shortcode-templates.md | 8 | ||||
-rw-r--r-- | content/en/templates/single-page-templates.md | 4 | ||||
-rw-r--r-- | content/en/templates/taxonomy-templates.md | 2 | ||||
-rw-r--r-- | content/en/templates/template-debugging.md | 2 |
13 files changed, 48 insertions, 29 deletions
diff --git a/content/en/templates/data-templates.md b/content/en/templates/data-templates.md index 1be4e93eb..1586d3a54 100644 --- a/content/en/templates/data-templates.md +++ b/content/en/templates/data-templates.md @@ -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]. + +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*). -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. +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 file (if applicable). +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. diff --git a/content/en/templates/homepage.md b/content/en/templates/homepage.md index b6ce87f8e..ace3f259b 100644 --- a/content/en/templates/homepage.md +++ b/content/en/templates/homepage.md @@ -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" }} diff --git a/content/en/templates/internal.md b/content/en/templates/internal.md index a92a0f551..05a6c862f 100644 --- a/content/en/templates/internal.md +++ b/content/en/templates/internal.md @@ -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 diff --git a/content/en/templates/introduction.md b/content/en/templates/introduction.md index 01f448778..87b7cab35 100644 --- a/content/en/templates/introduction.md +++ b/content/en/templates/introduction.md @@ -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`. diff --git a/content/en/templates/lists.md b/content/en/templates/lists.md index 18f03c6f1..03847707b 100644 --- a/content/en/templates/lists.md +++ b/content/en/templates/lists.md @@ -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 --> diff --git a/content/en/templates/output-formats.md b/content/en/templates/output-formats.md index 81a825493..0498c7e64 100644 --- a/content/en/templates/output-formats.md +++ b/content/en/templates/output-formats.md @@ -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] diff --git a/content/en/templates/pagination.md b/content/en/templates/pagination.md index dc56c18c4..bdb10d5bb 100644 --- a/content/en/templates/pagination.md +++ b/content/en/templates/pagination.md @@ -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 diff --git a/content/en/templates/partials.md b/content/en/templates/partials.md index b3826d56d..1899f87d5 100644 --- a/content/en/templates/partials.md +++ b/content/en/templates/partials.md @@ -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` diff --git a/content/en/templates/render-hooks.md b/content/en/templates/render-hooks.md index 6fae36ad9..69b34cc9b 100644 --- a/content/en/templates/render-hooks.md +++ b/content/en/templates/render-hooks.md @@ -84,7 +84,16 @@ PlainText : The plain variant of the above. Attributes (map) -: A map of attributes (e.g. `id`, `class`) +: A map of attributes (e.g. `id`, `class`). Note that this will currently always be empty for links. + +The `render-image` templates will also receive: + +IsBlock {{< new-in "0.108.0" >}} +: Returns true if this is a standalone image and the config option [markup.goldmark.parser.wrapStandAloneImageWithinParagraph](/getting-started/configuration-markup/#goldmark) is disabled. + +Ordinal {{< new-in "0.108.0" >}} +: Zero-based ordinal for all the images in the current document. + ### Link with title Markdown example diff --git a/content/en/templates/shortcode-templates.md b/content/en/templates/shortcode-templates.md index 15accbe7a..1c9314bb9 100644 --- a/content/en/templates/shortcode-templates.md +++ b/content/en/templates/shortcode-templates.md @@ -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 */>}} diff --git a/content/en/templates/single-page-templates.md b/content/en/templates/single-page-templates.md index b6d8241c2..2b0cfe0e2 100644 --- a/content/en/templates/single-page-templates.md +++ b/content/en/templates/single-page-templates.md @@ -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" }} diff --git a/content/en/templates/taxonomy-templates.md b/content/en/templates/taxonomy-templates.md index 9c283dfc3..e9fc80525 100644 --- a/content/en/templates/taxonomy-templates.md +++ b/content/en/templates/taxonomy-templates.md @@ -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 diff --git a/content/en/templates/template-debugging.md b/content/en/templates/template-debugging.md index ef8e205da..b8938890f 100644 --- a/content/en/templates/template-debugging.md +++ b/content/en/templates/template-debugging.md @@ -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 }} |