Merge branch 'eread/fix-misc-markdown-formatting-issues-docs' into 'main'

Fix miscellaneous Markdown formatting issues

See merge request https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6347

Merged-by: Evan Read <eread@gitlab.com>
Approved-by: Sam Roque-Worcel <sroque-worcel@gitlab.com>
Approved-by: Uma Chandran <uchandran@gitlab.com>
Reviewed-by: Uma Chandran <uchandran@gitlab.com>

Author: eread

docs/configuration/advanced-configuration.md

@@ -82,22 +82,20 @@ For more information, see:
 - [Long polling for runners](https://docs.gitlab.com/ci/runners/long_polling/)
 - [Workhorse configuration](https://docs.gitlab.com/development/workhorse/configuration/)
 
-**Symptoms:**
+Symptoms:
 
 - Jobs from some projects experience delays before starting (duration matches your GitLab instance long polling timeout)
 - Jobs from other projects run immediately
 - Warning message in runner logs: `CONFIGURATION: Long polling issues detected`
 
-**Common problematic scenarios:**
+Common problematic scenarios:
 
 - Worker starvation bottleneck: The `concurrent` setting is less than the number of runners (severe bottleneck)
 - Request bottleneck: Runners with `request_concurrency=1` cause job delays during long polling
 - Build limit bottleneck: Runners with low `limit` settings (≤2) combined with `request_concurrency=1`
 
-**Solution options:**
-
-GitLab Runner automatically detects the problem scenarios and provides tailored solutions in the warning messages.
-Common solutions include:
+GitLab Runner automatically detects the problem scenarios and provides tailored solutions in the
+warning messages. Common solutions include:
 
 - Increase the `concurrent` setting to exceed the number of runners.
 - Set the `request_concurrency` value for high-volume runners to a value higher than 1 (default is 1).
@@ -107,9 +105,9 @@ Common solutions include:
   see the [feature flags documentation](feature-flags.md).
 - Balance `limit` settings with expected job volume.
 
-**Example problematic configurations:**
+##### Example problematic configurations
 
-**Scenario 1: Worker starvation bottleneck**
+Scenario 1: Worker starvation bottleneck:
 
 ```toml
 concurrent = 2  # Only 2 concurrent workers
@@ -122,7 +120,7 @@ concurrent = 2  # Only 2 concurrent workers
   name = "runner-3"  # 3 runners, only 2 workers - severe bottleneck
 ```
 
-**Scenario 2: Request bottleneck**
+Scenario 2: Request bottleneck:
 
 ```toml
 concurrent = 4  # 4 workers available
@@ -133,7 +131,7 @@ concurrent = 4  # 4 workers available
   limit = 10               # Can handle 10 jobs, but only 1 request slot
 ```
 
-**Scenario 3: Build limit bottleneck**
+Scenario 3: Build limit bottleneck:
 
 ```toml
 concurrent = 4
@@ -145,7 +143,7 @@ concurrent = 4
   # Creates severe bottleneck: builds at capacity + request slot blocked by long polling
 ```
 
-**Example corrected configuration:**
+##### Example corrected configuration
 
 ```toml
 concurrent = 4  # Adequate worker capacity
@@ -760,11 +758,11 @@ precedence is taken into account:
 1. Credentials configured with `DOCKER_AUTH_CONFIG`.
 1. Credentials configured locally on the GitLab Runner host with `~/.docker/config.json`
    or `~/.dockercfg` files (for example, by running `docker login` on the host).
-1. Credentials sent by default with a job's payload (for example, credentials for the *integrated
-   registry* described earlier).
+1. Credentials sent by default with a job's payload (for example, credentials for the integrated
+   registry described earlier).
 
 The first credentials found for the registry are used. So for example,
-if you add credentials for the *integrated registry* with the
+if you add credentials for the integrated registry with the
 `DOCKER_AUTH_CONFIG` variable, then the default credentials are overridden.
 
 ## The `[runners.parallels]` section

docs/configuration/autoscale.md

@@ -424,7 +424,7 @@ for the rest of the week, and on the weekends, no pipelines are started.
 These periods can be configured with the help of `[[runners.machine.autoscaling]]` sections.
 Each of them supports setting `IdleCount` and `IdleTime` based on a set of `Periods`.
 
-**How autoscaling periods work**
+### How autoscaling periods work
 
 In the `[runners.machine]` settings, you can add multiple `[[runners.machine.autoscaling]]` sections, each one with its own `IdleCount`, `IdleTime`, `Periods` and `Timezone` properties. A section should be defined for each configuration, proceeding in order from the most general scenario to the most specific scenario.
 
@@ -456,7 +456,7 @@ The rest of the time, the values are taken from the defaults in the root - `Idle
 {{< alert type="note" >}}
 
 The 59th second of the last
-minute in any period that you specify is *not* be considered part of the
+minute in any period that you specify is not be considered part of the
 period. For more information, see [issue #2170](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2170).
 
 {{< /alert >}}

docs/configuration/configuring_runner_operator.md

@@ -407,17 +407,15 @@ fatal: detected dubious ownership in repository at '/builds/gitlab-org/gitlab-ru
 
 This error indicates that the repository was cloned by user ID `1001` (helper container), but a different user ID in the build container is attempting to access it.
 
-**Solution**
-
-Configure your build container's security context to match the helper container's user ID and group ID:
+Solution: configure your build container's security context to match the helper container's user ID and group ID:
 
 ```toml
 [runners.kubernetes.build_container_security_context]
 run_as_user = 1001
 run_as_group = 1001
 ```
 
-**Additional notes**
+Additional notes:
 
 - These settings ensure consistent file ownership between the container that clones the repository and the container that builds it.
 - If you've customized your helper image with different user ID or group IDs, adjust these values accordingly.

docs/configuration/macos_setup.md

@@ -116,7 +116,7 @@ When you create and register the runner:
 After you register the runner, a success message displays in the command-line:
 
 ```shell
-> Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!
+Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!
 ```
 
 To view the runner:

docs/configuration/runner_autoscale_aws_fargate/_index.md

@@ -256,9 +256,9 @@ Now install GitLab Runner on the Ubuntu instance.
    - If `EnablePublicIP` is set to true, the public IP of the task container is gathered to perform the SSH connection.
    - If `EnablePublicIP` is set to false:
      - The Fargate driver uses the task container's private IP. To set up a connection when set to `false`, the VPC Security Group must
-     have an inbound rule for Port 22 (SSH), where the source is the VPC CIDR.
+       have an inbound rule for Port 22 (SSH), where the source is the VPC CIDR.
      - To fetch external dependencies, provisioned AWS Fargate containers must have access to the public internet. To provide
-     public internet access for AWS Fargate containers, you can use a NAT Gateway in the VPC.
+       public internet access for AWS Fargate containers, you can use a NAT Gateway in the VPC.
 
    - The port number of the SSH server is optional. If omitted, the default SSH port (22) is used.
    - For more information about the section settings, see the [Fargate driver documentation](https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/fargate/-/tree/master/docs#configuration).

docs/executors/kubernetes/_index.md

@@ -127,6 +127,7 @@ You can either:
 You can use the following YAML role definition to create a role with the required permissions.
 
 <!-- k8s_api_permissions_role_yaml_start -->
+
 ```yaml
 apiVersion: rbac.authorization.k8s.io/v1
 kind: Role
@@ -188,6 +189,7 @@ rules:
   - "create"
   - "get"
 ```
+
 <!-- k8s_api_permissions_role_yaml_end -->
 
 Additional details:
@@ -2392,7 +2394,7 @@ In GitLab 15.1 and later, the entrypoint defined in a Docker image is used with
 
 The container entry point has the following known issues:
 
-- <a id="open-valid-shell"></a> If an entrypoint is defined in the Dockerfile for an image, it must open a valid shell. Otherwise, the job hangs.
+- If an entrypoint is defined in the Dockerfile for an image, it must open a valid shell. Otherwise, the job hangs.
 
   - To open a shell, the system passes the command as
     [`args`](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#entrypoint)
@@ -2409,7 +2411,7 @@ The container entry point has the following known issues:
 Before GitLab Runner 17.4:
 
 - The entrypoint logs were not forwarded to the build's log.
-- With the Kubernetes executor with `kube exec`, GitLab Runner did not wait for the entrypoint to open a shell (see [above](#open-valid-shell)).
+- With the Kubernetes executor with `kube exec`, GitLab Runner did not wait for the entrypoint to open a shell (see earlier in this section).
 
 Starting with GitLab Runner 17.4, the entrypoint logs are now forwarded. The system waits
 for the entrypoint to run and spawn the shell. This has the following
@@ -2419,7 +2421,7 @@ implications:
   longer than `poll_timeout` (default: 180 s), the build fails. The
   `poll_timeout` value (and potentially `poll_interval`)
   must be adapted if the entrypoint is expected to run longer.
-- When `FF_KUBERNETES_HONOR_ENTRYPOINT` *and* `FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY` are set, the system adds a
+- When `FF_KUBERNETES_HONOR_ENTRYPOINT` and `FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY` are set, the system adds a
   [startup probe](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-startup-probes)
   to the build container, so that it knows when the entrypoint is spawning
   the shell. If a custom entrypoint uses the provided `args`

docs/shells/_index.md

@@ -80,9 +80,9 @@ fi
 Executors that load shell profiles:
 
 - [`shell`](../executors/shell.md)
-- [`parallels`](../executors/parallels.md)  (The shell profile of the *target* virtual machine is loaded)
-- [`virtualbox`](../executors/virtualbox.md)  (The shell profile of the *target* virtual machine is loaded)
-- [`ssh`](../executors/ssh.md) (The shell profile of the *target* machine is loaded)
+- [`parallels`](../executors/parallels.md) (The shell profile of the target virtual machine is loaded)
+- [`virtualbox`](../executors/virtualbox.md) (The shell profile of the target virtual machine is loaded)
+- [`ssh`](../executors/ssh.md) (The shell profile of the target machine is loaded)
 
 ## PowerShell
 

magefiles/kubernetes/docs/generate_permissions.go

@@ -64,7 +64,7 @@ func GeneratePermissionsDocs(roleName, roleNamespace string, permissions Permiss
 		return err
 	}
 
-	roleYamlContent := fmt.Sprintf("```yaml\n%s\n```\n", strings.TrimSpace(roleYaml))
+	roleYamlContent := fmt.Sprintf("\n```yaml\n%s\n```\n\n", strings.TrimSpace(roleYaml))
 
 	newDocsFile, err = replace(roleYamlPlaceholderName, newDocsFile, roleYamlContent)
 	if err != nil {