diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index 3b594df659d..c8d5ecb8eef 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -159,50 +159,55 @@ The `key` directive allows you to define the affinity of caching
 between jobs, allowing to have a single cache for all jobs,
 cache per-job, cache per-branch or any other way you deem proper.
 
-This allows you to fine tune caching, allowing you to cache data between different jobs or even different branches.
-The `cache:key` variable can use any of the [predefined variables](../variables/README.md):
+This allows you to fine tune caching, allowing you to cache data between
+different jobs or even different branches.
 
-Example configurations:
+The `cache:key` variable can use any of the [predefined variables](../variables/README.md).
+
+---
+
+**Example configurations**
 
 To enable per-job caching:
 
-    ```yaml
-    cache:
-      key: "$CI_BUILD_NAME"
-      untracked: true
-    ```
+```yaml
+cache:
+  key: "$CI_BUILD_NAME"
+  untracked: true
+```
 
 To enable per-branch caching:
 
-    ```yaml
-    cache:
-      key: "$CI_BUILD_REF_NAME"
-      untracked: true
-    ```
+```yaml
+cache:
+  key: "$CI_BUILD_REF_NAME"
+  untracked: true
+```
 
 To enable per-job and per-branch caching:
 
-    ```yaml
-    cache:
-      key: "$CI_BUILD_NAME/$CI_BUILD_REF_NAME"
-      untracked: true
-    ```
+```yaml
+cache:
+  key: "$CI_BUILD_NAME/$CI_BUILD_REF_NAME"
+  untracked: true
+```
 
 To enable per-branch and per-stage caching:
 
-    ```yaml
-    cache:
-      key: "$CI_BUILD_STAGE/$CI_BUILD_REF_NAME"
-      untracked: true
-    ```
+```yaml
+cache:
+  key: "$CI_BUILD_STAGE/$CI_BUILD_REF_NAME"
+  untracked: true
+```
 
-If you use **Windows Batch** to run your shell scripts you need to replace the `$` with `%`:
+If you use **Windows Batch** to run your shell scripts you need to replace
+`$` with `%`:
 
-    ```yaml
-    cache:
-      key: "%CI_BUILD_STAGE%/%CI_BUILD_REF_NAME%"
-      untracked: true
-    ```
+```yaml
+cache:
+  key: "%CI_BUILD_STAGE%/%CI_BUILD_REF_NAME%"
+  untracked: true
+```
 
 ## Jobs