Merge branch 'docs-nested-arrays-merged-yaml' into 'master'

Add note explaining that nested arrays are OK

See merge request gitlab-org/gitlab!77554

doc/ci/pipeline_editor/index.md

@@ -83,7 +83,41 @@ where:
 - Configuration imported with [`include`](../yaml/index.md#include) is copied into the view.
 - Jobs that use [`extends`](../yaml/index.md#extends) display with the
   [extended configuration merged into the job](../yaml/yaml_optimization.md#merge-details).
-- YAML anchors are [replaced with the linked configuration](../yaml/yaml_optimization.md#anchors).
+- [YAML anchors](../yaml/yaml_optimization.md#anchors) are replaced with the linked configuration.
+- [YAML `!reference` tags](../yaml/yaml_optimization.md#reference-tags) are also replaced
+  with the linked configuration.
+
+Using `!refence` tags can cause nested configuration that display with
+multiple hyphens (`-`) in the expanded view. This behavior is expected, and the extra
+hyphens do not affect the job's execution. For example, this configuration and
+fully expanded version are both valid:
+
+- `.gitlab-ci.yml` file:
+
+  ```yaml
+  .python-req:
+    script:
+      - pip install pyflakes
+
+  lint-python:
+    image: python:latest
+    script:
+      - !reference [.python-req, script]
+      - pyflakes python/
+  ```
+
+- Expanded configuration in **View merged YAML** tab:
+
+  ```yaml
+  ".python-req":
+    script:
+    - pip install pyflakes
+  lint-python:
+    script:
+    - - pip install pyflakes  # <- The extra hyphens do not affect the job's execution.
+    - pyflakes python/
+    image: python:latest
+  ```
 
 ## Commit changes to CI configuration