[codespell]
# Comma separated list of dirs to be skipped.
-skip = _vendor,.cspell.json,chroma.css,chroma_dark.css
+skip = *.ai,chroma.css,chroma_dark.css,.cspell.json
# Comma separated list of words to be ignored. Words must be lowercased.
-ignore-words-list = abl,edn,te,ue,trys,januar,womens,crossreferences
+ignore-words-list = abl,edn,januar,te,trys,ue,womens
# Check file names as well.
check-filenames = true
{
"version": "0.2",
"allowCompoundWords": true,
- "files": [
- "**/*.md"
+ "overrides": [
+ {
+ "filename": "**/*",
+ "enabled": false
+ },
+ {
+ "filename": "**/*.md",
+ "enabled": true
+ }
],
"flagWords": [
"alot",
"templating",
"transpile",
"unmarshal",
+ "unmarshaled",
"unmarshaling",
"unmarshals",
"# ----------------------------------------------------------------------",
"descripción",
"dokumentation",
"erklärungen",
+ "español",
+ "français",
"libros",
"mercredi",
"miesiąc",
"dpkg",
"doas",
"eopkg",
+ "forgejo",
"gitee",
"goldmark",
"katex",
+++ /dev/null
-# Number of days of inactivity before an issue becomes stale
-daysUntilStale: 120
-# Number of days of inactivity before a stale issue is closed
-daysUntilClose: 30
-# Issues with these labels will never be considered stale
-exemptLabels:
- - Keep
- - Security
- - UndocumentedFeature
-# Label to use when marking an issue as stale
-staleLabel: Stale
-# Comment to post when marking an issue as stale. Set to `false` to disable
-markComment: >
- This issue has been automatically marked as stale because it has not had
- recent activity. The resources of the Hugo team are limited, and so we are asking for your help.
-
- If you still think this is important, please tell us why.
-
- This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.
-
-# Comment to post when closing a stale issue. Set to `false` to disable
-closeComment: false
steps:
- name: Checkout repository
- uses: actions/checkout@v4
+ uses: actions/checkout@v5
- name: Initialize CodeQL
uses: github/codeql-action/init@v3
--- /dev/null
+name: Lint markdown
+on:
+ workflow_dispatch:
+ pull_request:
+jobs:
+ lint:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v5
+ - name: Run Markdown linter
+ uses: DavidAnson/markdownlint-cli2-action@v20
+ with:
+ globs: # set to null to override default of *.{md,markdown}
+ continue-on-error: false
spellcheck:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v4
- - uses: streetsidesoftware/cspell-action@v5
+ - uses: actions/checkout@v5
+ - uses: streetsidesoftware/cspell-action@v7
with:
- check_dot_files: false
- files: content/**/*.md
incremental_files_only: true
- inline: warning
- strict: false
+ strict: true
+ # cspell uses the .cspell.json configuration file
- uses: codespell-project/actions-codespell@v2
with:
check_filenames: true
check_hidden: true
- # by default, codespell uses configuration from the .codespellrc
+ # codespell uses the .codespellrc file
--- /dev/null
+name: Close stale issues and pull requests
+on:
+ workflow_dispatch:
+ schedule:
+ - cron: "30 1 * * *"
+permissions:
+ contents: read
+jobs:
+ stale:
+ permissions:
+ contents: read
+ issues: write
+ pull-requests: write
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/stale@v9
+ with:
+ days-before-stale: 90 # default is 60
+ days-before-close: 14 # default is 7
+ exempt-all-assignees: true
+ exempt-draft-pr: true
+ exempt-issue-labels: Keep, InProgress, NeedsTriage
+ exempt-pr-labels: Keep
+ operations-per-run: 100
+ stale-issue-message: >
+ This issue has been marked as stale because there hasn't been any
+ recent activity. It will be closed soon if there are no further
+ updates.
+ stale-pr-message: >
+ This pull request has been marked as stale because there hasn't
+ been any recent activity. It will be closed soon if there are no
+ further updates.
+++ /dev/null
-name: Super Linter
-
-on:
- workflow_dispatch:
-
-permissions:
- contents: read # to fetch code (actions/checkout)
-
-jobs:
- build:
- permissions:
- contents: read # to fetch code (actions/checkout)
- statuses: write # to mark status of each linter run (github/super-linter/slim)
-
- name: Lint Code Base
- runs-on: ubuntu-latest
- if: ${{ github.actor != 'dependabot[bot]' }}
-
- steps:
- - name: Checkout Code
- uses: actions/checkout@v4
-
- - name: Lint Code Base
- uses: super-linter/super-linter/slim@v6
- env:
- DEFAULT_BRANCH: master
- GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- IGNORE_GITIGNORED_FILES: true
- LINTER_RULES_PATH: /
- LOG_LEVEL: NOTICE
- MARKDOWN_CONFIG_FILE: .markdownlint.yaml
- SUPPRESS_POSSUM: true
- VALIDATE_CSS: false
- VALIDATE_EDITORCONFIG: false
- VALIDATE_GITLEAKS: false
- VALIDATE_HTML: false
- VALIDATE_JAVASCRIPT_STANDARD: false
- VALIDATE_JSCPD: false
- VALIDATE_NATURAL_LANGUAGE: false
- VALIDATE_SHELL_SHFMT: false
- VALIDATE_XML: false
--- /dev/null
+# Glob patterns to include
+globs:
+ - "content/**/*.md"
+
+# Glob patterns to exclude
+ignores:
+ - "content/**/commands/**"
+ - "content/en/about/license.md"
+ - "content/LICENSE.md"
+
+# Markdownlint rules and configuration
+# https://github.com/DavidAnson/markdownlint?tab=readme-ov-file#rules--aliases
+config:
+ MD001: true
+ # MD002 deprecated
+ MD003:
+ style: atx
+ MD004:
+ style: dash
+ MD005: true
+ # MD006 deprecated
+ MD007: false # if enabled, throws errors when definition descriptions contain list items
+ # MD008 deprecated
+ MD009: true
+ MD010: true
+ MD011: true
+ MD012: true
+ MD013: false
+ MD014: true
+ # MD015 deprecated
+ # MD016 deprecated
+ # MD017 deprecated
+ MD018: true
+ MD019: true
+ MD020: true
+ MD021: true
+ MD022: true
+ MD023: true
+ MD024: true
+ MD025: true
+ MD026: true
+ MD027: true
+ MD028: false
+ MD029:
+ style: one
+ MD030: true
+ MD031: true
+ MD032: true
+ MD033: true
+ MD034: false
+ MD035:
+ style: ---
+ MD036: true
+ MD037: true
+ MD038: true
+ MD039: true
+ MD040: true
+ MD041: false
+ MD042: true
+ MD043: false
+ MD044: false
+ MD045: true
+ MD046: false
+ MD047: true
+ MD048:
+ style: backtick
+ MD049:
+ style: underscore
+ MD050:
+ style: asterisk
+ MD051: false
+ MD052: true
+ MD053: true
+ MD054:
+ autolink: true
+ collapsed: true
+ full: true
+ inline: true
+ shortcut: true
+ url_inline: true
+ MD055:
+ style: consistent
+ MD056: true
+ # MD057 deprecated
+ MD058: true
+ MD059:
+ prohibited_texts:
+ - click here
+ - here
+ - link
+ - more
+++ /dev/null
-# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
-
-MD001: false
-MD002: false
-MD003: false
-MD004: false
-MD007: false
-MD012:
- maximum: 2
-MD013: false
-MD014: false
-MD022: false
-MD024: false
-MD031: false
-MD032: false
-MD033: false
-MD034: false
-MD036: false
-MD037: false
-MD038: false
-MD041: false
-MD046: false
-MD049: false
-MD050: false
-MD051: false
-MD053: false
-MD055: false
+++ /dev/null
-**/commands/**
-**/functions/**
-**/news/**
-**/showcase/**
-**/zh/**
-**/license.md
```go-html-template
{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }}
```
+
And then in your JS file:
```js
loaders
: {{< new-in 0.140.0 />}}
-: (`map`) Configuring a loader for a given file type lets you load that file type with an `import` statement or a `require` call. For example, configuring the `.png` file extension to use the data URL loader means importing a `.png` file gives you a data URL containing the contents of that image. Loaders available are `none`, `base64`, `binary`, `copy`, `css`, `dataurl`, `default`, `empty`, `file`, `global-css`, `js`, `json`, `jsx`, `local-css`, `text`, `ts`, `tsx`. See https://esbuild.github.io/api/#loader.
+: (`map`) Configuring a loader for a given file type lets you load that file type with an `import` statement or a `require` call. For example, configuring the `.png` file extension to use the data URL loader means importing a `.png` file gives you a data URL containing the contents of that image. Loaders available are `none`, `base64`, `binary`, `copy`, `css`, `dataurl`, `default`, `empty`, `file`, `global-css`, `js`, `json`, `jsx`, `local-css`, `text`, `ts`, `tsx`. See <https://esbuild.github.io/api/#loader>.
inject
-: (`slice`) This option allows you to automatically replace a global variable with an import from another file. The path names must be relative to `assets`. See https://esbuild.github.io/api/#inject.
+: (`slice`) This option allows you to automatically replace a global variable with an import from another file. The path names must be relative to `assets`. See <https://esbuild.github.io/api/#inject>.
shims
: (`map`) This option allows swapping out a component with another. A common use case is to load dependencies like React from a CDN (with _shims_) when in production, but running with the full bundled `node_modules` dependency during development:
platform
: {{< new-in 0.140.0 />}}
-: (`string`) One of `browser`, `node`, `neutral`. Default is `browser`. See https://esbuild.github.io/api/#platform.
+: (`string`) One of `browser`, `node`, `neutral`. Default is `browser`. See <https://esbuild.github.io/api/#platform>.
externals
-: (`slice`) External dependencies. Use this to trim dependencies you know will never be executed. See https://esbuild.github.io/api/#external.
+: (`slice`) External dependencies. Use this to trim dependencies you know will never be executed. See <https://esbuild.github.io/api/#external>.
defines
: (`map`) This option allows you to define a set of string replacements to be performed when building. It must be a map where each key will be replaced by its value.
drop
: {{< new-in 0.144.0 />}}
: (`string`) Edit your source code before building to drop certain constructs: One of `debugger` or `console`.
-: See https://esbuild.github.io/api/#drop
+: See <https://esbuild.github.io/api/#drop>
sourceMap
: (`string`) Whether to generate `inline`, `linked`, or `external` source maps from esbuild. Linked and external source maps will be written to the target with the output file name + ".map". When `linked` a `sourceMappingURL` will also be written to the output file. By default, source maps are not created. Note that the `linked` option was added in Hugo 0.140.0.
JSX
: {{< new-in 0.124.0 />}}
-: (`string`) How to handle/transform JSX syntax. One of: `transform`, `preserve`, `automatic`. Default is `transform`. Notably, the `automatic` transform was introduced in React 17+ and will cause the necessary JSX helper functions to be imported automatically. See https://esbuild.github.io/api/#jsx.
+: (`string`) How to handle/transform JSX syntax. One of: `transform`, `preserve`, `automatic`. Default is `transform`. Notably, the `automatic` transform was introduced in React 17+ and will cause the necessary JSX helper functions to be imported automatically. See <https://esbuild.github.io/api/#jsx>.
JSXImportSource
: {{< new-in 0.124.0 />}}
-: (`string`) Which library to use to automatically import its JSX helper functions from. This only works if `JSX` is set to `automatic`. The specified library needs to be installed through npm and expose certain exports. See https://esbuild.github.io/api/#jsx-import-source.
+: (`string`) Which library to use to automatically import its JSX helper functions from. This only works if `JSX` is set to `automatic`. The specified library needs to be installed through npm and expose certain exports. See <https://esbuild.github.io/api/#jsx-import-source>.
The combination of `JSX` and `JSXImportSource` is helpful if you want to use a non-React JSX library like Preact, e.g.:
> You need [Go] version 1.18 or later and [Git] to use Hugo Modules. For older sites hosted on Netlify, please ensure the `GO_VERSION` environment variable is set to `1.18` or higher.
>
> Go Modules resources:
+>
> - [go.dev/wiki/Modules](https://go.dev/wiki/Modules)
> - [blog.golang.org/using-go-modules](https://go.dev/blog/using-go-modules)
Please consult your operating system documentation if you need help setting file permissions or modifying your PATH environment variable.
If you do not see a prebuilt binary for the desired edition, operating system, and architecture, install Hugo using one of the methods described below.
-
-[commit information]: /methods/page/gitinfo/
-[Git]: https://git-scm.com/
-[Go]: https://go.dev/
-[Hugo Modules]: /hugo-modules/
-[latest release]: https://github.com/gohugoio/hugo/releases/latest
{{ $taxonomyObject := .Site.Taxonomies.genres }}
```
-To capture the "genres" `Taxonomy` object when rendering its page with a taxonomy template, use the [`Terms`] method on the page's [`Data`] object:
+To capture the "genres" `Taxonomy` object when rendering its page with a _taxonomy_ template, use the [`Terms`] method on the page's [`Data`] object:
```go-html-template {file="layouts/taxonomy.html"}
{{ $taxonomyObject := .Data.Terms }}
permalinks:
posts: /:06/:1/:2/:title/
{{< /code-toggle >}}
-
-[content base name]: /methods/page/file/#contentbasename
Then call the shortcode in your Markdown:
-```text {file="content/posts/p1.md"}
-{{%/* include "/posts/p2" */%}}
+```text {file="content/posts/post-1.md"}
+{{%/* include "/posts/post-2" */%}}
```
-Any render hook triggered while rendering `/posts/p2` will get:
+Any render hook triggered while rendering `/posts/post-2` will get:
-- `/posts/p1` when calling `Page`
-- `/posts/p2` when calling `PageInner`
+- `/posts/post-1` when calling `Page`
+- `/posts/post-2` when calling `PageInner`
`PageInner` falls back to the value of `Page` if not relevant, and always returns a value.
Scope|Method or function
:--|:--
page|[`PAGE.Store`]
-site|[`SITE.Store`]
+site|[`SITE.Store`]
global|[`hugo.Store`]
local|[`collections.NewScratch`]
shortcode|[`SHORTCODE.Store`]
lineNos
: (`any`) Controls line number display. Default is `false`.
+
- `true`: Enable line numbers, controlled by `lineNumbersInTable`.
- `false`: Disable line numbers.
- `inline`: Enable inline line numbers (sets `lineNumbersInTable` to `false`).
## Performance
[Caching]
-: Reduce build time and cost by rendering a partial template once then cache the result, either globally or within a given context. For example, cache the result of an asset pipeline to prevent reprocessing on every rendered page.
+: Reduce build time and cost by rendering a _partial_ template once then cache the result, either globally or within a given context. For example, cache the result of an asset pipeline to prevent reprocessing on every rendered page.
[Segmentation]
: Reduce build time and cost by partitioning your sites into segments. For example, render the home page and the "news section" every hour, and render the entire site once a week.
[`MainSections`]: /methods/site/mainsections/
[`segments`]: /configuration/segments/
[`strings.Title`]: /functions/strings/title/
-[`strings.Title`]: /functions/strings/title
[`Summary`]: /methods/page/summary/
[`time.AsTime`]: /functions/time/astime/
[`time.Format`]: /functions/time/format/
The `build.cachebusters` configuration option was added to support development using Tailwind 3.x's JIT compiler where a `build` configuration may look like this:
+<!-- markdownlint-disable MD049 -->
{{< code-toggle file=hugo >}}
[build]
[build.buildStats]
source = "assets/.*\\.(.*)$"
target = "$1"
{{< /code-toggle >}}
+<!-- markdownlint-enable MD049 -->
When `buildStats` is enabled, Hugo writes a `hugo_stats.json` file on each build with HTML classes etc. that's used in the rendered output. Changes to this file will trigger a rebuild of the `styles.css` file. You also need to add `hugo_stats.json` to Hugo's server watcher. See [Hugo Starter Tailwind Basic](https://github.com/bep/hugo-starter-tailwind-basic) for a running example.
: (`string`) A [glob](g) pattern matching the build [environment](g). For example: `{staging,production}`.
kind
-: (`string`) A [glob](g) pattern matching the [page kind](g). For example: ` {taxonomy,term}`.
+: (`string`) A [glob](g) pattern matching the [page kind](g). For example: `{taxonomy,term}`.
lang
: (`string`) A [glob](g) pattern matching the [page language]. For example: `{en,de}`.
## Tokens
-Hugo provides several [tokens](g) to assist with front matter configuration.
+Hugo provides the following [tokens](g) to help you configure your front matter:
-Token|Description
-:--|:--
-`:default`|The default ordered sequence of date fields.
-`:fileModTime`|The file's last modification timestamp.
-`:filename`|The date from the file name, if present.
-`:git`|The Git author date for the file's last revision.
+`:default`
+: The default ordered sequence of date fields.
-When Hugo extracts a date from a file name, it uses the rest of the file name to generate the page's [`slug`], but only if a slug isn't already specified in the page's front matter. For example, given the name `2025-02-01-article.md`, Hugo will set the `date` to `2025-02-01` and the `slug` to `article`.
+`:fileModTime`
+: The file's last modification timestamp.
-[`slug`]: /content-management/front-matter/#slug
+`:filename`
+: Extracts the date from the file name, provided the file name begins with a date in one of the following formats:
-To enable access to the Git author date, set [`enableGitInfo`] to `true`, or use\
-the `--enableGitInfo` flag when building your site.
+ - `YYYY-MM-DD`
+ - `YYYY-MM-DD-HH-MM-SS` {{< new-in 0.148.0 />}}
-[`enableGitInfo`]: /configuration/all/#enablegitinfo
+ Within the `YYYY-MM-DD-HH-MM-SS` format, the date and time values may be separated by any character including a space (e.g., `2025-02-01T14-30-00`).
+
+ Hugo resolves the extracted date to the [`timeZone`] defined in your site configuration, falling back to the system time zone. After extracting the date, Hugo uses the remaining part of the file name to generate the page's [`slug`], but only if you haven't already specified a slug in the page's front matter.
+
+ For example, if you name your file `2025-02-01-article.md`, Hugo will set the date to `2025-02-01` and the slug to `article`.
-Consider this example:
+`:git`
+: The Git author date for the file's last revision. To enable access to the Git author date, set [`enableGitInfo`] to `true`, or use the `--enableGitInfo` flag when building your site.
+
+## Example
+
+Consider this site configuration:
{{< code-toggle file=hugo >}}
[frontmatter]
To determine `date`, Hugo tries to extract the date from the file name, falling back to the default ordered sequence of date fields.
To determine `lastmod`, Hugo looks for a `lastmod` field in front matter, falling back to the file's last modification timestamp.
+
+[`enableGitInfo`]: /configuration/all/#enablegitinfo
+[`slug`]: /content-management/front-matter/#slug
+[`timeZone`]: /configuration/all/#timezone
:--|:--|:-:
`cjk`|[Goldmark Extensions: CJK]|:heavy_check_mark:
`definitionList`|[PHP Markdown Extra: Definition lists]|:heavy_check_mark:
-`extras`|[Hugo Goldmark Extensions: Extras]||
+`extras`|[Hugo Goldmark Extensions: Extras]|
`footnote`|[PHP Markdown Extra: Footnotes]|:heavy_check_mark:
`linkify`|[GitHub Flavored Markdown: Autolinks]|:heavy_check_mark:
-`passthrough`|[Hugo Goldmark Extensions: Passthrough]||
+`passthrough`|[Hugo Goldmark Extensions: Passthrough]|
`strikethrough`|[GitHub Flavored Markdown: Strikethrough]|:heavy_check_mark:
`table`|[GitHub Flavored Markdown: Tables]|:heavy_check_mark:
`taskList`|[GitHub Flavored Markdown: Task list items]|:heavy_check_mark:
Subscript|`H~2~O`|`H<sub>2</sub>O`
Superscript|`1^st^`|`1<sup>st</sup>`
-To avoid a conflict when enabling the "subscript" feature of the Extras extension, if you want to render subscript and strikethrough text concurrently you must:
+To avoid a conflict[^1], if you enable the "subscript" feature of the Extras extension, you must disable the Strikethrough extension:
-1. Disable the Strikethrough extension
-1. Enable the "deleted text" feature of the Extras extension
-
-For example:
+[^1]: See [details](https://github.com/gohugoio/hugo-goldmark-extensions/commit/4d4fcd022fe45a9b51483df001c9e5f4e632d5a9).
{{< code-toggle file=hugo >}}
[markup.goldmark.extensions]
strikethrough = false
-[markup.goldmark.extensions.extras.delete]
+[markup.goldmark.extensions.extras.subscript]
enable = true
+{{< /code-toggle >}}
-[markup.goldmark.extensions.extras.subscript]
+If you still need to show deleted text after disabling the Strikethrough extension, enable the "deleted text" feature of the Extras extension:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.extensions]
+strikethrough = false
+
+[markup.goldmark.extensions.extras.delete]
enable = true
{{< /code-toggle >}}
+With this configuration, to format text as deleted, wrap it with double-tildes.
+
#### Passthrough
{{< new-in 0.122.0 />}}
`”`|`”`|right double quote
`’`|`’`|right single quote
-### Settings explained
+### Goldmark settings explained
Most of the Goldmark settings above are self-explanatory, but some require explanation.
: (`bool`) Whether to automatically add `id` attributes to headings (i.e., `h1`, `h2`, `h3`, `h4`, `h5`, and `h6` elements).
parser.autoIDType
-: (`string`) The strategy used to automatically generate `id` attributes, one of `github`, `github-ascii` or `blackfriday`.
+: (`string`) The strategy used to automatically generate `id` attributes, one of `github`, `github-ascii` or `blackfriday`. Default is `github`.
- - `github` produces GitHub-compatible `id` attributes
- - `github-ascii` drops any non-ASCII characters after accent normalization
- - `blackfriday` produces `id` attributes compatible with the Blackfriday Markdown renderer
+ - `github`: Generate GitHub-compatible `id` attributes
+ - `github-ascii`: Drop any non-ASCII characters after accent normalization
+ - `blackfriday`: Generate `id` attributes compatible with the Blackfriday Markdown renderer
- This is also the strategy used by the [anchorize](/functions/urls/anchorize) template function. Default is `github`.
+ This is also the strategy used by the [anchorize] template function.
parser.attribute.block
: (`bool`) Whether to enable [Markdown attributes] for block elements. Default is `false`.
parser.attribute.title
: (`bool`) Whether to enable [Markdown attributes] for headings. Default is `true`.
+<!-- TODO: delete this on or after July 1, 2027. -->
renderHooks.image.enableDefault
: {{< new-in 0.123.0 />}}
-: (`bool`) Whether to enable the [embedded image render hook]. Default is `false`.
+: Deprecated in v0.148.0. Use `renderHooks.image.useEmbedded` instead.
- > [!note]
- > The embedded image render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites.
+renderHooks.image.useEmbedded
+: {{< new-in 0.148.0 />}}
+: (`string`) When to use the [embedded image render hook]. One of `auto`, `never`, `always`, or `fallback`. Default is `auto`.
+ - `auto`: Automatically use the embedded image render hook for multilingual single-host sites, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such sites. If custom image render hooks are defined by your project, modules, or themes, these will be used instead.
+ - `never`: Never use the embedded image render hook. If custom image render hooks are defined by your project, modules, or themes, these will be used instead.
+ - `always`: Always use the embedded image render hook, even if custom image render hooks are provided by your project, modules, or themes. In this case, the embedded hook takes precedence.
+ - `fallback`: Use the embedded image render hook only if custom image render hooks are not provided by your project, modules, or themes. If custom image render hooks exist, these will be used instead.
+
+<!-- TODO: delete this on or after July 1, 2027. -->
renderHooks.link.enableDefault
: {{< new-in 0.123.0 />}}
-: (`bool`) Whether to enable the [embedded link render hook]. Default is `false`.
+: Deprecated in v0.148.0. Use `renderHooks.link.useEmbedded` instead.
- > [!note]
- > The embedded link render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites.
+renderHooks.link.useEmbedded
+: {{< new-in 0.148.0 />}}
+: (`string`) When to use the [embedded link render hook]. One of `auto`, `never`, `always`, or `fallback`. Default is `auto`.
+
+ - `auto`: Automatically use the embedded link render hook for multilingual single-host sites, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such sites. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
+ - `never`: Never use the embedded link render hook. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
+ - `always`: Always use the embedded link render hook, even if custom link render hooks are provided by your project, modules, or themes. In this case, the embedded hook takes precedence.
+ - `fallback`: Use the embedded link render hook only if custom link render hooks are not provided by your project, modules, or themes. If custom link render hooks exist, these will be used instead.
renderer.hardWraps
: (`bool`) Whether to replace newline characters within a paragraph with `br` elements. Default is `false`.
{{< code-toggle config=markup.asciidocExt />}}
-### Settings explained
+### AsciiDoc settings explained
attributes
: (`map`) A map of key-value pairs, each a document attribute. See Asciidoctor's [attributes].
Follow the steps below to enable syntax highlighting.
-#### Step 1
+Step 1
+: Set the `source-highlighter` attribute in your site configuration. For example:
-Set the `source-highlighter` attribute in your site configuration. For example:
+ {{< code-toggle file=hugo >}}
+ [markup.asciidocExt.attributes]
+ source-highlighter = 'rouge'
+ {{< /code-toggle >}}
-{{< code-toggle file=hugo >}}
-[markup.asciidocExt.attributes]
-source-highlighter = 'rouge'
-{{< /code-toggle >}}
+Step 2
+: Generate the highlighter CSS. For example:
-#### Step 2
+ ```text
+ rougify style monokai.sublime > assets/css/syntax.css
+ ```
-Generate the highlighter CSS. For example:
+Step 3
+: In your base template add a link to the CSS file:
-```text
-rougify style monokai.sublime > assets/css/syntax.css
-```
+ ```go-html-template {file="layouts/baseof.html"}
+ <head>
+ ...
+ {{ with resources.Get "css/syntax.css" }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
+ ...
+ </head>
+ ```
-#### Step 3
+Step 4
+: Add the code to be highlighted to your markup:
-In your base template add a link to the CSS file:
+ ```text
+ [#hello,ruby]
+ ----
+ require 'sinatra'
-```go-html-template {file="layouts/baseof.html"}
-<head>
- ...
- {{ with resources.Get "css/syntax.css" }}
- <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
- {{ end }}
- ...
-</head>
-```
-
-Then add the code to be highlighted to your markup:
-
-```text
-[#hello,ruby]
-----
-require 'sinatra'
-
-get '/hi' do
- "Hello World!"
-end
-----
-```
+ get '/hi' do
+ "Hello World!"
+ end
+ ----
+ ```
### Troubleshooting
[`Fragments.Identifiers`]: /methods/page/fragments/#identifiers
[`TableOfContents`]: /methods/page/tableofcontents/
+[anchorize]: /functions/urls/anchorize
+[AsciiDoc]: https://asciidoc.org/
[asciidoctor-diagram]: https://asciidoctor.org/docs/asciidoctor-diagram/
[attributes]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions
[CommonMark]: https://spec.commonmark.org/current/
[deleted text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/del
[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
-[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
-[embedded image render hook]: /render-hooks/images/#default
-[embedded image render hook]: /render-hooks/images/#default
-[embedded link render hook]: /render-hooks/links/#default
-[embedded link render hook]: /render-hooks/links/#default
-[GitHub Flavored Markdown]: https://github.github.com/gfm/
+[Emacs Org Mode]: https://orgmode.org/
+[embedded image render hook]: /render-hooks/images/#embedded
+[embedded link render hook]: /render-hooks/links/#embedded
[GitHub Flavored Markdown: Autolinks]: https://github.github.com/gfm/#autolinks-extension-
[GitHub Flavored Markdown: Strikethrough]: https://github.github.com/gfm/#strikethrough-extension-
[GitHub Flavored Markdown: Tables]: https://github.github.com/gfm/#tables-extension-
[GitHub Flavored Markdown: Task list items]: https://github.github.com/gfm/#task-list-items-extension-
-[Goldmark]: https://github.com/yuin/goldmark/
+[GitHub Flavored Markdown]: https://github.github.com/gfm/
[Goldmark Extensions: CJK]: https://github.com/yuin/goldmark?tab=readme-ov-file#cjk-extension
[Goldmark Extensions: Typographer]: https://github.com/yuin/goldmark?tab=readme-ov-file#typographer-extension
+[Goldmark]: https://github.com/yuin/goldmark/
[Hugo Goldmark Extensions: Extras]: https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#extras-extension
[Hugo Goldmark Extensions: Passthrough]: https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#passthrough-extension
[image render hook]: /render-hooks/images/
[Markdown attributes]: /content-management/markdown-attributes/
[mathematics in Markdown]: content-management/mathematics/
[multilingual page resources]: /content-management/page-resources/#multilingual
+[Pandoc]: https://pandoc.org/
[PHP Markdown Extra: Definition lists]: https://michelf.ca/projects/php-markdown/extra/#def-list
[PHP Markdown Extra: Footnotes]: https://michelf.ca/projects/php-markdown/extra/#footnotes
+[reStructuredText]: https://docutils.sourceforge.io/rst.html
[security policy]: /configuration/security/
[subscript]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sub
[superscript]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sup
-[AsciiDoc]: https://asciidoc.org/
-[Emacs Org Mode]: https://orgmode.org/
-[Pandoc]: https://pandoc.org/
-[reStructuredText]: https://docutils.sourceforge.io/rst.html
This nested menu demonstrates some of the available properties:
+<!-- markdownlint-disable MD033 -->
{{< code-toggle file=hugo >}}
[[menus.main]]
name = 'Products'
[menus.main.params]
rel = 'external'
{{< /code-toggle >}}
+<!-- markdownlint-enable MD033 -->
[`Menus`]: /methods/site/menus/
[Automatically]: /content-management/menus/#define-automatically
This is the default configuration:
+<!-- markdownlint-disable MD049 -->
{{< code-toggle file=hugo >}}
[module]
noProxy = 'none'
vendorClosest = false
workspace = 'off'
{{< /code-toggle >}}
+<!-- markdownlint-enable MD049 -->
auth
: {{< new-in 0.144.0 />}}
: (`bool`) Whether the extended edition of Hugo is required, satisfied by installing either the extended or extended/deploy edition.
max
-: (`string`) The maximum Hugo version supported, for example `0.143.0`.
+: (`string`) The maximum Hugo version supported, for example `0.148.0`.
min
-: (`string`) The minimum Hugo version supported, for example `0.123.0`.
-
-[`themesDir`]: /configuration/all/#themesdir
+: (`string`) The minimum Hugo version supported, for example `0.102.0`.
## Imports
path
: (`string`) The module path, either a valid Go module path (e.g., `github.com/gohugoio/myShortcodes`) or the directory name if stored in the [`themesDir`].
-[`themesDir`]: /configuration/all#themesDir
-
{{% include "/_common/gomodules-info.md" %}}
## Mounts
source="assets"
target="assets"
{{< /code-toggle >}}
+
+[`themesDir`]: /configuration/all/#themesdir
: (`bool`) Whether to classify the output format as HTML. Hugo uses this value to determine when to create alias redirects and when to inject the LiveReload script. Default is `false`.
isPlainText
-: (`bool`) Whether to parse templates for this output format with Go's [text/template] package instead of the [html/template] package. Default is `false`.
+: (`bool`) Whether to parse templates for this output format with Go's [text/template][] package instead of the [html/template][] package. Default is `false`.
mediaType
-: (`string`) The [media type](g) of the published file. This must match one of the [configured media types].
+: (`string`) The [media type](g) of the published file. This must match one of the [configured media types][].
notAlternative
-: (`bool`) Whether to exclude this output format from the values returned by the [`AlternativeOutputFormats`] method on a `Page` object. Default is `false`.
+: (`bool`) Whether to exclude this output format from the values returned by the [`AlternativeOutputFormats`][] method on a `Page` object. Default is `false`.
noUgly
-: (`bool`) Whether to disable ugly URLs for this output format when [`uglyURLs`] are enabled in your site configuration. Default is `false`.
+: (`bool`) Whether to disable ugly URLs for this output format when [`uglyURLs`][] are enabled in your site configuration. Default is `false`.
path
-: (`string`) The published file's directory path, relative to the root of the publish directory. If not specified, the file will be published using its content path.
+: (`string`) The first segment of the publication path for this output format. This path segment is relative to the root of your [`publishDir`][]. If omitted, Hugo will use the file's original content path for publishing.
permalinkable
-: (`bool`) Whether to return the rendering output format rather than main output format when invoking the [`Permalink`] and [`RelPermalink`] methods on a `Page` object. See [details](#link-to-output-formats). Enabled by default for the `html` and `amp` output formats. Default is `false`.
+: (`bool`) Whether to return the rendering output format rather than main output format when invoking the [`Permalink`][] and [`RelPermalink`][] methods on a `Page` object. See [details](#link-to-output-formats). Enabled by default for the `html` and `amp` output formats. Default is `false`.
protocol
-: (`string`) The protocol (scheme) of the URL for this output format. For example, `https://` or `webcal://`. Default is the scheme of the [`baseURL`] parameter in your site configuration, typically `https://`.
+: (`string`) The protocol (scheme) of the URL for this output format. For example, `https://` or `webcal://`. Default is the scheme of the [`baseURL`][] parameter in your site configuration, typically `https://`.
rel
: (`string`) If provided, you can assign this value to `rel` attributes in `link` elements when iterating over output formats in your templates. Default is `alternate`.
You can create new output formats as needed. For example, you may wish to create an output format to support Atom feeds.
-### Step 1
+Step 1
+: Output formats require a specified media type. Because Atom feeds use `application/atom+xml`, which is not one of the [default media types][], you must create it first.
-Output formats require a specified media type. Because Atom feeds use `application/atom+xml`, which is not one of the [default media types], you must create it first.
+ {{< code-toggle file=hugo >}}
+ [mediaTypes.'application/atom+xml']
+ suffixes = ['atom']
+ {{< /code-toggle >}}
-{{< code-toggle file=hugo >}}
-[mediaTypes.'application/atom+xml']
-suffixes = ['atom']
-{{< /code-toggle >}}
-
-See [configure media types] for more information.
-
-### Step 2
-
-Create a new output format:
-
-{{< code-toggle file=hugo >}}
-[outputFormats.atom]
-mediaType = 'application/atom+xml'
-noUgly = true
-{{< /code-toggle >}}
+ See [configure media types][] for more information.
-Note that we use the default settings for all other output format properties.
+Step 2
+: Create a new output format:
-### Step 3
+ {{< code-toggle file=hugo >}}
+ [outputFormats.atom]
+ mediaType = 'application/atom+xml'
+ noUgly = true
+ {{< /code-toggle >}}
-Specify the page [kinds](g) for which to render this output format:
+ Note that we use the default settings for all other output format properties.
-{{< code-toggle file=hugo >}}
-[outputs]
-home = ['html', 'rss', 'atom']
-section = ['html', 'rss', 'atom']
-taxonomy = ['html', 'rss', 'atom']
-term = ['html', 'rss', 'atom']
-{{< /code-toggle >}}
+Step 3
+: Specify the page [kinds](g) for which to render this output format:
-See [configure outputs] for more information.
+ {{< code-toggle file=hugo >}}
+ [outputs]
+ home = ['html', 'rss', 'atom']
+ section = ['html', 'rss', 'atom']
+ taxonomy = ['html', 'rss', 'atom']
+ term = ['html', 'rss', 'atom']
+ {{< /code-toggle >}}
-### Step 4
+ See [configure outputs][] for more information.
-Create a template to render the output format. Since Atom feeds are lists, you need to create a list template. Consult the [template lookup order] to find the correct template path:
+Step 4
+: Create a template to render the output format. Since Atom feeds are lists, you need to create a list template. Consult the [template lookup order] to find the correct template path:
-```text
-layouts/list.atom.atom
-```
+ ```text
+ layouts/list.atom.atom
+ ```
-We leave writing the template code as an exercise for you. Aim for a result similar to the [embedded RSS template].
+ We leave writing the template code as an exercise for you. Aim for a result similar to the [embedded RSS template][].
## List output formats
-To access output formats, each `Page` object provides two methods: [`OutputFormats`] (for all formats, including the current one) and [`AlternativeOutputFormats`]. Use `AlternativeOutputFormats` to create a link `rel` list within your site's `head` element, as shown below:
+To access output formats, each `Page` object provides two methods: [`OutputFormats`][] (for all formats, including the current one) and [`AlternativeOutputFormats`][]. Use `AlternativeOutputFormats` to create a link `rel` list within your site's `head` element, as shown below:
```go-html-template
{{ range .AlternativeOutputFormats }}
## Link to output formats
-By default, a `Page` object's [`Permalink`] and [`RelPermalink`] methods return the URL of the [primary output format](g), typically `html`. This behavior remains consistent regardless of the template used.
+By default, a `Page` object's [`Permalink`][] and [`RelPermalink`][] methods return the URL of the [primary output format](g), typically `html`. This behavior remains consistent regardless of the template used.
For example, in `page.json.json`, you'll see:
{{ end }}
```
-To make these methods return the URL of the _current_ template's output format, you must set the [`permalinkable`] setting to `true` for that format.
+To make these methods return the URL of the _current_ template's output format, you must set the [`permalinkable`][] setting to `true` for that format.
With `permalinkable` set to true for `json` in the same `page.json.json` template:
## Template lookup order
-Each output format requires a template conforming to the [template lookup order].
+Each output format requires a template conforming to the [template lookup order][].
For the highest specificity in the template lookup order, include the page kind, output format, and suffix in the file name:
`rss`|`layouts/section.rss.xml`
[`AlternativeOutputFormats`]: /methods/page/alternativeoutputformats/
+[`baseURL`]: /configuration/all/#baseurl
[`OutputFormats`]: /methods/page/outputformats/
[`Permalink`]: /methods/page/permalink/
-[`RelPermalink`]: /methods/page/relpermalink/
-[`baseURL`]: /configuration/all/#baseurl
[`permalinkable`]: #permalinkable
+[`publishDir`]: /configuration/all/#publishdir
+[`RelPermalink`]: /methods/page/relpermalink/
[`uglyURLs`]: /configuration/ugly-urls/
[configure media types]: /configuration/media-types/
[configure outputs]: /configuration/outputs/
[configured media types]: /configuration/media-types/
[default media types]: /configuration/media-types/
-[embedded RSS template]: {{% eturl rss %}}
+[embedded RSS template]: <{{% eturl rss %}}>
[html/template]: https://pkg.go.dev/html/template
[template lookup order]: /templates/lookup-order/
[text/template]: https://pkg.go.dev/text/template
We've configured the `authors` index with a weight of `2` and the `genres` index with a weight of `1`. This means Hugo prioritizes shared `authors` as twice as significant as shared `genres`.
-Then render a list of 5 related reviews with a partial template like this:
+Then render a list of 5 related reviews with a _partial_ template like this:
```go-html-template {file="layouts/_partials/related.html" copy=true}
{{ with site.RegularPages.Related . | first 5 }}
keywords: []
---
-Hugo's built-in security policy, which restricts access to `os/exec`, remote communication, and similar operations, is configured via allow lists. By default, access is restricted. If a build attempts to use a feature not included in the allow list, it will fail, providing a detailed message.
+Hugo's built-in security policy, which restricts access to `os/exec`, remote communication, and similar operations, is configured via allowlists. By default, access is restricted. If a build attempts to use a feature not included in the allowlist, it will fail, providing a detailed message.
This is the default security configuration:
: (`[]string`) A slice of [regular expressions](g) matching the URLs that the `resources.GetRemote` function is allowed to access.
> [!note]
-> Setting an allow list to the string `none` will completely disable the associated feature.
+> Setting an allowlist to the string `none` will completely disable the associated feature.
You can also override the site configuration with environment variables. For example, to block `resources.GetRemote` from accessing any URL:
Available fields for filtering:
kind
-: (`string`) A [glob](g) pattern matching the [page kind](g). For example: ` {taxonomy,term}`.
+: (`string`) A [glob](g) pattern matching the [page kind](g). For example: `{taxonomy,term}`.
lang
: (`string`) A [glob](g) pattern matching the [page language]. For example: `{en,de}`.
## Headers
-Include headers in every server response to facilitate testing, particularly for features like Content Security Policies.
+Include headers in every server response to facilitate testing, particularly for features like [Content Security Policies].
[Content Security Policies]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
Then use the value as the key in front matter:
+<!-- markdownlint-disable MD007 MD032 -->
{{< code-toggle file=content/example.md fm=true >}}
----
title: Example
categories:
- vegetarian
- appetizer
- main course
{{< /code-toggle >}}
-
+<!-- markdownlint-enable MD007 MD032 -->
If you do not expect to assign more than one [term](g) from a given taxonomy to a content page, you may use the singular form for both key and value:
{{< code-toggle file=hugo >}}
Then in front matter:
+<!-- markdownlint-disable MD007 MD032 -->
{{< code-toggle file=content/example.md fm=true >}}
----
title: Example
author:
- Robert Smith
{{< /code-toggle >}}
+<!-- markdownlint-enable MD007 MD032 -->
The example above illustrates that even with a single term, the value is still provided as an array.
```
In its default configuration, Hugo generates [pretty URLs](g). For example:
+
```text
https://example.org/section/article/
```
[configuration]: /configuration/
[disquspartial]: /templates/embedded/#disqus
[disqussetup]: https://disqus.com/profile/signup/
-[forum]: https://discourse.gohugo.io
[front matter]: /content-management/front-matter/
-[kaijuissue]: https://github.com/spf13/kaiju/issues/new
-[issotutorial]: https://stiobhart.net/2017-02-24-isso-comments/
-[partials]: /templates/partial/
-[MongoDB]: https://www.mongodb.com/
Create pages from remote data, where each page represents a book review.
-### Step 1
-
-Create the content structure.
-
-```text
-content/
-└── books/
- ├── _content.gotmpl <-- content adapter
- └── _index.md
-```
-
-### Step 2
-Inspect the remote data to determine how to map key-value pairs to front matter fields.\
-<https://gohugo.io/shared/examples/data/books.json>
-
-### Step 3
-
-Create the content adapter.
-
-```go-html-template {file="content/books/_content.gotmpl" copy=true}
-{{/* Get remote data. */}}
-{{ $data := dict }}
-{{ $url := "https://gohugo.io/shared/examples/data/books.json" }}
-{{ with try (resources.GetRemote $url) }}
- {{ with .Err }}
- {{ errorf "Unable to get remote resource %s: %s" $url . }}
- {{ else with .Value }}
- {{ $data = . | transform.Unmarshal }}
- {{ else }}
- {{ errorf "Unable to get remote resource %s" $url }}
+Step 1
+: Create the content structure.
+
+ ```text
+ content/
+ └── books/
+ ├── _content.gotmpl <-- content adapter
+ └── _index.md
+ ```
+
+Step 2
+: Inspect the remote data to determine how to map key-value pairs to front matter fields.\
+ <https://gohugo.io/shared/examples/data/books.json>
+
+Step 3
+: Create the content adapter.
+
+ ```go-html-template {file="content/books/_content.gotmpl" copy=true}
+ {{/* Get remote data. */}}
+ {{ $data := dict }}
+ {{ $url := "https://gohugo.io/shared/examples/data/books.json" }}
+ {{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ errorf "Unable to get remote resource %s: %s" $url . }}
+ {{ else with .Value }}
+ {{ $data = . | transform.Unmarshal }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %s" $url }}
+ {{ end }}
{{ end }}
-{{ end }}
-{{/* Add pages and page resources. */}}
-{{ range $data }}
-
- {{/* Add page. */}}
- {{ $content := dict "mediaType" "text/markdown" "value" .summary }}
- {{ $dates := dict "date" (time.AsTime .date) }}
- {{ $params := dict "author" .author "isbn" .isbn "rating" .rating "tags" .tags }}
- {{ $page := dict
- "content" $content
- "dates" $dates
- "kind" "page"
- "params" $params
- "path" .title
- "title" .title
- }}
- {{ $.AddPage $page }}
-
- {{/* Add page resource. */}}
- {{ $item := . }}
- {{ with $url := $item.cover }}
- {{ with try (resources.GetRemote $url) }}
- {{ with .Err }}
- {{ errorf "Unable to get remote resource %s: %s" $url . }}
- {{ else with .Value }}
- {{ $content := dict "mediaType" .MediaType.Type "value" .Content }}
- {{ $params := dict "alt" $item.title }}
- {{ $resource := dict
- "content" $content
- "params" $params
- "path" (printf "%s/cover.%s" $item.title .MediaType.SubType)
- }}
- {{ $.AddResource $resource }}
- {{ else }}
- {{ errorf "Unable to get remote resource %s" $url }}
+ {{/* Add pages and page resources. */}}
+ {{ range $data }}
+
+ {{/* Add page. */}}
+ {{ $content := dict "mediaType" "text/markdown" "value" .summary }}
+ {{ $dates := dict "date" (time.AsTime .date) }}
+ {{ $params := dict "author" .author "isbn" .isbn "rating" .rating "tags" .tags }}
+ {{ $page := dict
+ "content" $content
+ "dates" $dates
+ "kind" "page"
+ "params" $params
+ "path" .title
+ "title" .title
+ }}
+ {{ $.AddPage $page }}
+
+ {{/* Add page resource. */}}
+ {{ $item := . }}
+ {{ with $url := $item.cover }}
+ {{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ errorf "Unable to get remote resource %s: %s" $url . }}
+ {{ else with .Value }}
+ {{ $content := dict "mediaType" .MediaType.Type "value" .Content }}
+ {{ $params := dict "alt" $item.title }}
+ {{ $resource := dict
+ "content" $content
+ "params" $params
+ "path" (printf "%s/cover.%s" $item.title .MediaType.SubType)
+ }}
+ {{ $.AddResource $resource }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %s" $url }}
+ {{ end }}
{{ end }}
{{ end }}
- {{ end }}
-
-{{ end }}
-```
-### Step 4
-
-Create a page template to render each book review.
+ {{ end }}
+ ```
-```go-html-template {file="layouts/books/page.html" copy=true}
-{{ define "main" }}
- <h1>{{ .Title }}</h1>
+Step 4
+: Create a _page_ template to render each book review.
- {{ with .Resources.GetMatch "cover.*" }}
- <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="{{ .Params.alt }}">
- {{ end }}
+ ```go-html-template {file="layouts/books/page.html" copy=true}
+ {{ define "main" }}
+ <h1>{{ .Title }}</h1>
- <p>Author: {{ .Params.author }}</p>
+ {{ with .Resources.GetMatch "cover.*" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="{{ .Params.alt }}">
+ {{ end }}
- <p>
- ISBN: {{ .Params.isbn }}<br>
- Rating: {{ .Params.rating }}<br>
- Review date: {{ .Date | time.Format ":date_long" }}
- </p>
+ <p>Author: {{ .Params.author }}</p>
+
+ <p>
+ ISBN: {{ .Params.isbn }}<br>
+ Rating: {{ .Params.rating }}<br>
+ Review date: {{ .Date | time.Format ":date_long" }}
+ </p>
+
+ {{ with .GetTerms "tags" }}
+ <p>Tags:</p>
+ <ul>
+ {{ range . }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+ {{ end }}
- {{ with .GetTerms "tags" }}
- <p>Tags:</p>
- <ul>
- {{ range . }}
- <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
- {{ end }}
- </ul>
+ {{ .Content }}
{{ end }}
-
- {{ .Content }}
-{{ end }}
-```
+ ```
## Multilingual sites
```
[AsciiDoc]: https://asciidoc.org/
-[configure the AsciiDoc renderer]: /configuration/markup/#asciidoc
[configure asciidoc]: /configuration/markup/#asciidoc
### Pandoc
Provide front matter using a serialization format, one of [JSON], [TOML], or [YAML]. Hugo determines the front matter format by examining the delimiters that separate the front matter from the page content.
-[json]: https://www.json.org/
-[toml]: https://toml.io/
-[yaml]: https://yaml.org/
-
See examples of front matter delimiters by toggling between the serialization formats below.
{{< code-toggle file=content/example.md fm=true >}}
: (`map`) A map of sitemap options. See the [sitemap templates] page for details. Access these values from a template using the [`Sitemap`] method on a `Page` object.
slug
-: (`string`) Overrides the last segment of the URL path. Not applicable to section pages. See the [URL management] page for details. Access this value from a template using the [`Slug`] method on a `Page` object.
+: (`string`) Overrides the last segment of the URL path. Not applicable to `home`, `section`, `taxonomy`, or `term` pages. See the [URL management] page for details. Access this value from a template using the [`Slug`] method on a `Page` object.
summary
: (`string`) Conceptually different than the page `description`, the summary either summarizes the content or serves as a teaser to encourage readers to visit the page. Access this value from a template using the [`Summary`] method on a `Page` object.
weight
: (`int`) The page [weight](g), used to order the page within a [page collection](g). Access this value from a template using the [`Weight`] method on a `Page` object.
-[URL management]: /content-management/urls/#slug
-[`Summary`]: /methods/page/summary/
-[`aliases`]: /methods/page/aliases/
-[`date`]: /methods/page/date/
-[`description`]: /methods/page/description/
-[`draft`]: /methods/page/draft/
-[`expirydate`]: /methods/page/expirydate/
-[`fuzzywordcount`]: /methods/page/wordcount/
-[`keywords`]: /methods/page/keywords/
-[`lastmod`]: /methods/page/date/
-[`layout`]: /methods/page/layout/
-[`linktitle`]: /methods/page/linktitle/
-[`publishdate`]: /methods/page/publishdate/
-[`readingtime`]: /methods/page/readingtime/
-[`sitemap`]: /methods/page/sitemap/
-[`slug`]: /methods/page/slug/
-[`summary`]: /methods/page/summary/
-[`title`]: /methods/page/title/
-[`translationkey`]: /methods/page/translationkey/
-[`type`]: /methods/page/type/
-[`weight`]: /methods/page/weight/
-[`wordcount`]: /methods/page/wordcount/
-[aliases]: /content-management/urls/#aliases
-[build options]: /content-management/build-options/
-[cascade]: #cascade-1
-[configure outputs]: /configuration/outputs/#outputs-per-page
-[content formats]: /content-management/formats/#classification
-[leaf bundles]: /content-management/page-bundles/#leaf-bundles
-[menus]: /content-management/menus/#define-in-front-matter
-[output formats]: /configuration/output-formats/
-[page parameters]: #parameters
-[page resources]: /content-management/page-resources/#metadata
-[sitemap templates]: /templates/sitemap/
-[target a specific template]: /templates/lookup-order/#target-a-template
-[template lookup order]: /templates/lookup-order/
-
## Parameters
{{< new-in 0.123.0 />}}
Access these values from a template using the [`Params`] or [`Param`] method on a `Page` object.
-[`param`]: /methods/page/param/
-[`params`]: /methods/page/params/
-
Hugo provides [embedded templates] to optionally insert meta data within the `head` element of your rendered pages. These embedded templates expect the following front matter parameters:
Parameter|Data type|Used by these embedded templates
{{ end }}
```
-[`Params`]: /methods/page/params/
[`GetTerms`]: /methods/page/getterms/
## Cascade
: (`string`) A [glob](g) pattern matching the build [environment](g). For example: `{staging,production}`.
kind
-: (`string`) A [glob](g) pattern matching the [page kind](g). For example: ` {taxonomy,term}`.
+: (`string`) A [glob](g) pattern matching the [page kind](g). For example: `{taxonomy,term}`.
path
: (`string`) A [glob](g) pattern matching the page's [logical path](g). For example: `{/books,/books/**}`.
1. The time zone specified in your site configuration
1. The `Etc/UTC` time zone
+[`aliases`]: /methods/page/aliases/
+[`date`]: /methods/page/date/
+[`description`]: /methods/page/description/
+[`draft`]: /methods/page/draft/
+[`expirydate`]: /methods/page/expirydate/
+[`fuzzywordcount`]: /methods/page/wordcount/
+[`keywords`]: /methods/page/keywords/
+[`lastmod`]: /methods/page/date/
+[`layout`]: /methods/page/layout/
+[`linktitle`]: /methods/page/linktitle/
[`opengraph.html`]: {{% eturl opengraph %}}
+[`Param`]: /methods/page/param/
+[`Params`]: /methods/page/params/
+[`publishdate`]: /methods/page/publishdate/
+[`readingtime`]: /methods/page/readingtime/
[`schema.html`]: {{% eturl schema %}}
+[`sitemap`]: /methods/page/sitemap/
+[`slug`]: /methods/page/slug/
+[`Summary`]: /methods/page/summary/
+[`title`]: /methods/page/title/
+[`translationkey`]: /methods/page/translationkey/
[`twitter_cards.html`]: {{% eturl twitter_cards %}}
+[`type`]: /methods/page/type/
+[`weight`]: /methods/page/weight/
+[`wordcount`]: /methods/page/wordcount/
+[aliases]: /content-management/urls/#aliases
+[build options]: /content-management/build-options/
+[cascade]: #cascade-1
+[configure outputs]: /configuration/outputs/#outputs-per-page
+[content formats]: /content-management/formats/#classification
[embedded templates]: /templates/embedded/
+[json]: https://www.json.org/
+[leaf bundles]: /content-management/page-bundles/#leaf-bundles
+[menus]: /content-management/menus/#define-in-front-matter
+[output formats]: /configuration/output-formats/
+[page parameters]: #parameters
+[page resources]: /content-management/page-resources/#metadata
+[sitemap templates]: /templates/sitemap/
+[target a specific template]: /templates/lookup-order/#target-a-template
+[template lookup order]: /templates/lookup-order/
+[toml]: https://toml.io/
+[URL management]: /content-management/urls/#slug
+[yaml]: https://yaml.org/
Follow these instructions to include mathematical equations and expressions in your Markdown using LaTeX markup.
-### Step 1
+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.
-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.
+ {{< code-toggle file=hugo copy=true >}}
+ [markup.goldmark.extensions.passthrough]
+ enable = true
-{{< code-toggle file=hugo copy=true >}}
-[markup.goldmark.extensions.passthrough]
-enable = true
+ [markup.goldmark.extensions.passthrough.delimiters]
+ block = [['\[', '\]'], ['$$', '$$']]
+ inline = [['\(', '\)']]
-[markup.goldmark.extensions.passthrough.delimiters]
-block = [['\[', '\]'], ['$$', '$$']]
-inline = [['\(', '\)']]
+ [params]
+ math = true
+ {{< /code-toggle >}}
-[params]
-math = true
-{{< /code-toggle >}}
+ The configuration above enables mathematical rendering on every page unless you set the `math` parameter to `false` in front matter. To enable mathematical rendering as needed, set the `math` parameter to `false` in your site configuration, and set the `math` parameter to `true` in front matter. Use this parameter in your base template as shown in [Step 3](#step-3).
-The configuration above enables mathematical rendering on every page unless you set the `math` parameter to `false` in front matter. To enable mathematical rendering as needed, set the `math` parameter to `false` in your site configuration, and set the `math` parameter to `true` in front matter. Use this parameter in your base template as shown in [Step 3].
+ > [!note]
+ > The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration and JavaScript, you must double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting.
+ >
+ > See the [inline delimiters](#inline-delimiters) section for details.
-> [!note]
-> The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration and JavaScript, you must double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting.
->
-> See the [inline delimiters](#inline-delimiters) section for details.
+ To disable passthrough of inline snippets, omit the `inline` key from the configuration:
-To disable passthrough of inline snippets, omit the `inline` key from the configuration:
+ {{< code-toggle file=hugo >}}
+ [markup.goldmark.extensions.passthrough.delimiters]
+ block = [['\[', '\]'], ['$$', '$$']]
+ {{< /code-toggle >}}
-{{< code-toggle file=hugo >}}
-[markup.goldmark.extensions.passthrough.delimiters]
-block = [['\[', '\]'], ['$$', '$$']]
-{{< /code-toggle >}}
+ You can define your own opening and closing delimiters, provided they match the delimiters that you set in [Step 2].
-You can define your own opening and closing delimiters, provided they match the delimiters that you set in [Step 2].
+ {{< code-toggle file=hugo >}}
+ [markup.goldmark.extensions.passthrough.delimiters]
+ block = [['@@', '@@']]
+ inline = [['@', '@']]
+ {{< /code-toggle >}}
-{{< code-toggle file=hugo >}}
-[markup.goldmark.extensions.passthrough.delimiters]
-block = [['@@', '@@']]
-inline = [['@', '@']]
-{{< /code-toggle >}}
+Step 2
+: Create a _partial_ template to load MathJax or KaTeX. The example below loads MathJax, or you can use KaTeX as described in the [engines](#engines) section.
-### Step 2
+ ```go-html-template {file="layouts/_partials/math.html" copy=true}
+ <script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>
+ <script>
+ MathJax = {
+ tex: {
+ displayMath: [['\\[', '\\]'], ['$$', '$$']], // block
+ inlineMath: [['\\(', '\\)']] // inline
+ },
+ loader:{
+ load: ['ui/safe']
+ },
+ };
+ </script>
+ ```
-Create a partial template to load MathJax or KaTeX. The example below loads MathJax, or you can use KaTeX as described in the [engines](#engines) section.
+ The delimiters above must match the delimiters in your site configuration.
-```go-html-template {file="layouts/_partials/math.html" copy=true}
-<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>
-<script>
- MathJax = {
- tex: {
- displayMath: [['\\[', '\\]'], ['$$', '$$']], // block
- inlineMath: [['\\(', '\\)']] // inline
- },
- loader:{
- load: ['ui/safe']
- },
- };
-</script>
-```
+Step 3
+: Conditionally call the _partial_ template from the base template.
-The delimiters above must match the delimiters in your site configuration.
+ ```go-html-template {file="layouts/baseof.html"}
+ <head>
+ ...
+ {{ if .Param "math" }}
+ {{ partialCached "math.html" . }}
+ {{ end }}
+ ...
+ </head>
+ ```
-### Step 3
+ The example above loads the _partial_ template if you have set the `math` parameter in front matter to `true`. If you have not set the `math` parameter in front matter, the conditional statement falls back to the `math` parameter in your site configuration.
-Conditionally call the partial template from the base template.
+Step 4
+: If you set the `math` parameter to `false` in your site configuration, you must set the `math` parameter to `true` in front matter. For example:
-```go-html-template {file="layouts/baseof.html"}
-<head>
- ...
- {{ if .Param "math" }}
- {{ partialCached "math.html" . }}
- {{ end }}
- ...
-</head>
-```
+ {{< code-toggle file=content/math-examples.md fm=true >}}
+ title = 'Math examples'
+ date = 2024-01-24T18:09:49-08:00
+ [params]
+ math = true
+ {{< /code-toggle >}}
-The example above loads the partial template if you have set the `math` parameter in front matter to `true`. If you have not set the `math` parameter in front matter, the conditional statement falls back to the `math` parameter in your site configuration.
+Step 5
+: Include mathematical equations and expressions in Markdown using LaTeX markup.
-### Step 4
+ ```text {file="content/math-examples.md" copy=true}
+ This is an inline \(a^*=x-b^*\) equation.
-Include mathematical equations and expressions in Markdown using LaTeX markup.
+ These are block equations:
-```text {file="content/math-examples.md" copy=true}
-This is an inline \(a^*=x-b^*\) equation.
+ \[a^*=x-b^*\]
-These are block equations:
+ \[ a^*=x-b^* \]
-\[a^*=x-b^*\]
+ \[
+ a^*=x-b^*
+ \]
-\[ a^*=x-b^* \]
+ These are also block equations:
-\[
-a^*=x-b^*
-\]
-
-These are also block equations:
-
-$$a^*=x-b^*$$
-
-$$ a^*=x-b^* $$
-
-$$
-a^*=x-b^*
-$$
-```
+ $$a^*=x-b^*$$
-If you set the `math` parameter to `false` in your site configuration, you must set the `math` parameter to `true` in front matter. For example:
+ $$ a^*=x-b^* $$
-{{< code-toggle file=content/math-examples.md fm=true >}}
-title = 'Math examples'
-date = 2024-01-24T18:09:49-08:00
-[params]
-math = true
-{{< /code-toggle >}}
+ $$
+ a^*=x-b^*
+ $$
+ ```
## Inline delimiters
>
>See the [inline delimiters](#inline-delimiters) section for details.
-To use KaTeX instead of MathJax, replace the partial template from [Step 2] with this:
+To use KaTeX instead of MathJax, replace the _partial_ template from [Step 2] with this:
```go-html-template {file="layouts/_partials/math.html" copy=true}
<link
$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$
-As shown in [Step 2] above, MathJax supports chemical equations without additional configuration. To add chemistry support to KaTeX, enable the mhchem extension as described in the KaTeX [documentation](https://katex.org/docs/libs).
+As shown in [Step 2](#step-2) above, MathJax supports chemical equations without additional configuration. To add chemistry support to KaTeX, enable the mhchem extension as described in the KaTeX [documentation](https://katex.org/docs/libs).
[`transform.ToMath`]: /functions/transform/tomath/
[KaTeX]: https://katex.org/
[LaTeX]: https://www.latex-project.org/
[MathJax]: https://www.mathjax.org/
[passthrough extension]: /configuration/markup/#passthrough
-[Step 2]: #step-2
-[Step 3]: #step-3
This front matter menu entry demonstrates some of the available properties:
+<!-- markdownlint-disable MD033 -->
{{< code-toggle file=content/products/software.md fm=true >}}
title = 'Software'
[menus.main]
[menus.main.params]
class = 'center'
{{< /code-toggle >}}
+<!-- markdownlint-enable MD033 -->
Access the entry with `site.Menus.main` in your templates. See [menu templates] for details.
The first file is assigned the English language and is linked to the second.
The second file is assigned the French language and is linked to the first.
-Their language is __assigned__ according to the language code added as a __suffix to the file name__.
+Their language is assigned according to the language code added as a suffix to the file name.
-By having the same **path and base file name**, the content pieces are __linked__ together as translated pages.
+By having the same path and base file name, the content pieces are linked together as translated pages.
> [!note]
> If a file has no language code, it will be assigned the default language.
The first file is assigned the English language and is linked to the second.
The second file is assigned the French language and is linked to the first.
-Their language is __assigned__ according to the `content` directory they are __placed__ in.
+Their language is assigned according to the `content` directory they are placed in.
-By having the same **path and basename** (relative to their language `content` directory), the content pieces are __linked__ together as translated pages.
+By having the same path and basename (relative to their language `content` directory), the content pieces are linked together as translated pages.
### Bypassing default linking
translationKey: "about"
{{< /code-toggle >}}
-By setting the `translationKey` front matter parameter to `about` in all three pages, they will be __linked__ as translated pages.
+By setting the `translationKey` front matter parameter to `about` in all three pages, they will be linked as translated pages.
### Localizing permalinks
{{ end }}
```
-The above can be put in a partial template then included in any template. It will not print anything if there are no translations for a given page.
+The above can be put in a _partial_ template then included in any template. It will not print anything if there are no translations for a given page.
The above also uses the [`i18n` function][i18func] described in the next section.
### `section`
-A default content type is determined by the section in which a content item is stored. `section` is determined by the location within the project's `content` directory. `section` *cannot* be specified or overridden in front matter.
+A default content type is determined by the section in which a content item is stored. `section` is determined by the location within the project's `content` directory. `section` cannot be specified or overridden in front matter.
### `slug`
| | Leaf bundle | Branch bundle |
|---------------------|---------------------------------------------------------|---------------------------------------------------------|
-| Index file | `index.md` | `_index.md` |
-| Example | `content/about/index.md` | `content/posts/_index.md ` |
+| Index file | `index.md` | `_index.md` |
+| Example | `content/about/index.md` | `content/posts/_index.md` |
| [Page kinds](g) | `page` | `home`, `section`, `taxonomy`, or `term` |
-| Template types | [single] | [home], [section], [taxonomy], or [term] |
+| Template types | [single] | [home], [section], [taxonomy], or [term] |
| Descendant pages | None | Zero or more |
| Resource location | Adjacent to the index file or in a nested subdirectory | Same as a leaf bundles, but excludes descendant bundles |
| [Resource types](g) | `page`, `image`, `video`, etc. | all but `page` |
Use any of these methods on a `Page` object to capture page resources:
- - [`Resources.ByType`]
- - [`Resources.Get`]
- - [`Resources.GetMatch`]
- - [`Resources.Match`]
+- [`Resources.ByType`]
+- [`Resources.Get`]
+- [`Resources.GetMatch`]
+- [`Resources.Match`]
Once you have captured a resource, use any of the applicable [`Resource`] methods to return a value or perform an action.
### Resources metadata example
+<!-- markdownlint-disable MD007 MD032 -->
{{< code-toggle file=content/example.md fm=true >}}
title: Application
-date : 2018-01-25
-resources :
-- src : "images/sunset.jpg"
- name : "header"
-- src : "documents/photo_specs.pdf"
- title : "Photo Specifications"
- params:
- icon : "photo"
-- src : "documents/guide.pdf"
- title : "Instruction Guide"
-- src : "documents/checklist.pdf"
- title : "Document Checklist"
-- src : "documents/payment.docx"
- title : "Proof of Payment"
-- src : "**.pdf"
- name : "pdf-file-:counter"
- params :
- icon : "pdf"
-- src : "**.docx"
- params :
- icon : "word"
+date: 2018-01-25
+resources:
+ - src: images/sunset.jpg
+ name: header
+ - src: documents/photo_specs.pdf
+ title: Photo Specifications
+ params:
+ icon: photo
+ - src: documents/guide.pdf
+ title: Instruction Guide
+ - src: documents/checklist.pdf
+ title: Document Checklist
+ - src: documents/payment.docx
+ title: Proof of Payment
+ - src: "**.pdf"
+ name: pdf-file-:counter
+ params:
+ icon: pdf
+ - src: "**.docx"
+ params:
+ icon: word
{{</ code-toggle >}}
+<!-- markdownlint-enable MD007 MD032 -->
From the example above:
This approach reduces build times, storage requirements, bandwidth consumption, and deployment times, ultimately reducing cost.
-> [!note]
+> [!important]
> To resolve Markdown link and image destinations to the correct location, you must use link and image render hooks that capture the page resource with the [`Resources.Get`] method, and then invoke its [`RelPermalink`] method.
>
-> By default, with multilingual single-host sites, Hugo enables its [embedded link render hook] and [embedded image render hook] to resolve Markdown link and image destinations.
+> In its default configuration, Hugo automatically uses the [embedded link render hook] and the [embedded image render hook] for multilingual single-host sites, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such sites. If custom link or image render hooks are defined by your project, modules, or themes, these will be used instead.
>
-> You may override the embedded render hooks as needed, provided they capture the resource as described above.
+> You can also configure Hugo to `always` use the embedded link or image render hook, use it only as a `fallback`, or `never` use it. See [details](/configuration/markup/#renderhookslinkuseembedded).
Although duplicating shared page resources is inefficient, you can enable this feature in your site configuration if desired:
[`RelPermalink`]: /methods/resource/relpermalink/
[`Resource`]: /methods/resource
[`Resources.ByType`]: /methods/page/resources#bytype
-[`Resources.Get`]: /methods/page/resources#get
[`Resources.Get`]: /methods/page/resources/#get
[`Resources.GetMatch`]: /methods/page/resources#getmatch
[`Resources.Match`]: /methods/page/resources#match
[content formats]: /content-management/formats/
-[embedded image render hook]: /render-hooks/images/#default
-[embedded link render hook]: /render-hooks/links/#default
+[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
+[embedded image render hook]: /render-hooks/images/#embedded
+[embedded link render hook]: /render-hooks/links/#embedded
Sections and non-sections behave differently.
-||Sections|Non-sections
+ |Sections|Non-sections
:--|:-:|:-:
Directory names become URL segments|:heavy_check_mark:|:heavy_check_mark:
Have logical ancestors and descendants|:heavy_check_mark:|:x:
1. The list page for the articles section includes all articles, regardless of directory structure; none of the subdirectories are sections.
1. The articles/2022 and articles/2023 directories do not have list pages; they are not sections.
-1. The list page for the products section, by default, includes product-1 and product-2, but not their descendant pages. To include descendant pages, use the `RegularPagesRecursive` method instead of the `Pages` method in the section template.
+1. The list page for the products section, by default, includes product-1 and product-2, but not their descendant pages. To include descendant pages, use the `RegularPagesRecursive` method instead of the `Pages` method in the _section_ template.
1. All directories in the products section have list pages; each directory is a section.
## Template selection
## Custom
-Create custom shortcodes to simplify and standardize content creation. For example, the following shortcode template generates an audio player using a [global resource](g):
+Create custom shortcodes to simplify and standardize content creation. For example, the following _shortcode_ template generates an audio player using a [global resource](g):
```go-html-template {file="layouts/_shortcodes/audio.html"}
{{ with resources.Get (.Get "src") }}
## Inline
-An inline shortcode is a shortcode template defined within content.
+An inline shortcode is a _shortcode_ template defined within content.
Hugo's security model is based on the premise that template and configuration authors are trusted, but content authors are not. This model enables generation of HTML output safe against code injection.
-To conform with this security model, creating shortcode templates within content is disabled by default. If you trust your content authors, you can enable this functionality in your site's configuration:
+To conform with this security model, creating _shortcode_ templates within content is disabled by default. If you trust your content authors, you can enable this functionality in your site's configuration:
{{< code-toggle file=hugo >}}
[security]
<p>Today is Thursday, January 30, 2025</p>
```
-Inline shortcodes process their inner content within the same context as regular shortcode templates, allowing you to use any available [shortcode method].
+Inline shortcodes process their inner content within the same context as regular _shortcode_ templates, allowing you to use any available [shortcode method].
> [!note]
> You cannot [nest](#nesting) inline shortcodes.
With standard notation, Hugo processes the shortcode separately, merging the output into the page content after Markdown rendering. This means, for instance, that Markdown headings inside a standard-notation shortcode will be excluded when invoking the `TableOfContents` method on the `Page` object.
-By way of example, with this shortcode template:
+By way of example, with this _shortcode_ template:
```go-html-template {file="layouts/_shortcodes/foo.html"}
{{ .Inner }}
- Year
- Awards
-Then, in each of the movies, you would specify terms for each of these taxonomies (i.e., in the [front matter] of each of your movie content files). From these terms, Hugo would automatically create pages for each Actor, Director, Studio, Genre, Year, and Award, with each listing all of the Movies that matched that specific Actor, Director, Studio, Genre, Year, and Award.
+Then, in each of the movies, you would specify terms for each of these taxonomies (i.e., in the front matter of each of your movie content files). From these terms, Hugo would automatically create pages for each Actor, Director, Studio, Genre, Year, and Award, with each listing all of the Movies that matched that specific Actor, Director, Studio, Genre, Year, and Award.
### Movie taxonomy organization
### Default destinations
-When taxonomies are used---and [taxonomy templates] are provided---Hugo will automatically create both a page listing all the taxonomy's terms and individual pages with lists of content associated with each term. For example, a `categories` taxonomy declared in your configuration and used in your content front matter will create the following pages:
+When taxonomies are used Hugo will automatically create both a page listing all the taxonomy's terms and individual pages with lists of content associated with each term. For example, a `categories` taxonomy declared in your configuration and used in your content front matter will create the following pages:
- A single page at `example.com/categories/` that lists all the terms within the taxonomy
-- [Individual taxonomy list pages][taxonomy templates] (e.g., `/categories/development/`) for each of the terms that shows a listing of all pages marked as part of that taxonomy within any content file's [front matter]
+- Individual taxonomy list pages (e.g., `/categories/development/`) for each of the terms that shows a listing of all pages marked as part of that taxonomy within any content file's front matter
## Configuration
## Order taxonomies
-A content file can assign weight for each of its associate taxonomies. Taxonomic weight can be used for sorting or ordering content in [taxonomy templates] and is declared in a content file's [front matter]. The convention for declaring taxonomic weight is `taxonomyname_weight`.
+A content file can assign weight for each of its associate taxonomies. Taxonomic weight can be used for sorting or ordering content in taxonomy templates and is declared in a content file's front matter. The convention for declaring taxonomic weight is `taxonomyname_weight`.
The following show a piece of content that has a weight of 22, which can be used for ordering purposes when rendering the pages assigned to the "a", "b" and "c" values of the `tags` taxonomy. It has also been assigned the weight of 44 when rendering the "d" category page.
affiliation = "University of Chicago"
{{< /code-toggle >}}
-Then create a taxonomy template specific to the "authors" taxonomy:
+Then create a _taxonomy_ template specific to the "authors" taxonomy:
```go-html-template {file="layouts/authors/taxonomy.html"}
{{ define "main" }}
In the example above we list each author including their affiliation and portrait.
-Or create a term template specific to the "authors" taxonomy:
+Or create a _term_ template specific to the "authors" taxonomy:
```go-html-template {file="layouts/authors/term.html"}
{{ define "main" }}
### `slug`
-Set the `slug` in front matter to override the last segment of the path. The `slug` value does not affect section pages.
+Set the `slug` in front matter to override the last segment of the path. This front matter field is not applicable to `home`, `section`, `taxonomy`, or `term` pages.
{{< code-toggle file=content/posts/post-1.md fm=true >}}
title = 'My First Post'
> [!note]
> Hugo does not sanitize the `url` front matter field, allowing you to generate:
+>
> - File paths that contain characters reserved by the operating system. For example, file paths on Windows may not contain any of these [reserved characters]. Hugo throws an error if a file path includes a character reserved by the current operating system.
> - URLs that contain disallowed characters. For example, the less than sign (`<`) is not allowed in a URL.
Use this workflow to create and submit pull requests.
-### Step 1
+Step 1
+: Fork the [project repository].
-Fork the [project repository].
+Step 2
+: Clone your fork.
-### Step 2
+Step 3
+: Create a new branch with a descriptive name that includes the corresponding issue number.
-Clone your fork.
+ For a new feature:
-### Step 3
+ ```sh
+ git checkout -b feat/implement-some-feature-99999
+ ```
-Create a new branch with a descriptive name that includes the corresponding issue number.
+ For a bug fix:
-For a new feature:
+ ```sh
+ git checkout -b fix/fix-some-bug-99999
+ ```
-```sh
-git checkout -b feat/implement-some-feature-99999
-```
-
-For a bug fix:
-
-```sh
-git checkout -b fix/fix-some-bug-99999
-```
-
-### Step 4
-
-Make changes.
-
-### Step 5
-
-Compile and install.
+Step 4
+: Make changes.
-To compile and install the standard edition:
+Step 5
+: Compile and install.
-```text
-go install
-```
-
-To compile and install the extended edition:
-
-```text
-CGO_ENABLED=1 go install -tags extended
-```
-
-To compile and install the extended/deploy edition:
+ To compile and install the standard edition:
-```text
-CGO_ENABLED=1 go install -tags extended,withdeploy
-```
+ ```text
+ go install
+ ```
-### Step 6
+ To compile and install the extended edition:
-Test your changes:
+ ```text
+ CGO_ENABLED=1 go install -tags extended
+ ```
-```text
-go test ./...
-```
+ To compile and install the extended/deploy edition:
-### Step 7
+ ```text
+ CGO_ENABLED=1 go install -tags extended,withdeploy
+ ```
-Commit your changes with a descriptive commit message:
+Step 6
+: Test your changes:
-- Provide a summary on the first line, typically 50 characters or less, followed by a blank line.
- - Begin the summary with one of content, theme, config, all, or misc, followed by a colon, a space, and a brief description of the change beginning with a capital letter
- - Use imperative present tense
- - See the [commit message guidelines] for requirements
-- Optionally, provide a detailed description where each line is 72 characters or less, followed by a blank line.
-- Add one or more "Fixes" or "Closes" keywords, each on its own line, referencing the [issues] addressed by this change.
+ ```text
+ go test ./...
+ ```
-For example:
+Step 7
+: Commit your changes with a descriptive commit message:
-```sh
-git commit -m "tpl/strings: Create wrap function
+ - Provide a summary on the first line, typically 50 characters or less, followed by a blank line.
+ - Begin the summary with one of content, theme, config, all, or misc, followed by a colon, a space, and a brief description of the change beginning with a capital letter
+ - Use imperative present tense
+ - See the [commit message guidelines] for requirements
+ - Optionally, provide a detailed description where each line is 72 characters or less, followed by a blank line.
+ - Add one or more "Fixes" or "Closes" keywords, each on its own line, referencing the [issues] addressed by this change.
-The strings.Wrap function wraps a string into one or more lines,
-splitting the string after the given number of characters, but not
-splitting in the middle of a word.
-
-Fixes #99998
-Closes #99999"
-```
+ For example:
-### Step 8
+ ```sh
+ git commit -m "tpl/strings: Create wrap function
-Push the new branch to your fork of the documentation repository.
+ The strings.Wrap function wraps a string into one or more lines,
+ splitting the string after the given number of characters, but not
+ splitting in the middle of a word.
-### Step 9
+ Fixes #99998
+ Closes #99999"
+ ```
-Visit the [project repository] and create a pull request (PR).
+Step 8
+: Push the new branch to your fork of the documentation repository.
-### Step 10
+Step 9
+: Visit the [project repository] and create a pull request (PR).
-A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR.
+Step 10
+: A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR.
## Building from source
To build and install a specific release:
```sh
-CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@v0.147.1
+CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@v0.148.0
```
To build and install at the latest commit on the master branch:
To build and install at a specific commit:
```sh
-CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@0851c17
+CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@c0d9beb
```
[bugs]: https://github.com/gohugoio/hugo/issues?q=is%3Aopen+is%3Aissue+label%3ABug
- "Markdown" (capitalized)
- "open-source" (hyphenated adjective)
+### Template types
+
+When you refer to a template type, italicize it:
+
+```text
+When creating a _taxonomy_ template, do this...
+```
+
+However, if the template type is also a link, do not italicize it to avoid distracting formatting:
+
+```text
+When creating a [taxonomy] template, do this...
+```
+
+Do not italicize the template type in a title, heading, or front matter description.
+
### Titles and headings
- Use sentence-style capitalization.
Field|Description|Required
:--|:--|:--
-`title`|The page title|:heavy_check_mark:|
-`linkTitle`|A short version of the page title||
-`description`|A complete sentence describing the page|:heavy_check_mark:|
-`categories`|An array of terms in the categories taxonomy|:heavy_check_mark: [^1]|
-`keywords`|An array of keywords used to identify related content|:heavy_check_mark: [^1]|
-`publishDate`|Applicable to news items: the publication date||
-`params.alt_title`|An alternate title: used in the "see also" panel if provided||
-`params.functions_and_methods.aliases`|Applicable to function and method pages: an array of alias names||
-`params.functions_and_methods.returnType`|Applicable to function and method pages: the data type returned||
-`params.functions_and_methods.signatures`|Applicable to function and method pages: an array of signatures||
-`params.hide_in_this_section`|Whether to hide the "in this section" panel||
-`params.minversion`|Applicable to the quick start page: the minimum Hugo version required||
-`params.permalink`|Reserved for use by the news content adapter||
-`params.reference (used in glossary term)`|Applicable to glossary entries: a URL for additional information||
-`params.searchable`|Whether to add the content of this page to the search index. The default value is cascaded down from the site configuration; `true` if the page kind is `page`, and `false` if the page kind is one of `home`, `section`, `taxonomy`, or `term`. Add this field to override the default value.||
-`params.show_publish_date`|Whether to show the `publishDate` when rendering the page||
-`weight`|The page weight||
-`aliases`|Previous URLs used to access this page||
-`expirydate`|The expiration date||
+`title`|The page title|:heavy_check_mark:
+`linkTitle`|A short version of the page title|
+`description`|A complete sentence describing the page|:heavy_check_mark:
+`categories`|An array of terms in the categories taxonomy|:heavy_check_mark: [^1]
+`keywords`|An array of keywords used to identify related content|:heavy_check_mark: [^1]
+`publishDate`|Applicable to news items: the publication date|
+`params.alt_title`|An alternate title: used in the "see also" panel if provided|
+`params.functions_and_methods.aliases`|Applicable to function and method pages: an array of alias names|
+`params.functions_and_methods.returnType`|Applicable to function and method pages: the data type returned|
+`params.functions_and_methods.signatures`|Applicable to function and method pages: an array of signatures|
+`params.hide_in_this_section`|Whether to hide the "in this section" panel|
+`params.minversion`|Applicable to the quick start page: the minimum Hugo version required|
+`params.permalink`|Reserved for use by the news content adapter|
+`params.reference (used in glossary term)`|Applicable to glossary entries: a URL for additional information|
+`params.searchable`|Whether to add the content of this page to the search index. The default value is cascaded down from the site configuration; `true` if the page kind is `page`, and `false` if the page kind is one of `home`, `section`, `taxonomy`, or `term`. Add this field to override the default value.|
+`params.show_publish_date`|Whether to show the `publishDate` when rendering the page|
+`weight`|The page weight|
+`aliases`|Previous URLs used to access this page|
+`expirydate`|The expiration date|
[^1]: The field is required, but its data is not.
> [!important]
> Key information users need to know to achieve their goal.
-
-
## Shortcodes
These shortcodes are commonly used throughout the documentation. Other shortcodes are available for specialized use.
Use this workflow to create and submit pull requests.
-### Step 1
+Step 1
+: Fork the [documentation repository].
-Fork the [documentation repository].
+Step 2
+: Clone your fork.
-### Step 2
+Step 3
+: Create a new branch with a descriptive name that includes the corresponding issue number, if any:
-Clone your fork.
+ ```sh
+ git checkout -b restructure-foo-page-99999
+ ```
-### Step 3
+Step 4
+: Make changes.
-Create a new branch with a descriptive name that includes the corresponding issue number, if any:
+Step 5
+: Build the site locally to preview your changes.
-```sh
-git checkout -b restructure-foo-page-99999
-```
+Step 6
+: Commit your changes with a descriptive commit message:
-### Step 4
+ - Provide a summary on the first line, typically 50 characters or less, followed by a blank line.
+ - Begin the summary with one of `content`, `theme`, `config`, `all`, or `misc`, followed by a colon, a space, and a brief description of the change beginning with a capital letter
+ - Use imperative present tense
+ - Optionally, provide a detailed description where each line is 72 characters or less, followed by a blank line.
+ - Optionally, add one or more "Fixes" or "Closes" keywords, each on its own line, referencing the [issues] addressed by this change.
-Make changes.
+ For example:
-### Step 5
+ ```text
+ git commit -m "content: Restructure the taxonomy page
-Build the site locally to preview your changes.
+ This restructures the taxonomy page by splitting topics into logical
+ sections, each with one or more examples.
-### Step 6
+ Fixes #9999
+ Closes #9998"
+ ```
-Commit your changes with a descriptive commit message:
+Step 7
+: Push the new branch to your fork of the documentation repository.
-- Provide a summary on the first line, typically 50 characters or less, followed by a blank line.
- - Begin the summary with one of `content`, `theme`, `config`, `all`, or `misc`, followed by a colon, a space, and a brief description of the change beginning with a capital letter
- - Use imperative present tense
-- Optionally, provide a detailed description where each line is 72 characters or less, followed by a blank line.
-- Optionally, add one or more "Fixes" or "Closes" keywords, each on its own line, referencing the [issues] addressed by this change.
+Step 8
+: Visit the [documentation repository] and create a pull request (PR).
-For example:
-
-```text
-git commit -m "content: Restructure the taxonomy page
-
-This restructures the taxonomy page by splitting topics into logical
-sections, each with one or more examples.
-
-Fixes #9999
-Closes #9998"
-```
-
-### Step 7
-
-Push the new branch to your fork of the documentation repository.
-
-### Step 8
-
-Visit the [documentation repository] and create a pull request (PR).
-
-### Step 9
-
-A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR.
+Step 9
+: A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR.
[ATX]: https://spec.commonmark.org/current/#atx-headings
[basic english]: https://simple.wikipedia.org/wiki/Basic_English
-[basic english]: https://simple.wikipedia.org/wiki/Basic_English
[developer documentation style guide]: https://developers.google.com/style
[documentation repository]: https://github.com/gohugoio/hugoDocs/
[fenced code blocks]: https://spec.commonmark.org/current/#fenced-code-blocks
Follow the steps below to transform CSS using any of the available [PostCSS plugins].
-### Step 1
+Step 1
+: Install [Node.js].
-Install [Node.js].
+Step 2
+: Install the required Node.js packages in the root of your project. For example, to add vendor prefixes to your CSS rules:
-### Step 2
+ ```sh
+ npm i -D postcss postcss-cli autoprefixer
+ ```
-Install the required Node.js packages in the root of your project. For example, to add vendor prefixes to your CSS rules:
+Step 3
+: Create a PostCSS configuration file in the root of your project.
-```sh
-npm i -D postcss postcss-cli autoprefixer
-```
-
-### Step 3
-
-Create a PostCSS configuration file in the root of your project.
-
-```js {file="postcss.config.js"}
-module.exports = {
- plugins: [
- require('autoprefixer')
- ]
-};
-```
+ ```js {file="postcss.config.js"}
+ module.exports = {
+ plugins: [
+ require('autoprefixer')
+ ]
+ };
+ ```
-> [!note]
-> If you are a Windows user, and the path to your project contains a space, you must place the PostCSS configuration within the package.json file. See [this example] and issue [#7333].
+ > [!note]
+ > If you are a Windows user, and the path to your project contains a space, you must place the PostCSS configuration within the package.json file. See [this example] and issue [#7333].
-### Step 4
+Step 4
+: Place your CSS file within the `assets/css` directory.
-Place your CSS file within the `assets/css` directory.
+Step 5
+: Process the resource with PostCSS:
-### Step 5
-
-Process the resource with PostCSS:
-
-```go-html-template
-{{ with resources.Get "css/main.css" | postCSS }}
- <link rel="stylesheet" href="{{ .RelPermalink }}">
-{{ end }}
-```
+ ```go-html-template
+ {{ with resources.Get "css/main.css" | postCSS }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ end }}
+ ```
## Options
### Installing in a production environment
-For [CI/CD](g) deployments (e.g., GitHub Pages, GitLab Pages, Netlify, etc.) you must edit the workflow to install Dart Sass before Hugo builds the site[^2]. Some providers allow you to use one of the package managers above, or you can download and extract one of the prebuilt binaries.
+To use Dart Sass with Hugo on a CI/CD platform like GitHub Pages, GitLab Pages, or Netlify, you typically must modify your build workflow to install Dart Sass before the Hugo site build begins. This is because these platforms don't have Dart Sass pre-installed, and Hugo needs it to process your Sass files.
-[^2]: You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set `useResourceCacheWhen` to `never` in your [site configuration], and (c) you add and commit your `resources` directory to your repository.
+There's one key exception where you can skip this step: you have committed your `resources` directory to your repository. This is only possible if:
-#### GitHub Pages
+- You have not changed Hugo's default asset cache location.
+- You have not set [`useResourceCacheWhen`] to never in your sites configuration.
-To install Dart Sass for your builds on GitHub Pages, add this step to the GitHub Pages workflow file:
+By committing the `resources` directory, you're providing the pre-built CSS files directly to your CI/CD service, so it doesn't need to run the Sass compilation itself.
-```yaml
-- name: Install Dart Sass
- run: sudo snap install dart-sass
-```
-
-#### GitLab Pages
-
-To install Dart Sass for your builds on GitLab Pages, the `.gitlab-ci.yml` file should look something like this:
-
-```yaml
-variables:
- HUGO_VERSION: 0.147.9
- DART_SASS_VERSION: 1.89.2
- GIT_DEPTH: 0
- GIT_STRATEGY: clone
- GIT_SUBMODULE_STRATEGY: recursive
- TZ: America/Los_Angeles
-image:
- name: golang:1.20-buster
-pages:
- script:
- # Install Dart Sass
- - curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
- - tar -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
- - cp -r dart-sass/* /usr/local/bin
- - rm -rf dart-sass*
- # Install Hugo
- - curl -LJO https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
- - apt install -y ./hugo_extended_${HUGO_VERSION}_linux-amd64.deb
- - rm hugo_extended_${HUGO_VERSION}_linux-amd64.deb
- # Build
- - hugo --gc --minify
- artifacts:
- paths:
- - public
- rules:
- - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
-```
+For examples of how to install Dart Sass in a production environment, see the following workflow files:
-#### Netlify
-
-To install Dart Sass for your builds on Netlify, the `netlify.toml` file should look something like this:
-
-```toml
-[build.environment]
-HUGO_VERSION = "0.147.9"
-DART_SASS_VERSION = "1.89.2"
-NODE_VERSION = "22"
-TZ = "America/Los_Angeles"
-
-[build]
-publish = "public"
-command = """\
- curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
- tar -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
- rm dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
- export PATH=/opt/build/repo/dart-sass:$PATH && \
- hugo --gc --minify \
- """
-```
+- [GitHub Pages]
+- [GitLab Pages]
+- [Netlify]
+[`publishDir`]: /configuration/all/#publishdir
+[`useResourceCacheWhen`]: /configuration/build/#useresourcecachewhen
[brew.sh]: https://brew.sh/
[chocolatey.org]: https://community.chocolatey.org/packages/sass
[dart sass]: https://sass-lang.com/dart-sass
+[GitHub Pages]: /host-and-deploy/host-on-github-pages/#step-7
+[GitLab Pages]: /host-and-deploy/host-on-gitlab-pages/#configure-gitlab-cicd
[libsass]: https://sass-lang.com/libsass
+[Netlify]: /host-and-deploy/host-on-netlify/#configuration-file
[prebuilt binaries]: https://github.com/sass/dart-sass/releases/latest
[scoop.sh]: https://scoop.sh/#/apps?q=sass
-[site configuration]: /configuration/build/
[snap package]: /installation/linux/#snap
[snapcraft.io]: https://snapcraft.io/dart-sass
-[starter workflow]: https://github.com/actions/starter-workflows/blob/main/pages/hugo.yml
-[`publishDir`]: /configuration/all/#publishdir
## Setup
-### Step 1
-
-Install the Tailwind CSS CLI v4.0 or later:
-
-```sh {copy=true}
-npm install --save-dev tailwindcss @tailwindcss/cli
-```
-
-The Tailwind CSS CLI is also available as a [standalone executable]. You must install it outside of your project directory and ensure its path is included in your system's `PATH` environment variable.
-
-
-[standalone executable]: https://github.com/tailwindlabs/tailwindcss/releases/latest
-
-### Step 2
-
-Add this to your site configuration:
-
-{{< code-toggle file=hugo copy=true >}}
-[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 = 'assets'
- target = 'assets'
- [[module.mounts]]
- disableWatch = true
- source = 'hugo_stats.json'
- target = 'assets/notwatching/hugo_stats.json'
-{{< /code-toggle >}}
-
-### Step 3
-
-Create a CSS entry file:
-
-```css {file="assets/css/main.css" copy=true}
-@import "tailwindcss";
-@source "hugo_stats.json";
-```
-
-Tailwind CSS respects `.gitignore` files. This means that if `hugo_stats.json` is listed in your `.gitignore` file, Tailwind CSS will ignore it. To make `hugo_stats.json` available to Tailwind CSS you must explicitly source it as shown in the example above.
-
-### Step 4
-
-Create a partial template to process the CSS with the Tailwind CSS CLI:
-
-```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 }}
- <link rel="stylesheet" href="{{ .RelPermalink }}">
- {{ else }}
- {{ with . | fingerprint }}
- <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+Step 1
+: Install the Tailwind CSS CLI v4.0 or later:
+
+ ```sh {copy=true}
+ npm install --save-dev tailwindcss @tailwindcss/cli
+ ```
+
+ The Tailwind CSS CLI is also available as a [standalone executable]. You must install it outside of your project directory and ensure its path is included in your system's `PATH` environment variable.
+
+ [standalone executable]: https://github.com/tailwindlabs/tailwindcss/releases/latest
+
+Step 2
+: Add this to your site configuration:
+
+ {{< code-toggle file=hugo copy=true >}}
+ [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 = 'assets'
+ target = 'assets'
+ [[module.mounts]]
+ disableWatch = true
+ source = 'hugo_stats.json'
+ target = 'assets/notwatching/hugo_stats.json'
+ {{< /code-toggle >}}
+
+Step 3
+: Create a CSS entry file:
+
+ ```css {file="assets/css/main.css" copy=true}
+ @import "tailwindcss";
+ @source "hugo_stats.json";
+ ```
+
+ Tailwind CSS respects `.gitignore` files. This means that if `hugo_stats.json` is listed in your `.gitignore` file, Tailwind CSS will ignore it. To make `hugo_stats.json` available to Tailwind CSS you must explicitly source it as shown in the example above.
+
+Step 4
+: Create a _partial_ template to process the CSS with the Tailwind CSS CLI:
+
+ ```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 }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ else }}
+ {{ with . | fingerprint }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
{{ end }}
{{ end }}
{{ end }}
-{{ end }}
-```
-
-### Step 5
+ ```
-Call the partial template from your base template, deferring template execution until after all sites and output formats have been rendered:
+Step 5
+: Call the _partial_ template from your base template, deferring template execution until after all sites and output formats have been rendered:
-```go-html-template {file="layouts/baseof.html" copy=true}
-<head>
- ...
- {{ with (templates.Defer (dict "key" "global")) }}
- {{ partial "css.html" . }}
- {{ end }}
- ...
-</head>
-```
+ ```go-html-template {file="layouts/baseof.html" copy=true}
+ <head>
+ ...
+ {{ with (templates.Defer (dict "key" "global")) }}
+ {{ partial "css.html" . }}
+ {{ end }}
+ ...
+ </head>
+ ```
## Options
## Page resource alternative
-Consider using the [`Resources.Get`] method with [`transform.Unmarshal`] when accessing a page resource.
+Consider using the [`Resources.Get`][/methods/page/resources/] method with [`transform.Unmarshal`] when accessing a page resource.
```text
my-project/
{{ end }}
```
-[`Resources.Get`]: /methods/page/resources/
[`resources.GetRemote`]: /functions/resources/getremote/
-[`resources.Get`]: /functions/resources/get/
+
+<!-- markdownlint-disable MD053 -->
[`transform.Unmarshal`]: /functions/transform/unmarshal/
+<!-- markdownlint-enable MD053 -->
## Global resource alternative
-Consider using the [`resources.Get`] function with [`transform.Unmarshal`] when accessing a global resource.
+Consider using the [`resources.Get`](/functions/resources/get/) function with [`transform.Unmarshal`] when accessing a global resource.
```text
my-project/
## Page resource alternative
-Consider using the [`Resources.Get`] method with [`transform.Unmarshal`] when accessing a page resource.
+Consider using the [`Resources.Get`][/methods/page/resources/] method with [`transform.Unmarshal`] when accessing a page resource.
```text
my-project/
{{ end }}
```
-[`Resources.Get`]: /methods/page/resources/
[`resources.GetRemote`]: /functions/resources/getremote/
-[`resources.Get`]: /functions/resources/get/
+
+<!-- markdownlint-disable MD053 -->
[`transform.Unmarshal`]: /functions/transform/unmarshal/
+<!-- markdownlint-enable MD053 -->
To customize the printing of the JSON, pass an options map as the first
argument. Supported options are "prefix" and "indent". Each JSON element in
-the output will begin on a new line beginning with *prefix* followed by one or
-more copies of *indent* according to the indentation nesting.
+the output will begin on a new line beginning with _prefix_ followed by one or
+more copies of _indent_ according to the indentation nesting.
```go-html-template
{{ dict "title" .Title "content" .Plain | jsonify }}
└── _index.md <-- title is "My Home Page"
```
-And this code in the home template:
+And this code in the _home_ template:
-```go-html-template
+```go-html-template {file="layouts/home.html"}
{{ range site.Sections }}
{{ range .Pages }}
{{ page.Title }}
My Home Page
```
-In the example above, the global `page` function accesses the `Page` object passed into the home template; it does not access the `Page` object of the iterated pages.
+In the example above, the global `page` function accesses the `Page` object passed into the _home_ template; it does not access the `Page` object of the iterated pages.
### Be aware of caching
Hugo caches rendered shortcodes. If you use the global `page` function within a shortcode, and the page content is rendered in two or more templates, the cached shortcode may be incorrect.
-Consider this section template:
+Consider this _section_ template:
-```go-html-template
+```go-html-template {file="layouts/section.html"}
{{ range .Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ .Summary }}
```go-html-template
{{ template "name" pipeline }}
```
+
The typical use is to define a set of root templates that are then customized by redefining the block templates within.
```go-html-template {file="layouts/baseof.html"}
{{ end }}
```
-> [!warning]
-> Only [template comments] are allowed outside of the `define` and `end` statements. Avoid placing any other text, including HTML comments, outside of these boundaries. Doing so will cause rendering issues, potentially resulting in a blank page. See the example below.
-
-```go-html-template {file="layouts/do-not-do-this.html"}
-<div>This div element broke your template.</div>
-{{ define "main" }}
- <h2>{{ .Title }}</h2>
- {{ .Content }}
-{{ end }}
-<!-- An HTML comment will break your template too. -->
-```
-
{{% include "/_common/functions/go-template/text-template.md" %}}
[`block`]: /functions/go-template/block/
[`template`]: /functions/go-template/block/
[`partial`]: /functions/partials/include/
-[template comments]: /templates/introduction/#comments
## Understanding context
-At the top of a page template, the [context](g) (the dot) is a `Page` object. Within the `range` block, the context is bound to each successive element.
+See the [context] section in the introduction to templating.
+
+For example, at the top of a _page_ template, the [context](g) (the dot) is a `Page` object. Within the `range` block, the context is bound to each successive element.
With this contrived example:
[`break`]: /functions/go-template/break/
[`continue`]: /functions/go-template/continue/
[`else`]: /functions/go-template/else/
+[context]: /templates/introduction/#context
signatures: ['return [VALUE]']
---
-The `return` statement is a non-standard extension to Go's [text/template package]. Used within partial templates, the `return` statement terminates template execution and returns the given value, if any.
+The `return` statement is a non-standard extension to Go's [text/template package]. Used within _partial_ templates, the `return` statement terminates template execution and returns the given value, if any.
The returned value may be of any data type including, but not limited to, [`bool`](g), [`float`](g), [`int`](g), [`map`](g), [`resource`](g), [`slice`](g), or [`string`](g).
## Example
-By way of example, let's create a partial template that _renders_ HTML, describing whether the given number is odd or even:
+By way of example, let's create a _partial_ template that _renders_ HTML, describing whether the given number is odd or even:
```go-html-template {file="layouts/_partials/odd-or-even.html"}
{{ if math.ModBool . 2 }}
{{ end }}
```
-The example above can be rewritten using an inline partial template:
+The example above can be rewritten using an inline _partial_ template:
```go-html-template
{{ partial "inline/foo.html" (dict "answer" 42) }}
The key distinctions between the preceding two examples are:
1. Inline partials are globally scoped. That means that an inline partial defined in _one_ template may be called from _any_ template.
-2. Leveraging the [`partialCached`] function when calling an inline partial allows for performance optimization through result caching.
-3. An inline partial can [`return`] a value of any data type instead of rendering a string.
+1. Leveraging the [`partialCached`] function when calling an inline partial allows for performance optimization through result caching.
+1. An inline partial can [`return`] a value of any data type instead of rendering a string.
{{% include "/_common/functions/go-template/text-template.md" %}}
{{ end }}
{{ end }}
```
+
In the above, note that the [context](g) within the last conditional block is the `TryValue` object returned by the `try` statement. At this point neither the `Err` nor `Value` methods returned anything, so the current context is not useful. Use the `$` to access the [template context] if needed.
> [!note]
## Understanding context
-At the top of a page template, the [context](g) (the dot) is a `Page` object. Inside of the `with` block, the context is bound to the value passed to the `with` statement.
+See the [context] section in the introduction to templating.
+
+For example, at the top of a _page_ template, the [context](g) (the dot) is a `Page` object. Inside of the `with` block, the context is bound to the value passed to the `with` statement.
With this contrived example:
{{% include "/_common/functions/go-template/text-template.md" %}}
[`else`]: /functions/go-template/else/
+[context]: /templates/introduction/#context
---
```go-html-template
-{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.147.9">
+{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.148.0">
```
## Determinate values
-The `Store` method is often used to set scratch pad values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.
+The `Store` method is often used to set scratch pad values within a _shortcode_ template, a _partial_ template called by a _shortcode_ template, or by a _render hook_ template. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.
If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop](g) variable:
---
```go-html-template
-{{ hugo.Version }} → 0.147.9
+{{ hugo.Version }} → 0.148.0
```
## Setup
-### Step 1
+Step 1
+: Install [Node.js](https://nodejs.org/en/download)
-Install [Node.js](https://nodejs.org/en/download)
+Step 2
+: Install the required Node.js packages in the root of your project.
-### Step 2
+ ```sh
+ npm install --save-dev @babel/core @babel/cli
+ ```
-Install the required Node.js packages in the root of your project.
+Step 3
+: Add the babel executable to Hugo's `security.exec.allow` list in your site configuration:
-```sh
-npm install --save-dev @babel/core @babel/cli
-```
-
-### Step 3
-
-Add the babel executable to Hugo's `security.exec.allow` list in your site configuration:
-
-{{< code-toggle file=hugo >}}
-[security.exec]
- allow = ['^(dart-)?sass(-embedded)?$', '^go$', '^npx$', '^postcss$', '^babel$']
-{{< /code-toggle >}}
+ {{< code-toggle file=hugo >}}
+ [security.exec]
+ allow = ['^(dart-)?sass(-embedded)?$', '^go$', '^npx$', '^postcss$', '^babel$']
+ {{< /code-toggle >}}
## Configuration
import * as config from "@params/config";
```
-Setting the `Config` for a batch can be done from any template (including shortcode templates), but will only be set once (the first will win):
+Setting the `Config` for a batch can be done from any template (including _shortcode_ templates), but will only be set once (the first will win):
```go-html-template
{{ with js.Batch "js/mybatch" }}
In the official documentation for ESBuild's [code splitting], there's a warning note in the header. The two issues are:
- - `esm` is currently the only implemented output format. This means that it will not work for very old browsers. See [caniuse](https://caniuse.com/?search=ESM).
- - There's a known import ordering issue.
+- `esm` is currently the only implemented output format. This means that it will not work for very old browsers. See [caniuse](https://caniuse.com/?search=ESM).
+- There's a known import ordering issue.
We have not seen the ordering issue as a problem during our [extensive testing](https://github.com/bep/hugojsbatchdemo) of this new feature with different libraries. There are two main cases:
[`Resources.Mount`]: /methods/page/resources/#mount
[`Resources`]: /methods/page/resources/
[`templates.Defer`]: /functions/templates/defer/
-[`templates.Defer`]: /functions/templates/defer/
[build options]: #build-options
[code splitting]: https://esbuild.github.io/api/#splitting
[config]: #config
```go-html-template
{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }}
```
+
And then in your JS file:
```js
```
> [!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.
+> 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.
---
title: partials.Include
-description: Executes the given partial template, optionally passing context. If the partial template contains a return statement, returns the given value, else returns the rendered output.
+description: Executes the given template, optionally passing context. If the partial template contains a return statement, returns the given value, else returns the rendered output.
categories: []
keywords: []
params:
Without a [`return`] statement, the `partial` function returns a string of type `template.HTML`. With a `return` statement, the `partial` function can return any data type.
-[`return`]: /functions/go-template/return/
-
-In this example we have three partial templates:
+In this example we have three _partial_ templates:
```text
layouts/
{{ partial "render-student-info.html" $ctx }}
```
-Then, within the partial template:
+Then, within the _partial_ template:
```go-html-template
<p>{{ .name }} is majoring in {{ .major }}.</p>
<p>See <a href="{{ .page.RelPermalink }}">details.</a></p>
```
-To return a value from a partial template, it must contain only one `return` statement, placed at the end of the template:
+To return a value from a _partial_ template, it must contain only one `return` statement, placed at the end of the template:
```go-html-template
{{ $result := "" }}
See [details][`return`].
[`return`]: /functions/go-template/return/
-
[breadcrumb navigation]: /content-management/sections/#ancestors-and-descendants
-[details]: /functions/go-template/return/
{{ partialCached "footer.html" . .Params.country .Params.province }}
```
-The variant arguments are not available to the underlying partial template; they are only used to create unique cache keys.
+The variant arguments are not available to the underlying _partial_ template; they are only used to create unique cache keys.
-To return a value from a partial template, it must contain only one `return` statement, placed at the end of the template:
+To return a value from a _partial_ template, it must contain only one `return` statement, placed at the end of the template:
```go-html-template
{{ $result := "" }}
```json
{
- "build_date": "2025-05-03T19:14:41-08:00",
- "hugo_version": "0.147.9",
- "last_modified": "2025-05-03T19:14:46-08:00"
+ "build_date": "2025-07-08T13:12:19-07:00",
+ "hugo_version": "0.148.0",
+ "last_modified": "2025-07-07T22:09:13-07:00"
}
```
Use the [`try`] statement instead, as shown in the [error handling] example below.
-[`try`]: /functions/go-template/try
-[error handling]: #error-handling
{{< /new-in >}}
```go-html-template
The `resources.GetRemote` function takes an optional map of options.
-###### body
-
-(`string`) The data you want to transmit to the server.
-
-###### headers
-
-(`map[string][]string`) The collection of key-value pairs that provide additional information about the request.
+body
+: (`string`) The data you want to transmit to the server.
-###### key
+headers
+: (`map[string][]string`) The collection of key-value pairs that provide additional information about the request.
-(`string`) The cache key. Hugo derives the default value from the URL and options map. See [caching](#caching).
+key
+: (`string`) The cache key. Hugo derives the default value from the URL and options map. See [caching](#caching).
-###### method
+method
+: (`string`) The action to perform on the requested resource, typically one of `GET`, `POST`, or `HEAD`.
-(`string`) The action to perform on the requested resource, typically one of `GET`, `POST`, or `HEAD`.
-
-###### responseHeaders
-{{< new-in 0.143.0 />}}
-
-(`[]string`) The headers to extract from the server's response, accessible through the resource's [`Data.Headers`] method. Header name matching is case-insensitive.
+responseHeaders
+: {{< new-in 0.143.0 />}}
+: (`[]string`) The headers to extract from the server's response, accessible through the resource's [`Data.Headers`] method. Header name matching is case-insensitive.
[`Data.Headers`]: /methods/resource/data/#headers
> [!note]
> For brevity, the examples below do not include [error handling].
-[error handling]: #error-handling
-
To include a header:
```go-html-template
Use the [`try`] statement to capture HTTP request errors. If you do not handle the error yourself, Hugo will fail the build.
-[`try`]: /functions/go-template/try
-
> [!note]
> Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil.
{{ $resource := resources.GetRemote $url $opts }}
```
-[configure file caches]: /configuration/caches/
-
## Security
To protect against malicious intent, the `resources.GetRemote` function inspects the server response including:
[allowlist]: https://en.wikipedia.org/wiki/Whitelist
[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
+
+[`try`]: /functions/go-template/try
+[configure file caches]: /configuration/caches/
+[error handling]: #error-handling
In this example, after the build is complete, Hugo will:
1. Purge unused CSS using the [PurgeCSS] plugin for [PostCSS]
-2. Add vendor prefixes to CSS rules using the [Autoprefixer] plugin for PostCSS
-3. [Minify] the CSS
-4. [Fingerprint] the CSS
+1. Add vendor prefixes to CSS rules using the [Autoprefixer] plugin for PostCSS
+1. [Minify] the CSS
+1. [Fingerprint] the CSS
Step 1
: Install [Node.js].
Step 2
: Install the required Node.js packages in the root of your project:
-```sh
-npm i -D postcss postcss-cli autoprefixer @fullhuman/postcss-purgecss
-```
+ ```sh {copy=true}
+ npm i -D postcss postcss-cli autoprefixer @fullhuman/postcss-purgecss
+ ```
Step 3
: Enable creation of the `hugo_stats.json` file when building the site. If you are only using this for the production build, consider placing it below [`config/production`].
-{{< code-toggle file=hugo >}}
-[build.buildStats]
-enable = true
-{{< /code-toggle >}}
+ {{< code-toggle file=hugo copy=true >}}
+ [build.buildStats]
+ enable = true
+ {{< /code-toggle >}}
-See the [configure build] documentation for details and options.
+ See the [configure build] documentation for details and options.
Step 4
: Create a PostCSS configuration file in the root of your project.
-```js {file="postcss.config.js" copy=true}
-const autoprefixer = require('autoprefixer');
-const purgeCSSPlugin = require('@fullhuman/postcss-purgecss').default;
-
-const purgecss = purgeCSSPlugin({
- content: ['./hugo_stats.json'],
- defaultExtractor: content => {
- const els = JSON.parse(content).htmlElements;
- return [
- ...(els.tags || []),
- ...(els.classes || []),
- ...(els.ids || []),
- ];
- },
- // https://purgecss.com/safelisting.html
- safelist: []
-});
-
-module.exports = {
- plugins: [
- process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null,
- autoprefixer,
- ]
-};
-```
-
-> [!note]
-> If you are a Windows user, and the path to your project contains a space, you must place the PostCSS configuration within the package.json file. See [this example] and issue [#7333].
+ ```js {file="postcss.config.js" copy=true}
+ const autoprefixer = require('autoprefixer');
+ const purgeCSSPlugin = require('@fullhuman/postcss-purgecss').default;
+
+ const purgecss = purgeCSSPlugin({
+ content: ['./hugo_stats.json'],
+ defaultExtractor: content => {
+ const els = JSON.parse(content).htmlElements;
+ return [
+ ...(els.tags || []),
+ ...(els.classes || []),
+ ...(els.ids || []),
+ ];
+ },
+ // https://purgecss.com/safelisting.html
+ safelist: []
+ });
+
+ module.exports = {
+ plugins: [
+ process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null,
+ autoprefixer,
+ ]
+ };
+ ```
+
+ > [!note]
+ > If you are a Windows user, and the path to your project contains a space, you must place the PostCSS configuration within the package.json file. See [this example] and issue [#7333].
Step 5
: Place your CSS file within the `assets/css` directory.
Step 6
: If the current environment is not `development`, process the resource with PostCSS:
-```go-html-template
-{{ with resources.Get "css/main.css" }}
- {{ if hugo.IsDevelopment }}
- <link rel="stylesheet" href="{{ .RelPermalink }}">
- {{ else }}
- {{ with . | postCSS | minify | fingerprint | resources.PostProcess }}
- <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ ```go-html-template {copy=true}
+ {{ with resources.Get "css/main.css" }}
+ {{ if hugo.IsDevelopment }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ else }}
+ {{ with . | postCSS | minify | fingerprint | resources.PostProcess }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
{{ end }}
{{ end }}
-{{ end }}
-```
+ ```
## Environment variables
## Limitations
-Do not use `resources.PostProcess` when running Hugo's built-in development server. The examples above specifically prevent this by verifying that the current environment is not "development".
+Do not use `resources.PostProcess` when running Hugo's built-in development server. The examples above specifically prevent this by verifying that the current environment is not `development`.
The `resources.PostProcess` function only works within templates that produce HTML files.
### Call stack
-To display the chain of templates that led to the current one, create a partial template that iterates through its ancestors:
+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}
{{ with templates.Current }}
### VS Code
-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:
+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}
{{ with templates.Current.Parent }}
{{< new-in 0.128.0 />}}
> [!note]
-> 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 feature should only be used in the main template, typically `layouts/baseof.html`. Using it in _shortcode_, _partial_, 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
aliases: [/functions/time.parseduration]
---
-The `time.ParseDuration` function returns a time.Duration value that you can use with any of the `Duration` [methods].
+The `time.ParseDuration` function returns a [`time.Duration`] value that you can use with any of the `Duration` [methods].
A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as `300ms`, `-1.5h` or `2h45m`. Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`.
Unfortunately, Sanity's API does not support [RFC 7234](https://tools.ietf.org/html/rfc7234) and their output changes even if the data has not. A recommended setup is therefore to use their cached `apicdn` endpoint (see above) and then set up a reasonable polling and file cache strategy in your Hugo configuration, e.g:
+<!-- markdownlint-disable MD049 -->
{{< code-toggle file=hugo >}}
[HTTPCache]
[[HTTPCache.polls]]
dir = ':cacheDir/:project'
maxAge = "5m"
{{< /code-toggle >}}
+<!-- markdownlint-enable MD049 -->
The polling above will be used when running the server/watch mode and rebuild when you push new content in Sanity.
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 }}
- ```
+ ```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.
+ 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.22/dist/katex.min.css" rel="stylesheet">
+ ```html
+ <link href="https://cdn.jsdelivr.net/npm/katex@0.16.22/dist/katex.min.css" rel="stylesheet">
strict
: {{< new-in 0.147.6 />}}
- `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.
+ 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`.
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
+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.
-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.
-
-{{< 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 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/_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 -}}
-```
-
-### Step 3
-
-In your base template, conditionally include the KaTeX CSS within the head element.
-
-```go-html-template {file="layouts/baseof.html" copy=true}
-<head>
- {{ $noop := .WordCount }}
- {{ if .Page.Store.Get "hasMath" }}
- <link href="https://cdn.jsdelivr.net/npm/katex@0.16.22/dist/katex.min.css" rel="stylesheet">
- {{ end }}
-</head>
-```
-
-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
+[passthrough extension]: /configuration/markup/#passthrough
-Add some mathematical markup to your content, then test.
+ {{< code-toggle file=hugo copy=true >}}
+ [markup.goldmark.extensions.passthrough]
+ enable = true
+ [markup.goldmark.extensions.passthrough.delimiters]
+ block = [['\[', '\]'], ['$$', '$$']]
+ inline = [['\(', '\)']]
+ {{< /code-toggle >}}
-```text {file="content/example.md"}
-This is an inline \(a^*=x-b^*\) equation.
+ > [!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 must double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting.
-These are block equations:
+Step 2
+: Create a [passthrough render hook][] to capture and render the LaTeX markup.4
-\[a^*=x-b^*\]
+[passthrough render hook]: /render-hooks/passthrough/
-$$a^*=x-b^*$$
-```
+ ```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 }}
+ {{- 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 -}}
+ ```
+
+Step 3
+: In your base template, conditionally include the KaTeX CSS within the head element.
+
+ ```go-html-template {file="layouts/baseof.html" copy=true}
+ <head>
+ {{ $noop := .WordCount }}
+ {{ if .Page.Store.Get "hasMath" }}
+ <link href="https://cdn.jsdelivr.net/npm/katex@0.16.22/dist/katex.min.css" rel="stylesheet">
+ {{ end }}
+ </head>
+ ```
+
+ 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.
+
+ ```text {file="content/example.md"}
+ This is an inline \(a^*=x-b^*\) equation.
+
+ These are block equations:
+
+ \[a^*=x-b^*\]
+
+ $$a^*=x-b^*$$
+ ```
## Chemistry
[KaTeX]: https://katex.org/
[MathML]: https://developer.mozilla.org/en-US/docs/Web/MathML
[mhchem]: https://mhchem.github.io/MathJax-mhchem/
-[passthrough extension]: /configuration/markup/#passthrough
-[passthrough render hook]: /render-hooks/passthrough/
[rendering options]: https://katex.org/docs/options.html
├── i18n/
├── layouts/
├── static/
-├── LICENSE
-├── README.md
-├── hugo.toml
-└── theme.toml
+└── hugo.toml
```
Using the union file system described above, Hugo mounts each of these directories to the corresponding location in the project. When two files have the same path, the file in the project directory takes precedence. This allows you, for example, to override a theme's template by placing a copy in the same location within the project directory.
weight: 40
---
+> [!note]
+> Many of the resources on this page, including older books and videos, may contain out-of-date information. The Hugo software has undergone significant changes since these resources were created. These changes include the introduction of a new template system, the deprecation of various functions and settings, and the addition of new features like Markdown render hooks, content adapters, and support for mathematical markup. While some concepts may still be relevant, it's recommended to consult the official Hugo documentation for the most current and accurate information.
+
## Books
### Hugo in Action
+++ /dev/null
----
-title: Host on 21YunBox
-description: Host your site on 21YunBox.
-categories: []
-keywords: []
-aliases: [/hosting-and-deployment/hosting-on-21yunbox/]
----
-
-[21YunBox](https://www.21cloudbox.com/) is a fully-managed cloud platform dedicated to make web deployment easy within the Chinese Great Firewall where you can host static sites, backend APIs, databases, cron jobs, and all your other apps in one place. It provides blazing fast Chinese CDN, continuous deployment, one-click HTTPS and [other services like managed databases and backend web services](https://www.21cloudbox.com/docs/), providing an avenue to launch web projects in China.
-
-21YunBox includes the following features:
-
-- Continuous, automatic builds & deploys from GitHub and Gitee
-- Automatic SSL certificates through [Let's Encrypt](https://letsencrypt.org)
-- Instant cache invalidation with a blazing fast, Chinese CDN
-- Unlimited [custom domains](https://www.21cloudbox.com/dns-configuration.html)
-- Automatic [Brotli compression](https://en.wikipedia.org/wiki/Brotli) for faster sites
-- Native HTTP/2 support
-- Automatic HTTP → HTTPS redirects
-- Custom URL redirects and rewrites
-
-## Prerequisites
-
-This guide assumes you already have a Hugo project to deploy. If you need a project, use the [Quick Start](/getting-started/quick-start/) to get started or fork 21YunBox's [Hugo Example](https://gitee.com/eryiyunbox-examples/hello-hugo) before continuing.
-
-## Setup
-
-You can set up a Hugo site on 21YunBox in two quick steps:
-
-1. Create a new web service on 21YunBox, and give 21YunBox permission to access your GitHub or Gitee repo.
-1. Use the following values during creation:<!-- do not insert blank line -->
- | Field | Value |
- | ----------------- | ------------------------------------------------ |
- | Environment | `Static Site` |
- | Build Command | `hugo --gc --minify` (or your own build command) |
- | Publish Directory | `./public` (or your own output directory) |
-
-That's it! Your site will be live on your 21YunBox URL (which looks like `yoursite.21yunbox.com`) as soon as the build is done.
-
-## Continuous deploys
-
-Now that 21YunBox is connected to your repo, it will automatically build and publish your site any time you push to GitHub.
-
-Every deploy automatically and instantly invalidates the CDN cache, so your users can always access the latest content on your site.
-
-## Custom domains
-
-Add your own domains to your site easily using 21YunBox's [custom domains](https://www.21cloudbox.com/dns-configuration.html) guide.
-
-## Support
-
-Click [here](https://www.21cloudbox.com/contact.html) to contact with 21YunBox' experts if you need help.
aliases: [/hosting-and-deployment/hosting-on-aws-amplify/]
---
+Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using GitLab for version control.
+
## Prerequisites
Please complete the following tasks before continuing:
-1. [Create an AWS account]
-1. [Install Git]
-1. [Create a Hugo site] and test it locally with `hugo server`
-1. Commit the changes to your local repository
-1. Push the local repository to your [GitHub], [GitLab], or [Bitbucket] account
-
-[Bitbucket]: https://bitbucket.org/product
-[Create a Hugo site]: /getting-started/quick-start/
-[Create an AWS account]: https://aws.amazon.com/resources/create-account/
-[GitHub]: https://github.com
-[GitLab]: https://about.gitlab.com/
-[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+1. [Create](https://aws.amazon.com/resources/create-account/) an AWS account
+1. [Log in](https://console.aws.amazon.com/) to your AWS account
+1. [Create](https://github.com/signup) a GitHub account
+1. [Log in](https://github.com/login) to your GitHub account
+1. [Create](https://github.com/new) a GitHub repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
+1. Create a Hugo site within your local Git repository and test it with the `hugo server` command
+1. Commit the changes to your local Git repository and push to your GitHub repository.
## Procedure
This procedure will enable continuous deployment from a GitHub repository. The procedure is essentially the same if you are using GitLab or Bitbucket.
-### Step 1
-
-Create a file named `amplify.yml` in the root of your project.
-
-```sh
-touch amplify.yml
-```
-
-### Step 2
-
-Copy and paste the YAML below into the file you created. Change the application versions and time zone as needed.
-
-```yaml {file="amplify.yml" copy=true}
-version: 1
-env:
- variables:
- # Application versions
- DART_SASS_VERSION: 1.89.2
- GO_VERSION: 1.24.2
- HUGO_VERSION: 0.147.9
- # Time zone
- TZ: America/Los_Angeles
- # Cache
- HUGO_CACHEDIR: ${PWD}/.hugo
- NPM_CONFIG_CACHE: ${PWD}/.npm
-frontend:
- phases:
- preBuild:
- commands:
- # Install Dart Sass
- - curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
- - sudo tar -C /usr/local/bin -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
- - rm dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
- - export PATH=/usr/local/bin/dart-sass:$PATH
-
- # Install Go
- - curl -LJO https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz
- - sudo tar -C /usr/local -xf go${GO_VERSION}.linux-amd64.tar.gz
- - rm go${GO_VERSION}.linux-amd64.tar.gz
- - export PATH=/usr/local/go/bin:$PATH
-
- # Install Hugo
- - curl -LJO https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz
- - sudo tar -C /usr/local/bin -xf hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz
- - rm hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz
- - export PATH=/usr/local/bin:$PATH
-
- # Check installed versions
- - go version
- - hugo version
- - node -v
- - npm -v
- - sass --embedded --version
-
- # Install Node.JS dependencies
- - "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci --prefer-offline || true"
-
- # https://github.com/gohugoio/hugo/issues/9810
- - git config --add core.quotepath false
- build:
- commands:
- - hugo --gc --minify
- artifacts:
- baseDirectory: public
- files:
- - '**/*'
- cache:
- paths:
- - ${HUGO_CACHEDIR}/**/*
- - ${NPM_CONFIG_CACHE}/**/*
-```
-
-### Step 3
-
-Commit and push the change to your GitHub repository.
-
-```sh
-git add -A
-git commit -m "Create amplify.yml"
-git push
-```
-
-### Step 4
-
-Log in to your AWS account, navigate to the [Amplify Console], then press the **Deploy an app** button.
-
-[Amplify Console]: https://console.aws.amazon.com/amplify/apps
-
-### Step 5
-
-Choose a source code provider, then press the **Next** button.
+Step 1
+: Create a file named `amplify.yml` in the root of your project.
+
+ ```sh
+ touch amplify.yml
+ ```
+
+Step 2
+: Copy and paste the YAML below into the file you created. Change the application versions and time zone as needed.
+
+ ```yaml {file="amplify.yml" copy=true}
+ version: 1
+ env:
+ variables:
+ # Application versions
+ DART_SASS_VERSION: 1.90.0
+ GO_VERSION: 1.24.5
+ HUGO_VERSION: 0.148.2
+ # Time zone
+ TZ: Europe/Oslo
+ # Cache
+ HUGO_CACHEDIR: ${PWD}/.hugo
+ NPM_CONFIG_CACHE: ${PWD}/.npm
+ frontend:
+ phases:
+ preBuild:
+ commands:
+ # Create directory for user-specific executable files
+ - echo "Creating directory for user-specific executable files..."
+ - mkdir -p "${HOME}/.local"
+
+ # Install Dart Sass
+ - echo "Installing Dart Sass ${DART_SASS_VERSION}..."
+ - curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ - tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ - rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ - export PATH="${HOME}/.local/dart-sass:${PATH}"
+
+ # Install Go
+ - echo "Installing Go ${GO_VERSION}..."
+ - curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz"
+ - tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz"
+ - rm "go${GO_VERSION}.linux-amd64.tar.gz"
+ - export PATH="${HOME}/.local/go/bin:${PATH}"
+
+ # Install Hugo
+ - echo "Installing Hugo ${HUGO_VERSION}..."
+ - curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ - mkdir "${HOME}/.local/hugo"
+ - tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ - rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ - export PATH="${HOME}/.local/hugo:${PATH}"
+
+ # Verify installations
+ - echo "Verifying installations..."
+ - "echo Dart Sass: $(sass --version)"
+ - "echo Go: $(go version)"
+ - "echo Hugo: $(hugo version)"
+ - "echo Node.js: $(node --version)"
+
+ # Install Node.js dependencies
+ - echo "Installing Node.js dependencies..."
+ - "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci --prefer-offline || true"
+
+ # Configure Git
+ - echo "Configuring Git..."
+ - git config core.quotepath false
+ build:
+ commands:
+ - echo "Building site..."
+ - hugo --gc --minify
+ artifacts:
+ baseDirectory: public
+ files:
+ - '**/*'
+ cache:
+ paths:
+ - ${HUGO_CACHEDIR}/**/*
+ - ${NPM_CONFIG_CACHE}/**/*
+ ```
+
+Step 3
+: Commit and push the change to your GitHub repository.
+
+ ```sh
+ git add -A
+ git commit -m "Create amplify.yml"
+ git push
+ ```
+
+Step 4
+: Log in to your AWS account, navigate to the [Amplify Console], then press the **Deploy an app** button.
+
+Step 5
+: Choose a source code provider, then press the **Next** button.
-### Step 6
-
-Authorize AWS Amplify to access your GitHub account.
+Step 6
+: Authorize AWS Amplify to access your GitHub account.
-### Step 7
-
-Select your personal account or relevant organization.
+Step 7
+: Select your personal account or relevant organization.
-### Step 8
-
-Authorize access to one or more repositories.
+Step 8
+: Authorize access to one or more repositories.
-### Step 9
-
-Select a repository and branch, then press the **Next** button.
+Step 9
+: Select a repository and branch, then press the **Next** button.
-### Step 10
-
-On the "App settings" page, scroll to the bottom then press the **Next** button. Amplify reads the `amplify.yml` file you created in Steps 1-3 instead of using the values on this page.
-
-### Step 11
+Step 10
+: On the "App settings" page, scroll to the bottom then press the **Next** button. Amplify reads the `amplify.yml` file you created in Steps 1-3 instead of using the values on this page.
-On the "Review" page, scroll to the bottom then press the **Save and deploy** button.
+Step 11
+: On the "Review" page, scroll to the bottom then press the **Save and deploy** button.
-### Step 12
-
-When your site has finished deploying, press the **Visit deployed URL** button to view your published site.
+Step 12
+: When your site has finished deploying, press the **Visit deployed URL** button to view your published site.
+
+[Amplify Console]: https://console.aws.amazon.com/amplify/apps
+++ /dev/null
----
-title: Host on Cloudflare Pages
-description: Host your site on Cloudflare Pages.
-categories: []
-keywords: []
-aliases: [/hosting-and-deployment/hosting-on-cloudflare-pages/]
----
-
-[Cloudflare Pages](https://developers.cloudflare.com/pages/) are super fast, always up-to-date, and deployed directly from your [Git provider](https://developers.cloudflare.com/pages/get-started/#connect-your-git-provider-to-pages).
-
-Cloudflare Pages docs have a detailed tutorial on [how to deploy a Hugo site](https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site/).
--- /dev/null
+---
+title: Host on Cloudflare
+description: Host your site on Cloudflare.
+categories: []
+keywords: []
+---
+
+Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using GitLab for version control.
+
+## Prerequisites
+
+Please complete the following tasks before continuing:
+
+1. [Create](https://dash.cloudflare.com/sign-up) a Cloudflare account
+1. [Log in](https://dash.cloudflare.com/login) to your Cloudflare account
+1. [Create](https://github.com/signup) a GitHub account
+1. [Log in](https://github.com/login) to your GitHub account
+1. [Create](https://github.com/new) a GitHub repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
+1. Create a Hugo site within your local Git repository and test it with the `hugo server` command
+
+## Procedure
+
+Step 1
+: Create a `wrangler.toml` file in the root of your project.
+
+ ```toml {file="wrangler.toml" copy=true}
+ # Configure Cloudflare Worker
+
+ name = "hosting-cloudflare-worker"
+ compatibility_date = "2025-07-31"
+
+ [build]
+ command = "chmod a+x build.sh && ./build.sh"
+
+ [assets]
+ directory = "./public"
+ not_found_handling = "404"
+ ```
+
+Step 2
+: Create a `build.sh` file in the root of your project.
+
+ ```sh {file="build.sh" copy=true}
+ #!/usr/bin/env bash
+
+ #------------------------------------------------------------------------------
+ # @file
+ # Builds a Hugo site hosted on a Cloudflare Worker.
+ #
+ # The Cloudflare Worker automatically installs Node.js dependencies.
+ #------------------------------------------------------------------------------
+
+ main() {
+
+ DART_SASS_VERSION=1.90.0
+ GO_VERSION=1.24.5
+ HUGO_VERSION=0.148.2
+ NODE_VERSION=22.18.0
+
+ export TZ=Europe/Oslo
+
+ # Install Dart Sass
+ echo "Installing Dart Sass ${DART_SASS_VERSION}..."
+ curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ export PATH="${HOME}/.local/dart-sass:${PATH}"
+
+ # Install Go
+ echo "Installing Go ${GO_VERSION}..."
+ curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz"
+ tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz"
+ rm "go${GO_VERSION}.linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/go/bin:${PATH}"
+
+ # Install Hugo
+ echo "Installing Hugo ${HUGO_VERSION}..."
+ curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ mkdir "${HOME}/.local/hugo"
+ tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/hugo:${PATH}"
+
+ # Install Node.js
+ echo "Installing Node.js ${NODE_VERSION}..."
+ curl -sLJO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz"
+ tar -C "${HOME}/.local" -xf "node-v${NODE_VERSION}-linux-x64.tar.xz"
+ rm "node-v${NODE_VERSION}-linux-x64.tar.xz"
+ export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}"
+
+ # Verify installations
+ echo "Verifying installations..."
+ echo Dart Sass: "$(sass --version)"
+ echo Go: "$(go version)"
+ echo Hugo: "$(hugo version)"
+ echo Node.js: "$(node --version)"
+
+ # Configure Git
+ echo "Configuring Git..."
+ git config core.quotepath false
+ if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
+ git fetch --unshallow
+ fi
+
+ # Build the site
+ echo "Building the site..."
+ hugo --gc --minify
+
+ }
+
+ set -euo pipefail
+ main "$@"
+ ```
+
+Step 3
+: Commit the changes to your local Git repository and push to your GitHub repository.
+
+Step 4
+: In the upper right corner of the Cloudflare [dashboard](https://dash.cloudflare.com/), press the **Add** button and select "Workers" from the drop down menu.
+
+ 
+
+Step 5
+: On the "Workers" tab, press the **Get started** button to the right of the "Import a repository" item.
+
+ 
+
+Step 6
+: Connect to GitHub.
+
+ 
+
+Step 7
+: Select the GitHub account where you want to install the Cloudflare Workers and Pages application.
+
+ 
+
+Step 8
+: Authorize the Cloudflare Workers and Pages application to access all repositories or only select repositories, then press the **Install & Authorize** button.
+
+ 
+
+ Your browser will be redirected to the Cloudflare dashboard.
+
+Step 9
+: On the "Workers" tab, press the **Get started** button to the right of the "Import a repository" item.
+
+ 
+
+Step 10
+: Select the repository to import.
+
+ 
+
+Step 11
+: On the "Set up your application" screen, provide a project name, leave the build command blank, then press the **Create and deploy** button.
+
+ 
+
+Step 12
+: Wait for the site to build and deploy, then visit your site.
+
+ 
+
+In the future, whenever you push a change from your local Git repository, Cloudflare will rebuild and deploy your site.
git push -u origin main
```
-## Automated deployment using Woodpecker CI
+## Automated deployment
-There are two methods you can use to deploy your Hugo website to Codeberg automatically. These are: Woodpecker CI and Forgejo Actions.
+You can automatically deploy your Hugo website to Codeberg using one of two methods: Woodpecker CI or Forgejo Actions.
+
+### Woodpecker CI
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].
Your project will then be built and deployed by Codeberg's Woodpecker CI.
-## Automated deployment using Forgejo Actions
+### 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.
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"
+ image: "hugomods/hugo:exts-0.148.0"
steps:
- name: Clone the repository
uses: https://code.forgejo.org/actions/checkout@v4
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://<YourUsername>.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:
+1. 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` | `<YourUsername>/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) |
+1. 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.
+1. 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.
+1. Navigate to the "Variables" submenu of the "Actions" menu and add the following variables:
+
+Name|Value
+:--|:--
+`TARGET_REPOSITORY`|`<YourUsername>/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:
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"
+ image: "hugomods/hugo:exts-0.148.0"
steps:
- name: Clone the repository
uses: https://code.forgejo.org/actions/checkout@v4
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**.
+## Forgejo Actions custom domains
+
+Codeberg Pages relies on a `.domains` file to identify allowed domains for a specific branch. It's important that this file is located in the root directory of your output repository or branch, rather than in the root directory of your source files. To achieve this, simply place your `.domains` file in the `static` directory of your project. When your site is built, it will be automatically copied to the `public` directory, which serves as the root of your output.
+
+When looking at the example `.forgejo/workflows/hugo.yaml`, you'll notice that the `upload-artifact@v3` action is used to upload the public directory to the deployment branch.
+
+By default, both `upload-artifact@v3` and `upload-artifact@v4` exclude all dot files from being uploaded unless you specifically tell them not to (you can find more details [here]).
+
+By default, upload-artifact@v3 and upload-artifact@v4 exclude all dot files from being uploaded. You can find more details on [how to handle dot files and other file patterns in the documentation](https://github.com/actions/upload-artifact/issues/602). To make sure dot files are included, modify your workflow like this:
+
+```yaml {file=".forgejo/workflows/hugo.yaml" copy=true}
+ - name: Upload generated files
+ uses: https://code.forgejo.org/actions/upload-artifact@v3
+ with:
+ name: Generated files
+ path: public/
+ include-hidden-files: true # Prevents excluding .domains from uploading
+```
+
+If you're using a custom domain, it's important to update your workflow file accordingly.
+
## Other resources
- [Codeberg Pages](https://codeberg.page/)
In new versions of Firebase, some other questions apply:
-6. Set up automatic builds and deploys with GitHub?
+1. Set up automatic builds and deploys with GitHub?
-Here you will be redirected to login in your GitHub account to get permissions. Confirm.
+ Here you will be redirected to login in your GitHub account to get permissions. Confirm.
-7. For which GitHub repository would you like to set up a GitHub workflow? (format: user/repository)
+1. For which GitHub repository would you like to set up a GitHub workflow? (format: user/repository)
-Include the repository you will use in the format above (Account/Repo)
-Firebase script with retrieve credentials, create a service account you can later manage in your GitHub settings.
+ Include the repository you will use in the format above (Account/Repo)
+ Firebase script with retrieve credentials, create a service account you can later manage in your GitHub settings.
-8. Set up the workflow to run a build script before every deploy?
+1. Set up the workflow to run a build script before every deploy?
-Here is your opportunity to include some commands before you run the deploy.
+ Here is your opportunity to include some commands before you run the deploy.
-9. Set up automatic deployment to your site's live channel when a PR is merged?
+1. Set up automatic deployment to your site's live channel when a PR is merged?
-You can let in the default option (main)
+ You can let in the default option (main)
After that Firebase has been set in your project with [CI/CD](g). After that run:
hugo && firebase deploy
```
-With this you will have the app initialized manually. After that you can manage and fix your GitHub workflow from: https://github.com/your-account/your-repo/actions
+With this you will have the app initialized manually. After that you can manage and fix your GitHub workflow from <https://github.com/your-account/your-repo/actions>.
Don't forget to update your static pages before push!
aliases: [/hosting-and-deployment/hosting-on-github/]
---
-## Prerequisites
-
-Please complete the following tasks before continuing:
-
-1. [Create a GitHub account]
-1. [Install Git]
-1. [Create a Hugo site] and test it locally with `hugo server`.
-
## Types of sites
There are three types of GitHub Pages sites: project, user, and organization. Project sites are connected to a specific project hosted on GitHub. User and organization sites are connected to a specific account on GitHub.com.
> [!note]
> See the [GitHub Pages documentation] to understand the requirements for repository ownership and naming.
-## Procedure
-
-### Step 1
-
-Create a GitHub repository.
-
-### Step 2
-
-Push your local repository to GitHub.
-
-### Step 3
-
-Visit your GitHub repository. From the main menu choose **Settings** > **Pages**. In the center of your screen you will see this:
-
-
-{style="max-width: 280px"}
-
-### Step 4
-
-Change the **Source** to `GitHub Actions`. The change is immediate; you do not have to press a Save button.
-
-
-{style="max-width: 280px"}
-
-### Step 5
-
-In your site configuration, change the location of the image cache to the [`cacheDir`] as shown below:
-
-{{< code-toggle file=hugo >}}
-[caches.images]
-dir = ":cacheDir/images"
-{{< /code-toggle >}}
-
-See [configure file caches] for more information.
-
-### Step 6
-
-Create a file named `hugo.yaml` in a directory named `.github/workflows`.
-
-```text
-mkdir -p .github/workflows
-touch .github/workflows/hugo.yaml
-```
-
-### Step 7
-
-> [!note]
-> The workflow below ensures Hugo's `cacheDir` is persistent, preserving modules, processed images, and [`resources.GetRemote`] data between builds.
-
-Copy and paste the YAML below into the file you created. Change the branch name and Hugo version as needed.
-
-```yaml {file=".github/workflows/hugo.yaml" copy=true}
-# Sample workflow for building and deploying a Hugo site to GitHub Pages
-name: Deploy Hugo site to Pages
-
-on:
- # Runs on pushes targeting the default branch
- push:
- branches:
- - main
-
- # Allows you to run this workflow manually from the Actions tab
- workflow_dispatch:
-
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
-permissions:
- contents: read
- pages: write
- id-token: write
-
-# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
-# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
-concurrency:
- group: "pages"
- cancel-in-progress: false
-
-# Default to bash
-defaults:
- run:
- shell: bash
-
-jobs:
- # Build job
- build:
- runs-on: ubuntu-latest
- env:
- DART_SASS_VERSION: 1.89.2
- HUGO_VERSION: 0.147.9
- HUGO_ENVIRONMENT: production
- TZ: America/Los_Angeles
- steps:
- - name: Install Hugo CLI
- run: |
- 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: |
- 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:
- submodules: recursive
- fetch-depth: 0
- - name: Setup Pages
- id: pages
- uses: actions/configure-pages@v5
- - name: Install Node.js dependencies
- run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
- - name: Cache Restore
- id: cache-restore
- uses: actions/cache/restore@v4
- with:
- path: |
- ${{ runner.temp }}/hugo_cache
- key: hugo-${{ github.run_id }}
- restore-keys:
- hugo-
- - name: Configure Git
- run: git config core.quotepath false
- - name: Build with Hugo
- run: |
- hugo \
- --gc \
- --minify \
- --baseURL "${{ steps.pages.outputs.base_url }}/" \
- --cacheDir "${{ runner.temp }}/hugo_cache"
- - name: Cache Save
- id: cache-save
- uses: actions/cache/save@v4
- with:
- path: |
- ${{ runner.temp }}/hugo_cache
- key: ${{ steps.cache-restore.outputs.cache-primary-key }}
- - name: Upload artifact
- uses: actions/upload-pages-artifact@v3
- with:
- path: ./public
-
- # Deployment job
- deploy:
- environment:
- name: github-pages
- url: ${{ steps.deployment.outputs.page_url }}
- runs-on: ubuntu-latest
- needs: build
- steps:
- - name: Deploy to GitHub Pages
- id: deployment
- uses: actions/deploy-pages@v4
-```
-
-### Step 8
-
-Commit and push the change to your GitHub repository.
-
-```sh
-git add -A
-git commit -m "Create hugo.yaml"
-git push
-```
-
-### Step 9
-
-From GitHub's main menu, choose **Actions**. You will see something like this:
-
-
-{style="max-width: 350px"}
-
-### Step 10
-
-When GitHub has finished building and deploying your site, the color of the status indicator will change to green.
-
-
-{style="max-width: 350px"}
-
-### Step 11
+## Prerequisites
-Click on the commit message as shown above. You will see this:
+Please complete the following tasks before continuing:
-
-{style="max-width: 611px"}
+1. [Create](https://github.com/signup) a GitHub account
+1. [Log in](https://github.com/login) to your GitHub account
+1. [Create](https://github.com/new) a GitHub repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
+1. Create a Hugo site within your local Git repository and test it with the `hugo server` command
+1. Commit the changes to your local Git repository and push to your GitHub repository
-Under the deploy step, you will see a link to your live site.
+## Procedure
-In the future, whenever you push a change from your local repository, GitHub will rebuild your site and deploy the changes.
+Step 1
+: Visit your GitHub repository. From the main menu choose **Settings** > **Pages**. In the center of your screen you will see this:
+
+ 
+
+ Change the **Source** to `GitHub Actions`. The change is immediate; you do not have to press a Save button.
+
+ 
+
+Step 2
+: In your site configuration, change the location of the image cache to the [`cacheDir`] as shown below:
+
+ {{< code-toggle file=hugo copy=true >}}
+ [caches.images]
+ dir = ":cacheDir/images"
+ {{< /code-toggle >}}
+
+ See [configure file caches] for more information.
+
+Step 3
+: Create a file named `hugo.yaml` in a directory named `.github/workflows`.
+
+ ```text
+ mkdir -p .github/workflows
+ touch .github/workflows/hugo.yaml
+ ```
+
+Step 4
+: Copy and paste the YAML below into the file you created.
+
+ ```yaml {file=".github/workflows/hugo.yaml" copy=true}
+ name: Build and deploy
+ on:
+ push:
+ branches:
+ - main
+ workflow_dispatch:
+ permissions:
+ contents: read
+ pages: write
+ id-token: write
+ concurrency:
+ group: pages
+ cancel-in-progress: false
+ defaults:
+ run:
+ shell: bash
+ jobs:
+ build:
+ runs-on: ubuntu-latest
+ env:
+ DART_SASS_VERSION: 1.90.0
+ GO_VERSION: 1.24.5
+ HUGO_VERSION: 0.148.2
+ NODE_VERSION: 22.18.0
+ TZ: Europe/Oslo
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v5
+ with:
+ submodules: recursive
+ fetch-depth: 0
+ - name: Setup Go
+ uses: actions/setup-go@v5
+ with:
+ go-version: ${{ env.GO_VERSION }}
+ cache: false
+ - name: Setup Node.js
+ uses: actions/setup-node@v4
+ with:
+ node-version: ${{ env.NODE_VERSION }}
+ - name: Setup Pages
+ id: pages
+ uses: actions/configure-pages@v5
+ - name: Create directory for user-specific executable files
+ run: |
+ mkdir -p "${HOME}/.local"
+ - name: Install Dart Sass
+ run: |
+ curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ echo "${HOME}/.local/dart-sass" >> "${GITHUB_PATH}"
+ - name: Install Hugo
+ run: |
+ curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ mkdir "${HOME}/.local/hugo"
+ tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ echo "${HOME}/.local/hugo" >> "${GITHUB_PATH}"
+ - name: Verify installations
+ run: |
+ echo "Dart Sass: $(sass --version)"
+ echo "Go: $(go version)"
+ echo "Hugo: $(hugo version)"
+ echo "Node.js: $(node --version)"
+ - name: Install Node.js dependencies
+ run: |
+ [[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true
+ - name: Configure Git
+ run: |
+ git config core.quotepath false
+ - name: Cache restore
+ id: cache-restore
+ uses: actions/cache/restore@v4
+ with:
+ path: ${{ runner.temp }}/hugo_cache
+ key: hugo-${{ github.run_id }}
+ restore-keys:
+ hugo-
+ - name: Build the site
+ run: |
+ hugo \
+ --gc \
+ --minify \
+ --baseURL "${{ steps.pages.outputs.base_url }}/" \
+ --cacheDir "${{ runner.temp }}/hugo_cache"
+ - name: Cache save
+ id: cache-save
+ uses: actions/cache/save@v4
+ with:
+ path: ${{ runner.temp }}/hugo_cache
+ key: ${{ steps.cache-restore.outputs.cache-primary-key }}
+ - name: Upload artifact
+ uses: actions/upload-pages-artifact@v3
+ with:
+ path: ./public
+ deploy:
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ runs-on: ubuntu-latest
+ needs: build
+ steps:
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v4
+ ```
+
+Step 5
+: Commit the changes to your local Git repository and push to your GitHub repository.
+
+Step 6
+: From GitHub's main menu, choose **Actions**. You will see something like this:
+
+ 
+
+Step 7
+: When GitHub has finished building and deploying your site, the color of the status indicator will change to green.
+
+ 
+
+Step 8
+: Click on the commit message as shown above. Under the deploy step, you will see a link to your live site.
+
+ 
+
+In the future, whenever you push a change from your local Git repository, GitHub Pages will rebuild and deploy your site.
## Customize the workflow
- [Caching dependencies to speed up workflows](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows)
- [Manage a custom domain for your GitHub Pages site](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages)
-[Create a GitHub account]: https://github.com/signup
-[Create a Hugo site]: /getting-started/quick-start/
-[Dart Sass]: /functions/css/sass/#dart-sass
-[GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites
-[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
[`cacheDir`]: /configuration/all/#cachedir
-[`resources.GetRemote`]: /functions/resources/getremote/
[configure file caches]: /configuration/caches/
+[Dart Sass]: /functions/css/sass/#dart-sass
+[GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites
```yaml {file=".gitlab-ci.yml" copy=true}
variables:
- DART_SASS_VERSION: 1.89.2
+ # Application versions
+ DART_SASS_VERSION: 1.90.0
+ HUGO_VERSION: 0.148.2
+ NODE_VERSION: 22.18.0
+ # Git
GIT_DEPTH: 0
GIT_STRATEGY: clone
GIT_SUBMODULE_STRATEGY: recursive
- HUGO_VERSION: 0.147.9
- NODE_VERSION: 22.x
- TZ: America/Los_Angeles
+ # Time zone
+ TZ: Europe/Oslo
+
image:
- name: golang:1.24.2-bookworm
+ name: golang:1.24.5-bookworm
pages:
stage: deploy
script:
- # Install brotli
+ # Create directory for user-specific executable files
+ - echo "Creating directory for user-specific executable files..."
+ - mkdir -p "${HOME}/.local"
+
+ # Install utilities
+ - echo "Installing utilities..."
- apt-get update
- - apt-get install -y brotli
+ - apt-get install -y brotli xz-utils zstd
+
# Install Dart Sass
- - curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
- - tar -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
- - cp -r dart-sass/ /usr/local/bin
- - rm -rf dart-sass*
- - export PATH=/usr/local/bin/dart-sass:$PATH
+ - echo "Installing Dart Sass ${DART_SASS_VERSION}..."
+ - curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ - tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ - rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ - export PATH="${HOME}/.local/dart-sass:${PATH}"
+
# Install Hugo
- - curl -LJO https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
- - apt-get install -y ./hugo_extended_${HUGO_VERSION}_linux-amd64.deb
- - rm hugo_extended_${HUGO_VERSION}_linux-amd64.deb
+ - echo "Installing Hugo ${HUGO_VERSION}..."
+ - curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ - mkdir "${HOME}/.local/hugo"
+ - tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ - rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ - export PATH="${HOME}/.local/hugo:${PATH}"
+
# Install Node.js
- - curl -fsSL https://deb.nodesource.com/setup_${NODE_VERSION} | bash -
- - apt-get install -y nodejs
+ - echo "Installing Node.js ${NODE_VERSION}..."
+ - curl -sLJO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz"
+ - tar -C "${HOME}/.local" -xf "node-v${NODE_VERSION}-linux-x64.tar.xz"
+ - rm "node-v${NODE_VERSION}-linux-x64.tar.xz"
+ - export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}"
+
+ # Verify installations
+ - echo "Verifying installations..."
+ - "echo Dart Sass: $(sass --version)"
+ - "echo Go: $(go version)"
+ - "echo Hugo: $(hugo version)"
+ - "echo Node.js: $(node --version)"
+ - "echo brotli: $(brotli --version)"
+ - "echo xz: $(xz --version)"
+ - "echo zstd: $(zstd --version)"
+
# Install Node.js dependencies
- - "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
+ - echo "Installing Node.js dependencies..."
+ - "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci --prefer-offline || true"
+
# Configure Git
+ - echo "Configuring Git..."
- git config core.quotepath false
- # Build
- - hugo --gc --minify --baseURL ${CI_PAGES_URL}
- # Compress
- - find public -type f -regex '.*\.\(css\|html\|js\|txt\|xml\)$' -exec gzip -f -k {} \;
- - find public -type f -regex '.*\.\(css\|html\|js\|txt\|xml\)$' -exec brotli -f -k {} \;
+
+ # Build site
+ - echo "Building site..."
+ - hugo --gc --minify --baseURL "${CI_PAGES_URL}"
+
+ # Compress published files
+ - echo "Compressing published files..."
+ - find public/ -type f -regextype posix-extended -regex '.+\.(css|html|js|json|mjs|svg|txt|xml)$' -print0 > files.txt
+ - time xargs --null --max-procs=0 --max-args=1 brotli --quality=10 --force --keep < files.txt
+ - time xargs --null --max-procs=0 --max-args=1 gzip -9 --force --keep < files.txt
artifacts:
paths:
- public
## Push your Hugo website to GitLab
-Next, create a new repository on GitLab. It is *not* necessary to make the repository public. In addition, you might want to add `/public` to your .gitignore file, as there is no need to push compiled assets to GitLab or keep your output website in version control.
+Next, create a new repository on GitLab. It is not necessary to make the repository public. In addition, you might want to add `/public` to your .gitignore file, as there is no need to push compiled assets to GitLab or keep your output website in version control.
```sh
# initialize new git repository
+++ /dev/null
----
-title: Host on KeyCDN
-description: Host your site on KeyCDN.
-categories: []
-keywords: []
-aliases: [/hosting-and-deployment/hosting-on-keycdn/]
----
-
-[KeyCDN](https://www.keycdn.com/) provides a multitude of features to help accelerate and secure your Hugo site globally including Brotli compression, Let's Encrypt support, Origin Shield, and more.
-
-## Assumptions
-
-- You already have a Hugo page configured
-- You have a GitLab account
-- You have a KeyCDN account
-
-## Create a KeyCDN Pull Zone
-
-The first step will be to log in to your KeyCDN account and create a new zone. Name this whatever you like and select the [Pull Zone](https://www.keycdn.com/support/create-a-pull-zone/) option. As for the origin URL, your site will be running on [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/getting_started_part_one.html) with a URL of `https://youruser.gitlab.io/reponame/`. Use this as the Origin URL.
-
-
-
-While the origin location doesn't exist yet, you will need to use your new Zone URL address (or [Zone Alias](https://www.keycdn.com/support/create-a-zone-alias/)) in the `.gitlab-ci.yml` file that will be uploaded to your GitLab project.
-
-Ensure that you use your Zone URL or Zone alias as the `BASEURL` variable in the example below. This will be the user-visible website address.
-
-## Configure Your .gitlab-ci.yml File
-
-Your `.gitlab-ci.yml` file should look similar to the example below. Be sure to modify any variables that are specific to your setup.
-
-```yml
-image: alpine:latest
-
-variables:
- BASEURL: "https://cipull-7bb7.kxcdn.com/"
- HUGO_VERSION: "0.26"
- HUGO_CHECKSUM: "67e4ba5ec2a02c8164b6846e30a17cc765b0165a5b183d5e480149baf54e1a50"
- KEYCDN_ZONE_ID: "75544"
-
-before_script:
- - apk update
- - apk add curl
-
-pages:
- stage: deploy
- script:
- - apk add git
- - git submodule update --init
- - curl -sSL https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_Linux-64bit.tar.gz -o /tmp/hugo.tar.gz
- - echo "${HUGO_CHECKSUM} /tmp/hugo.tar.gz" | sha256sum -c
- - tar xf /tmp/hugo.tar.gz hugo -C /tmp/ && cp /tmp/hugo /usr/bin
- - hugo --baseURL ${BASEURL}
- - curl "https://api.keycdn.com/zones/purge/${KEYCDN_ZONE_ID}.json" -u "${KEYCDN_API_KEY}:"
- artifacts:
- paths:
- - public
- only:
- - master
-```
-
-Using this integration method, you will have to specify the Zone ID and your [KeyCDN API](https://www.keycdn.com/api) key as secret variables. To do this, navigate to the top-left menu bar in GitLab and select Projects. Then, select your project and click on the Settings page. Finally, select Pipelines from the sub-menu and scroll down to the Secret Variable section.
-
-The Secret Variable for your Zone ID should look similar to:
-
-
-
-While the Secret Variable for your API Key will look similar to:
-
-
-
-While not strictly required, providing your Zone ID and API key is recommended for purging your zone. Without them, the CDN may continue serving outdated versions of your assets for an extended period.
-
-## Push your changes to GitLab
-
-Now it's time to push the newly created repository to GitLab:
-
-```sh
-git remote add origin git@gitlab.com:youruser/ci-example.git
-git push -u origin master
-```
-
-You can watch the progress and CI job output in your GitLab project under “Pipelines”.
-
-After verifying your CI job ran without issues, first check that your GitLab page shows up under `https://youruser.gitlab.io/reponame/` (it might look broken depending on your browser settings as all links point to your KeyCDN zone---don't worry about that) and then by heading to whatever Zone alias / Zone URL you defined.
-
-To learn more about Hugo hosting options with KeyCDN, check out the complete [Hugo hosting with KeyCDN integration guide](https://www.keycdn.com/support/hugo-hosting/).
aliases: [/hosting-and-deployment/hosting-on-netlify/]
---
+Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using Azure DevOps, Bitbucket, or GitLab for version control.
+
## Prerequisites
Please complete the following tasks before continuing:
-1. [Create a Netlify account]
-1. [Install Git]
-1. [Create a Hugo site] and test it locally with `hugo server`
-1. Commit the changes to your local repository
-1. Push the local repository to your [GitHub], [GitLab], or [Bitbucket] account
-
-[Bitbucket]: https://bitbucket.org/product
-[Create a Hugo site]: /getting-started/quick-start/
-[Create a Netlify account]: https://app.netlify.com/signup
-[GitHub]: https://github.com
-[GitLab]: https://about.gitlab.com/
-[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+1. [Create](https://app.netlify.com/signup) a Netlify account
+1. [Log in](https://app.netlify.com/login) to your Netlify account
+1. [Create](https://github.com/signup) a GitHub account
+1. [Log in](https://github.com/login) to your GitHub account
+1. [Create](https://github.com/new) a GitHub repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
+1. Create a Hugo site within your local Git repository and test it with the `hugo server` command
+1. Commit the changes to your local Git repository and push to your GitHub repository.
## Procedure
-This procedure will enable continuous deployment from a GitHub repository. The procedure is essentially the same if you are using GitLab or Bitbucket.
-
-### Step 1
-
-Log in to your Netlify account, navigate to the Sites page, press the **Add new site** button, and choose "Import an existing project" from the dropdown menu.
-
-### Step 2
+Step 1
+: Log in to your Netlify account, navigate to the Sites page, press the **Add new site** button, and choose "Import an existing project" from the dropdown menu.
-Select your deployment method.
+Step 2
+: Select your deployment method.
-### Step 3
-
-Authorize Netlify to connect with your GitHub account by pressing the **Authorize Netlify** button.
-
-
-
-### Step 4
-
-Press the **Configure Netlify on GitHub** button.
-
-
+Step 3
+: Authorize Netlify to connect with your GitHub account by pressing the **Authorize Netlify** button.
-### Step 5
+ 
-Install the Netlify app by selecting your GitHub account.
+Step 4
+: Press the **Configure Netlify on GitHub** button.
-
+ 
-### Step 6
+Step 5
+: Install the Netlify app by selecting your GitHub account.
-Press the **Install** button.
+ 
-
+Step 6
+: Press the **Install** button.
-### Step 7
+ 
-Click on the site's repository from the list.
+Step 7
+: Click on the site's repository from the list.
-
+ 
-### Step 8
+Step 8
+: Set the site name and branch from which to deploy.
-Set the site name and branch from which to deploy.
+ 
-
+Step 9
+: Define the build settings, press the **Add environment variables** button, then press the **New variable** button.
-### Step 9
+ 
-Define the build settings, press the **Add environment variables** button, then press the **New variable** button.
+Step 10
+: Create a new environment variable named `HUGO_VERSION` and set the value to the [latest version](https://github.com/gohugoio/hugo/releases/latest).
-
+ 
-### Step 10
+Step 11
+: Press the "Deploy my new site" button at the bottom of the page.
-Create a new environment variable named `HUGO_VERSION` and set the value to the [latest version].
+ 
-[latest version]: https://github.com/gohugoio/hugo/releases/latest
+Step 12
+: At the bottom of the screen, wait for the deploy to complete, then click on the deploy log entry.
-
+ 
-### Step 11
+Step 13
+: Press the **Open production deploy** button to view the live site.
-Press the "Deploy my new site" button at the bottom of the page.
-
-
-
-### Step 12
-
-At the bottom of the screen, wait for the deploy to complete, then click on the deploy log entry.
-
-
-
-### Step 13
-
-Press the **Open production deploy** button to view the live site.
-
-
+ 
## Configuration file
In the procedure above we configured our site using the Netlify user interface. Most site owners find it easier to use a configuration file checked into source control.
-Create a new file named netlify.toml in the root of your project directory. In its simplest form, the configuration file might look like this:
+Create a new file named `netlify.toml` in the root of your project directory. In its simplest form, the configuration file might look like this:
```toml {file="netlify.toml"}
[build.environment]
-GO_VERSION = "1.24.2"
-HUGO_VERSION = "0.147.9"
-NODE_VERSION = "22"
-TZ = "America/Los_Angeles"
+GO_VERSION = "1.24.5"
+HUGO_VERSION = "0.148.2"
+NODE_VERSION = "22.18.0"
+TZ = "Europe/Oslo"
[build]
publish = "public"
-command = "git config core.quotepath false && hugo --gc --minify"
+command = """\
+ git config core.quotepath false && \
+ hugo --gc --minify --baseURL "${URL}"
+ """
```
If your site requires Dart Sass to transpile Sass to CSS, the configuration file should look something like this:
```toml {file="netlify.toml"}
[build.environment]
-DART_SASS_VERSION = "1.89.2"
-GO_VERSION = "1.24.2"
-HUGO_VERSION = "0.147.9"
-NODE_VERSION = "22"
-TZ = "America/Los_Angeles"
+DART_SASS_VERSION = "1.90.0"
+GO_VERSION = "1.24.5"
+HUGO_VERSION = "0.148.2"
+NODE_VERSION = "22.18.0"
+TZ = "Europe/Oslo"
[build]
publish = "public"
command = """\
- curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
- tar -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
- rm dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
- export PATH=/opt/build/repo/dart-sass:$PATH && \
+ curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" && \
+ tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" && \
+ rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" && \
+ export PATH="${HOME}/.local/dart-sass:${PATH}" && \
git config core.quotepath false && \
- hugo --gc --minify \
+ hugo --gc --minify --baseURL "${URL}"
"""
```
+++ /dev/null
----
-title: Host on Render
-description: Host your site on Render.
-categories: []
-keywords: []
-aliases: [/hosting-and-deployment/hosting-on-render/]
----
-
-## Introduction
-
-[Render](https://render.com) is a fully-managed cloud platform where you can host static sites, backend APIs, databases, cron jobs, and all your other apps in one place.
-
-Static sites are **completely free** on Render and include the following:
-
-- Continuous, automatic builds & deploys from [GitHub](https://render.com/docs/github) and [GitLab](https://render.com/docs/gitlab).
-- Automatic SSL certificates through [Let's Encrypt](https://letsencrypt.org).
-- Instant cache invalidation with a lightning fast, global CDN.
-- Unlimited collaborators.
-- Unlimited [custom domains](https://render.com/docs/custom-domains).
-- Automatic [Brotli compression](https://en.wikipedia.org/wiki/Brotli) for faster sites.
-- Native HTTP/2 support.
-- [Pull Request Previews](https://render.com/docs/pull-request-previews).
-- Automatic HTTP → HTTPS redirects.
-- Custom URL redirects and rewrites.
-
-## Assumptions
-
-- You have an account with GitHub or GitLab.
-- You have completed the [Quick Start] or have a Hugo website you are ready to deploy and share with the world.
-- You have a Render account. You can sign up at https://render.com/register.
-
-## Deployment
-
-You can set up a Hugo site on Render in two quick steps:
-
-1. Create a new **Static Site** on Render, and give Render permission to access your GitHub/GitLab repo.
-1. Use the following values during creation:
-
-Field | Value
-------------------- | -------------------
-**Build Command** | `hugo --gc --minify` (or your own build command)
-**Publish Directory** | `public` (or your own output directory)
-
-That's it! Your site will be live on your Render URL (which looks like `yoursite.onrender.com`) as soon as the build is done.
-
-## Continuous deploys
-
-Now that Render is connected to your repo, it will **automatically build and publish your site** any time you push to your GitHub/GitLab.
-
-You can choose to disable auto deploys under the **Settings** section for your site and deploy it manually from the Render dashboard.
-
-## CDN and cache invalidation
-
-Render hosts your site on a global, lightning fast CDN which ensures the fastest possible download times for all your users across the globe.
-
-Every deploy automatically and instantly invalidates the CDN cache, so your users can always access the latest content on your site.
-
-## Custom domains
-
-Add your own domains to your site easily using Render's [custom domains](https://render.com/docs/custom-domains) guide.
-
-## Pull Request previews
-
-With Pull Request (PR) previews, you can visualize changes introduced in a pull request instead of simply relying on code reviews.
-
-Once enabled, every PR for your site will automatically generate a new static site based on the code in the PR. It will have its own URL, and it will be deleted automatically when the PR is closed.
-
-Read more about [Pull Request Previews](https://render.com/docs/pull-request-previews) on Render.
-
-## Hugo themes
-
-Render automatically downloads all Git submodules defined in your Git repo on every build. This way Hugo themes added as submodules work as expected.
-
-## Support
-
-Chat with Render developers at https://render.com/chat or email `support@render.com` if you need help.
-
-[Quick Start]: /getting-started/quick-start/
--- /dev/null
+---
+title: Host on Render
+description: Host your site on Render.
+categories: []
+keywords: []
+aliases: [/hosting-and-deployment/hosting-on-render/]
+---
+
+Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using Bitbucket or GitLab for version control.
+
+## Prerequisites
+
+Please complete the following tasks before continuing:
+
+1. [Create](https://dashboard.render.com/register) a Render account
+1. [Log in](https://dashboard.render.com/login) to your Render account
+1. [Create](https://github.com/signup) a GitHub account
+1. [Log in](https://github.com/login) to your GitHub account
+1. [Create](https://github.com/new) a GitHub repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
+1. Create a Hugo site within your local Git repository and test it with the `hugo server` command
+
+## Procedure
+
+Step 1
+: Create a [Render Blueprint][] in the root of your project.
+
+ ``` {file="render.yaml" copy=true}
+ services:
+ - type: web
+ name: hosting-render
+ repo: https://github.com/jmooring/hosting-render
+ runtime: static
+ buildCommand: chmod a+x build.sh && ./build.sh
+ staticPublishPath: public
+ envVars:
+ - key: DART_SASS_VERSION
+ value: 1.90.0
+ - key: GO_VERSION
+ value: 1.24.5
+ - key: HUGO_VERSION
+ value: 0.148.2
+ - key: NODE_VERSION
+ value: 22.18.0
+ - key: TZ
+ value: Europe/Oslo
+ ```
+
+Step 2
+: Create a `build.sh` file in the root of your project.
+
+ ```sh {file="build.sh" copy=true}
+ #!/usr/bin/env bash
+
+ #------------------------------------------------------------------------------
+ # @file
+ # Builds a Hugo site hosted on a Render.
+ #
+ # Render automatically installs Node.js dependencies.
+ #------------------------------------------------------------------------------
+
+ main() {
+
+ # Create directory for user-specific executable files
+ echo "Creating directory for user-specific executable files..."
+ mkdir -p "${HOME}/.local"
+
+ # Install Dart Sass
+ echo "Installing Dart Sass ${DART_SASS_VERSION}..."
+ curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ export PATH="${HOME}/.local/dart-sass:${PATH}"
+
+ # Install Go
+ echo "Installing Go ${GO_VERSION}..."
+ curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz"
+ tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz"
+ rm "go${GO_VERSION}.linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/go/bin:${PATH}"
+
+ # Install Hugo
+ echo "Installing Hugo ${HUGO_VERSION}..."
+ curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ mkdir -p "${HOME}/.local/hugo"
+ tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/hugo:${PATH}"
+
+ # Verify installations
+ echo "Verifying installations..."
+ echo Dart Sass: "$(sass --version)"
+ echo Go: "$(go version)"
+ echo Hugo: "$(hugo version)"
+ echo Node.js: "$(node --version)"
+
+ # Configure Git
+ echo "Configuring Git..."
+ git config core.quotepath false
+ if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
+ git fetch --unshallow
+ fi
+
+ # Build the site
+ echo "Building the site..."
+ hugo --gc --minify --baseURL "${RENDER_EXTERNAL_URL}"
+
+ }
+
+ set -euo pipefail
+ main "$@"
+ ```
+
+Step 3
+: Commit the changes to your local Git repository and push to your GitHub repository.
+
+Step 4
+: On the Render [dashboard][], press the **Add new** button and select "Blueprint" from the drop-down menu.
+
+ 
+
+Step 5
+: Press the **GitHub** button to connect to your GitHub account.
+
+ 
+
+Step 6
+: Press the **Authorize Render** button to allow the Render application to access your GitHub account.
+
+ 
+
+Step 7
+: Select the GitHub account where you want to install the Render application.
+
+ 
+
+Step 8
+: Authorize the Render application to access all repositories or only select repositories, then press the **Install** button.
+
+
+
+Step 9
+: On the "Create a new Blueprint Instance in My Workspacee" page, press the **Connect** button to the right of the name of your GitHub repository.
+
+ 
+
+Step 10
+: Enter a unique name for your Blueprint, then press the **Deploy Blueprint** button at the bottom of the page.
+
+ 
+
+Step 11
+: Wait for the site to build and deploy, then click on the "Resources" link on the left side of the page.
+
+ 
+
+Step 12
+: Click on the link to the static site resource.
+
+ 
+
+Step 13
+: Click on the link to your published site.
+
+ 
+
+In the future, whenever you push a change from your local Git repository, Render will rebuild and deploy your site.
+
+[Render Blueprint]: https://render.com/docs/blueprint-spec
+[dashboard]: https://dashboard.render.com/
--- /dev/null
+---
+title: Host on Vercel
+description: Host your site on Vercel.
+categories: []
+keywords: []
+---
+
+Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using Bitbucket or GitLab for version control.
+
+## Prerequisites
+
+Please complete the following tasks before continuing:
+
+1. [Create](https://vercel.com/signup) a Vercel account
+1. [Log in](https://vercel.com/login) to your Vercel account
+1. [Create](https://github.com/signup) a GitHub account
+1. [Log in](https://github.com/login) to your GitHub account
+1. [Create](https://github.com/new) a GitHub repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
+1. Create a Hugo site within your local Git repository and test it with the `hugo server` command
+
+## Procedure
+
+Step 1
+: Create a `vercel.json` file in the root of your project.
+
+ ```json {file="vercel.json" copy=true}
+ {
+ "$schema": "https://openapi.vercel.sh/vercel.json",
+ "buildCommand": "chmod a+x build.sh && ./build.sh",
+ "outputDirectory": "public"
+ }
+ ```
+
+Step 2
+: Create a `build.sh` file in the root of your project.
+
+ ```sh {file="build.sh" copy=true}
+ #!/usr/bin/env bash
+
+ #------------------------------------------------------------------------------
+ # @file
+ # Builds a Hugo site hosted on Vercel.
+ #
+ # The Vercel build image automatically installs Node.js dependencies.
+ #------------------------------------------------------------------------------
+
+ main() {
+
+ DART_SASS_VERSION=1.90.0
+ GO_VERSION=1.24.5
+ HUGO_VERSION=0.148.2
+ NODE_VERSION=22.18.0
+
+ export TZ=Europe/Oslo
+
+ # Install Dart Sass
+ echo "Installing Dart Sass ${DART_SASS_VERSION}..."
+ curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ export PATH="${HOME}/.local/dart-sass:${PATH}"
+
+ # Install Go
+ echo "Installing Go ${GO_VERSION}..."
+ curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz"
+ tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz"
+ rm "go${GO_VERSION}.linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/go/bin:${PATH}"
+
+ # Install Hugo
+ echo "Installing Hugo ${HUGO_VERSION}..."
+ curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ mkdir "${HOME}/.local/hugo"
+ tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/hugo:${PATH}"
+
+ # Install Node.js
+ echo "Installing Node.js ${NODE_VERSION}..."
+ curl -sLJO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz"
+ tar -C "${HOME}/.local" -xf "node-v${NODE_VERSION}-linux-x64.tar.xz"
+ rm "node-v${NODE_VERSION}-linux-x64.tar.xz"
+ export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}"
+
+ # Verify installations
+ echo "Verifying installations..."
+ echo Dart Sass: "$(sass --version)"
+ echo Go: "$(go version)"
+ echo Hugo: "$(hugo version)"
+ echo Node.js: "$(node --version)"
+
+ # Configure Git
+ echo "Configuring Git..."
+ git config core.quotepath false
+ if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
+ git fetch --unshallow
+ fi
+
+ # Build the site
+ echo "Building the site"
+ hugo --gc --minify --baseURL "https://${VERCEL_PROJECT_PRODUCTION_URL}"
+
+ }
+
+ set -euo pipefail
+ main "$@"
+ ```
+
+Step 3
+: Commit the changes to your local Git repository and push to your GitHub repository.
+
+Step 4
+: In the upper right corner of the Vercel dashboard, press the **Add New** button and select "Project" from the drop down menu.
+
+ 
+
+Step 5
+: Press the "Continue with GitHub" button.
+
+ 
+
+Step 6
+: Press the **Authorize Vercel** button to allow the Vercel application to access your GitHub account.
+
+ 
+
+Step 7
+: Press the **Install** button to install the Vercel application.
+
+ 
+
+Step 8
+: Select the GitHub account where you want to install the Vercel application.
+
+ 
+
+Step 9
+: Authorize the Vercel application to access all repositories or only select repositories, then press the **Install** button.
+
+ 
+
+ Your browser will be redirected to the Cloudflare dashboard.
+
+Step 10
+: Press the **Import** button to the right of the name of your GitHub repository.
+
+ 
+
+Step 11
+: On the "New Project" page, leave the settings at their default values and press the **Deploy** button.
+
+ 
+
+Step 12
+: When the deployment completes, press the **Continue to Dashboard" button at the bottom of the page.
+
+ 
+
+Step 13
+: On the "Production Deployment" page, click on the link to your published site.
+
+ 
+
+In the future, whenever you push a change from your local Git repository, Vercel will rebuild and deploy your site.
## Caching
-Hugo Pipes invocations are cached based on the entire *pipe chain*.
+Hugo Pipes invocations are cached based on the entire _pipe chain_.
An example of a pipe chain is:
## Comparison
-||Prebuilt binaries|Repository packages|Build from source
+ |Prebuilt binaries|Repository packages|Build from source
:--|:--:|:--:|:--:
Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
Easy to upgrade?|:heavy_check_mark:|varies|:heavy_check_mark:
## Comparison
-||Prebuilt binaries|Package managers|Repository packages|Build from source
+ |Prebuilt binaries|Package managers|Repository packages|Build from source
:--|:--:|:--:|:--:|:--:
Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark:
## Comparison
-||Prebuilt binaries|Package managers|Build from source
+ |Prebuilt binaries|Package managers|Build from source
:--|:--:|:--:|:--:
-Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|
+Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^1]|:heavy_check_mark:
Automatic updates?|:x:|:x: [^2]|:x:
## Comparison
-||Prebuilt binaries|Package managers|Build from source
+ |Prebuilt binaries|Package managers|Build from source
:--|:--:|:--:|:--:
-Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|
+Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^2]|:heavy_check_mark:
Automatic updates?|:x:|:x: [^1]|:x:
---
title: AllTranslations
-description: Returns all translations of the given page, including the current language.
+description: Returns all translations of the given page, including the current language, sorted by language weight.
categories: []
keywords: []
params:
## In a taxonomy template
-Use these methods on the `Data` object within a taxonomy template.
+Use these methods on the `Data` object within a _taxonomy_ template.
Singular
: (`string`) Returns the singular name of the taxonomy.
## In a term template
-Use these methods on the `Data` object within a term template.
+Use these methods on the `Data` object within a _term_ template.
Singular
: (`string`) Returns the singular name of the taxonomy.
[`time.Format`]: /functions/time/format/
[details]: /configuration/front-matter/#dates
-[details]: /configuration/front-matter/#dates
[time methods]: /methods/time/
[time.Time]: https://pkg.go.dev/time#Time
keywords: []
params:
functions_and_methods:
- returnType: source.GitInfo
+ returnType: '*gitmap.GitInfo'
signatures: [PAGE.GitInfo]
---
## Prerequisites
-Install [Git], create a repository, and commit your project files.
+Install Git, create a repository, and commit your project files.
You must also allow Hugo to access your repository. In your site configuration:
{{ end }}
```
+### Ancestors
+
+(`gitmap.GitInfos`) A slice of file-filtered ancestor commits, if any, ordered from most recent to least recent.
+
+For example, to list the last 5 commits:
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ range .Ancestors | first 5 }}
+ {{ .CommitDate.Format "2006-01-02" }}: {{ .Subject }}
+ {{ end }}
+{{ end }}
+```
+
+To reverse the order:
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ range .Ancestors.Reverse | first 5 }}
+ {{ .CommitDate.Format "2006-01-02" }}: {{ .Subject }}
+ {{ end }}
+{{ end }}
+```
+
+### Parent
+
+(`*gitmap.GitInfo`) The first file-filtered ancestor commit, if any.
+
## Last modified date
By default, when `enableGitInfo` is `true`, the `Lastmod` method on a `Page` object returns the Git AuthorDate of the last commit that included the file.
## Hosting considerations
-When hosting your site in a [CI/CD](g) environment, the step that clones your project repository must perform a deep clone. If the clone is shallow, the Git information for a given file may not be accurate---it may reflect the most recent repository commit, not the commit that last modified the file.
+In a [CI/CD](g) environment, the step that clones your project repository must perform a deep clone. If the clone is shallow, the Git information for a given file may be inaccurate. It might incorrectly reflect the most recent repository commit, rather than the commit that actually modified the file.
+
+While some providers perform a deep clone by default, others require you to configure the depth yourself.
-Some providers perform deep clones by default, others allow you to configure the clone depth, and some only perform shallow clones.
+Hosting service|Default clone depth|Configurable
+:--|:--|:--
+AWS Amplify|Deep|N/A
+Cloudflare|Shallow|Yes [^1]
+DigitalOcean App Platform|Deep|N/A
+GitHub Pages|Shallow|Yes [^2]
+GitLab Pages|Shallow|Yes [^3]
+Netlify|Deep|N/A
+Render|Shallow|Yes [^1]
+Vercel|Shallow|Yes [^1]
-Hosting service | Default clone depth | Configurable
-:-- | :-- | :--
-AWS Amplify | Deep | N/A
-Cloudflare Pages | Shallow | Yes [^1]
-DigitalOcean App Platform | Deep | N/A
-GitHub Pages | Shallow | Yes [^2]
-GitLab Pages | Shallow | Yes [^3]
-Netlify | Deep | N/A
-Render | Shallow | No
-Vercel | Shallow | No
+[^1]: To perform a deep clone when hosting on Cloudflare, Render, or Vercel, include this code in the build script after the repository has been cloned:
-[^1]: To configure a Cloudflare Pages site for deep cloning, run `git fetch --unshallow` before building the site.
+ ```text
+ if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
+ git fetch --unshallow
+ fi
+ ```
-[^2]: You can configure the GitHub Action to do a deep clone by specifying `fetch-depth: 0` in the applicable "checkout" step of your workflow file, as shown in the Hugo documentation's [example workflow file](/host-and-deploy/host-on-github-pages/#procedure).
+[^2]: To perform a deep clone when hosting on GitHub Pages, set `fetch-depth: 0` in the `checkout` step of the GitHub Action. See [example](/host-and-deploy/host-on-github-pages/#step-7).
-[^3]: You can configure the GitLab Runner's clone depth [as explained in the GitLab documentation](https://docs.gitlab.com/ee/ci/large_repositories/#shallow-cloning); see also the Hugo documentation's [example workflow file](/host-and-deploy/host-on-gitlab-pages/#configure-gitlab-cicd).
+[^3]: To perform a deep clone when hosting on GitLab Pages, set the `GIT_DEPTH` environment variable to `0` in the workflow file. See [example](/host-and-deploy/host-on-gitlab-pages/#configure-gitlab-cicd).
[details]: /configuration/front-matter/#dates
[gitmailmap]: https://git-scm.com/docs/gitmailmap
signatures: [PAGE.Page]
---
-This is a convenience method, useful within partial templates that are called from both [shortcodes](g) and page templates.
+This is a convenience method, useful within _partial_ templates that are called from both _shortcode_ and other template types.
```go-html-template {file="layouts/_shortcodes/foo.html"}
{{ partial "my-partial.html" . }}
```
-When the shortcode calls the partial, it passes the current [context](g) (the dot). The context includes identifiers such as `Page`, `Params`, `Inner`, and `Name`.
+When the _shortcode_ template calls the _partial_ template, it passes the current [context](g) (the dot). The context includes identifiers such as `Page`, `Params`, `Inner`, and `Name`.
```go-html-template {file="layouts/page.html"}
{{ partial "my-partial.html" . }}
```
-When the page template calls the partial, it also passes the current context (the dot). But in this case, the dot _is_ the `Page` object.
+When the _page_ template calls the _partial_ template, it also passes the current context (the dot). But in this case, the dot _is_ the `Page` object.
```go-html-template {file="layouts/_partials/my-partial.html"}
The page title is: {{ .Page.Title }}
```
-To handle both scenarios, the partial template must be able to access the `Page` object with `Page.Page`.
+To handle both scenarios, the _partial_ template must be able to access the `Page` object with `Page.Page`.
> [!note]
> And yes, that means you can do `.Page.Page.Page.Page.Title` too.
>
> The `Paginate` method is more flexible.
-You can invoke pagination on the [home template], [section templates], [taxonomy templates], and [term templates].
+You can invoke pagination in [home], [section], [taxonomy], and [term] templates.
```go-html-template {file="layouts/section.html"}
{{ $pages := where .Site.RegularPages "Section" "articles" }}
> [!note]
> Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect.
-[home template]: /templates/types/#home
-[section templates]: /templates/types/#section
+[home]: /templates/types/#home
+[section]: /templates/types/#section
[site configuration]: /configuration/pagination/
-[taxonomy templates]: /templates/types/#taxonomy
-[term templates]: /templates/types/#term
+[taxonomy]: /templates/types/#taxonomy
+[term]: /templates/types/#term
The number of elements on each pager is determined by your [site configuration]. The default is `10`.
-You can invoke pagination on the [home template], [section templates], [taxonomy templates], and [term templates]. Each of these receives a collection of regular pages in [context](g). When you invoke the `Paginator` method, it paginates the page collection received in context.
+You can invoke pagination in [home], [section], [taxonomy], and [term] templates. Each of these receives a collection of regular pages in [context](g). When you invoke the `Paginator` method, it paginates the page collection received in context.
```go-html-template {file="layouts/section.html"}
{{ range .Paginator.Pages }}
> [!note]
> Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect.
-[home template]: /templates/types/#home
-[section templates]: /templates/types/#section
+[home]: /templates/types/#home
+[section]: /templates/types/#section
[site configuration]: /configuration/pagination/
-[taxonomy templates]: /templates/types/#taxonomy
-[term templates]: /templates/types/#term
+[taxonomy]: /templates/types/#taxonomy
+[term]: /templates/types/#term
[`Paginate`]: /methods/page/paginate/
:--|:--|:--
[`Site.GetPage`]|[`urls.Ref`]|[`ref`]
[`Page.GetPage`]|[`urls.RelRef`]|[`relref`]
-[`Page.Ref`]|||
-[`Page.RelRef`]|||
-[`Shortcode.Ref`]|||
-[`Shortcode.RelRef`]|||
+[`Page.Ref`]| |
+[`Page.RelRef`]| |
+[`Shortcode.Ref`]| |
+[`Shortcode.RelRef`]| |
> [!note]
> Specify the logical path when using any of these methods, functions, or shortcodes. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree.
Although similar to the [`partial`] function, there are key differences.
-`Render` method|`partial` function|
+`Render` method|`partial` function
:--|:--
-The `Page` object is automatically passed to the given template. You cannot pass additional context.| You must specify the context, allowing you to pass a combination of objects, slices, maps, and scalars.
+The `Page` object is automatically passed to the given template. You cannot pass additional context.|You must specify the context, allowing you to pass a combination of objects, slices, maps, and scalars.
The path to the template is determined by the [content type](g).|You must specify the path to the template, relative to the `layouts/_partials` directory.
Consider this layout structure:
signatures: [PAGE.RenderShortcodes]
---
-Use this method in shortcode templates to compose a page from multiple content files, while preserving a global context for footnotes and the table of contents.
+Use this method in _shortcode_ templates to compose a page from multiple content files, while preserving a global context for footnotes and the table of contents.
For example:
## Determinate values
-The `Store` method is often used to set scratch pad values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.
+The `Store` method is often used to set scratch pad values within a _shortcode_ template, a _partial_ template called by a _shortcode_ template, or by a _render hook_ template. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.
If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop](g) variable:
---
title: Translations
-description: Returns all translations of the given page, excluding the current language.
+description: Returns all translations of the given page, excluding the current language, sorted by language weight.
categories: []
keywords: []
params:
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-The `Content` method on a `Resource` object returns `template.HTML` when the resource type is `page`, otherwise it returns a `string`.
+The `Content` method on a `Resource` object returns `template.HTML` when the [resource type] is `page`, otherwise it returns a `string`.
[resource type]: /methods/resource/resourcetype/
The `Data` method on a resource returned by the [`resources.GetRemote`] function returns information from the HTTP response.
-[`resources.GetRemote`]: /functions/resources/getremote/
-
## Example
```go-html-template
{{ .Name }} → images/Sunrise in Bryce Canyon.jpg
{{ end }}
```
+
## Remote resource
With a [remote resource](g), the `Name` method returns a hashed file name.
To support both positional and named arguments when calling a shortcode, use the `IsNamedParams` method to determine how the shortcode was called.
-With this shortcode template:
+With this _shortcode_ template:
```go-html-template {file="layouts/_shortcodes/myshortcode.html"}
{{ if .IsNamedParams }}
```
> [!note]
-> In the shortcode template above, the [`with`] statement is used to create conditional blocks. Remember that the `with` statement binds context (the dot) to its expression. Inside of a `with` block, preface shortcode method calls with a `$` to access the top-level context passed into the template.
+> In the _shortcode_ template above, the [`with`] statement is used to create conditional blocks. Remember that the `with` statement binds context (the dot) to its expression. Inside of a `with` block, preface shortcode method calls with a `$` to access the top-level context passed into the template.
[`with`]: /functions/go-template/with/
└── _index.md
```
-This home template:
+This _home_ template:
-```go-html-template
+```go-html-template {file="layouts/home.html"}
{{ with .Site.GetPage "/works/paintings" }}
<ul>
{{ range .Pages }}
To get a regular page instead of a section page:
-```go-html-template
+```go-html-template {file="layouts/home.html"}
{{ with .Site.GetPage "/works/paintings/starry-night" }}
{{ .Title }} → Starry Night
{{ .Params.artist }} → Vincent van Gogh
└── _index.md
```
-In the home template, use the `GetPage` method on a `Site` object to render all the images in the headless [page bundle](g):
+In the _home_ template, use the `GetPage` method on a `Site` object to render all the images in the headless [page bundle](g):
-```go-html-template
+```go-html-template {file="layouts/home.html"}
{{ with .Site.GetPage "/headless" }}
{{ range .Resources.ByType "image" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
When creating a theme, instead of hardcoding section names when listing the most relevant pages on the front page, instruct site authors to set `mainSections` in their site configuration.
-Then your home template can do something like this:
+Then your _home_ template can do something like this:
-```go-html-template
+```go-html-template {file="layouts/home.html"}
{{ range where .Site.RegularPages "Section" "in" .Site.MainSections }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
</nav>
```
-You will typically render a menu using a partial template. As the active menu entry will be different on each page, use the [`partial`] function to call the template. Do not use the [`partialCached`] function.
+You will typically render a menu using a _partial_ template. As the active menu entry will be different on each page, use the [`partial`] function to call the template. Do not use the [`partialCached`] function.
The example above is simplistic. Please see the [menu templates] section for more information.
## Determinate values
-The `Store` method is often used to set scratch pad values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.
+The `Store` method is often used to set scratch pad values within a _shortcode_ template, a _partial_ template called by a _shortcode_ template, or by a _render hook_ template. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.
If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop](g) variable:
Conceptually, the `Taxonomies` method on a `Site` object returns a data structure such as:
+<!-- markdownlint-disable MD007 MD032 -->
{{< code-toggle file=hugo >}}
taxonomy a:
- term 1:
- page 1
- page 2
{{< /code-toggle >}}
+<!-- markdownlint-enable MD007 MD032 -->
For example, on a book review site you might create two taxonomies; one for genres and another for authors.
Conceptually, the taxonomies data structure looks like:
+<!-- markdownlint-disable MD007 MD032 -->
{{< code-toggle file=hugo >}}
genres:
- suspense:
- jausten:
- Pride and Prejudice
{{< /code-toggle >}}
+<!-- markdownlint-enable MD007 MD032 -->
To list the "suspense" books:
{{ end }}
</ul>
```
+
This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms.
```go-html-template {file="layouts/_partials/all-taxonomies.html"}
```go-html-template
{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
-{{ $d := time.ParseDuration "1h"}}
+{{ $d := time.ParseDuration "1h" }}
{{ ($t.Round $d).Format "2006-01-02T15:04:05-00:00" }} → 2023-01-28T00:00:00-00:00
```
```go-html-template
{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
-{{ $d := time.ParseDuration "1h"}}
+{{ $d := time.ParseDuration "1h" }}
{{ ($t.Truncate $d).Format "2006-01-02T15:04:05-00:00" }} → 2023-01-27T23:00:00-00:00
```
reference: https://go.dev/ref/spec#String_literals
---
-A _raw string literal_ is a character sequences between backticks, as in \`bar\`. Within the backticks, any character may appear except a backtick. Backslashes have no special meaning and the string may contain newlines. Carriage return characters (`\r`) inside raw string literals are discarded from the raw string value.
+A _raw string literal_ is a character sequence between backticks, as in \`bar\`. Within the backticks, any character may appear except a backtick. Backslashes have no special meaning and the string may contain newlines. Carriage return characters (`\r`) inside raw string literals are discarded from the raw string value.
- Use the [`transform.Highlight`] function within your templates
- Use the [`highlight`] shortcode with any [content format](g)
-- Use fenced code blocks with the Markdown content format
+- Use [fenced code blocks] with the Markdown content format
Regardless of method, use any of the syntax highlighting styles below.
---
title: Render hooks
-description: Create render hooks to override the rendering of Markdown to HTML.
+description: Create render hook templates to override the rendering of Markdown to HTML.
categories: []
keywords: []
weight: 10
---
title: Blockquote render hooks
linkTitle: Blockquotes
-description: Create a blockquote render hook to override the rendering of Markdown blockquotes to HTML.
+description: Create blockquote render hook templates to override the rendering of Markdown blockquotes to HTML.
categories: []
keywords: []
---
## Context
-Blockquote render hook templates receive the following [context](g):
+Blockquote _render hook_ templates receive the following [context](g):
AlertType
: (`string`) Applicable when [`Type`](#type) is `alert`, this is the alert type converted to lowercase. See the [alerts](#alerts) section below.
---
title: Code block render hooks
linkTitle: Code blocks
-description: Create a code block render hook to override the rendering of Markdown code blocks to HTML.
+description: Create code block render hook templates to override the rendering of Markdown code blocks to HTML.
categories: []
keywords: []
---
## Context
-Code block render hook templates receive the following [context](g):
+Code block _render hook_ templates receive the following [context](g):
Attributes
: (`map`) The generic attributes from the info string.
: (`string`) The content between the leading and trailing code fences, excluding the info string.
Options
-: (`map`) The highlighting options from the info string.
+: (`map`) The highlighting options from the info string. This map is empty if [`Type`](#type) is an empty string or a code language that is not supported by the Chroma syntax highlighter. However, in this case, the highlighting options are available in the [`Attributes`](#attributes) map.
Ordinal
: (`int`) The zero-based ordinal of the code block on the page.
---
title: Heading render hooks
linkTitle: Headings
-description: Create a heading render hook to override the rendering of Markdown headings to HTML.
+description: Create heading render hook templates to override the rendering of Markdown headings to HTML.
categories: []
keywords: []
---
## Context
-Heading render hook templates receive the following [context](g):
+Heading _render hook_ templates receive the following [context](g):
Anchor
: (`string`) The `id` attribute of the heading element.
---
title: Image render hooks
linkTitle: Images
-description: Create an image render to hook override the rendering of Markdown images to HTML.
+description: Create image render hook templates to override the rendering of Markdown images to HTML.
categories: []
keywords: []
---
## Context
-Image render hook templates receive the following context:
+Image _render hook_ templates receive the following context:
Attributes
: (`map`) The [Markdown attributes], available if you configure your site as follows:
wrapStandAloneImageWithinParagraph = false
{{< /code-toggle >}}
-## Default
+## Embedded
{{< new-in 0.123.0 />}}
-Hugo includes an [embedded image render hook] to resolve Markdown image destinations. Disabled by default, you can enable it in your site configuration:
+Hugo includes an [embedded image render hook] to resolve Markdown image destinations. You can adjust its behavior in your site configuration. This is the default setting:
{{< code-toggle file=hugo >}}
[markup.goldmark.renderHooks.image]
-enableDefault = true
+useEmbedded = 'auto'
{{< /code-toggle >}}
-A custom render hook, even when provided by a theme or module, will override the embedded render hook regardless of the configuration setting above.
+When set to `auto` as shown above, Hugo automatically uses the embedded image render hook for multilingual single-host sites, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such sites. If custom image render hooks are defined by your project, modules, or themes, these will be used instead.
-> [!note]
-> The embedded image render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites.
+You can also configure Hugo to `always` use the embedded image render hook, use it only as a `fallback`, or `never` use it. See [details](/configuration/markup/#renderhooksimageuseembedded).
The embedded image render hook resolves internal Markdown destinations by looking for a matching [page resource](g), falling back to a matching [global resource](g). Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination.
## Context
-Link render hook templates receive the following context:
+Link _render hook_ templates receive the following context:
Destination
: (`string`) The link destination.
{{- /* chomp trailing newline */ -}}
```
-## Default
+## Embedded
{{< new-in 0.123.0 />}}
-Hugo includes an [embedded link render hook] to resolve Markdown link destinations. Disabled by default, you can enable it in your site configuration:
+Hugo includes an [embedded link render hook] to resolve Markdown link destinations. You can adjust its behavior in your site configuration. This is the default setting:
{{< code-toggle file=hugo >}}
[markup.goldmark.renderHooks.link]
-enableDefault = true
+useEmbedded = 'auto'
{{< /code-toggle >}}
-A custom render hook, even when provided by a theme or module, will override the embedded render hook regardless of the configuration setting above.
+When set to `auto` as shown above, Hugo automatically uses the embedded link render hook for multilingual single-host sites, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such sites. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
-> [!note]
-> The embedded link render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites.
+You can also configure Hugo to `always` use the embedded link render hook, use it only as a `fallback`, or `never` use it. See [details](/configuration/markup/#renderhookslinkuseembedded).
The embedded link render hook resolves internal Markdown destinations by looking for a matching page, falling back to a matching [page resource](g), then falling back to a matching [global resource](g). Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination.
---
title: Passthrough render hooks
linkTitle: Passthrough
-description: Create a passthrough render hook to override the rendering of text snippets captured by the Goldmark Passthrough extension.
+description: Create passthrough render hook templates to override the rendering of text snippets captured by the Goldmark Passthrough extension.
categories: []
keywords: []
---
## Context
-Passthrough render hook templates receive the following [context](g):
+Passthrough _render hook_ templates receive the following [context](g):
Attributes
: (`map`) The [Markdown attributes], available if you configure your site as follows:
---
title: Table render hooks
linkTitle: Tables
-description: Create a table render hook to override the rendering of Markdown tables to HTML.
+description: Create table render hook templates to override the rendering of Markdown tables to HTML.
categories: []
keywords: []
---
## Context
-Table render hook templates receive the following [context](g):
+Table _render hook_ templates receive the following [context](g):
Attributes
: (`map`) The [Markdown attributes], available if you configure your site as follows:
[QR code]: https://en.wikipedia.org/wiki/QR_code
[related documentation]: /functions/images/qr/
[source code]: {{% eturl qr %}}
-[vCard]: https://en.wikipedia.org/wiki/VCard
+[vCard]: <https://en.wikipedia.org/wiki/VCard>
> To override Hugo's embedded `ref` shortcode, copy the [source code] to a file with the same name in the `layouts/_shortcodes` directory.
> [!note]
-> When working with Markdown, this shortcode is obsolete. Instead, use a [link render hook] that resolves the link destination using the `GetPage` method on the `Page` object. You can either create your own, or simply enable the [embedded link render hook]. The embedded link render hook is automatically enabled for multilingual single-host projects.
+> When working with Markdown this shortcode is obsolete. Instead, to properly resolve Markdown link destinations, use the [embedded link render hook] or create your own.
+>
+> In its default configuration, Hugo automatically uses the embedded link render hook for multilingual single-host sites, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such sites. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
+>
+> You can also configure Hugo to `always` use the embedded link render hook, use it only as a `fallback`, or `never` use it. See [details](/configuration/markup/#renderhookslinkuseembedded).
## Usage
{{% include "_common/ref-and-relref-error-handling.md" %}}
-[content format]: /content-management/formats/
-[embedded link render hook]: /render-hooks/links/#default
-[link render hook]: /render-hooks/links/
+[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
+[embedded link render hook]: /render-hooks/links/#embedded
[Markdown notation]: /content-management/shortcodes/#notation
[source code]: {{% eturl relref %}}
> To override Hugo's embedded `relref` shortcode, copy the [source code] to a file with the same name in the `layouts/_shortcodes` directory.
> [!note]
-> When working with Markdown, this shortcode is obsolete. Instead, use a [link render hook] that resolves the link destination using the `GetPage` method on the `Page` object. You can either create your own, or simply enable the [embedded link render hook]. The embedded link render hook is automatically enabled for multilingual single-host projects.
+> When working with Markdown this shortcode is obsolete. Instead, to properly resolve Markdown link destinations, use the [embedded link render hook] or create your own.
+>
+> In its default configuration, Hugo automatically uses the embedded link render hook for multilingual single-host sites, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such sites. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
+>
+> You can also configure Hugo to `always` use the embedded link render hook, use it only as a `fallback`, or `never` use it. See [details](/configuration/markup/#renderhookslinkuseembedded).
## Usage
{{% include "_common/ref-and-relref-error-handling.md" %}}
-[content format]: /content-management/formats/
-[embedded link render hook]: /render-hooks/links/#default
-[link render hook]: /render-hooks/links/
+[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
+[embedded link render hook]: /render-hooks/links/#embedded
[Markdown notation]: /content-management/shortcodes/#notation
[source code]: {{% eturl relref %}}
1. Write the story about your site in this file.
1. Add a summary to the `bio.md` file in this directory.
1. Replace the `featured-template.png` with a screenshot of your site. You can rename it, but it must contain the word `featured`.
-1. Create a new pull request in https://github.com/gohugoio/hugoDocs/pulls
+1. Create a new pull request in <https://github.com/gohugoio/hugoDocs/pulls>
The content of this bundle explained:
-__We are Ampio.__ We design and manufacture a building automation system that provides control, comfort, safety and reliability. Visit [our page](http://ampio.com/) to learn more about our solution!
+We are Ampio. We design and manufacture a building automation system that provides control, comfort, safety and reliability. Visit [our page](http://ampio.com/) to learn more about our solution!
-__Ampio Knowledge Base__ is a service built and maintained with Hugo. It is a self-service support platform for our customers and certified installers. It also contains a complete portfolio of our modules---building blocks of the Ampio building automation system.
+Ampio Knowledge Base is a service built and maintained with Hugo. It is a self-service support platform for our customers and certified installers. It also contains a complete portfolio of our modules---building blocks of the Ampio building automation system.
The site is built by:
We started our journey with the following requirements:
- - Ease of contribution
- - Efficient search capabilities
- - The possibility of deployment to simple shared hosting
- - Proper support for multilingualism
+- Ease of contribution
+- Efficient search capabilities
+- The possibility of deployment to simple shared hosting
+- Proper support for multilingualism
## Dark ages of WordPress
We've just launched a shiny new website for [Hartwell Insurance](https://www.hartwell-insurance.com/). I'm really proud of it. It was tackled in a different way to most previous Tomango site builds, using some fancy new tools and some vintage web standards.
-It's a multi-page, single-page (!) website written in Hugo, a static site generator built with performance as a first-class feature. _I've outlined a load of benefits to Hugo & static sites [here](https://why-static.netlify.com/), in case you're interested._
+It's a multi-page, single-page (!) website written in Hugo, a static site generator built with performance as a first-class feature. I've outlined a load of benefits to Hugo and static sites [on a page explaining the benefits of static sites](https://why-static.netlify.com/), in case you're interested.
> **In essence, a static site generator pre-renders the whole site into HTML files and serves them like it's 1995.**
We had two goals:
-**Make it fast**
+## Make it fast
We wanted to optimize the site as much as possible, so we opted for using Cloudinary, enabling us to take advantage of on-the-fly image manipulation, and thanks to the sheer speed of static sites, we achieved a perfect optimization score with Google audits.
Because we're hosting the site through Netlify and our target audience is in America, we are taking advantage of Netlify edge (Their alternative to a CDN). We're talking blazing fast.
-**Make it easy**
+## Make it easy
We're big fans of simplicity, and that's what we delivered with the Forestry building blocks. Every element on the site is built with building blocks in mind, allowing PHARMASEAL to generate multiple pages in the blink of an eye.
{{< newtemplatesystem >}}
-
{{% glossary-term template %}}
Templates use [variables], [functions], and [methods] to transform your content, resources, and data into a published page.
The most important concept to understand before creating a template is _context_, the data passed into each template. The data may be a simple value, or more commonly [objects](g) and associated [methods](g).
-For example, a template for a single page receives a `Page` object, and the `Page` object provides methods to return values or perform actions.
+For example, a _page_ template receives a `Page` object, and the `Page` object provides methods to return values or perform actions.
### Current context
{{ partialCached "css.html" . }}
```
-Create your partial templates in the layouts/_partials directory.
+Create your _partial_ templates in the `layouts/_partials` directory.
> [!note]
> In the examples above, note that we are passing the current context (the dot) to each of the templates.
[`end`]: /functions/go-template/end/
[`if`]: /functions/go-template/if/
[`index`]: /functions/collections/indexfunction/
-[`index`]: /functions/collections/indexfunction/
[`or`]: /functions/go-template/or
[`Page`]: /methods/page/
[`partial`]: /functions/partials/include/
[`partialCached`]: /functions/partials/includecached/
[`range`]: /functions/go-template/range/
-[`range`]: /functions/go-template/range/
[`safeHTML`]: /functions/safe/html
[`Site`]: /methods/site/
[`template`]: /functions/go-template/template/
[`Title`]: /methods/page/title
[`with`]: /functions/go-template/with/
-[`with`]: /functions/go-template/with/
[current context]: #current-context
[embedded templates]: /templates/embedded/
[front matter]: /content-management/front-matter/
[front matter fields]: /content-management/front-matter/#fields
[functions]: /functions/
-[functions]: /functions
[go-templates]: /functions/go-template/
[html/template]: https://pkg.go.dev/html/template
[methods]: /methods/
-[methods]: /methods/
[partial templates]: /templates/types/#partial
[templates]: /templates/
[text/template]: https://pkg.go.dev/text/template
## Example
-This partial template recursively "walks" a menu structure, rendering a localized, accessible nested list.
+This _partial_ template recursively "walks" a menu structure, rendering a localized, accessible nested list.
```go-html-template {file="layouts/_partials/menu.html" copy=true}
{{- $page := .page }}
-
---
title: New template system in Hugo v0.146.0
linktitle: New template system
## Changes to template lookup order
-We have consolidated the template lookup so it works the same across all shortcodes, render hooks, partials, and page templates. The previous setup was very hard to understand and had a massive number of variants. The new setup aims to feel natural with few surprises.
+We have consolidated the template lookup so it works the same across all [template types]. The previous setup was very hard to understand and had a massive number of variants. The new setup aims to feel natural with few surprises.
The identifiers used in the template weighting, in order of importance, are:
For templates placed in a `layouts` folder partly or completely matching a [Page path], a closer match upwards will be considered _better_. In the [Example folder structure] below, this means that:
-* `layouts/docs/api/_markup/render-link.html` will be used to render links from the Page path `/docs/api` and below.
-* `layouts/docs/baseof.html` will be used as the base template for the Page path `/docs` and below.
-* `layouts/tags/term.html` will be used for all `term` rendering in the `tags` taxonomy, except for the `blue` term, which will use `layouts/tags/blue/list.html`.
+- `layouts/docs/api/_markup/render-link.html` will be used to render links from the Page path `/docs/api` and below.
+- `layouts/docs/baseof.html` will be used as the base template for the Page path `/docs` and below.
+- `layouts/tags/term.html` will be used for all `term` rendering in the `tags` taxonomy, except for the `blue` term, which will use `layouts/tags/blue/list.html`.
## Example folder structure
└── list.html
```
-[Hugo v0.146.0]: https://github.com/gohugoio/hugo/releases/tag/v0.146.0
-[Page path]: https://gohugo.io/methods/page/path/
-[Page kinds]: https://gohugo.io/methods/page/kind/
-[Example folder structure]: #example-folder-structure
-
[^type]: The `type` set in front matter will effectively replace the `section` folder in [Page path] when doing lookups.
[^internal]: The old way of doing it made it very hard/impossible to, e.g., override `_internal/disqus.html` in a theme. Now you can just create a partial with the same name.
+
+[Example folder structure]: #example-folder-structure
+[Hugo v0.146.0]: https://github.com/gohugoio/hugo/releases/tag/v0.146.0
+[Page kinds]: https://gohugo.io/methods/page/kind/
+[Page path]: https://gohugo.io/methods/page/path/
+[template types]: /templates/types/
path = 'page'
{{< /code-toggle >}}
-And this section template:
+And this _section_ template:
-```go-html-template
+```go-html-template {file="layouts/section.html"}
{{ range (.Paginate .Pages).Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
[`Paginator`]: /methods/page/paginator/
[`partial`]: /functions/partials/include/
[grouping methods]: /quick-reference/page-collections/#group
-[grouping methods]: /quick-reference/page-collections/#group
[source code]: {{% eturl pagination %}}
> 1. Set `enableRobotsTXT` to `false` in the site configuration.
> 1. Create a robots.txt file in the `static` directory.
>
-> Remember that Hugo copies everything in the [`static` directory][static] to the root of `publishDir` (typically `public`) when you build your site.
+> Remember that Hugo copies everything in the static director to the root of `publishDir` (typically `public`) when you build your site.
[embedded template]: {{% eturl robots %}}
[site configuration]: /configuration/
-[static]: /getting-started/directory-structure/
{{< newtemplatesystem >}}
-
> [!note]
> Before creating custom shortcodes, please review the [shortcodes] page in the [content management] section. Understanding the usage details will help you design and create better templates.
## Directory structure
-Create shortcode templates within the `layouts/_shortcodes` directory, either at its root or organized into subdirectories.
+Create _shortcode_ templates within the `layouts/_shortcodes` directory, either at its root or organized into subdirectories.
```text
layouts/
## Lookup order
-Hugo selects shortcode templates based on the shortcode name, the current output format, and the current language. The examples below are sorted by specificity in descending order. The least specific path is at the bottom of the list.
+Hugo selects _shortcode_ templates based on the shortcode name, the current output format, and the current language. The examples below are sorted by specificity in descending order. The least specific path is at the bottom of the list.
Shortcode name|Output format|Language|Template path
:--|:--|:--|:--
## Methods
-Use these methods in your shortcode templates. Refer to each methods's documentation for details and examples.
+Use these methods in your _shortcode_ templates. Refer to each methods's documentation for details and examples.
{{% list-pages-in-section path=/methods/shortcode %}}
## Override built-in templates
-To override the built-in sitemap.xml template, create a new file in either of these locations:
+To override the built-in sitemap.xml template, create a new `layouts/sitemap.xml` file. When ranging through the page collection, access the _change frequency_ and _priority_ with `.Sitemap.ChangeFreq` and `.Sitemap.Priority` respectively.
-- `layouts/sitemap.xml`
-- `layouts/sitemap.xml`
-
-When ranging through the page collection, access the _change frequency_ and _priority_ with `.Sitemap.ChangeFreq` and `.Sitemap.Priority` respectively.
-
-To override the built-in sitemapindex.xml template, create a new file in either of these locations:
-
-- `layouts/sitemapindex.xml`
-- `layouts/sitemapindex.xml`
+To override the built-in sitemapindex.xml template, create a new `layouts/sitemapindex.xml` file.
## Disable sitemap generation
│ ├── page.html
│ └── section.html
├── films/
-│ ├── card.html <-- content view
+│ ├── view_card.html <-- content view
+│ ├── view_li.html <-- content view
│ ├── page.html
│ └── section.html
├── baseof.html
## Base
-A base template reduces duplicate code by wrapping other templates within a shell.
+A _base_ template serves as a foundational layout that other templates can build upon. It typically defines the common structural components of your HTML, such as the `html`, `head`, and `body` elements. It also often includes recurring features like headers, footers, navigation, and script inclusions that appear across multiple pages of your site. By defining these common aspects once in a _base_ template, you avoid redundancy, ensure consistency, and simplify the maintenance of your website.
-For example, the base template below calls the [`partial`] function to include partial templates for the `head`, `header`, and `footer` elements of each page, and it calls the [`block`] function to include `home`, `page`, `section`, `taxonomy`, and `term` templates within the `main` element of each page.
+Hugo can apply a _base_ template to the following template types: [home](#home), [page](#page), [section](#section), [taxonomy](#taxonomy), [term](#term), [single](#single), [list](#list), and [all](#all). When Hugo parses any of these template types, it will apply a _base_ template only if the template being parsed meets these specific conditions:
+
+- It must include at least one [`define`] [action](g).
+- It can only contain `define` actions, whitespace, and [template comments]. No other content is allowed.
+
+> [!note]
+> If a template doesn't meet all these criteria, Hugo executes it exactly as provided, without applying a _base_ template.
+
+When Hugo applies a _base_ template, it replaces its [`block`] actions with content from the corresponding `define` actions found in the template to which the base template is applied.
+
+For example, the _base_ template below calls the [`partial`] function to include `head`, `header`, and `footer` elements. The `block` action acts as a placeholder, and its content will be replaced by a matching `define` action from the template to which it is applied.
```go-html-template {file="layouts/baseof.html"}
<!DOCTYPE html>
-<html lang="{{ or site.Language.LanguageCode }}" dir="{{ or site.Language.LanguageDirection `ltr` }}">
+<html lang="{{ site.Language.LanguageCode }}" dir="{{ or site.Language.LanguageDirection `ltr` }}">
<head>
{{ partial "head.html" . }}
</head>
{{ partial "header.html" . }}
</header>
<main>
- {{ block "main" . }}{{ end }}
+ {{ block "main" . }}
+ This will be replaced with content from the
+ corresponding "define" action found in the template
+ to which this base template is applied.
+ {{ end }}
</main>
<footer>
{{ partial "footer.html" . }}
</html>
```
-The `block` construct above is used to define a set of root templates that are then customized by redefining the block templates within. See [details](/functions/go-template/block/)
+```go-html-template {file="layouts/home.html"}
+{{ define "main" }}
+ This will replace the content of the "block" action
+ found in the base template.
+{{ end }}
+```
## Home
-A home template renders your site's home page. For example, the home template below inherits the site's shell from the [base template] and renders the home page content, such as a list of other pages.
+A _home_ template renders your site's home page.
+
+For example, Hugo applies a _base_ template to the _home_ template below, then renders the page content and a list of the site's regular pages.
```go-html-template {file="layouts/home.html"}
{{ define "main" }}
## Page
-A page template renders a regular page.
+A _page_ template renders a regular page.
-For example, the page template below inherits the site's shell from the [base template] and renders the page title and page content.
+For example, Hugo applies a _base_ template to the _page_ template below, then renders the page title and page content.
```go-html-template {file="layouts/page.html"}
{{ define "main" }}
## Section
-A section template renders a list of pages within a section.
+A _section_ template renders a list of pages within a [section](g).
-For example, the section template below inherits the site's shell from the [base template] and renders a list of pages in the current section.
+For example, Hugo applies a _base_ template to the _section_ template below, then renders the page title, page content, and a list of pages in the current section.
```go-html-template {file="layouts/section.html"}
{{ define "main" }}
## Taxonomy
-A taxonomy template renders a list of terms in a [taxonomy](g).
+A _taxonomy_ template renders a list of terms in a [taxonomy](g).
-For example, the taxonomy template below inherits the site's shell from the [base template] and renders a list of terms in the current taxonomy.
+For example, Hugo applies a _base_ template to the _taxonomy_ template below, then renders the page title, page content, and a list of [terms](g) in the current taxonomy.
```go-html-template {file="layouts/taxonomy.html"}
{{ define "main" }}
{{% include "/_common/filter-sort-group.md" %}}
-Within a taxonomy template, the [`Data`] object provides these taxonomy-specific methods:
+Within a _taxonomy_ template, the [`Data`] object provides these taxonomy-specific methods:
- [`Singular`][taxonomy-singular]
- [`Plural`][taxonomy-plural]
-- [`Terms`].
+- [`Terms`]
The `Terms` method returns a [taxonomy object](g), allowing you to call any of its methods including [`Alphabetical`] and [`ByCount`]. For example, use the `ByCount` method to render a list of terms sorted by the number of pages associated with each term:
## Term
-A term template renders a list of pages associated with a [term](g).
+A _term_ template renders a list of pages associated with a [term](g).
-For example, the term template below inherits the site's shell from the [base template] and renders a list of pages associated with the current term.
+For example, Hugo applies a _base_ template to the _term_ template below, then renders the page title, page content, and a list of pages associated with the current term.
```go-html-template {file="layouts/term.html"}
{{ define "main" }}
{{% include "/_common/filter-sort-group.md" %}}
-Within a term template, the [`Data`] object provides these term-specific methods:
+Within a _term_ template, the [`Data`] object provides these term-specific methods:
- [`Singular`][term-singular]
- [`Plural`][term-plural]
-- [`Term`].
+- [`Term`]
## Single
-A single template is a fallback for [page templates](#page). If a page template does not exist, Hugo will look for a single template instead.
-
-Like a page template, a single template renders a regular page.
+A _single_ template is a fallback for a _page_ template. If a _page_ template does not exist, Hugo will look for a _single_ template instead.
-For example, the single template below inherits the site's shell from the [base template] and renders the page title and page content.
+For example, Hugo applies a _base_ template to the _single_ template below, then renders the page title and page content.
```go-html-template {file="layouts/single.html"}
{{ define "main" }}
## List
-A list template is a fallback for these template types: [home](#home), [section](#section), [taxonomy](#taxonomy), and [term](#term). If one of these template types does not exist, Hugo will look for a list template instead.
+A _list_ template is a fallback for [home](#home), [section](#section), [taxonomy](#taxonomy), and [term](#term) templates. If one of these template types does not exist, Hugo will look for a _list_ template instead.
-For example, the list template below inherits the site's shell from the [base template] and renders a list of pages:
+For example, Hugo applies a _base_ template to the _list_ template below, then renders the page title, page content, and a list of pages.
```go-html-template {file="layouts/list.html"}
{{ define "main" }}
## All
-An "all" template is a fallback for these template types: [home](#home), [page](#page), [section](#section), [taxonomy](#taxonomy), [term](#term), [single](#single), and [list](#list). If one of these template types does not exist, Hugo will look for an "all" template instead.
+An _all_ template is a fallback for [home](#home), [page](#page), [section](#section), [taxonomy](#taxonomy), [term](#term), [single](#single), and [list](#list) templates. If one of these template types does not exist, Hugo will look for an _all_ template instead.
-For example, the contrived "all" template below inherits the site's shell from the [base template] and conditionally renders a page based on its page kind:
+For example, Hugo applies a _base_ template to the _all_ template below, then conditionally renders a page based on its page kind.
```go-html-template {file="layouts/all.html"}
{{ define "main" }}
## Partial
-A partial template is typically used to render a component of your site, though you may also create partial templates that return values.
+A _partial_ template is typically used to render a component of your site, though you may also create _partial_ templates that return values.
-
-For example, the partial template below renders copyright information:
+For example, the _partial_ template below renders copyright information:
```go-html-template {file="layouts/_partials/footer.html"}
<p>Copyright {{ now.Year }}. All rights reserved.</p>
```
-Execute the partial template by calling the [`partial`] or [`partialCached`] function, optionally passing context as the second argument:
+Execute the _partial_ template by calling the [`partial`] or [`partialCached`] function, optionally passing context as the second argument:
```go-html-template {file="layouts/baseof.html"}
{{ partial "footer.html" . }}
```
-Unlike other template types, partial template selection is based on the file name passed in the partial call. Hugo does not consider the current page kind, content type, logical path, language, or output format when searching for a matching partial template. However, Hugo _does_ apply the same name matching logic it uses for other templates. This means it tries to find the most specific match first, then progressively looks for more general versions if the specific one isn't found.
+<!-- https://github.com/gohugoio/hugo/pull/13614#issuecomment-2805977008 -->
+Unlike other template types, Hugo does not consider the current page kind, content type, logical path, language, or output format when searching for a matching _partial_ template. However, it _does_ apply the same name matching logic it uses for other template types. This means it tries to find the most specific match first, then progressively looks for more general versions if the specific one isn't found.
-For example, with this partial call:
+For example, with this call:
```go-html-template {file="layouts/baseof.html"}
{{ partial "footer.section.de.html" . }}
1. `layouts/_partials/footer.de.html`
1. `layouts/_partials/footer.html`
-Partials can also be defined inline within a template. However, it's important to note that the template namespace is global; ensuring unique names for these partials is necessary to prevent conflicts.
+A _partial_ template can also be defined inline within another template. However, it's important to note that the template namespace is global; ensuring unique names for these _partial_ templates is necessary to prevent conflicts.
```go-html-template
Value: {{ partial "my-inline-partial.html" . }}
## Content view
-A content view template is similar to a partial template, invoked by calling the [`Render`] method on a `Page` object. Unlike partial templates, content view templates:
+A _content view_ template is similar to a _partial_ template, invoked by calling the [`Render`] method on a `Page` object. Unlike _partial_ templates, _content view_ templates:
- Inherit the context of the current page
- Can target any page kind, content type, logical path, language, or output format
-For example, the home template below inherits the site's shell from the [base template], and renders a card component for each page within the "films" section of your site.
+For example, Hugo applies a _base_ template to the _home_ template below, then renders the page content and a card component for each page within the "films" section of your site.
```go-html-template {file="layouts/home.html"}
{{ define "main" }}
{{ .Content }}
<ul>
{{ range where site.RegularPages "Section" "films" }}
- {{ .Render "card" }}
+ {{ .Render "view_card" }}
{{ end }}
</ul>
{{ end }}
```
-```go-html-template {file="layouts/films/card.html"}
+```go-html-template {file="layouts/films/view_card.html"}
<div class="card">
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ .Summary }}
</div>
```
+In the example above, the content view template's name starts with `view_`. While not strictly required, this naming convention helps distinguish content view templates from other templates within the same directory, improving organization and clarity.
+
## Render hook
-A render hook template overrides the conversion of Markdown to HTML.
+A _render hook_ template overrides the conversion of Markdown to HTML.
-For example, the render hook template below adds an anchor link to the right of each heading.
+For example, the _render hook_ template below adds an anchor link to the right of each heading.
-```go-html-template {file="layouts/_markup/heading.html"}
+```go-html-template {file="layouts/_markup/render-heading.html"}
<h{{ .Level }} id="{{ .Anchor }}" {{- with .Attributes.class }} class="{{ . }}" {{- end }}>
{{ .Text }}
<a href="#{{ .Anchor }}">#</a>
## Shortcode
-A shortcode template is used to render a component of your site. Unlike [partial templates](#partial) or [content view templates](#content-view), shortcode templates are called from content pages.
+A _shortcode_ template is used to render a component of your site. Unlike _partial_ or _content view_ templates, _shortcode_ templates are called from content pages.
-For example, the shortcode template below renders an audio element from a [global resource](g).
+For example, the _shortcode_ template below renders an audio element from a [global resource](g).
```go-html-template {file="layouts/_shortcodes/audio.html"}
{{ with resources.Get (.Get "src") }}
[`block`]: /functions/go-template/block/
[`ByCount`]: /methods/taxonomy/bycount/
[`Data`]: /methods/page/data/
+[`define`]: /functions/go-template/define/
[`partial`]: /functions/partials/include/
[`partialCached`]: /functions/partials/includeCached/
[`Render`]: /methods/page/render/
-[`Taxonomy`]: /methods/taxonomy/
-[`Terms`]: /methods/page/data/#terms
[`Term`]: /methods/page/data/#term
+[`Terms`]: /methods/page/data/#terms
[taxonomy-plural]: /methods/page/data/#plural
[taxonomy-singular]: /methods/page/data/#singular
+[template comments]: /templates/introduction/#comments
[template lookup order]: /templates/lookup-order/
[term-plural]: /methods/page/data/#plural-1
[term-singular]: /methods/page/data/#singular-1
-[base template]: #base
: Once you go for a static site, you need to think about how you are going to manage your articles. Front matter is a tool that helps you maintain the metadata/front matter of your articles like: creation date, modified date, slug, tile, SEO check, and more.
[Hugo Helper](https://marketplace.visualstudio.com/items?itemName=rusnasonov.vscode-hugo)
-: Hugo Helper is a plugin for Visual Studio Code that has some useful commands for Hugo. The source code can be found [here](https://github.com/rusnasonov/vscode-hugo).
+: Hugo Helper is a plugin for Visual Studio Code that has some useful commands for Hugo. The source code can be found on its [GitHub repository](https://github.com/rusnasonov/vscode-hugo).
[Hugo Language and Syntax Support](https://marketplace.visualstudio.com/items?itemName=budparr.language-hugo-vscode)
-: Hugo Language and Syntax Support is a Visual Studio Code plugin for Hugo syntax highlighting and snippets. The source code can be found [here](https://github.com/budparr/language-hugo-vscode).
+: Hugo Language and Syntax Support is a Visual Studio Code plugin for Hugo syntax highlighting and snippets. The source code can be found on its [GitHub repository](https://github.com/budparr/language-hugo-vscode).
[Hugo Themer](https://marketplace.visualstudio.com/items?itemName=eliostruyf.vscode-hugo-themer)
: Hugo Themer is an extension to help you while developing themes. It allows you to easily navigate through your theme files.
[Hugofy](https://marketplace.visualstudio.com/items?itemName=akmittal.hugofy)
-: Hugofy is a plugin for Visual Studio Code to "make life easier" when developing with Hugo. The source code can be found [here](https://github.com/akmittal/hugofy-vscode).
+: Hugofy is a plugin for Visual Studio Code to "make life easier" when developing with Hugo. The source code can be found on its [GitHub repository](https://github.com/akmittal/hugofy-vscode).
[Prettier Plugin for Go Templates](https://github.com/NiklasPor/prettier-plugin-go-template)
: Format Hugo templates using this [Prettier](https://prettier.io/) plugin. See [installation instructions](https://discourse.gohugo.io/t/38403).
: Emacs major mode for managing hugo blogs. Note that Hugo also supports [Org-mode][formats].
[ox-hugo.el](https://ox-hugo.scripter.co)
-: Native Org-mode exporter that exports to Blackfriday Markdown with Hugo front-matter. `ox-hugo` supports two common Org blogging flows --- exporting multiple Org subtrees in a single file to multiple Hugo posts, and exporting a single Org file to a single Hugo post. It also leverages the Org tag and property inheritance features. See [*Why ox-hugo?*](https://ox-hugo.scripter.co/doc/why-ox-hugo/) for more.
+: Native Org-mode exporter that exports to Blackfriday Markdown with Hugo front-matter. `ox-hugo` supports two common Org blogging flows --- exporting multiple Org subtrees in a single file to multiple Hugo posts, and exporting a single Org file to a single Hugo post. It also leverages the Org tag and property inheritance features. See [Why ox-hugo?](https://ox-hugo.scripter.co/doc/why-ox-hugo/) for more.
## Sublime Text
[PubCrank](https://www.pubcrank.com/)
: PubCrank is a static site editor which lets you define templates for different front matter layouts in your site. This gives writers an easy-to-use visual interface to create and edit content while maintaining the guardrails that the developer has created. PubCrank is free for local editing.
+[Sitepins](https://sitepins.com)
+: Sitepins is a Git-based CMS built for static site generators like Hugo. It offers a clean visual editor, media management, role-based permissions, shortcode support, and more. To get started, simply connect your GitHub repository, configure your content folders, and start visually editing your Hugo site with Sitepins.
+
## Open-source
[Decap CMS](https://decapcms.org/)
: A small utility written in Java that exports the entire WordPress site from the database and resource (e.g., images) files stored locally or remotely. Therefore, migration from the backup files is possible. Supports merging multiple WordPress sites into a single Hugo site.
[wp2hugo](https://github.com/ashishb/wp2hugo)
-: A Go-based CLI tool to migrate WordPress website to Hugo while preserving original URLs, GUIDs (for feeds), image URLs, code highlights, table of contents, YouTube embeds, Google Maps embeds, and original WordPress navigation categories.
+: A Go-based CLI tool to migrate WordPress websites to Hugo. It preserves original URLs, GUIDs, image URLs, code highlights, tables of contents, and WordPress navigation categories. It migrates WordPress custom post types, custom taxonomies, custom fields, and page hierarchy. It supports translated WordPress blogs via Polylang or WPML. It imports a WordPress media library database with original titles and dates. The tool can download all media or only media inserted into pages from the original server. It converts WordPress shortcodes and Gutenberg blocks to Hugo shortcodes including galleries, images, audio, YouTube embeds, Gists, and Google Maps.
## Medium
What is the difference between an `index.md` file and an `_index.md` file?
: A directory with an `index.md file` is a [leaf bundle](g). A directory with an `_index.md` file is a [branch bundle](g). See [details](/content-management/page-bundles/).
-Why is my partial template not rendered as expected?
+Why is my _partial_ template not rendered as expected?
: You may have neglected to pass the required [context](g) when calling the partial. For example:
```go-html-template
: You are probably invoking the [`Paginate`] or [`Paginator`] method more than once on the same page. See [details](/templates/pagination/).
Why are there two ways to call a shortcode?
-: Use the `{{%/* shortcode */%}}` notation if the shortcode template, or the content between the opening and closing shortcode tags, contains Markdown. Otherwise use the\
+: Use the `{{%/* shortcode */%}}` notation if the _shortcode_ template, or the content between the opening and closing shortcode tags, contains Markdown. Otherwise use the\
`{{</* shortcode */>}}` notation. See [details](/content-management/shortcodes/#notation).
Can I use environment variables to control configuration?
In these cases, instead of monitoring native file system events, use the `--poll` command line flag. For example, to poll the project files every 700 milliseconds, use `--poll 700ms`.
Why is my page Store missing a value?
-: The [`Store`] method on a `Page` object allows you to create a [scratch pad](g) on the given page to store and manipulate data. Values are often set within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are not determinate until Hugo renders the page content.
+: The [`Store`] method on a `Page` object allows you to create a [scratch pad](g) on the given page to store and manipulate data. Values are often set within a _shortcode_ template, a _partial_ template called by a _shortcode_ template, or by a _render hook_ template. In all three cases, the scratch pad values are not determinate until Hugo renders the page content.
If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop](g) variable:
[`Paginator`]: /methods/page/paginator/
[`Store`]: /methods/page/store
[forum]: https://discourse.gohugo.io
-[forum]: https://discourse.gohugo.io
[installation]: /installation/
[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132
-[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132
: The maximum time spent executing the template.
cache potential
-: Displayed as a percentage, any partial template with a 100% cache potential should be called with the [`partialCached`] function instead of the [`partial`] function. See the [caching](#caching) section below.
+: Displayed as a percentage, any _partial_ template with a 100% cache potential should be called with the [`partialCached`] function instead of the [`partial`] function. See the [caching](#caching) section below.
percent cached
: The number of times the rendered templated was cached divided by the number of times the template was executed.
## Caching
-Some partial templates such as sidebars or menus are executed many times during a site build. Depending on the content within the partial template and the desired output, the template may benefit from caching to reduce the number of executions. The [`partialCached`] template function provides caching capabilities for partial templates.
+Some _partial_ templates such as sidebars or menus are executed many times during a site build. Depending on the content within the _partial_ template and the desired output, the template may benefit from caching to reduce the number of executions. The [`partialCached`] template function provides caching capabilities for _partial_ templates.
> [!note]
> Note that you can create cached variants of each partial by passing additional arguments to `partialCached` beyond the initial context. See the `partialCached` documentation for more details.
- Aliases:
- coq
Name: Coq
+ - Aliases:
+ - core
+ Name: Core
- Aliases:
- cr
- crystal
- Aliases:
- monkeyc
Name: MonkeyC
+ - Aliases:
+ - moonscript
+ - moon
+ Name: MoonScript
- Aliases:
- morrowind
- mwscript
renderHooks:
image:
enableDefault: false
+ useEmbedded: auto
link:
enableDefault: false
+ useEmbedded: auto
renderer:
hardWraps: false
unsafe: false
-# Do not delete. Required for layouts/shortcodes/list-pages-in-section.html.
+# Do not delete. Required for layouts/_shortcodes/list-pages-in-section.html.
#
# When calling the list-pages-in-section shortcode, you can specify a page
# filter, and whether the pages in the filter should be included or excluded
link = "https://www.jetbrains.com/go/?utm_source=OSS&utm_medium=referral&utm_campaign=hugo"
logo = "images/sponsors/goland.svg"
bgcolor = "#f4f4f4"
-
-[[banners]]
- name = "PinMe"
- link = "https://pinme.eth.limo/?s=hugo"
- logo = "images/sponsors/logo-pinme.svg"
- no_query_params = true
- bgcolor = "#fafafa"
command = "hugo --gc --minify"
[build.environment]
- HUGO_VERSION = "0.147.9"
+ HUGO_VERSION = "0.148.2"
[context.production.environment]
HUGO_ENV = "production"
projects / brevno-suite / hugo / commitdiff
