tiennm99/hugoDocs
1
0 Fork 0
mirror of https://github.com/tiennm99/hugoDocs.git synced 2026-10-14 08:18:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

content: Consolidate configuration documentation

Browse Source
This commit is contained in:
Joe Mooring authored and GitHub committed 2025-03-05 04:50:06 -08:00
1 parent 727ef6f665
commit b6cae5cbc6
911 files changed
+10902 -11171
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

content/en/methods/shortcode/Get.md
+11 -11
View File
@@ -3,13 +3,13 @@ title: Get
description: Returns the value of the given argument.
categories: []
keywords: []
action:
related:
- methods/shortcode/IsNamedParams
- methods/shortcode/Params
returnType: any
signatures: [SHORTCODE.Get ARG]
toc: true
params:
functions_and_methods:
related:
- methods/shortcode/IsNamedParams
- methods/shortcode/Params
returnType: any
signatures: [SHORTCODE.Get ARG]
---
Specify the argument by position or by name. When calling a shortcode within Markdown, use either positional or named argument, but not both.
@@ -22,13 +22,13 @@ Some shortcodes support positional arguments, some support named arguments, and
This shortcode call uses positional arguments:
{{< code file=content/about.md lang=md >}}
{{< code file=content/about.md lang=text >}}
{{</* myshortcode "Hello" "world" */>}}
{{< /code >}}
To retrieve arguments by position:
{{< code file=layouts/shortcodes/myshortcode.html >}}
{{< code file=layouts/shortcodes/myshortcode.html >}}
{{ printf "%s %s." (.Get 0) (.Get 1) }} → Hello world.
{{< /code >}}
@@ -36,13 +36,13 @@ To retrieve arguments by position:
This shortcode call uses named arguments:
{{< code file=content/about.md lang=md >}}
{{< code file=content/about.md lang=text >}}
{{</* myshortcode greeting="Hello" firstName="world" */>}}
{{< /code >}}
To retrieve arguments by name:
{{< code file=layouts/shortcodes/myshortcode.html >}}
{{< code file=layouts/shortcodes/myshortcode.html >}}
{{ printf "%s %s." (.Get "greeting") (.Get "firstName") }} → Hello world.
{{< /code >}}
content/en/methods/shortcode/Inner.md
+14 -14
View File
@@ -3,20 +3,20 @@ 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]
toc: true
params:
functions_and_methods:
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 >}}
{{< code file=content/services.md lang=text >}}
{{</* card title="Product Design" */>}}
We design the **best** widgets in the world.
{{</* /card */>}}
@@ -24,7 +24,7 @@ We design the **best** widgets in the world.
With this shortcode:
{{< code file=layouts/shortcodes/card.html >}}
{{< code file=layouts/shortcodes/card.html >}}
<div class="card">
{{ with .Get "title" }}
<div class="card-title">{{ . }}</div>
@@ -62,7 +62,7 @@ Let's modify the example above to pass the value returned by `Inner` through the
[`RenderString`]: /methods/page/renderstring/
{{< code file=layouts/shortcodes/card.html >}}
{{< code file=layouts/shortcodes/card.html >}}
<div class="card">
{{ with .Get "title" }}
<div class="card-title">{{ . }}</div>
@@ -93,7 +93,7 @@ You can use the [`markdownify`] function instead of the `RenderString` method, b
Instead of calling the shortcode with the `{{</* */>}}` notation, use the `{{%/* */%}}` notation:
{{< code file=content/services.md lang=md >}}
{{< code file=content/services.md lang=text >}}
{{%/* card title="Product Design" */%}}
We design the **best** widgets in the world.
{{%/* /card */%}}
@@ -112,7 +112,7 @@ This configuration is not unsafe if _you_ control the content. Read more about H
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 >}}
{{< code file=layouts/shortcodes/card.html >}}
<div class="card">
{{ with .Get "title" }}
<div class="card-title">{{ . }}</div>
content/en/methods/shortcode/InnerDeindent.md
+10 -9
View File
@@ -1,13 +1,14 @@
---
title: InnerDeindent
description: Returns the content between opening and closing shortcode tags, with indentation removed, applicable when the shortcode call includes a closing tag.
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]
params:
functions_and_methods:
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.
@@ -16,7 +17,7 @@ This allows us to effectively bypass the rules governing [indentation] as provid
Consider this Markdown, an unordered list with a small gallery of thumbnail images within each list item:
{{< code file=content/about.md lang=md >}}
{{< code file=content/about.md lang=text >}}
- Gallery one
{{</* gallery */>}}
@@ -36,7 +37,7 @@ In the example above, notice that the content between the opening and closing sh
With this shortcode, calling `Inner` instead of `InnerDeindent`:
{{< code file=layouts/shortcodes/gallery.html >}}
{{< code file=layouts/shortcodes/gallery.html >}}
<div class="gallery">
{{ .Inner | strings.TrimSpace | .Page.RenderString }}
</div>
@@ -67,7 +68,7 @@ Hugo renders the Markdown to:
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 >}}
{{< code file=layouts/shortcodes/gallery.html >}}
<div class="gallery">
{{ .InnerDeindent | strings.TrimSpace | .Page.RenderString }}
</div>
content/en/methods/shortcode/IsNamedParams.md
+8 -7
View File
@@ -3,18 +3,19 @@ title: IsNamedParams
description: Reports whether the shortcode call uses named arguments.
categories: []
keywords: []
action:
related:
- methods/shortcode/Get
returnType: bool
signatures: [SHORTCODE.IsNamedParams]
params:
functions_and_methods:
related:
- methods/shortcode/Get
returnType: bool
signatures: [SHORTCODE.IsNamedParams]
---
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:
{{< code file=layouts/shortcodes/myshortcode.html >}}
{{< code file=layouts/shortcodes/myshortcode.html >}}
{{ if .IsNamedParams }}
{{ printf "%s %s." (.Get "greeting") (.Get "firstName") }}
{{ else }}
@@ -24,7 +25,7 @@ With this shortcode template:
Both of these calls return the same value:
{{< code file=content/about.md lang=md >}}
{{< code file=content/about.md lang=text >}}
{{</* myshortcode greeting="Hello" firstName="world" */>}}
{{</* myshortcode "Hello" "world" */>}}
{{< /code >}}
content/en/methods/shortcode/Name.md
+8 -7
View File
@@ -3,17 +3,18 @@ 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]
params:
functions_and_methods:
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" argument:
{{< code file=layouts/shortcodes/myshortcode.html >}}
{{< code file=layouts/shortcodes/myshortcode.html >}}
{{ $greeting := "" }}
{{ with .Get "greeting" }}
{{ $greeting = . }}
content/en/methods/shortcode/Ordinal.md
+9 -8
View File
@@ -3,21 +3,22 @@ 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]
params:
functions_and_methods:
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.
{{< note >}}
Hugo increments the ordinal with each shortcode call, regardless of the specific shortcode type. This means that the ordinal value is tracked sequentially across all shortcodes within a given page.
Hugo increments the ordinal with each shortcode call, regardless of the specific shortcode type. This means that the ordinal value is tracked sequentially across all shortcodes within a given page.
{{< /note >}}
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 >}}
{{< code file=content/about.md lang=text >}}
{{</* img src="images/a.jpg" */>}}
{{</* img src="images/b.jpg" */>}}
@@ -25,7 +26,7 @@ This method is useful for, among other things, assigning unique element IDs when
This shortcode performs error checking, then renders an HTML `img` element with a unique `id` attribute:
{{< code file=layouts/shortcodes/img.html >}}
{{< code file=layouts/shortcodes/img.html >}}
{{ $src := "" }}
{{ with .Get "src" }}
{{ $src = . }}
@@ -48,7 +49,7 @@ Hugo renders the page to:
```
{{< 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.
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 >}}
content/en/methods/shortcode/Page.md
+6 -5
View File
@@ -3,10 +3,11 @@ title: Page
description: Returns the Page object from which the shortcode was called.
categories: []
keywords: []
action:
related: []
returnType: hugolib.pageForShortcode
signatures: [SHORTCODE.Page]
params:
functions_and_methods:
related: []
returnType: hugolib.pageForShortcode
signatures: [SHORTCODE.Page]
---
With this content:
@@ -26,7 +27,7 @@ Calling this shortcode:
We can access the front matter values using the `Page` method:
{{< code file=layouts/shortcodes/book-details.html >}}
{{< code file=layouts/shortcodes/book-details.html >}}
<ul>
<li>Title: {{ .Page.Title }}</li>
<li>Author: {{ .Page.Params.author }}</li>
content/en/methods/shortcode/Params.md
+10 -9
View File
@@ -3,31 +3,32 @@ title: Params
description: Returns a collection of the shortcode arguments.
categories: []
keywords: []
action:
related:
- methods/shortcode/Get
returnType: any
signatures: [SHORTCODE.Params]
params:
functions_and_methods:
related:
- methods/shortcode/Get
returnType: any
signatures: [SHORTCODE.Params]
---
When you call a shortcode using positional arguments, the `Params` method returns a slice.
{{< code file=content/about.md lang=md >}}
{{< code file=content/about.md lang=text >}}
{{</* myshortcode "Hello" "world" */>}}
{{< /code >}}
{{< code file=layouts/shortcodes/myshortcode.html >}}
{{< code file=layouts/shortcodes/myshortcode.html >}}
{{ index .Params 0 }} → Hello
{{ index .Params 1 }} → world
{{< /code >}}
When you call a shortcode using named arguments, the `Params` method returns a map.
{{< code file=content/about.md lang=md >}}
{{< code file=content/about.md lang=text >}}
{{</* myshortcode greeting="Hello" name="world" */>}}
{{< /code >}}
{{< code file=layouts/shortcodes/myshortcode.html >}}
{{< code file=layouts/shortcodes/myshortcode.html >}}
{{ .Params.greeting }} → Hello
{{ .Params.name }} → world
{{< /code >}}
content/en/methods/shortcode/Parent.md
+9 -8
View File
@@ -1,31 +1,32 @@
---
title: Parent
description: Returns the parent shortcode context in nested shortcodes.
description: Returns the parent shortcode context in nested shortcodes.
categories: []
keywords: []
action:
related: []
returnType: hugolib.ShortcodeWithPage
signatures: [SHORTCODE.Parent]
params:
functions_and_methods:
related: []
returnType: hugolib.ShortcodeWithPage
signatures: [SHORTCODE.Parent]
---
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.
{{< code file=content/welcome.md lang=md >}}
{{< code file=content/welcome.md lang=text >}}
{{</* greeting dateFormat="Jan 2, 2006" */>}}
Welcome. Today is {{</* now */>}}.
{{</* /greeting */>}}
{{< /code >}}
{{< code file=layouts/shortcodes/greeting.html >}}
{{< code file=layouts/shortcodes/greeting.html >}}
<div class="greeting">
{{ .Inner | strings.TrimSpace | .Page.RenderString }}
</div>
{{< /code >}}
{{< code file=layouts/shortcodes/now.html >}}
{{< code file=layouts/shortcodes/now.html >}}
{{- $dateFormat := "January 2, 2006 15:04:05" }}
{{- with .Params }}
content/en/methods/shortcode/Position.md
+9 -8
View File
@@ -1,19 +1,20 @@
---
title: Position
description: Returns the filename and position from which the shortcode was called.
description: Returns the file name and position from which the shortcode was called.
categories: []
keywords: []
action:
related:
- methods/shortcode/Name
- functions/fmt/Errorf
returnType: text.Position
signatures: [SHORTCODE.Position]
params:
functions_and_methods:
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" argument:
{{< code file=layouts/shortcodes/myshortcode.html >}}
{{< code file=layouts/shortcodes/myshortcode.html >}}
{{ $greeting := "" }}
{{ with .Get "greeting" }}
{{ $greeting = . }}
content/en/methods/shortcode/Ref.md
+18 -20
View File
@@ -3,27 +3,28 @@ title: Ref
description: Returns the absolute URL of the page with the given path, language, and output format.
categories: []
keywords: []
action:
related:
- methods/shortcode/RelRef
- functions/urls/RelRef
- functions/urls/Ref
returnType: string
signatures: [SHORTCODE.Ref OPTIONS]
params:
functions_and_methods:
related:
- methods/shortcode/RelRef
- functions/urls/RelRef
- functions/urls/Ref
returnType: string
signatures: [SHORTCODE.Ref OPTIONS]
---
The map of option contains:
path
: (`string`) The path to the page, relative to the `content` directory. Required.
## Usage
lang
: (`string`) The language (site) to search for the page. Default is the current language. Optional.
The `Ref` method accepts a single argument: an options map.
outputFormat
: (`string`) The output format to search for the page. Default is the current output format. Optional.
## Options
The examples below show the rendered output when visiting a page on the English language version of the site:
{{% include "_common/ref-and-relref-options.md" %}}
## Examples
The following examples show the rendered output for a page on the English version of the site:
```go-html-template
{{ $opts := dict "path" "/books/book-1" }}
@@ -36,9 +37,6 @@ The examples below show the rendered output when visiting a page on the English
{{ .Ref $opts }} → https://example.org/de/books/book-1/index.json
```
By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your site configuration, and specify a URL to return when the path cannot be resolved.
## Error handling
{{< code-toggle file=hugo >}}
refLinksErrorLevel = 'warning'
refLinksNotFoundURL = '/some/other/url'
{{< /code-toggle >}}
{{% include "_common/ref-and-relref-error-handling.md" %}}
content/en/methods/shortcode/RelRef.md
+17 -20
View File
@@ -3,27 +3,27 @@ title: RelRef
description: Returns the relative URL of the page with the given path, language, and output format.
categories: []
keywords: []
action:
related:
- methods/shortcode/Ref
- functions/urls/Ref
- functions/urls/RelRef
returnType: string
signatures: [SHORTCODE.RelRef OPTIONS]
params:
functions_and_methods:
related:
- methods/shortcode/Ref
- functions/urls/Ref
- functions/urls/RelRef
returnType: string
signatures: [SHORTCODE.RelRef OPTIONS]
---
The map of option contains:
## Usage
path
: (`string`) The path to the page, relative to the `content` directory. Required.
The `RelRef` method accepts a single argument: an options map.
lang
: (`string`) The language (site) to search for the page. Default is the current language. Optional.
## Options
outputFormat
: (`string`) The output format to search for the page. Default is the current output format. Optional.
{{% include "_common/ref-and-relref-options.md" %}}
The examples below show the rendered output when visiting a page on the English language version of the site:
## Examples
The following examples show the rendered output for a page on the English version of the site:
```go-html-template
{{ $opts := dict "path" "/books/book-1" }}
@@ -36,9 +36,6 @@ The examples below show the rendered output when visiting a page on the English
{{ .RelRef $opts }} → /de/books/book-1/index.json
```
By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your site configuration, and specify a URL to return when the path cannot be resolved.
## Error handling
{{< code-toggle file=hugo >}}
refLinksErrorLevel = 'warning'
refLinksNotFoundURL = '/some/other/url'
{{< /code-toggle >}}
{{% include "_common/ref-and-relref-error-handling.md" %}}
content/en/methods/shortcode/Scratch.md
+5 -4
View File
@@ -3,10 +3,11 @@ title: Scratch
description: Returns a "scratch pad" to store and manipulate data, scoped to the current shortcode.
categories: []
keywords: []
action:
related: []
returnType: maps.Scratch
signatures: [SHORTCODE.Scratch]
params:
functions_and_methods:
related: []
returnType: maps.Scratch
signatures: [SHORTCODE.Scratch]
expiryDate: 2026-11-18 # deprecated 2024-11-18 (soft)
---
content/en/methods/shortcode/Site.md
+6 -5
View File
@@ -3,11 +3,12 @@ title: Site
description: Returns the Site object.
categories: []
keywords: []
action:
related:
- methods/page/Sites
returnType: page.siteWrapper
signatures: [SHORTCODE.Site]
params:
functions_and_methods:
related:
- methods/page/Sites
returnType: page.siteWrapper
signatures: [SHORTCODE.Site]
---
See [Site methods].
content/en/methods/shortcode/Store.md
+10 -10
View File
@@ -3,15 +3,15 @@ title: Store
description: Returns a "scratch pad" to store and manipulate data, scoped to the current shortcode.
categories: []
keywords: []
action:
related:
- methods/page/Store
- methods/site/Store
- functions/hugo/Store
- functions/collections/NewScratch
returnType: maps.Scratch
signatures: [SHORTCODE.Store]
toc: true
params:
functions_and_methods:
related:
- methods/page/Store
- methods/site/Store
- functions/hugo/Store
- functions/collections/NewScratch
returnType: maps.Scratch
signatures: [SHORTCODE.Store]
---
{{< new-in 0.139.0 />}}
@@ -21,7 +21,7 @@ Use the `Store` method to create a [scratch pad](g) to store and manipulate data
{{< note >}}
With the introduction of the [`newScratch`] function, and the ability to [assign values to template variables] after initialization, the `Store` method within a shortcode is mostly obsolete.
[assign values to template variables]: https://go.dev/doc/go1.11#text/template
[assign values to template variables]: https://go.dev/doc/go1.11#texttemplatepkgtexttemplate
[`newScratch`]: /functions/collections/newScratch/
{{< /note >}}
content/en/methods/shortcode/_index.md
-5
View File
@@ -4,10 +4,5 @@ linkTitle: Shortcode
description: Use these methods in your shortcode templates.
categories: []
keywords: []
menu:
docs:
parent: methods
aliases: [/variables/shortcodes]
---
Use these methods in your shortcode templates.