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,6 +1,6 @@
|
||||
---
|
||||
title: Content management
|
||||
linkTitle: In this section
|
||||
|
||||
description: Hugo makes managing large static sites easy with support for archetypes, content types, menus, cross references, summaries, and more.
|
||||
categories: []
|
||||
keywords: []
|
||||
|
||||
@@ -76,13 +76,13 @@ Date
|
||||
: (`string`) The current date and time, formatted in compliance with RFC3339.
|
||||
|
||||
File
|
||||
: (`hugolib.fileInfo`) Returns file information for the current page. See [details](/methods/page/file).
|
||||
: (`hugolib.fileInfo`) Returns file information for the current page. See [details](/methods/page/file).
|
||||
|
||||
Type
|
||||
: (`string`) The [content type](g) inferred from the top-level directory name, or as specified by the `--kind` flag passed to the `hugo new content` command.
|
||||
|
||||
Site
|
||||
: (`page.Site`) The current site object. See [details](/methods/site/).
|
||||
: (`page.Site`) The current site object. See [details](/methods/site/).
|
||||
|
||||
## Date format
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ weight: 290
|
||||
toc: true
|
||||
---
|
||||
|
||||
{{< new-in 0.126.0 >}}
|
||||
{{< new-in 0.126.0 />}}
|
||||
|
||||
## Overview
|
||||
|
||||
|
||||
@@ -142,7 +142,7 @@ produces this HTML:
|
||||
The behavior can be configured in `hugo.toml`:
|
||||
|
||||
refLinksErrorLevel ("ERROR")
|
||||
: When using `ref` or `relref` to resolve page links and a link cannot resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`).
|
||||
: When using `ref` or `relref` to resolve page links and a link cannot be resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`).
|
||||
|
||||
refLinksNotFoundURL
|
||||
: URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is.
|
||||
|
||||
@@ -74,7 +74,7 @@ Create your content in [HTML] preceded by front matter. The content is typically
|
||||
|
||||
### Emacs Org Mode
|
||||
|
||||
Create your content in the [Emacs Org Mode] format preceded by front matter. You can use Org Mode keywords for front matter. See [details].
|
||||
Create your content in the [Emacs Org Mode] format preceded by front matter. You can use Org Mode keywords for front matter. See [details].
|
||||
|
||||
[details]: /content-management/front-matter/#emacs-org-mode
|
||||
[Emacs Org Mode]: https://orgmode.org/
|
||||
|
||||
@@ -179,7 +179,7 @@ path
|
||||
|
||||
###### params
|
||||
|
||||
{{< new-in 0.123.0 >}}
|
||||
{{< new-in 0.123.0 />}}
|
||||
|
||||
(`map`) A map of custom [page parameters].
|
||||
|
||||
@@ -258,7 +258,7 @@ Alias to [expirydate](#expirydate).
|
||||
|
||||
## Parameters
|
||||
|
||||
{{< new-in 0.123.0 >}}
|
||||
{{< new-in 0.123.0 />}}
|
||||
|
||||
Specify custom page parameters under the `params` key in front matter:
|
||||
|
||||
|
||||
@@ -17,7 +17,7 @@ To process an image you must access the file as a page resource, global resource
|
||||
|
||||
### Page resource
|
||||
|
||||
A page resource is a file within a [page bundle]. A page bundle is a directory with an `index.md` or `_index.md` file at its root.
|
||||
A page resource is a file within a [page bundle]. A page bundle is a directory with an `index.md` or `_index.md` file at its root.
|
||||
|
||||
```text
|
||||
content/
|
||||
@@ -110,7 +110,7 @@ Metadata (EXIF, IPTC, XMP, etc.) is not preserved during image transformation. U
|
||||
|
||||
### Process
|
||||
|
||||
{{< new-in 0.119.0 >}}
|
||||
{{< new-in 0.119.0 />}}
|
||||
|
||||
{{% note %}}
|
||||
The `Process` method is also available as a filter, which is more effective if you need to apply multiple filters to an image. See [Process filter](/functions/images/process).
|
||||
|
||||
@@ -13,7 +13,7 @@ toc: true
|
||||
math: true
|
||||
---
|
||||
|
||||
{{< new-in 0.122.0 >}}
|
||||
{{< new-in 0.122.0 />}}
|
||||
|
||||
## Overview
|
||||
|
||||
@@ -44,7 +44,7 @@ Equations and expressions can be displayed inline with other text, or as standal
|
||||
Whether an equation or expression appears inline, or as a block, depends on the delimiters that surround the mathematical markup. Delimiters are defined in pairs, where each pair consists of an opening and closing delimiter. The opening and closing delimiters may be the same, or different.
|
||||
|
||||
{{% note %}}
|
||||
You can configure Hugo to render mathematical markup on the client-side using the MathJax or KaTeX display engine, or you can render the markup while building your site with the [`transform.ToMath`]function.
|
||||
You can configure Hugo to render mathematical markup on the client side using the MathJax or KaTeX display engine, or you can render the markup with the [`transform.ToMath`] function while building your site.
|
||||
|
||||
The first approach is described below.
|
||||
|
||||
@@ -105,7 +105,10 @@ Create a partial template to load MathJax or KaTeX. The example below loads Math
|
||||
tex: {
|
||||
displayMath: [['\\[', '\\]'], ['$$', '$$']], // block
|
||||
inlineMath: [['\\(', '\\)']] // inline
|
||||
}
|
||||
},
|
||||
loader:{
|
||||
load: ['ui/safe']
|
||||
},
|
||||
};
|
||||
</script>
|
||||
{{< /code >}}
|
||||
@@ -192,9 +195,25 @@ See the [inline delimiters](#inline-delimiters) section for details.
|
||||
To use KaTeX instead of MathJax, replace the partial template from [Step 2] with this:
|
||||
|
||||
{{< code file=layouts/partials/math.html copy=true >}}
|
||||
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css" integrity="sha384-n8MVd4RsNIU0tAv4ct0nTaAbDJwPJzDEaqSD1odI+WdtXRGWt2kTvGFasHpSy3SV" crossorigin="anonymous">
|
||||
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js" integrity="sha384-XjKyOOlGwcjNTAIQHIpgOno0Hl1YQqzUOEleOLALmuqehneUG+vnGctmUb0ZY0l8" crossorigin="anonymous"></script>
|
||||
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js" integrity="sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCRWbxyPt0Koah1uHoK0o4+/RRE05" crossorigin="anonymous"></script>
|
||||
<link
|
||||
rel="stylesheet"
|
||||
href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css"
|
||||
integrity="sha384-zh0CIslj+VczCZtlzBcjt5ppRcsAmDnRem7ESsYwWwg3m/OaJ2l4x7YBZl9Kxxib"
|
||||
crossorigin="anonymous"
|
||||
>
|
||||
<script
|
||||
defer
|
||||
src="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.js"
|
||||
integrity="sha384-Rma6DA2IPUwhNxmrB/7S3Tno0YY7sFu9WSYMCuulLhIqYSGZ2gKCJWIqhBWqMQfh"
|
||||
crossorigin="anonymous">
|
||||
</script>
|
||||
<script
|
||||
defer
|
||||
src="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/contrib/auto-render.min.js"
|
||||
integrity="sha384-hCXGrW6PitJEwbkoStFjeJxv+fSOOQKOPbJxSfM6G5sWZjAyWhXiTIIAmQqnlLlh"
|
||||
crossorigin="anonymous"
|
||||
onload="renderMathInElement(document.body);">
|
||||
</script>
|
||||
<script>
|
||||
document.addEventListener("DOMContentLoaded", function() {
|
||||
renderMathInElement(document.body, {
|
||||
|
||||
@@ -140,7 +140,7 @@ When building the English site:
|
||||
{{ site.Params.subtitle }} --> Reference, Tutorials, and Explanations
|
||||
```
|
||||
|
||||
When building the English site:
|
||||
When building the German site:
|
||||
|
||||
```go-html-template
|
||||
{{ site.Params.color }} --> blue
|
||||
|
||||
@@ -30,10 +30,10 @@ The "about" page is a page bundle. It logically associates a resource with conte
|
||||
Page bundles are either _leaf bundles_ or _branch bundles_.
|
||||
|
||||
leaf bundle
|
||||
: A _leaf bundle_ is a directory that contains an `index.md` file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants.
|
||||
: A _leaf bundle_ is a directory that contains an `index.md` file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants.
|
||||
|
||||
branch bundle
|
||||
: A _branch bundle_ is a directory that contains an `_index.md` file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without `_index.md` files are also branch bundles. This includes the home page.
|
||||
: A _branch bundle_ is a directory that contains an `_index.md` file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without `_index.md` files are also branch bundles. This includes the home page.
|
||||
|
||||
{{% note %}}
|
||||
In the definitions above and the examples below, the extension of the index file depends on the [content format](g). For example, use `index.md` for Markdown content, `index.html` for HTML content, `index.adoc` for AsciiDoc content, etc.
|
||||
@@ -63,7 +63,7 @@ Files with [resource type](g) `page` include content written in Markdown, HTML,
|
||||
|
||||
## Leaf bundles
|
||||
|
||||
A _leaf bundle_ is a directory that contains an `index.md` file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants.
|
||||
A _leaf bundle_ is a directory that contains an `index.md` file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants.
|
||||
|
||||
```text
|
||||
content/
|
||||
@@ -114,7 +114,7 @@ Create leaf bundles at any depth within the `content` directory, but a leaf bund
|
||||
|
||||
## Branch bundles
|
||||
|
||||
A _branch bundle_ is a directory that contains an `_index.md` file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without `_index.md` files are also branch bundles. This includes the home page.
|
||||
A _branch bundle_ is a directory that contains an `_index.md` file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without `_index.md` files are also branch bundles. This includes the home page.
|
||||
|
||||
```text
|
||||
content/
|
||||
@@ -143,7 +143,7 @@ branch-bundle-2
|
||||
: This branch bundle contains an index file and a leaf bundle.
|
||||
|
||||
{{% note %}}
|
||||
Create branch bundles at any depth within the `content` directory, but a leaf bundle may not contain another bundle. Leaf bundles do not have descendants.
|
||||
Create branch bundles at any depth within the `content` directory. Branch bundles may have descendants.
|
||||
{{% /note %}}
|
||||
|
||||
## Headless bundles
|
||||
|
||||
@@ -12,7 +12,7 @@ toc: true
|
||||
---
|
||||
|
||||
Page resources are only accessible from [page bundles](/content-management/page-bundles), those directories with `index.md` or
|
||||
`_index.md` files at their root. Page resources are only available to the
|
||||
`_index.md` files at their root. Page resources are only available to the
|
||||
page with which they are bundled.
|
||||
|
||||
In this example, `first-post` is a page bundle with access to 10 page resources including audio, data, documents, images, and video. Although `second-post` is also a page bundle, it has no page resources and is unable to directly access the page resources associated with `first-post`.
|
||||
@@ -206,7 +206,7 @@ the `Name` and `Title` will be assigned to the resource files as follows:
|
||||
|
||||
## Multilingual
|
||||
|
||||
{{< new-in 0.123.0 >}}
|
||||
{{< new-in 0.123.0 />}}
|
||||
|
||||
By default, with a multilingual single-host site, Hugo does not duplicate shared page resources when building the site.
|
||||
|
||||
|
||||
@@ -15,10 +15,10 @@ aliases: [/content/sections/]
|
||||
|
||||
## Overview
|
||||
|
||||
A section is a top-level content directory, or any content directory with an `_index.md` file. A content directory with an `_index.md` file is also known as a [branch bundle](g). Section templates receive one or more page [collections](g) in [context](g).
|
||||
A section is a top-level content directory, or any content directory with an `_index.md` file. A content directory with an `_index.md` file is also known as a [branch bundle](g). Section templates receive one or more page [collections](g) in [context](g).
|
||||
|
||||
{{% note %}}
|
||||
Although top-level directories without `_index.md` files are sections, we recommend creating `_index.md` files in _all_ sections.
|
||||
Although top-level directories without `_index.md` files are sections, we recommend creating `_index.md` files in _all_ sections.
|
||||
{{% /note %}}
|
||||
|
||||
A typical site consists of one or more sections. For example:
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -56,7 +56,7 @@ If you set both `slug` and `url` in front matter, the `url` value takes preceden
|
||||
|
||||
#### Include a colon
|
||||
|
||||
{{< new-in 0.136.0 >}}
|
||||
{{< new-in 0.136.0 />}}
|
||||
|
||||
If you need to include a colon in the `url` front matter field, escape it with backslash characters. Use one backslash if you wrap the string within single quotes, or use two backslashes if you wrap the string within double quotes. With YAML front matter, use a single backslash if you omit quotation marks.
|
||||
|
||||
@@ -118,7 +118,7 @@ multilingual|`about`|`https://example.org/de/about/`
|
||||
|
||||
#### Permalinks tokens in front matter
|
||||
|
||||
{{< new-in "0.131.0" >}}
|
||||
{{< new-in 0.131.0 />}}
|
||||
|
||||
You can also use [tokens](#tokens) when setting the `url` value. This is typically used in `cascade` sections:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user