-
{{ range .Pages }}
- {{ .Title }} diff --git a/docs/content/en/content-management/comments.md b/docs/content/en/content-management/comments.md index fee4fb372..f0e4a9ae1 100644 --- a/docs/content/en/content-management/comments.md +++ b/docs/content/en/content-management/comments.md @@ -34,7 +34,7 @@ For many websites, this is enough configuration. However, you also have the opti Disqus has its own [internal template](/templates/embedded/#disqus) available, to render it add the following code where you want comments to appear: ```go-html-template -{{ template "_internal/disqus.html" . }} +{{ partial "disqus.html" . }} ``` ## Alternatives diff --git a/docs/content/en/content-management/content-adapters.md b/docs/content/en/content-management/content-adapters.md index 3468bb728..e22962531 100644 --- a/docs/content/en/content-management/content-adapters.md +++ b/docs/content/en/content-management/content-adapters.md @@ -27,7 +27,7 @@ content/ └── _index.md ``` -Each content adapter is named _content.gotmpl and uses the same [syntax] as templates in the `layouts` directory. You can use any of the [template functions] within a content adapter, as well as the methods described below. +Each content adapter is named `_content.gotmpl` and uses the same [syntax] as templates in the `layouts` directory. You can use any of the [template functions] within a content adapter, as well as the methods described below. ## Methods @@ -71,7 +71,7 @@ Adds a page resource to the site. Then retrieve the new page resource with something like: -```go-html-template {file="layouts/_default/single.html"} +```go-html-template {file="layouts/page.html"} {{ with .Resources.Get "cover.jpg" }}
- {{ .Name }} @@ -83,7 +83,7 @@ In the above note that the `href` attribute of the second `anchor` element is bl With this template code: -```go-html-template {file="layouts/partials/menu.html"} +```go-html-template {file="layouts/_partials/menu.html"}
- {{ .Name }} diff --git a/docs/content/en/methods/page/Data.md b/docs/content/en/methods/page/Data.md index ae0bdc57f..bb88dbde6 100644 --- a/docs/content/en/methods/page/Data.md +++ b/docs/content/en/methods/page/Data.md @@ -14,7 +14,7 @@ The `Data` method on a `Page` object returns a unique data object for each [page > [!note] > The `Data` method is only useful within [taxonomy](g) and [term](g) templates. > -> Themes that are not actively maintained may still use `.Data.Pages` in list templates. Although that syntax remains functional, use one of these methods instead: [`Pages`], [`RegularPages`], or [`RegularPagesRecursive`] +> Themes that are not actively maintained may still use `.Data.Pages` in their templates. Although that syntax remains functional, use one of these methods instead: [`Pages`], [`RegularPages`], or [`RegularPagesRecursive`] The examples that follow are based on this site configuration: diff --git a/docs/content/en/methods/page/Description.md b/docs/content/en/methods/page/Description.md index 5287aa699..7a609bb07 100644 --- a/docs/content/en/methods/page/Description.md +++ b/docs/content/en/methods/page/Description.md @@ -16,7 +16,7 @@ title = 'How to make spicy tuna hand rolls' description = 'Instructions for making spicy tuna hand rolls.' {{< /code-toggle >}} -```go-html-template {file="layouts/_default/baseof.html"} +```go-html-template {file="layouts/baseof.html"} ... diff --git a/docs/content/en/methods/page/Eq.md b/docs/content/en/methods/page/Eq.md index 4947a4bfa..0cfe1f1f7 100644 --- a/docs/content/en/methods/page/Eq.md +++ b/docs/content/en/methods/page/Eq.md @@ -9,9 +9,9 @@ params: signatures: [PAGE1.Eq PAGE2] --- -In this contrived example from a single template, we list all pages in the current section except for the current page. +In this contrived example we list all pages in the current section except for the current page. -```go-html-template +```go-html-template {file="layouts/page.html"} {{ $currentPage := . }} {{ range .CurrentSection.Pages }} {{ if not (.Eq $currentPage) }} diff --git a/docs/content/en/methods/page/Fragments.md b/docs/content/en/methods/page/Fragments.md index 2c0460def..1b30ac973 100644 --- a/docs/content/en/methods/page/Fragments.md +++ b/docs/content/en/methods/page/Fragments.md @@ -102,8 +102,8 @@ Hugo renders this to: > When using the `Fragments` methods within a shortcode, call the shortcode using [standard notation]. If you use [Markdown notation] the rendered shortcode is included in the creation of the fragments map, resulting in a circular loop. [`TableOfContents`]: /methods/page/tableofcontents/ -[ATX]: https://spec.commonmark.org/0.30/#atx-headings +[ATX]: https://spec.commonmark.org/current/#atx-headings [Markdown notation]: /content-management/shortcodes/#notation -[setext]: https://spec.commonmark.org/0.30/#setext-headings +[setext]: https://spec.commonmark.org/current/#setext-headings [standard notation]: /content-management/shortcodes/#notation [table of contents]: /methods/page/tableofcontents/ diff --git a/docs/content/en/methods/page/GetPage.md b/docs/content/en/methods/page/GetPage.md index 02f6888e0..7c1e45dd9 100644 --- a/docs/content/en/methods/page/GetPage.md +++ b/docs/content/en/methods/page/GetPage.md @@ -35,9 +35,9 @@ content/ └── _index.md ``` -The examples below depict the result of rendering works/paintings/the-mona-lisa.md: +The examples below depict the result of rendering `works/paintings/the-mona-lisa.md`: -```go-html-template {file="layouts/works/single.html"} +```go-html-template {file="layouts/works/page.html"} {{ with .GetPage "starry-night" }} {{ .Title }} → Starry Night {{ end }} diff --git a/docs/content/en/methods/page/HasShortcode.md b/docs/content/en/methods/page/HasShortcode.md index 616b6de09..2e585da31 100644 --- a/docs/content/en/methods/page/HasShortcode.md +++ b/docs/content/en/methods/page/HasShortcode.md @@ -29,7 +29,7 @@ By example, let's use [Plotly] to render a chart: The shortcode is simple: -```go-html-template {file="layouts/shortcodes/plotly.html"} +```go-html-template {file="layouts/_shortcodes/plotly.html"} {{ $id := printf "plotly-%02d" .Ordinal }}
{{ .Title }}
@@ -338,7 +338,7 @@ content/ └── the-hunchback-of-notre-dame.md ``` -If the content adapter also creates books/the-hunchback-of-notre-dame, the content of the published page is indeterminate. You can not define the processing order. +If the content adapter also creates `books/the-hunchback-of-notre-dame`, the content of the published page is indeterminate. You can not define the processing order. To detect page collisions, use the `--printPathWarnings` flag when building your site. diff --git a/docs/content/en/content-management/data-sources.md b/docs/content/en/content-management/data-sources.md index 3fc98b36a..0395266e0 100644 --- a/docs/content/en/content-management/data-sources.md +++ b/docs/content/en/content-management/data-sources.md @@ -65,7 +65,7 @@ Use data sources to augment existing content. For example, create a shortcode to {{}} ``` -```go-html-template {file="layouts/shortcodes/csv-to-table.html"} +```go-html-template {file="layouts/_shortcodes/csv-to-table.html"} {{ with $file := .Get 0 }} {{ with resources.Get $file }} {{ with . | transform.Unmarshal }} diff --git a/docs/content/en/content-management/diagrams.md b/docs/content/en/content-management/diagrams.md index 0070ced59..3bcecb60b 100644 --- a/docs/content/en/content-management/diagrams.md +++ b/docs/content/en/content-management/diagrams.md @@ -39,7 +39,7 @@ Will be rendered as: Hugo does not provide a built-in template for Mermaid diagrams. Create your own using a [code block render hook]: -```go-html-template {file="layouts/_default/_markup/render-codeblock-mermaid.html" copy=true} +```go-html-template {file="layouts/_markup/render-codeblock-mermaid.html" copy=true}
{{ .Inner | htmlEscape | safeHTML }}
@@ -48,7 +48,7 @@ Hugo does not provide a built-in template for Mermaid diagrams. Create your own
Then include this snippet at the _bottom_ of your base template, before the closing `body` tag:
-```go-html-template {file="layouts/_default/baseof.html" copy=true}
+```go-html-template {file="layouts/baseof.html" copy=true}
{{ if .Store.Get "hasMermaid" }}
+ {{ else }}
{{ with . | fingerprint }}
{{ end }}
- {{ else }}
-
{{ end }}
{{ end }}
{{ end }}
diff --git a/docs/content/en/functions/lang/Merge.md b/docs/content/en/functions/lang/Merge.md
index db40c2669..f2ce16011 100644
--- a/docs/content/en/functions/lang/Merge.md
+++ b/docs/content/en/functions/lang/Merge.md
@@ -24,6 +24,6 @@ A more practical example is to fill in the missing translations from the other l
```sh
{{ $pages := .Site.RegularPages }}
{{ range .Site.Home.Translations }}
-{{ $pages = $pages | lang.Merge .Site.RegularPages }}
+ {{ $pages = $pages | lang.Merge .Site.RegularPages }}
{{ end }}
```
diff --git a/docs/content/en/functions/math/Counter.md b/docs/content/en/functions/math/Counter.md
index 16456cec6..eec4df8b3 100644
--- a/docs/content/en/functions/math/Counter.md
+++ b/docs/content/en/functions/math/Counter.md
@@ -12,14 +12,14 @@ params:
The counter is global for both monolingual and multilingual sites, and its initial value for each build is 1.
-```go-html-template
-{{ warnf "single.html called %d times" math.Counter }}
+```go-html-template {file="layouts/page.html"}
+{{ warnf "page.html called %d times" math.Counter }}
```
-```sh
-WARN single.html called 1 times
-WARN single.html called 2 times
-WARN single.html called 3 times
+```text
+WARN page.html called 1 times
+WARN page.html called 2 times
+WARN page.html called 3 times
```
Use this function to:
diff --git a/docs/content/en/functions/math/MaxInt64.md b/docs/content/en/functions/math/MaxInt64.md
new file mode 100644
index 000000000..ee4f68ffd
--- /dev/null
+++ b/docs/content/en/functions/math/MaxInt64.md
@@ -0,0 +1,27 @@
+---
+title: math.MaxInt64
+description: Returns the maximum value for a signed 64-bit integer.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: int64
+ signatures: [math.MaxInt64]
+---
+
+{{< new-in 0.147.3 />}}
+
+```go-html-template
+{{ math.MaxInt64 }} → 9223372036854775807
+```
+
+This function is helpful for simulating a loop that continues indefinitely until a break condition is met. For example:
+
+```go-html-template
+{{ range math.MaxInt64 }}
+ {{ if eq . 42 }}
+ {{ break }}
+ {{ end }}
+{{ end }}
+```
diff --git a/docs/content/en/functions/openapi3/Unmarshal.md b/docs/content/en/functions/openapi3/Unmarshal.md
index d1f928aeb..ca2ee93e3 100644
--- a/docs/content/en/functions/openapi3/Unmarshal.md
+++ b/docs/content/en/functions/openapi3/Unmarshal.md
@@ -39,7 +39,7 @@ To inspect the data structure:
To list the GET and POST operations for each of the API paths:
```go-html-template
-{{ range $path, $details := $api.Paths }}
+{{ range $path, $details := $api.Paths.Map }}
{{ $path }}
-
{{ with $details.Get }}
@@ -54,6 +54,11 @@ To list the GET and POST operations for each of the API paths:
{{ end }}
```
+> [!warning]
+> The unmarshaled data structure is created with [`kin-openapi`](https://github.com/getkin/kin-openapi). Many fields are structs or pointers (not maps), and therefore require accessors or other methods for indexing and iteration.
+> For example, prior to [`kin-openapi` v0.122.0](https://github.com/getkin/kin-openapi#v01220) / [Hugo v0.121.0](https://github.com/gohugoio/hugo/releases/tag/v0.121.0), `Paths` was a map (so `.Paths` was iterable) and it is now a pointer (and requires the `.Paths.Map` accessor, as in the example above).
+> See the [`kin-openapi` godoc for OpenAPI 3](https://pkg.go.dev/github.com/getkin/kin-openapi/openapi3) for full type definitions.
+
Hugo renders this to:
```html
diff --git a/docs/content/en/functions/partials/Include.md b/docs/content/en/functions/partials/Include.md
index eb7eeafdc..0474bf77f 100644
--- a/docs/content/en/functions/partials/Include.md
+++ b/docs/content/en/functions/partials/Include.md
@@ -19,7 +19,7 @@ In this example we have three partial templates:
```text
layouts/
-└── partials/
+└── _partials/
├── average.html
├── breadcrumbs.html
└── footer.html
diff --git a/docs/content/en/functions/partials/IncludeCached.md b/docs/content/en/functions/partials/IncludeCached.md
index 3905ee15e..9bf1d5384 100644
--- a/docs/content/en/functions/partials/IncludeCached.md
+++ b/docs/content/en/functions/partials/IncludeCached.md
@@ -16,7 +16,7 @@ Without a [`return`] statement, the `partialCached` function returns a string of
The `partialCached` function can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation.
> [!note]
-> Each Site (or language) has its own `partialCached` cache, so each site will execute a partial once.
+> Each site (or language) has its own `partialCached` cache, so each site will execute a partial once.
>
> Hugo renders pages in parallel, and will render the partial more than once with concurrent calls to the `partialCached` function. After Hugo caches the rendered partial, new pages entering the build pipeline will use the cached result.
@@ -28,7 +28,7 @@ Here is the simplest usage:
Pass additional arguments to `partialCached` to create variants of the cached partial. For example, if you have a complex partial that should be identical when rendered for pages within the same section, use a variant based on section so that the partial is only rendered once per section:
-```go-html-template {file="layouts/_default/baseof.html"}
+```go-html-template {file="layouts/baseof.html"}
{{ partialCached "footer.html" . .Section }}
```
diff --git a/docs/content/en/functions/resources/FromString.md b/docs/content/en/functions/resources/FromString.md
index 4cd04f609..bd2d894b1 100644
--- a/docs/content/en/functions/resources/FromString.md
+++ b/docs/content/en/functions/resources/FromString.md
@@ -22,9 +22,9 @@ Let's say you need to publish a file named "site.json" in the root of your `publ
```json
{
- "build_date": "2025-01-16T19:14:41-08:00",
- "hugo_version": "0.141.0",
- "last_modified": "2025-01-16T19:14:46-08:00"
+ "build_date": "2025-05-03T19:14:41-08:00",
+ "hugo_version": "0.147.9",
+ "last_modified": "2025-05-03T19:14:46-08:00"
}
```
diff --git a/docs/content/en/functions/templates/Current.md b/docs/content/en/functions/templates/Current.md
index 805aeec05..d2c2c9609 100644
--- a/docs/content/en/functions/templates/Current.md
+++ b/docs/content/en/functions/templates/Current.md
@@ -47,7 +47,7 @@ debug = true
To visually mark where a template begins and ends execution:
-```go-html-template {file="layouts/_default/single.html"}
+```go-html-template {file="layouts/page.html"}
{{ define "main" }}
{{ if site.Params.debug }}
[entering {{ templates.Current.Filename }}]
@@ -66,7 +66,7 @@ To visually mark where a template begins and ends execution:
To display the chain of templates that led to the current one, create a partial template that iterates through its ancestors:
-```go-html-template {file="layouts/partials/template-call-stack.html" copy=true}
+```go-html-template {file="layouts/_partials/template-call-stack.html" copy=true}
{{ with templates.Current }}
{{ range .Ancestors }}
@@ -81,7 +81,7 @@ To display the chain of templates that led to the current one, create a partial
Then call the partial from any template:
-```go-html-template {file="layouts/partials/footer/copyright.html" copy=true}
+```go-html-template {file="layouts/_partials/footer/copyright.html" copy=true}
{{ if site.Params.debug }}
{{ partial "template-call-stack.html" . }}
{{ end }}
@@ -90,15 +90,15 @@ Then call the partial from any template:
The rendered template stack would look something like this:
```text
-/home/user/project/layouts/partials/footer/copyright.html
-/home/user/project/themes/foo/layouts/partials/footer.html
-/home/user/project/layouts/_default/single.html
-/home/user/project/themes/foo/layouts/_default/baseof.html
+/home/user/project/layouts/_partials/footer/copyright.html
+/home/user/project/themes/foo/layouts/_partials/footer.html
+/home/user/project/layouts/page.html
+/home/user/project/themes/foo/layouts/baseof.html
```
To reverse the order of the entries, chain the `Reverse` method to the `Ancestors` method:
-```go-html-template {file="layouts/partials/template-call-stack.html" copy=true}
+```go-html-template {file="layouts/_partials/template-call-stack.html" copy=true}
{{ with templates.Current }}
{{ range .Ancestors.Reverse }}
@@ -115,7 +115,7 @@ To reverse the order of the entries, chain the `Reverse` method to the `Ancestor
To render links that, when clicked, will open the template in Microsoft Visual Studio Code, create a partial template with anchor elements that use the `vscode` URI scheme:
-```go-html-template {file="layouts/partials/template-open-in-vs-code.html" copy=true}
+```go-html-template {file="layouts/_partials/template-open-in-vs-code.html" copy=true}
{{ with templates.Current.Parent }}
{{ .Name }}
@@ -128,7 +128,7 @@ To render links that, when clicked, will open the template in Microsoft Visual S
Then call the partial from any template:
-```go-html-template {file="layouts/_default/single.html" copy=true}
+```go-html-template {file="layouts/page.html" copy=true}
{{ define "main" }}
{{ .Title }}
{{ .Content }} @@ -141,7 +141,7 @@ Then call the partial from any template: Use the same approach to render the entire call stack as links: -```go-html-template {file="layouts/partials/template-call-stack.html" copy=true} +```go-html-template {file="layouts/_partials/template-call-stack.html" copy=true} {{ with templates.Current }}
{{ range .Ancestors }}
diff --git a/docs/content/en/functions/templates/Defer.md b/docs/content/en/functions/templates/Defer.md
index 6a9ca56ae..16c32724e 100644
--- a/docs/content/en/functions/templates/Defer.md
+++ b/docs/content/en/functions/templates/Defer.md
@@ -14,33 +14,34 @@ aliases: [/functions/templates.defer]
{{< new-in 0.128.0 />}}
> [!note]
-> This feature is meant to be used in the main page layout files/templates, and has undefined behavior when used from shortcodes, partials or render hook templates. See [this issue](https://github.com/gohugoio/hugo/issues/13492#issuecomment-2734700391) for more info.
+> This feature should only be used in the main page template, typically `layouts/baseof.html`. Using it in shortcodes, partials, or render hook templates may lead to unpredictable results. For further details, please refer to [this issue].
+
+[this issue]: https://github.com/gohugoio/hugo/issues/13492#issuecomment-2734700391
In some rare use cases, you may need to defer the execution of a template until after all sites and output formats have been rendered. One such example could be [TailwindCSS](/functions/css/tailwindcss/) using the output of [hugo_stats.json](/configuration/build/) to determine which classes and other HTML identifiers are being used in the final output:
-```go-html-template
-{{ with (templates.Defer (dict "key" "global")) }}
- {{ $t := debug.Timer "tailwindcss" }}
- {{ with resources.Get "css/styles.css" }}
- {{ $opts := dict
- "inlineImports" true
- "optimize" hugo.IsProduction
- }}
- {{ with . | css.TailwindCSS $opts }}
- {{ if hugo.IsDevelopment }}
-
- {{ else }}
- {{ with . | minify | fingerprint }}
-
- {{ end }}
+```go-html-template {file="layouts/baseof.html" copy=true}
+
+ ...
+ {{ with (templates.Defer (dict "key" "global")) }}
+ {{ partial "css.html" . }}
+ {{ end }}
+ ...
+
+```
+
+```go-html-template {file="layouts/_partials/css.html" copy=true}
+{{ with resources.Get "css/main.css" }}
+ {{ $opts := dict "minify" (not hugo.IsDevelopment) }}
+ {{ with . | css.TailwindCSS $opts }}
+ {{ if hugo.IsDevelopment }}
+
+ {{ else }}
+ {{ with . | fingerprint }}
+
{{ end }}
{{ end }}
{{ end }}
- {{ $t.Stop }}
{{ end }}
```
@@ -52,19 +53,23 @@ In some rare use cases, you may need to defer the execution of a template until
For the above to work well when running the server (or `hugo -w`), you want to have a configuration similar to this:
{{< code-toggle file=hugo >}}
+[build]
+ [build.buildStats]
+ enable = true
+ [[build.cachebusters]]
+ source = 'assets/notwatching/hugo_stats\.json'
+ target = 'css'
+ [[build.cachebusters]]
+ source = '(postcss|tailwind)\.config\.js'
+ target = 'css'
[module]
-[[module.mounts]]
-source = "hugo_stats.json"
-target = "assets/notwatching/hugo_stats.json"
-disableWatch = true
-[build.buildStats]
-enable = true
-[[build.cachebusters]]
-source = "assets/notwatching/hugo_stats\\.json"
-target = "styles\\.css"
-[[build.cachebusters]]
-source = "(postcss|tailwind)\\.config\\.js"
-target = "css"
+ [[module.mounts]]
+ source = 'assets'
+ target = 'assets'
+ [[module.mounts]]
+ disableWatch = true
+ source = 'hugo_stats.json'
+ target = 'assets/notwatching/hugo_stats.json'
{{< /code-toggle >}}
## Options
diff --git a/docs/content/en/functions/templates/Exists.md b/docs/content/en/functions/templates/Exists.md
index 79fc561c8..a8d627ff7 100644
--- a/docs/content/en/functions/templates/Exists.md
+++ b/docs/content/en/functions/templates/Exists.md
@@ -17,7 +17,7 @@ Use the `templates.Exists` function with dynamic template paths:
```go-html-template
{{ $partialPath := printf "headers/%s.html" .Type }}
-{{ if templates.Exists ( printf "partials/%s" $partialPath ) }}
+{{ if templates.Exists ( printf "_partials/%s" $partialPath ) }}
{{ partial $partialPath . }}
{{ else }}
{{ partial "headers/default.html" . }}
diff --git a/docs/content/en/functions/transform/ToMath.md b/docs/content/en/functions/transform/ToMath.md
index a9f12c546..0beb8f56a 100644
--- a/docs/content/en/functions/transform/ToMath.md
+++ b/docs/content/en/functions/transform/ToMath.md
@@ -6,7 +6,7 @@ keywords: []
params:
functions_and_methods:
aliases: []
- returnType: types.Result[template.HTML]
+ returnType: template.HTML
signatures: ['transform.ToMath INPUT [OPTIONS]']
aliases: [/functions/tomath]
---
@@ -58,12 +58,25 @@ 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`.
+: (`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
-
+
+
+strict
+: {{< new-in 0.147.6 />}}
+: (`string`) Controls how KaTeX handles LaTeX features that offer convenience but aren't officially supported, one of `error`, `ignore`, or `warn`. Default is `error`.
+
+ - `error`: Throws an error when convenient, unsupported LaTeX features are encountered.
+ - `ignore`: Allows convenient, unsupported LaTeX features without any feedback.
+ - `warn`: {{< new-in 0.147.7 />}} Emits a warning when convenient, unsupported LaTeX features are encountered.
+
+: The `newLineInDisplayMode` error code, which flags the use of `\\`
+or `\newline` in display mode outside an array or tabular environment, is
+intentionally designed not to throw an error, despite this behavior
+being questionable.
throwOnError
: (`bool`) Whether to throw a `ParseError` when KaTeX encounters an unsupported command or invalid LaTeX. Default is `true`.
@@ -96,13 +109,13 @@ 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.
+> The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration, you must double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting.
### Step 2
Create a [passthrough render hook] to capture and render the LaTeX markup.
-```go-html-template {file="layouts/_default/_markup/render-passthrough.html" copy=true}
+```go-html-template {file="layouts/_markup/render-passthrough.html" copy=true}
{{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }}
{{- with try (transform.ToMath .Inner $opts) }}
{{- with .Err }}
@@ -118,11 +131,11 @@ Create a [passthrough render hook] to capture and render the LaTeX markup.
In your base template, conditionally include the KaTeX CSS within the head element.
-```go-html-template {file="layouts/_default/baseof.html" copy=true}
+```go-html-template {file="layouts/baseof.html" copy=true}
{{ $noop := .WordCount }}
{{ if .Page.Store.Get "hasMath" }}
-
+
{{ end }}
```
diff --git a/docs/content/en/functions/transform/Unmarshal.md b/docs/content/en/functions/transform/Unmarshal.md
index 93168294c..8b2173b9b 100644
--- a/docs/content/en/functions/transform/Unmarshal.md
+++ b/docs/content/en/functions/transform/Unmarshal.md
@@ -180,7 +180,7 @@ To render an HTML table from a CSV file:
To extract a subset of the data, or to sort the data, unmarshal to a map instead of a slice:
```go-html-template
-{{ $data := slice }}
+{{ $data := dict }}
{{ $file := "pets.csv" }}
{{ with or (.Resources.Get $file) (resources.Get $file) }}
{{ $opts := dict "targetType" "map" }}
diff --git a/docs/content/en/functions/transform/XMLEscape.md b/docs/content/en/functions/transform/XMLEscape.md
index 9e6c77927..372ad9b6a 100644
--- a/docs/content/en/functions/transform/XMLEscape.md
+++ b/docs/content/en/functions/transform/XMLEscape.md
@@ -31,7 +31,7 @@ For example:
When using `transform.XMLEscape` in a template rendered by Go's [html/template] package, declare the string to be safe HTML to avoid double escaping. For example, in an RSS template:
-```xml {file="layouts/_default/rss.xml"}
+```xml {file="layouts/rss.xml"}
{{ .Summary | transform.XMLEscape | safeHTML }}
```
diff --git a/docs/content/en/getting-started/external-learning-resources/index.md b/docs/content/en/getting-started/external-learning-resources/index.md
index 7838b6810..f36544c02 100644
--- a/docs/content/en/getting-started/external-learning-resources/index.md
+++ b/docs/content/en/getting-started/external-learning-resources/index.md
@@ -62,7 +62,7 @@ This course covers the basics of using the Hugo static site generator. Work your
1. [Content Organization](https://www.giraffeacademy.com/static-site-generators/hugo/content-organization/)
1. [Front Matter](https://www.giraffeacademy.com/static-site-generators/hugo/front-matter/)
1. [Archetypes](https://www.giraffeacademy.com/static-site-generators/hugo/archetypes/)
-1. [Shortcodes](https://www.giraffeacademy.com/static-site-generators/hugo/archetypes/)
+1. [Shortcodes](https://www.giraffeacademy.com/static-site-generators/hugo/shortcodes/)
1. [Taxonomies](https://www.giraffeacademy.com/static-site-generators/hugo/taxonomies/)
1. [Template Basics](https://www.giraffeacademy.com/static-site-generators/hugo/introduction-to-templates/)
1. [List Page Templates](https://www.giraffeacademy.com/static-site-generators/hugo/list-page-templates/)
diff --git a/docs/content/en/host-and-deploy/host-on-aws-amplify/index.md b/docs/content/en/host-and-deploy/host-on-aws-amplify/index.md
index aadb89116..e2b35dbbe 100644
--- a/docs/content/en/host-and-deploy/host-on-aws-amplify/index.md
+++ b/docs/content/en/host-and-deploy/host-on-aws-amplify/index.md
@@ -44,9 +44,9 @@ version: 1
env:
variables:
# Application versions
- DART_SASS_VERSION: 1.85.0
- GO_VERSION: 1.23.3
- HUGO_VERSION: 0.144.2
+ DART_SASS_VERSION: 1.89.2
+ GO_VERSION: 1.24.2
+ HUGO_VERSION: 0.147.9
# Time zone
TZ: America/Los_Angeles
# Cache
diff --git a/docs/content/en/host-and-deploy/host-on-codeberg-pages.md b/docs/content/en/host-and-deploy/host-on-codeberg-pages.md
index cd137c420..2a881f718 100644
--- a/docs/content/en/host-and-deploy/host-on-codeberg-pages.md
+++ b/docs/content/en/host-and-deploy/host-on-codeberg-pages.md
@@ -51,9 +51,11 @@ git remote add origin https://codeberg.org//pages.git
git push -u origin main
```
-## Automated deployment
+## Automated deployment using Woodpecker CI
-In order to automatically deploy your Hugo website, you need to have or [request] access to Codeberg's CI, as well as add a `.woodpecker.yaml` file in the root of your project. A template and additional instructions are available in the official [examples repository].
+There are two methods you can use to deploy your Hugo website to Codeberg automatically. These are: Woodpecker CI and Forgejo Actions.
+
+To use Codeberg's Woodpecker CI, you need to have or [request] access to it, as well as add a `.woodpecker.yaml` file in the root of your project. A template and additional instructions are available in the official [examples repository].
[request]: https://codeberg.org/Codeberg-e.V./requests/issues/new?template=ISSUE_TEMPLATE%2fWoodpecker-CI.yaml
[examples repository]: https://codeberg.org/Codeberg-CI/examples/src/branch/main/Hugo/.woodpecker.yaml
@@ -74,7 +76,178 @@ git remote add origin https://codeberg.org//.git
git push -u origin main
```
-Your project will then be built and deployed by Codeberg's CI.
+Your project will then be built and deployed by Codeberg's Woodpecker CI.
+
+## Automated deployment using Forgejo Actions
+
+The other way to deploy your website to Codeberg pages automatically is to make use of Forgejo Actions. Actions need a _runner_ to work, and Codeberg has [great documentation] on how to set one up yourself. However, Codeberg provides a [handful of humble runners] themselves (they say this feature is in "open alpha"), which actually seem powerful enough to build at least relatively simple websites.
+
+[great documentation]: https://docs.codeberg.org/ci/actions/
+[handful of humble runners]: https://codeberg.org/actions/meta
+
+To deploy your website this way, you don't need to request any access. All you need to do is enable actions in your repository settings (see the documentation link above) and add a workflow configuration file, for example, `hugo.yaml`, to the `.forgejo/workflows/` directory in your website's source repository.
+
+Two examples of such a file are provided below.
+
+The first file should work for automatically building your website from the source branch (`main` in this case) and committing the result to the target branch (`pages`). Without changes, this file should make your built website accessible under `https://.codeberg.page//`:
+
+```yaml {file=".forgejo/workflows/hugo.yaml" copy=true}
+name: Deploy Hugo site to Pages
+
+on:
+ # Runs on pushes targeting the default branch
+ push:
+ branches:
+ # If you want to build from a different branch, change it here.
+ - main
+ # Allows you to run this workflow manually from the Actions tab
+ workflow_dispatch:
+
+jobs:
+ build:
+ # You can find the list of available runners on https://codeberg.org/actions/meta, or run one yourself.
+ runs-on: codeberg-tiny-lazy
+ container:
+ # Specify "hugomods/hugo:exts" if you want to always use the latest version of Hugo for building.
+ image: "hugomods/hugo:exts-0.147.9"
+ steps:
+ - name: Clone the repository
+ uses: https://code.forgejo.org/actions/checkout@v4
+ with:
+ submodules: recursive
+ fetch-depth: 0
+ - name: Generate static files with Hugo
+ env:
+ # For maximum backward compatibility with Hugo modules
+ HUGO_ENVIRONMENT: production
+ HUGO_ENV: production
+ run: |
+ hugo \
+ --gc \
+ --minify
+ - name: Upload generated files
+ uses: https://code.forgejo.org/actions/upload-artifact@v3
+ with:
+ name: Generated files
+ path: public/
+ deploy:
+ needs: [ build ]
+ runs-on: codeberg-tiny-lazy
+ steps:
+ - name: Clone the repository
+ uses: https://code.forgejo.org/actions/checkout@v4
+ with:
+ submodules: recursive
+ fetch-depth: 0
+ - name: Checkout the target branch and clean it up
+ # If you want to commit to a branch other than "pages", change the two references below, as well as the reference in the last step.
+ run: |
+ git checkout pages || git switch --orphan pages && \
+ rm -Rfv $(ls -A | egrep -v '^(\.git|LICENSE)$')
+ - name: Download generated files
+ uses: https://code.forgejo.org/actions/download-artifact@v3
+ with:
+ name: Generated files
+ - name: Publish the website
+ run: |
+ git config user.email codeberg-ci && \
+ git config user.name "Codeberg CI" && \
+ git add . && \
+ git commit --allow-empty --message "Codeberg build for ${GITHUB_SHA}" && \
+ git push origin pages
+```
+
+The second file implements a more complex scenario: having your website sources in one repository and the resulting static website in another repository (in this case, `pages`). If you want Codeberg to make your website available at the root of your pages subdomain (`https://.codeberg.page/`), you have to push that website to the default branch of your repository named `pages`.
+
+Since this action involves more than one repository, it will require a bit more preparation:
+1. Create the target repository. Name it `pages`.
+2. Generate a new SSH key. *Do not* use any of your own SSH keys for this, but generate one for this specific task only. On Linux, BSD, and, likely, other operating systems, you can open a terminal emulator and run the following command to generate the key:
+ ```shell
+ ssh-keygen -f pagesbuild -P ""
+ ```
+ This will generate two files in your current directory: `pagesbuild` (private key) and `pagesbuild.pub` (public key).
+3. Add the newly generated public key as a deploy key to your `pages` repository: navigate to its Settings, click on "Deploy keys" in the left menu, click the "Add deploy key" button, give it a name (e.g. "Actions deploy key"), paste the contents of the **public** key file (`pagesbuild.pub`) to the Content field, tick the "Enable write access" checkbox, then submit the form.
+4. Navigate back to your source repository settings, expand the "Actions" menu and click on "Secrets". Then click "Add Secret", enter "DEPLOY_KEY" as the secret name and paste the contents of the newly generated **private** key file (`pagesbuild`) into the Value field.
+5. Navigate to the "Variables" submenu of the "Actions" menu and add the following variables:
+
+ | Name | Value |
+ |---------------------|----------------------------------------------------------------------------------|
+ | `TARGET_REPOSITORY` | `/pages` |
+ | `TARGET_BRANCH` | `main` (enter the default branch name of the `pages` repo here) |
+ | `SSH_KNOWN_HOSTS` | (paste the output you get by running `ssh-keyscan codeberg.org` in the terminal) |
+
+Once you've done all of the above, commit the following file to your repository as `.forgejo/workflows/hugo.yaml`. As you can see, the `deploy` job of this workflow is slightly different from the file above:
+
+```yaml {file=".forgejo/workflows/hugo.yaml" copy=true}
+name: Deploy Hugo site to Pages
+
+on:
+ # Runs on pushes targeting the default branch
+ push:
+ branches:
+ # If you want to build from a different branch, change it here.
+ - main
+ # Allows you to run this workflow manually from the Actions tab
+ workflow_dispatch:
+
+jobs:
+ build:
+ runs-on: codeberg-tiny-lazy
+ container:
+ # Specify "hugomods/hugo:exts" if you want to always use the latest version of Hugo for building.
+ image: "hugomods/hugo:exts-0.147.9"
+ steps:
+ - name: Clone the repository
+ uses: https://code.forgejo.org/actions/checkout@v4
+ with:
+ submodules: recursive
+ fetch-depth: 0
+ - name: Generate static files with Hugo
+ env:
+ # For maximum backward compatibility with Hugo modules
+ HUGO_ENVIRONMENT: production
+ HUGO_ENV: production
+ run: |
+ hugo \
+ --gc \
+ --minify \
+ --source ${PWD} \
+ --destination ${PWD}/public/
+ - name: Upload generated files
+ uses: https://code.forgejo.org/actions/upload-artifact@v3
+ with:
+ name: Generated files
+ path: public/
+ deploy:
+ needs: [ build ]
+ runs-on: codeberg-tiny-lazy
+ steps:
+ - name: Clone the repository
+ uses: https://code.forgejo.org/actions/checkout@v4
+ with:
+ repository: ${{ vars.TARGET_REPOSITORY }}
+ ref: ${{ vars.TARGET_BRANCH }}
+ submodules: recursive
+ fetch-depth: 0
+ ssh-key: ${{ secrets.DEPLOY_KEY }}
+ ssh-known-hosts: ${{ vars.SSH_KNOWN_HOSTS }}
+ - name: Remove all files
+ run: |
+ rm -Rfv $(ls -A | egrep -v '^(\.git|LICENSE)$')
+ - name: Download generated files
+ uses: https://code.forgejo.org/actions/download-artifact@v3
+ with:
+ name: Generated files
+ - name: Commit and push the website
+ run: |
+ git config user.email codeberg-ci && \
+ git config user.name "Codeberg CI" && \
+ git add -v . && \
+ git commit -v --allow-empty --message "Codeberg build for ${GITHUB_SHA}" && \
+ git push -v origin ${{ vars.TARGET_BRANCH }}
+```
+
+Once you commit one of the two files to your website source repository, you should see your first automated build firing up pretty soon. You can also trigger it manually by navigating to the **Actions** section of your repository web page, choosing **hugo.yaml** on the left and clicking on **Run workflow**.
## Other resources
diff --git a/docs/content/en/host-and-deploy/host-on-github-pages/index.md b/docs/content/en/host-and-deploy/host-on-github-pages/index.md
index 7c3201099..165c9934c 100644
--- a/docs/content/en/host-and-deploy/host-on-github-pages/index.md
+++ b/docs/content/en/host-and-deploy/host-on-github-pages/index.md
@@ -107,7 +107,8 @@ jobs:
build:
runs-on: ubuntu-latest
env:
- HUGO_VERSION: 0.145.0
+ DART_SASS_VERSION: 1.89.2
+ HUGO_VERSION: 0.147.9
HUGO_ENVIRONMENT: production
TZ: America/Los_Angeles
steps:
@@ -116,7 +117,11 @@ jobs:
wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
&& sudo dpkg -i ${{ runner.temp }}/hugo.deb
- name: Install Dart Sass
- run: sudo snap install dart-sass
+ run: |
+ wget -O ${{ runner.temp }}/dart-sass.tar.gz https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz \
+ && tar -xf ${{ runner.temp }}/dart-sass.tar.gz --directory ${{ runner.temp }} \
+ && mv ${{ runner.temp }}/dart-sass/ /usr/local/bin \
+ && echo "/usr/local/bin/dart-sass" >> $GITHUB_PATH
- name: Checkout
uses: actions/checkout@v4
with:
diff --git a/docs/content/en/host-and-deploy/host-on-gitlab-pages.md b/docs/content/en/host-and-deploy/host-on-gitlab-pages.md
index 4750b0ff3..cf4220888 100644
--- a/docs/content/en/host-and-deploy/host-on-gitlab-pages.md
+++ b/docs/content/en/host-and-deploy/host-on-gitlab-pages.md
@@ -23,17 +23,18 @@ Define your [CI/CD](g) jobs by creating a `.gitlab-ci.yml` file in the root of y
```yaml {file=".gitlab-ci.yml" copy=true}
variables:
- DART_SASS_VERSION: 1.87.0
+ DART_SASS_VERSION: 1.89.2
GIT_DEPTH: 0
GIT_STRATEGY: clone
GIT_SUBMODULE_STRATEGY: recursive
- HUGO_VERSION: 0.146.7
+ HUGO_VERSION: 0.147.9
NODE_VERSION: 22.x
TZ: America/Los_Angeles
image:
name: golang:1.24.2-bookworm
pages:
+ stage: deploy
script:
# Install brotli
- apt-get update
diff --git a/docs/content/en/host-and-deploy/host-on-netlify/index.md b/docs/content/en/host-and-deploy/host-on-netlify/index.md
index 4c89a6c1e..61ac15da8 100644
--- a/docs/content/en/host-and-deploy/host-on-netlify/index.md
+++ b/docs/content/en/host-and-deploy/host-on-netlify/index.md
@@ -113,8 +113,8 @@ Create a new file named netlify.toml in the root of your project directory. In i
```toml {file="netlify.toml"}
[build.environment]
-GO_VERSION = "1.24"
-HUGO_VERSION = "0.146.7"
+GO_VERSION = "1.24.2"
+HUGO_VERSION = "0.147.9"
NODE_VERSION = "22"
TZ = "America/Los_Angeles"
@@ -127,9 +127,9 @@ If your site requires Dart Sass to transpile Sass to CSS, the configuration file
```toml {file="netlify.toml"}
[build.environment]
-DART_SASS_VERSION = "1.87.0"
-GO_VERSION = "1.24"
-HUGO_VERSION = "0.146.7"
+DART_SASS_VERSION = "1.89.2"
+GO_VERSION = "1.24.2"
+HUGO_VERSION = "0.147.9"
NODE_VERSION = "22"
TZ = "America/Los_Angeles"
diff --git a/docs/content/en/host-and-deploy/host-on-render.md b/docs/content/en/host-and-deploy/host-on-render.md
index ac486fcbf..c4495c4b1 100644
--- a/docs/content/en/host-and-deploy/host-on-render.md
+++ b/docs/content/en/host-and-deploy/host-on-render.md
@@ -1,6 +1,6 @@
---
title: Host on Render
-description: Host your on Render.
+description: Host your site on Render.
categories: []
keywords: []
aliases: [/hosting-and-deployment/hosting-on-render/]
diff --git a/docs/content/en/methods/menu-entry/PageRef.md b/docs/content/en/methods/menu-entry/PageRef.md
index 979879b03..5fc2dfcae 100644
--- a/docs/content/en/methods/menu-entry/PageRef.md
+++ b/docs/content/en/methods/menu-entry/PageRef.md
@@ -62,7 +62,7 @@ weight = 20
With this template code:
-```go-html-template {file="layouts/partials/menu.html"}
+```go-html-template {file="layouts/_partials/menu.html"}
-
{{ range .Site.Menus.main }}
-
{{ range .Site.Menus.main }}