From ad78e851aae85d6c2ed9f874842f3c56ed10bf02 Mon Sep 17 00:00:00 2001
From: Florian Greinacher <florian@greinacher.de>
Date: Tue, 9 May 2023 05:38:37 +0200
Subject: [PATCH] docs: add config-validation chapter (#21969)

Co-authored-by: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com>
---
 docs/usage/.pages                             |  1 +
 docs/usage/config-validation.md               | 22 +++++++++++++++++++
 .../getting-started/installing-onboarding.md  |  8 +------
 docs/usage/troubleshooting.md                 |  5 +++++
 4 files changed, 29 insertions(+), 7 deletions(-)
 create mode 100644 docs/usage/config-validation.md

diff --git a/docs/usage/.pages b/docs/usage/.pages
index e6e2117b871bdd..f5d466abd10b82 100644
--- a/docs/usage/.pages
+++ b/docs/usage/.pages
@@ -6,6 +6,7 @@ nav:
       - 'Self-hosted': 'self-hosted-configuration.md'
       - 'Repository': 'configuration-options.md'
       - 'Presets': 'config-presets.md'
+      - 'Validation': 'config-validation.md'
   - ... | key-concepts
   - ... | modules
   - Language Support:
diff --git a/docs/usage/config-validation.md b/docs/usage/config-validation.md
new file mode 100644
index 00000000000000..7871cc5367d072
--- /dev/null
+++ b/docs/usage/config-validation.md
@@ -0,0 +1,22 @@
+---
+title: Config Validation
+description: How to validate Renovate's configuration.
+---
+
+# Config Validation
+
+All [`renovate` distributions](getting-started/running.md#available-distributions) contain a standalone validator program (`renovate-config-validator`) that can be used to validate Renovate's configuration.
+
+The validator program checks files passed as CLI arguments.
+If no argument is given, all [default locations](configuration-options.md) (if files exist) and the `RENOVATE_CONFIG_FILE` environment variable are checked.
+
+```console
+$ npm install --global renovate
+added 750 packages, and audited 751 packages in 51s
+$ renovate-config-validator
+INFO: Validating renovate.json
+INFO: Config validated successfully
+```
+
+You can configure a [pre-commit](https://pre-commit.com) hook to validate your configuration automatically.
+Please check out the [`renovatebot/pre-commit-hooks` repository](https://github.com/renovatebot/pre-commit-hooks) for more information.
diff --git a/docs/usage/getting-started/installing-onboarding.md b/docs/usage/getting-started/installing-onboarding.md
index f681575fcedea2..7b3275c2adde70 100644
--- a/docs/usage/getting-started/installing-onboarding.md
+++ b/docs/usage/getting-started/installing-onboarding.md
@@ -133,15 +133,9 @@ If you want to make config edits directly, follow these steps:
 1. Create a new Git branch to work on
 1. Install or update the `renovate` package globally (`npm i -g renovate` or `yarn global add renovate`) to get the `renovate-config-validator` program
 1. Edit your Renovate configuration file
-1. Validate your config by running `renovate-config-validator`
+1. [Validate your config](../config-validation.md)
 1. If the improved config passes the validation, merge the branch into your mainline branch
 
-The validator program checks files passed as CLI arguments.
-If no argument is given, all [default locations](../configuration-options.md) (if files exist) and the `RENOVATE_CONFIG_FILE` environment variable are checked.
-
-You can configure a [pre-commit](https://pre-commit.com) hook to validate your configuration automatically.
-Please check out the [`renovatebot/pre-commit-hooks` repository](https://github.com/renovatebot/pre-commit-hooks) for more information.
-
 ### Nuke config and re-onboard
 
 Perhaps you really liked the interactive onboarding PR and want to use it again.
diff --git a/docs/usage/troubleshooting.md b/docs/usage/troubleshooting.md
index 3ad9a414486f11..75d1ee1bb00777 100644
--- a/docs/usage/troubleshooting.md
+++ b/docs/usage/troubleshooting.md
@@ -64,3 +64,8 @@ If none of these steps have helped you, then create a new discussion post to get
 Please locate the relevant parts of the logs as described earlier before asking for help or posting a bug report.
 Do not expect the Renovate maintainers to read through the full logs when trying to help you, as that takes a lot of time on our part.
 If later it turns out that the full logs are necessary, you will be asked for them then.
+
+## Validating configuration changes
+
+Sometimes you will have to change your Renovate configuration to solve a problem.
+The [`renovate-config-validator` program](config-validation.md) helps validate such configuration changes without commiting them to your repository.