docs: use titles for more code blocks (#25526)

docs/usage/bazel.md

@@ -36,16 +36,12 @@ Renovate:
 In this example, there is a `.bazelrc` file which imports another file called `.registry.bazelrc`.
 Both files have `--registry` values:
 
-```
-# -------------
-# .bazelrc File
-# -------------
+```title=".bazelrc"
 import .registry.bazelrc
 build --registry=https://raw.githubusercontent.com/bazelbuild/bazel-central-registry/main
+```
 
-# ----------------------
-# .registry.bazelrc File
-# ----------------------
+```title=".registry.bazelrc"
 build --registry=https://example.com/custom_registry
 ```
 
@@ -58,10 +54,7 @@ The final registry list is:
 
 In this example, a `.bazelrc` file has registry values with and without a configuration:
 
-```
-# -------------
-# .bazelrc File
-# -------------
+```title=".bazelrc"
 build:ci --registry=https://internal.server/custom_registry
 build --registry=https://raw.githubusercontent.com/bazelbuild/bazel-central-registry/main
 ```
@@ -164,8 +157,8 @@ Renovate extracts dependencies from the following repository rules:
 - `http_archive`
 - `http_file`
 
-It also recognizes when these repository rule names are prefixed with an
-underscore. For example, `_http_archive` is treated the same as `http_archive`.
+It also recognizes when these repository rule names are prefixed with an underscore.
+For example, `_http_archive` is treated the same as `http_archive`.
 
 ### `git_repository`
 

docs/usage/configuration-options.md

@@ -727,9 +727,8 @@ Each provided `matchString` will be matched individually to the content of the `
 If a `matchString` has multiple matches in a file each will be interpreted as an independent dependency.
 
 As example the following configuration will update all three lines in the Dockerfile.
-renovate.json:
 
-```json
+```json title="renovate.json"
 {
   "customManagers": [
     {
@@ -746,9 +745,7 @@ renovate.json:
 }
 ```
 
-A Dockerfile:
-
-```dockerfile
+```dockerfile title="Dockerfile"
 FROM amd64/ubuntu:18.04
 ENV GRADLE_VERSION=6.2 # gradle-version/gradle&versioning=maven
 ENV NODE_VERSION=10.19.0 # github-tags/nodejs/node&versioning=node
@@ -769,9 +766,7 @@ This is an example how this can work.
 The first custom manager will only upgrade `grafana/loki` as looks for the `backup` key then looks for the `test` key and then uses this result for extraction of necessary attributes.
 But the second custom manager will upgrade both definitions as its first `matchStrings` matches both `test` keys.
 
-renovate.json:
-
-```json
+```json title="renovate.json"
 {
   "customManagers": [
     {
@@ -798,9 +793,7 @@ renovate.json:
 }
 ```
 
-example.json:
-
-```json
+```json title="example.json"
 {
   "backup": {
     "test": {
@@ -829,9 +822,7 @@ To update multiple dependencies with `combination` you must define multiple cust
 
 Matched group values will be merged to form a single dependency.
 
-renovate.json:
-
-```json
+```json title="renovate.json"
 {
   "customManagers": [
     {
@@ -857,9 +848,7 @@ renovate.json:
 }
 ```
 
-Ansible variable file (YAML):
-
-```yaml
+```yaml title="Ansible variable file (YAML)"
 prometheus_image: "prom/prometheus"  // a comment
 prometheus_version: "v2.21.0" // a comment
 ------
@@ -916,16 +905,12 @@ Allows overwriting how the matched string is replaced.
 This allows for some migration strategies.
 E.g. moving from one Docker image repository to another one.
 
-`helm-values.yaml`:
-
-```yaml
+```yaml title="helm-values.yaml"
 # The image of the service <registry>/<repo>/<image>:<tag>
 image: my.old.registry/aRepository/andImage:1.18-alpine
 ```
 
-The regex definition:
-
-```json
+```json title="The regex definition"
 {
   "customManagers": [
     {
@@ -1630,7 +1615,7 @@ For example to also skip 404 responses then configure the following:
 Use this field to configure Renovate to abort runs for custom hosts.
 By default, Renovate will only abort for known public hosts, which has the downside that transient errors for other hosts can cause autoclosing of PRs.
 
-To abort Renovate runs for http failures from _any_ host:
+To abort Renovate runs for HTTP failures from _any_ host:
 
 ```json
 {
@@ -1769,7 +1754,7 @@ You usually don't need to configure it in a host rule if you have already config
 
 ### insecureRegistry
 
-Enable this option to allow Renovate to connect to an [insecure Docker registry](https://docs.docker.com/registry/insecure/) that is http only.
+Enable this option to allow Renovate to connect to an [insecure Docker registry](https://docs.docker.com/registry/insecure/) that is HTTP only.
 This is insecure and is not recommended.
 
 Example:
@@ -2764,9 +2749,7 @@ For example to apply a special label to `major` updates:
     This configuration option needs a Mend API key, and is in private beta testing only.
     API keys are not available for free or via the `renovatebot/renovate` repository.
 
-For example to group high merge confidence updates:
-
-```json
+```json title="Grouping high merge confidence updates"
 {
   "packageRules": [
     {
@@ -2797,9 +2780,7 @@ Source URLs are necessary in order to look up release notes.
 
 Using this field we can specify the exact URL to fetch release notes from.
 
-Example setting source URL for package "dummy":
-
-```json
+```json title="Setting the source URL for the dummy package"
 {
   "packageRules": [
     {
@@ -3447,9 +3428,7 @@ i.e. Renovate will run on the repository around the clock.
 The easiest way to define a schedule is to use a preset if one of them fits your requirements.
 See [Schedule presets](https://docs.renovatebot.com/presets-schedule/) for details and feel free to request a new one in the source repository if you think it would help others.
 
-Otherwise, here are some text schedules that are known to work:
-
-```
+```title="Some text schedules that are known to work"
 every weekend
 before 5:00am
 after 10pm and before 5:00am
@@ -3576,7 +3555,7 @@ You can set your own label name with the `"stopUpdatingLabel"` field:
 ## suppressNotifications
 
 Use this field to suppress various types of warnings and other notifications from Renovate.
-Example:
+For example:
 
 ```json
 {
@@ -3642,7 +3621,7 @@ You can edit these user-facing strings:
 - `ignoreOther`: Text of the PR comment for other (neither digest nor major) upgrades.
 - `ignoreTopic`: Topic of the PR comment.
 
-Example:
+For example:
 
 ```json
 {
@@ -3723,9 +3702,8 @@ Follow these steps:
 Once the above conditions are met, and you got one or more vulnerability alerts from GitHub for this repository, then Renovate tries to raise fix PRs.
 
 You may use the `vulnerabilityAlerts` configuration object to customize vulnerability-fix PRs.
-For example, to set a custom label and assignee:
 
-```json
+```json title="Setting a custom label and assignee"
 {
   "vulnerabilityAlerts": {
     "labels": ["security"],
@@ -3748,7 +3726,7 @@ For example, to set a custom label and assignee:
 
 To disable the vulnerability alerts feature, set `enabled=false` in a `vulnerabilityAlerts` config object, like this:
 
-```json
+```json title="Disabling vulnerability alerts"
 {
   "vulnerabilityAlerts": {
     "enabled": false

docs/usage/docker.md

@@ -51,9 +51,8 @@ You could then use this `packageRules` array, to tell Renovate to use `semver` v
 ```
 
 Another example is the official `python` image, which follows `pep440` versioning.
-You can tell Renovate to use the `pep440` versioning scheme with this set of `packageRules`:
 
-```json
+```json title="Telling Renovate to use the pep440 versioning scheme"
 {
   "packageRules": [
     {
@@ -202,7 +201,7 @@ We will explain how to authenticate for the most common registries.
 Here is an example of configuring a default Docker username/password in `config.js`.
 The Docker Hub password is stored in a process environment variable.
 
-```js
+```js title="config.js"
 module.exports = {
   hostRules: [
     {

docs/usage/examples/self-hosting.md

@@ -21,9 +21,8 @@ The same goes for any other third-party binary tool like `gradle` or `poetry` -
 
 Renovate is available for Docker via an automated build at [`renovate/renovate` on Docker Hub](https://hub.docker.com/r/renovate/renovate/).
 It builds `latest` based on the `main` branch and all SemVer tags are published too.
-For example, all the following are valid tags:
 
-```sh
+```sh title="Example of valid tags"
 docker run --rm renovate/renovate
 docker run --rm renovate/renovate:35
 docker run --rm renovate/renovate:35.14
@@ -46,9 +45,8 @@ docker run --rm -v "/path/to/your/config.js:/usr/src/app/config.js" renovate/ren
 
 Renovate's official Docker image is compatible with Kubernetes.
 The following is an example manifest of running Renovate against a GitHub Enterprise server.
-First the Kubernetes manifest:
 
-```yaml
+```yaml title="Kubernetes manifest"
 apiVersion: batch/v1
 kind: CronJob
 metadata:
@@ -79,7 +77,7 @@ spec:
 
 And the `secret.yaml` that goes with it:
 
-```yaml
+```yaml title="secret.yaml"
 apiVersion: v1
 kind: Secret
 metadata:
@@ -97,7 +95,7 @@ stringData:
 
 A `config.json` file can be added to the manifest using a `ConfigMap` as shown in the following example (using a "dry run" in github.com):
 
-```yaml
+```yaml title="Adding a config.json file to the manifest with configMap"
 ---
 apiVersion: v1
 kind: ConfigMap
@@ -261,10 +259,9 @@ If you're running against GitHub Enterprise Server, then change the `gitlab` val
 
 You can save this file as anything you want and then use the `RENOVATE_CONFIG_FILE` environment variable to tell Renovate where to find it.
 
-Most people use cron to schedule when Renovate runs, usually on an hourly schedule.
-Here's an example Bash script that you can point `cron` to:
+Most people use `cron` to schedule when Renovate runs, usually on an hourly schedule.
 
-```sh
+```sh title="Example bash script that you can point cron to"
 #!/bin/bash
 
 export PATH="/home/user/.yarn/bin:/usr/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:$PATH"
@@ -277,7 +274,7 @@ renovate
 ```
 
 Save the script file, and run the script manually.
-Only add the script to cron after you checked it works.
+Only add the script to `cron` after you checked it works.
 
 <!-- prettier-ignore -->
 !!! note
@@ -428,9 +425,8 @@ On Ubuntu/Debian and many Linux-based systems, this can be done by copying the s
 ### Renovate Docker image
 
 If you're using the official [Renovate Docker image](#docker) then we recommend you add the self-signed certificate and build your own modified Docker image.
-For example, the following `Dockerfile` is set up to use a self-signed certificate:
 
-```dockerfile
+```dockerfile title="Example of a Dockerfile that uses a self-signed certificate"
 FROM renovate/renovate
 
 # Changes to the certificate authority require root permissions

docs/usage/faq.md

@@ -81,9 +81,7 @@ Use the "Dependency Dashboard approval" workflow to get updates for certain pack
 
 The basic idea is that you create a new `packageRules` entry and describe what kind of package, or type of updates you want to approve beforehand.
 
-Say you want to manually approve all major `npm` package manager updates:
-
-```json
+```json title="Manually approve all major npm package manager updates"
 {
   "packageRules": [
     {
@@ -95,9 +93,7 @@ Say you want to manually approve all major `npm` package manager updates:
 }
 ```
 
-Or say you want to manually approve all major Jest updates:
-
-```json
+```json title="Manually approve all major Jest updates"
 {
   "packageRules": [
     {

docs/usage/getting-started/private-packages.md

@@ -67,9 +67,7 @@ In addition to the above options to match against a host, you need to add the cr
 Typically they are either `token`, or `username` + `password`.
 Other credential terms are not supported yet.
 
-Here is an example of some host rules:
-
-```json
+```json title="Example host rules"
 {
   "hostRules": [
     {
@@ -210,7 +208,7 @@ The environment variables used are: `GIT_CONFIG_KEY_0=url.https://${token}@githu
 Maybe you're running your own ChartMuseum server to host your private Helm Charts.
 This is how you connect to a private Helm repository:
 
-```js
+```js title="Connecting to a private Helm repository"
 module.exports = {
   hostRules: [
     {

docs/usage/golang.md

@@ -66,9 +66,8 @@ Renovate will commit all files changed within the `vendor/` folder.
 By default, Renovate will keep up with the latest version of the `go` binary.
 
 You can force Renovate to use a specific version of Go by setting a constraint.
-As an example, say you want Renovate to use the latest patch version of the `1.16` Go binary, you'd put this in your Renovate config:
 
-```json
+```json title="Getting Renovate to use the latest patch version of the 1.16 Go binary"
 {
   "constraints": {
     "go": "1.16"

docs/usage/java.md

@@ -106,7 +106,7 @@ Renovate can be configured to access more repositories and access repositories a
 This example shows how you can use a `config.js` file to configure Renovate for use with Artifactory.
 We're using environment variables to pass the Artifactory username and password to Renovate bot.
 
-```js
+```js title="config.js"
 module.exports = {
   hostRules: [
     {

docs/usage/key-concepts/automerge.md

@@ -35,9 +35,8 @@ If you have an API with 100% test coverage and Express is updated... automerge i
 
 The lowest risk type of update to automerge is probably `lockFileMaintenance`.
 When Renovate performs lock file maintenance, it leaves the project dependency definitions unchanged, but refreshes the lock file completely so that the latest versions according to the package file constraints are installed.
-Here is an example of automerging lock file maintenance:
 
-```json
+```json title="Example of automerging lock file maintenance"
 {
   "lockFileMaintenance": {
     "enabled": true,
@@ -52,7 +51,7 @@ Automerging lint tool updates can be a real time-saver.
 Sometimes an update to a lint tool or plugin definition causes tests to fail, and that is usually deliberate/intentional because the lint authors have added a new rule that you need to adhere to.
 But in many cases the new version(s) will pass tests, and if so then there's really nothing else to consider before merging, so they may as well be automerged:
 
-```json
+```json title="Example of automerging lint and Prettier development packages"
 {
   "packageRules": [
     {
@@ -68,7 +67,7 @@ But in many cases the new version(s) will pass tests, and if so then there's rea
 
 Non-major updates in SemVer ecosystems shouldn't have breaking changes (if they follow the spec), so many users enable automerge for these too:
 
-```json
+```json title="Example of automerging non-major updates in SemVer ecosystem"
 {
   "packageRules": [
     {
@@ -86,7 +85,7 @@ The `matchCurrentVersion` setting above is a rule to exclude any dependencies wh
 
 Say you want to automerge `patch` and `minor` updates for packages in the `group:ionic-nativeMonorepo` preset:
 
-```json
+```json title="Example of automerging patch and minor updates in a group from a preset"
 {
   "packageRules": [
     {
@@ -103,9 +102,7 @@ Say you want to automerge `patch` and `minor` updates for packages in the `group
 By default, Renovate uses platform-native automerge to speed up automerging.
 If you don't want Renovate to use the platform-native automerge, then set `platformAutomerge` to `false`.
 
-For example:
-
-```json
+```json title="Example of disabling platform-native automerge"
 {
   "lockFileMaintenance": {
     "enabled": true,

docs/usage/key-concepts/scheduling.md

@@ -52,9 +52,7 @@ By default, Renovate schedules use the UTC timezone.
 If you want Renovate to use your local time, use the `timezone` configuration option.
 The timezone must be a valid [IANA time zone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
 
-You can set a specific time zone in your local config file like this:
-
-```json
+```json title="Setting a specific timezone in your local config file"
 {
   "timezone": "America/Los_Angeles"
 }
@@ -66,9 +64,7 @@ Also read the [`timezone` config option docs](../configuration-options.md#timezo
 
 After you've set your local timezone, you can define "days of the week" or "hours of the day" in which Renovate is allowed to make changes.
 
-Examples of the kind of schedules you can create include:
-
-```
+```title="Examples of the kind of schedules you can create"
 every weekend
 before 5:00am
 [after 10pm, before 5:00am]
@@ -93,17 +89,15 @@ If you use the Mend Renovate App, the default is that Renovate will always be al
 Be sure to schedule enough time for Renovate to process your repository.
 Do not set schedules like "Run Renovate for an hour each Sunday" as you _will_ run into problems.
 
-Say you want Renovate to run each day before 4 am:
+Some config examples:
 
-```json
+```json title="Renovate should run each day before 4 am"
 {
   "schedule": ["before 4am"]
 }
 ```
 
-Or you could tell Renovate to run outside of common office hours like this:
-
-```json
+```json title="Renovate should run outside of common office hours"
 {
   "schedule": [
     "after 10pm every weekday",
@@ -123,9 +117,7 @@ These preset schedules only affect when Renovate bot checks for updates, and do
 
 The scheduling feature can be very useful for "noisy" packages that are updated frequently, such as `aws-sdk`.
 
-Say you want to restrict `aws-sdk` to weekly updates, you would create this package rule:
-
-```json
+```json title="Restrict aws-sdk to weekly updates"
 {
   "packageRules": [
     {

docs/usage/modules/manager/index.md

@@ -72,9 +72,7 @@ If there was a manager called `some-new-manager` you would enable it like this:
 
 #### Disabling managers
 
-To disable a specific manager like `gradle`, do this:
-
-```json
+```json title="Example of disabling a specific manager (gradle)"
 {
   "gradle": {
     "enabled": false

docs/usage/node.md

@@ -32,7 +32,7 @@ Renovate bot will then use that version constraint for npm when it creates a pul
 
 For example, if you want to use at least npm `8.1.0` and also allow newer versions of npm in the `8.x` range, you would put this in your `package.json` file:
 
-```json
+```json title="package.json"
 {
   "engines": {
     "npm": "^8.1.0"

docs/usage/noise-reduction.md

@@ -87,7 +87,7 @@ Remember our example of grouping all `eslint` packages?
 If you think about it, updates to `eslint` rules don't exactly need to be applied in real time!
 You don't want to get too far behind, so how about we update `eslint` packages only once a month?
 
-```json
+```json title="Update ESLint packages once a month"
 {
   "packageRules": [
     {
@@ -101,7 +101,7 @@ You don't want to get too far behind, so how about we update `eslint` packages o
 
 Or perhaps at least weekly:
 
-```json
+```json title="Update ESLint packages weekly"
 {
   "packageRules": [
     {
@@ -161,7 +161,7 @@ This is a lot better than you waking up to two PRs and then having to deal with
 Remember our running `eslint` example?
 Let's automerge it if all the linting updates pass:
 
-```json
+```json title="Automerge ESLint packages"
 {
   "packageRules": [
     {

docs/usage/python.md

@@ -33,7 +33,7 @@ But Renovate may not find all your files.
 
 You can tell Renovate where to find your file(s) by setting your own `fileMatch` regex:
 
-```json
+```json title="Setting a custom fileMatch regex"
 {
   "pip_requirements": {
     "fileMatch": ["my/specifically-named.file", "\\.requirements$"]
@@ -55,9 +55,7 @@ There are three ways to do this:
 
 ### index-url in `requirements.txt`
 
-You can set the index URL in the first line of the `requirements.txt`, for example:
-
-```
+```title="Setting index URL in first line of requirements.txt"
 --index-url http://example.com/private-pypi/
 some-package==0.3.1
 some-other-package==1.0.0
@@ -92,9 +90,7 @@ Fill the array with alternate index URL(s).
 
 ## Disabling Python support
 
-To disable all managers with `language` set to `python` in Renovate, do this:
-
-```json
+```json title="Disabling all managers where language is set to Python"
 {
   "python": {
     "enabled": false
@@ -103,9 +99,8 @@ To disable all managers with `language` set to `python` in Renovate, do this:
 ```
 
 Alternatively, you can use `enabledManagers` to tell Renovate what package managers it can use.
-For example, if you only want to use Renovate's `npm` package manager:
 
-```json
+```json title="Only use Renovate's npm package manager"
 {
   "enabledManagers": ["npm"]
 }

docs/usage/rust.md

@@ -36,9 +36,7 @@ You as user can set authentication for private crates by adding a `hostRules` co
 All token `hostRules` with a `hostType` (e.g. `github`, `gitlab`, `bitbucket`, etc.) and host rules without a `hostType` will be automatically setup for authentication.
 You can also configure a `hostRules` that's only for Cargo authentication (e.g. `hostType: 'cargo'`).
 
-Here's an example of authentication for a private GitHub and Cargo registry:
-
-```js
+```js title="Example of authentication for a private GitHub and Cargo registry:"
 module.exports = {
   hostRules: [
     {

docs/usage/self-hosted-configuration.md

@@ -88,7 +88,7 @@ If you use an environment variable or the CLI to set the value for `autodiscover
 Commas will be used as delimiter for a new filter.
 
 ```
-# DO NOT use commas inside the filter if your are using env or cli variables to configure it.
+# DO NOT use commas inside the filter if your are using env or CLI variables to configure it.
 RENOVATE_AUTODISCOVER_FILTER="/myapp/{readme.md,src/**}"
 
 # in this example you can use regex instead
@@ -393,9 +393,8 @@ The user-id (UID) and group-id (GID) must match the user that executes Renovate.
 
 Read the [Docker run reference](https://docs.docker.com/engine/reference/run/#user) for more information on user and group syntax.
 Set this to `1001:1002` to use UID 1001 and GID 1002.
-For example:
 
-```json
+```json title="Setting UID to 1001 and GID to 1002"
 {
   "dockerUser": "1001:1002"
 }
@@ -788,9 +787,7 @@ JSON files will be stored inside the `cacheDir` beside the existing file-based p
 
 ## repositoryCacheType
 
-Set this to an S3 URI to enable S3 backed repository cache.
-
-```ts
+```ts title="Set repositoryCacheType to an S3 URI to enable S3 backed repository cache"
 {
   repositoryCacheType: 's3://bucket-name';
 }

docs/usage/semantic-commits.md

@@ -26,17 +26,13 @@ There are some exceptions:
 
 You can override the default settings, and disable or enable semantic commits.
 
-If you want Renovate to use semantic commits: add `":semanticCommits"` to your `extends` array:
-
-```json
+```json title="If you want Renovate to use semantic commits"
 {
   "extends": [":semanticCommits"]
 }
 ```
 
-If you want Renovate to stop using semantic commits: add `":semanticCommitsDisabled"` to your `extends` array:
-
-```json
+```json title="If you want Renovate to stop using semantic commits"
 {
   "extends": [":semanticCommitsDisabled"]
 }

docs/usage/user-stories/maintaining-aur-packages-with-renovate.md

@@ -41,7 +41,7 @@ There isn’t an AUR or `PKGBUILD` manager, but there is a [regex manager](https
 
 I can create a `renovate.json` configuration with the following custom manager configuration:
 
-```json
+```json title="renovate.json"
 {
   "customManagers": [
     {