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 '346b60358dd8ec2ca228e6635bff9d7914b398b7'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2025-01-23 09:47:46 +01:00
parent 7f0f50b133 346b60358d
commit 43307b07f8
384 changed files with 3305 additions and 3271 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -17,7 +17,6 @@ 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;
```text
I :heart: Hugo!
```

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

@@ -9,81 +9,31 @@ action:
- functions/transform/CanHighlight
- functions/transform/HighlightCodeBlock
returnType: template.HTML
signatures: ['transform.Highlight INPUT LANG [OPTIONS]']
signatures: ['transform.Highlight CODE LANG [OPTIONS]']
aliases: [/functions/highlight]
toc: true
---
The `highlight` function uses the [Chroma] syntax highlighter, supporting over 200 languages with more than 40 available styles.
The `highlight` function uses the [Chroma] syntax highlighter, supporting over 200 languages with more than 40 [available styles].
[chroma]: https://github.com/alecthomas/chroma
[available styles]: https://xyproto.github.io/splash/docs/
## Arguments
INPUT
: The code to highlight.
The `transform.Highlight` shortcode takes three arguments.
CODE
: (`string`) The code to highlight.
LANG
: The language of the code to highlight. Choose from one of the [supported languages]. Case-insensitive.
: (`string`) The language of the code to highlight. Choose from one of the [supported languages]. This value is case-insensitive.
OPTIONS
: A map or comma-separated list of zero or more options. Set default values in [site configuration].
: (`map or string`) A map or space-separate key-value pairs wrapped in quotation marks. Set default values for each option in your [site configuration]. The key names are case-insensitive.
## Options
anchorLineNos
: (`bool`) Whether to render each line number as an HTML anchor element, setting the `id` attribute of the surrounding `span` element to the line number. Irrelevant if `lineNos` is `false`. Default is `false`.
codeFences
: (`bool`) Whether to highlight fenced code blocks. Default is `true`.
guessSyntax
: (`bool`) Whether to automatically detect the language if the `LANG` argument is blank or set to a language for which there is no corresponding [lexer]. Falls back to a plain text lexer if unable to automatically detect the language. Default is `false`.
[lexer]: /getting-started/glossary/#lexer
{{% note %}}
The Chroma syntax highlighter includes lexers for approximately 250 languages, but only 5 of these have implemented automatic language detection.
{{% /note %}}
hl_Lines
: (`string`) 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
: (`bool`) Whether to render the highlighted code without a wrapping container.Default is `false`.
lineAnchors
: (`string`) When rendering a line number as an HTML anchor element, prepend this value to the `id` attribute of the surrounding `span` element. This provides unique `id` attributes when a page contains two or more code blocks. Irrelevant if `lineNos` or `anchorLineNos` is `false`.
lineNoStart
: (`int`) The number to display at the beginning of the first line. Irrelevant if `lineNos` is `false`. Default is `1`.
lineNos
: (`bool`) Whether to display a number at the beginning of each line. Default is `false`.
lineNumbersInTable
: (`bool`) Whether to render the highlighted code in an HTML table with two cells. The left table cell contains the line numbers, while the right table cell contains the code. Irrelevant if `lineNos` is `false`. Default is `true`.
noClasses
: (`bool`) Whether to use inline CSS styles instead of an external CSS file. To use an external CSS file, set this value to `false` and generate the CSS file using the `hugo gen chromastyles` command. Default is `true`.
style
: (`string`) The CSS styles to apply to the highlighted code. See the [style gallery] for examples. Case-sensitive. Default is `monokai`.
tabWidth
: (`int`) Substitute this number of spaces for each tab character in your highlighted code. Irrelevant if `noClasses` is `false`. Default is `4`.
wrapperClass
{{< new-in 0.140.2 >}}
: (`string`) The class or classes to use for the outermost element of the highlighted code. Default is `highlight`.
{{% 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 %}}
[site configuration]: /getting-started/configuration-markup#highlight
[supported languages]: /content-management/syntax-highlighting#list-of-chroma-highlighting-languages
## Examples
@@ -101,7 +51,6 @@ lineNos=table
{{ transform.Highlight $input $lang $opts }}
```
[Chroma]: https://github.com/alecthomas/chroma
[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
## Options
{{% include "functions/_common/highlighting-options" %}}

211
docs/content/en/functions/transform/ToMath.md
View File

@@ -1,112 +1,161 @@
---
title: transform.ToMath
description: Renders a math expression using KaTeX.
description: Renders mathematical equations and expressions written in the LaTeX markup language.
categories: []
keywords: [math,katex]
keywords: [katex,latex,math,typesetting]
action:
aliases: []
related:
- content-management/mathematics
returnType: types.Result[template.HTML]
signatures: ['transform.ToMath EXPRESSION [OPTIONS]']
signatures: ['transform.ToMath INPUT [OPTIONS]']
aliases: [/functions/tomath]
toc: true
---
{{< new-in "0.132.0" >}}
{{% note %}}
This feature was introduced in Hugo 0.132.0 and is marked as experimental.
Hugo uses an embedded instance of the [KaTeX] display engine to render mathematical markup to HTML. You do not need to install the KaTeX display engine.
This does not mean that it's going to be removed, but this is our first use of WASI/Wasm in Hugo, and we need to see how it [works in the wild](https://github.com/gohugoio/hugo/issues/12736) before we can set it in stone.
{{% /note %}}
## Arguments
EXPRESSION
: The math expression to render using KaTeX.
OPTIONS
: A map of zero or more options.
## Options
These are a subset of the [KaTeX options].
output
: (`string`). Determines the markup language of the output. One of `html`, `mathml`, or `htmlAndMathml`. Default is `mathml`.
{{% comment %}}Indent to prevent splitting the description list.{{% / comment %}}
With `html` and `htmlAndMathml` you must include KaTeX CSS within the `head` element of your base template. For example:
```html
<head>
...
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css" integrity="sha384-nB0miv6/jRmo5UMMR1wu3Gz6NLsoTkbqJghGIsx//Rlm+ZU03BU6SQNC66uf4l5+" crossorigin="anonymous">
...
</head>
```
displayMode
: (`bool`) If `true` render in display mode, else render in inline mode. Default is `false`.
leqno
: (`bool`) If `true` render with the equation numbers on the left. Default is `false`.
fleqn
: (`bool`) If `true` render flush left with a 2em left margin. Default is `false`.
minRuleThickness
: (`float`) The minimum thickness of the fraction lines in `em`. Default is `0.04`.
macros
: (`map`) A map of macros to be used in the math expression. Default is `{}`.
throwOnError
: (`bool`) If `true` throw a `ParseError` when KaTeX encounters an unsupported command or invalid LaTex. See [error handling]. Default is `true`.
errorColor
: (`string`) The color of the error messages expressed as an RGB [hexadecimal color]. Default is `#cc0000`.
## Examples
### Basic
[KaTeX]: https://katex.org/
```go-html-template
{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" }}
```
### Macros
{{% note %}}
By default, Hugo renders mathematical markup to [MathML], and does not require any CSS to display the result.
[MathML]: https://developer.mozilla.org/en-US/docs/Web/MathML
To optimize rendering quality and accessibility, use the `htmlAndMathml` output option as described below. This approach requires an external stylesheet.
{{% /note %}}
```go-html-template
{{ $macros := dict
"\\addBar" "\\bar{#1}"
"\\bold" "\\mathbf{#1}"
}}
{{ $opts := dict "macros" $macros }}
{{ transform.ToMath "\\addBar{y} + \\bold{H}" $opts }}
{{ $opts := dict "output" "htmlAndMathml" }}
{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" $opts }}
```
## Options
Pass a map of options as the second argument to the `transform.ToMath` function. The options below are a subset of the KaTeX [rendering options].
[rendering options]: https://katex.org/docs/options.html
displayMode
: (`bool`) If `true` render in display mode, else render in inline mode. Default is `false`.
errorColor
: (`string`) The color of the error messages expressed as an RGB [hexadecimal color]. Default is `#cc0000`.
[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
fleqn
: (`bool`) If `true` render flush left with a 2em left margin. Default is `false`.
macros
: (`map`) A map of macros to be used in the math expression. Default is `{}`.
```go-html-template
{{ $macros := dict
"\\addBar" "\\bar{#1}"
"\\bold" "\\mathbf{#1}"
}}
{{ $opts := dict "macros" $macros }}
{{ transform.ToMath "\\addBar{y} + \\bold{H}" $opts }}
```
minRuleThickness
: (`float`) The minimum thickness of the fraction lines in `em`. Default is `0.04`.
output
: (`string`). Determines the markup language of the output, one of `html`, `mathml`, or `htmlAndMathml`. Default is `mathml`.
With `html` and `htmlAndMathml` you must include the KaTeX style sheet within the `head` element of your base template.
```html
<link href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css" rel="stylesheet">
throwOnError
: (`bool`) If `true` throw a `ParseError` when KaTeX encounters an unsupported command or invalid LaTeX. Default is `true`.
## Error handling
There are 3 ways to handle errors from KaTeX:
There are three ways to handle errors:
1. Let KaTeX throw an error and make the build fail. This is the default behavior.
1. Handle the error in your template. See the render hook example below.
1. Let KaTeX throw an error and fail the build. This is the default behavior.
1. Set the `throwOnError` option to `false` to make KaTeX render the expression as an error instead of throwing an error. See [options](#options).
1. Handle the error in your template.
{{< code file=layouts/_default/_markup/render-passthrough-inline.html copy=true >}}
{{ with transform.ToMath .Inner }}
{{ with .Err }}
{{ errorf "Failed to render KaTeX: %q. See %s" . $.Position }}
{{ else }}
{{ . }}
{{ end }}
{{ end }}
{{- /* chomp trailing newline */ -}}
The example below demonstrates error handing within a template.
## Example
Instead of client-side JavaScript rendering of mathematical markup using MathJax or KaTeX, create a passthrough render hook which calls the `transform.ToMath` function.
###### Step 1
Enable and configure the Goldmark [passthrough extension] in your site configuration. The passthrough extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves.
[passthrough extension]: /getting-started/configuration-markup/#passthrough
{{< code-toggle file=hugo copy=true >}}
[markup.goldmark.extensions.passthrough]
enable = true
[markup.goldmark.extensions.passthrough.delimiters]
block = [['\[', '\]'], ['$$', '$$']]
inline = [['\(', '\)']]
{{< /code-toggle >}}
{{% note %}}
The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration, you will need to double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting.
{{% /note %}}
###### Step 2
Create a [passthrough render hook] to capture and render the LaTeX markup.
[passthrough render hook]: /render-hooks/passthrough/
{{< code file=layouts/_default/_markup/render-passthrough.html copy=true >}}
{{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }}
{{- with try (transform.ToMath .Inner $opts) }}
{{- with .Err }}
{{ errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }}
{{- else }}
{{- .Value }}
{{- $.Page.Store.Set "hasMath" true }}
{{- end }}
{{- end -}}
{{< /code >}}
[error handling]: #error-handling
[KaTeX options]: https://katex.org/docs/options.html
[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
###### Step 3
In your base template, conditionally include the KaTeX CSS within the head element.
{{< code file=layouts/_default/baseof.html copy=true >}}
<head>
{{ $noop := .WordCount }}
{{ if .Page.Store.Get "hasMath" }}
<link href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css" rel="stylesheet">
{{ end }}
</head>
{{< /code >}}
In the above, note the use of a [noop](g) statement to force content rendering before we check the value of `hasMath` with the `Store.Get` method.
#### Step 4
Add some mathematical markup to your content, then test.
{{< code file=content/example.md >}}
This is an inline \(a^*=x-b^*\) equation.
These are block equations:
\[a^*=x-b^*\]
$$a^*=x-b^*$$
{{< /code >}}

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

@@ -16,7 +16,7 @@ toc: true
aliases: [/functions/transform.unmarshal]
---
The input can be a string or a [resource].
The input can be a string or a [resource](g).
## Unmarshal a string
@@ -37,7 +37,7 @@ 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.
A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
```text
assets/
@@ -97,14 +97,14 @@ A remote resource is a file on a remote server, accessible via HTTP or HTTPS.
```go-html-template
{{ $data := dict }}
{{ $url := "https://example.org/books.json" }}
{{ with resources.GetRemote $url }}
{{ with try (resources.GetRemote $url) }}
{{ with .Err }}
{{ errorf "%s" . }}
{{ else }}
{{ else with .Value }}
{{ $data = . | transform.Unmarshal }}
{{ else }}
{{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
{{ else }}
{{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
{{ range where $data "author" "Victor Hugo" }}
@@ -175,14 +175,14 @@ Get the remote data:
```go-html-template
{{ $data := dict }}
{{ $url := "https://example.org/books/index.xml" }}
{{ with resources.GetRemote $url }}
{{ with try (resources.GetRemote $url) }}
{{ with .Err }}
{{ errorf "%s" . }}
{{ else }}
{{ else with .Value }}
{{ $data = . | transform.Unmarshal }}
{{ else }}
{{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
{{ else }}
{{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
```
@@ -271,7 +271,7 @@ Each item node looks like this:
}
```
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:
The title keys do not begin with an underscore or a letter---they are not valid [identifiers](g). Use the [`index`] function to access the values:
```go-html-template
{{ with $data.channel.item }}
@@ -296,6 +296,4 @@ Hugo renders this to:
```
[`index`]: /functions/collections/indexfunction/
[identifiers]: https://go.dev/ref/spec#Identifiers
[resource]: /getting-started/glossary/#resource
[page bundle]: /content-management/page-bundles/