diff --git a/.cspell.json b/.cspell.json index 28dba57be..c41b857fd 100644 --- a/.cspell.json +++ b/.cspell.json @@ -23,7 +23,8 @@ "**/emojis.md", "**/commands/*", "**/showcase/*", - "**/tools/*" + "**/tools/*", + "data/docs.yaml" ], "ignoreRegExpList": [ "# cspell: ignore fenced code blocks", @@ -59,12 +60,14 @@ "marshal", "marshaling", "multihost", - "multiplatfom", + "multiplatform", "performantly", "preconfigured", "prerendering", "redirection", "redirections", + "slugified", + "slugify", "subexpression", "suppressible", "synchronisation", @@ -113,7 +116,6 @@ "libros", "mercredi", "miesiąc", - "miesiąc", "miesiąca", "miesiące", "miesięcy", @@ -144,6 +146,7 @@ "Samsa", "Stucki", "Thénardier", + "Vitter", "WASI", "# ----------------------------------------------------------------------", "# cspell: ignore operating systems and software packages", diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml index 1ededafd0..c8f5b7bd3 100644 --- a/.markdownlint-cli2.yaml +++ b/.markdownlint-cli2.yaml @@ -77,7 +77,7 @@ config: full: true inline: true shortcut: true - url_inline: true + url_inline: false MD055: style: consistent MD056: true diff --git a/.textlintignore b/.textlintignore deleted file mode 100644 index 97a18e37c..000000000 --- a/.textlintignore +++ /dev/null @@ -1,3 +0,0 @@ -**/news/** -**/showcase/** -**/zh/** \ No newline at end of file diff --git a/assets/css/styles.css b/assets/css/styles.css index 6665a7e2b..05304a93b 100644 --- a/assets/css/styles.css +++ b/assets/css/styles.css @@ -129,3 +129,8 @@ body { text-decoration: none; padding-left: .0625em; } + +/* Code spans within paragraphs, tables cells, list items, etc. */ +:not(pre) > code { + white-space: nowrap; +} diff --git a/assets/images/sponsors/cloudcannon-blue.svg b/assets/images/sponsors/cloudcannon-blue.svg deleted file mode 100644 index 79b13f431..000000000 --- a/assets/images/sponsors/cloudcannon-blue.svg +++ /dev/null @@ -1,6 +0,0 @@ - - - - - - diff --git a/assets/images/sponsors/cloudcannon-cms-logo.svg b/assets/images/sponsors/cloudcannon-cms-logo.svg new file mode 100644 index 000000000..9860c5999 --- /dev/null +++ b/assets/images/sponsors/cloudcannon-cms-logo.svg @@ -0,0 +1,13 @@ + + + + + + + + + + + + + diff --git a/assets/images/sponsors/cloudcannon-white.svg b/assets/images/sponsors/cloudcannon-white.svg deleted file mode 100644 index 83e319a6d..000000000 --- a/assets/images/sponsors/cloudcannon-white.svg +++ /dev/null @@ -1,6 +0,0 @@ - - - - - - diff --git a/assets/js/body-start.js b/assets/js/body-start.js deleted file mode 100644 index f9b596671..000000000 --- a/assets/js/body-start.js +++ /dev/null @@ -1,6 +0,0 @@ -import { initColorScheme } from './alpinejs/stores/index'; - -(function () { - // This allows us to initialize the color scheme before AlpineJS etc. is loaded. - initColorScheme(); -})(); diff --git a/assets/js/head-early.js b/assets/js/head-early.js index 250bdd6cb..b21eb58a2 100644 --- a/assets/js/head-early.js +++ b/assets/js/head-early.js @@ -1,6 +1,10 @@ import { scrollToActive } from 'js/helpers/index'; +import { initColorScheme } from './alpinejs/stores/index'; (function () { + // This allows us to initialize the color scheme before AlpineJS etc. is loaded. + initColorScheme(); + // Now we know that the browser has JS enabled. document.documentElement.classList.remove('no-js'); diff --git a/assets/js/main.js b/assets/js/main.js index 14440044b..c12be19fa 100644 --- a/assets/js/main.js +++ b/assets/js/main.js @@ -8,14 +8,6 @@ import focus from '@alpinejs/focus'; var debug = 0 ? console.log.bind(console, '[index]') : function () {}; -// Turbolinks init. -(function () { - document.addEventListener('turbo:render', function (e) { - // This is also called right after the body start. This is added to prevent flicker on navigation. - initColorScheme(); - }); -})(); - // Set up and start Alpine. (function () { // Register AlpineJS plugins. diff --git a/content/en/_common/installation/02-prerequisites.md b/content/en/_common/installation/02-prerequisites.md index f27d9d56b..2a0b1ac09 100644 --- a/content/en/_common/installation/02-prerequisites.md +++ b/content/en/_common/installation/02-prerequisites.md @@ -29,6 +29,7 @@ Please refer to the relevant documentation for installation instructions: [cloudcannon]: https://cloudcannon.com/ [cloudflare pages]: https://pages.cloudflare.com/ +[commit information]: /methods/page/GitInfo [dart sass install]: /functions/css/sass/#dart-sass [dart sass]: https://sass-lang.com/dart-sass [git install]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git @@ -37,4 +38,5 @@ Please refer to the relevant documentation for installation instructions: [gitlab pages]: https://docs.gitlab.com/ee/user/project/pages/ [go install]: https://go.dev/doc/install [go]: https://go.dev/ +[hugo modules]: /hugo-modules/ [netlify]: https://www.netlify.com/ diff --git a/content/en/_common/installation/03-prebuilt-binaries.md b/content/en/_common/installation/03-prebuilt-binaries.md index c72a68bee..aa8268fcd 100644 --- a/content/en/_common/installation/03-prebuilt-binaries.md +++ b/content/en/_common/installation/03-prebuilt-binaries.md @@ -15,3 +15,5 @@ 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. + +[latest release]: https://github.com/gohugoio/hugo/releases/latest diff --git a/content/en/_common/installation/04-build-from-source.md b/content/en/_common/installation/04-build-from-source.md index 3ce245f4a..fb2588d8a 100644 --- a/content/en/_common/installation/04-build-from-source.md +++ b/content/en/_common/installation/04-build-from-source.md @@ -7,7 +7,7 @@ _comment: Do not remove front matter. To build the extended or extended/deploy edition from source you must: 1. Install [Git] -1. Install [Go] version 1.23.0 or later +1. Install [Go] version 1.24.0 or later 1. Install a C compiler, either [GCC] or [Clang] 1. Update your `PATH` environment variable as described in the [Go documentation] diff --git a/content/en/_common/installation/homebrew.md b/content/en/_common/installation/homebrew.md index 14f48174e..bc7902c00 100644 --- a/content/en/_common/installation/homebrew.md +++ b/content/en/_common/installation/homebrew.md @@ -4,7 +4,7 @@ _comment: Do not remove front matter. ### Homebrew -[Homebrew] is a free and open-source package manager for macOS and Linux. To install the extended edition of Hugo: +[Homebrew] is a free and open-source package manager for macOS and Linux. To install the extended/deploy edition of Hugo: ```sh brew install hugo diff --git a/content/en/_common/permalink-tokens.md b/content/en/_common/permalink-tokens.md index f2c16e100..aac412576 100644 --- a/content/en/_common/permalink-tokens.md +++ b/content/en/_common/permalink-tokens.md @@ -26,9 +26,17 @@ _comment: Do not remove front matter. `:section` : The content's section. +`:sectionslug` +: {{< new-in 0.149.0 />}} +: The content's section using slugified section name. The slugified section name is the `slug` as defined in front matter, else the `title` as defined in front matter, else the automatic title. + `:sections` : The content's sections hierarchy. You can use a selection of the sections using _slice syntax_: `:sections[1:]` includes all but the first, `:sections[:last]` includes all but the last, `:sections[last]` includes only the last, `:sections[1:2]` includes section 2 and 3. Note that this slice access will not throw any out-of-bounds errors, so you don't have to be exact. +`:sectionslugs` +: {{< new-in 0.149.0 />}} +: The content's sections hierarchy using slugified section names. The slugified section name is the `slug` as defined in front matter, else the `title` as defined in front matter, else the automatic title. You can use a selection of the sections using _slice syntax_: `:sectionslugs[1:]` includes all but the first, `:sectionslugs[:last]` includes all but the last, `:sectionslugs[last]` includes only the last, `:sectionslugs[1:2]` includes section 2 and 3. Note that this slice access will not throw any out-of-bounds errors, so you don't have to be exact. + `:title` : The `title` as defined in front matter, else the automatic title. Hugo generates titles automatically for section, taxonomy, and term pages that are not backed by a file. diff --git a/content/en/_common/render-hooks/pageinner.md b/content/en/_common/render-hooks/pageinner.md index 3efbc9ce3..2068b28db 100644 --- a/content/en/_common/render-hooks/pageinner.md +++ b/content/en/_common/render-hooks/pageinner.md @@ -43,5 +43,5 @@ As a practical example, Hugo's embedded link and image render hooks use the `Pag [`RenderShortcodes`]: /methods/page/rendershortcodes/ [Markdown notation]: /content-management/shortcodes/#notation -[Embedded link render hook]: {{% eturl render-link %}} -[Embedded image render hook]: {{% eturl render-image %}} +[Embedded link render hook]: <{{% eturl render-link %}}> +[Embedded image render hook]: <{{% eturl render-image %}}> diff --git a/content/en/about/introduction.md b/content/en/about/introduction.md index 9586d08f8..3d56b9570 100644 --- a/content/en/about/introduction.md +++ b/content/en/about/introduction.md @@ -28,7 +28,7 @@ Learn more about Hugo's [features], [privacy protections], and [security model]. [Hugo Modules]: /hugo-modules/ [static site generator]: https://en.wikipedia.org/wiki/Static_site_generator [features]: /about/features/ -[security model]: about/security/ +[security model]: /about/security/ [privacy protections]: /configuration/privacy {{< youtube 0RKpf3rK57I >}} diff --git a/content/en/commands/hugo_gen_chromastyles.md b/content/en/commands/hugo_gen_chromastyles.md index 2863e46b4..78cc62f88 100644 --- a/content/en/commands/hugo_gen_chromastyles.md +++ b/content/en/commands/hugo_gen_chromastyles.md @@ -24,6 +24,8 @@ hugo gen chromastyles [flags] [args] --highlightStyle string foreground and background colors for highlighted lines, e.g. --highlightStyle "#fff000 bg:#000fff" --lineNumbersInlineStyle string foreground and background colors for inline line numbers, e.g. --lineNumbersInlineStyle "#fff000 bg:#000fff" --lineNumbersTableStyle string foreground and background colors for table line numbers, e.g. --lineNumbersTableStyle "#fff000 bg:#000fff" + --omitClassComments omit CSS class comment prefixes in the generated CSS + --omitEmpty omit empty CSS rules (deprecated, no longer needed) --style string highlighter style (see https://xyproto.github.io/splash/docs/) (default "friendly") ``` diff --git a/content/en/commands/hugo_new.md b/content/en/commands/hugo_new.md index 2788ef168..56ab4aef9 100644 --- a/content/en/commands/hugo_new.md +++ b/content/en/commands/hugo_new.md @@ -45,6 +45,6 @@ Ensure you run this within the root directory of your site. * [hugo](/commands/hugo/) - Build your site * [hugo new content](/commands/hugo_new_content/) - Create new content -* [hugo new site](/commands/hugo_new_site/) - Create a new site (skeleton) -* [hugo new theme](/commands/hugo_new_theme/) - Create a new theme (skeleton) +* [hugo new site](/commands/hugo_new_site/) - Create a new site +* [hugo new theme](/commands/hugo_new_theme/) - Create a new theme diff --git a/content/en/commands/hugo_new_site.md b/content/en/commands/hugo_new_site.md index 0f0096ae4..ccf74bc6f 100644 --- a/content/en/commands/hugo_new_site.md +++ b/content/en/commands/hugo_new_site.md @@ -5,13 +5,11 @@ url: /commands/hugo_new_site/ --- ## hugo new site -Create a new site (skeleton) +Create a new site ### Synopsis -Create a new site in the provided directory. -The new site will have the correct structure, but no content or theme yet. -Use `hugo new [contentPath]` to create new content. +Create a new site at the specified path. ``` hugo new site [path] [flags] diff --git a/content/en/commands/hugo_new_theme.md b/content/en/commands/hugo_new_theme.md index b1c937bae..140660077 100644 --- a/content/en/commands/hugo_new_theme.md +++ b/content/en/commands/hugo_new_theme.md @@ -5,14 +5,12 @@ url: /commands/hugo_new_theme/ --- ## hugo new theme -Create a new theme (skeleton) +Create a new theme ### Synopsis -Create a new theme (skeleton) called [name] in ./themes. -New theme is a skeleton. Please add content to the touched files. Add your -name to the copyright line in the license and adjust the theme.toml file -according to your needs. +Create a new theme with the specified name in the ./themes directory. +This generates a functional theme including template examples and sample content. ``` hugo new theme [name] [flags] @@ -21,7 +19,8 @@ hugo new theme [name] [flags] ### Options ``` - -h, --help help for theme + --format string preferred file format (toml, yaml or json) (default "toml") + -h, --help help for theme ``` ### Options inherited from parent commands diff --git a/content/en/configuration/all.md b/content/en/configuration/all.md index c733e0a99..2d6178e5b 100644 --- a/content/en/configuration/all.md +++ b/content/en/configuration/all.md @@ -47,7 +47,7 @@ cascade : See [configure cascade](/configuration/cascade/). cleanDestinationDir -: (`bool`) Whether to remove files from the site's destination directory that do not have corresponding files in the `static` directory during the build. Default is `false`. +: (`bool`) Whether to remove files from the [`publishDir`](#publishdir) that do not exist in the [`staticDir`](#staticdir) when building the site. This setting will not take effect if the `staticDir` does not exist. Note that `.gitignore` and `.gitattributes` files, along with directories named `.git`, are always preserved in the `publishDir`. Default is `false`. contentDir : (`string`) The designated directory for content files. Default is `content`. {{% module-mounts-note %}} @@ -262,7 +262,7 @@ staticDir : (`string`) The designated directory for static files. Default is `static`. {{% module-mounts-note %}} summaryLength -: (`int`) Applicable to [automatic summaries], the minimum number of words returned by the [`Summary`] method on a `Page` object. The `Summary` method will return content truncated at the paragraph boundary closest to the specified `summaryLength`, but at least this minimum number of words. +: (`int`) Applicable to [automatic summaries], the minimum number of words returned by the [`Summary`] method on a `Page` object. The `Summary` method will return content truncated at the paragraph boundary closest to the specified `summaryLength`, but at least this minimum number of words. Default is `70`. taxonomies : See [configure taxonomies](/configuration/taxonomies/). @@ -350,9 +350,9 @@ Some configuration settings, such as menus and custom parameters, can be defined [Chicago Manual of Style]: https://www.chicagomanualofstyle.org/home.html [default front matter configuration]: /configuration/front-matter/ [duration]: https://pkg.go.dev/time#Duration -[embedded alias template]: {{% eturl alias %}} -[embedded Open Graph template]: {{% eturl opengraph %}} -[embedded RSS template]: {{% eturl rss %}} +[embedded alias template]: <{{% eturl alias %}}> +[embedded Open Graph template]: <{{% eturl opengraph %}}> +[embedded RSS template]: <{{% eturl rss %}}> [IANA Time Zone Database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones [module mounts]: /configuration/module/#mounts [os.UserCacheDir]: https://pkg.go.dev/os#UserCacheDir diff --git a/content/en/configuration/cascade.md b/content/en/configuration/cascade.md index 85b221df2..9a1fda4c6 100644 --- a/content/en/configuration/cascade.md +++ b/content/en/configuration/cascade.md @@ -14,7 +14,6 @@ You can configure your site to cascade front matter values to the home page and For example, to cascade a "color" parameter to the home page and all its descendants: {{< code-toggle file=hugo >}} -title = 'Home' [cascade.params] color = 'red' {{< /code-toggle >}} @@ -61,14 +60,14 @@ Define an array of cascade parameters to apply different values to different tar [cascade.params] color = 'red' [cascade.target] -path = '{/books/**}' +path = '/books/**' kind = 'page' lang = '{en,de}' [[cascade]] [cascade.params] color = 'blue' [cascade.target] -path = '{/films/**}' +path = '/films/**' kind = 'page' environment = 'production' {{< /code-toggle >}} diff --git a/content/en/configuration/front-matter.md b/content/en/configuration/front-matter.md index a97648b61..edffd302d 100644 --- a/content/en/configuration/front-matter.md +++ b/content/en/configuration/front-matter.md @@ -90,10 +90,11 @@ Consider this site configuration: {{< code-toggle file=hugo >}} [frontmatter] date = [':filename', ':default'] +publishDate = [':filename', ':default'] lastmod = ['lastmod', ':fileModTime'] {{< /code-toggle >}} -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 `date` and `publishDate`, Hugo tries to extract the value 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. diff --git a/content/en/configuration/http-cache.md b/content/en/configuration/http-cache.md index 788d22a08..c48c9cbcd 100644 --- a/content/en/configuration/http-cache.md +++ b/content/en/configuration/http-cache.md @@ -44,20 +44,42 @@ The HTTP cache involves two key aspects: determining which content to cache (the The HTTP cache behavior is defined for a configured set of resources. Stale resources will be refreshed from the file cache, even if their configured Time-To-Live (TTL) has not expired. If HTTP caching is disabled for a resource, Hugo will bypass the cache and access the file directly. -The default configuration disables everything: +This is the default configuration for HTTP caching: -{{< code-toggle file=hugo >}} -[HTTPCache.cache.for] -excludes = ['**'] -includes = [] -{{< /code-toggle >}} +{{< code-toggle config=HTTPCache />}} + +respectCacheControlNoStoreInRequest +: {{< new-in 0.151.0 />}} +: (`bool`) Whether to respect the `no-store` directive in the server's `Cache-Control` request header when fetching remote resources via the [`resources.GetRemote`][] function. Default is `true`. + +respectCacheControlNoStoreInResponse +: {{< new-in 0.151.0 />}} +: (`bool`) Whether to respect the `no-store` directive in the server's `Cache-Control` response header when fetching remote resources via the [`resources.GetRemote`][] function. Default is `false`. cache.for.excludes -: (`string`) A list of [glob](g) patterns to exclude from caching. +: (`string`) A list of [glob](g) patterns to exclude from caching. In its default configuration HTTP caching excludes all files. cache.for.includes : (`string`) A list of [glob](g) patterns to cache. +polls +: A slice of polling configurations. + +polls.disable +: (`bool`) Whether to disable polling for this configuration. Default is `true`. + +polls.high +: (`string`) The maximum polling interval expressed as a [duration](g). This is used when the resource is considered stable. Default is `0s`. + +polls.low +: (`string`) The minimum polling interval expressed as a [duration](g). This is used after a recent change and gradually increases towards `polls.high`. Default is `0s`. + +polls.for.excludes +: (`string`) A list of [glob](g) patterns to exclude from polling for this configuration. + +polls.for.includes +: (`string`) A list of [glob](g) patterns to include in polling for this configuration. + ## HTTP polling Polling is used in watch mode (e.g., `hugo server`) to detect changes in remote resources. Polling can be enabled even if HTTP caching is disabled. Detected changes trigger a rebuild of pages using the affected resource. Polling can be disabled for specific resources, typically those known to be static. @@ -78,13 +100,13 @@ polls : A slice of polling configurations. polls.disable -: (`bool`) Whether to disable polling for this configuration. - -polls.low -: (`string`) The minimum polling interval expressed as a [duration](g). This is used after a recent change and gradually increases towards `polls.high`. +: (`bool`) Whether to disable polling for this configuration. Default is `true`. polls.high -: (`string`) The maximum polling interval expressed as a [duration](g). This is used when the resource is considered stable. +: (`string`) The maximum polling interval expressed as a [duration](g). This is used when the resource is considered stable. Default is `0s`. + +polls.low +: (`string`) The minimum polling interval expressed as a [duration](g). This is used after a recent change and gradually increases towards `polls.high`. Default is `0s`. polls.for.excludes : (`string`) A list of [glob](g) patterns to exclude from polling for this configuration. diff --git a/content/en/configuration/languages.md b/content/en/configuration/languages.md index 540cfd34f..72fee25d3 100644 --- a/content/en/configuration/languages.md +++ b/content/en/configuration/languages.md @@ -185,9 +185,9 @@ public [`Language.LanguageName`]: /methods/site/language/#languagename [`Language.Weight`]: /methods/site/language/#weight [`Title`]: /methods/site/title/ -[embedded alias template]: {{% eturl alias %}} -[embedded OpenGraph template]: {{% eturl opengraph %}} -[embedded RSS template]: {{% eturl rss %}} +[embedded alias template]: <{{% eturl alias %}}> +[embedded OpenGraph template]: <{{% eturl opengraph %}}> +[embedded RSS template]: <{{% eturl rss %}}> [RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1 [RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7 [translating by file name]: /content-management/multilingual/#translation-by-file-name diff --git a/content/en/configuration/markup.md b/content/en/configuration/markup.md index bf5aac374..a34074ae5 100644 --- a/content/en/configuration/markup.md +++ b/content/en/configuration/markup.md @@ -94,9 +94,23 @@ enable = true With this configuration, to format text as deleted, wrap it with double-tildes. -#### Passthrough +#### Footnote -{{< new-in 0.122.0 />}} +Enabled by default, the Footnote extension enables inclusion of footnotes in Markdown. + +enable +: {{< new-in 0.151.0 />}} +: (`bool`) Whether to enable the Footnotes extension. Default is `true`. + +backlinkHTML +: {{< new-in 0.151.0 />}} +: (`string`) The HTML to be displayed at the end of a footnote that links the user back to the corresponding reference in the main text. The default is ↩︎ (a return arrow symbol). + +enableAutoIDPrefix +: {{< new-in 0.151.0 />}} +: (`bool`) Whether to prepend a unique prefix to footnote IDs, preventing clashes when multiple documents are rendered together. This prefix is unique to each logical path, which means that the prefix is not unique across content dimensions such as language. Default is `false`. + +#### Passthrough Enable the Passthrough extension to include mathematical equations and expressions in Markdown using LaTeX markup. See [mathematics in Markdown] for details. @@ -202,7 +216,7 @@ backend : (`string`) The backend output file format. Default is `html5`. extensions -: (`string array`) An array of enabled extensions, one or more of `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`, `asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, or `asciidoctor-question`. +: (`string array`) An array of enabled extensions, such as `asciidoctor-html5s`, `asciidoctor-bibtex`, or `asciidoctor-diagram`. > [!note] > To mitigate security risks, entries in the extension array may not contain forward slashes (`/`), backslashes (`\`), or periods. Due to this restriction, extensions must be in Ruby's `$LOAD_PATH`. diff --git a/content/en/configuration/minify.md b/content/en/configuration/minify.md index a530cb73d..3f010f974 100644 --- a/content/en/configuration/minify.md +++ b/content/en/configuration/minify.md @@ -10,6 +10,11 @@ This is the default configuration: {{< code-toggle config=minify />}} -See the [tdewolff/minify] project page for details. +See the [tdewolff/minify] project page for details, but note the following: + +- `css.inline` is for internal use. Changing this setting has no effect. +- `css.keepCSS2` has been deprecated. Use `css.version` instead. +- `html.keepConditionalComments` has been deprecated. Use `html.keepSpecialComments` instead. +- `svg.inline` is for internal use. Changing this setting has no effect. [tdewolff/minify]: https://github.com/tdewolff/minify diff --git a/content/en/configuration/module.md b/content/en/configuration/module.md index 4a7267bd6..76fc034de 100644 --- a/content/en/configuration/module.md +++ b/content/en/configuration/module.md @@ -7,6 +7,8 @@ keywords: [] aliases: [/hugo-modules/configuration/] --- +{{% include "/_common/gomodules-info.md" %}} + ## Top-level options This is the default configuration: @@ -40,7 +42,7 @@ proxy : (`string`) The proxy server to use to download remote modules. Default is `direct`, which means `git clone` and similar. replacements -: (`string`) Primarily useful for local module development, a comma-separated list of mappings from module paths to directories. Paths may be absolute or relative to the [`themesDir`]. +: (`string`) Primarily useful for local module development, a comma-separated list of mappings from module paths to directories. Paths may be absolute or relative to the [`themesDir`][]. {{< code-toggle file=hugo >}} [module] @@ -61,8 +63,6 @@ export HUGO_MODULE_REPLACEMENTS="github.com/bep/my-theme -> ../.." export HUGO_MODULE_WORKSPACE="/my/hugo.work" ``` -{{% include "/_common/gomodules-info.md" %}} - ## Hugo version You can specify a required Hugo version for your module in the `module` section. Users will then receive a warning if their Hugo version is incompatible. @@ -77,7 +77,7 @@ 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.148.0`. +: (`string`) The maximum Hugo version supported, for example `0.152.2`. min : (`string`) The minimum Hugo version supported, for example `0.102.0`. @@ -110,32 +110,36 @@ noVendor : (`bool`) Whether to disable vendoring for this import. This setting is restricted to the main project. Default is `false`. 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`]. +: (`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`][]. -{{% include "/_common/gomodules-info.md" %}} +version +: {{< new-in 0.150.0 />}} +: If set to a [version query](https://go.dev/ref/mod#version-queries), this import becomes a direct dependency, in contrast to dependencies managed by Go Modules. See [this issue](https://github.com/gohugoio/hugo/pull/13966) for more information. ## Mounts -Before Hugo v0.56.0, custom component paths could only be configured by setting [`archetypeDir`], [`assetDir`], [`contentDir`], [`dataDir`], [`i18nDir`], [`layoutDi`], or [`staticDir`] in the site configuration. Module mounts offer greater flexibility than these legacy settings, but -you cannot use both. +{{% glossary-term mount %}} -[`archetypeDir`]: /configuration/all/ -[`assetDir`]: /configuration/all/ -[`contentDir`]: /configuration/all/ -[`dataDir`]: /configuration/all/ -[`i18nDir`]: /configuration/all/ -[`layoutDi`]: /configuration/all/ -[`staticDir`]: /configuration/all/ +> [!important] +> If you define one or more mounts to map a file system path to a component path, do not use these legacy configuration settings: [`archetypeDir`][], [`assetDir`][], [`contentDir`][], [`dataDir`][], [`i18nDir`][], [`layoutDir`][], or [`staticDir`][]. -> [!note] -> If you use module mounts do not use the legacy settings. +[`archetypeDir`]: /configuration/all/#archetypedir +[`assetDir`]: /configuration/all/#assetdir +[`contentDir`]: /configuration/all/#contentdir +[`dataDir`]: /configuration/all/#datadir +[`i18nDir`]: /configuration/all/#i18ndir +[`layoutDir`]: /configuration/all/#layoutdir +[`staticDir`]: /configuration/all/#staticdir ### Default mounts -> [!note] -> Adding a new mount to a target root will cause the existing default mount for that root to be ignored. If you still need the default mount, you must explicitly add it along with the new mount. +Within a project, if you define a mount to map a file system path to a component path, the corresponding default mount for that component will be removed. This action essentially overwrites the standard, automatic mapping for that specific component with your custom one. -The are the default mounts: +Within a module, if you define a mount to map a file system path to a component path, all of the default mounts will be removed. Defining a mount at the module level is a more sweeping change, causing all default mappings within that module to be discarded. + +In either case, if you still need one of the default mounts, you must explicitly add it along with the new mount. Because custom mounts override defaults, any necessary default mappings must be re-added manually after you introduce your custom configuration. + +These are the default mounts: {{< code-toggle config=module.mounts />}} @@ -143,7 +147,7 @@ source : (`string`) The source directory of the mount. For the main project, this can be either project-relative or absolute. For other modules it must be project-relative. target -: (`string`) Where the mount will reside within Hugo's virtual file system. It must begin with one of Hugo's component directories: `archetypes`, `assets`, `content`, `data`, `i18n`, `layouts`, or `static`. For example, `content/blog`. +: (`string`) Where the mount will reside within Hugo's [unified file system](g). It must begin with one of Hugo's [component](g) directories: archetypes, assets, content, data, i18n, layouts, or static. For example, content/blog. disableWatch : {{< new-in 0.128.0 />}} diff --git a/content/en/content-management/archetypes.md b/content/en/content-management/archetypes.md index db0838504..5f7d1ece4 100644 --- a/content/en/content-management/archetypes.md +++ b/content/en/content-management/archetypes.md @@ -44,7 +44,7 @@ archetypes/ Hugo looks for archetypes in the `archetypes` directory in the root of your project, falling back to the `archetypes` directory in themes or installed modules. An archetype for a specific content type takes precedence over the default archetype. -For example, with this command: +For example, if you have enabled a theme named `my-theme` and you run this command: ```sh hugo new content posts/my-first-post.md @@ -53,8 +53,8 @@ hugo new content posts/my-first-post.md The archetype lookup order is: 1. `archetypes/posts.md` -1. `archetypes/default.md` 1. `themes/my-theme/archetypes/posts.md` +1. `archetypes/default.md` 1. `themes/my-theme/archetypes/default.md` If none of these exists, Hugo uses a built-in default archetype. diff --git a/content/en/content-management/diagrams.md b/content/en/content-management/diagrams.md index 3bcecb60b..763fce2d6 100644 --- a/content/en/content-management/diagrams.md +++ b/content/en/content-management/diagrams.md @@ -256,5 +256,5 @@ Created from ``` [code block render hook]: /render-hooks/code-blocks/ -[embedded code block render hook]: {{% eturl render-codeblock-goat %}} +[embedded code block render hook]: <{{% eturl render-codeblock-goat %}}> [GoAT]: https://github.com/bep/goat diff --git a/content/en/content-management/front-matter.md b/content/en/content-management/front-matter.md index 2da6a2613..f0484ef74 100644 --- a/content/en/content-management/front-matter.md +++ b/content/en/content-management/front-matter.md @@ -47,7 +47,7 @@ build : (`map`) A map of [build options]. cascade -: (`map`) A map of front matter keys whose values are passed down to the page's descendants unless overwritten by self or a closer ancestor's cascade. See the [cascade] section for details. +: (`map`) A map (or a slice of maps) of front matter keys whose values are passed down to the page's descendants unless overwritten by self or a closer ancestor's cascade. See the [cascade] section for details. date : (`string`) The date associated with the page, typically the creation date. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`Date`] method on a `Page` object. @@ -322,18 +322,18 @@ To override the default time zone, set the [`timeZone`](/configuration/all/#time [`lastmod`]: /methods/page/date/ [`layout`]: /methods/page/layout/ [`linktitle`]: /methods/page/linktitle/ -[`opengraph.html`]: {{% eturl opengraph %}} +[`opengraph.html`]: <{{% eturl opengraph %}}> [`Param`]: /methods/page/param/ [`Params`]: /methods/page/params/ [`publishdate`]: /methods/page/publishdate/ [`readingtime`]: /methods/page/readingtime/ -[`schema.html`]: {{% eturl schema %}} +[`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 %}} +[`twitter_cards.html`]: <{{% eturl twitter_cards %}}> [`type`]: /methods/page/type/ [`weight`]: /methods/page/weight/ [`wordcount`]: /methods/page/wordcount/ diff --git a/content/en/content-management/image-processing/index.md b/content/en/content-management/image-processing/index.md index 8d60c4f93..3cf8aa4fd 100644 --- a/content/en/content-management/image-processing/index.md +++ b/content/en/content-management/image-processing/index.md @@ -105,8 +105,6 @@ The `image` resource implements the [`Process`], [`Resize`], [`Fit`], [`Fill`] ### Process -{{< new-in 0.119.0 />}} - > [!note] > The `Process` method is also available as a filter, which is more effective if you need to apply multiple filters to an image. See [Process filter](/functions/images/process). diff --git a/content/en/content-management/mathematics.md b/content/en/content-management/mathematics.md index aaa8c2394..5414a00f9 100644 --- a/content/en/content-management/mathematics.md +++ b/content/en/content-management/mathematics.md @@ -6,13 +6,11 @@ categories: [] keywords: [] --- -{{< new-in 0.122.0 />}} - ## Overview -Mathematical equations and expressions written in [LaTeX] are common in academic and scientific publications. Your browser typically renders this mathematical markup using an open-source JavaScript display engine such as [MathJax] or [KaTeX]. +Mathematical equations and expressions written in [LaTeX][] are common in academic and scientific publications. Your browser typically renders this mathematical markup using an open-source JavaScript display engine such as [MathJax][] or [KaTeX][]. -For example, with this LaTeX markup: +For example, this LaTeX markup: ```text \[ @@ -23,7 +21,7 @@ JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y \] ``` -The MathJax display engine renders this: +Is rendered to: \[ \begin{aligned} @@ -37,7 +35,7 @@ Equations and expressions can be displayed inline with other text, or as standal Whether an equation or expression appears inline, or as a block, depends on the delimiters that surround the mathematical markup. Delimiters are defined in pairs, where each pair consists of an opening and closing delimiter. The opening and closing delimiters may be the same, or different. > [!note] -> You can configure Hugo to render mathematical markup on the client side using the MathJax or KaTeX display engine, or you can render the markup with the [`transform.ToMath`] function while building your site. +> You can configure Hugo to render mathematical markup on the client side using the MathJax or KaTeX display engine, or you can render the markup with the [`transform.ToMath`][] function while building your site. > > The first approach is described below. @@ -46,7 +44,7 @@ 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 -: 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] @@ -60,12 +58,12 @@ Step 1 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. + > See the [inline delimiters][] section for details. To disable passthrough of inline snippets, omit the `inline` key from the configuration: @@ -74,7 +72,7 @@ Step 1 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] @@ -83,10 +81,11 @@ Step 1 {{< /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. +: Create a _partial_ template to load MathJax or KaTeX. The example below loads MathJax, or you can use KaTeX as described in the [engines][] section. ```go-html-template {file="layouts/_partials/math.html" copy=true} - + +