Namespace functions and methods

This commit is contained in:
Joe Mooring authored and GitHub committed 2023-11-04 21:01:42 -07:00
1 parent 40212779ae
commit 723a827fdc
687 files changed
+20449 -5821

No files matched your search

+51
View File
@@ -0,0 +1,51 @@
---
title: Get
description: Returns the value of the given parameter.
categories: []
keywords: []
action:
related:
- methods/shortcode/IsNamedParams
- methods/shortcode/Params
returnType: any
signatures: [SHORTCODE.Get PARAM]
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.
{{% note %}}
Some shortcodes support positional parameters, some support named parameters, and others support both. Refer to the shortcode's documentation for usage details.
{{% /note %}}
## Positional parameters
This shortcode call uses positional parameters:
{{< code file="content/about.md" lang=md copy=false >}}
{{</* myshortcode "Hello" "world" */>}}
{{< /code >}}
To retrieve parameters by position:
{{< code file="layouts/shortcodes/myshortcode.html" lang=go-html-template copy=false >}}
{{ printf "%s %s." (.Get 0) (.Get 1) }} → Hello world.
{{< /code >}}
## Named parameters
This shortcode call uses named parameters:
{{< code file="content/about.md" lang=md copy=false >}}
{{</* myshortcode greeting="Hello" firstName="world" */>}}
{{< /code >}}
To retrieve parameters by name:
{{< code file="layouts/shortcodes/myshortcode.html" lang=go-html-template copy=false >}}
{{ printf "%s %s." (.Get "greeting") (.Get "firstName") }} → Hello world.
{{< /code >}}
{{% note %}}
Parameter names are case-sensitive.
{{% /note %}}
+153
View File
@@ -0,0 +1,153 @@
---
title: Inner
description: Returns the content between opening and closing shortcode tags, applicable when the shortcode call includes a closing tag.
categories: []
keywords: []
action:
related:
- functions/strings/Trim
- methods/page/RenderString
- functions/transform/Markdownify
- methods/shortcode/InnerDeindent
returnType: template.HTML
signatures: [SHORTCODE.Inner]
---
This content:
{{< code file="content/services.md" lang=md copy=false >}}
{{</* card title="Product Design" */>}}
We design the **best** widgets in the world.
{{</* /card */>}}
{{< /code >}}
With this shortcode:
{{< code file="layouts/shortcodes/card.html" lang=go-html-template copy=false >}}
<div class="card">
{{ with .Get "title" }}
<div class="card-title">{{ . }}</div>
{{ end }}
<div class="card-content">
{{ trim .Inner "\r\n" }}
</div>
</div>
{{< /code >}}
Is rendered to:
```html
<div class="card">
<div class="card-title">Product Design</div>
<div class="card-content">
We design the **best** widgets in the world.
</div>
</div>
```
{{% note %}}
Content between opening and closing shortcode tags may include leading and/or trailing newlines, depending on placement within the markdown. Use the [`trim`] function as shown above to remove both carriage returns and newlines.
[`trim`]: /functions/strings/trim
{{% /note %}}
{{% note %}}
In the example above, the value returned by `Inner` is markdown, but it was rendered as plain text. Use either of the following approaches to render markdown to HTML.
{{% /note %}}
## Use the RenderString method
Let's modify the example above to pass the value returned by `Inner` through the [`RenderString`] method on the `Page` object:
[`RenderString`]: /methods/page/renderstring
{{< code file="layouts/shortcodes/card.html" lang=go-html-template copy=false >}}
<div class="card">
{{ with .Get "title" }}
<div class="card-title">{{ . }}</div>
{{ end }}
<div class="card-content">
{{ trim .Inner "\r\n" | .Page.RenderString }}
</div>
</div>
{{< /code >}}
Hugo renders this to:
```html
<div class="card">
<div class="card-title">Product design</div>
<div class="card-content">
We produce the <strong>best</strong> widgets in the world.
</div>
</div>
```
You can use the [`markdownify`] function instead of the `RenderString` method, but the latter is more flexible. See&nbsp;[details].
[details]: /methods/page/renderstring
[`markdownify`]: /functions/transform/markdownify
## Use alternate notation
Instead of calling the shortcode with the `{{</* */>}}` notation, use the `{{%/* */%}}` notation:
{{< code file="content/services.md" lang=md copy=false >}}
{{%/* card title="Product Design" */%}}
We design the **best** widgets in the world.
{{%/* /card */%}}
{{< /code >}}
When you use the `{{%/* */%}}` notation, Hugo renders the entire shortcode as markdown, requiring the following changes.
First, configure the renderer to allow raw HTML within markdown:
{{< code-toggle file=hugo copy=false >}}
[markup.goldmark.renderer]
unsafe = true
{{< /code-toggle >}}
This configuration is not unsafe if _you_ control the content. Read more about Hugo's [security model].
Second, because we are rendering the entire shortcode as markdown, we must adhere to the rules governing [indentation] and inclusion of [raw HTML blocks] as provided in the [CommonMark] specification.
{{< code file="layouts/shortcodes/card.html" lang=go-html-template copy=false >}}
<div class="card">
{{ with .Get "title" }}
<div class="card-title">{{ . }}</div>
{{ end }}
<div class="card-content">
{{ trim .Inner "\r\n" }}
</div>
</div>
{{< /code >}}
The difference between this and the previous example is subtle but required. Note the change in indentation, the addition of a blank line, and removal of the `RenderString` method.
```diff
--- layouts/shortcodes/a.html
+++ layouts/shortcodes/b.html
@@ -1,8 +1,9 @@
<div class="card">
{{ with .Get "title" }}
- <div class="card-title">{{ . }}</div>
+ <div class="card-title">{{ . }}</div>
{{ end }}
<div class="card-content">
- {{ trim .Inner "\r\n" | .Page.RenderString }}
+
+ {{ trim .Inner "\r\n" }}
</div>
</div>
```
{{% note %}}
When using the `{{%/* */%}}` notation, do not pass the value returned by `Inner` through the `RenderString` method or the `markdownify` function.
{{% /note %}}
[commonmark]: https://commonmark.org/
[indentation]: https://spec.commonmark.org/0.30/#indented-code-blocks
[raw html blocks]: https://spec.commonmark.org/0.30/#html-blocks
[security model]: /about/security-model/
@@ -0,0 +1,99 @@
---
title: InnerDeindent
description: Returns the content between opening and closing shortcode tags, with indentation removed, applicable when the shortcode call includes a closing tag.
categories: []
keywords: []
action:
related:
- methods/shortcode/Inner
returnType: template.HTML
signatures: [SHORTCODE.InnerDeindent]
---
Similar to the [`Inner`] method, `InnerDeindent` returns the content between opening and closing shortcode tags. However, with `InnerDeindent`, indentation before the content is removed.
This allows us to effectively bypass the rules governing [indentation] as provided in the [CommonMark] specification.
Consider this markdown, an unordered list with a small gallery of thumbnail images within each list item:
{{< code file="content/about.md" lang=md copy=false >}}
- Gallery one
{{</* gallery */>}}
![kitten a](thumbnails/a.jpg)
![kitten b](thumbnails/b.jpg)
{{</* /gallery */>}}
- Gallery two
{{</* gallery */>}}
![kitten c](thumbnails/c.jpg)
![kitten d](thumbnails/d.jpg)
{{</* /gallery */>}}
{{< /code >}}
In the example above, notice that the content between the opening and closing shortcode tags is indented by four spaces. Per the CommonMark specification, this is treated as an indented code block.
With this shortcode, calling `Inner` instead of `InnerDeindent`:
{{< code file="layouts/shortcodes/gallery.html" lang=go-html-template copy=false >}}
<div class="gallery">
{{ trim .Inner "\r\n" | .Page.RenderString }}
</div>
{{< /code >}}
Hugo renders the markdown to:
```html
<ul>
<li>
<p>Gallery one</p>
<div class="gallery">
<pre><code>![kitten a](images/a.jpg)
![kitten b](images/b.jpg)
</code></pre>
</div>
</li>
<li>
<p>Gallery two</p>
<div class="gallery">
<pre><code>![kitten c](images/c.jpg)
![kitten d](images/d.jpg)
</code></pre>
</div>
</li>
</ul>
```
Although technically correct per the CommonMark specification, this is not what we want. If we remove the indentation using the `InnerDeindent` method:
{{< code file="layouts/shortcodes/gallery.html" lang=go-html-template copy=false >}}
<div class="gallery">
{{ trim .InnerDeindent "\r\n" | .Page.RenderString }}
</div>
{{< /code >}}
Hugo renders the markdown to:
```html
<ul>
<li>
<p>Gallery one</p>
<div class="gallery">
<img src="images/a.jpg" alt="kitten a">
<img src="images/b.jpg" alt="kitten b">
</div>
</li>
<li>
<p>Gallery two</p>
<div class="gallery">
<img src="images/c.jpg" alt="kitten c">
<img src="images/d.jpg" alt="kitten d">
</div>
</li>
</ul>
```
[commonmark]: https://commonmark.org/
[indentation]: https://spec.commonmark.org/0.30/#indented-code-blocks
[`Inner`]: /methods/shortcode/inner
@@ -0,0 +1,30 @@
---
title: IsNamedParams
description: Reports whether the shortcode call specifies named or positional parameters.
categories: []
keywords: []
action:
related:
- methods/shortcode/Get
returnType: bool
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.
With this shortcode template:
{{< code file="layouts/shortcodes/myshortcode.html" lang=go-html-template copy=false >}}
{{ if .IsNamedParams }}
{{ printf "%s %s." (.Get "greeting") (.Get "firstName") }}
{{ else }}
{{ printf "%s %s." (.Get 0) (.Get 1) }}
{{ end }}
{{< /code >}}
Both of these calls return the same value:
{{< code file="content/about.md" lang=md copy=false >}}
{{</* myshortcode greeting="Hello" firstName="world" */>}}
{{</* myshortcode "Hello" "world" */>}}
{{< /code >}}
+29
View File
@@ -0,0 +1,29 @@
---
title: Name
description: Returns the shortcode file name, excluding the file extension.
categories: []
keywords: []
action:
related:
- methods/shortcode/Position
- functions/fmt/Errorf
returnType: string
signatures: [SHORTCODE.Name]
---
The `Name` method is useful for error reporting. For example, if your shortcode requires a "greeting" parameter:
{{< code file="layouts/shortcodes/myshortcode.html" lang=go-html-template copy=false >}}
{{ $greeting := "" }}
{{ with .Get "greeting" }}
{{ $greeting = . }}
{{ else }}
{{ errorf "The %q shortcode requires a 'greeting' parameter. See %s" .Name .Position }}
{{ end }}
{{< /code >}}
In the absence of a "greeting" parameter, 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"
```
+50
View File
@@ -0,0 +1,50 @@
---
title: Ordinal
description: Returns the zero-based ordinal of the shortcode in relation to its parent.
categories: []
keywords: []
action:
related: []
returnType: int
signatures: [SHORTCODE.Ordinal]
---
The `Ordinal` method returns the zero-based ordinal of the shortcode in relation to its parent. If the parent is the page itself, the ordinal represents the position of this shortcode in the page content.
This method is useful for, among other things, assigning unique element IDs when a shortcode is called two or more times from the same page. For example:
{{< code file="content/about.md" lang=md copy=false >}}
{{</* img src="images/a.jpg" */>}}
{{</* img src="images/b.jpg" */>}}
{{< /code >}}
This shortcode performs error checking, then renders an HTML `img` element with a unique `id` attribute:
{{< code file="layouts/shortcodes/img.html" lang=go-html-template copy=false >}}
{{ $src := "" }}
{{ with .Get "src" }}
{{ $src = . }}
{{ with resources.Get $src }}
{{ $id := printf "img-%03d" $.Ordinal }}
<img id="{{ $id }}" src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ else }}
{{ 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 }}
{{ end }}
{{< /code >}}
Hugo renders the page to:
```html
<img id="img-000" src="/images/a.jpg" width="600" height="400" alt="">
<img id="img-001" src="/images/b.jpg" width="600" height="400" alt="">
```
{{% note %}}
In the shortcode template above, the [`with`] statement is used to create conditional blocks. Remember that the `with` statement binds context (the dot) to its expression. Inside of a `with` block, preface shortcode method calls with a `$` to access the top level context passed into the template.
[`with`]: /functions/go-template/with
{{% /note %}}
+36
View File
@@ -0,0 +1,36 @@
---
title: Page
description: Returns the Page object from which the shortcode was called.
categories: []
keywords: []
action:
related: []
returnType: hugolib.pageForShortcode
signatures: [SHORTCODE.Page]
---
With this content:
{{< code-toggle file=content/books/les-miserables.md copy=false fm=true >}}
title = 'Les Misérables'
author = 'Victor Hugo'
published = 1862
isbn = '978-0451419439'
{{< /code-toggle >}}
Calling this shortcode:
```text
{{</* book-details */>}}
```
We can access the front matter values using the `Page` method:
{{< code file="layouts/shortcodes/book-details.html" lang=go-html-template copy=false >}}
<ul>
<li>Title: {{ .Page.Title }}</li>
<li>Author: {{ .Page.Params.author }}</li>
<li>Published: {{ .Page.Params.publication_year }}</li>
<li>ISBN: {{ .Page.Params.isbn }}</li>
</ul>
{{< /code >}}
+33
View File
@@ -0,0 +1,33 @@
---
title: Params
description: Returns a collection of the shortcode parameters.
categories: []
keywords: []
action:
related:
- methods/shortcode/Get
returnType: any
signatures: [SHORTCODE.Params]
---
When you call a shortcode using positional parameters, the `Params` method returns a slice.
{{< code file="content/about.md" lang=md copy=false >}}
{{</* myshortcode "Hello" "world" */>}}
{{< /code >}}
{{< code file="layouts/shortcodes/myshortcode.html" lang=go-html-template copy=false >}}
{{ index .Params 0 }} → Hello
{{ index .Params 1 }} → world
{{< /code >}}
When you call a shortcode using named parameters, the `Params` method returns a map.
{{< code file="content/about.md" lang=md copy=false >}}
{{</* myshortcode greeting="Hello" name="world" */>}}
{{< /code >}}
{{< code file="layouts/shortcodes/myshortcode.html" lang=go-html-template copy=false >}}
{{ .Params.greeting }} → Hello
{{ .Params.name }} → world
{{< /code >}}
+50
View File
@@ -0,0 +1,50 @@
---
title: Parent
description: Returns the parent shortcode context in nested shortcodes.
categories: []
keywords: []
action:
related: []
returnType: hugolib.ShortcodeWithPage
signatures: [SHORTCODE.Parent]
---
This is useful for inheritance of common shortcode parameters from the root.
In this contrived example, the "greeting" shortcode is the parent, and the "now" shortcode is child.
{{< code file="content/welcome.md" lang=md copy=false >}}
{{</* greeting dateFormat="Jan 2, 2006" */>}}
Welcome. Today is {{</* now */>}}.
{{</* /greeting */>}}
{{< /code >}}
{{< code file="layouts/shortcodes/greeting.html" lang=go-html-template copy=false >}}
<div class="greeting">
{{ trim .Inner "\r\n" | .Page.RenderString }}
</div>
{{< /code >}}
{{< code file="layouts/shortcodes/now.html" lang=go-html-template copy=false >}}
{{- $dateFormat := "January 2, 2006 15:04:05" }}
{{- with .Params }}
{{- with .dateFormat }}
{{- $dateFormat = . }}
{{- end }}
{{- else }}
{{- with .Parent.Params }}
{{- with .dateFormat }}
{{- $dateFormat = . }}
{{- end }}
{{- end }}
{{- end }}
{{- now | time.Format $dateFormat -}}
{{< /code >}}
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
3. The default layout string defined at the top of the shortcode
+33
View File
@@ -0,0 +1,33 @@
---
title: Position
description: Returns the filename and position from which the shortcode was called.
categories: []
keywords: []
action:
related:
- methods/shortcode/Name
- functions/fmt/Errorf
returnType: text.Position
signatures: [SHORTCODE.Position]
---
The `Position` method is useful for error reporting. For example, if your shortcode requires a "greeting" parameter:
{{< code file="layouts/shortcodes/myshortcode.html" lang=go-html-template copy=false >}}
{{ $greeting := "" }}
{{ with .Get "greeting" }}
{{ $greeting = . }}
{{ else }}
{{ errorf "The %q shortcode requires a 'greeting' parameter. See %s" .Name .Position }}
{{ end }}
{{< /code >}}
In the absence of a "greeting" parameter, 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"
```
{{% note %}}
The position can relatively expensive to calculate. Limit its use to error reporting.
{{% /note %}}
+24
View File
@@ -0,0 +1,24 @@
---
title: Scratch
description: Creates a "scratch pad" scoped to the shortcode to store and manipulate data.
categories: []
keywords: []
action:
related:
- functions/collections/NewScratch
returnType: maps.Scratch
signatures: [SHORTCODE.Scratch]
---
The `Scratch` method within a shortcode creates a [scratch pad] to store and manipulate data. The scratch pad is scoped to the shortcode, and is reset on server rebuilds.
{{% note %}}
With the introduction of the [`newScratch`] function, and the ability to [assign values to template variables] after initialization, the `Scratch` method within a shortcode is obsolete.
[assign values to variables]: https://go.dev/doc/go1.11#text/template
[`newScratch`]: functions/collections/newscratch
{{% /note %}}
[scratch pad]: /getting-started/glossary/#scratch-pad
{{% include "methods/page/_common/scratch-methods.md" %}}
+12
View File
@@ -0,0 +1,12 @@
---
title: Shortcode methods
linkTitle: Shortcode
description: Use these methods in your shortcode templates.
categories: []
keywords: []
menu:
docs:
parent: methods
---
Use these methods in your shortcode templates.