Update troubleshooting section

Closes #2316

.cspell.json

@@ -116,14 +116,18 @@
     "dring",
     "getenv",
     "gohugo",
+    "inor",
     "jdoe",
     "milli",
     "rgba",
     "rsmith",
     "stringifier",
     "struct",
+    "tdewolff",
     "tjones",
     "toclevels",
-    "vals"
+    "vals",
+    "xfeff",
+    "zgotmplz"
   ]
 }

content/en/troubleshooting/_index.md

@@ -1,7 +1,7 @@
 ---
-title: Troubleshoot
+title: Troubleshooting
 linkTitle: Overview
-description: Frequently asked questions and known issues pulled from the Hugo Discuss forum.
+description: Use these techniques when troubleshooting your site.
 categories: []
 keywords: []
 menu:
@@ -10,9 +10,6 @@ menu:
     parent: troubleshooting
     weight: 10
 weight: 10
-aliases: [/troubleshooting/faqs/,/faqs/]
 ---
 
-The Troubleshooting section includes known issues, recent workarounds, and FAQs pulled from the [Hugo Discussion Forum][forum].
-
-[forum]: https://discourse.gohugo.io
+Use these techniques when troubleshooting your site.

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. For more information see. 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 because, but a case-insensitive search of the output for `HAHAHUGO` is likely to catch the majority of cases without producing false positives.

content/en/troubleshooting/deprecation.md

@@ -0,0 +1,51 @@
+---
+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.
+
+[article]: https://en.wikipedia.org/wiki/Deprecation
+
+Think of deprecation as a statement of intent. This Wikipedia [article] describes common reasons for deprecation:
+
+- The feature has been replaced by a more powerful alternative.
+- The feature contains a design flaw.
+- The 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.