mirror of
https://github.com/gohugoio/hugo.git
synced 2025-08-21 21:35:28 +02:00
Merge commit '346b60358dd8ec2ca228e6635bff9d7914b398b7'
This commit is contained in:
Bjørn Erik Pedersen
@@ -72,557 +72,7 @@ You can call shortcodes within other shortcodes by creating your own templates t
|
||||
|
||||
## Embedded shortcodes
|
||||
|
||||
Use these embedded shortcodes as needed.
|
||||
|
||||
### comment
|
||||
|
||||
{{< new-in "0.137.1" >}}
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `comment` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
[source code]: {{% eturl comment %}}
|
||||
{{% /note %}}
|
||||
|
||||
Use the `comment` shortcode to include comments in your Markdown. Hugo excludes the encapsulated text when rendering your site.
|
||||
|
||||
Example usage:
|
||||
|
||||
```text
|
||||
{{%/* comment */%}} TODO: rewrite the paragraph below. {{%/* /comment */%}}
|
||||
```
|
||||
|
||||
Although you can call this shortcode using the `{{</* */>}}` notation, computationally it is more efficient to call it using the `{{%/* */%}}` notation as shown above.
|
||||
|
||||
### details
|
||||
|
||||
{{< new-in 0.140.0 >}}
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `details` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
[source code]: {{% eturl details %}}
|
||||
{{% /note %}}
|
||||
|
||||
Use the `details` shortcode to create a `details` HTML element. For example:
|
||||
|
||||
```text
|
||||
{{</* details summary="See the details" */>}}
|
||||
This is a **bold** word.
|
||||
{{</* /details */>}}
|
||||
```
|
||||
|
||||
Hugo renders this to:
|
||||
|
||||
```html
|
||||
<details>
|
||||
<summary>See the details</summary>
|
||||
<p>This is a <strong>bold</strong> word.</p>
|
||||
</details>
|
||||
```
|
||||
|
||||
The `details` shortcode accepts these named arguments:
|
||||
|
||||
summary
|
||||
: (`string`) The content of the child `summary` element rendered from Markdown to HTML. Default is `Details`.
|
||||
|
||||
open
|
||||
: (`bool`) Whether to initially display the content of the `details` element. Default is `false`.
|
||||
|
||||
class
|
||||
: (`string`) The value of the element's `class` attribute.
|
||||
|
||||
name
|
||||
: (`string`) The value of the element's `name` attribute.
|
||||
|
||||
title
|
||||
: (`string`) The value of the element's `title` attribute.
|
||||
|
||||
### figure
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `figure` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
[source code]: {{% eturl figure %}}
|
||||
{{% /note %}}
|
||||
|
||||
The `figure` shortcode can use the following named arguments:
|
||||
|
||||
src
|
||||
: URL of the image to be displayed.
|
||||
|
||||
link
|
||||
: If the image needs to be hyperlinked, URL of the destination.
|
||||
|
||||
target
|
||||
: Optional `target` attribute for the URL if `link` argument is set.
|
||||
|
||||
rel
|
||||
: Optional `rel` attribute for the URL if `link` argument is set.
|
||||
|
||||
alt
|
||||
: Alternate text for the image if the image cannot be displayed.
|
||||
|
||||
title
|
||||
: Image title.
|
||||
|
||||
caption
|
||||
: Image caption. Markdown within the value of `caption` will be rendered.
|
||||
|
||||
class
|
||||
: `class` attribute of the HTML `figure` tag.
|
||||
|
||||
height
|
||||
: `height` attribute of the image.
|
||||
|
||||
width
|
||||
: `width` attribute of the image.
|
||||
|
||||
loading
|
||||
: `loading` attribute of the image.
|
||||
|
||||
attr
|
||||
: Image attribution text. Markdown within the value of `attr` will be rendered.
|
||||
|
||||
attrlink
|
||||
: If the attribution text needs to be hyperlinked, URL of the destination.
|
||||
|
||||
Example usage:
|
||||
|
||||
```text
|
||||
{{</* figure src="elephant.jpg" title="An elephant at sunset" */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
```html
|
||||
<figure>
|
||||
<img src="elephant.jpg">
|
||||
<figcaption><h4>An elephant at sunset</h4></figcaption>
|
||||
</figure>
|
||||
```
|
||||
|
||||
### gist
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `gist` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
[source code]: {{% eturl gist %}}
|
||||
{{% /note %}}
|
||||
|
||||
To display a GitHub [gist] with this URL:
|
||||
|
||||
[gist]: https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists
|
||||
|
||||
```text
|
||||
https://gist.github.com/user/50a7482715eac222e230d1e64dd9a89b
|
||||
```
|
||||
|
||||
Include this in your Markdown:
|
||||
|
||||
```text
|
||||
{{</* gist user 50a7482715eac222e230d1e64dd9a89b */>}}
|
||||
```
|
||||
|
||||
This will display all files in the gist alphabetically by file name.
|
||||
|
||||
{{< gist jmooring 23932424365401ffa5e9d9810102a477 >}}
|
||||
|
||||
To display a specific file within the gist:
|
||||
|
||||
```text
|
||||
{{</* gist user 23932424365401ffa5e9d9810102a477 list.html */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< gist jmooring 23932424365401ffa5e9d9810102a477 list.html >}}
|
||||
|
||||
### highlight
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `highlight` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
[source code]: {{% eturl highlight %}}
|
||||
{{% /note %}}
|
||||
|
||||
To display a highlighted code sample:
|
||||
|
||||
```text
|
||||
{{</* highlight go-html-template */>}}
|
||||
{{ range .Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
{{</* /highlight */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< highlight go-html-template >}}
|
||||
{{ range .Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
{{< /highlight >}}
|
||||
|
||||
To specify one or more [highlighting options], include a quotation-encapsulated, comma-separated list:
|
||||
|
||||
[highlighting options]: /functions/transform/highlight/
|
||||
|
||||
```text
|
||||
{{</* highlight go-html-template "lineNos=inline, lineNoStart=42" */>}}
|
||||
{{ range .Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
{{</* /highlight */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< highlight go-html-template "lineNos=inline, lineNoStart=42" >}}
|
||||
{{ range .Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
{{< /highlight >}}
|
||||
|
||||
### instagram
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `instagram` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
[source code]: {{% eturl instagram %}}
|
||||
{{% /note %}}
|
||||
|
||||
To display an Instagram post with this URL:
|
||||
|
||||
```text
|
||||
https://www.instagram.com/p/CxOWiQNP2MO/
|
||||
```
|
||||
|
||||
Include this in your Markdown:
|
||||
|
||||
```text
|
||||
{{</* instagram CxOWiQNP2MO */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< instagram CxOWiQNP2MO >}}
|
||||
|
||||
### param
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `param` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
[source code]: {{% eturl param %}}
|
||||
{{% /note %}}
|
||||
|
||||
The `param` shortcode renders a parameter from the page's front matter, falling back to a site parameter of the same name. The shortcode throws an error if the parameter does not exist.
|
||||
|
||||
Example usage:
|
||||
|
||||
```text
|
||||
{{</* param testparam */>}}
|
||||
```
|
||||
|
||||
Access nested values by [chaining] the [identifiers]:
|
||||
|
||||
[chaining]: /getting-started/glossary/#chain
|
||||
[identifiers]: /getting-started/glossary/#identifier
|
||||
|
||||
```text
|
||||
{{</* param my.nested.param */>}}
|
||||
```
|
||||
|
||||
### qr
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `qr` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
[source code]: {{% eturl qr %}}
|
||||
{{% /note %}}
|
||||
|
||||
The `qr` shortcode encodes the given text into a [QR code] using the specified options and renders the resulting image.
|
||||
|
||||
[QR code]: https://en.wikipedia.org/wiki/QR_code
|
||||
|
||||
Use the self-closing syntax to pass the text as an argument:
|
||||
|
||||
```text
|
||||
{{</* qr text="https://gohugo.io" /*/>}}
|
||||
```
|
||||
|
||||
Or insert the text between the opening and closing tags:
|
||||
|
||||
```text
|
||||
{{</* qr */>}}
|
||||
https://gohugo.io
|
||||
{{</* /qr */>}}
|
||||
```
|
||||
|
||||
Both of the above produce this image:
|
||||
|
||||
{{< qr text="https://gohugo.io" class="qrcode" />}}
|
||||
|
||||
To create a QR code for a phone number:
|
||||
|
||||
```text
|
||||
{{</* qr text="tel:+12065550101" /*/>}}
|
||||
```
|
||||
|
||||
{{< qr text="tel:+12065550101" class="qrcode" />}}
|
||||
|
||||
To create a QR code containing contact information in the [vCard] format:
|
||||
|
||||
[vCard]: https://en.wikipedia.org/wiki/VCard
|
||||
|
||||
```text
|
||||
{{</* qr level="low" scale=2 alt="QR code of vCard for John Smith" */>}}
|
||||
BEGIN:VCARD
|
||||
VERSION:2.1
|
||||
N;CHARSET=UTF-8:Smith;John;R.;Dr.;PhD
|
||||
FN;CHARSET=UTF-8:Dr. John R. Smith, PhD.
|
||||
ORG;CHARSET=UTF-8:ABC Widgets
|
||||
TITLE;CHARSET=UTF-8:Vice President Engineering
|
||||
TEL;TYPE=WORK:+12065550101
|
||||
EMAIL;TYPE=WORK:jsmith@example.org
|
||||
END:VCARD
|
||||
{{</* /qr */>}}
|
||||
```
|
||||
|
||||
{{< qr level="low" scale=2 alt="QR code of vCard for John Smith" class="qrcode" >}}
|
||||
BEGIN:VCARD
|
||||
VERSION:2.1
|
||||
N;CHARSET=UTF-8:Smith;John;R.;Dr.;PhD
|
||||
FN;CHARSET=UTF-8:Dr. John R. Smith, PhD.
|
||||
ORG;CHARSET=UTF-8:ABC Widgets
|
||||
TITLE;CHARSET=UTF-8:Vice President Engineering
|
||||
TEL;TYPE=WORK:+12065550101
|
||||
EMAIL;TYPE=WORK:jsmith@example.org
|
||||
END:VCARD
|
||||
{{< /qr >}}
|
||||
|
||||
Internally this shortcode calls the `images.QR` function. Please read the [related documentation] for implementation details and guidance.
|
||||
|
||||
[related documentation]: /functions/images/qr/
|
||||
|
||||
The `qr` shortcode accepts these named arguments:
|
||||
|
||||
text
|
||||
: (`string`) The text to encode, falling back to the text between the opening and closing shortcode tags.
|
||||
|
||||
level
|
||||
: (`string`) The error correction level to use when encoding the text, one of `low`, `medium`, `quartile`, or `high`. Default is `medium`.
|
||||
|
||||
scale
|
||||
: (`int`) The number of image pixels per QR code module. Must be greater than or equal to 2. Default is `4`.
|
||||
|
||||
targetDir
|
||||
: (`string`) The subdirectory within the [`publishDir`] where Hugo will place the generated image.
|
||||
|
||||
[`publishDir`]: /getting-started/configuration/#publishdir
|
||||
|
||||
alt
|
||||
: (`string`) The `alt` attribute of the `img` element.
|
||||
|
||||
class
|
||||
: (`string`) The `class` attribute of the `img` element.
|
||||
|
||||
id
|
||||
: (`string`) The `id` attribute of the `img` element.
|
||||
|
||||
title
|
||||
: (`string`) The `title` attribute of the `img` element.
|
||||
|
||||
### ref
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `ref` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
Always use the `{{%/* */%}}` notation when calling this shortcode.
|
||||
|
||||
[source code]: {{% eturl ref %}}
|
||||
{{% /note %}}
|
||||
|
||||
The `ref` shortcode returns the permalink of the given page reference.
|
||||
|
||||
Example usage:
|
||||
|
||||
```text
|
||||
[Post 1]({{%/* ref "/posts/post-1" */%}})
|
||||
[Post 1]({{%/* ref "/posts/post-1.md" */%}})
|
||||
[Post 1]({{%/* ref "/posts/post-1#foo" */%}})
|
||||
[Post 1]({{%/* ref "/posts/post-1.md#foo" */%}})
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
```html
|
||||
<a href="http://example.org/posts/post-1/">Post 1</a>
|
||||
<a href="http://example.org/posts/post-1/">Post 1</a>
|
||||
<a href="http://example.org/posts/post-1/#foo">Post 1</a>
|
||||
<a href="http://example.org/posts/post-1/#foo">Post 1</a>
|
||||
```
|
||||
|
||||
### relref
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `relref` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
Always use the `{{%/* */%}}` notation when calling this shortcode.
|
||||
|
||||
[source code]: {{% eturl relref %}}
|
||||
{{% /note %}}
|
||||
|
||||
The `relref` shortcode returns the permalink of the given page reference.
|
||||
|
||||
Example usage:
|
||||
|
||||
```text
|
||||
[Post 1]({{%/* relref "/posts/post-1" */%}})
|
||||
[Post 1]({{%/* relref "/posts/post-1.md" */%}})
|
||||
[Post 1]({{%/* relref "/posts/post-1#foo" */%}})
|
||||
[Post 1]({{%/* relref "/posts/post-1.md#foo" */%}})
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
```html
|
||||
<a href="/posts/post-1/">Post 1</a>
|
||||
<a href="/posts/post-1/">Post 1</a>
|
||||
<a href="/posts/post-1/#foo">Post 1</a>
|
||||
<a href="/posts/post-1/#foo">Post 1</a>
|
||||
```
|
||||
|
||||
### twitter
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `twitter` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
You may call the `twitter` shortcode by using its `tweet` alias.
|
||||
|
||||
[source code]: {{% eturl twitter %}}
|
||||
{{% /note %}}
|
||||
|
||||
To display a Twitter post with this URL:
|
||||
|
||||
```txt
|
||||
https://x.com/SanDiegoZoo/status/1453110110599868418
|
||||
```
|
||||
|
||||
Include this in your Markdown:
|
||||
|
||||
```text
|
||||
{{</* twitter user="SanDiegoZoo" id="1453110110599868418" */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< twitter user="SanDiegoZoo" id="1453110110599868418" >}}
|
||||
|
||||
### vimeo
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `vimeo` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
[source code]: {{% eturl vimeo %}}
|
||||
{{% /note %}}
|
||||
|
||||
To display a Vimeo video with this URL:
|
||||
|
||||
```text
|
||||
https://vimeo.com/channels/staffpicks/55073825
|
||||
```
|
||||
|
||||
Include this in your Markdown:
|
||||
|
||||
```text
|
||||
{{</* vimeo 55073825 */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< vimeo 55073825 >}}
|
||||
|
||||
{{% note %}}
|
||||
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" */>}}
|
||||
```
|
||||
{{% /note %}}
|
||||
|
||||
### youtube
|
||||
|
||||
{{% note %}}
|
||||
To override Hugo's embedded `youtube` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
|
||||
|
||||
[source code]: {{% eturl youtube %}}
|
||||
{{% /note %}}
|
||||
|
||||
To display a YouTube video with this URL:
|
||||
|
||||
```text
|
||||
https://www.youtube.com/watch?v=0RKpf3rK57I
|
||||
```
|
||||
|
||||
Include this in your Markdown:
|
||||
|
||||
```text
|
||||
{{</* youtube 0RKpf3rK57I */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< youtube 0RKpf3rK57I >}}
|
||||
|
||||
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.
|
||||
|
||||
allowFullScreen
|
||||
{{< new-in 0.125.0 >}}
|
||||
: (`bool`) Whether the `iframe` element can activate full screen mode. Default is `true`.
|
||||
|
||||
autoplay
|
||||
{{< new-in 0.125.0 >}}
|
||||
: (`bool`) Whether to automatically play the video. Forces `mute` to `true`. Default is `false`.
|
||||
|
||||
class
|
||||
: (`string`) The `class` attribute of the wrapping `div` element. When specified, removes the `style` attributes from the `iframe` element and its wrapping `div` element.
|
||||
|
||||
controls
|
||||
{{< new-in 0.125.0 >}}
|
||||
: (`bool`) Whether to display the video controls. Default is `true`.
|
||||
|
||||
end
|
||||
{{< new-in 0.125.0 >}}
|
||||
: (`int`) The time, measured in seconds from the start of the video, when the player should stop playing the video.
|
||||
|
||||
loading
|
||||
{{< new-in 0.125.0 >}}
|
||||
: (`string`) The loading attribute of the `iframe` element, either `eager` or `lazy`. Default is `eager`.
|
||||
|
||||
loop
|
||||
{{< new-in 0.125.0 >}}
|
||||
: (`bool`) Whether to indefinitely repeat the video. Ignores the `start` and `end` arguments after the first play. Default is `false`.
|
||||
|
||||
mute
|
||||
{{< new-in 0.125.0 >}}
|
||||
: (`bool`) Whether to mute the video. Always `true` when `autoplay` is `true`. Default is `false`.
|
||||
|
||||
start
|
||||
{{< new-in 0.125.0 >}}
|
||||
: (`int`) The time, measured in seconds from the start of the video, when the player should start playing the video.
|
||||
|
||||
title
|
||||
: (`string`) The `title` attribute of the `iframe` element. Defaults to "YouTube video".
|
||||
|
||||
Example using some of the above:
|
||||
|
||||
```text
|
||||
{{</* youtube id=0RKpf3rK57I start=30 end=60 loading=lazy */>}}
|
||||
```
|
||||
See the [shortcodes](/shortcodes/) section.
|
||||
|
||||
## Privacy configuration
|
||||
|
||||
|
||||
Reference in New Issue
Block a user