Merge branch '31481-document-custom-sections' into 'master'

Documentation for adding custom collapsible sections to job logs. For #31481

Closes #31481

See merge request gitlab-org/gitlab!24468

doc/ci/pipelines.md

@@ -166,6 +166,43 @@ In the following example:
 
 ![Collapsible sections](img/collapsible_log_v12_6.png)
 
+#### Custom collapsible sections
+
+You can create collapsible sections in job logs by manually outputting special codes
+that GitLab will use to determine what sections to collapse:
+
+- Section start marker: `section_start:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K` + `TEXT_OF_SECTION_HEADER`
+- Section end marker: `section_end:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K`
+
+You must add these codes to the script section of the CI configuration. For example,
+using `echo`:
+
+```yaml
+job1:
+  script:
+    - echo -e "section_start:`date +%s`:my_first_section\r\e[0KHeader of the 1st collapsible section"
+    - echo 'this line should be hidden when collapsed'
+    - echo -e "section_end:`date +%s`:my_first_section\r\e[0K"
+```
+
+In the example above:
+
+- `date +%s`: The Unix timestamp (for example `1560896352`).
+- `my_first_section`: The name given to the section.
+- `\r\e[0K`: Prevents the section markers from displaying in the rendered (colored)
+  job log, but they are displayed in the raw job log. To see them, in the top right
+  of the job log, click **{doc-text}** (**Show complete raw**).
+  - `\r`: carriage return.
+  - `\e[0K`: clear line ANSI escape code.
+
+Sample raw job log:
+
+```plaintext
+section_start:1560896352:my_first_section\r\e[0KHeader of the 1st collapsible section
+this line should be hidden when collapsed
+section_end:1560896353:my_first_section\r\e[0K
+```
+
 ## Configuring pipelines
 
 Pipelines, and their component jobs and stages, are defined in the [`.gitlab-ci.yml`](yaml/README.md) file for each project.