Merge commit '8b9803425e63e1b1801f8d5d676e96368d706722'

2025-08-15 20:44:01 +02:00 · 2024-06-21 09:41:24 +02:00
parent d5542ed286 8b9803425e
commit af0cb57aaf
475 changed files with 7408 additions and 4720 deletions
--- a/docs/content/en/troubleshooting/_index.md
+++ b/docs/content/en/troubleshooting/_index.md
@@ -1,12 +1,12 @@
 ---
 title: Troubleshooting
-linkTitle: Overview
+linkTitle: In this section
 description: Use these techniques when troubleshooting your site.
 categories: []
 keywords: []
 menu:
  docs:
-    identifier: troubleshooting-overview
+    identifier: troubleshooting-in-this-section
    parent: troubleshooting
    weight: 10
 weight: 10
--- a/docs/content/en/troubleshooting/audit/index.md
+++ b/docs/content/en/troubleshooting/audit/index.md
@@ -53,7 +53,7 @@ _Tested with GNU Bash 5.1 and GNU grep 3.7._
 ### Patterns

 `<!-- raw HTML omitted -->`
-: By default, Hugo strips raw HTML from your markdown prior to rendering, and leaves this HTML comment in its place.
+: By default, Hugo strips raw HTML from your Markdown prior to rendering, and leaves this HTML comment in its place.

 `ZgotmplZ`
 : ZgotmplZ is a special value that indicates that unsafe content reached a CSS or URL context at runtime. See&nbsp;[details].
--- a/docs/content/en/troubleshooting/faq.md
+++ b/docs/content/en/troubleshooting/faq.md
@@ -39,17 +39,6 @@ In the content/_index.md file:

 If the answer to any of these questions is yes, either change the field values, or use one of these command line flags: `--buildDrafts`, `--buildFuture`, or `--buildExpired`.

-###### Why is a given section not published?
-
-In the content/section/_index.md file:
-
-  - Is `draft` set to `true`?
-  - Is the `date` in the future?
-  - Is the `publishDate` in the future?
-  - Is the `expiryDate` in the past?
-
-If the answer to any of these questions is yes, either change the field values, or use one of these command line flags: `--buildDrafts`, `--buildFuture`, or `--buildExpired`.
-
 ###### Why is a given page not published?

 In the content/section/page.md file, or in the content/section/page/index.md file:
@@ -94,7 +83,7 @@ You are probably invoking the [`Paginate`] or [`Paginator`] method more than onc

 ###### Why are there two ways to call a shortcode?

-Use the `{{%/* shortcode */%}}` notation if the shortcode template, or the content between the opening and closing shortcode tags, contains markdown. Otherwise use the\
+Use the `{{%/* shortcode */%}}` notation if the shortcode template, or the content between the opening and closing shortcode tags, contains Markdown. Otherwise use the\
 `{{</* shortcode */>}}` notation. See&nbsp;[details](/content-management/shortcodes/).

 ###### Can I use environment variables to control configuration?
@@ -105,6 +94,36 @@ Yes. See&nbsp;[details](/getting-started/configuration/#configure-with-environme

 The most common causes are page collisions (publishing two pages to the same path) and the effects of concurrency. Use the `--printPathWarnings` command line flag to check for page collisions, and create a topic on the [forum] if you suspect concurrency problems.

+###### Why isn't Hugo's development server detecting file changes?
+
+In its default configuration, Hugo's file watcher may not be able detect file changes when:
+
+- Running Hugo within Windows Subsystem for Linux (WSL/WSL2) with project files on a Windows partition
+- Running Hugo locally with project files on a removable drive
+- Running Hugo locally with project files on a storage server accessed via the NFS, SMB, or CIFS protocols
+
+In these cases, instead of monitoring native file system events, use the `--poll` command line flag. For example, to poll the project files every 700 milliseconds, use `--poll 700ms`.
+
+###### Why is my page Scratch or Store missing a value?
+
+The [`Scratch`] and [`Store`] methods on a `Page` object allow you to create a [scratch pad] on the given page to store and manipulate data. Values are often set within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are not determinate until Hugo renders the page content.
+
+[scratch pad]: /getting-started/glossary/#scratch-pad
+
+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] variable:
+
+[noop]: /getting-started/glossary/#noop
+
+```go-html-template
+{{ $noop := .Content }}
+{{ .Store.Get "mykey" }}
+```
+
+You can trigger content rendering with other methods as well. See next FAQ.
+
+[`Scratch`]: /methods/page/scratch
+[`Store`]: /methods/page/store
+
 ###### Which page methods trigger content rendering?

 The following methods on a `Page` object trigger content rendering: `Content`, `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount`.
@@ -116,9 +135,9 @@ For other questions please visit the [forum]. A quick search of over 20,000 topi
 [requesting help]: https://discourse.gohugo.io/t/requesting-help/9132
 {{% /note %}}

-[`Paginate`]: /methods/page/paginate
-[`Paginator`]: /methods/page/paginator
+[`Paginate`]: /methods/page/paginate/
+[`Paginator`]: /methods/page/paginator/
 [context]: /getting-started/glossary/#context
 [forum]: https://discourse.gohugo.io
-[installation]: /installation
+[installation]: /installation/
 [requesting help]: https://discourse.gohugo.io/t/requesting-help/9132
--- a/docs/content/en/troubleshooting/inspection.md
+++ b/docs/content/en/troubleshooting/inspection.md
@@ -11,10 +11,10 @@ menu:
 weight: 40
 ---

-Use the [`jsonify`] function to inspect a data structure:
+Use the [`debug.Dump`] function to inspect a data structure:

 ```go-html-template
-<pre>{{ jsonify (dict "indent" "  ") .Params }}</pre>
+<pre>{{ debug.Dump .Params }}</pre>
 ```

 ```text
@@ -32,33 +32,6 @@ Use the [`jsonify`] function to inspect a data structure:
 }
 ```

-{{% note %}}
-Hugo will throw an error if you attempt to use the construct above to display context that includes a page collection. For example, in a home page template, this will fail:
-
-`{{ jsonify (dict "indent" "  ") . }}`
-{{% /note %}}
-
-Use the [`debug.Dump`] function to inspect data types:
-
-```go-html-template
-<pre>{{ debug.Dump .Params }}</pre>
-```
-
-```text
-maps.Params{
-  "date": time.Time{},
-  "draft": false,
-  "iscjklanguage": false,
-  "lastmod": time.Time{},
-  "publishdate": time.Time{},
-  "tags": []string{
-    "foo",
-    "bar",
-  },
-  "title": "My first post",
-}
-```
-
 Use the [`printf`] function (render) or [`warnf`] function (log to console) to inspect simple data structures. The layout string below displays both value and data type.

 ```go-html-template
@@ -66,7 +39,6 @@ Use the [`printf`] function (render) or [`warnf`] function (log to console) to i
 {{ printf "%[1]v (%[1]T)" $value }} → 42 (int)
 ```

-[`jsonify`]: /functions/encoding/jsonify
-[`debug.Dump`]: /functions/debug/dump
-[`printf`]: /functions/fmt/printf
-[`warnf`]: /functions/fmt/warnf
+[`debug.Dump`]: /functions/debug/dump/
+[`printf`]: /functions/fmt/printf/
+[`warnf`]: /functions/fmt/warnf/
--- a/docs/content/en/troubleshooting/logging.md
+++ b/docs/content/en/troubleshooting/logging.md
@@ -54,3 +54,19 @@ If you do not specify a logging level with the `--logLevel` flag, warnings and e
 You can also use template functions to print warnings or errors to the console. These functions are typically used to report data validation errors, missing files, etc.

 {{< list-pages-in-section path=/functions/fmt filter=functions_fmt_logging filterType=include >}}
+
+## LiveReload
+
+To log Hugo's LiveReload requests in your browser, add this query string to the URL when running Hugo's development server:
+
+```text
+debug=LR-verbose
+```
+
+For example:
+
+```text
+http://localhost:1313/?debug=LR-verbose
+```
+
+Then monitor the reload requests in your browser's dev tools console. Make sure the dev tools "preserve log" option is enabled.
--- a/docs/content/en/troubleshooting/performance.md
+++ b/docs/content/en/troubleshooting/performance.md
@@ -1,6 +1,6 @@
 ---
 title: Performance
-description: Use template metrics and timers to identify opportunities to improve performance.
+description: Tools and suggestions for evaluating and improving performance.
 categories: [troubleshooting]
 keywords: []
 menu:
@@ -12,6 +12,24 @@ toc: true
 aliases: [/troubleshooting/build-performance/]
 ---

+## Virus scanning
+
+Virus scanners are an essential component of system protection, but the performance impact can be severe for applications like Hugo that frequently read and write to disk. For example, with Microsoft Defender Antivirus, build times for some sites may increase by 400% or more.
+
+Before building a site, your virus scanner has already evaluated the files in your project directory. Scanning them again while building the site is superfluous. To improve performance, add Hugo's executable to your virus scanner's process exclusion list.
+
+For example, with Microsoft Defender Antivirus:
+
+**Start**&nbsp;> **Settings**&nbsp;> **Privacy&nbsp;&&nbsp;security**&nbsp;> **Windows&nbsp;Security**&nbsp;> **Open&nbsp;Windows&nbsp;Security**&nbsp;> **Virus&nbsp;&&nbsp;threat&nbsp;protection**&nbsp;> **Manage&nbsp;settings**&nbsp;> **Add&nbsp;or&nbsp;remove&nbsp;exclusions**&nbsp;> **Add&nbsp;an&nbsp;exclusion**&nbsp;> **Process**
+
+Then type `hugo.exe` add press the **Add** button.
+
+{{% note %}}
+Virus scanning exclusions are common, but use caution when changing these settings. See the [Microsoft Defender Antivirus documentation](https://support.microsoft.com/en-us/topic/how-to-add-a-file-type-or-process-exclusion-to-windows-security-e524cbc2-3975-63c2-f9d1-7c2eb5331e53) for details.
+{{% /note %}}
+
+Other virus scanners have similar exclusion mechanisms. See their respective documentation.
+
 ## Template metrics

 Hugo is fast, but inefficient templates impede performance. Enable template metrics to determine which templates take the most time, and to identify caching opportunities:
@@ -74,8 +92,8 @@ total count
 template
 : The path to the template, relative to the layouts directory.

-[`partial`]: /functions/partials/include
-[`partialCached`]: /functions/partials/includecached
+[`partial`]: /functions/partials/include/
+[`partialCached`]: /functions/partials/includecached/

 {{% note %}}
 Hugo builds pages in parallel where multiple pages are generated simultaneously. Because of this parallelism, the sum of "cumulative duration" values is usually greater than the actual time it takes to build a site.
@@ -86,7 +104,7 @@ Hugo builds pages in parallel where multiple pages are generated simultaneously.
 Some partial templates such as sidebars or menus are executed many times during a site build. Depending on the content within the partial template and the desired output, the template may benefit from caching to reduce the number of executions. The [`partialCached`] template function provides caching capabilities for partial templates.

 {{% note %}}
-Note that you can create cached variants of each partial by passing additional parameters to `partialCached` beyond the initial context. See the `partialCached` documentation for more details.
+Note that you can create cached variants of each partial by passing additional arguments to `partialCached` beyond the initial context. See the `partialCached` documentation for more details.
 {{% /note %}}

 ## Timers