TheCloud/hugoDocs
1
0
Fork 0
mirror of https://github.com/gohugoio/hugoDocs.git synced 2025-09-13 16:27:15 -04:00
Code Issues Packages Projects Releases Wiki Activity

Update pages describing Store methods and functions

Browse Source
This commit is contained in:
Joe Mooring 2025-01-30 02:26:10 -08:00 committed by GitHub
parent fa7643d1be
commit 6a7fd42ff7
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
19 changed files with 172 additions and 255 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
content/en/_common/_index.md Normal file
View File

@ -0,0 +1,13 @@
---
cascade:
_build:
list: never
publishResources: false
render: never
---
<!--
Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
Include the rendered content using the "include" shortcode.
-->

21
content/en/_common/scratch-pad-scope.md Normal file
View File

@ -0,0 +1,21 @@
---
_comment: Do not remove front matter.
---
## Scope
The method or function used to create a scratch pad determines its scope. For example, use the `Store` method on a `Page` object to create a scratch pad scoped to the page.
Scope|Method or function
:--|:--
page|[`PAGE.Store`]
site|[`SITE.Store`]
global|[`hugo.Store`]
local|[`collections.NewScratch`]
shortcode|[`SHORTCODE.Store`]
[`page.store`]: /methods/page/store
[`site.store`]: /methods/site/store
[`hugo.store`]: /functions/hugo/store
[`collections.newscratch`]: functions/collections/newscratch
[`shortcode.store`]: /methods/shortcode/store

86
content/en/_common/store-methods.md Normal file
View File

@ -0,0 +1,86 @@
---
# Do not remove front matter.
---
## Methods
###### Set
Sets the value of the given key.
```go-html-template
{{ .Store.Set "greeting" "Hello" }}
```
###### Get
Gets the value of the given key.
```go-html-template
{{ .Store.Set "greeting" "Hello" }}
{{ .Store.Get "greeting" }} → Hello
```
###### Add
Adds the given value to the existing value(s) of the given key.
For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list.
```go-html-template
{{ .Store.Set "greeting" "Hello" }}
{{ .Store.Add "greeting" "Welcome" }}
{{ .Store.Get "greeting" }} → HelloWelcome
```
```go-html-template
{{ .Store.Set "total" 3 }}
{{ .Store.Add "total" 7 }}
{{ .Store.Get "total" }} → 10
```
```go-html-template
{{ .Store.Set "greetings" (slice "Hello") }}
{{ .Store.Add "greetings" (slice "Welcome" "Cheers") }}
{{ .Store.Get "greetings" }} → [Hello Welcome Cheers]
```
###### SetInMap
Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`.
```go-html-template
{{ .Store.SetInMap "greetings" "english" "Hello" }}
{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
{{ .Store.Get "greetings" }} → map[english:Hello french:Bonjour]
```
###### DeleteInMap
Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
```go-html-template
{{ .Store.SetInMap "greetings" "english" "Hello" }}
{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
{{ .Store.DeleteInMap "greetings" "english" }}
{{ .Store.Get "greetings" }} → map[french:Bonjour]
```
###### GetSortedMapValues
Returns an array of values from `key` sorted by `mapKey`.
```go-html-template
{{ .Store.SetInMap "greetings" "english" "Hello" }}
{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
{{ .Store.GetSortedMapValues "greetings" }} → [Hello Bonjour]
```
###### Delete
Removes the given key.
```go-html-template
{{ .Store.Set "greeting" "Hello" }}
{{ .Store.Delete "greeting" }}
```

1
content/en/contribute/documentation.md
View File

@ -79,6 +79,7 @@ Please link to the [glossary of terms] when necessary, and use the terms consist
- The term "standalone" is one word, not hyphenated
- Use the word "map" instead of "dictionary"
- Use the word "flag" instead of "option" when referring to a command line flag
- Use "client side" as a noun, and "client-side" as an adjective
- Capitalize the word "Markdown"
- Hyphenate the term "open-source" when used an adjective.

21
content/en/functions/collections/NewScratch.md
View File

@ -6,23 +6,22 @@ keywords: []
action:
aliases: [newScratch]
related:
- methods/page/scratch
- methods/page/store
- methods/shortcode/scratch
- methods/page/Store
- methods/site/Store
- methods/shortcode/Store
- functions/hugo/Store
returnType: maps.Scratch
signatures: [collections.NewScratch ]
toc: true
---
The `collections.NewScratch` function creates a locally scoped [scratch pad](g) to store and manipulate data. To create a scratch pad that is attached to a `Page` object, use the [`Scratch`] or [`Store`] method.
[`Scratch`]: /methods/page/scratch/
[`Store`]: /methods/page/store/
Use the `collections.NewScratch` function to create a locally scoped [scratch pad](g) to store and manipulate data. To create a scratch pad with a different [scope](g), refer to the [scope](#scope) section below.
## Methods
###### Set
Sets the value of a given key.
Sets the value of the given key.
```go-html-template
{{ $s := newScratch }}
@ -31,7 +30,7 @@ Sets the value of a given key.
###### Get
Gets the value of a given key.
Gets the value of the given key.
```go-html-template
{{ $s := newScratch }}
@ -41,7 +40,7 @@ Gets the value of a given key.
###### Add
Adds a given value to existing value(s) of the given key.
Adds the given value to existing value(s) of the given key.
For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list.
@ -121,3 +120,5 @@ Returns the raw backing map. Do not use with `Scratch` or `Store` methods on a `
{{ $map := $s.Values }}
```
{{% include "_common/scratch-pad-scope.md" %}}

22
content/en/functions/hugo/Store.md
View File

@ -1,13 +1,14 @@
---
title: hugo.Store
description: Returns a global, persistent "scratch pad" to store and manipulate data.
description: Returns a globally scoped "scratch pad" to store and manipulate data.
categories: []
keywords: []
action:
related:
- methods/page/store
- methods/site/store
- functions/collections/NewScratch
- methods/page/Store
- methods/site/Store
- methods/shortcode/Store
- functions/collections/NewScratch
returnType: maps.Scratch
signatures: [hugo.Store]
toc: true
@ -15,16 +16,13 @@ toc: true
{{< new-in 0.139.0 >}}
The global `hugo.Store` function creates a persistent [scratch pad](g) to store and manipulate data. To create a locally scoped, use the [`newScratch`] function.
[`Scratch`]: /functions/hugo/scratch/
[`newScratch`]: /functions/collections/newscratch/
Use the `hugo.Store` function to create a globally scoped [scratch pad](g) to store and manipulate data. To create a scratch pad with a different [scope](g), refer to the [scope](#scope) section below.
## Methods
###### Set
Sets the value of a given key.
Sets the value of the given key.
```go-html-template
{{ hugo.Store.Set "greeting" "Hello" }}
@ -32,7 +30,7 @@ Sets the value of a given key.
###### Get
Gets the value of a given key.
Gets the value of the given key.
```go-html-template
{{ hugo.Store.Set "greeting" "Hello" }}
@ -41,7 +39,7 @@ Gets the value of a given key.
###### Add
Adds a given value to existing value(s) of the given key.
Adds the given value to the existing value(s) of the given key.
For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list.
@ -103,6 +101,8 @@ Removes the given key.
{{ hugo.Store.Delete "greeting" }}
```
{{% include "_common/scratch-pad-scope.md" %}}
## Determinate values
The `Store` method is often used to set scratch pad values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.

1
content/en/functions/resources/Babel.md
View File

@ -7,7 +7,6 @@ action:
related: []
returnType: resource.Resource
signatures: ['resources.Babel [OPTIONS] RESOURCE']
toc: true
expiryDate: 2025-06-24 # deprecated 2024-06-24
---

1
content/en/functions/resources/PostCSS.md
View File

@ -7,7 +7,6 @@ action:
related: []
returnType: resource.Resource
signatures: ['resources.PostCSS [OPTIONS] RESOURCE']
toc: true
expiryDate: 2025-06-24 # deprecated 2024-06-24
---

1
content/en/functions/resources/ToCSS.md
View File

@ -7,7 +7,6 @@ action:
related: []
returnType: resource.Resource
signatures: ['resources.ToCSS [OPTIONS] RESOURCE']
toc: true
expiryDate: 2025-06-24 # deprecated 2024-06-24
---

5
content/en/getting-started/glossary/scope.md Normal file
View File

@ -0,0 +1,5 @@
---
title: scope
---
The term _scope_ refers to the specific region of code where a [_variable_](g) or [_object_](g) is accessible. For example, a variable initialized in one template is not available within another.

29
content/en/methods/page/Scratch.md
View File

@ -7,8 +7,6 @@ action:
related: []
returnType: maps.Scratch
signatures: [PAGE.Scratch]
toc: true
aliases: [/extras/scratch/,/doc/scratch/,/functions/scratch]
expiryDate: 2025-11-18 # deprecated 2024-11-18
---
@ -21,30 +19,3 @@ Beginning with v0.138.0 the `PAGE.Scratch` method is aliased to `PAGE.Store`.
[`PAGE.Store`]: /methods/page/store/
{{% /deprecated-in %}}
The `Scratch` method on a `Page` object creates a [scratch pad](g) to store and manipulate data. To create a scratch pad that is not reset on server rebuilds, use the [`Store`] method instead.
To create a locally scoped scratch pad that is not attached to a `Page` object, use the [`newScratch`] function.
[`Store`]: /methods/page/store/
[`newScratch`]: /functions/collections/newscratch/
{{% include "methods/page/_common/scratch-methods.md" %}}
## Determinate values
The `Scratch` method is often used to set scratch pad values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.
If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop](g) variable:
```go-html-template
{{ $noop := .Content }}
{{ .Store.Get "mykey" }}
```
You can also trigger content rendering with the `ContentWithoutSummary`, `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount` methods. For example:
```go-html-template
{{ $noop := .WordCount }}
{{ .Store.Get "mykey" }}
```

101
content/en/methods/page/Store.md
View File

@ -1,108 +1,25 @@
---
title: Store
linktitle: PAGE.Store
description: Returns a persistent "scratch pad" on the given page to store and manipulate data.
description: Returns a "scratch pad" to store and manipulate data, scoped to the current page.
categories: []
keywords: []
action:
related:
- methods/page/scratch
- methods/site/store
- functions/hugo/store
- functions/collections/NewScratch
- methods/site/Store
- methods/shortcode/Store
- functions/hugo/Store
- functions/collections/NewScratch
returnType: maps.Scratch
signatures: [PAGE.Store]
toc: true
aliases: [/functions/store]
aliases: [/functions/store/,/extras/scratch/,/doc/scratch/,/functions/scratch]
---
The `Store` method on a `Page` object creates a persistent [scratch pad](g) to store and manipulate data. To create a locally scoped scratch pad that is not attached to a `Page` object, use the [`newScratch`] function.
Use the `Store` method on a `Page` object to create a [scratch pad](g) to store and manipulate data, scoped to the current page. To create a scratch pad with a different [scope](g), refer to the [scope](#scope) section below.
[`Scratch`]: /methods/page/scratch/
[`newScratch`]: /functions/collections/newscratch/
{{% include "_common/store-methods.md" %}}
## Methods
###### Set
Sets the value of a given key.
```go-html-template
{{ .Store.Set "greeting" "Hello" }}
```
###### Get
Gets the value of a given key.
```go-html-template
{{ .Store.Set "greeting" "Hello" }}
{{ .Store.Get "greeting" }} → Hello
```
###### Add
Adds a given value to existing value(s) of the given key.
For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list.
```go-html-template
{{ .Store.Set "greeting" "Hello" }}
{{ .Store.Add "greeting" "Welcome" }}
{{ .Store.Get "greeting" }} → HelloWelcome
```
```go-html-template
{{ .Store.Set "total" 3 }}
{{ .Store.Add "total" 7 }}
{{ .Store.Get "total" }} → 10
```
```go-html-template
{{ .Store.Set "greetings" (slice "Hello") }}
{{ .Store.Add "greetings" (slice "Welcome" "Cheers") }}
{{ .Store.Get "greetings" }} → [Hello Welcome Cheers]
```
###### SetInMap
Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`.
```go-html-template
{{ .Store.SetInMap "greetings" "english" "Hello" }}
{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
{{ .Store.Get "greetings" }} → map[english:Hello french:Bonjour]
```
###### DeleteInMap
Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
```go-html-template
{{ .Store.SetInMap "greetings" "english" "Hello" }}
{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
{{ .Store.DeleteInMap "greetings" "english" }}
{{ .Store.Get "greetings" }} → map[french:Bonjour]
```
###### GetSortedMapValues
Returns an array of values from `key` sorted by `mapKey`.
```go-html-template
{{ .Store.SetInMap "greetings" "english" "Hello" }}
{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
{{ .Store.GetSortedMapValues "greetings" }} → [Hello Bonjour]
```
###### Delete
Removes the given key.
```go-html-template
{{ .Store.Set "greeting" "Hello" }}
{{ .Store.Delete "greeting" }}
```
{{% include "_common/scratch-pad-scope.md" %}}
## Determinate values

86
content/en/methods/page/_common/scratch-methods.md
View File

@ -1,86 +0,0 @@
---
_comment: Do not remove front matter.
---
## Methods
###### Set
Sets the value of a given key.
```go-html-template
{{ .Scratch.Set "greeting" "Hello" }}
```
###### Get
Gets the value of a given key.
```go-html-template
{{ .Scratch.Set "greeting" "Hello" }}
{{ .Scratch.Get "greeting" }} → Hello
```
###### Add
Adds a given value to existing value(s) of the given key.
For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list.
```go-html-template
{{ .Scratch.Set "greeting" "Hello" }}
{{ .Scratch.Add "greeting" "Welcome" }}
{{ .Scratch.Get "greeting" }} → HelloWelcome
```
```go-html-template
{{ .Scratch.Set "total" 3 }}
{{ .Scratch.Add "total" 7 }}
{{ .Scratch.Get "total" }} → 10
```
```go-html-template
{{ .Scratch.Set "greetings" (slice "Hello") }}
{{ .Scratch.Add "greetings" (slice "Welcome" "Cheers") }}
{{ .Scratch.Get "greetings" }} → [Hello Welcome Cheers]
```
###### SetInMap
Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`.
```go-html-template
{{ .Scratch.SetInMap "greetings" "english" "Hello" }}
{{ .Scratch.SetInMap "greetings" "french" "Bonjour" }}
{{ .Scratch.Get "greetings" }} → map[english:Hello french:Bonjour]
```
###### DeleteInMap
Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
```go-html-template
{{ .Scratch.SetInMap "greetings" "english" "Hello" }}
{{ .Scratch.SetInMap "greetings" "french" "Bonjour" }}
{{ .Scratch.DeleteInMap "greetings" "english" }}
{{ .Scratch.Get "greetings" }} → map[french:Bonjour]
```
###### GetSortedMapValues
Returns an array of values from `key` sorted by `mapKey`.
```go-html-template
{{ .Scratch.SetInMap "greetings" "english" "Hello" }}
{{ .Scratch.SetInMap "greetings" "french" "Bonjour" }}
{{ .Scratch.GetSortedMapValues "greetings" }} → [Hello Bonjour]
```
###### Delete
Removes the given key.
```go-html-template
{{ .Scratch.Set "greeting" "Hello" }}
{{ .Scratch.Delete "greeting" }}
```

11
content/en/methods/shortcode/Scratch.md
View File

@ -19,14 +19,3 @@ Beginning with v0.139.0 the `SHORTCODE.Scratch` method is aliased to `SHORTCODE.
[`SHORTCODE.Store`]: /methods/shortcode/store/
{{% /deprecated-in %}}
The `Scratch` method within a shortcode creates a [scratch pad](g) to store and manipulate data. The scratch pad is scoped to the shortcode.
{{% 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 template variables]: https://go.dev/doc/go1.11#text/template
[`newScratch`]: /functions/collections/newscratch/
{{% /note %}}
{{% include "methods/page/_common/scratch-methods.md" %}}

13
content/en/methods/shortcode/Store.md
View File

@ -1,21 +1,22 @@
---
title: Store
description: Returns a "Store pad" scoped to the shortcode to store and manipulate data.
description: Returns a "scratch pad" to store and manipulate data, scoped to the current shortcode.
categories: []
keywords: []
action:
related:
- functions/collections/NewScratch
- methods/page/Store
- methods/site/Store
- functions/hugo/Store
returnType: maps.Store
- functions/collections/NewScratch
returnType: maps.Scratch
signatures: [SHORTCODE.Store]
toc: true
---
{{< new-in 0.139.0 >}}
The `Store` method within a shortcode creates a [scratch pad](g) to store and manipulate data. The scratch pad is scoped to the shortcode.
Use the `Store` method to create a [scratch pad](g) to store and manipulate data, scoped to the current shortcode. To create a scratch pad with a different [scope](g), refer to the [scope](#scope) section below.
{{% 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.
@ -24,4 +25,6 @@ With the introduction of the [`newScratch`] function, and the ability to [assign
[`newScratch`]: /functions/collections/newScratch/
{{% /note %}}
{{% include "methods/page/_common/scratch-methods.md" %}}
{{% include "_common/store-methods.md" %}}
{{% include "_common/scratch-pad-scope.md" %}}

1
content/en/methods/shortcode/_index.md
View File

@ -7,6 +7,7 @@ keywords: []
menu:
docs:
parent: methods
aliases: [/variables/shortcodes]
---
Use these methods in your shortcode templates.

10
content/en/methods/site/Store.md
View File

@ -1,7 +1,6 @@
---
title: Store
linktitle: site.Store
description: Returns a persistent "scratch pad" on the given site to store and manipulate data.
description: Returns a "scratch pad" to store and manipulate data, scoped to the current site.
categories: []
keywords: []
action:
@ -16,10 +15,7 @@ toc: true
{{< new-in 0.139.0 >}}
The `Store` method on a `Site` object creates a persistent [scratch pad](g) to store and manipulate data. To create a locally scoped scratch pad that is not attached to a `Site` object, use the [`newScratch`] function.
[`Scratch`]: /methods/site/scratch/
[`newScratch`]: /functions/collections/newscratch/
Use the `Store` method on a `Site` object to create a [scratch pad](g) to store and manipulate data, scoped to the current site. To create a scratch pad with a different [scope](g), refer to the [scope](#scope) section below.
## Methods
@ -104,6 +100,8 @@ Removes the given key.
{{ site.Store.Delete "greeting" }}
```
{{% include "_common/scratch-pad-scope.md" %}}
## Determinate values
The `Store` method is often used to set scratch pad values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.

2
content/en/tools/search.md
View File

@ -29,7 +29,7 @@ A static website with a dynamic search function? Yes, Hugo provides an alternati
: A bit like Hugo-lunr, but Hugo-lunr-zh can help you separate the Chinese keywords.
[GitHub Gist for Fuse.js integration](https://gist.github.com/eddiewebb/735feb48f50f0ddd65ae5606a1cb41ae)
: This gist demonstrates how to leverage Hugo's existing build time processing to generate a searchable JSON index used by [Fuse.js](https://fusejs.io/) on the client-side. Although this gist uses Fuse.js for fuzzy matching, any client-side search tool capable of reading JSON indexes will work. Does not require npm, grunt, or other build-time tools except Hugo!
: This gist demonstrates how to leverage Hugo's existing build time processing to generate a searchable JSON index used by [Fuse.js](https://fusejs.io/) on the client side. Although this gist uses Fuse.js for fuzzy matching, any client-side search tool capable of reading JSON indexes will work. Does not require npm, grunt, or other build-time tools except Hugo!
[hugo-search-index](https://www.npmjs.com/package/hugo-search-index)
: A library containing Gulp tasks and a prebuilt browser script that implements search. Gulp generates a search index from project Markdown files.