mirrors/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-04-29 07:00:31 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Merge commit 'e509cac533'

Browse source
This commit is contained in:
Bjørn Erik Pedersen 2023-10-20 09:43:56 +02:00
commit e2dd4cd05f
No known key found for this signature in database
GPG key ID: 330E6E2BD4859D8F
298 changed files with 4568 additions and 1991 deletions
Download patch file Download diff file Expand all files Collapse all files

22
docs/content/en/functions/transform/CanHighlight.md Normal file
View file

@ -0,0 +1,22 @@
---
title: transform.CanHighlight
description: Reports whether the given code language is supported by the Chroma highlighter.
categories: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: []
returnType: bool
signatures: [transform.CanHighlight LANGUAGE]
relatedFunctions:
- transform.CanHighlight
- transform.Highlight
- transform.HighlightCodeBlock
---
```go-html-template
{{ transform.CanHighlight "go" }} → true
{{ transform.CanHighlight "klingon" }} → false
```

31
docs/content/en/functions/transform/Emojify.md Normal file
View file

@ -0,0 +1,31 @@
---
title: transform.Emojify
linkTitle: emojify
description: Runs a string through the Emoji emoticons processor.
categories: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: [emojify]
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.
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>:
I :heart: Hugo!
[configuration]: /getting-started/configuration/
[emojis]: https://www.webfx.com/tools/emoji-cheat-sheet/
[sc]: /templates/shortcode-templates/
[scsource]: https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes

24
docs/content/en/functions/transform/HTMLEscape.md Normal file
View file

@ -0,0 +1,24 @@
---
title: transform.HTMLEscape
linkTitle: htmlEscape
description: Returns the given string with the reserved HTML codes escaped.
categories: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: [htmlEscape]
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 `"`.
```go-html-template
{{ htmlEscape "Hugo & Caddy > WordPress & Apache" }} → "Hugo &amp; Caddy &gt; WordPress &amp; Apache"
```

24
docs/content/en/functions/transform/HTMLUnescape.md Normal file
View file

@ -0,0 +1,24 @@
---
title: transform.HTMLUnescape
linkTitle: htmlUnescape
description: Returns the given string with HTML escape codes un-escaped.
categories: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: [htmlUnescape]
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.
```go-html-template
{{ htmlUnescape "Hugo &amp; Caddy &gt; WordPress &amp; Apache" }} → "Hugo & Caddy > WordPress & Apache"
```

113
docs/content/en/functions/transform/Highlight.md Normal file
View file

@ -0,0 +1,113 @@
---
title: transform.Highlight
linkTitle: highlight
description: Renders code with a syntax highlighter.
categories: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: [highlight]
returnType: template.HTML
signatures: ['transform.Highlight INPUT LANG [OPTIONS]']
namespace: transform
relatedFunctions:
- transform.CanHighlight
- transform.Highlight
- transform.HighlightCodeBlock
aliases: [/functions/highlight]
toc: true
---
The `highlight` function uses the [Chroma] syntax highlighter, supporting over 200 languages with more than 40 available styles.
## Arguments
INPUT
: The code to highlight.
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].
## Options
lineNos
: Boolean. Default is `false`.\
Display a number at the beginning of each line.
lineNumbersInTable
: Boolean. Default is `true`.\
Render the highlighted code in an HTML table with two cells. The left table cell contains the line numbers. The right table cell contains the code, allowing a user to select and copy the code without line numbers. Irrelevant if `lineNos` is `false`.
anchorLineNos
: Boolean. Default is `false`.\
Render each line number as an HTML anchor element, and set the `id` attribute of the surrounding `<span>` to the line number. Irrelevant if `lineNos` is `false`.
lineAnchors
: String. Default is `""`.\
When rendering a line number as an HTML anchor element, prepend this value to the `id` attribute of the surrounding `<span>`. This provides unique `id` attributes when a page contains two or more code blocks. Irrelevant if `lineNos` or `anchorLineNos` is `false`.
lineNoStart
: Integer. Default is `1`.\
The number to display at the beginning of the first line. Irrelevant if `lineNos` is `false`.
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.
hl_inline
: Boolean. Default is `false`.\
Render the highlighted code without a wrapping container.
style
: String. Default is `monokai`.\
The CSS styles to apply to the highlighted code. See the [style gallery] for examples. Case-sensitive.
noClasses
: Boolean. Default is `true`.\
Use inline CSS styles instead of an external CSS file. To use an external CSS file, set this value to `false` and [generate the file with the hugo client][hugo client].
tabWidth
: Integer. Default is `4`.\
Substitute this number of spaces for each tab character in your highlighted code. Irrelevant if `noClasses` is `false`.
guessSyntax
: Boolean. Default is `false`.\
If the `LANG` argument is blank or an unrecognized language, auto-detect the language if possible, otherwise use a fallback language.
{{% note %}}
Instead of specifying both `lineNos` and `lineNumbersInTable`, you can use the following shorthand notation:
`lineNos=inline`
: equivalent to `lineNos=true` and `lineNumbersInTable=false`
`lineNos=table`
: equivalent to `lineNos=true` and `lineNumbersInTable=true`
{{% /note %}}
## Examples
```go-html-template
{{ $input := `fmt.Println("Hello World!")` }}
{{ transform.Highlight $input "go" }}
{{ $input := `console.log('Hello World!');` }}
{{ $lang := "js" }}
{{ transform.Highlight $input $lang "lineNos=table, style=api" }}
{{ $input := `echo "Hello World!"` }}
{{ $lang := "bash" }}
{{ $options := dict "lineNos" "table" "style" "dracula" }}
{{ transform.Highlight $input $lang $options }}
```
[Chroma]: https://github.com/alecthomas/chroma
[hugo client]: /commands/hugo_gen_chromastyles
[options]: #options
[site configuration]: /getting-started/configuration-markup#highlight
[style gallery]: https://xyproto.github.io/splash/docs/
[supported languages]: /content-management/syntax-highlighting#list-of-chroma-highlighting-languages

43
docs/content/en/functions/transform/HighlightCodeBlock.md Normal file
View file

@ -0,0 +1,43 @@
---
title: transform.HighlightCodeBlock
description: Highlights code received in context within a code block render hook.
categories: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: []
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.
Given the context passed into a code block render hook, `transform.HighlightCodeBlock` returns a `HighlightResult` object with two methods.
.Wrapped
: (`template.HTML`) Returns highlighted code wrapped in `<div>`, `<pre>`, and `<code>` elements. This is identical to the value returned by the transform.Highlight function.
.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 }}
```
To override the default [highlighting options]:
```go-html-template
{{ $options := merge .Options (dict "linenos" true) }}
{{ $result := transform.HighlightCodeBlock . $options }}
{{ $result.Wrapped }}
```
[highlighting options]: /functions/transform/highlight/#options

35
docs/content/en/functions/transform/Markdownify.md Normal file
View file

@ -0,0 +1,35 @@
---
title: transform.Markdownify
linkTitle: markdownify
description: Renders markdown to HTML.
categories: [functions]
keywords: []
menu:
docs:
parent: functions
function:
aliases: [markdownify]
returnType: template.HTML
signatures: [transform.Markdownify INPUT]
relatedFunctions: []
aliases: [/functions/markdownify]
---
```go-html-template
{{ .Title | markdownify }}
```
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`.
If the resulting HTML is two or more paragraphs, Hugo leaves the wrapping `p` tags in place.
[`.Page.RenderString`]: /functions/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.
[markdown render hooks]: /templates/render-hooks/
[#9692]: https://github.com/gohugoio/hugo/issues/9692
{{% /note %}}

24
docs/content/en/functions/transform/Plainify.md Normal file
View file

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

96
docs/content/en/functions/transform/Remarshal.md Normal file
View file

@ -0,0 +1,96 @@
---
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]
keywords: []
menu:
docs:
parent: functions
function:
aliases: []
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.
{{% note %}}
This function is primarily a helper for Hugo's documentation, used to convert configuration and front matter examples to JSON, TOML, and YAML.
This is not a general purpose converter, and may change without notice if required for Hugo's documentation site.
{{% /note %}}
Example 1
: Convert a string of TOML to JSON.
```go-html-template
{{ $s := `
baseURL = 'https://example.org/'
languageCode = 'en-US'
title = 'ABC Widgets'
`}}
<pre>{{ transform.Remarshal "json" $s }}</pre>
```
Resulting HTML:
```html
<pre>{
&#34;baseURL&#34;: &#34;https://example.org/&#34;,
&#34;languageCode&#34;: &#34;en-US&#34;,
&#34;title&#34;: &#34;ABC Widgets&#34;
}
</pre>
```
Rendered in browser:
```text
{
"baseURL": "https://example.org/",
"languageCode": "en-US",
"title": "ABC Widgets"
}
```
Example 2
: Convert a map to YAML.
```go-html-template
{{ $m := dict
"a" "Hugo rocks!"
"b" (dict "question" "What is 6x7?" "answer" 42)
"c" (slice "foo" "bar")
}}
<pre>{{ transform.Remarshal "yaml" $m }}</pre>
```
Resulting HTML:
```html
<pre>a: Hugo rocks!
b:
answer: 42
question: What is 6x7?
c:
- foo
- bar
</pre>
```
Rendered in browser:
```text
a: Hugo rocks!
b:
answer: 42
question: What is 6x7?
c:
- foo
- bar
```

83
docs/content/en/functions/transform/Unmarshal.md Normal file
View file

@ -0,0 +1,83 @@
---
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]
keywords: []
menu:
docs:
parent: functions
function:
aliases: [unmarshal]
returnType: any
signatures:
- RESOURCE or STRING | transform.Unmarshal [OPTIONS]
- RESOURCE or STRING | unmarshal [OPTIONS]
relatedFunctions:
- encoding.Jsonify
- transform.Remarshal
- transform.Unmarshal
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:
```go-html-template
{{ $greetings := "hello = \"Hello Hugo\"" | transform.Unmarshal }}`
```
```go-html-template
{{ $greetings := "hello = \"Hello Hugo\"" | resources.FromString "data/greetings.toml" | transform.Unmarshal }}
```
In both the above examples, you get a map you can work with:
```go-html-template
{{ $greetings.hello }}
```
The above prints `Hello Hugo`.
## CSV options
Unmarshal with CSV as input has some options you can set:
delimiter
: 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:
```go-html-template
{{ $csv := "a;b;c" | transform.Unmarshal (dict "delimiter" ";") }}
```
## XML data
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 }}`:
```xml
<root>
<message>
<title>Hugo rocks!</title>
<description>Thanks for using Hugo</description>
</message>
</root>
```
The following example lists the items of an RSS feed:
```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>
{{ end }}
{{ end }}
```