mirror of
https://github.com/gohugoio/hugo.git
synced 2025-08-28 22:19:59 +02:00
Merge commit 'a024bc7d76fcc5e49e8210f9b0896db9ef21861a'
This commit is contained in:
Bjørn Erik Pedersen
@@ -1,91 +1,241 @@
|
||||
---
|
||||
title: Shortcodes
|
||||
description: Shortcodes are simple snippets inside your content files calling built-in or custom templates.
|
||||
description: Use embedded, custom, or inline shortcodes to insert elements such as videos, images, and social media embeds into your content.
|
||||
categories: [content management]
|
||||
keywords: [markdown,content,shortcodes]
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: content-management
|
||||
weight: 100
|
||||
weight: 100
|
||||
toc: true
|
||||
aliases: [/extras/shortcodes/]
|
||||
testparam: "Hugo Rocks!"
|
||||
toc: true
|
||||
---
|
||||
|
||||
## What a shortcode is
|
||||
## Introduction
|
||||
|
||||
Hugo loves Markdown because of its simple content format, but there are times when Markdown falls short. Often, content authors are forced to add raw HTML (e.g., video `<iframe>`'s) to Markdown content. We think this contradicts the beautiful simplicity of Markdown's syntax.
|
||||
{{% glossary-term shortcode %}}
|
||||
|
||||
Hugo created **shortcodes** to circumvent these limitations.
|
||||
There are three types of shortcodes: embedded, custom, and inline.
|
||||
|
||||
A shortcode is a simple snippet inside a content file that Hugo will render using a predefined template. Note that shortcodes will not work in template files. If you need the type of drop-in functionality that shortcodes provide but in a template, you most likely want a [partial template][partials] instead.
|
||||
## Embedded
|
||||
|
||||
In addition to cleaner Markdown, shortcodes can be updated any time to reflect new classes, techniques, or standards. At the point of site generation, Hugo shortcodes will easily merge in your changes. You avoid a possibly complicated search and replace operation.
|
||||
Hugo's embedded shortcodes are pre-defined templates within the application. Refer to each shortcode's documentation for specific usage instructions and available arguments.
|
||||
|
||||
## Use shortcodes
|
||||
{{< list-pages-in-section path=/shortcodes >}}
|
||||
|
||||
{{< youtube 2xkNJL4gJ9E >}}
|
||||
## Custom
|
||||
|
||||
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.
|
||||
Create custom shortcodes to simplify and standardize content creation. For example, the following shortcode template generates an audio player using a [global resource](g):
|
||||
|
||||
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"`.
|
||||
{{< code file=layouts/shortcodes/audio.html >}}
|
||||
{{ with resources.Get (.Get "src") }}
|
||||
<audio controls preload="auto" src="{{ .RelPermalink }}"></audio>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
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.
|
||||
Then call the shortcode from within markup:
|
||||
|
||||
Here are two examples of paired shortcodes:
|
||||
{{< code file=content/example.md >}}
|
||||
{{</* audio src=/audio/test.mp3 */>}}
|
||||
{{< /code >}}
|
||||
|
||||
```go-html-template
|
||||
{{%/* mdshortcode */%}}Stuff to `process` in the *center*.{{%/* /mdshortcode */%}}
|
||||
Learn more about creating shortcodes in the [shortcode templates] section.
|
||||
|
||||
[shortcode templates]: /templates/shortcode/
|
||||
|
||||
## Inline
|
||||
|
||||
An inline shortcode is a shortcode template defined within content.
|
||||
|
||||
Hugo's security model is based on the premise that template and configuration authors are trusted, but content authors are not. This model enables generation of HTML output safe against code injection.
|
||||
|
||||
To conform with this security model, creating shortcode templates within content is disabled by default. If you trust your content authors, you can enable this functionality in your site's configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[security]
|
||||
enableInlineShortcodes = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The following example demonstrates an inline shortcode, `date.inline`, that accepts a single positional argument: a date/time [layout string].
|
||||
|
||||
[layout string]: /functions/time/format/#layout-string
|
||||
|
||||
{{< code file=content/example.md >}}
|
||||
Today is
|
||||
{{</* date.inline ":date_medium" */>}}
|
||||
{{- now | time.Format (.Get 0) -}}
|
||||
{{</* /date.inline */>}}.
|
||||
|
||||
Today is {{</* date.inline ":date_full" */>}}.
|
||||
{{< /code >}}
|
||||
|
||||
In the example above, the inline shortcode is executed twice: once upon definition and again when subsequently called. Hugo renders this to:
|
||||
|
||||
```html
|
||||
<p>Today is Jan 30, 2025.</p>
|
||||
<p>Today is Thursday, January 30, 2025</p>
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{</* highlight go */>}} A bunch of code here {{</* /highlight */>}}
|
||||
Inline shortcodes process their inner content within the same context as regular shortcode templates, allowing you to use any available [shortcode method].
|
||||
|
||||
[shortcode method]: /templates/shortcode/#methods
|
||||
|
||||
{{% note %}}
|
||||
You cannot [nest](#nesting) inline shortcodes.
|
||||
{{% /note %}}
|
||||
|
||||
Learn more about creating shortcodes in the [shortcode templates] section.
|
||||
|
||||
## Calling
|
||||
|
||||
Shortcode calls involve three syntactical elements: tags, arguments, and notation.
|
||||
|
||||
### Tags
|
||||
|
||||
Some shortcodes expect content between opening and closing tags. For example, the embedded [`details`] shortcode requires an opening and closing tag:
|
||||
|
||||
```text
|
||||
{{</* details summary="See the details" */>}}
|
||||
This is a **bold** word.
|
||||
{{</* /details */>}}
|
||||
```
|
||||
|
||||
The examples above use two different delimiters, the difference being the `%` character in the first and the `<>` characters in the second.
|
||||
Some shortcodes do not accept content. For example, the embedded [`instagram`] shortcode requires a single _positional_ argument:
|
||||
|
||||
### Shortcodes with raw string arguments
|
||||
```text
|
||||
{{</* instagram CxOWiQNP2MO */>}}
|
||||
```
|
||||
|
||||
You can pass multiple lines as arguments to a shortcode by using raw string literals:
|
||||
Some shortcodes optionally accept content. For example, you can call the embedded [`qr`] shortcode with content:
|
||||
|
||||
```go-html-template
|
||||
```text
|
||||
{{</* qr */>}}
|
||||
https://gohugo.io
|
||||
{{</* /qr */>}}
|
||||
```
|
||||
|
||||
Or use the self-closing syntax with a trailing slash to pass the text as an argument:
|
||||
|
||||
```text
|
||||
{{</* qr text=https://gohugo.io /*/>}}
|
||||
```
|
||||
|
||||
[`details`]: /shortcodes/details
|
||||
[`instagram`]: /shortcodes/instagram
|
||||
[`qr`]: /shortcodes/qr
|
||||
|
||||
Refer to each shortcode's documentation for specific usage instructions and available arguments.
|
||||
|
||||
### Arguments
|
||||
|
||||
Shortcode arguments can be either _named_ or _positional_.
|
||||
|
||||
Named arguments are passed as case-sensitive key-value pairs, as seen in this example with the embedded [`figure`] shortcode. The `src` argument, for instance, is required.
|
||||
|
||||
[`figure`]: /shortcodes/figure
|
||||
|
||||
```text
|
||||
{{</* figure src=/images/kitten.jpg */>}}
|
||||
```
|
||||
|
||||
Positional arguments, on the other hand, are determined by their position. The embedded `instagram` shortcode, for example, expects the first argument to be the Instagram post ID.
|
||||
|
||||
```text
|
||||
{{</* instagram CxOWiQNP2MO */>}}
|
||||
```
|
||||
|
||||
Shortcode arguments are space delimited, and arguments with internal spaces must be quoted.
|
||||
|
||||
```text
|
||||
{{</* figure src=/images/kitten.jpg alt="A white kitten" */>}}
|
||||
```
|
||||
|
||||
Shortcodes accept [scalar](g) arguments, one of [string](g), [integer](g), [floating point](g), or [boolean](g).
|
||||
|
||||
```text
|
||||
{{</* my-shortcode name="John Smith" age=24 married=false */>}}
|
||||
```
|
||||
|
||||
You can optionally use multiple lines when providing several arguments to a shortcode for better readability:
|
||||
|
||||
```text
|
||||
{{</* figure
|
||||
src=/images/kitten.jpg
|
||||
alt="A white kitten"
|
||||
caption="This is a white kitten"
|
||||
loading=lazy
|
||||
*/>}}
|
||||
```
|
||||
|
||||
Use a [raw string literal](g) if you need to pass a multiline string:
|
||||
|
||||
```text
|
||||
{{</* myshortcode `This is some <b>HTML</b>,
|
||||
and a new line with a "quoted string".` */>}}
|
||||
```
|
||||
|
||||
### Shortcodes with Markdown
|
||||
Shortcodes can accept named arguments, positional arguments, or both, but you must use either named or positional arguments exclusively within a single shortcode call; mixing them is not allowed.
|
||||
|
||||
Shortcodes using the `%` as the outer-most delimiter will be fully rendered when sent to the content renderer. This means that the rendered output from a shortcode can be part of the page's table of contents, footnotes, etc.
|
||||
Refer to each shortcode's documentation for specific usage instructions and available arguments.
|
||||
|
||||
### Shortcodes without Markdown
|
||||
### Notation
|
||||
|
||||
The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without Markdown include internal HTML:
|
||||
Shortcodes can be called using two different notations, distinguished by their tag delimiters.
|
||||
|
||||
```go-html-template
|
||||
{{</* myshortcode */>}}<p>Hello <strong>World!</strong></p>{{</* /myshortcode */>}}
|
||||
Notation|Example
|
||||
:--|:--
|
||||
Markdown|`{{%/* foo */%}} ## Section 1 {{%/* /foo */%}}`
|
||||
Standard|`{{</* foo */>}} ## Section 2 {{</* /foo */>}}`
|
||||
|
||||
###### Markdown notation
|
||||
|
||||
Hugo processes the shortcode before the page content is rendered by the Markdown renderer. This means, for instance, that Markdown headings inside a Markdown-notation shortcode will be included when invoking the [`TableOfContents`] method on the `Page` object.
|
||||
|
||||
[`TableOfContents`]: /methods/page/tableofcontents/
|
||||
|
||||
###### Standard notation
|
||||
|
||||
With standard notation, Hugo processes the shortcode separately, merging the output into the page content after Markdown rendering. This means, for instance, that Markdown headings inside a standard-notation shortcode will be excluded when invoking the `TableOfContents` method on the `Page` object.
|
||||
|
||||
By way of example, with this shortcode template:
|
||||
|
||||
{{< code file=layouts/shortcodes/foo.html >}}
|
||||
{{ .Inner }}
|
||||
{{< /code >}}
|
||||
|
||||
And this markdown:
|
||||
|
||||
{{< code file=content/example.md >}}
|
||||
{{%/* foo */%}} ## Section 1 {{%/* /foo */%}}
|
||||
|
||||
{{</* foo */>}} ## Section 2 {{</* /foo */>}}
|
||||
{{< /code >}}
|
||||
|
||||
Hugo renders this HTML:
|
||||
|
||||
```html
|
||||
<h2 id="heading">Section 1</h2>
|
||||
|
||||
## Section 2
|
||||
```
|
||||
|
||||
### Nested shortcodes
|
||||
In the above, "Section 1" will be included when invoking the `TableOfContents` method, while "Section 2" will not.
|
||||
|
||||
You can call shortcodes within other shortcodes by creating your own templates that leverage the `.Parent` method. `.Parent` allows you to check the context in which the shortcode is being called. See [Shortcode templates][sctemps].
|
||||
The shortcode author determines which notation to use. Consult each shortcode's documentation for specific usage instructions and available arguments.
|
||||
|
||||
## Embedded shortcodes
|
||||
## Nesting
|
||||
|
||||
See the [shortcodes](/shortcodes/) section.
|
||||
Shortcodes (excluding [inline](#inline) shortcodes) can be nested, creating parent-child relationships. For example, a gallery shortcode might contain several image shortcodes:
|
||||
|
||||
## Privacy configuration
|
||||
{{< code file=content/example.md >}}
|
||||
{{</* gallery class="content-gallery" */>}}
|
||||
{{</* image src="/images/a.jpg" */>}}
|
||||
{{</* image src="/images/b.jpg" */>}}
|
||||
{{</* image src="/images/c.jpg" */>}}
|
||||
{{</* /gallery */>}}
|
||||
{{< /code >}}
|
||||
|
||||
To learn how to configure your Hugo site to meet the new EU privacy regulation, see [privacy protections].
|
||||
The [shortcode templates][nesting] section provides a detailed explanation and examples.
|
||||
|
||||
## Create custom shortcodes
|
||||
|
||||
To learn more about creating custom shortcodes, see the [shortcode template documentation].
|
||||
|
||||
[privacy protections]: /about/privacy/
|
||||
[partials]: /templates/partial/
|
||||
[quickstart]: /getting-started/quick-start/
|
||||
[sctemps]: /templates/shortcode/
|
||||
[shortcode template documentation]: /templates/shortcode/
|
||||
[Vimeo]: https://vimeo.com/
|
||||
[YouTube Videos]: https://www.youtube.com/
|
||||
[nesting]: /templates/shortcode/#nesting
|
||||
|
||||
Reference in New Issue
Block a user