Document adding custom collapsible sections to job logs. For #31481

doc/ci/pipelines.md

@@ -159,6 +159,24 @@ In the following example:
 
 ![Collapsible sections](img/collapsible_log_v12_6.png)
 
+#### Custom collapsible sections
+
+Build scripts can introduce their own collapsible sections like so:
+
+```text
+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
+```
+
+Where `1560896352` is the unix time the section started or ended; `my_first_section` is a section name; and `\e[0K` is the clear line ANSI escape code. For example, a shell script can demark a collapsible section with:
+
+```sh
+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"
+```
+
 ## Configuring pipelines
 
 Pipelines, and their component jobs and stages, are defined in the [`.gitlab-ci.yml`](yaml/README.md) file for each project.