docs: prefix child options with their parent (renovatebot#41828)

This also makes sure that our URL fragments should be more consistent
over the years, as duplicate names (across parent and child options)
cannot clash.

This also corrects links from the code to include the new fragment.

Co-authored-by: Claude Sonnet 4.6 <jamie.tanna+claude-code@mend.io>

Author: jamietanna

docs/usage/configuration-options.md

@@ -34,7 +34,7 @@ Set to `off` if changelog fetching is causing a problem.
 
 Set to `branch` if you have an advanced use case where you're embedding changelogs in the Git commit itself, we don't recommend this due to its potential size.
 
-### [`changelogUrl`](../configuration-options.md#changelogurl)
+### [`changelogUrl`](../configuration-options.md#packageruleschangelogurl)
 
 This doesn't help with _fetching_ the changelogs, but if you configure it then Renovate will include a link to this URL in the PR body, so users can click through to read the changelog.
 

docs/usage/key-concepts/changelogs.md

@@ -1041,7 +1041,7 @@ If you use the Mend Renovate Enterprise Edition (Renovate EE) and:
 
 Then you must set this variable at the _server_ and the _workers_.
 
-But if you have specified the token as a [`matchConfidence`](configuration-options.md#matchconfidence) `packageRule`, you only need to set this variable at the _workers_.
+But if you have specified the token as a [`matchConfidence`](configuration-options.md#packagerulesmatchconfidence) `packageRule`, you only need to set this variable at the _workers_.
 
 This feature is in private beta.
 

docs/usage/self-hosted-configuration.md

@@ -77,7 +77,7 @@ If this does not happen, for whatever reason, Renovate can not show the changelo
 
 You can use these config options to let Renovate find the correct changelog:
 
-- [`changelogUrl`](https://docs.renovatebot.com/configuration-options/#changelogurl)
+- [`changelogUrl`](https://docs.renovatebot.com/configuration-options/#packageruleschangelogurl)
 
 Read the [Renovate docs, key concepts page for changelogs](https://docs.renovatebot.com/key-concepts/changelogs/) to learn more about how Renovate fetches and displays changelogs.
 
@@ -105,7 +105,7 @@ To check if Renovate can find the source URLs for your package:
 1. Read the Renovate docs for the datasource.
 1. Look for a table in the docs that shows if the datasource returns source URLs.
 
-If Renovate does not find the right source URls automatically: use the [`sourceUrl` config option](https://docs.renovatebot.com/configuration-options/#sourceurl).
+If Renovate does not find the right source URls automatically: use the [`sourceUrl` config option](https://docs.renovatebot.com/configuration-options/#packagerulessourceurl).
 
 To locate the source repository, Renovate requires:
 

lib/data/readme.md

@@ -23,12 +23,12 @@ The first two required fields are `managerFilePatterns` and `matchStrings`:
 
 Before Renovate can look up a dependency and decide about updates, it must have this info about each dependency:
 
-| Info type                                            | Required | Notes                                                     | Docs                                                                           |
-| :--------------------------------------------------- | :------- | :-------------------------------------------------------- | :----------------------------------------------------------------------------- |
-| Name of the dependency                               | Yes      |                                                           |                                                                                |
-| `datasource`                                         | Yes      | Example datasources: npm, Docker, GitHub tags, and so on. | [Supported datasources](../../datasource/index.md#supported-datasources)       |
-| Version scheme to use. Defaults to `semver-coerced`. | Yes      | You may set another version scheme, like `pep440`.        | [Supported versioning schemes](../../versioning/index.md#supported-versioning) |
-| `fileFormat`                                         | Yes      | Must be either `json`, `yaml` or `toml`.                  | [`Configuration Options`](../../../configuration-options.md#fileformat)        |
+| Info type                                            | Required | Notes                                                     | Docs                                                                                  |
+| :--------------------------------------------------- | :------- | :-------------------------------------------------------- | :------------------------------------------------------------------------------------ |
+| Name of the dependency                               | Yes      |                                                           |                                                                                       |
+| `datasource`                                         | Yes      | Example datasources: npm, Docker, GitHub tags, and so on. | [Supported datasources](../../datasource/index.md#supported-datasources)              |
+| Version scheme to use. Defaults to `semver-coerced`. | Yes      | You may set another version scheme, like `pep440`.        | [Supported versioning schemes](../../versioning/index.md#supported-versioning)        |
+| `fileFormat`                                         | Yes      | Must be either `json`, `yaml` or `toml`.                  | [`Configuration Options`](../../../configuration-options.md#custommanagersfileformat) |
 
 #### Required fields to be present in the resulting structure returned by the jsonata query
 

lib/modules/manager/custom/jsonata/readme.md

@@ -764,7 +764,7 @@ describe('util/package-rules/index', () => {
       expect(error).toMatchObject(new Error(MISSING_API_CREDENTIALS));
       expect(error.validationError).toBe('Missing credentials');
       expect(error.validationMessage).toBe(
-        'The `matchConfidence` matcher in `packageRules` requires authentication. Please refer to the [documentation](https://docs.renovatebot.com/configuration-options/#matchconfidence) and add the required host rule.',
+        'The `matchConfidence` matcher in `packageRules` requires authentication. Please refer to the [documentation](https://docs.renovatebot.com/configuration-options/#packagerulesmatchconfidence) and add the required host rule.',
       );
     });
   });

lib/util/package-rules/index.spec.ts

@@ -29,7 +29,7 @@ export class MergeConfidenceMatcher extends Matcher {
       error.validationSource = 'MatchConfidence Authenticator';
       error.validationError = 'Missing credentials';
       error.validationMessage =
-        'The `matchConfidence` matcher in `packageRules` requires authentication. Please refer to the [documentation](https://docs.renovatebot.com/configuration-options/#matchconfidence) and add the required host rule.';
+        'The `matchConfidence` matcher in `packageRules` requires authentication. Please refer to the [documentation](https://docs.renovatebot.com/configuration-options/#packagerulesmatchconfidence) and add the required host rule.';
       throw error;
     }
 

lib/util/package-rules/merge-confidence.ts

@@ -29,7 +29,9 @@ describe('docs/documentation', () => {
       const content = await fs.readFile(`docs/usage/${file}`, 'utf8');
       const reg = regEx(`##\\s${configOption}[\\s\\S]+?\n##\\s`);
       const match = reg.exec(content);
-      const subHeadersMatch = match?.[0]?.matchAll(/\n###\s(?<child>\w+)\n/g);
+      const subHeadersMatch = match?.[0]?.matchAll(
+        /\n###\s(?<child>[\w.]+)\n/g,
+      );
       if (subHeadersMatch) {
         for (const subHeaderStr of subHeadersMatch) {
           if (subHeaderStr?.groups?.child) {
@@ -86,10 +88,15 @@ describe('docs/documentation', () => {
           .filter((option) => option.stage !== 'global')
           .filter((option) => !option.globalOnly)
           .filter((option) => option.parents)
-          .map((option) => option.name)
           .filter(
-            (header) =>
-              header !== 'managerFilePatterns' && header !== 'enabled',
+            (option) =>
+              option.name !== 'managerFilePatterns' &&
+              option.name !== 'enabled',
+          )
+          .flatMap((option) =>
+            (option.parents ?? [])
+              .filter((parent) => parent !== '.')
+              .map((parent) => `${parent}.${option.name}`),
           )
           .sort();
       }

test/docs/documentation.spec.ts

@@ -294,32 +294,48 @@ export async function generateConfig(dist: string, bot = false): Promise<void> {
       // TODO: fix types (#22198,#9610)
       const el: Record<string, any> = { ...option };
 
-      if (!indexed[option.name]) {
-        throw new Error(
-          `Config option "${option.name}" is missing an entry in ${configFile}`,
-        );
+      // Child options are indexed as "parent.optionName"; collect all matching keys
+      let lookupKeys: string[] = [];
+      for (const parent of option.parents ?? []) {
+        if (parent !== '.') {
+          const key = `${parent}.${option.name}`;
+          if (indexed[key]) {
+            lookupKeys.push(key);
+          }
+        }
+      }
+      // Fall back to plain name for top-level ## options (e.g. enabled, managerFilePatterns)
+      if (lookupKeys.length === 0) {
+        if (!indexed[option.name]) {
+          throw new Error(
+            `Config option "${option.name}" is missing an entry in ${configFile}`,
+          );
+        }
+        lookupKeys = [option.name];
       }
-
-      const [headerIndex, footerIndex] = indexed[option.name];
 
       el.cli = getCliName(option);
       el.env = getEnvName(option);
       stringifyArrays(el);
 
-      configOptionsRaw[headerIndex] +=
-        `\n${option.description}\n\n` +
-        genTable(Object.entries(el), option.type, option.default);
+      for (const key of lookupKeys) {
+        const [headerIndex, footerIndex] = indexed[key];
 
-      if (el.advancedUse) {
-        configOptionsRaw[headerIndex] += generateAdvancedUse();
-      }
+        configOptionsRaw[headerIndex] +=
+          `\n${option.description}\n\n` +
+          genTable(Object.entries(el), option.type, option.default);
 
-      if (el.experimental) {
-        configOptionsRaw[footerIndex] += genExperimentalMsg(el);
-      }
+        if (el.advancedUse) {
+          configOptionsRaw[headerIndex] += generateAdvancedUse();
+        }
 
-      if (is.nonEmptyString(el.deprecationMsg)) {
-        configOptionsRaw[footerIndex] += genDeprecationMsg(el);
+        if (el.experimental) {
+          configOptionsRaw[footerIndex] += genExperimentalMsg(el);
+        }
+
+        if (is.nonEmptyString(el.deprecationMsg)) {
+          configOptionsRaw[footerIndex] += genDeprecationMsg(el);
+        }
       }
     });
 

tools/docs/config.ts

@@ -1,3 +1,4 @@
+import { getOptions } from '../../lib/config/options/index.ts';
 import {
   allowedFields,
   exposedConfigOptions,
@@ -6,13 +7,23 @@ import { readFile, updateFile } from '../utils/index.ts';
 import { replaceContent } from './utils.ts';
 
 export async function generateTemplates(dist: string): Promise<void> {
+  const options = getOptions();
+  const optionParentMap = new Map(
+    options
+      .filter((o) => o.parents?.length)
+      .map((o) => [o.name, o.parents![0]]),
+  );
+
   let exposedConfigOptionsText =
     'The following configuration options are passed through for templating: \n';
   exposedConfigOptionsText += exposedConfigOptions
-    .map(
-      (field) =>
-        ` - [${field}](configuration-options.md#${field.toLowerCase()})`,
-    )
+    .map((field) => {
+      const parent = optionParentMap.get(field);
+      const anchor = parent
+        ? `${parent}${field}`.toLowerCase()
+        : field.toLowerCase();
+      return ` - [${field}](configuration-options.md#${anchor})`;
+    })
     .join('\n');
 
   let runtimeText =