diff --git a/docs/.codespellrc b/docs/.codespellrc index 564fc77c0..f322b0123 100644 --- a/docs/.codespellrc +++ b/docs/.codespellrc @@ -4,10 +4,10 @@ [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 diff --git a/docs/.cspell.json b/docs/.cspell.json index 16f9bd9f2..28dba57be 100644 --- a/docs/.cspell.json +++ b/docs/.cspell.json @@ -1,8 +1,15 @@ { "version": "0.2", "allowCompoundWords": true, - "files": [ - "**/*.md" + "overrides": [ + { + "filename": "**/*", + "enabled": false + }, + { + "filename": "**/*.md", + "enabled": true + } ], "flagWords": [ "alot", @@ -64,6 +71,7 @@ "templating", "transpile", "unmarshal", + "unmarshaled", "unmarshaling", "unmarshals", "# ----------------------------------------------------------------------", @@ -100,6 +108,8 @@ "descripción", "dokumentation", "erklärungen", + "español", + "français", "libros", "mercredi", "miesiąc", @@ -147,6 +157,7 @@ "dpkg", "doas", "eopkg", + "forgejo", "gitee", "goldmark", "katex", diff --git a/docs/.github/stale.yml b/docs/.github/stale.yml deleted file mode 100644 index 1e72eb329..000000000 --- a/docs/.github/stale.yml +++ /dev/null @@ -1,22 +0,0 @@ -# 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 diff --git a/docs/.github/workflows/codeql-analysis.yml b/docs/.github/workflows/codeql-analysis.yml index 86441b845..6f7038c9e 100644 --- a/docs/.github/workflows/codeql-analysis.yml +++ b/docs/.github/workflows/codeql-analysis.yml @@ -15,7 +15,7 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Initialize CodeQL uses: github/codeql-action/init@v3 diff --git a/docs/.github/workflows/markdownlint.yml b/docs/.github/workflows/markdownlint.yml new file mode 100644 index 000000000..0e2ac88fb --- /dev/null +++ b/docs/.github/workflows/markdownlint.yml @@ -0,0 +1,15 @@ +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 diff --git a/docs/.github/workflows/spellcheck.yml b/docs/.github/workflows/spellcheck.yml index e01ab1764..d9036f18a 100644 --- a/docs/.github/workflows/spellcheck.yml +++ b/docs/.github/workflows/spellcheck.yml @@ -12,16 +12,14 @@ jobs: 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 diff --git a/docs/.github/workflows/stale.yml b/docs/.github/workflows/stale.yml new file mode 100644 index 000000000..c537f1642 --- /dev/null +++ b/docs/.github/workflows/stale.yml @@ -0,0 +1,32 @@ +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. diff --git a/docs/.github/workflows/super-linter.yml b/docs/.github/workflows/super-linter.yml deleted file mode 100644 index d8e408ee2..000000000 --- a/docs/.github/workflows/super-linter.yml +++ /dev/null @@ -1,41 +0,0 @@ -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 diff --git a/docs/.markdownlint-cli2.yaml b/docs/.markdownlint-cli2.yaml new file mode 100644 index 000000000..1ededafd0 --- /dev/null +++ b/docs/.markdownlint-cli2.yaml @@ -0,0 +1,91 @@ +# 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 diff --git a/docs/.markdownlint.yaml b/docs/.markdownlint.yaml deleted file mode 100644 index dbb5b2ee8..000000000 --- a/docs/.markdownlint.yaml +++ /dev/null @@ -1,27 +0,0 @@ -# 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 diff --git a/docs/.markdownlintignore b/docs/.markdownlintignore deleted file mode 100644 index 4ac45b395..000000000 --- a/docs/.markdownlintignore +++ /dev/null @@ -1,6 +0,0 @@ -**/commands/** -**/functions/** -**/news/** -**/showcase/** -**/zh/** -**/license.md diff --git a/docs/content/en/_common/functions/js/options.md b/docs/content/en/_common/functions/js/options.md index 475429d05..0c82fcae5 100644 --- a/docs/content/en/_common/functions/js/options.md +++ b/docs/content/en/_common/functions/js/options.md @@ -8,6 +8,7 @@ params ```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 @@ -21,10 +22,10 @@ minify 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 . 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 . 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: @@ -58,10 +59,10 @@ target 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 . 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 . 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. @@ -73,7 +74,7 @@ defines 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 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. @@ -84,11 +85,11 @@ sourcesContent 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 . 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 . The combination of `JSX` and `JSXImportSource` is helpful if you want to use a non-React JSX library like Preact, e.g.: diff --git a/docs/content/en/_common/gomodules-info.md b/docs/content/en/_common/gomodules-info.md index 5d88a6f9d..1eefff545 100644 --- a/docs/content/en/_common/gomodules-info.md +++ b/docs/content/en/_common/gomodules-info.md @@ -6,6 +6,7 @@ _comment: Do not remove front matter. > 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) diff --git a/docs/content/en/_common/installation/03-prebuilt-binaries.md b/docs/content/en/_common/installation/03-prebuilt-binaries.md index 34411cddd..c72a68bee 100644 --- a/docs/content/en/_common/installation/03-prebuilt-binaries.md +++ b/docs/content/en/_common/installation/03-prebuilt-binaries.md @@ -15,9 +15,3 @@ Prebuilt binaries are available for a variety of operating systems and architect 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 diff --git a/docs/content/en/_common/methods/taxonomy/get-a-taxonomy-object.md b/docs/content/en/_common/methods/taxonomy/get-a-taxonomy-object.md index a6c46b8b7..c90224338 100644 --- a/docs/content/en/_common/methods/taxonomy/get-a-taxonomy-object.md +++ b/docs/content/en/_common/methods/taxonomy/get-a-taxonomy-object.md @@ -32,7 +32,7 @@ To capture the "genres" `Taxonomy` object from within any template, use the [`Ta {{ $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 }} diff --git a/docs/content/en/_common/permalink-tokens.md b/docs/content/en/_common/permalink-tokens.md index e8443101a..62b4b0d0c 100644 --- a/docs/content/en/_common/permalink-tokens.md +++ b/docs/content/en/_common/permalink-tokens.md @@ -73,5 +73,3 @@ For time-related values, you can also use the layout string components defined i permalinks: posts: /:06/:1/:2/:title/ {{< /code-toggle >}} - -[content base name]: /methods/page/file/#contentbasename diff --git a/docs/content/en/_common/render-hooks/pageinner.md b/docs/content/en/_common/render-hooks/pageinner.md index e5c0afb79..3efbc9ce3 100644 --- a/docs/content/en/_common/render-hooks/pageinner.md +++ b/docs/content/en/_common/render-hooks/pageinner.md @@ -22,14 +22,14 @@ The primary use case for `PageInner` is to resolve links and [page resources](g) 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. diff --git a/docs/content/en/_common/scratch-pad-scope.md b/docs/content/en/_common/scratch-pad-scope.md index b659497d8..789b943e6 100644 --- a/docs/content/en/_common/scratch-pad-scope.md +++ b/docs/content/en/_common/scratch-pad-scope.md @@ -9,7 +9,7 @@ The method or function used to create a scratch pad determines its scope. For ex Scope|Method or function :--|:-- page|[`PAGE.Store`] -site|[`SITE.Store`] +site|[`SITE.Store`] global|[`hugo.Store`] local|[`collections.NewScratch`] shortcode|[`SHORTCODE.Store`] diff --git a/docs/content/en/_common/syntax-highlighting-options.md b/docs/content/en/_common/syntax-highlighting-options.md index 36144e090..11348f661 100644 --- a/docs/content/en/_common/syntax-highlighting-options.md +++ b/docs/content/en/_common/syntax-highlighting-options.md @@ -28,6 +28,7 @@ lineNoStart 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`). diff --git a/docs/content/en/about/features.md b/docs/content/en/about/features.md index ff1a6b8eb..d9fd36f61 100644 --- a/docs/content/en/about/features.md +++ b/docs/content/en/about/features.md @@ -92,7 +92,7 @@ weight: 20 ## 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. diff --git a/docs/content/en/configuration/all.md b/docs/content/en/configuration/all.md index c64638499..c733e0a99 100644 --- a/docs/content/en/configuration/all.md +++ b/docs/content/en/configuration/all.md @@ -339,7 +339,6 @@ Some configuration settings, such as menus and custom parameters, can be defined [`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/ diff --git a/docs/content/en/configuration/build.md b/docs/content/en/configuration/build.md index 116294f05..1354f0860 100644 --- a/docs/content/en/configuration/build.md +++ b/docs/content/en/configuration/build.md @@ -27,6 +27,7 @@ useResourceCacheWhen 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: + {{< code-toggle file=hugo >}} [build] [build.buildStats] @@ -44,6 +45,7 @@ The `build.cachebusters` configuration option was added to support development u source = "assets/.*\\.(.*)$" target = "$1" {{< /code-toggle >}} + 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. diff --git a/docs/content/en/configuration/cascade.md b/docs/content/en/configuration/cascade.md index d91996301..85b221df2 100644 --- a/docs/content/en/configuration/cascade.md +++ b/docs/content/en/configuration/cascade.md @@ -44,7 +44,7 @@ environment : (`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}`. diff --git a/docs/content/en/configuration/front-matter.md b/docs/content/en/configuration/front-matter.md index 9f51b8a5a..a97648b61 100644 --- a/docs/content/en/configuration/front-matter.md +++ b/docs/content/en/configuration/front-matter.md @@ -60,25 +60,32 @@ The default front matter configuration includes these aliases. ## 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`). -Consider this example: + 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`. + +`: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] @@ -89,3 +96,7 @@ lastmod = ['lastmod', ':fileModTime'] 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 diff --git a/docs/content/en/configuration/markup.md b/docs/content/en/configuration/markup.md index 4a2efb5e8..bf5aac374 100644 --- a/docs/content/en/configuration/markup.md +++ b/docs/content/en/configuration/markup.md @@ -47,10 +47,10 @@ Extension|Documentation|Enabled :--|:--|:-: `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: @@ -70,12 +70,19 @@ Mark text|`==baz==`|`baz` Subscript|`H~2~O`|`H2O` Superscript|`1^st^`|`1st` -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 +[^1]: See [details](https://github.com/gohugoio/hugo-goldmark-extensions/commit/4d4fcd022fe45a9b51483df001c9e5f4e632d5a9). -For example: +{{< code-toggle file=hugo >}} +[markup.goldmark.extensions] +strikethrough = false + +[markup.goldmark.extensions.extras.subscript] +enable = true +{{< /code-toggle >}} + +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] @@ -83,11 +90,10 @@ strikethrough = false [markup.goldmark.extensions.extras.delete] enable = true - -[markup.goldmark.extensions.extras.subscript] -enable = true {{< /code-toggle >}} +With this configuration, to format text as deleted, wrap it with double-tildes. + #### Passthrough {{< new-in 0.122.0 />}} @@ -111,7 +117,7 @@ Markdown|Replaced by|Description `”`|`”`|right double quote `’`|`’`|right single quote -### Settings explained +### Goldmark settings explained Most of the Goldmark settings above are self-explanatory, but some require explanation. @@ -133,13 +139,13 @@ parser.autoHeadingID : (`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`. @@ -147,19 +153,33 @@ parser.attribute.block parser.attribute.title : (`bool`) Whether to enable [Markdown attributes] for headings. Default is `true`. + 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. + + 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`. @@ -173,7 +193,7 @@ This is the default configuration for the AsciiDoc renderer: {{< 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]. @@ -226,49 +246,47 @@ workingFolderCurrent 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"} + + ... + {{ with resources.Get "css/syntax.css" }} + + {{ end }} + ... + + ``` -#### 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"} - - ... - {{ with resources.Get "css/syntax.css" }} - - {{ end }} - ... - -``` - -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 @@ -303,24 +321,24 @@ ordered [`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/ @@ -330,12 +348,10 @@ ordered [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 diff --git a/docs/content/en/configuration/menus.md b/docs/content/en/configuration/menus.md index 759f53ff3..6b27e966b 100644 --- a/docs/content/en/configuration/menus.md +++ b/docs/content/en/configuration/menus.md @@ -96,6 +96,7 @@ url This nested menu demonstrates some of the available properties: + {{< code-toggle file=hugo >}} [[menus.main]] name = 'Products' @@ -127,6 +128,7 @@ weight = 30 [menus.main.params] rel = 'external' {{< /code-toggle >}} + [`Menus`]: /methods/site/menus/ [Automatically]: /content-management/menus/#define-automatically diff --git a/docs/content/en/configuration/module.md b/docs/content/en/configuration/module.md index d736b7c6f..4a7267bd6 100644 --- a/docs/content/en/configuration/module.md +++ b/docs/content/en/configuration/module.md @@ -11,6 +11,7 @@ aliases: [/hugo-modules/configuration/] This is the default configuration: + {{< code-toggle file=hugo >}} [module] noProxy = 'none' @@ -20,6 +21,7 @@ proxy = 'direct' vendorClosest = false workspace = 'off' {{< /code-toggle >}} + auth : {{< new-in 0.144.0 />}} @@ -75,12 +77,10 @@ extended : (`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 @@ -112,8 +112,6 @@ noVendor 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 @@ -177,3 +175,5 @@ excludeFiles source="assets" target="assets" {{< /code-toggle >}} + +[`themesDir`]: /configuration/all/#themesdir diff --git a/docs/content/en/configuration/output-formats.md b/docs/content/en/configuration/output-formats.md index f3dbceec5..7e80d30fb 100644 --- a/docs/content/en/configuration/output-formats.md +++ b/docs/content/en/configuration/output-formats.md @@ -44,25 +44,25 @@ isHTML : (`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`. @@ -93,56 +93,52 @@ The example above shows that when you modify a default content format, you only 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. -See [configure media types] for more information. +Step 2 +: Create a new output format: -### Step 2 + {{< code-toggle file=hugo >}} + [outputFormats.atom] + mediaType = 'application/atom+xml' + noUgly = true + {{< /code-toggle >}} -Create a new output format: + Note that we use the default settings for all other output format properties. -{{< code-toggle file=hugo >}} -[outputFormats.atom] -mediaType = 'application/atom+xml' -noUgly = true -{{< /code-toggle >}} +Step 3 +: 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 + See [configure outputs][] for more information. -Specify the page [kinds](g) for which to render this output format: +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: -{{< code-toggle file=hugo >}} -[outputs] -home = ['html', 'rss', 'atom'] -section = ['html', 'rss', 'atom'] -taxonomy = ['html', 'rss', 'atom'] -term = ['html', 'rss', 'atom'] -{{< /code-toggle >}} + ```text + layouts/list.atom.atom + ``` -See [configure outputs] for more information. - -### 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 -``` - -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 }} @@ -152,7 +148,7 @@ To access output formats, each `Page` object provides two methods: [`OutputForma ## 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: @@ -163,7 +159,7 @@ 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: @@ -176,7 +172,7 @@ With `permalinkable` set to true for `json` in the same `page.json.json` templat ## 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: @@ -193,17 +189,18 @@ Output format|Template path `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 diff --git a/docs/content/en/configuration/related-content.md b/docs/content/en/configuration/related-content.md index 7f2aa9831..421a1ea77 100644 --- a/docs/content/en/configuration/related-content.md +++ b/docs/content/en/configuration/related-content.md @@ -95,7 +95,7 @@ weight = 1 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 }} diff --git a/docs/content/en/configuration/security.md b/docs/content/en/configuration/security.md index f950dd233..f9eb91bd9 100644 --- a/docs/content/en/configuration/security.md +++ b/docs/content/en/configuration/security.md @@ -6,7 +6,7 @@ categories: [] 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: @@ -34,7 +34,7 @@ http.urls : (`[]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: diff --git a/docs/content/en/configuration/segments.md b/docs/content/en/configuration/segments.md index 0c4098770..b87c870c4 100644 --- a/docs/content/en/configuration/segments.md +++ b/docs/content/en/configuration/segments.md @@ -31,7 +31,7 @@ Each segment is defined by include and exclude filters: 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}`. diff --git a/docs/content/en/configuration/server.md b/docs/content/en/configuration/server.md index 92f0f0cfa..f77e7f47f 100644 --- a/docs/content/en/configuration/server.md +++ b/docs/content/en/configuration/server.md @@ -47,7 +47,7 @@ to ## 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 diff --git a/docs/content/en/configuration/taxonomies.md b/docs/content/en/configuration/taxonomies.md index 3cf6497bc..fed1d4c5e 100644 --- a/docs/content/en/configuration/taxonomies.md +++ b/docs/content/en/configuration/taxonomies.md @@ -17,8 +17,8 @@ When creating a taxonomy: Then use the value as the key in front matter: + {{< code-toggle file=content/example.md fm=true >}} ---- title: Example categories: - vegetarian @@ -27,7 +27,7 @@ tags: - appetizer - main course {{< /code-toggle >}} - + 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 >}} @@ -37,12 +37,13 @@ taxonomies: Then in front matter: + {{< code-toggle file=content/example.md fm=true >}} ---- title: Example author: - Robert Smith {{< /code-toggle >}} + The example above illustrates that even with a single term, the value is still provided as an array. diff --git a/docs/content/en/configuration/ugly-urls.md b/docs/content/en/configuration/ugly-urls.md index ec1dd8a49..17b110a9f 100644 --- a/docs/content/en/configuration/ugly-urls.md +++ b/docs/content/en/configuration/ugly-urls.md @@ -13,6 +13,7 @@ https://example.org/section/article.html ``` In its default configuration, Hugo generates [pretty URLs](g). For example: + ```text https://example.org/section/article/ ``` diff --git a/docs/content/en/content-management/comments.md b/docs/content/en/content-management/comments.md index f0e4a9ae1..b843ddb99 100644 --- a/docs/content/en/content-management/comments.md +++ b/docs/content/en/content-management/comments.md @@ -64,9 +64,4 @@ Open-source commenting systems: [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/ diff --git a/docs/content/en/content-management/content-adapters.md b/docs/content/en/content-management/content-adapters.md index e22962531..9eae86266 100644 --- a/docs/content/en/content-management/content-adapters.md +++ b/docs/content/en/content-management/content-adapters.md @@ -161,112 +161,109 @@ Key|Description|Required Create pages from remote data, where each page represents a book review. -### Step 1 +Step 1 +: Create the content structure. -Create the content structure. + ```text + content/ + └── books/ + ├── _content.gotmpl <-- content adapter + └── _index.md + ``` -```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.\ + -### Step 2 -Inspect the remote data to determine how to map key-value pairs to front matter fields.\ - +Step 3 +: Create the content adapter. -### 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 }} - -{{/* 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 }} + ```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 }} -### Step 4 + {{/* 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 }} -Create a page template to render each book review. - -```go-html-template {file="layouts/books/page.html" copy=true} -{{ define "main" }} -

{{ .Title }}

- - {{ with .Resources.GetMatch "cover.*" }} - {{ .Params.alt }} - {{ end }} - -

Author: {{ .Params.author }}

- -

- ISBN: {{ .Params.isbn }}
- Rating: {{ .Params.rating }}
- Review date: {{ .Date | time.Format ":date_long" }} -

- - {{ with .GetTerms "tags" }} -

Tags:

-
    - {{ range . }} -
  • {{ .LinkTitle }}
    • + {{/* 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 }} - {{ .Content }} -{{ end }} -``` + {{ end }} + ``` + +Step 4 +: Create a _page_ template to render each book review. + + ```go-html-template {file="layouts/books/page.html" copy=true} + {{ define "main" }} +

{{ .Title }}

+ + {{ with .Resources.GetMatch "cover.*" }} + {{ .Params.alt }} + {{ end }} + +

Author: {{ .Params.author }}

+ +

+ ISBN: {{ .Params.isbn }}
+ Rating: {{ .Params.rating }}
+ Review date: {{ .Date | time.Format ":date_long" }} +

+ + {{ with .GetTerms "tags" }} +

Tags:

+ + {{ end }} + + {{ .Content }} + {{ end }} + ``` ## Multilingual sites diff --git a/docs/content/en/content-management/formats.md b/docs/content/en/content-management/formats.md index c82329ab2..65fb3d04d 100644 --- a/docs/content/en/content-management/formats.md +++ b/docs/content/en/content-management/formats.md @@ -92,7 +92,6 @@ hugo --logLevel info ``` [AsciiDoc]: https://asciidoc.org/ -[configure the AsciiDoc renderer]: /configuration/markup/#asciidoc [configure asciidoc]: /configuration/markup/#asciidoc ### Pandoc diff --git a/docs/content/en/content-management/front-matter.md b/docs/content/en/content-management/front-matter.md index d99475f4c..2da6a2613 100644 --- a/docs/content/en/content-management/front-matter.md +++ b/docs/content/en/content-management/front-matter.md @@ -18,10 +18,6 @@ The front matter at the top of each content file is metadata that: 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 >}} @@ -115,7 +111,7 @@ sitemap : (`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. @@ -138,42 +134,6 @@ url 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 />}} @@ -191,9 +151,6 @@ author = 'John Smith' 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 @@ -248,7 +205,6 @@ Access taxonomy terms from a template using the [`Params`] or [`GetTerms`] metho {{ end }} ``` -[`Params`]: /methods/page/params/ [`GetTerms`]: /methods/page/getterms/ ## Cascade @@ -289,7 +245,7 @@ environment : (`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/**}`. @@ -356,7 +312,46 @@ To override the default time zone, set the [`timeZone`](/configuration/all/#time 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/ diff --git a/docs/content/en/content-management/mathematics.md b/docs/content/en/content-management/mathematics.md index dc47cbde4..aaa8c2394 100644 --- a/docs/content/en/content-management/mathematics.md +++ b/docs/content/en/content-management/mathematics.md @@ -45,117 +45,114 @@ Whether an equation or expression appears inline, or as a block, depends on the 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} + + + ``` -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} - - -``` +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"} + + ... + {{ if .Param "math" }} + {{ partialCached "math.html" . }} + {{ end }} + ... + + ``` -### 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"} - - ... - {{ if .Param "math" }} - {{ partialCached "math.html" . }} - {{ end }} - ... - -``` + {{< 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^* -\] + $$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: - -{{< 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 @@ -179,7 +176,7 @@ MathJax and KaTeX are open-source JavaScript display engines. Both engines are f > >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} {{< code-toggle file=content/products/software.md fm=true >}} title = 'Software' [menus.main] @@ -77,6 +78,7 @@ pre = '' [menus.main.params] class = 'center' {{< /code-toggle >}} + Access the entry with `site.Menus.main` in your templates. See [menu templates] for details. diff --git a/docs/content/en/content-management/multilingual.md b/docs/content/en/content-management/multilingual.md index a22f0b50e..5a5cd2307 100644 --- a/docs/content/en/content-management/multilingual.md +++ b/docs/content/en/content-management/multilingual.md @@ -25,9 +25,9 @@ Considering the following example: 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. @@ -58,9 +58,9 @@ Considering the following example in conjunction with the configuration above: 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 @@ -76,7 +76,7 @@ Considering the following example: 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 @@ -127,7 +127,7 @@ To create a list of links to translated content, use a template similar to the f {{ 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. diff --git a/docs/content/en/content-management/organization/index.md b/docs/content/en/content-management/organization/index.md index 4a8fcb6fc..4c6b94e3e 100644 --- a/docs/content/en/content-management/organization/index.md +++ b/docs/content/en/content-management/organization/index.md @@ -128,7 +128,7 @@ The following concepts provide more insight into the relationship between your p ### `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` diff --git a/docs/content/en/content-management/page-bundles.md b/docs/content/en/content-management/page-bundles.md index f6a5cf771..a5bf9a3af 100644 --- a/docs/content/en/content-management/page-bundles.md +++ b/docs/content/en/content-management/page-bundles.md @@ -38,10 +38,10 @@ Page bundle characteristics vary by bundle type. | | 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` | diff --git a/docs/content/en/content-management/page-resources.md b/docs/content/en/content-management/page-resources.md index 204ca5301..e8991de6f 100644 --- a/docs/content/en/content-management/page-resources.md +++ b/docs/content/en/content-management/page-resources.md @@ -35,10 +35,10 @@ content 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. @@ -125,30 +125,32 @@ params ### Resources metadata example + {{< 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 {{}} + From the example above: @@ -271,12 +273,12 @@ public/ 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: @@ -288,10 +290,10 @@ duplicateResourceFiles = true [`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 diff --git a/docs/content/en/content-management/sections.md b/docs/content/en/content-management/sections.md index d21aca71b..3dfad5bd4 100644 --- a/docs/content/en/content-management/sections.md +++ b/docs/content/en/content-management/sections.md @@ -53,7 +53,7 @@ The example above has two top-level sections: articles and products. None of the 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: @@ -63,7 +63,7 @@ With the file structure from the [example above](#overview): 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 diff --git a/docs/content/en/content-management/shortcodes.md b/docs/content/en/content-management/shortcodes.md index 2c3f1e29f..07ad22568 100644 --- a/docs/content/en/content-management/shortcodes.md +++ b/docs/content/en/content-management/shortcodes.md @@ -20,7 +20,7 @@ Hugo's embedded shortcodes are pre-defined templates within the application. Ref ## 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") }} @@ -38,11 +38,11 @@ Learn more about creating shortcodes in the [shortcode templates] section. ## 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] @@ -69,7 +69,7 @@ In the example above, the inline shortcode is executed twice: once upon definiti

Today is Thursday, January 30, 2025

``` -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. @@ -179,7 +179,7 @@ Hugo processes the shortcode before the page content is rendered by the Markdown 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 }} diff --git a/docs/content/en/content-management/taxonomies.md b/docs/content/en/content-management/taxonomies.md index 6caf70b0c..12d96170e 100644 --- a/docs/content/en/content-management/taxonomies.md +++ b/docs/content/en/content-management/taxonomies.md @@ -32,7 +32,7 @@ Let's assume you are making a website about movies. You may want to include the - 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 @@ -71,10 +71,10 @@ Moonrise Kingdom <- Value ### 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 @@ -92,7 +92,7 @@ categories = ['Category A','Category B'] ## 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. @@ -139,7 +139,7 @@ title = "John Smith" 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" }} @@ -159,7 +159,7 @@ Then create a taxonomy template specific to the "authors" taxonomy: 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" }} diff --git a/docs/content/en/content-management/urls.md b/docs/content/en/content-management/urls.md index a39afa6ef..2513614ee 100644 --- a/docs/content/en/content-management/urls.md +++ b/docs/content/en/content-management/urls.md @@ -20,7 +20,7 @@ You can change the structure and appearance of URLs with front matter values and ### `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' @@ -39,6 +39,7 @@ Set the `url` in front matter to override the entire path. Use this with either > [!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. diff --git a/docs/content/en/contribute/development.md b/docs/content/en/contribute/development.md index e2cfee4ff..5930fbf52 100644 --- a/docs/content/en/contribute/development.md +++ b/docs/content/en/contribute/development.md @@ -46,99 +46,89 @@ To build the extended or extended/deploy edition from source you must: 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 -``` +Step 4 +: Make changes. -For a bug fix: +Step 5 +: Compile and install. -```sh -git checkout -b fix/fix-some-bug-99999 -``` + To compile and install the standard edition: -### Step 4 + ```text + go install + ``` -Make changes. + To compile and install the extended edition: -### Step 5 + ```text + CGO_ENABLED=1 go install -tags extended + ``` -Compile and install. + 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 +: Test your changes: -To compile and install the extended edition: + ```text + go test ./... + ``` -```text -CGO_ENABLED=1 go install -tags extended -``` +Step 7 +: Commit your changes with a descriptive commit message: -To compile and install the extended/deploy edition: + - 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 -CGO_ENABLED=1 go install -tags extended,withdeploy -``` + For example: -### Step 6 + ```sh + git commit -m "tpl/strings: Create wrap function -Test your changes: + 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. -```text -go test ./... -``` + Fixes #99998 + Closes #99999" + ``` -### Step 7 +Step 8 +: Push the new branch to your fork of the documentation repository. -Commit your changes with a descriptive commit message: +Step 9 +: Visit the [project repository] and create a pull request (PR). -- 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. - -For example: - -```sh -git commit -m "tpl/strings: Create wrap function - -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" -``` - -### Step 8 - -Push the new branch to your fork of the documentation repository. - -### Step 9 - -Visit the [project repository] and create a pull request (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. +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 @@ -153,7 +143,7 @@ CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@latest 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: @@ -165,7 +155,7 @@ CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@master 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 diff --git a/docs/content/en/contribute/documentation.md b/docs/content/en/contribute/documentation.md index c72ddd03f..2ce2db169 100644 --- a/docs/content/en/contribute/documentation.md +++ b/docs/content/en/contribute/documentation.md @@ -70,6 +70,22 @@ Link to the [glossary] as needed and use terms consistently. Pay particular atte - "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. @@ -154,25 +170,25 @@ If quotation marks are required, prefer single quotes to double quotes when poss 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. @@ -329,8 +345,6 @@ Limiting the number of callout types helps us to use them consistently. > [!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. @@ -457,67 +471,57 @@ Set the `expiryDate` to two years from the date of deprecation, and add a brief 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 diff --git a/docs/content/en/functions/css/PostCSS.md b/docs/content/en/functions/css/PostCSS.md index 9cc698248..4dce705be 100644 --- a/docs/content/en/functions/css/PostCSS.md +++ b/docs/content/en/functions/css/PostCSS.md @@ -22,46 +22,41 @@ params: 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 -``` + ```js {file="postcss.config.js"} + module.exports = { + plugins: [ + require('autoprefixer') + ] + }; + ``` -### Step 3 + > [!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]. -Create a PostCSS configuration file in the root of your project. +Step 4 +: Place your CSS file within the `assets/css` directory. -```js {file="postcss.config.js"} -module.exports = { - plugins: [ - require('autoprefixer') - ] -}; -``` +Step 5 +: Process the resource with PostCSS: -> [!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 - -Place your CSS file within the `assets/css` directory. - -### Step 5 - -Process the resource with PostCSS: - -```go-html-template -{{ with resources.Get "css/main.css" | postCSS }} - -{{ end }} -``` + ```go-html-template + {{ with resources.Get "css/main.css" | postCSS }} + + {{ end }} + ``` ## Options diff --git a/docs/content/en/functions/css/Sass.md b/docs/content/en/functions/css/Sass.md index ae628a15f..4bce2fd06 100644 --- a/docs/content/en/functions/css/Sass.md +++ b/docs/content/en/functions/css/Sass.md @@ -122,83 +122,31 @@ Run `hugo env` to list the active transpilers. ### 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 -``` +For examples of how to install Dart Sass in a production environment, see the following workflow files: -#### 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 -``` - -#### 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 diff --git a/docs/content/en/functions/css/TailwindCSS.md b/docs/content/en/functions/css/TailwindCSS.md index 9d40ad0aa..e8514679b 100644 --- a/docs/content/en/functions/css/TailwindCSS.md +++ b/docs/content/en/functions/css/TailwindCSS.md @@ -25,86 +25,80 @@ Use the `css.TailwindCSS` function to process your Tailwind CSS files. This func ## Setup -### Step 1 +Step 1 +: Install the Tailwind CSS CLI v4.0 or later: -Install the Tailwind CSS CLI v4.0 or later: + ```sh {copy=true} + npm install --save-dev tailwindcss @tailwindcss/cli + ``` -```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. -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: -[standalone executable]: https://github.com/tailwindlabs/tailwindcss/releases/latest + {{< 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 2 +Step 3 +: Create a CSS entry file: -Add this to your site configuration: + ```css {file="assets/css/main.css" copy=true} + @import "tailwindcss"; + @source "hugo_stats.json"; + ``` -{{< 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 >}} + 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 3 +Step 4 +: Create a _partial_ template to process the CSS with the Tailwind CSS CLI: -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 }} - - {{ else }} - {{ with . | fingerprint }} - + ```go-html-template {file="layouts/_partials/css.html" copy=true} + {{ with resources.Get "css/main.css" }} + {{ $opts := dict "minify" (not hugo.IsDevelopment) }} + {{ with . | css.TailwindCSS $opts }} + {{ if hugo.IsDevelopment }} + + {{ else }} + {{ with . | fingerprint }} + + {{ end }} {{ end }} {{ end }} {{ end }} -{{ end }} -``` + ``` -### Step 5 +Step 5 +: Call the _partial_ template from your base template, deferring template execution until after all sites and output formats have been rendered: -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} - - ... - {{ with (templates.Defer (dict "key" "global")) }} - {{ partial "css.html" . }} - {{ end }} - ... - -``` + ```go-html-template {file="layouts/baseof.html" copy=true} + + ... + {{ with (templates.Defer (dict "key" "global")) }} + {{ partial "css.html" . }} + {{ end }} + ... + + ``` ## Options diff --git a/docs/content/en/functions/data/GetCSV.md b/docs/content/en/functions/data/GetCSV.md index 39c71b06c..8d3f8a7d9 100644 --- a/docs/content/en/functions/data/GetCSV.md +++ b/docs/content/en/functions/data/GetCSV.md @@ -97,7 +97,7 @@ 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/ @@ -138,7 +138,8 @@ Consider using the [`resources.GetRemote`] function with [`transform.Unmarshal`] {{ end }} ``` -[`Resources.Get`]: /methods/page/resources/ [`resources.GetRemote`]: /functions/resources/getremote/ -[`resources.Get`]: /functions/resources/get/ + + [`transform.Unmarshal`]: /functions/transform/unmarshal/ + diff --git a/docs/content/en/functions/data/GetJSON.md b/docs/content/en/functions/data/GetJSON.md index 9cdea9287..d3aafe94d 100644 --- a/docs/content/en/functions/data/GetJSON.md +++ b/docs/content/en/functions/data/GetJSON.md @@ -80,7 +80,7 @@ Add multiple headers using a slice: ## 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/ @@ -101,7 +101,7 @@ 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/ @@ -140,7 +140,8 @@ Consider using the [`resources.GetRemote`] function with [`transform.Unmarshal`] {{ end }} ``` -[`Resources.Get`]: /methods/page/resources/ [`resources.GetRemote`]: /functions/resources/getremote/ -[`resources.Get`]: /functions/resources/get/ + + [`transform.Unmarshal`]: /functions/transform/unmarshal/ + diff --git a/docs/content/en/functions/encoding/Jsonify.md b/docs/content/en/functions/encoding/Jsonify.md index 1d60dd68d..5bbbf1446 100644 --- a/docs/content/en/functions/encoding/Jsonify.md +++ b/docs/content/en/functions/encoding/Jsonify.md @@ -13,8 +13,8 @@ aliases: [/functions/jsonify] 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 }} diff --git a/docs/content/en/functions/global/page.md b/docs/content/en/functions/global/page.md index 40f6aba8f..a7672d947 100644 --- a/docs/content/en/functions/global/page.md +++ b/docs/content/en/functions/global/page.md @@ -53,9 +53,9 @@ content/ └── _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 }} @@ -71,7 +71,7 @@ My Home Page 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 @@ -83,9 +83,9 @@ Do not use the global `page` function in: 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 }}

{{ .LinkTitle }}

{{ .Summary }} diff --git a/docs/content/en/functions/go-template/block.md b/docs/content/en/functions/go-template/block.md index 383a3d72e..d603a1f89 100644 --- a/docs/content/en/functions/go-template/block.md +++ b/docs/content/en/functions/go-template/block.md @@ -21,6 +21,7 @@ and then executing it in place: ```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"} diff --git a/docs/content/en/functions/go-template/define.md b/docs/content/en/functions/go-template/define.md index 40d495bd9..e4939057f 100644 --- a/docs/content/en/functions/go-template/define.md +++ b/docs/content/en/functions/go-template/define.md @@ -43,21 +43,8 @@ Use with the [`template`] function: {{ 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"} -
This div element broke your template.
-{{ define "main" }} -

{{ .Title }}

- {{ .Content }} -{{ end }} - -``` - {{% 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 diff --git a/docs/content/en/functions/go-template/range.md b/docs/content/en/functions/go-template/range.md index 50f714140..3c50068f1 100644 --- a/docs/content/en/functions/go-template/range.md +++ b/docs/content/en/functions/go-template/range.md @@ -38,7 +38,9 @@ Within a range block: ## 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: @@ -217,3 +219,4 @@ Ranging over a non-positive integer executes the block zero times. [`break`]: /functions/go-template/break/ [`continue`]: /functions/go-template/continue/ [`else`]: /functions/go-template/else/ +[context]: /templates/introduction/#context diff --git a/docs/content/en/functions/go-template/return.md b/docs/content/en/functions/go-template/return.md index 911c0925c..e96908565 100644 --- a/docs/content/en/functions/go-template/return.md +++ b/docs/content/en/functions/go-template/return.md @@ -10,7 +10,7 @@ params: 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). @@ -21,7 +21,7 @@ A `return` statement without a value returns an empty string of type `template.H ## 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 }} diff --git a/docs/content/en/functions/go-template/template.md b/docs/content/en/functions/go-template/template.md index 903f1490a..671f95e15 100644 --- a/docs/content/en/functions/go-template/template.md +++ b/docs/content/en/functions/go-template/template.md @@ -20,7 +20,7 @@ Use the `template` function to execute a defined template: {{ 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) }} @@ -33,8 +33,8 @@ The example above can be rewritten using an inline partial template: 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" %}} diff --git a/docs/content/en/functions/go-template/try.md b/docs/content/en/functions/go-template/try.md index 6aef4da36..143810654 100644 --- a/docs/content/en/functions/go-template/try.md +++ b/docs/content/en/functions/go-template/try.md @@ -101,6 +101,7 @@ Instead of failing the build, we can catch the error and emit a warning: {{ 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] diff --git a/docs/content/en/functions/go-template/with.md b/docs/content/en/functions/go-template/with.md index c25ce3fba..7354f1608 100644 --- a/docs/content/en/functions/go-template/with.md +++ b/docs/content/en/functions/go-template/with.md @@ -57,7 +57,9 @@ Initialize a variable, scoped to the current block: ## 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: @@ -90,3 +92,4 @@ This template will render the page title as desired: {{% include "/_common/functions/go-template/text-template.md" %}} [`else`]: /functions/go-template/else/ +[context]: /templates/introduction/#context diff --git a/docs/content/en/functions/hugo/Generator.md b/docs/content/en/functions/hugo/Generator.md index c044a210c..176d8e6bf 100644 --- a/docs/content/en/functions/hugo/Generator.md +++ b/docs/content/en/functions/hugo/Generator.md @@ -11,5 +11,5 @@ params: --- ```go-html-template -{{ hugo.Generator }} → +{{ hugo.Generator }} → ``` diff --git a/docs/content/en/functions/hugo/Store.md b/docs/content/en/functions/hugo/Store.md index 08c684146..c0d5c5933 100644 --- a/docs/content/en/functions/hugo/Store.md +++ b/docs/content/en/functions/hugo/Store.md @@ -100,7 +100,7 @@ Removes the given key. ## 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: diff --git a/docs/content/en/functions/hugo/Version.md b/docs/content/en/functions/hugo/Version.md index a23bd75cd..33827737a 100644 --- a/docs/content/en/functions/hugo/Version.md +++ b/docs/content/en/functions/hugo/Version.md @@ -11,5 +11,5 @@ params: --- ```go-html-template -{{ hugo.Version }} → 0.147.9 +{{ hugo.Version }} → 0.148.0 ``` diff --git a/docs/content/en/functions/js/Babel.md b/docs/content/en/functions/js/Babel.md index d0007aaa0..488c80503 100644 --- a/docs/content/en/functions/js/Babel.md +++ b/docs/content/en/functions/js/Babel.md @@ -31,26 +31,23 @@ params: ## 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 diff --git a/docs/content/en/functions/js/Batch.md b/docs/content/en/functions/js/Batch.md index a2c8bb893..360f98656 100644 --- a/docs/content/en/functions/js/Batch.md +++ b/docs/content/en/functions/js/Batch.md @@ -158,7 +158,7 @@ import * as params from "@params"; 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" }} @@ -270,8 +270,8 @@ In a template you would typically handle one group with a given `ID` (e.g. scrip 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: @@ -291,7 +291,6 @@ console.log('entrypoints-workaround.js'); [`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 diff --git a/docs/content/en/functions/js/Build.md b/docs/content/en/functions/js/Build.md index d55220a52..79c52087d 100644 --- a/docs/content/en/functions/js/Build.md +++ b/docs/content/en/functions/js/Build.md @@ -82,6 +82,7 @@ Also note the new `params` option that can be passed from template to your JS fi ```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 diff --git a/docs/content/en/functions/openapi3/Unmarshal.md b/docs/content/en/functions/openapi3/Unmarshal.md index ca2ee93e3..ed15d4d6a 100644 --- a/docs/content/en/functions/openapi3/Unmarshal.md +++ b/docs/content/en/functions/openapi3/Unmarshal.md @@ -55,7 +55,7 @@ To list the GET and POST operations for each of the API paths: ``` > [!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. diff --git a/docs/content/en/functions/partials/Include.md b/docs/content/en/functions/partials/Include.md index 0474bf77f..dfb8873b4 100644 --- a/docs/content/en/functions/partials/Include.md +++ b/docs/content/en/functions/partials/Include.md @@ -1,6 +1,6 @@ --- 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: @@ -13,9 +13,7 @@ aliases: [/functions/partial] 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/ @@ -56,7 +54,7 @@ You can pass anything in context: a page, a page collection, a scalar value, a s {{ partial "render-student-info.html" $ctx }} ``` -Then, within the partial template: +Then, within the _partial_ template: ```go-html-template

{{ .name }} is majoring in {{ .major }}.

@@ -64,7 +62,7 @@ Then, within the partial template:

See details.

``` -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 := "" }} @@ -79,6 +77,4 @@ To return a value from a partial template, it must contain only one `return` sta See [details][`return`]. [`return`]: /functions/go-template/return/ - [breadcrumb navigation]: /content-management/sections/#ancestors-and-descendants -[details]: /functions/go-template/return/ diff --git a/docs/content/en/functions/partials/IncludeCached.md b/docs/content/en/functions/partials/IncludeCached.md index 9bf1d5384..b80aaf8a1 100644 --- a/docs/content/en/functions/partials/IncludeCached.md +++ b/docs/content/en/functions/partials/IncludeCached.md @@ -38,9 +38,9 @@ Pass additional arguments, of any data type, as needed to create unique variants {{ 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 := "" }} diff --git a/docs/content/en/functions/resources/FromString.md b/docs/content/en/functions/resources/FromString.md index bd2d894b1..c86f90cbb 100644 --- a/docs/content/en/functions/resources/FromString.md +++ b/docs/content/en/functions/resources/FromString.md @@ -22,9 +22,9 @@ Let's say you need to publish a file named "site.json" in the root of your `publ ```json { - "build_date": "2025-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" } ``` diff --git a/docs/content/en/functions/resources/GetRemote.md b/docs/content/en/functions/resources/GetRemote.md index c6f6742b3..29768eedf 100644 --- a/docs/content/en/functions/resources/GetRemote.md +++ b/docs/content/en/functions/resources/GetRemote.md @@ -15,8 +15,6 @@ The `Err` method on the returned resource was removed in v0.141.0. 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 @@ -36,26 +34,21 @@ Use the [`try`] statement instead, as shown in the [error handling] example belo The `resources.GetRemote` function takes an optional map of options. -###### body +body +: (`string`) The data you want to transmit to the server. -(`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. -###### headers +key +: (`string`) The cache key. Hugo derives the default value from the URL and options map. See [caching](#caching). -(`map[string][]string`) The collection of key-value pairs that provide additional information about the request. +method +: (`string`) The action to perform on the requested resource, typically one of `GET`, `POST`, or `HEAD`. -###### key - -(`string`) The cache key. Hugo derives the default value from the URL and options map. See [caching](#caching). - -###### method - -(`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 @@ -64,8 +57,6 @@ The `resources.GetRemote` function takes an optional map of options. > [!note] > For brevity, the examples below do not include [error handling]. -[error handling]: #error-handling - To include a header: ```go-html-template @@ -150,8 +141,6 @@ When retrieving remote data, use the [`transform.Unmarshal`] function to [unmars 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. @@ -202,8 +191,6 @@ By default, Hugo derives the cache key from the arguments passed to the function {{ $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: @@ -234,3 +221,7 @@ Note that the entry above is: [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 diff --git a/docs/content/en/functions/resources/PostProcess.md b/docs/content/en/functions/resources/PostProcess.md index d70437694..766817ff5 100644 --- a/docs/content/en/functions/resources/PostProcess.md +++ b/docs/content/en/functions/resources/PostProcess.md @@ -17,9 +17,9 @@ The `resources.PostProcess` function delays resource transformation steps until 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]. @@ -27,51 +27,51 @@ Step 1 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; + ```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: [] -}); + 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, - ] -}; -``` + 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]. + > [!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. @@ -79,17 +79,17 @@ Step 5 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 }} - - {{ else }} - {{ with . | postCSS | minify | fingerprint | resources.PostProcess }} - + ```go-html-template {copy=true} + {{ with resources.Get "css/main.css" }} + {{ if hugo.IsDevelopment }} + + {{ else }} + {{ with . | postCSS | minify | fingerprint | resources.PostProcess }} + + {{ end }} {{ end }} {{ end }} -{{ end }} -``` + ``` ## Environment variables @@ -124,7 +124,7 @@ let tailwindConfig = process.env.HUGO_FILE_TAILWIND_CONFIG_JS || './tailwind.con ## 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. diff --git a/docs/content/en/functions/templates/Current.md b/docs/content/en/functions/templates/Current.md index d2c2c9609..b82818c47 100644 --- a/docs/content/en/functions/templates/Current.md +++ b/docs/content/en/functions/templates/Current.md @@ -64,7 +64,7 @@ To visually mark where a template begins and ends execution: ### 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 }} @@ -113,7 +113,7 @@ To reverse the order of the entries, chain the `Reverse` method to the `Ancestor ### 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 }} diff --git a/docs/content/en/functions/templates/Defer.md b/docs/content/en/functions/templates/Defer.md index 16c32724e..9acb91405 100644 --- a/docs/content/en/functions/templates/Defer.md +++ b/docs/content/en/functions/templates/Defer.md @@ -14,7 +14,7 @@ aliases: [/functions/templates.defer] {{< 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 diff --git a/docs/content/en/functions/time/ParseDuration.md b/docs/content/en/functions/time/ParseDuration.md index af5d73ad5..418632fc8 100644 --- a/docs/content/en/functions/time/ParseDuration.md +++ b/docs/content/en/functions/time/ParseDuration.md @@ -11,7 +11,7 @@ params: 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`. diff --git a/docs/content/en/functions/transform/PortableText.md b/docs/content/en/functions/transform/PortableText.md index 7baba99d4..fa9a91e33 100644 --- a/docs/content/en/functions/transform/PortableText.md +++ b/docs/content/en/functions/transform/PortableText.md @@ -194,6 +194,7 @@ export const schemaTypes = [postType] 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: + {{< code-toggle file=hugo >}} [HTTPCache] [[HTTPCache.polls]] @@ -207,6 +208,7 @@ Unfortunately, Sanity's API does not support [RFC 7234](https://tools.ietf.org/h dir = ':cacheDir/:project' maxAge = "5m" {{< /code-toggle >}} + The polling above will be used when running the server/watch mode and rebuild when you push new content in Sanity. diff --git a/docs/content/en/functions/transform/ToMath.md b/docs/content/en/functions/transform/ToMath.md index 0beb8f56a..be62e8bce 100644 --- a/docs/content/en/functions/transform/ToMath.md +++ b/docs/content/en/functions/transform/ToMath.md @@ -45,14 +45,14 @@ fleqn 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`. @@ -60,10 +60,10 @@ minRuleThickness 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 - + ```html + strict : {{< new-in 0.147.6 />}} @@ -73,10 +73,7 @@ strict - `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`. @@ -95,66 +92,65 @@ The example below demonstrates error handing within a template. 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. +[passthrough extension]: /configuration/markup/#passthrough -{{< 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 = [['\(', '\)']] + {{< /code-toggle >}} -[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. -> [!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.4 -### Step 2 +[passthrough render hook]: /render-hooks/passthrough/ -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/_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 -}} -``` + ```go-html-template {file="layouts/baseof.html" copy=true} + + {{ $noop := .WordCount }} + {{ if .Page.Store.Get "hasMath" }} + + {{ end }} + + ``` -### Step 3 + 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. -In your base template, conditionally include the KaTeX CSS within the head element. +Step 4 +: Add some mathematical markup to your content, then test. -```go-html-template {file="layouts/baseof.html" copy=true} - - {{ $noop := .WordCount }} - {{ if .Page.Store.Get "hasMath" }} - - {{ end }} - -``` + ```text {file="content/example.md"} + This is an inline \(a^*=x-b^*\) equation. -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. + These are block equations: -### Step 4 + \[a^*=x-b^*\] -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^*$$ -``` + $$a^*=x-b^*$$ + ``` ## Chemistry @@ -172,6 +168,4 @@ $$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$ [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 diff --git a/docs/content/en/getting-started/directory-structure.md b/docs/content/en/getting-started/directory-structure.md index 3feecd135..d01822c96 100644 --- a/docs/content/en/getting-started/directory-structure.md +++ b/docs/content/en/getting-started/directory-structure.md @@ -196,10 +196,7 @@ my-theme/ ├── 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. diff --git a/docs/content/en/getting-started/external-learning-resources/index.md b/docs/content/en/getting-started/external-learning-resources/index.md index f36544c02..d3101be18 100644 --- a/docs/content/en/getting-started/external-learning-resources/index.md +++ b/docs/content/en/getting-started/external-learning-resources/index.md @@ -7,6 +7,9 @@ keywords: [] 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 diff --git a/docs/content/en/host-and-deploy/host-on-21yunbox.md b/docs/content/en/host-and-deploy/host-on-21yunbox.md deleted file mode 100644 index 9ef684fd8..000000000 --- a/docs/content/en/host-and-deploy/host-on-21yunbox.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -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: - | 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. diff --git a/docs/content/en/host-and-deploy/host-on-aws-amplify/index.md b/docs/content/en/host-and-deploy/host-on-aws-amplify/index.md index e2b35dbbe..4fd71f3f9 100644 --- a/docs/content/en/host-and-deploy/host-on-aws-amplify/index.md +++ b/docs/content/en/host-and-deploy/host-on-aws-amplify/index.md @@ -6,155 +6,152 @@ keywords: [] 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 +Step 1 +: Create a file named `amplify.yml` in the root of your project. -Create a file named `amplify.yml` in the root of your project. + ```sh + touch amplify.yml + ``` -```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. -### Step 2 + ```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" -Copy and paste the YAML below into the file you created. Change the application versions and time zone as needed. + # 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}" -```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 + - 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 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 + - 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 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 + # Verify installations + - echo "Verifying installations..." + - "echo Dart Sass: $(sass --version)" + - "echo Go: $(go version)" + - "echo Hugo: $(hugo version)" + - "echo Node.js: $(node --version)" - # Check installed versions - - go version - - hugo version - - node -v - - npm -v - - sass --embedded --version + # Install Node.js dependencies + - echo "Installing Node.js dependencies..." + - "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci --prefer-offline || true" - # Install 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}/**/* + ``` - # 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. -### Step 3 + ```sh + git add -A + git commit -m "Create amplify.yml" + git push + ``` -Commit and push the change to your GitHub repository. +Step 4 +: Log in to your AWS account, navigate to the [Amplify Console], then press the **Deploy an app** button. -```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 5 +: Choose a source code provider, then press the **Next** button. ![screen capture](amplify-step-05.png) -### Step 6 - -Authorize AWS Amplify to access your GitHub account. +Step 6 +: Authorize AWS Amplify to access your GitHub account. ![screen capture](amplify-step-06.png) -### Step 7 - -Select your personal account or relevant organization. +Step 7 +: Select your personal account or relevant organization. ![screen capture](amplify-step-07.png) -### Step 8 - -Authorize access to one or more repositories. +Step 8 +: Authorize access to one or more repositories. ![screen capture](amplify-step-08.png) -### Step 9 - -Select a repository and branch, then press the **Next** button. +Step 9 +: Select a repository and branch, then press the **Next** button. ![screen capture](amplify-step-09.png) -### Step 10 +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 "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 +: 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. ![screen capture](amplify-step-11.png) + +[Amplify Console]: https://console.aws.amazon.com/amplify/apps diff --git a/docs/content/en/host-and-deploy/host-on-cloudflare-pages.md b/docs/content/en/host-and-deploy/host-on-cloudflare-pages.md deleted file mode 100644 index 1c3627288..000000000 --- a/docs/content/en/host-and-deploy/host-on-cloudflare-pages.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -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/). diff --git a/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-01.png b/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-01.png new file mode 100644 index 000000000..9c7a4380d Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-01.png differ diff --git a/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-02.png b/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-02.png new file mode 100644 index 000000000..595a164ea Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-02.png differ diff --git a/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-03.png b/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-03.png new file mode 100644 index 000000000..6d4228b4a Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-03.png differ diff --git a/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-04.png b/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-04.png new file mode 100644 index 000000000..12fa0cbd8 Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-04.png differ diff --git a/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-05.png b/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-05.png new file mode 100644 index 000000000..d907844d1 Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-05.png differ diff --git a/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-06.png b/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-06.png new file mode 100644 index 000000000..33010b11d Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-06.png differ diff --git a/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-07.png b/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-07.png new file mode 100644 index 000000000..10ed1c7c6 Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-07.png differ diff --git a/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-08.png b/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-08.png new file mode 100644 index 000000000..396387314 Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-08.png differ diff --git a/docs/content/en/host-and-deploy/host-on-cloudflare/index.md b/docs/content/en/host-and-deploy/host-on-cloudflare/index.md new file mode 100644 index 000000000..018c50f0a --- /dev/null +++ b/docs/content/en/host-and-deploy/host-on-cloudflare/index.md @@ -0,0 +1,166 @@ +--- +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. + + ![screen capture](cloudflare-01.png) + +Step 5 +: On the "Workers" tab, press the **Get started** button to the right of the "Import a repository" item. + + ![screen capture](cloudflare-02.png) + +Step 6 +: Connect to GitHub. + + ![screen capture](cloudflare-03.png) + +Step 7 +: Select the GitHub account where you want to install the Cloudflare Workers and Pages application. + + ![screen capture](cloudflare-04.png) + +Step 8 +: Authorize the Cloudflare Workers and Pages application to access all repositories or only select repositories, then press the **Install & Authorize** button. + + ![screen capture](cloudflare-05.png) + + 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. + + ![screen capture](cloudflare-02.png) + +Step 10 +: Select the repository to import. + + ![screen capture](cloudflare-06.png) + +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. + + ![screen capture](cloudflare-07.png) + +Step 12 +: Wait for the site to build and deploy, then visit your site. + + ![screen capture](cloudflare-08.png) + +In the future, whenever you push a change from your local Git repository, Cloudflare will rebuild and deploy your site. diff --git a/docs/content/en/host-and-deploy/host-on-codeberg-pages.md b/docs/content/en/host-and-deploy/host-on-codeberg-pages.md index 2a881f718..3c7e7a847 100644 --- a/docs/content/en/host-and-deploy/host-on-codeberg-pages.md +++ b/docs/content/en/host-and-deploy/host-on-codeberg-pages.md @@ -51,9 +51,11 @@ git remote add origin https://codeberg.org//pages.git git push -u origin main ``` -## Automated deployment 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]. @@ -78,7 +80,7 @@ git push -u origin main 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. @@ -109,7 +111,7 @@ jobs: 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 @@ -160,21 +162,25 @@ jobs: The second file implements a more complex scenario: having your website sources in one repository and the resulting static website in another repository (in this case, `pages`). If you want Codeberg to make your website available at the root of your pages subdomain (`https://.codeberg.page/`), you have to push that website to the default branch of your repository named `pages`. Since this action involves more than one repository, it will require a bit more preparation: + 1. Create the target repository. Name it `pages`. -2. Generate a new SSH key. *Do not* use any of your own SSH keys for this, but generate one for this specific task only. On Linux, BSD, and, likely, other operating systems, you can open a terminal emulator and run the following command to generate the key: +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` | `/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) | + This will generate two files in your current directory: `pagesbuild` (private key) and `pagesbuild.pub` (public key). + +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`|`/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: @@ -195,7 +201,7 @@ jobs: 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 @@ -249,6 +255,27 @@ jobs: 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/) diff --git a/docs/content/en/host-and-deploy/host-on-firebase.md b/docs/content/en/host-and-deploy/host-on-firebase.md index 267c8d127..064ecadad 100644 --- a/docs/content/en/host-and-deploy/host-on-firebase.md +++ b/docs/content/en/host-and-deploy/host-on-firebase.md @@ -43,22 +43,22 @@ From here: 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: @@ -66,7 +66,7 @@ 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 . Don't forget to update your static pages before push! diff --git a/docs/content/en/host-and-deploy/host-on-github-pages/gh-pages-1.png b/docs/content/en/host-and-deploy/host-on-github-pages/gh-pages-01.png similarity index 100% rename from docs/content/en/host-and-deploy/host-on-github-pages/gh-pages-1.png rename to docs/content/en/host-and-deploy/host-on-github-pages/gh-pages-01.png diff --git a/docs/content/en/host-and-deploy/host-on-github-pages/gh-pages-2.png b/docs/content/en/host-and-deploy/host-on-github-pages/gh-pages-02.png similarity index 100% rename from docs/content/en/host-and-deploy/host-on-github-pages/gh-pages-2.png rename to docs/content/en/host-and-deploy/host-on-github-pages/gh-pages-02.png diff --git a/docs/content/en/host-and-deploy/host-on-github-pages/gh-pages-3.png b/docs/content/en/host-and-deploy/host-on-github-pages/gh-pages-03.png similarity index 100% rename from docs/content/en/host-and-deploy/host-on-github-pages/gh-pages-3.png rename to docs/content/en/host-and-deploy/host-on-github-pages/gh-pages-03.png diff --git a/docs/content/en/host-and-deploy/host-on-github-pages/gh-pages-4.png b/docs/content/en/host-and-deploy/host-on-github-pages/gh-pages-04.png similarity index 100% rename from docs/content/en/host-and-deploy/host-on-github-pages/gh-pages-4.png rename to docs/content/en/host-and-deploy/host-on-github-pages/gh-pages-04.png diff --git a/docs/content/en/host-and-deploy/host-on-github-pages/gh-pages-5.png b/docs/content/en/host-and-deploy/host-on-github-pages/gh-pages-05.png similarity index 100% rename from docs/content/en/host-and-deploy/host-on-github-pages/gh-pages-5.png rename to docs/content/en/host-and-deploy/host-on-github-pages/gh-pages-05.png diff --git a/docs/content/en/host-and-deploy/host-on-github-pages/index.md b/docs/content/en/host-and-deploy/host-on-github-pages/index.md index 165c9934c..dd4039dd8 100644 --- a/docs/content/en/host-and-deploy/host-on-github-pages/index.md +++ b/docs/content/en/host-and-deploy/host-on-github-pages/index.md @@ -6,14 +6,6 @@ keywords: [] 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. @@ -21,194 +13,177 @@ There are three types of GitHub Pages sites: project, user, and organization. Pr > [!note] > See the [GitHub Pages documentation] to understand the requirements for repository ownership and naming. +## Prerequisites + +Please complete the following tasks before continuing: + +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 -### Step 1 +Step 1 +: Visit your GitHub repository. From the main menu choose **Settings** > **Pages**. In the center of your screen you will see this: -Create a GitHub repository. + ![screen capture](gh-pages-01.png) -### Step 2 + Change the **Source** to `GitHub Actions`. The change is immediate; you do not have to press a Save button. -Push your local repository to GitHub. + ![screen capture](gh-pages-02.png) -### Step 3 +Step 2 +: In your site configuration, change the location of the image cache to the [`cacheDir`] as shown below: -Visit your GitHub repository. From the main menu choose **Settings** > **Pages**. In the center of your screen you will see this: + {{< code-toggle file=hugo copy=true >}} + [caches.images] + dir = ":cacheDir/images" + {{< /code-toggle >}} -![screen capture](gh-pages-1.png) -{style="max-width: 280px"} + See [configure file caches] for more information. -### Step 4 +Step 3 +: Create a file named `hugo.yaml` in a directory named `.github/workflows`. -Change the **Source** to `GitHub Actions`. The change is immediate; you do not have to press a Save button. + ```text + mkdir -p .github/workflows + touch .github/workflows/hugo.yaml + ``` -![screen capture](gh-pages-2.png) -{style="max-width: 280px"} +Step 4 +: Copy and paste the YAML below into the file you created. -### Step 5 + ```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 + ``` -In your site configuration, change the location of the image cache to the [`cacheDir`] as shown below: +Step 5 +: Commit the changes to your local Git repository and push to your GitHub repository. -{{< code-toggle file=hugo >}} -[caches.images] -dir = ":cacheDir/images" -{{< /code-toggle >}} +Step 6 +: From GitHub's main menu, choose **Actions**. You will see something like this: -See [configure file caches] for more information. + ![screen capture](gh-pages-03.png) -### Step 6 +Step 7 +: When GitHub has finished building and deploying your site, the color of the status indicator will change to green. -Create a file named `hugo.yaml` in a directory named `.github/workflows`. + ![screen capture](gh-pages-04.png) -```text -mkdir -p .github/workflows -touch .github/workflows/hugo.yaml -``` +Step 8 +: Click on the commit message as shown above. Under the deploy step, you will see a link to your live site. -### Step 7 + ![screen capture](gh-pages-05.png) -> [!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: - -![screen capture](gh-pages-3.png) -{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. - -![screen capture](gh-pages-4.png) -{style="max-width: 350px"} - -### Step 11 - -Click on the commit message as shown above. You will see this: - -![screen capture](gh-pages-5.png) -{style="max-width: 611px"} - -Under the deploy step, you will see a link to your live site. - -In the future, whenever you push a change from your local repository, GitHub will rebuild your site and deploy the changes. +In the future, whenever you push a change from your local Git repository, GitHub Pages will rebuild and deploy your site. ## Customize the workflow @@ -227,11 +202,7 @@ You may remove this step if your site, themes, and modules do not transpile Sass - [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/ +[`cacheDir`]: /configuration/all/#cachedir +[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 -[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/ diff --git a/docs/content/en/host-and-deploy/host-on-gitlab-pages.md b/docs/content/en/host-and-deploy/host-on-gitlab-pages.md index cf4220888..c43303804 100644 --- a/docs/content/en/host-and-deploy/host-on-gitlab-pages.md +++ b/docs/content/en/host-and-deploy/host-on-gitlab-pages.md @@ -23,44 +23,81 @@ Define your [CI/CD](g) jobs by creating a `.gitlab-ci.yml` file in the root of y ```yaml {file=".gitlab-ci.yml" copy=true} variables: - DART_SASS_VERSION: 1.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 @@ -70,7 +107,7 @@ pages: ## 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 diff --git a/docs/content/en/host-and-deploy/host-on-keycdn/index.md b/docs/content/en/host-and-deploy/host-on-keycdn/index.md deleted file mode 100644 index 828e250c6..000000000 --- a/docs/content/en/host-and-deploy/host-on-keycdn/index.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -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. - -![Screenshot of KeyCDN's pull zone creation page](keycdn-pull-zone.png) - -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: - -![Screenshot of setting the Zone ID secret variable](secret-zone-id.png) - -While the Secret Variable for your API Key will look similar to: - -![Screenshot of setting the API Key secret variable](secret-api-key.png) - -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/). diff --git a/docs/content/en/host-and-deploy/host-on-keycdn/keycdn-pull-zone.png b/docs/content/en/host-and-deploy/host-on-keycdn/keycdn-pull-zone.png deleted file mode 100644 index 7cde4a6a2..000000000 Binary files a/docs/content/en/host-and-deploy/host-on-keycdn/keycdn-pull-zone.png and /dev/null differ diff --git a/docs/content/en/host-and-deploy/host-on-keycdn/secret-api-key.png b/docs/content/en/host-and-deploy/host-on-keycdn/secret-api-key.png deleted file mode 100644 index ad99341d5..000000000 Binary files a/docs/content/en/host-and-deploy/host-on-keycdn/secret-api-key.png and /dev/null differ diff --git a/docs/content/en/host-and-deploy/host-on-keycdn/secret-zone-id.png b/docs/content/en/host-and-deploy/host-on-keycdn/secret-zone-id.png deleted file mode 100644 index 2e5cf5f41..000000000 Binary files a/docs/content/en/host-and-deploy/host-on-keycdn/secret-zone-id.png and /dev/null differ diff --git a/docs/content/en/host-and-deploy/host-on-netlify/index.md b/docs/content/en/host-and-deploy/host-on-netlify/index.md index 61ac15da8..cc0bf6b2b 100644 --- a/docs/content/en/host-and-deploy/host-on-netlify/index.md +++ b/docs/content/en/host-and-deploy/host-on-netlify/index.md @@ -6,141 +6,125 @@ keywords: [] 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 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 - -Select your deployment method. +Step 2 +: Select your deployment method. ![screen capture](netlify-step-02.png) -### Step 3 +Step 3 +: Authorize Netlify to connect with your GitHub account by pressing the **Authorize Netlify** button. -Authorize Netlify to connect with your GitHub account by pressing the **Authorize Netlify** button. + ![screen capture](netlify-step-03.png) -![screen capture](netlify-step-03.png) +Step 4 +: Press the **Configure Netlify on GitHub** button. -### Step 4 + ![screen capture](netlify-step-04.png) -Press the **Configure Netlify on GitHub** button. +Step 5 +: Install the Netlify app by selecting your GitHub account. -![screen capture](netlify-step-04.png) + ![screen capture](netlify-step-05.png) -### Step 5 +Step 6 +: Press the **Install** button. -Install the Netlify app by selecting your GitHub account. + ![screen capture](netlify-step-06.png) -![screen capture](netlify-step-05.png) +Step 7 +: Click on the site's repository from the list. -### Step 6 + ![screen capture](netlify-step-07.png) -Press the **Install** button. +Step 8 +: Set the site name and branch from which to deploy. -![screen capture](netlify-step-06.png) + ![screen capture](netlify-step-08.png) -### Step 7 +Step 9 +: Define the build settings, press the **Add environment variables** button, then press the **New variable** button. -Click on the site's repository from the list. + ![screen capture](netlify-step-09.png) -![screen capture](netlify-step-07.png) +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 8 + ![screen capture](netlify-step-10.png) -Set the site name and branch from which to deploy. +Step 11 +: Press the "Deploy my new site" button at the bottom of the page. -![screen capture](netlify-step-08.png) + ![screen capture](netlify-step-11.png) -### Step 9 +Step 12 +: At the bottom of the screen, wait for the deploy to complete, then click on the deploy log entry. -Define the build settings, press the **Add environment variables** button, then press the **New variable** button. + ![screen capture](netlify-step-12.png) -![screen capture](netlify-step-09.png) +Step 13 +: Press the **Open production deploy** button to view the live site. -### Step 10 - -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 - -![screen capture](netlify-step-10.png) - -### Step 11 - -Press the "Deploy my new site" button at the bottom of the page. - -![screen capture](netlify-step-11.png) - -### Step 12 - -At the bottom of the screen, wait for the deploy to complete, then click on the deploy log entry. - -![screen capture](netlify-step-12.png) - -### Step 13 - -Press the **Open production deploy** button to view the live site. - -![screen capture](netlify-step-13.png) + ![screen capture](netlify-step-13.png) ## 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}" """ ``` diff --git a/docs/content/en/host-and-deploy/host-on-render.md b/docs/content/en/host-and-deploy/host-on-render.md deleted file mode 100644 index c4495c4b1..000000000 --- a/docs/content/en/host-and-deploy/host-on-render.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -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/ diff --git a/docs/content/en/host-and-deploy/host-on-render/index.md b/docs/content/en/host-and-deploy/host-on-render/index.md new file mode 100644 index 000000000..f52e09280 --- /dev/null +++ b/docs/content/en/host-and-deploy/host-on-render/index.md @@ -0,0 +1,170 @@ +--- +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. + + ![screen capture](render-01.png) + +Step 5 +: Press the **GitHub** button to connect to your GitHub account. + + ![screen capture](render-02.png) + +Step 6 +: Press the **Authorize Render** button to allow the Render application to access your GitHub account. + + ![screen capture](render-03.png) + +Step 7 +: Select the GitHub account where you want to install the Render application. + + ![screen capture](render-04.png) + +Step 8 +: Authorize the Render application to access all repositories or only select repositories, then press the **Install** button. + +![screen capture](render-05.png) + +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. + + ![screen capture](render-06.png) + +Step 10 +: Enter a unique name for your Blueprint, then press the **Deploy Blueprint** button at the bottom of the page. + + ![screen capture](render-07.png) + +Step 11 +: Wait for the site to build and deploy, then click on the "Resources" link on the left side of the page. + + ![screen capture](render-08.png) + +Step 12 +: Click on the link to the static site resource. + + ![screen capture](render-09.png) + +Step 13 +: Click on the link to your published site. + + ![screen capture](render-10.png) + +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/ diff --git a/docs/content/en/host-and-deploy/host-on-render/render-01.png b/docs/content/en/host-and-deploy/host-on-render/render-01.png new file mode 100644 index 000000000..b325a679c Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-render/render-01.png differ diff --git a/docs/content/en/host-and-deploy/host-on-render/render-02.png b/docs/content/en/host-and-deploy/host-on-render/render-02.png new file mode 100644 index 000000000..aa8753536 Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-render/render-02.png differ diff --git a/docs/content/en/host-and-deploy/host-on-render/render-03.png b/docs/content/en/host-and-deploy/host-on-render/render-03.png new file mode 100644 index 000000000..731d8ff26 Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-render/render-03.png differ diff --git a/docs/content/en/host-and-deploy/host-on-render/render-04.png b/docs/content/en/host-and-deploy/host-on-render/render-04.png new file mode 100644 index 000000000..94e5ea87b Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-render/render-04.png differ diff --git a/docs/content/en/host-and-deploy/host-on-render/render-05.png b/docs/content/en/host-and-deploy/host-on-render/render-05.png new file mode 100644 index 000000000..05707092c Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-render/render-05.png differ diff --git a/docs/content/en/host-and-deploy/host-on-render/render-06.png b/docs/content/en/host-and-deploy/host-on-render/render-06.png new file mode 100644 index 000000000..7b0076139 Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-render/render-06.png differ diff --git a/docs/content/en/host-and-deploy/host-on-render/render-07.png b/docs/content/en/host-and-deploy/host-on-render/render-07.png new file mode 100644 index 000000000..2a645d13a Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-render/render-07.png differ diff --git a/docs/content/en/host-and-deploy/host-on-render/render-08.png b/docs/content/en/host-and-deploy/host-on-render/render-08.png new file mode 100644 index 000000000..1dc75ae6c Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-render/render-08.png differ diff --git a/docs/content/en/host-and-deploy/host-on-render/render-09.png b/docs/content/en/host-and-deploy/host-on-render/render-09.png new file mode 100644 index 000000000..48e9404a9 Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-render/render-09.png differ diff --git a/docs/content/en/host-and-deploy/host-on-render/render-10.png b/docs/content/en/host-and-deploy/host-on-render/render-10.png new file mode 100644 index 000000000..4df0dcffd Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-render/render-10.png differ diff --git a/docs/content/en/host-and-deploy/host-on-vercel/index.md b/docs/content/en/host-and-deploy/host-on-vercel/index.md new file mode 100644 index 000000000..8d402cb87 --- /dev/null +++ b/docs/content/en/host-and-deploy/host-on-vercel/index.md @@ -0,0 +1,165 @@ +--- +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. + + ![screen capture](vercel-01.png) + +Step 5 +: Press the "Continue with GitHub" button. + + ![screen capture](vercel-02.png) + +Step 6 +: Press the **Authorize Vercel** button to allow the Vercel application to access your GitHub account. + + ![screen capture](vercel-03.png) + +Step 7 +: Press the **Install** button to install the Vercel application. + + ![screen capture](vercel-04.png) + +Step 8 +: Select the GitHub account where you want to install the Vercel application. + + ![screen capture](vercel-05.png) + +Step 9 +: Authorize the Vercel application to access all repositories or only select repositories, then press the **Install** button. + + ![screen capture](vercel-06.png) + + 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. + + ![screen capture](vercel-07.png) + +Step 11 +: On the "New Project" page, leave the settings at their default values and press the **Deploy** button. + + ![screen capture](vercel-08.png) + +Step 12 +: When the deployment completes, press the **Continue to Dashboard" button at the bottom of the page. + + ![screen capture](vercel-09.png) + +Step 13 +: On the "Production Deployment" page, click on the link to your published site. + + ![screen capture](vercel-10.png) + +In the future, whenever you push a change from your local Git repository, Vercel will rebuild and deploy your site. diff --git a/docs/content/en/host-and-deploy/host-on-vercel/vercel-01.png b/docs/content/en/host-and-deploy/host-on-vercel/vercel-01.png new file mode 100644 index 000000000..dd0215d0c Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-vercel/vercel-01.png differ diff --git a/docs/content/en/host-and-deploy/host-on-vercel/vercel-02.png b/docs/content/en/host-and-deploy/host-on-vercel/vercel-02.png new file mode 100644 index 000000000..ef3a788ae Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-vercel/vercel-02.png differ diff --git a/docs/content/en/host-and-deploy/host-on-vercel/vercel-03.png b/docs/content/en/host-and-deploy/host-on-vercel/vercel-03.png new file mode 100644 index 000000000..a86ba36d4 Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-vercel/vercel-03.png differ diff --git a/docs/content/en/host-and-deploy/host-on-vercel/vercel-04.png b/docs/content/en/host-and-deploy/host-on-vercel/vercel-04.png new file mode 100644 index 000000000..cbd0388d5 Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-vercel/vercel-04.png differ diff --git a/docs/content/en/host-and-deploy/host-on-vercel/vercel-05.png b/docs/content/en/host-and-deploy/host-on-vercel/vercel-05.png new file mode 100644 index 000000000..4ae341aa5 Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-vercel/vercel-05.png differ diff --git a/docs/content/en/host-and-deploy/host-on-vercel/vercel-06.png b/docs/content/en/host-and-deploy/host-on-vercel/vercel-06.png new file mode 100644 index 000000000..3b34cd44c Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-vercel/vercel-06.png differ diff --git a/docs/content/en/host-and-deploy/host-on-vercel/vercel-07.png b/docs/content/en/host-and-deploy/host-on-vercel/vercel-07.png new file mode 100644 index 000000000..ec4355b85 Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-vercel/vercel-07.png differ diff --git a/docs/content/en/host-and-deploy/host-on-vercel/vercel-08.png b/docs/content/en/host-and-deploy/host-on-vercel/vercel-08.png new file mode 100644 index 000000000..c7fa13d0d Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-vercel/vercel-08.png differ diff --git a/docs/content/en/host-and-deploy/host-on-vercel/vercel-09.png b/docs/content/en/host-and-deploy/host-on-vercel/vercel-09.png new file mode 100644 index 000000000..35ae55748 Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-vercel/vercel-09.png differ diff --git a/docs/content/en/host-and-deploy/host-on-vercel/vercel-10.png b/docs/content/en/host-and-deploy/host-on-vercel/vercel-10.png new file mode 100644 index 000000000..5fdd0aab6 Binary files /dev/null and b/docs/content/en/host-and-deploy/host-on-vercel/vercel-10.png differ diff --git a/docs/content/en/hugo-pipes/introduction.md b/docs/content/en/hugo-pipes/introduction.md index d1b93094f..fa9493f20 100755 --- a/docs/content/en/hugo-pipes/introduction.md +++ b/docs/content/en/hugo-pipes/introduction.md @@ -63,7 +63,7 @@ For improved readability, the Hugo Pipes examples of this documentation will be ## 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: diff --git a/docs/content/en/installation/bsd.md b/docs/content/en/installation/bsd.md index 2f6519e6d..a4f31bd5f 100644 --- a/docs/content/en/installation/bsd.md +++ b/docs/content/en/installation/bsd.md @@ -66,7 +66,7 @@ doas pkg_add hugo ## 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: diff --git a/docs/content/en/installation/linux.md b/docs/content/en/installation/linux.md index 591bf0818..babb759ea 100644 --- a/docs/content/en/installation/linux.md +++ b/docs/content/en/installation/linux.md @@ -174,7 +174,7 @@ sudo xbps-install -S hugo ## 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: diff --git a/docs/content/en/installation/macos.md b/docs/content/en/installation/macos.md index a873b512a..0f1fc0d27 100644 --- a/docs/content/en/installation/macos.md +++ b/docs/content/en/installation/macos.md @@ -34,9 +34,9 @@ sudo port install hugo ## 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: diff --git a/docs/content/en/installation/windows.md b/docs/content/en/installation/windows.md index a5920d45f..0b7d89f6e 100644 --- a/docs/content/en/installation/windows.md +++ b/docs/content/en/installation/windows.md @@ -58,9 +58,9 @@ winget uninstall --name "Hugo (Extended)" ## 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: diff --git a/docs/content/en/methods/page/AllTranslations.md b/docs/content/en/methods/page/AllTranslations.md index 62117b429..ed92cd482 100644 --- a/docs/content/en/methods/page/AllTranslations.md +++ b/docs/content/en/methods/page/AllTranslations.md @@ -1,6 +1,6 @@ --- 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: diff --git a/docs/content/en/methods/page/Data.md b/docs/content/en/methods/page/Data.md index bb88dbde6..387422901 100644 --- a/docs/content/en/methods/page/Data.md +++ b/docs/content/en/methods/page/Data.md @@ -38,7 +38,7 @@ content/ ## 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. @@ -68,7 +68,7 @@ Learn more about [taxonomy templates]. ## 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. diff --git a/docs/content/en/methods/page/Date.md b/docs/content/en/methods/page/Date.md index b6c2042c2..21bf03445 100644 --- a/docs/content/en/methods/page/Date.md +++ b/docs/content/en/methods/page/Date.md @@ -29,6 +29,5 @@ In the example above we explicitly set the date in front matter. With Hugo's def [`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 diff --git a/docs/content/en/methods/page/GitInfo.md b/docs/content/en/methods/page/GitInfo.md index 90dc3870a..2b620103e 100644 --- a/docs/content/en/methods/page/GitInfo.md +++ b/docs/content/en/methods/page/GitInfo.md @@ -5,7 +5,7 @@ categories: [] keywords: [] params: functions_and_methods: - returnType: source.GitInfo + returnType: '*gitmap.GitInfo' signatures: [PAGE.GitInfo] --- @@ -16,7 +16,7 @@ The `GitInfo` method on a `Page` object returns an object with additional method ## 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: @@ -119,7 +119,9 @@ hugo --enableGitInfo ### Ancestors -(`*source.GitInfo`) The file-filtered ancestor commits, if any. +(`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 }} @@ -129,9 +131,19 @@ hugo --enableGitInfo {{ end }} ``` +To reverse the order: + +```go-html-template +{{ with .GitInfo }} + {{ range .Ancestors.Reverse | first 5 }} + {{ .CommitDate.Format "2006-01-02" }}: {{ .Subject }} + {{ end }} +{{ end }} +``` + ### Parent -(`*source.GitInfo`) The first file-filtered ancestor commit, if any. +(`*gitmap.GitInfo`) The first file-filtered ancestor commit, if any. ## Last modified date @@ -141,26 +153,32 @@ You can change this behavior in your [site configuration]. ## 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. -Some providers perform deep clones by default, others allow you to configure the clone depth, and some only perform shallow clones. +While some providers perform a deep clone by default, others require you to configure the depth yourself. -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 +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] -[^1]: To configure a Cloudflare Pages site for deep cloning, run `git fetch --unshallow` before building the site. +[^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: -[^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). + ```text + if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then + git fetch --unshallow + fi + ``` -[^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). +[^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]: 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 diff --git a/docs/content/en/methods/page/Page.md b/docs/content/en/methods/page/Page.md index 01abb3103..b7bdf3558 100644 --- a/docs/content/en/methods/page/Page.md +++ b/docs/content/en/methods/page/Page.md @@ -9,25 +9,25 @@ params: 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. diff --git a/docs/content/en/methods/page/Paginate.md b/docs/content/en/methods/page/Paginate.md index 7792980e6..337811240 100644 --- a/docs/content/en/methods/page/Paginate.md +++ b/docs/content/en/methods/page/Paginate.md @@ -18,7 +18,7 @@ By default, the number of elements on each pager is determined by your [site con > > 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" }} @@ -40,8 +40,8 @@ In the example above, we: > [!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 diff --git a/docs/content/en/methods/page/Paginator.md b/docs/content/en/methods/page/Paginator.md index 1518ac95d..02b5d5719 100644 --- a/docs/content/en/methods/page/Paginator.md +++ b/docs/content/en/methods/page/Paginator.md @@ -13,7 +13,7 @@ Pagination is the process of splitting a list page into two or more pagers, wher 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 }} @@ -32,9 +32,9 @@ In the example above, the embedded pagination template creates navigation links > [!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/ diff --git a/docs/content/en/methods/page/Path.md b/docs/content/en/methods/page/Path.md index db4e7d629..df565f716 100644 --- a/docs/content/en/methods/page/Path.md +++ b/docs/content/en/methods/page/Path.md @@ -87,10 +87,10 @@ Methods|Functions|Shortcodes :--|:--|:-- [`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. diff --git a/docs/content/en/methods/page/Render.md b/docs/content/en/methods/page/Render.md index 4ee09fb6e..cd24419c2 100644 --- a/docs/content/en/methods/page/Render.md +++ b/docs/content/en/methods/page/Render.md @@ -23,9 +23,9 @@ In the example above, note that the template ("summary") is identified by its fi 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: diff --git a/docs/content/en/methods/page/RenderShortcodes.md b/docs/content/en/methods/page/RenderShortcodes.md index 81a78b04b..e440302dc 100644 --- a/docs/content/en/methods/page/RenderShortcodes.md +++ b/docs/content/en/methods/page/RenderShortcodes.md @@ -9,7 +9,7 @@ params: 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: diff --git a/docs/content/en/methods/page/Store.md b/docs/content/en/methods/page/Store.md index 0b1049b0a..c5ad6b316 100644 --- a/docs/content/en/methods/page/Store.md +++ b/docs/content/en/methods/page/Store.md @@ -18,7 +18,7 @@ Use the `Store` method on a `Page` object to create a [scratch pad](g) to store ## 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: diff --git a/docs/content/en/methods/page/Translations.md b/docs/content/en/methods/page/Translations.md index 4bab9fe11..c342a8618 100644 --- a/docs/content/en/methods/page/Translations.md +++ b/docs/content/en/methods/page/Translations.md @@ -1,6 +1,6 @@ --- 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: diff --git a/docs/content/en/methods/resource/Content.md b/docs/content/en/methods/resource/Content.md index 2c2c12d3a..ff2ad6de8 100644 --- a/docs/content/en/methods/resource/Content.md +++ b/docs/content/en/methods/resource/Content.md @@ -11,7 +11,7 @@ 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/ diff --git a/docs/content/en/methods/resource/Data.md b/docs/content/en/methods/resource/Data.md index 0709ca50a..01b22823d 100644 --- a/docs/content/en/methods/resource/Data.md +++ b/docs/content/en/methods/resource/Data.md @@ -11,8 +11,6 @@ params: 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 diff --git a/docs/content/en/methods/resource/Name.md b/docs/content/en/methods/resource/Name.md index c678c96c9..3331bb50d 100644 --- a/docs/content/en/methods/resource/Name.md +++ b/docs/content/en/methods/resource/Name.md @@ -77,6 +77,7 @@ content/ {{ .Name }} → images/Sunrise in Bryce Canyon.jpg {{ end }} ``` + ## Remote resource With a [remote resource](g), the `Name` method returns a hashed file name. diff --git a/docs/content/en/methods/shortcode/IsNamedParams.md b/docs/content/en/methods/shortcode/IsNamedParams.md index c95398313..0574128ec 100644 --- a/docs/content/en/methods/shortcode/IsNamedParams.md +++ b/docs/content/en/methods/shortcode/IsNamedParams.md @@ -11,7 +11,7 @@ params: 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 }} diff --git a/docs/content/en/methods/shortcode/Ordinal.md b/docs/content/en/methods/shortcode/Ordinal.md index 4c32705c1..b16758952 100644 --- a/docs/content/en/methods/shortcode/Ordinal.md +++ b/docs/content/en/methods/shortcode/Ordinal.md @@ -47,6 +47,6 @@ Hugo renders the page to: ``` > [!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/ diff --git a/docs/content/en/methods/site/GetPage.md b/docs/content/en/methods/site/GetPage.md index 2a3bd7d59..34f531720 100644 --- a/docs/content/en/methods/site/GetPage.md +++ b/docs/content/en/methods/site/GetPage.md @@ -34,9 +34,9 @@ content/ └── _index.md ``` -This home template: +This _home_ template: -```go-html-template +```go-html-template {file="layouts/home.html"} {{ with .Site.GetPage "/works/paintings" }}
    {{ range .Pages }} @@ -57,7 +57,7 @@ Is rendered to: 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 @@ -94,9 +94,9 @@ content/ └── _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" }} diff --git a/docs/content/en/methods/site/MainSections.md b/docs/content/en/methods/site/MainSections.md index bee4f2d57..6a0dbdc74 100644 --- a/docs/content/en/methods/site/MainSections.md +++ b/docs/content/en/methods/site/MainSections.md @@ -45,9 +45,9 @@ Template: 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 }}

    {{ .LinkTitle }}

    {{ end }} diff --git a/docs/content/en/methods/site/Menus.md b/docs/content/en/methods/site/Menus.md index 398a9b022..0c8509e92 100644 --- a/docs/content/en/methods/site/Menus.md +++ b/docs/content/en/methods/site/Menus.md @@ -79,7 +79,7 @@ When viewing the "books" page, the result is: ``` -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. diff --git a/docs/content/en/methods/site/Store.md b/docs/content/en/methods/site/Store.md index 7dcf7d095..6c6d57a90 100644 --- a/docs/content/en/methods/site/Store.md +++ b/docs/content/en/methods/site/Store.md @@ -100,7 +100,7 @@ Removes the given key. ## 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: diff --git a/docs/content/en/methods/site/Taxonomies.md b/docs/content/en/methods/site/Taxonomies.md index 857bfd01d..ab28aff1d 100644 --- a/docs/content/en/methods/site/Taxonomies.md +++ b/docs/content/en/methods/site/Taxonomies.md @@ -11,6 +11,7 @@ params: Conceptually, the `Taxonomies` method on a `Site` object returns a data structure such as: + {{< code-toggle file=hugo >}} taxonomy a: - term 1: @@ -25,6 +26,7 @@ taxonomy b: - page 1 - page 2 {{< /code-toggle >}} + For example, on a book review site you might create two taxonomies; one for genres and another for authors. @@ -50,6 +52,7 @@ content/ Conceptually, the taxonomies data structure looks like: + {{< code-toggle file=hugo >}} genres: - suspense: @@ -68,6 +71,7 @@ authors: - jausten: - Pride and Prejudice {{< /code-toggle >}} + To list the "suspense" books: @@ -138,6 +142,7 @@ The following example displays all terms in a site's tags taxonomy: {{ end }}
``` + 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"} diff --git a/docs/content/en/methods/time/Round.md b/docs/content/en/methods/time/Round.md index 816d41b44..afda0e294 100644 --- a/docs/content/en/methods/time/Round.md +++ b/docs/content/en/methods/time/Round.md @@ -15,7 +15,7 @@ The `Round` method operates on TIME as an absolute duration since the [zero time ```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 ``` diff --git a/docs/content/en/methods/time/Truncate.md b/docs/content/en/methods/time/Truncate.md index b797afec0..b90c3847f 100644 --- a/docs/content/en/methods/time/Truncate.md +++ b/docs/content/en/methods/time/Truncate.md @@ -13,7 +13,7 @@ The `Truncate` method operates on TIME as an absolute duration since the [zero t ```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 ``` diff --git a/docs/content/en/quick-reference/glossary/raw-string-literal.md b/docs/content/en/quick-reference/glossary/raw-string-literal.md index 7465c6837..a3ceabe10 100644 --- a/docs/content/en/quick-reference/glossary/raw-string-literal.md +++ b/docs/content/en/quick-reference/glossary/raw-string-literal.md @@ -3,4 +3,4 @@ title: raw string literal 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. diff --git a/docs/content/en/quick-reference/syntax-highlighting-styles.md b/docs/content/en/quick-reference/syntax-highlighting-styles.md index 14b313cbc..76aa77bf4 100644 --- a/docs/content/en/quick-reference/syntax-highlighting-styles.md +++ b/docs/content/en/quick-reference/syntax-highlighting-styles.md @@ -11,7 +11,7 @@ Hugo provides several methods to add syntax highlighting to code examples: - 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. diff --git a/docs/content/en/render-hooks/_index.md b/docs/content/en/render-hooks/_index.md index a5e6203ff..a957cb4cf 100644 --- a/docs/content/en/render-hooks/_index.md +++ b/docs/content/en/render-hooks/_index.md @@ -1,6 +1,6 @@ --- 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 diff --git a/docs/content/en/render-hooks/blockquotes.md b/docs/content/en/render-hooks/blockquotes.md index 411c6c796..77e7059c7 100755 --- a/docs/content/en/render-hooks/blockquotes.md +++ b/docs/content/en/render-hooks/blockquotes.md @@ -1,7 +1,7 @@ --- 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: [] --- @@ -10,7 +10,7 @@ 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. diff --git a/docs/content/en/render-hooks/code-blocks.md b/docs/content/en/render-hooks/code-blocks.md index 6e0ea011f..526a1232f 100755 --- a/docs/content/en/render-hooks/code-blocks.md +++ b/docs/content/en/render-hooks/code-blocks.md @@ -1,7 +1,7 @@ --- 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: [] --- @@ -41,7 +41,7 @@ In the example above, the _highlighting options_ are `lineNos` and `tabWidth`. H ## 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. @@ -50,7 +50,7 @@ Inner : (`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. diff --git a/docs/content/en/render-hooks/headings.md b/docs/content/en/render-hooks/headings.md index 5279dff78..44281bb3d 100755 --- a/docs/content/en/render-hooks/headings.md +++ b/docs/content/en/render-hooks/headings.md @@ -1,14 +1,14 @@ --- 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. diff --git a/docs/content/en/render-hooks/images.md b/docs/content/en/render-hooks/images.md index 9f8ef1efb..bee068a0d 100755 --- a/docs/content/en/render-hooks/images.md +++ b/docs/content/en/render-hooks/images.md @@ -1,7 +1,7 @@ --- 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: [] --- @@ -20,7 +20,7 @@ These components are passed into the render hook [context](g) as shown below. ## 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: @@ -97,21 +97,20 @@ Note that the above requires the following site configuration: 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. diff --git a/docs/content/en/render-hooks/links.md b/docs/content/en/render-hooks/links.md index af0a8f0dd..0e6519e2e 100755 --- a/docs/content/en/render-hooks/links.md +++ b/docs/content/en/render-hooks/links.md @@ -20,7 +20,7 @@ These components are passed into the render hook [context](g) as shown below. ## Context -Link render hook templates receive the following context: +Link _render hook_ templates receive the following context: Destination : (`string`) The link destination. @@ -70,21 +70,20 @@ To include a `rel` attribute set to `external` for external links: {{- /* 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. diff --git a/docs/content/en/render-hooks/passthrough.md b/docs/content/en/render-hooks/passthrough.md index ea0df8824..253039316 100755 --- a/docs/content/en/render-hooks/passthrough.md +++ b/docs/content/en/render-hooks/passthrough.md @@ -1,7 +1,7 @@ --- 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: [] --- @@ -47,7 +47,7 @@ To enable custom rendering of passthrough elements, create a passthrough render ## 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: diff --git a/docs/content/en/render-hooks/tables.md b/docs/content/en/render-hooks/tables.md index 619090797..852f67e11 100755 --- a/docs/content/en/render-hooks/tables.md +++ b/docs/content/en/render-hooks/tables.md @@ -1,7 +1,7 @@ --- 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: [] --- @@ -10,7 +10,7 @@ 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: diff --git a/docs/content/en/shortcodes/qr.md b/docs/content/en/shortcodes/qr.md index 27d9ae02f..3cbc5d3fd 100755 --- a/docs/content/en/shortcodes/qr.md +++ b/docs/content/en/shortcodes/qr.md @@ -104,4 +104,4 @@ title [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]: diff --git a/docs/content/en/shortcodes/ref.md b/docs/content/en/shortcodes/ref.md index b38413c63..0cd5b52dc 100755 --- a/docs/content/en/shortcodes/ref.md +++ b/docs/content/en/shortcodes/ref.md @@ -10,7 +10,11 @@ keywords: [] > 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 @@ -55,8 +59,7 @@ Rendered: {{% 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 %}} diff --git a/docs/content/en/shortcodes/relref.md b/docs/content/en/shortcodes/relref.md index d4f4c2425..22cdb9f2f 100755 --- a/docs/content/en/shortcodes/relref.md +++ b/docs/content/en/shortcodes/relref.md @@ -10,7 +10,11 @@ keywords: [] > 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 @@ -55,8 +59,7 @@ Rendered: {{% 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 %}} diff --git a/docs/content/en/showcase/_template/index.md b/docs/content/en/showcase/_template/index.md index 3103903e1..6a115961b 100644 --- a/docs/content/en/showcase/_template/index.md +++ b/docs/content/en/showcase/_template/index.md @@ -17,7 +17,7 @@ To complete this showcase: 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 The content of this bundle explained: diff --git a/docs/content/en/showcase/ampio-help/bio.md b/docs/content/en/showcase/ampio-help/bio.md index a08b26be7..bc0a9a937 100644 --- a/docs/content/en/showcase/ampio-help/bio.md +++ b/docs/content/en/showcase/ampio-help/bio.md @@ -1,6 +1,6 @@ -__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: diff --git a/docs/content/en/showcase/ampio-help/index.md b/docs/content/en/showcase/ampio-help/index.md index 462452cb1..20e767289 100644 --- a/docs/content/en/showcase/ampio-help/index.md +++ b/docs/content/en/showcase/ampio-help/index.md @@ -15,10 +15,10 @@ Over and above that, we could not overlook the fact that our internal team of ed 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 diff --git a/docs/content/en/showcase/hartwell-insurance/index.md b/docs/content/en/showcase/hartwell-insurance/index.md index 07ee6182c..1e15510a8 100644 --- a/docs/content/en/showcase/hartwell-insurance/index.md +++ b/docs/content/en/showcase/hartwell-insurance/index.md @@ -8,7 +8,7 @@ byline: "[Trys Mudford](http://www.trysmudford.com), Lead Developer, Tomango" 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.** diff --git a/docs/content/en/showcase/pharmaseal/index.md b/docs/content/en/showcase/pharmaseal/index.md index 3a8da2377..fa8c8a8ab 100644 --- a/docs/content/en/showcase/pharmaseal/index.md +++ b/docs/content/en/showcase/pharmaseal/index.md @@ -10,13 +10,13 @@ We wanted to shake the status quo with PHARMASEAL, opting for a fast and scalabl 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. diff --git a/docs/content/en/templates/introduction.md b/docs/content/en/templates/introduction.md index 7ee4f6cdf..9d94032c9 100644 --- a/docs/content/en/templates/introduction.md +++ b/docs/content/en/templates/introduction.md @@ -9,7 +9,6 @@ weight: 10 {{< newtemplatesystem >}} - {{% glossary-term template %}} Templates use [variables], [functions], and [methods] to transform your content, resources, and data into a published page. @@ -35,7 +34,7 @@ While HTML templates are the most common, you can create templates for any [outp 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 @@ -343,7 +342,7 @@ Use the [`partial`] or [`partialCached`] function to include one or more [partia {{ 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. @@ -508,29 +507,24 @@ In the template example above, each of the keys is a valid identifier. For examp [`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 diff --git a/docs/content/en/templates/menu.md b/docs/content/en/templates/menu.md index e1eaa07b9..aa0e7c673 100644 --- a/docs/content/en/templates/menu.md +++ b/docs/content/en/templates/menu.md @@ -21,7 +21,7 @@ The example below handles every combination. ## 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 }} diff --git a/docs/content/en/templates/new-templatesystem-overview.md b/docs/content/en/templates/new-templatesystem-overview.md index 93be94bcc..a3b53197b 100644 --- a/docs/content/en/templates/new-templatesystem-overview.md +++ b/docs/content/en/templates/new-templatesystem-overview.md @@ -1,4 +1,3 @@ - --- title: New template system in Hugo v0.146.0 linktitle: New template system @@ -32,7 +31,7 @@ Also, see the [Example folder structure] below for a more concrete example of th ## 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: @@ -50,9 +49,9 @@ 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 @@ -90,10 +89,11 @@ layouts └── 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/ diff --git a/docs/content/en/templates/pagination.md b/docs/content/en/templates/pagination.md index 76b9d1fdc..6d4203949 100644 --- a/docs/content/en/templates/pagination.md +++ b/docs/content/en/templates/pagination.md @@ -172,9 +172,9 @@ And this site configuration: 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 }}

{{ .LinkTitle }}

{{ end }} @@ -237,5 +237,4 @@ public/ [`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 %}} diff --git a/docs/content/en/templates/robots.md b/docs/content/en/templates/robots.md index 2d412d775..807a6027a 100644 --- a/docs/content/en/templates/robots.md +++ b/docs/content/en/templates/robots.md @@ -46,8 +46,7 @@ This template creates a robots.txt file with a `Disallow` directive for each pag > 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/ diff --git a/docs/content/en/templates/shortcode.md b/docs/content/en/templates/shortcode.md index 5e6ad3429..f07206f6a 100644 --- a/docs/content/en/templates/shortcode.md +++ b/docs/content/en/templates/shortcode.md @@ -9,7 +9,6 @@ aliases: [/templates/shortcode-templates/] {{< 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. @@ -27,7 +26,7 @@ Hugo provides [embedded shortcodes] for many common tasks, but you'll likely nee ## 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/ @@ -53,7 +52,7 @@ When calling a shortcode in a subdirectory, specify its path relative to the `_s ## 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 :--|:--|:--|:-- @@ -71,7 +70,7 @@ foo|json|en|`layouts/_shortcodes/foo.json.en.json` ## 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 %}} diff --git a/docs/content/en/templates/sitemap.md b/docs/content/en/templates/sitemap.md index 2691ae471..8eb358d87 100644 --- a/docs/content/en/templates/sitemap.md +++ b/docs/content/en/templates/sitemap.md @@ -36,17 +36,9 @@ title = 'News' ## 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 diff --git a/docs/content/en/templates/types.md b/docs/content/en/templates/types.md index 8c533a56f..19e0e32dd 100644 --- a/docs/content/en/templates/types.md +++ b/docs/content/en/templates/types.md @@ -38,7 +38,8 @@ layouts/ │ ├── 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 @@ -58,13 +59,23 @@ The purpose of each template type is described below. ## 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"} - + {{ partial "head.html" . }} @@ -73,7 +84,11 @@ For example, the base template below calls the [`partial`] function to include p {{ partial "header.html" . }}
- {{ 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 }}