Merge commit '9b0050e9aabe4be65c78ccf292a348f309d50ccd' as 'docs'

```
git subtree add --prefix=docs/ https://github.com/gohugoio/hugoDocs.git master --squash
```

Closes #11925

docs/content/en/troubleshooting/_index.md

@@ -0,0 +1,16 @@
+---
+title: Troubleshooting
+linkTitle: Overview
+description: Use these techniques when troubleshooting your site.
+categories: []
+keywords: []
+menu:
+  docs:
+    identifier: troubleshooting-overview
+    parent: troubleshooting
+    weight: 10
+weight: 10
+aliases: [/templates/template-debugging/]
+---
+
+Use these techniques when troubleshooting your site.

docs/content/en/troubleshooting/audit/index.md

@@ -0,0 +1,73 @@
+---
+title: Site audit
+linkTitle: Audit
+description: Run this audit before deploying your production site.
+categories: [troubleshooting]
+keywords: []
+menu:
+  docs:
+    parent: troubleshooting
+    weight: 20
+weight: 20
+---
+
+There are several conditions that can produce errors in your published site which are not detected during the build. Run this audit before your final build.
+
+{{< code copy=true >}}
+HUGO_MINIFY_TDEWOLFF_HTML_KEEPCOMMENTS=true HUGO_ENABLEMISSINGTRANSLATIONPLACEHOLDERS=true hugo && grep -inorE "<\!-- raw HTML omitted -->|ZgotmplZ|\[i18n\]|\(<nil>\)|(&lt;nil&gt;)|hahahugo" public/
+{{< /code >}}
+
+_Tested with GNU Bash 5.1 and GNU grep 3.7._
+
+## Example output
+
+![site audit terminal output](screen-capture.png)
+
+## Explanation
+
+### Environment variables
+
+`HUGO_MINIFY_TDEWOLFF_HTML_KEEPCOMMENTS=true`
+: Retain HTML comments even if minification is enabled. This takes precedence over `minify.tdewolff.html.keepComments` in the site configuration. If you minify without keeping HTML comments when performing this audit, you will not be able to detect when raw HTML has been omitted.
+
+`HUGO_ENABLEMISSINGTRANSLATIONPLACEHOLDERS=true`
+: Show a placeholder instead of the default value or an empty string if a translation is missing. This takes precedence over `enableMissingTranslationPlaceholders` in the site configuration.
+
+### Grep options
+
+`-i, --ignore-case`
+: Ignore case distinctions in patterns and input data, so that characters that differ only in case match each other.
+
+`-n, --line-number`
+: Prefix each line of output with the 1-based line number within its input file.
+
+`-o, --only-matching`
+: Print only the matched (non-empty) parts of a matching line, with each such part on a separate output line.
+
+`-r, --recursive`
+: Read all files under each directory, recursively, following symbolic links only if they are on the command line.
+
+`-E, --extended-regexp`
+: Interpret PATTERNS as extended regular expressions.
+
+### Patterns
+
+`<!-- raw HTML omitted -->`
+: 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].
+
+[details]: https://pkg.go.dev/html/template
+
+`[i18n]`
+: This is the placeholder produced instead of the default value or an empty string if a translation is missing.
+
+`(<nil>)`
+: This string will appear in the rendered HTML when passing a nil value to the `printf` function.
+
+`(&lt;nil&gt;)`
+: Same as above when the value returned from the `printf` function has not been passed through `safeHTML`.
+
+`HAHAHUGO`
+: Under certain conditions a rendered shortcode may include all or a portion of the string H&#xfeff;AHAHUGOSHORTCODE in either uppercase or lowercase. This is difficult to detect in all circumstances, but a case-insensitive search of the output for `HAHAHUGO` is likely to catch the majority of cases without producing false positives.

docs/content/en/troubleshooting/deprecation.md

@@ -0,0 +1,50 @@
+---
+title: Deprecation
+description: The Hugo project follows a formal and consistent process to deprecate functions, methods, and configuration settings.
+categories: [troubleshooting]
+keywords: []
+menu:
+  docs:
+    parent: troubleshooting
+    weight: 50
+weight: 50
+---
+
+When a project _deprecates_ something, they are telling its users:
+
+1. Don't use Thing One anymore.
+2. Use Thing Two instead.
+3. We're going to remove Thing One at some point in the future.
+
+[reasons for deprecation]: https://en.wikipedia.org/wiki/Deprecation
+
+Common [reasons for deprecation]:
+
+- A feature has been replaced by a more powerful alternative.
+- A feature contains a design flaw.
+- A feature is considered extraneous, and will be removed in the future in order to simplify the system as a whole.
+- A future version of the software will make major structural changes, making it impossible or impractical to support older features.
+- Standardization or increased consistency in naming.
+- A feature that once was available only independently is now combined with its co-feature.
+
+After the project team deprecates something in code, Hugo will:
+
+1. Log an INFO message for 6 minor releases[^1]
+2. Log a WARN message for another 6 minor releases
+3. Log an ERROR message and fail the build thereafter
+
+To see the INFO messages, you must use the `--logLevel` command line flag:
+
+```text
+hugo --logLevel info
+```
+
+To limit the output to deprecation notices:
+
+```text
+hugo --logLevel info | grep deprecate
+```
+
+Run the above command every time you upgrade Hugo.
+
+[^1]: For example, v0.1.1 => v0.2.0 is a minor release.

docs/content/en/troubleshooting/faq.md

@@ -0,0 +1,124 @@
+---
+title: Frequently asked questions
+linkTitle: FAQs
+description: These questions are frequently asked by new users.
+categories: [troubleshooting]
+keywords: [faq]
+menu:
+  docs:
+    parent: troubleshooting
+    weight: 70
+weight: 70
+# Use level 6 headings for each question.
+---
+
+Hugo’s [forum] is an active community of users and developers who answer questions, share knowledge, and provide examples. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question.
+
+These are just a few of the questions most frequently asked by new users.
+
+###### An error message indicates that a feature is not available. Why?
+
+Hugo is available in two editions: standard and extended. With the extended edition you can (a) encode to the WebP format when processing images, and (b) transpile Sass to CSS using the embedded LibSass transpiler. The extended edition is not required to use the Dart Sass transpiler.
+
+When you attempt to perform either of the operations above with the standard edition, Hugo throws this error:
+
+```go-html-template
+Error: this feature is not available in your current Hugo version
+```
+
+To resolve, uninstall the standard edition, then install the extended edition. See the [installation] section for details.
+
+###### Why do I see "Page Not Found" when visiting the home page?
+
+In the content/_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 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:
+
+  - 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 can't I see any of a page's descendants?
+
+You may have an index.md file instead of an _index.md file. See [details](/content-management/page-bundles/).
+
+###### What is the difference between an index.md file and an _index.md file?
+
+A directory with an index.md file is a [leaf bundle]. A directory with an _index.md file is a [branch bundle]. See [details](/content-management/page-bundles/).
+
+[branch bundle]: /getting-started/glossary/#branch-bundle
+[leaf bundle]: /getting-started/glossary/#leaf-bundle
+
+###### Why is my partial template not rendered as expected? {#foo}
+
+You may have neglected to pass the required [context] when calling the partial. For example:
+
+```go-html-template
+{{/* incorrect */}}
+{{ partial "_internal/pagination.html" }}
+
+{{/* correct */}}
+{{ partial "_internal/pagination.html" . }}
+```
+
+###### In a template, what's the difference between `:=` and `=` when assigning values to variables?
+
+Use `:=` to initialize a variable, and use `=` to assign a value to a variable that has been previously initialized. See [details](https://pkg.go.dev/text/template#hdr-Variables).
+
+###### When I paginate a list page, why is the page collection not filtered as specified?
+
+You are probably invoking the [`Paginate`] or [`Paginator`] method more than once on the same page. See [details](/templates/pagination/#list-paginator-pages).
+
+###### 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\
+`{{</* shortcode */>}}` notation. See&nbsp;[details](/content-management/shortcodes/).
+
+###### Can I use environment variables to control configuration?
+
+Yes. See&nbsp;[details](/getting-started/configuration/#configure-with-environment-variables).
+
+###### Why am I seeing inconsistent output from one build to the next?
+
+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.
+
+###### 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`.
+
+{{% note %}}
+For other questions please visit the [forum]. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question.
+
+[forum]: https://discourse.gohugo.io
+[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132
+{{% /note %}}
+
+[`Paginate`]: /methods/page/paginate
+[`Paginator`]: /methods/page/paginator
+[context]: /getting-started/glossary/#context
+[forum]: https://discourse.gohugo.io
+[installation]: /installation
+[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132

docs/content/en/troubleshooting/inspection.md

@@ -0,0 +1,72 @@
+---
+title: Data inspection
+linkTitle: Inspection
+description: Use template functions to inspect values and data structures.
+categories: [troubleshooting]
+keywords: []
+menu:
+  docs:
+    parent: troubleshooting
+    weight: 40
+weight: 40
+---
+
+Use the [`jsonify`] function to inspect a data structure:
+
+```go-html-template
+<pre>{{ jsonify (dict "indent" "  ") .Params }}</pre>
+```
+
+```text
+{
+  "date": "2023-11-10T15:10:42-08:00",
+  "draft": false,
+  "iscjklanguage": false,
+  "lastmod": "2023-11-10T15:10:42-08:00",
+  "publishdate": "2023-11-10T15:10:42-08:00",
+  "tags": [
+    "foo",
+    "bar"
+  ],
+  "title": "My first post"
+}
+```
+
+{{% 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
+{{ $value := 42 }}
+{{ 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

docs/content/en/troubleshooting/logging.md

@@ -0,0 +1,56 @@
+---
+title: Logging
+description: Enable logging to inspect events while building your site.
+categories: [troubleshooting]
+keywords: []
+menu:
+  docs:
+    parent: troubleshooting
+    weight: 30
+weight: 30
+toc: true
+---
+
+## Command line
+
+Enable console logging with the `--logLevel` command line flag.
+
+Hugo has four logging levels:
+
+error
+: Display error messages only.
+
+```sh
+hugo --logLevel error
+```
+
+warn
+: Display warning and error messages.
+
+```sh
+hugo --logLevel warn
+```
+
+info
+: Display information, warning, and error messages.
+
+```sh
+hugo --logLevel info
+```
+
+debug
+: Display debug, information, warning, and error messages.
+
+```sh
+hugo --logLevel debug
+```
+
+{{% note %}}
+If you do not specify a logging level with the `--logLevel` flag, warnings and errors are always displayed.
+{{% /note %}}
+
+## Template functions
+
+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 >}}

docs/content/en/troubleshooting/performance.md

@@ -0,0 +1,94 @@
+---
+title: Performance
+description: Use template metrics and timers to identify opportunities to improve performance.
+categories: [troubleshooting]
+keywords: []
+menu:
+  docs:
+    parent: troubleshooting
+    weight: 60
+weight: 60
+toc: true
+aliases: [/troubleshooting/build-performance/]
+---
+
+## 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:
+
+```sh
+hugo --templateMetrics --templateMetricsHints
+```
+
+The result will look something like this:
+
+```text
+Template Metrics:
+
+     cumulative       average       maximum      cache  percent  cached  total  
+       duration      duration      duration  potential   cached   count  count  template
+     ----------      --------      --------  ---------  -------  ------  -----  --------
+  36.037476822s  135.990478ms  225.765245ms         11        0       0    265  partials/head.html
+  35.920040902s  164.018451ms  233.475072ms          0        0       0    219  articles/single.html
+  34.163268129s  128.917992ms  224.816751ms         23        0       0    265  partials/head/meta/opengraph.html
+   1.041227437s     3.92916ms  186.303376ms         47        0       0    265  partials/head/meta/schema.html
+   805.628827ms   27.780304ms  114.678523ms          0        0       0     29  _default/list.html
+    624.08354ms   15.221549ms  108.420729ms          8        0       0     41  partials/utilities/render-page-collection.html
+   545.968801ms     775.523µs  105.045775ms          0        0       0    704  _default/summary.html
+   334.680981ms    1.262947ms  127.412027ms        100        0       0    265  partials/head/js.html
+   272.763205ms    2.050851ms   24.371757ms          0        0       0    133  _default/_markup/render-codeblock.html
+   230.490038ms    8.865001ms    177.4615ms          0        0       0     26  shortcodes/template.html
+   176.921913ms  176.921913ms  176.921913ms          0        0       0      1  examples.tmpl
+   163.951469ms   14.904679ms   70.267953ms          0        0       0     11  articles/list.html
+    153.07021ms     577.623µs   73.593597ms        100        0       0    265  partials/head/init.html
+   150.910984ms  150.910984ms  150.910984ms          0        0       0      1  _default/single.html
+   146.785804ms  146.785804ms  146.785804ms          0        0       0      1  _default/contact.html
+   115.364617ms  115.364617ms  115.364617ms          0        0       0      1  authors/term.html
+    87.392071ms     329.781µs   10.687132ms        100        0       0    265  partials/head/css.html
+    86.803122ms   86.803122ms   86.803122ms          0        0       0      1  _default/home.html
+```
+
+From left to right, the columns represent:
+
+cumulative duration
+: The cumulative time spent executing the template.
+
+average duration
+: The average time spent executing the template.
+
+maximum duration
+: The maximum time spent executing the template.
+
+cache potential
+: Displayed as a percentage, any partial template with a 100% cache potential should be called with the [`partialCached`] function instead of the [`partial`] function. See the [caching](#caching) section below.
+
+percent cached
+: The number of times the rendered templated was cached divided by the number of times the template was executed.
+
+cached count
+: The number of times the rendered templated was cached.
+
+total count
+: The number of times the template was executed.
+
+template
+: The path to the template, relative to the layouts directory.
+
+[`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.
+{{% /note %}}
+
+## Caching
+
+Some partial templates such as sidebars or menus are executed many times during a site build. Depending on the content within the partial template and the desired output, the template may benefit from caching to reduce the number of executions. The [`partialCached`] template function provides caching capabilities for partial templates.
+
+{{% 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 %}}
+
+## Timers
+
+Use the `debug.Timer` function to determine execution time for a block of code, useful for finding performance bottle necks in templates. See [details](/functions/debug/timer/).