mirror of
https://github.com/gohugoio/hugo.git
synced 2026-08-24 23:38:53 +00:00
Ensure consistent use of method instead of variable
This commit is contained in:
Joe Mooring
@@ -16,7 +16,7 @@ The `ref` and `relref` shortcodes display the absolute and relative permalinks t
|
||||
|
||||
## Use of `ref` and `relref`
|
||||
|
||||
The `ref` and `relref` shortcodes require a single parameter: the path to a content document, with or without a file extension, with or without an anchor. Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site.
|
||||
The `ref` and `relref` shortcodes require a single argument: the path to a content document, with or without a file extension, with or without an anchor. Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site.
|
||||
|
||||
```text
|
||||
.
|
||||
|
||||
@@ -104,7 +104,7 @@ Use data sources to augment existing content. For example, create a shortcode to
|
||||
{{ errorf "The %q shortcode was unable to find %s. See %s" $.Name $file $.Position }}
|
||||
{{ end }}
|
||||
{{ else }}
|
||||
{{ errorf "The %q shortcode requires one positional parameter, the path to the CSV file relative to the assets directory. See %s" .Name .Position }}
|
||||
{{ errorf "The %q shortcode requires one positional argument, the path to the CSV file relative to the assets directory. See %s" .Name .Position }}
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
|
||||
@@ -27,9 +27,9 @@ In addition to cleaner Markdown, shortcodes can be updated any time to reflect n
|
||||
|
||||
{{< youtube 2xkNJL4gJ9E >}}
|
||||
|
||||
In your content files, a shortcode can be called by calling `{{%/* shortcodename parameters */%}}`. Shortcode parameters are space delimited, and parameters with internal spaces can be quoted.
|
||||
In your content files, a shortcode can be called by calling `{{%/* shortcodename arguments */%}}`. Shortcode arguments are space delimited, and arguments with internal spaces must be quoted.
|
||||
|
||||
The first word in the shortcode declaration is always the name of the shortcode. Parameters follow the name. Depending upon how the shortcode is defined, the parameters may be named, positional, or both, although you can't mix parameter types in a single call. The format for named parameters models that of HTML with the format `name="value"`.
|
||||
The first word in the shortcode declaration is always the name of the shortcode. Arguments follow the name. Depending upon how the shortcode is defined, the arguments may be named, positional, or both, although you can't mix argument types in a single call. The format for named arguments models that of HTML with the format `name="value"`.
|
||||
|
||||
Some shortcodes use or require closing shortcodes. Again like HTML, the opening and closing shortcodes match (name only) with the closing declaration, which is prepended with a slash.
|
||||
|
||||
@@ -45,9 +45,9 @@ Here are two examples of paired shortcodes:
|
||||
|
||||
The examples above use two different delimiters, the difference being the `%` character in the first and the `<>` characters in the second.
|
||||
|
||||
### Shortcodes with raw string parameters
|
||||
### Shortcodes with raw string arguments
|
||||
|
||||
You can pass multiple lines as parameters to a shortcode by using raw string literals:
|
||||
You can pass multiple lines as arguments to a shortcode by using raw string literals:
|
||||
|
||||
```go-html-template
|
||||
{{</* myshortcode `This is some <b>HTML</b>,
|
||||
@@ -82,7 +82,7 @@ To override Hugo's embedded `figure` shortcode, copy the [source code] to a file
|
||||
[source code]: {{% eturl figure %}}
|
||||
{{% /note %}}
|
||||
|
||||
The `figure` shortcode can use the following named parameters:
|
||||
The `figure` shortcode can use the following named arguments:
|
||||
|
||||
src
|
||||
: URL of the image to be displayed.
|
||||
@@ -91,10 +91,10 @@ link
|
||||
: If the image needs to be hyperlinked, URL of the destination.
|
||||
|
||||
target
|
||||
: Optional `target` attribute for the URL if `link` parameter is set.
|
||||
: Optional `target` attribute for the URL if `link` argument is set.
|
||||
|
||||
rel
|
||||
: Optional `rel` attribute for the URL if `link` parameter is set.
|
||||
: Optional `rel` attribute for the URL if `link` argument is set.
|
||||
|
||||
alt
|
||||
: Alternate text for the image if the image cannot be displayed.
|
||||
@@ -380,7 +380,7 @@ Rendered:
|
||||
{{< vimeo 55073825 >}}
|
||||
|
||||
{{% note %}}
|
||||
If you want to further customize the visual styling, add a `class` parameter when calling the shortcode. The new `class` will be added to the `<div>` that wraps the `<iframe>` *and* will remove the inline styles. Note that you will need to call the `id` as a named parameter as well. You can also give the vimeo video a descriptive title with `title`.
|
||||
If you want to further customize the visual styling, add a `class` argument when calling the shortcode. The new `class` will be added to the `<div>` that wraps the `<iframe>` *and* will remove the inline styles. Note that you will need to call the `id` as a named argument as well. You can also give the vimeo video a descriptive title with `title`.
|
||||
|
||||
```go
|
||||
{{</* vimeo id="146022717" class="my-vimeo-wrapper-class" title="My vimeo video" */>}}
|
||||
@@ -411,7 +411,7 @@ Rendered:
|
||||
|
||||
{{< youtube 0RKpf3rK57I >}}
|
||||
|
||||
The youtube shortcode accepts these named parameters:
|
||||
The youtube shortcode accepts these named arguments:
|
||||
|
||||
id
|
||||
: (`string`) The video `id`. Optional if the `id` is provided as a positional argument as shown in the example above.
|
||||
|
||||
@@ -32,7 +32,7 @@ Run `hugo gen chromastyles -h` for more options. See https://xyproto.github.io/s
|
||||
|
||||
## Highlight shortcode
|
||||
|
||||
Highlighting is carried out via the built-in [`highlight` shortcode](/content-management/shortcodes/#highlight). It takes exactly one required parameter for the programming language to be highlighted and requires a closing shortcode.
|
||||
Highlighting is carried out via the built-in [`highlight` shortcode](/content-management/shortcodes/#highlight). It takes exactly one required argument for the programming language to be highlighted and requires a closing tag.
|
||||
|
||||
Options:
|
||||
|
||||
|
||||
@@ -171,7 +171,7 @@ wikipedia: "https://en.wikipedia.org/wiki/Bruce_Willis"
|
||||
[content type]: /content-management/types/
|
||||
[documentation on archetypes]: /content-management/archetypes/
|
||||
[front matter]: /content-management/front-matter/
|
||||
[taxonomy list templates]: /templates/taxonomy-templates/#taxonomy-list-templates
|
||||
[taxonomy list templates]: /templates/taxonomy-templates/#taxonomy-templates
|
||||
[taxonomy templates]: /templates/taxonomy-templates/
|
||||
[terms within the taxonomy]: /templates/taxonomy-templates/#taxonomy-terms-templates
|
||||
[terms within the taxonomy]: /templates/taxonomy-templates/#term-templates
|
||||
[site configuration]: /getting-started/configuration/
|
||||
|
||||
@@ -12,7 +12,7 @@ action:
|
||||
aliases: [/functions/keyvals]
|
||||
---
|
||||
|
||||
The primary application for this function is the definition of the `namedSlices` parameter in the options map passed to the [`Related`] method on the `Pages` object.
|
||||
The primary application for this function is the definition of the `namedSlices` value in the options map passed to the [`Related`] method on the `Pages` object.
|
||||
|
||||
[`Related`]: /methods/pages/related/
|
||||
|
||||
|
||||
@@ -19,7 +19,7 @@ aliases: [/functions/errorf]
|
||||
The `errorf` function evaluates the format string, then prints the result to the ERROR log and fails the build.
|
||||
|
||||
```go-html-template
|
||||
{{ errorf "The %q shortcode requires a src parameter. See %s" .Name .Position }}
|
||||
{{ errorf "The %q shortcode requires a src argument. See %s" .Name .Position }}
|
||||
```
|
||||
|
||||
Use the [`erroridf`] function to allow optional suppression of specific errors.
|
||||
|
||||
@@ -13,11 +13,11 @@ action:
|
||||
toc: true
|
||||
---
|
||||
|
||||
The sigma parameter is used in a gaussian function and affects the radius of effect. Sigma must be positive. The sharpen radius is approximately 3 times the sigma value.
|
||||
The sigma argument is used in a gaussian function and affects the radius of effect. Sigma must be positive. The sharpen radius is approximately 3 times the sigma value.
|
||||
|
||||
The amount parameter controls how much darker and how much lighter the edge borders become. Typically between 0.5 and 1.5.
|
||||
The amount argument controls how much darker and how much lighter the edge borders become. Typically between 0.5 and 1.5.
|
||||
|
||||
The threshold parameter controls the minimum brightness change that will be sharpened. Typically between 0 and 0.05.
|
||||
The threshold argument controls the minimum brightness change that will be sharpened. Typically between 0 and 0.05.
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Get
|
||||
description: Returns the value of the given parameter.
|
||||
description: Returns the value of the given argument.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
@@ -12,40 +12,40 @@ action:
|
||||
toc: true
|
||||
---
|
||||
|
||||
Specify the parameter by position or by name. When calling a shortcode within Markdown, use either positional or named parameters, but not both.
|
||||
Specify the argument by position or by name. When calling a shortcode within Markdown, use either positional or named argument, but not both.
|
||||
|
||||
{{% note %}}
|
||||
Some shortcodes support positional parameters, some support named parameters, and others support both. Refer to the shortcode's documentation for usage details.
|
||||
Some shortcodes support positional arguments, some support named arguments, and others support both. Refer to the shortcode's documentation for usage details.
|
||||
{{% /note %}}
|
||||
|
||||
## Positional parameters
|
||||
## Positional arguments
|
||||
|
||||
This shortcode call uses positional parameters:
|
||||
This shortcode call uses positional arguments:
|
||||
|
||||
{{< code file=content/about.md lang=md >}}
|
||||
{{</* myshortcode "Hello" "world" */>}}
|
||||
{{< /code >}}
|
||||
|
||||
To retrieve parameters by position:
|
||||
To retrieve arguments by position:
|
||||
|
||||
{{< code file=layouts/shortcodes/myshortcode.html >}}
|
||||
{{ printf "%s %s." (.Get 0) (.Get 1) }} → Hello world.
|
||||
{{< /code >}}
|
||||
|
||||
## Named parameters
|
||||
## Named arguments
|
||||
|
||||
This shortcode call uses named parameters:
|
||||
This shortcode call uses named arguments:
|
||||
|
||||
{{< code file=content/about.md lang=md >}}
|
||||
{{</* myshortcode greeting="Hello" firstName="world" */>}}
|
||||
{{< /code >}}
|
||||
|
||||
To retrieve parameters by name:
|
||||
To retrieve arguments by name:
|
||||
|
||||
{{< code file=layouts/shortcodes/myshortcode.html >}}
|
||||
{{ printf "%s %s." (.Get "greeting") (.Get "firstName") }} → Hello world.
|
||||
{{< /code >}}
|
||||
|
||||
{{% note %}}
|
||||
Parameter names are case-sensitive.
|
||||
Argument names are case-sensitive.
|
||||
{{% /note %}}
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: IsNamedParams
|
||||
description: Reports whether the shortcode call uses named parameters.
|
||||
description: Reports whether the shortcode call uses named arguments.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
@@ -10,7 +10,7 @@ action:
|
||||
signatures: [SHORTCODE.IsNamedParams]
|
||||
---
|
||||
|
||||
To support both positional and named parameters when calling a shortcode, use the `IsNamedParams` method to determine how the shortcode was called.
|
||||
To support both positional and named arguments when calling a shortcode, use the `IsNamedParams` method to determine how the shortcode was called.
|
||||
|
||||
With this shortcode template:
|
||||
|
||||
|
||||
@@ -11,19 +11,19 @@ action:
|
||||
signatures: [SHORTCODE.Name]
|
||||
---
|
||||
|
||||
The `Name` method is useful for error reporting. For example, if your shortcode requires a "greeting" parameter:
|
||||
The `Name` method is useful for error reporting. For example, if your shortcode requires a "greeting" argument:
|
||||
|
||||
{{< code file=layouts/shortcodes/myshortcode.html >}}
|
||||
{{ $greeting := "" }}
|
||||
{{ with .Get "greeting" }}
|
||||
{{ $greeting = . }}
|
||||
{{ else }}
|
||||
{{ errorf "The %q shortcode requires a 'greeting' parameter. See %s" .Name .Position }}
|
||||
{{ errorf "The %q shortcode requires a 'greeting' argument. See %s" .Name .Position }}
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
In the absence of a "greeting" parameter, Hugo will throw an error message and fail the build:
|
||||
In the absence of a "greeting" argument, Hugo will throw an error message and fail the build:
|
||||
|
||||
```text
|
||||
ERROR The "myshortcode" shortcode requires a 'greeting' parameter. See "/home/user/project/content/about.md:11:1"
|
||||
ERROR The "myshortcode" shortcode requires a 'greeting' argument. See "/home/user/project/content/about.md:11:1"
|
||||
```
|
||||
|
||||
@@ -32,7 +32,7 @@ This shortcode performs error checking, then renders an HTML `img` element with
|
||||
{{ errorf "The %q shortcode was unable to find %s. See %s" $.Name $src $.Position }}
|
||||
{{ end }}
|
||||
{{ else }}
|
||||
{{ errorf "The %q shortcode requires a 'src' parameter. See %s" .Name .Position }}
|
||||
{{ errorf "The %q shortcode requires a 'src' argument. See %s" .Name .Position }}
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Params
|
||||
description: Returns a collection of the shortcode parameters.
|
||||
description: Returns a collection of the shortcode arguments.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
@@ -10,7 +10,7 @@ action:
|
||||
signatures: [SHORTCODE.Params]
|
||||
---
|
||||
|
||||
When you call a shortcode using positional parameters, the `Params` method returns a slice.
|
||||
When you call a shortcode using positional arguments, the `Params` method returns a slice.
|
||||
|
||||
{{< code file=content/about.md lang=md >}}
|
||||
{{</* myshortcode "Hello" "world" */>}}
|
||||
@@ -21,7 +21,7 @@ When you call a shortcode using positional parameters, the `Params` method retur
|
||||
{{ index .Params 1 }} → world
|
||||
{{< /code >}}
|
||||
|
||||
When you call a shortcode using named parameters, the `Params` method returns a map.
|
||||
When you call a shortcode using named arguments, the `Params` method returns a map.
|
||||
|
||||
{{< code file=content/about.md lang=md >}}
|
||||
{{</* myshortcode greeting="Hello" name="world" */>}}
|
||||
|
||||
@@ -9,7 +9,7 @@ action:
|
||||
signatures: [SHORTCODE.Parent]
|
||||
---
|
||||
|
||||
This is useful for inheritance of common shortcode parameters from the root.
|
||||
This is useful for inheritance of common shortcode arguments from the root.
|
||||
|
||||
In this contrived example, the "greeting" shortcode is the parent, and the "now" shortcode is child.
|
||||
|
||||
@@ -45,6 +45,6 @@ Welcome. Today is {{</* now */>}}.
|
||||
|
||||
The "now" shortcode formats the current time using:
|
||||
|
||||
1. The `dateFormat` parameter passed to the "now" shortcode, if present
|
||||
2. The `dateFormat` parameter passed to the "greeting" shortcode, if present
|
||||
1. The `dateFormat` argument passed to the "now" shortcode, if present
|
||||
2. The `dateFormat` argument passed to the "greeting" shortcode, if present
|
||||
3. The default layout string defined at the top of the shortcode
|
||||
|
||||
@@ -11,21 +11,21 @@ action:
|
||||
signatures: [SHORTCODE.Position]
|
||||
---
|
||||
|
||||
The `Position` method is useful for error reporting. For example, if your shortcode requires a "greeting" parameter:
|
||||
The `Position` method is useful for error reporting. For example, if your shortcode requires a "greeting" argument:
|
||||
|
||||
{{< code file=layouts/shortcodes/myshortcode.html >}}
|
||||
{{ $greeting := "" }}
|
||||
{{ with .Get "greeting" }}
|
||||
{{ $greeting = . }}
|
||||
{{ else }}
|
||||
{{ errorf "The %q shortcode requires a 'greeting' parameter. See %s" .Name .Position }}
|
||||
{{ errorf "The %q shortcode requires a 'greeting' argument. See %s" .Name .Position }}
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
In the absence of a "greeting" parameter, Hugo will throw an error message and fail the build:
|
||||
In the absence of a "greeting" argument, Hugo will throw an error message and fail the build:
|
||||
|
||||
```text
|
||||
ERROR The "myshortcode" shortcode requires a 'greeting' parameter. See "/home/user/project/content/about.md:11:1"
|
||||
ERROR The "myshortcode" shortcode requires a 'greeting' argument. See "/home/user/project/content/about.md:11:1"
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
|
||||
@@ -223,7 +223,7 @@ To include the embedded template:
|
||||
|
||||
### Configure X (Twitter) Cards
|
||||
|
||||
Hugo's X (Twitter) Card template is configured using a mix of configuration variables and [front-matter](/content-management/front-matter/) on individual pages.
|
||||
Hugo's X (Twitter) Card template is configured using a mix of configuration settings and [front-matter](/content-management/front-matter/) values on individual pages.
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[params]
|
||||
|
||||
@@ -12,11 +12,8 @@ toc: true
|
||||
aliases: [/layout/homepage/,/templates/homepage-template/]
|
||||
---
|
||||
|
||||
Homepage is a `Page` and therefore has all the [page variables][pagevars] and [site variables][sitevars] available for use.
|
||||
|
||||
{{% note %}}
|
||||
The homepage template is the *only* required template for building a site and therefore useful when bootstrapping a new site and template. It is also the only required template if you are developing a single-page website.
|
||||
{{% /note %}}
|
||||
|
||||
|
||||
{{< youtube ut1xtRZ1QOA >}}
|
||||
|
||||
@@ -32,8 +29,6 @@ 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].
|
||||
|
||||
{{< code file=layouts/index.html >}}
|
||||
{{ define "main" }}
|
||||
<main aria-role="main">
|
||||
@@ -56,10 +51,6 @@ The following is an example of a homepage template that uses [partial][partials]
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
[base]: /templates/base/
|
||||
[contentorg]: /content-management/organization/
|
||||
[lists]: /templates/lists/
|
||||
[lookup]: /templates/lookup-order/
|
||||
[pagevars]: /methods/page/
|
||||
[partials]: /templates/partials/
|
||||
[sitevars]: /methods/site/
|
||||
|
||||
@@ -34,25 +34,9 @@ The idea of a list page comes from the [hierarchical mental model of the web][me
|
||||
|
||||
[](site-hierarchy.svg)
|
||||
|
||||
## List defaults
|
||||
|
||||
### Default templates
|
||||
|
||||
Since section lists and taxonomy lists (N.B., *not* [taxonomy terms lists][taxterms]) are both *lists* with regards to their templates, both have the same terminating default of `_default/list.html` or `themes/<THEME>/layouts/_default/list.html` in their lookup order. In addition, both [section lists][sectiontemps] and [taxonomy lists][taxlists] have their own default list templates in `_default`.
|
||||
|
||||
See [Template Lookup Order](/templates/lookup-order/) for the complete reference.
|
||||
|
||||
## Add content and front matter to list pages
|
||||
|
||||
Since v0.18, [everything in Hugo is a `Page`][bepsays]. This means list pages and the homepage can have associated content files (i.e. `_index.md`) that contain page metadata (i.e., front matter) and content.
|
||||
|
||||
This new model allows you to include list-specific front matter via `.Params` and also means that list templates (e.g., `layouts/_default/list.html`) have access to all [page variables][pagevars].
|
||||
|
||||
{{% note %}}
|
||||
It is important to note that all `_index.md` content files will render according to a *list* template and not according to a [single page template](/templates/single-page-templates/).
|
||||
{{% /note %}}
|
||||
|
||||
### Example project directory
|
||||
Add content and front matter to list pages by creating an _index.md file for `home`, `section`, `taxonomy`, and `term` pages.
|
||||
|
||||
The following is an example of a typical Hugo project directory's content:
|
||||
|
||||
@@ -241,15 +225,13 @@ See the documentation on [`where`] and
|
||||
[getpage]: /methods/page/getpage/
|
||||
[homepage]: /templates/homepage/
|
||||
[mentalmodel]: https://webstyleguide.com/wsg3/3-information-architecture/3-site-structure.html
|
||||
[pagevars]: /methods/page/
|
||||
[partials]: /templates/partials/
|
||||
[RSS 2.0]: https://cyber.harvard.edu/rss/rss.html
|
||||
[rss]: /templates/rss/
|
||||
[sections]: /content-management/sections/
|
||||
[sectiontemps]: /templates/section-templates/
|
||||
[sitevars]: /methods/site/
|
||||
[taxlists]: /templates/taxonomy-templates/#taxonomy-list-templates
|
||||
[taxterms]: /templates/taxonomy-templates/#taxonomy-terms-templates
|
||||
[taxlists]: /templates/taxonomy-templates/#taxonomy-templates
|
||||
[taxterms]: /templates/taxonomy-templates/#term-templates
|
||||
[taxvars]: /methods/taxonomy/
|
||||
[views]: /templates/views/
|
||||
[`where`]: /functions/collections/where/
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Section page templates
|
||||
linkTitle: Section templates
|
||||
description: Templates used for section pages are **lists** and therefore have all the variables and methods available to list pages.
|
||||
description: Use section templates to list members of a section.
|
||||
categories: [templates]
|
||||
keywords: [lists,sections,templates]
|
||||
menu:
|
||||
|
||||
@@ -27,7 +27,7 @@ Hugo's embedded 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 /*/%}}`.
|
||||
To create a shortcode, place an HTML template in the `layouts/shortcodes` directory. 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 /*/%}}`.
|
||||
|
||||
You can organize your shortcodes in subdirectories, e.g. in `layouts/shortcodes/boxes`. These shortcodes would then be accessible with their relative path, e.g:
|
||||
|
||||
@@ -44,31 +44,31 @@ Shortcode templates have a simple [lookup order]:
|
||||
1. `/layouts/shortcodes/<SHORTCODE>.html`
|
||||
2. `/themes/<THEME>/layouts/shortcodes/<SHORTCODE>.html`
|
||||
|
||||
### Positional vs. named parameters
|
||||
### Positional vs. named arguments
|
||||
|
||||
You can create shortcodes using the following types of parameters:
|
||||
You can create shortcodes using the following types of arguments:
|
||||
|
||||
* Positional parameters
|
||||
* Named parameters
|
||||
* Positional *or* named parameters (i.e, "flexible")
|
||||
* Positional arguments
|
||||
* Named arguments
|
||||
* Positional *or* named arguments
|
||||
|
||||
In shortcodes with positional parameters, the order of the parameters is important. If a shortcode has a single required value (e.g., the `youtube` shortcode below), positional parameters work very well and require less typing from content authors.
|
||||
In shortcodes with positional arguments, the order of the arguments is important. If a shortcode has a single required value, positional arguments require less typing from content authors.
|
||||
|
||||
For more complex layouts with multiple or optional parameters, named parameters work best. While less terse, named parameters require less memorization from a content author and can be added in a shortcode declaration in any order.
|
||||
For more complex layouts with multiple or optional arguments, named arguments work best. While less terse, named arguments require less memorization from a content author and can be added in a shortcode declaration in any order.
|
||||
|
||||
Allowing both types of parameters (i.e., a "flexible" shortcode) is useful for complex layouts where you want to set default values that can be easily overridden by users.
|
||||
Allowing both types of arguments is useful for complex layouts where you want to set default values that can be easily overridden by users.
|
||||
|
||||
### Access parameters
|
||||
### Access arguments
|
||||
|
||||
All shortcode parameters can be accessed via the `.Get` method. Whether you pass a key (i.e., string) or a number to the `.Get` method depends on whether you are accessing a named or positional parameter, respectively.
|
||||
All shortcode arguments can be accessed via the `.Get` method. Whether you pass a string or a number to the `.Get` method depends on whether you are accessing a named or positional argument, respectively.
|
||||
|
||||
To access a parameter by name, use the `.Get` method followed by the named parameter as a quoted string:
|
||||
To access an argument by name, use the `.Get` method followed by the named argument as a quoted string:
|
||||
|
||||
```go-html-template
|
||||
{{ .Get "class" }}
|
||||
```
|
||||
|
||||
To access a parameter by position, use the `.Get` followed by a numeric position, keeping in mind that positional parameters are zero-indexed:
|
||||
To access an argument by position, use the `.Get` followed by a numeric position, keeping in mind that positional arguments are zero-indexed:
|
||||
|
||||
```go-html-template
|
||||
{{ .Get 0 }}
|
||||
@@ -80,13 +80,13 @@ For the second position, you would just use:
|
||||
{{ .Get 1 }}
|
||||
```
|
||||
|
||||
`with` is great when the output depends on a parameter being set:
|
||||
`with` is great when the output depends on a argument being set:
|
||||
|
||||
```go-html-template
|
||||
{{ with .Get "class" }} class="{{ . }}"{{ end }}
|
||||
```
|
||||
|
||||
`.Get` can also be used to check if a parameter has been provided. This is
|
||||
`.Get` can also be used to check if a argument has been provided. This is
|
||||
most helpful when the condition depends on either of the values, or both:
|
||||
|
||||
```go-html-template
|
||||
@@ -95,7 +95,7 @@ most helpful when the condition depends on either of the values, or both:
|
||||
|
||||
#### `.Inner`
|
||||
|
||||
If a closing shortcode is used, the `.Inner` variable will be populated with the content between the opening and closing shortcodes. To check if `.Inner` contains anything other than whitespace:
|
||||
The `.Inner` method returns the content between the opening and closing shortcode tags. To check if `.Inner` returns anything other than whitespace:
|
||||
|
||||
```go-html-template
|
||||
{{ if strings.ContainsNonSpace .Inner }}
|
||||
@@ -103,35 +103,33 @@ If a closing shortcode is used, the `.Inner` variable will be populated with the
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
A shortcode with content declared via the `.Inner` variable can also be declared without the content and without the closing tag by using the self-closing syntax:
|
||||
{{% note %}}
|
||||
Any shortcode that calls the `.Inner` method must be closed or self-closed. To call a shortcode using the self-closing sytax
|
||||
|
||||
```go-html-template
|
||||
{{</* innershortcode /*/>}}
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
Any shortcode that refers to `.Inner` must be closed or self-closed.
|
||||
|
||||
{{% /note %}}
|
||||
|
||||
#### `.Params`
|
||||
|
||||
The `.Params` variable in shortcodes contains the list parameters passed to shortcode for more complicated use cases. You can also access higher-scoped parameters with the following logic:
|
||||
The `.Params` method in shortcodes returns the arguments passed to the shortcode for more complicated use cases. You can also access higher-scoped arguments with the following logic:
|
||||
|
||||
$.Params
|
||||
: these are the parameters passed directly into the shortcode declaration (e.g., a YouTube video ID)
|
||||
: these are the arguments passed directly into the shortcode declaration (e.g., a YouTube video ID)
|
||||
|
||||
$.Page.Params
|
||||
: refers to the page's parameters; the "page" in this case refers to the content file in which the shortcode is declared (e.g., a `shortcode_color` field in a content's front matter could be accessed via `$.Page.Params.shortcode_color`).
|
||||
|
||||
$.Page.Site.Params
|
||||
$.Site.Params
|
||||
: refers to parameters defined in your site configuration.
|
||||
|
||||
#### `.IsNamedParams`
|
||||
|
||||
The `.IsNamedParams` method checks whether the shortcode declaration uses named parameters and returns a boolean value.
|
||||
The `.IsNamedParams` method checks whether the shortcode declaration uses named arguments and returns a boolean value.
|
||||
|
||||
For example, you could create an `image` shortcode that can take either a `src` named parameter or the first positional parameter, depending on the preference of the content's author. Let's assume the `image` shortcode is called as follows:
|
||||
For example, you could create an `image` shortcode that can take either a `src` named argument or the first positional argument, depending on the preference of the content's author. Let's assume the `image` shortcode is called as follows:
|
||||
|
||||
```go-html-template
|
||||
{{</* image src="images/my-image.jpg" */>}}
|
||||
@@ -141,25 +139,23 @@ You could then include the following as part of your shortcode templating:
|
||||
|
||||
```go-html-template
|
||||
{{ if .IsNamedParams }}
|
||||
<img src="{{ .Get "src" }}" alt="">
|
||||
<img src="{{ .Get "src" }}" alt="">
|
||||
{{ else }}
|
||||
<img src="{{ .Get 0 }}" alt="">
|
||||
<img src="{{ .Get 0 }}" alt="">
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
See the [example Vimeo shortcode][vimeoexample] below for `.IsNamedParams` in action.
|
||||
|
||||
{{% note %}}
|
||||
While you can create shortcode templates that accept both positional and named parameters, you *cannot* declare shortcodes in content with a mix of parameter types. Therefore, a shortcode declared like `{{</* image src="images/my-image.jpg" "This is my alt text" */>}}` will return an error.
|
||||
While you can create shortcode templates that accept both positional and named arguments, you *cannot* declare shortcodes in content with a mix of argument types. Therefore, a shortcode declared like `{{</* image src="images/my-image.jpg" "This is my alt text" */>}}` will return an error.
|
||||
{{% /note %}}
|
||||
|
||||
You can also use the variable `.Page` to access all the normal [page variables][pagevars].
|
||||
|
||||
Shortcodes can also be nested. In a nested shortcode, you can access the parent shortcode context with the [`.Parent`] shortcode method. This can be very useful for inheritance of common shortcode parameters from the root.
|
||||
Shortcodes can also be nested. In a nested shortcode, you can access the parent shortcode context with the [`.Parent`] shortcode method. This can be very useful for inheritance from the root.
|
||||
|
||||
### Checking for existence
|
||||
|
||||
You can check if a specific shortcode is used on a page by calling `.HasShortcode` in that page template, providing the name of the shortcode. This is sometimes useful when you want to include specific scripts or styles in the header that are only used by that shortcode.
|
||||
You can check if a specific shortcode is used on a page by calling `.HasShortcode` in that page template, providing the name of the shortcode. This is useful when you want to include specific scripts or styles in the header that are only used by that shortcode.
|
||||
|
||||
## Custom shortcode examples
|
||||
|
||||
@@ -179,7 +175,7 @@ Let's assume you would like to keep mentions of your copyright year current in y
|
||||
|
||||
### Single positional example: `youtube`
|
||||
|
||||
Embedded videos are a common addition to Markdown content that can quickly become unsightly. The following is the code used by [Hugo's built-in YouTube shortcode][youtubeshortcode]:
|
||||
Embedded videos are a common addition to Markdown content. The following is the code used by [Hugo's built-in YouTube shortcode][youtubeshortcode]:
|
||||
|
||||
```go-html-template
|
||||
{{</* youtube 09jf3ow9jfw */>}}
|
||||
@@ -307,9 +303,9 @@ The rendered output of the HTML example code block will be as follows:
|
||||
|
||||
### Nested shortcode: image gallery
|
||||
|
||||
Hugo's [`.Parent`] shortcode method provides access to the parent shortcode context when the shortcode in question is called within the context of a *parent* shortcode. This provides an inheritance model for common shortcode parameters.
|
||||
Hugo's [`.Parent`] shortcode method provides access to the parent shortcode context when the shortcode in question is called within the context of a parent shortcode. This provides an inheritance model.
|
||||
|
||||
The following example is contrived but demonstrates the concept. Assume you have a `gallery` shortcode that expects one named `class` parameter:
|
||||
The following example is contrived but demonstrates the concept. Assume you have a `gallery` shortcode that expects one named `class` argument:
|
||||
|
||||
{{< code file=layouts/shortcodes/gallery.html >}}
|
||||
<div class="{{ .Get "class" }}">
|
||||
@@ -317,7 +313,7 @@ The following example is contrived but demonstrates the concept. Assume you have
|
||||
</div>
|
||||
{{< /code >}}
|
||||
|
||||
You also have an `img` shortcode with a single named `src` parameter that you want to call inside of `gallery` and other shortcodes, so that the parent defines the context of each `img`:
|
||||
You also have an `img` shortcode with a single named `src` argument that you want to call inside of `gallery` and other shortcodes, so that the parent defines the context of each `img`:
|
||||
|
||||
{{< code file=layouts/shortcodes/img.html >}}
|
||||
{{- $src := .Get "src" -}}
|
||||
@@ -356,14 +352,14 @@ Use the [`errorf`] template function with the [`Name`] and [`Position`] shortcod
|
||||
{{ with .Get "name" }}
|
||||
<p>Hello, my name is {{ . }}.</p>
|
||||
{{ else }}
|
||||
{{ errorf "The %q shortcode requires a 'name' parameter. See %s" .Name .Position }}
|
||||
{{ errorf "The %q shortcode requires a 'name' argument. See %s" .Name .Position }}
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
When the above fails, you will see an `ERROR` message such as:
|
||||
|
||||
```sh
|
||||
ERROR The "greeting" shortcode requires a 'name' parameter. See "/home/user/project/content/_index.md:12:1"
|
||||
ERROR The "greeting" shortcode requires a 'name' argument. See "/home/user/project/content/_index.md:12:1"
|
||||
```
|
||||
|
||||
## Inline shortcodes
|
||||
@@ -387,11 +383,11 @@ And once enabled, you can do this in your content files:
|
||||
|
||||
The above will print the current date and time.
|
||||
|
||||
Note that an inline shortcode's inner content is parsed and executed as a Go text template with the same context as a regular shortcode template.
|
||||
Note that an inline shortcode's inner content is parsed and executed as a Go text template with the same context as a regular shortcode template.
|
||||
|
||||
This means that the current page can be accessed via `.Page.Title` etc. This also means that there are no concept of "nested inline shortcodes".
|
||||
|
||||
The same inline shortcode can be reused later in the same content file, with different parameters if needed, using the self-closing syntax:
|
||||
The same inline shortcode can be reused later in the same content file, with different arguments if needed, using the self-closing syntax:
|
||||
|
||||
```go-html-template
|
||||
{{</* time.inline /*/>}}
|
||||
@@ -404,7 +400,6 @@ The same inline shortcode can be reused later in the same content file, with dif
|
||||
[built-in shortcode]: /content-management/shortcodes/
|
||||
[figure]: /content-management/shortcodes/#figure
|
||||
[lookup order]: /templates/lookup-order/
|
||||
[pagevars]: /methods/page/
|
||||
[source organization]: /getting-started/directory-structure/
|
||||
[vimeoexample]: #single-flexible-example-vimeo
|
||||
[youtubeshortcode]: /content-management/shortcodes/#youtube
|
||||
|
||||
@@ -18,12 +18,6 @@ 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.
|
||||
|
||||
### `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.
|
||||
|
||||
{{< code file=layouts/posts/single.html >}}
|
||||
{{ define "main" }}
|
||||
<section id="main">
|
||||
@@ -77,9 +71,7 @@ To easily generate new instances of a content type (e.g., new `.md` files in a s
|
||||
[`.format` function]: /methods/time/format/
|
||||
[front matter]: /content-management/front-matter/
|
||||
[pagetaxonomy]: /templates/taxonomy-templates/#list-terms-assigned-to-a-page
|
||||
[pagevars]: /methods/page/
|
||||
[partials]: /templates/partials/
|
||||
[section]: /content-management/sections/
|
||||
[site variables]: /methods/site/
|
||||
[spf13]: https://spf13.com/
|
||||
[`with`]: /functions/go-template/with/
|
||||
|
||||
@@ -16,21 +16,21 @@ Hugo includes support for user-defined groupings of content called **taxonomies*
|
||||
|
||||
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)
|
||||
* Order the way content associated with a taxonomy term is displayed in a [taxonomy template](#taxonomy-templates)
|
||||
* Order the way the terms for a taxonomy are displayed in a [term template](#term-templates)
|
||||
* List a single content's taxonomy terms within a [single page template]
|
||||
|
||||
## Taxonomy list templates
|
||||
## Taxonomy templates
|
||||
|
||||
Taxonomy list page templates are lists and therefore have all the methods available to [list pages][lists].
|
||||
|
||||
### Taxonomy list template lookup order
|
||||
### Taxonomy template lookup order
|
||||
|
||||
See [Template Lookup](/templates/lookup-order/).
|
||||
|
||||
## Taxonomy terms templates
|
||||
## Term templates
|
||||
|
||||
### Taxonomy terms templates lookup order
|
||||
### Term template lookup order
|
||||
|
||||
See [Template Lookup](/templates/lookup-order/).
|
||||
|
||||
@@ -201,9 +201,9 @@ To render a comma-delimited list:
|
||||
|
||||
## List content with the same taxonomy term
|
||||
|
||||
If you are using a taxonomy for something like a series of posts, you can list individual pages associated with the same taxonomy. This is also a quick and dirty method for showing related content:
|
||||
If you are using a taxonomy for something like a series of posts, you can list individual pages associated with the same term. For example:
|
||||
|
||||
|
||||
### Example: showing content in same series
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
@@ -217,13 +217,11 @@ If you are using a taxonomy for something like a series of posts, you can list i
|
||||
|
||||
This would be very useful in a sidebar as “featured content”. You could even have different sections of “featured content” by assigning different terms to the content.
|
||||
|
||||
### Example: grouping "featured" content
|
||||
|
||||
```go-html-template
|
||||
<section id="menu">
|
||||
<ul>
|
||||
{{ range $key, $taxonomy := .Site.Taxonomies.featured }}
|
||||
<li>{{ $key }}</li>
|
||||
{{ range $term, $taxonomy := .Site.Taxonomies.featured }}
|
||||
<li>{{ $term }}</li>
|
||||
<ul>
|
||||
{{ range $taxonomy.Pages }}
|
||||
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
|
||||
@@ -236,14 +234,8 @@ This would be very useful in a sidebar as “featured content”. You could even
|
||||
|
||||
## Render a site's taxonomies
|
||||
|
||||
If you wish to display the list of all keys for your site's taxonomy, you can retrieve them from the [`.Site` variable][sitevars] available on every page.
|
||||
|
||||
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
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range .Site.Taxonomies.tags }}
|
||||
@@ -251,9 +243,6 @@ The following example displays all terms in a site's tags taxonomy:
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
### Example: list all taxonomies, terms, and assigned content
|
||||
|
||||
This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms.
|
||||
|
||||
{{< code file=layouts/partials/all-taxonomies.html >}}
|
||||
@@ -289,24 +278,8 @@ This example will list all taxonomies and their terms, as well as all the conten
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
## `.Site.GetPage` for taxonomies
|
||||
|
||||
Because taxonomies are lists, the [`.GetPage` function][getpage] can be used to get all the pages associated with a particular taxonomy term using a terse syntax. The following ranges over the full list of tags on your site and links to each of the individual taxonomy pages for each term without having to use the more fragile URL construction of the ["List All Site Tags" example above](#example-list-all-site-tags):
|
||||
|
||||
{{< code file=links-to-all-tags.html >}}
|
||||
{{ $taxo := "tags" }}
|
||||
<ul class="{{ $taxo }}">
|
||||
{{ with ($.Site.GetPage (printf "/%s" $taxo)) }}
|
||||
{{ range .Pages }}
|
||||
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{< /code >}}
|
||||
|
||||
[`Pages`]: /methods/page/pages/
|
||||
[getpage]: /methods/page/getpage/
|
||||
[lists]: /templates/lists/
|
||||
[renderlists]: /templates/lists/
|
||||
[single page template]: /templates/single-page-templates/
|
||||
[sitevars]: /methods/site/
|
||||
|
||||
@@ -104,7 +104,7 @@ Hugo builds pages in parallel where multiple pages are generated simultaneously.
|
||||
Some partial templates such as sidebars or menus are executed many times during a site build. Depending on the content within the partial template and the desired output, the template may benefit from caching to reduce the number of executions. The [`partialCached`] template function provides caching capabilities for partial templates.
|
||||
|
||||
{{% note %}}
|
||||
Note that you can create cached variants of each partial by passing additional parameters to `partialCached` beyond the initial context. See the `partialCached` documentation for more details.
|
||||
Note that you can create cached variants of each partial by passing additional arguments to `partialCached` beyond the initial context. See the `partialCached` documentation for more details.
|
||||
{{% /note %}}
|
||||
|
||||
## Timers
|
||||
|
||||
Reference in New Issue
Block a user