mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-21 21:35:28 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit '35dec7c96f7ee3eb17dd444f7067f0c776fb56ae'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2023-12-04 15:24:01 +01:00
parent 9f978d387f 35dec7c96f
commit d19ed4d4e6
810 changed files with 24147 additions and 7766 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/content/en/functions/transform/CanHighlight.md
View File

@@ -1,19 +1,15 @@
---
title: transform.CanHighlight
description: Reports whether the given code language is supported by the Chroma highlighter.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: []
related:
- functions/transform/Highlight
- functions/transform/HighlightCodeBlock
returnType: bool
signatures: [transform.CanHighlight LANGUAGE]
relatedFunctions:
- transform.CanHighlight
- transform.Highlight
- transform.HighlightCodeBlock
---
```go-html-template

23
docs/content/en/functions/transform/Emojify.md
View File

@@ -1,31 +1,30 @@
---
title: transform.Emojify
linkTitle: emojify
description: Runs a string through the Emoji emoticons processor.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [emojify]
related: []
returnType: template.HTML
signatures: [transform.Emojify INPUT]
namespace: transform
relatedFunctions: []
aliases: [/functions/emojify]
---
`emojify` runs a passed string through the Emoji emoticons processor.
See the [Emoji cheat sheet][emojis] for available emoticons.
See the list of [emoji shortcodes] for available emoticons.
The `emojify` function can be called in your templates but not directly in your content files by default. For emojis in content files, set `enableEmoji` to `true` in your site's [configuration]. Then you can write emoji shorthand directly into your content files; e.g. <code>I :</code><code>heart</code><code>: Hugo!</code>:
The `emojify` function can be called in your templates but not directly in your content files by default. For emojis in content files, set `enableEmoji` to `true` in your site's [configuration]. Then you can write emoji shorthand directly into your content files;
```text
I :heart: Hugo!
```
I :heart: Hugo!
[configuration]: /getting-started/configuration/
[emojis]: https://www.webfx.com/tools/emoji-cheat-sheet/
[emoji shortcodes]: /quick-reference/emojis/
[sc]: /templates/shortcode-templates/
[scsource]: https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes

30
docs/content/en/functions/transform/HTMLEscape.md
View File

@@ -1,24 +1,30 @@
---
title: transform.HTMLEscape
linkTitle: htmlEscape
description: Returns the given string with the reserved HTML codes escaped.
categories: [functions]
description: Returns the given string, escaping special characters by replacing them with HTML entities.
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [htmlEscape]
related:
- functions/transform/HTMLUnescape
returnType: string
signatures: [transform.HTMLEscape INPUT]
relatedFunctions:
- transform.HTMLEscape
- transform.HTMLUnescape
aliases: [/functions/htmlescape]
---
In the result `&` becomes `&amp;` and so on. It escapes only: `<`, `>`, `&`, `'` and `"`.
The `transform.HTMLEscape` function escapes five special characters by replacing them with [HTML entities]:
- `&` → `&amp;`
- `<` → `&lt;`
- `>` → `&gt;`
- `'` → `&#39;`
- `"` → `&#34;`
For example:
```go-html-template
{{ htmlEscape "Hugo & Caddy > WordPress & Apache" }} → "Hugo &amp; Caddy &gt; WordPress &amp; Apache"
{{ htmlEscape "Lilo & Stitch" }} → Lilo &amp; Stitch
{{ htmlEscape "7 > 6" }} → 7 &gt; 6
```
[html entities]: https://developer.mozilla.org/en-US/docs/Glossary/Entity

30
docs/content/en/functions/transform/HTMLUnescape.md
View File

@@ -1,24 +1,30 @@
---
title: transform.HTMLUnescape
linkTitle: htmlUnescape
description: Returns the given string with HTML escape codes un-escaped.
categories: [functions]
description: Returns the given string, replacing each HTML entity with its corresponding character.
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [htmlUnescape]
related:
- functions/transform/HTMLEscape
returnType: string
signatures: [transform.HTMLUnescape INPUT]
relatedFunctions:
- transform.HTMLEscape
- transform.HTMLUnescape
aliases: [/functions/htmlunescape]
---
Remember to pass the output of this to `safeHTML` if fully un-escaped characters are desired. Otherwise, the output will be escaped again as normal.
The `transform.HTMLUnescape` function replaces [HTML entities] with their corresponding characters.
```go-html-template
{{ htmlUnescape "Hugo &amp; Caddy &gt; WordPress &amp; Apache" }} → "Hugo & Caddy > WordPress & Apache"
{{ htmlUnescape "Lilo &amp; Stitch" }} → Lilo & Stitch
{{ htmlUnescape "7 &gt; 6" }} → 7 > 6
```
In most contexts Go's [html/template] package will escape special characters. To bypass this behavior, pass the unescaped string through the [`safeHTML`] function.
```go-html-template
{{ htmlUnescape "Lilo &amp; Stitch" | safeHTML }}
```
[`safehtml`]: /functions/safe/html
[html entities]: https://developer.mozilla.org/en-us/docs/glossary/entity
[html/template]: https://pkg.go.dev/html/template

28
docs/content/en/functions/transform/Highlight.md
View File

@@ -1,21 +1,15 @@
---
title: transform.Highlight
linkTitle: highlight
description: Renders code with a syntax highlighter.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [highlight]
related:
- functions/transform/CanHighlight
- functions/transform/HighlightCodeBlock
returnType: template.HTML
signatures: ['transform.Highlight INPUT LANG [OPTIONS]']
namespace: transform
relatedFunctions:
- transform.CanHighlight
- transform.Highlight
- transform.HighlightCodeBlock
aliases: [/functions/highlight]
toc: true
---
@@ -31,7 +25,7 @@ LANG
: The language of the code to highlight. Choose from one of the [supported languages]. Case-insensitive.
OPTIONS
: An optional, comma-separated list of zero or more [options]. Set default values in [site configuration].
: A map, or comma-separated list, of zero or more [options]. Set default values in [site configuration].
## Options
@@ -57,7 +51,7 @@ The number to display at the beginning of the first line. Irrelevant if `lineNos
hl_Lines
: String. Default is `""`.\
A space-separated list of lines to emphasize within the highlighted code. To emphasize lines 2, 3, 4, and 7, set this value to `2-4 7`. This option is independent of the `lineNoStart` option.
A space-delimited list of lines to emphasize within the highlighted code. To emphasize lines 2, 3, 4, and 7, set this value to `2-4 7`. This option is independent of the `lineNoStart` option.
hl_inline
: Boolean. Default is `false`.\
@@ -82,10 +76,10 @@ If the `LANG` argument is blank or an unrecognized language, auto-detect the lan
{{% note %}}
Instead of specifying both `lineNos` and `lineNumbersInTable`, you can use the following shorthand notation:
`lineNos=inline`
lineNos=inline
: equivalent to `lineNos=true` and `lineNumbersInTable=false`
`lineNos=table`
lineNos=table
: equivalent to `lineNos=true` and `lineNumbersInTable=true`
{{% /note %}}
@@ -101,8 +95,8 @@ Instead of specifying both `lineNos` and `lineNumbersInTable`, you can use the f
{{ $input := `echo "Hello World!"` }}
{{ $lang := "bash" }}
{{ $options := dict "lineNos" "table" "style" "dracula" }}
{{ transform.Highlight $input $lang $options }}
{{ $opts := dict "lineNos" "table" "style" "dracula" }}
{{ transform.Highlight $input $lang $opts }}
```
[Chroma]: https://github.com/alecthomas/chroma

19
docs/content/en/functions/transform/HighlightCodeBlock.md
View File

@@ -1,19 +1,15 @@
---
title: transform.HighlightCodeBlock
description: Highlights code received in context within a code block render hook.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: []
related:
- functions/transform/CanHighlight
- functions/transform/Highlight
returnType: highlight.HighlightResult
signatures: ['transform.HighlightCodeBlock CONTEXT [OPTIONS]']
relatedFunctions:
- transform.CanHighlight
- transform.Highlight
- transform.HighlightCodeBlock
---
This function is only useful within a code block render hook.
@@ -26,7 +22,6 @@ Given the context passed into a code block render hook, `transform.HighlightCode
.Inner
: (`template.HTML`) Returns highlighted code without any wrapping elements, allowing you to create your own wrapper.
```go-html-template
{{ $result := transform.HighlightCodeBlock . }}
{{ $result.Wrapped }}
@@ -35,8 +30,8 @@ Given the context passed into a code block render hook, `transform.HighlightCode
To override the default [highlighting options]:
```go-html-template
{{ $options := merge .Options (dict "linenos" true) }}
{{ $result := transform.HighlightCodeBlock . $options }}
{{ $opts := merge .Options (dict "linenos" true) }}
{{ $result := transform.HighlightCodeBlock . $opts }}
{{ $result.Wrapped }}
```

22
docs/content/en/functions/transform/Markdownify.md
View File

@@ -1,34 +1,30 @@
---
title: transform.Markdownify
linkTitle: markdownify
description: Renders markdown to HTML.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [markdownify]
related:
- methods/page/RenderString
- methods/page/RenderShortcodes
returnType: template.HTML
signatures: [transform.Markdownify INPUT]
relatedFunctions: []
aliases: [/functions/markdownify]
---
```go-html-template
{{ .Title | markdownify }}
<h2>{{ .Title | markdownify }}</h2>
```
If the resulting HTML is a single paragraph, Hugo removes the wrapping `p` tags to produce inline HTML as required per the example above.
To keep the wrapping `p` tags for a single paragraph, use the [`.Page.RenderString`] method, setting the `display` option to `block`.
To keep the wrapping `p` tags for a single paragraph, use the [`RenderString`] method on the `Page` object, setting the `display` option to `block`.
If the resulting HTML is two or more paragraphs, Hugo leaves the wrapping `p` tags in place.
[`.Page.RenderString`]: /functions/renderstring/
[`RenderString`]: /methods/page/renderstring/
{{% note %}}
Although the `markdownify` function honors [markdown render hooks] when rendering markdown to HTML, use the `.Page.RenderString` method instead of `markdownify` if a render hook accesses `.Page` context. See issue [#9692] for details.
Although the `markdownify` function honors [markdown render hooks] when rendering markdown to HTML, use the `RenderString` method instead of `markdownify` if a render hook accesses `.Page` context. See issue [#9692] for details.
[markdown render hooks]: /templates/render-hooks/
[#9692]: https://github.com/gohugoio/hugo/issues/9692

16
docs/content/en/functions/transform/Plainify.md
View File

@@ -1,24 +1,16 @@
---
title: transform.Plainify
linkTitle: plainify
description: Returns a string with all HTML tags removed.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [plainify]
related: []
returnType: string
signatures: [transform.Plainify INPUT]
relatedFunctions: []
aliases: [/functions/plainify]
---
```go-html-template
{{ "<b>BatMan</b>" | plainify }} → "BatMan"
{{ "<b>BatMan</b>" | plainify }} → BatMan
```
See also the `.PlainWords`, `.Plain`, and `.RawContent` [page variables][pagevars].
[pagevars]: /variables/page/

16
docs/content/en/functions/transform/Remarshal.md
View File

@@ -1,23 +1,19 @@
---
title: transform.Remarshal
description: Marshals a string of serialized data, or a map, into a string of serialized data in the specified format.
categories: [functions]
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: []
related:
- functions/encoding/Jsonify
- functions/transform/Unmarshal
returnType: string
signatures: [transform.Remarshal FORMAT INPUT]
relatedFunctions:
- encoding.Jsonify
- transform.Remarshal
- transform.Unmarshal
aliases: [/functions/transform.remarshal]
---
The FORMAT must be one of `json`, `toml`, `yaml`, or `xml`. If the INPUT is a string of serialized data, it must be valid JSON, TOML, YAML, or XML.
The format must be one of `json`, `toml`, `yaml`, or `xml`. If the input is a string of serialized data, it must be valid JSON, TOML, YAML, or XML.
{{% note %}}
This function is primarily a helper for Hugo's documentation, used to convert configuration and front matter examples to JSON, TOML, and YAML.

292
docs/content/en/functions/transform/Unmarshal.md
View File

@@ -1,83 +1,289 @@
---
title: transform.Unmarshal
description: Parses the input and converts it into a map or an array. Supported formats are JSON, TOML, YAML, XML and CSV.
categories: [functions]
description: Parses serialized data and returns a map or an array. Supports CSV, JSON, TOML, YAML, and XML.
categories: []
keywords: []
menu:
docs:
parent: functions
function:
action:
aliases: [unmarshal]
related:
- functions/transform/Remarshal
- functions/resources/Get
- functions/resources/GetRemote
- functions/encoding/Jsonify
returnType: any
signatures:
- RESOURCE or STRING | transform.Unmarshal [OPTIONS]
- RESOURCE or STRING | unmarshal [OPTIONS]
relatedFunctions:
- encoding.Jsonify
- transform.Remarshal
- transform.Unmarshal
signatures: ['transform.Unmarshal [OPTIONS] INPUT']
toc: true
aliases: [/functions/transform.unmarshal]
---
The function accepts either a `Resource` created in [Hugo Pipes](/hugo-pipes/) or via [Page Bundles](/content-management/page-bundles/), or simply a string. The two examples below will produce the same map:
The input can be a string or a [resource].
## Unmarshal a string
```go-html-template
{{ $greetings := "hello = \"Hello Hugo\"" | transform.Unmarshal }}`
{{ $string := `
title: Les Misérables
author: Victor Hugo
`}}
{{ $book := unmarshal $string }}
{{ $book.title }} → Les Misérables
{{ $book.author }} → Victor Hugo
```
## Unmarshal a resource
Use the `transform.Unmarshal` function with global, page, and remote resources.
### Global resource
A global resource is a file within the assets directory, or within any directory mounted to the assets directory.
```text
assets/
└── data/
└── books.json
```
```go-html-template
{{ $greetings := "hello = \"Hello Hugo\"" | resources.FromString "data/greetings.toml" | transform.Unmarshal }}
{{ $data := "" }}
{{ $path := "data/books.json" }}
{{ with resources.Get $path }}
{{ with unmarshal . }}
{{ $data = . }}
{{ end }}
{{ else }}
{{ errorf "Unable to get global resource %q" $path }}
{{ end }}
{{ range where $data "author" "Victor Hugo" }}
{{ .title }} → Les Misérables
{{ end }}
```
In both the above examples, you get a map you can work with:
### Page resource
A page resource is a file within a [page bundle].
```text
content/
├── post/
│ └── book-reviews/
│ ├── books.json
│ └── index.md
└── _index.md
```
```go-html-template
{{ $greetings.hello }}
{{ $data := "" }}
{{ $path := "books.json" }}
{{ with .Resources.Get $path }}
{{ with unmarshal . }}
{{ $data = . }}
{{ end }}
{{ else }}
{{ errorf "Unable to get page resource %q" $path }}
{{ end }}
{{ range where $data "author" "Victor Hugo" }}
{{ .title }} → Les Misérables
{{ end }}
```
The above prints `Hello Hugo`.
### Remote resource
## CSV options
A remote resource is a file on a remote server, accessible via HTTP or HTTPS.
Unmarshal with CSV as input has some options you can set:
```go-html-template
{{ $data := "" }}
{{ $url := "https://example.org/books.json" }}
{{ with resources.GetRemote $url }}
{{ with .Err }}
{{ errorf "%s" . }}
{{ else }}
{{ $data = . | transform.Unmarshal }}
{{ end }}
{{ else }}
{{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
{{ range where $data "author" "Victor Hugo" }}
{{ .title }} → Les Misérables
{{ end }}
```
[resource]: /getting-started/glossary/#resource
[page bundle]: /content-management/page-bundles
## Options
When unmarshaling a CSV file, provide an optional map of options.
delimiter
: The delimiter used, default is `,`.
: (`string`) The delimiter used, default is `,`.
comment
: The comment character used in the CSV. If set, lines beginning with the comment character without preceding whitespace are ignored.:
Example:
: (`string`) The comment character used in the CSV. If set, lines beginning with the comment character without preceding whitespace are ignored.
```go-html-template
{{ $csv := "a;b;c" | transform.Unmarshal (dict "delimiter" ";") }}
```
## XML data
## Working with XML
As a convenience, Hugo allows you to access XML data in the same way that you access JSON, TOML, and YAML: you do not need to specify the root node when accessing the data.
To get the contents of `<title>` in the document below, you use `{{ .message.title }}`:
When unmarshaling an XML file, do not include the root node when accessing data. For example, after unmarshaling the RSS feed below, access the feed title with `$data.channel.title`.
```xml
<root>
<message>
<title>Hugo rocks!</title>
<description>Thanks for using Hugo</description>
</message>
</root>
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
<channel>
<title>Books on Example Site</title>
<link>https://example.org/books/</link>
<description>Recent content in Books on Example Site</description>
<language>en-US</language>
<atom:link href="https://example.org/books/index.xml" rel="self" type="application/rss+xml" />
<item>
<title>The Hunchback of Notre Dame</title>
<description>Written by Victor Hugo</description>
<link>https://example.org/books/the-hunchback-of-notre-dame/</link>
<pubDate>Mon, 09 Oct 2023 09:27:12 -0700</pubDate>
<guid>https://example.org/books/the-hunchback-of-notre-dame/</guid>
</item>
<item>
<title>Les Misérables</title>
<description>Written by Victor Hugo</description>
<link>https://example.org/books/les-miserables/</link>
<pubDate>Mon, 09 Oct 2023 09:27:11 -0700</pubDate>
<guid>https://example.org/books/les-miserables/</guid>
</item>
</channel>
</rss>
```
The following example lists the items of an RSS feed:
Get the remote data:
```go-html-template
{{ with resources.GetRemote "https://example.com/rss.xml" | transform.Unmarshal }}
{{ range .channel.item }}
<strong>{{ .title | plainify | htmlUnescape }}</strong><br>
<p>{{ .description | plainify | htmlUnescape }}</p>
{{ $link := .link | plainify | htmlUnescape }}
<a href="{{ $link }}">{{ $link }}</a><br>
<hr>
{{ $data := "" }}
{{ $url := "https://example.org/books/index.xml" }}
{{ with resources.GetRemote $url }}
{{ with .Err }}
{{ errorf "%s" . }}
{{ else }}
{{ $data = . | transform.Unmarshal }}
{{ end }}
{{ else }}
{{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
```
Inspect the data structure:
```go-html-template
<pre>{{ jsonify (dict "indent" " ") $data }}</pre>
```
List the book titles:
```go-html-template
{{ with $data.channel.item }}
<ul>
{{ range . }}
<li>{{ .title }}</li>
{{ end }}
</ul>
{{ end }}
```
Hugo renders this to:
```html
<ul>
<li>The Hunchback of Notre Dame</li>
<li>Les Misérables</li>
</ul>
```
### XML attributes and namespaces
Let's add a `lang` attribute to the `title` nodes of our RSS feed, and a namespaced node for the ISBN number:
```xml
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rss version="2.0"
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:isbn="http://schemas.isbn.org/ns/1999/basic.dtd"
>
<channel>
<title>Books on Example Site</title>
<link>https://example.org/books/</link>
<description>Recent content in Books on Example Site</description>
<language>en-US</language>
<atom:link href="https://example.org/books/index.xml" rel="self" type="application/rss+xml" />
<item>
<title lang="fr">The Hunchback of Notre Dame</title>
<description>Written by Victor Hugo</description>
<isbn:number>9780140443530</isbn:number>
<link>https://example.org/books/the-hunchback-of-notre-dame/</link>
<pubDate>Mon, 09 Oct 2023 09:27:12 -0700</pubDate>
<guid>https://example.org/books/the-hunchback-of-notre-dame/</guid>
</item>
<item>
<title lang="en">Les Misérables</title>
<description>Written by Victor Hugo</description>
<isbn:number>9780451419439</isbn:number>
<link>https://example.org/books/les-miserables/</link>
<pubDate>Mon, 09 Oct 2023 09:27:11 -0700</pubDate>
<guid>https://example.org/books/les-miserables/</guid>
</item>
</channel>
</rss>
```
After retrieving the remote data, inspect the data structure:
```go-html-template
<pre>{{ jsonify (dict "indent" " ") $data }}</pre>
```
Each item node looks like this:
```json
{
"description": "Written by Victor Hugo",
"guid": "https://example.org/books/the-hunchback-of-notre-dame/",
"link": "https://example.org/books/the-hunchback-of-notre-dame/",
"number": "9780140443530",
"pubDate": "Mon, 09 Oct 2023 09:27:12 -0700",
"title": {
"#text": "The Hunchback of Notre Dame",
"-lang": "fr"
}
}
```
The title keys do not begin with an underscore or a letter---they are not valid [identifiers]. Use the [`index`] function to access the values:
```go-html-template
{{ with $data.channel.item }}
<ul>
{{ range . }}
{{ $title := index .title "#text" }}
{{ $lang := index .title "-lang" }}
{{ $ISBN := .number }}
<li>{{ $title }} ({{ $lang }}) {{ $ISBN }}</li>
{{ end }}
</ul>
{{ end }}
```
Hugo renders this to:
```html
<ul>
<li>The Hunchback of Notre Dame (fr) 9780140443530</li>
<li>Les Misérables (en) 9780451419439</li>
</ul>
```
[`index`]: /functions/collections/indexfunction
[identifiers]: https://go.dev/ref/spec#Identifiers

12
docs/content/en/functions/transform/_index.md Normal file
View File

@@ -0,0 +1,12 @@
---
title: Transform functions
linkTitle: transform
description: Template functions to transform values from one format to another.
categories: []
keywords: []
menu:
docs:
parent: functions
---
Use these functions to transform values from one format to another.