From 761bdf135b39d9cd834d04d03ec2d84b16f6f258 Mon Sep 17 00:00:00 2001
From: qwerty287 <qwerty287@posteo.de>
Date: Sun, 21 Jan 2024 18:57:01 +0100
Subject: [PATCH 1/5] Use array syntax in docs

---
 docs/docs/10-intro.md                         | 10 +--
 docs/docs/20-usage/10-intro.md                | 10 +--
 docs/docs/20-usage/20-workflow-syntax.md      | 70 +++++++++----------
 docs/docs/20-usage/25-workflows.md            | 12 ++--
 docs/docs/20-usage/30-matrix-workflows.md     | 16 ++---
 docs/docs/20-usage/40-secrets.md              |  8 +--
 docs/docs/20-usage/41-registries.md           |  6 +-
 docs/docs/20-usage/45-cron.md                 |  2 +-
 docs/docs/20-usage/50-environment.md          | 16 ++---
 docs/docs/20-usage/51-plugins/10-overview.md  |  6 +-
 .../51-plugins/20-creating-plugins.md         |  4 +-
 docs/docs/20-usage/60-services.md             | 28 ++++----
 docs/docs/20-usage/70-volumes.md              |  2 +-
 docs/docs/20-usage/90-advanced-usage.md       | 20 +++---
 .../100-external-configuration-api.md         |  4 +-
 .../30-administration/22-backends/20-local.md |  4 +-
 .../22-backends/40-kubernetes.md              |  8 +--
 17 files changed, 113 insertions(+), 113 deletions(-)

diff --git a/docs/docs/10-intro.md b/docs/docs/10-intro.md
index 087fbe7ffb..276dcb000e 100644
--- a/docs/docs/10-intro.md
+++ b/docs/docs/10-intro.md
@@ -13,11 +13,11 @@ If you are already using containers in your daily workflow, you'll for sure love
 
 ```yaml title=".woodpecker.yaml"
 steps:
-  build:
+  - name: build
     image: debian
     commands:
       - echo "This is the build step"
-  a-test-step:
+  - name: a-test-step
     image: debian
     commands:
       - echo "Testing.."
@@ -32,7 +32,7 @@ steps:
 
 ```diff
  steps:
-   build:
+   - name: build
 -    image: debian
 +    image: mycompany/image-with-awscli
      commands:
@@ -46,11 +46,11 @@ steps:
 
 ```yaml title=".woodpecker.yaml"
 steps:
-  build:
+  - name: build
     image: debian
     commands:
       - touch myfile
-  a-test-step:
+  - name: a-test-step
     image: debian
     commands:
       - cat myfile
diff --git a/docs/docs/20-usage/10-intro.md b/docs/docs/20-usage/10-intro.md
index d5eaeed894..4774661730 100644
--- a/docs/docs/20-usage/10-intro.md
+++ b/docs/docs/20-usage/10-intro.md
@@ -30,7 +30,7 @@ Example pipeline configuration:
 
 ```yaml
 steps:
-  build:
+  - name: build
     image: golang
     commands:
       - go get
@@ -38,7 +38,7 @@ steps:
       - go test
 
 services:
-  postgres:
+  - name: postgres
     image: postgres:9.4.5
     environment:
       - POSTGRES_USER=myapp
@@ -48,20 +48,20 @@ Example pipeline configuration with multiple, serial steps:
 
 ```yaml
 steps:
-  backend:
+  - name: backend
     image: golang
     commands:
       - go get
       - go build
       - go test
 
-  frontend:
+  - name: frontend
     image: node:6
     commands:
       - npm install
       - npm test
 
-  notify:
+  - name: notify
     image: plugins/slack
     channel: developers
     username: woodpecker
diff --git a/docs/docs/20-usage/20-workflow-syntax.md b/docs/docs/20-usage/20-workflow-syntax.md
index d79ec6a392..bb18e953ee 100644
--- a/docs/docs/20-usage/20-workflow-syntax.md
+++ b/docs/docs/20-usage/20-workflow-syntax.md
@@ -6,12 +6,12 @@ Example steps:
 
 ```yaml
 steps:
-  backend:
+  - name: backend
     image: golang
     commands:
       - go build
       - go test
-  frontend:
+  - name: frontend
     image: node
     commands:
       - npm install
@@ -21,16 +21,18 @@ steps:
 
 In the above example we define two steps, `frontend` and `backend`. The names of these steps are completely arbitrary.
 
-Another way to name a step is by using the name keyword:
+The name is optional, if not added the steps will be numerated.
+
+Another way to name a step is by using dictionaries:
 
 ```yaml
 steps:
-  - name: backend
+  backend:
     image: golang
     commands:
       - go build
       - go test
-  - name: frontend
+  frontend:
     image: node
     commands:
       - npm install
@@ -38,8 +40,6 @@ steps:
       - npm run build
 ```
 
-Keep in mind the name is optional, if not added the steps will be numerated.
-
 ## Skip Commits
 
 Woodpecker gives the ability to skip individual commits by adding `[SKIP CI]` or `[CI SKIP]` to the commit message. Note this is case-insensitive.
@@ -55,7 +55,7 @@ The associated commit is checked out with git to a workspace which is mounted to
 
 ```diff
  steps:
-   backend:
+   - name: backend
      image: golang
      commands:
 +      - go build
@@ -69,11 +69,11 @@ The associated commit is checked out with git to a workspace which is mounted to
 
 ```yaml title=".woodpecker.yaml"
 steps:
-  build:
+  - name: build
     image: debian
     commands:
       - echo "test content" > myfile
-  a-test-step:
+  - name: a-test-step
     image: debian
     commands:
       - cat myfile
@@ -87,18 +87,18 @@ When using the `local` backend, the `image` entry is used to specify the shell,
 
 ```diff
  steps:
-   build:
+   - name: build
 +    image: golang:1.6
      commands:
        - go build
        - go test
 
-   publish:
+   - name: publish
 +    image: plugins/docker
      repo: foo/bar
 
  services:
-   database:
+   - name: database
 +    image: mysql
 ```
 
@@ -116,7 +116,7 @@ Woodpecker does not automatically upgrade container images. Example configuratio
 
 ```diff
  steps:
-   build:
+   - name: build
      image: golang:latest
 +    pull: true
 ```
@@ -129,7 +129,7 @@ Commands of every step are executed serially as if you would enter them into you
 
 ```diff
  steps:
-   backend:
+   - name: backend
      image: golang
      commands:
 +      - go build
@@ -178,7 +178,7 @@ Some of the steps may be allowed to fail without causing the whole workflow and
 
 ```diff
  steps:
-   backend:
+   - name: backend
      image: golang
      commands:
        - go build
@@ -192,7 +192,7 @@ Woodpecker supports defining a list of conditions for a step by using a `when` b
 
 ```diff
  steps:
-   slack:
+   - name: slack
      image: plugins/slack
      settings:
        channel: dev
@@ -209,7 +209,7 @@ Example conditional execution by repository:
 
 ```diff
  steps:
-   slack:
+   - name: slack
      image: plugins/slack
      settings:
        channel: dev
@@ -227,7 +227,7 @@ Example conditional execution by branch:
 
 ```diff
  steps:
-   slack:
+   - name: slack
      image: plugins/slack
      settings:
        channel: dev
@@ -324,7 +324,7 @@ There are use cases for executing steps on failure, such as sending notification
 
 ```diff
  steps:
-   slack:
+   - name: slack
      image: plugins/slack
      settings:
        channel: dev
@@ -457,18 +457,18 @@ Normally steps of a workflow are executed serially in the order in which they ar
 
 ```diff
  steps:
-   build: # build will be executed immediately
+   - name: build # build will be executed immediately
      image: golang
      commands:
        - go build
 
-   deploy:
+   - name: deploy
      image: plugins/docker
      settings:
        repo: foo/bar
 +    depends_on: [build, test] # deploy will be executed after build and test finished
 
-   test: # test will be executed immediately as no dependencies are set
+   - name: test # test will be executed immediately as no dependencies are set
      image: golang
      commands:
        - go test
@@ -508,7 +508,7 @@ The workspace can be customized using the workspace block in the YAML file:
 +  path: src/github.com/octocat/hello-world
 
  steps:
-   build:
+   - name: build
      image: golang:latest
      commands:
        - go get
@@ -523,12 +523,12 @@ The base attribute defines a shared base volume available to all steps. This ens
    path: src/github.com/octocat/hello-world
 
  steps:
-   deps:
+   - name: deps
      image: golang:latest
      commands:
        - go get
        - go test
-   build:
+   - name: build
      image: node:latest
      commands:
        - go build
@@ -580,7 +580,7 @@ You can add additional labels as a key value map:
 +  hostname: "" # this label will be ignored as it is empty
 
  steps:
-   build:
+   - name: build
      image: golang
      commands:
        - go build
@@ -622,7 +622,7 @@ You can manually configure the clone step in your workflow for customization:
 +    image: woodpeckerci/plugin-git
 
  steps:
-   build:
+   - name: build
      image: golang
      commands:
        - go build
@@ -633,7 +633,7 @@ Example configuration to override depth:
 
 ```diff
  clone:
-   git:
+   - name: git
      image: woodpeckerci/plugin-git
 +    settings:
 +      partial: false
@@ -652,7 +652,7 @@ Example configuration to clone Mercurial repository:
 
 ```diff
  clone:
-   hg:
+   - name: hg
 +    image: plugins/hg
 +    settings:
 +      path: bitbucket.org/foo/bar
@@ -673,7 +673,7 @@ To use the ssh git url in `.gitmodules` for users cloning with ssh, and also use
 
 ```diff
  clone:
-   git:
+   - name: git
      image: woodpeckerci/plugin-git
      settings:
        recursive: true
@@ -705,7 +705,7 @@ Example conditional execution by repository:
 +  repo: test/test
 +
  steps:
-   slack:
+   - name: slack
      image: plugins/slack
      settings:
        channel: dev
@@ -724,7 +724,7 @@ Example conditional execution by branch:
 +  branch: main
 +
  steps:
-   slack:
+   - name: slack
      image: plugins/slack
      settings:
        channel: dev
@@ -862,14 +862,14 @@ Privileged mode is only available to trusted repositories and for security reaso
 
 ```diff
  steps:
-   build:
+   - name: build
      image: docker
      environment:
        - DOCKER_HOST=tcp://docker:2375
      commands:
        - docker --tls=false ps
 
- services:
+ - name: services
    docker:
      image: docker:dind
      commands: dockerd-entrypoint.sh --storage-driver=vfs --tls=false
diff --git a/docs/docs/20-usage/25-workflows.md b/docs/docs/20-usage/25-workflows.md
index d1f8a0c446..1a3f40fc86 100644
--- a/docs/docs/20-usage/25-workflows.md
+++ b/docs/docs/20-usage/25-workflows.md
@@ -31,7 +31,7 @@ If you still need to pass artifacts between the workflows you need use some stor
 
 ```yaml title=".woodpecker/.build.yaml"
 steps:
-  build:
+  - name: build
     image: debian:stable-slim
     commands:
       - echo building
@@ -40,7 +40,7 @@ steps:
 
 ```yaml title=".woodpecker/.deploy.yaml"
 steps:
-  deploy:
+  - name: deploy
     image: debian:stable-slim
     commands:
       - echo deploying
@@ -53,7 +53,7 @@ depends_on:
 
 ```yaml title=".woodpecker/.test.yaml"
 steps:
-  test:
+  - name: test
     image: debian:stable-slim
     commands:
       - echo testing
@@ -65,7 +65,7 @@ depends_on:
 
 ```yaml title=".woodpecker/.lint.yaml"
 steps:
-  lint:
+  - name: lint
     image: debian:stable-slim
     commands:
       - echo linting
@@ -86,7 +86,7 @@ The name for a `depends_on` entry is the filename without the path, leading dots
 
 ```diff
  steps:
-   deploy:
+   - name: deploy
      image: debian:stable-slim
      commands:
        - echo deploying
@@ -101,7 +101,7 @@ Workflows that need to run even on failures should set the `runs_on` tag.
 
 ```diff
  steps:
-   notify:
+   - name: notify
      image: debian:stable-slim
      commands:
        - echo notifying
diff --git a/docs/docs/20-usage/30-matrix-workflows.md b/docs/docs/20-usage/30-matrix-workflows.md
index c1c62c324f..a5ba107c9e 100644
--- a/docs/docs/20-usage/30-matrix-workflows.md
+++ b/docs/docs/20-usage/30-matrix-workflows.md
@@ -43,7 +43,7 @@ matrix:
     - mariadb:10.1
 
 steps:
-  build:
+  - name: build
     image: golang:${GO_VERSION}
     commands:
       - go get
@@ -51,7 +51,7 @@ steps:
       - go test
 
 services:
-  database:
+  - name: database
     image: ${DATABASE}
 ```
 
@@ -59,7 +59,7 @@ Example YAML file after injecting the matrix parameters:
 
 ```diff
  steps:
-   build:
+   - name: build
 -    image: golang:${GO_VERSION}
 +    image: golang:1.4
      commands:
@@ -71,7 +71,7 @@ Example YAML file after injecting the matrix parameters:
 +      - DATABASE=mysql:8
 
  services:
-   database:
+   - name: database
 -    image: ${DATABASE}
 +    image: mysql:8
 ```
@@ -88,7 +88,7 @@ matrix:
     - latest
 
 steps:
-  build:
+  - name: build
     image: golang:${TAG}
     commands:
       - go build
@@ -105,7 +105,7 @@ matrix:
     - golang:latest
 
 steps:
-  build:
+  - name: build
     image: ${IMAGE}
     commands:
       - go build
@@ -124,12 +124,12 @@ labels:
   platform: ${platform}
 
 steps:
-  test:
+  - name: test
     image: alpine
     commands:
       - echo "I am running on ${platform}"
 
-  test-arm-only:
+  - name: test-arm-only
     image: alpine
     commands:
       - echo "I am running on ${platform}"
diff --git a/docs/docs/20-usage/40-secrets.md b/docs/docs/20-usage/40-secrets.md
index 6c8465a58b..09fc00c45b 100644
--- a/docs/docs/20-usage/40-secrets.md
+++ b/docs/docs/20-usage/40-secrets.md
@@ -18,7 +18,7 @@ once their usage is declared in the `secrets` section:
 
 ```diff
  steps:
-   docker:
+   - name: docker
      image: docker
      commands:
 +      - echo $DOCKER_USERNAME
@@ -35,7 +35,7 @@ In this example, the secret named `secret_token` would be passed to the setting
 
 ```diff
  steps:
-   docker:
+   - name: docker
      image: my-plugin
      settings:
 +      token:
@@ -48,7 +48,7 @@ Please note parameter expressions are subject to pre-processing. When using secr
 
 ```diff
  steps:
-   docker:
+   - name: docker
      image: docker
      commands:
 -      - echo ${DOCKER_USERNAME}
@@ -64,7 +64,7 @@ There may be scenarios where you are required to store secrets using alternate n
 
 ```diff
  steps:
-   docker:
+   - name: docker
      image: plugins/docker
      repo: octocat/hello-world
      tags: latest
diff --git a/docs/docs/20-usage/41-registries.md b/docs/docs/20-usage/41-registries.md
index 9711c3519d..b87ae55c43 100644
--- a/docs/docs/20-usage/41-registries.md
+++ b/docs/docs/20-usage/41-registries.md
@@ -12,7 +12,7 @@ Example configuration using a private image:
 
 ```diff
  steps:
-   build:
+   - name: build
 +    image: gcr.io/custom/golang
      commands:
        - go build
@@ -55,14 +55,14 @@ With a `Dockerfile` at the root of the project:
 
 ```yaml
 steps:
-  build-image:
+  - name: build-image
     image: docker
     commands:
       - docker build --rm -t local/project-image .
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock
 
-  build-project:
+  - name: build-project
     image: local/project-image
     commands:
       - ./build.sh
diff --git a/docs/docs/20-usage/45-cron.md b/docs/docs/20-usage/45-cron.md
index f90c77c1ad..994e022bcd 100644
--- a/docs/docs/20-usage/45-cron.md
+++ b/docs/docs/20-usage/45-cron.md
@@ -8,7 +8,7 @@ To configure cron jobs you need at least push access to the repository.
 
    ```diff
     steps:
-      sync_locales:
+      - name: sync_locales
         image: weblate_sync
         settings:
           url: example.com
diff --git a/docs/docs/20-usage/50-environment.md b/docs/docs/20-usage/50-environment.md
index 32096c5da3..02cee4337d 100644
--- a/docs/docs/20-usage/50-environment.md
+++ b/docs/docs/20-usage/50-environment.md
@@ -4,7 +4,7 @@ Woodpecker provides the ability to pass environment variables to individual pipe
 
 ```diff
  steps:
-   build:
+   - name: build
      image: golang
 +    environment:
 +      - CGO=0
@@ -19,7 +19,7 @@ Please note that the environment section is not able to expand environment varia
 
 ```diff
  steps:
-   build:
+   - name: build
      image: golang
 -    environment:
 -      - PATH=$PATH:/go
@@ -35,7 +35,7 @@ Please note that the environment section is not able to expand environment varia
 
 ```diff
  steps:
-   build:
+   - name: build
      image: golang
      commands:
 -      - export PATH=${PATH}:/go
@@ -153,7 +153,7 @@ WOODPECKER_ENVIRONMENT=GOLANG_VERSION:1.18
 
 ```diff
  steps:
-   build:
+   - name: build
 -    image: golang:1.18
 +    image: golang:${GOLANG_VERSION}
      commands:
@@ -168,7 +168,7 @@ Example commit substitution:
 
 ```diff
  steps:
-   docker:
+   - name: docker
      image: plugins/docker
      settings:
 +      tags: ${CI_COMMIT_SHA}
@@ -178,7 +178,7 @@ Example tag substitution:
 
 ```diff
  steps:
-   docker:
+   - name: docker
      image: plugins/docker
      settings:
 +      tags: ${CI_COMMIT_TAG}
@@ -206,7 +206,7 @@ Example variable substitution with substring:
 
 ```diff
  steps:
-   docker:
+   - name: docker
      image: plugins/docker
      settings:
 +      tags: ${CI_COMMIT_SHA:0:8}
@@ -216,7 +216,7 @@ Example variable substitution strips `v` prefix from `v.1.0.0`:
 
 ```diff
  steps:
-   docker:
+   - name: docker
      image: plugins/docker
      settings:
 +      tags: ${CI_COMMIT_TAG##v}
diff --git a/docs/docs/20-usage/51-plugins/10-overview.md b/docs/docs/20-usage/51-plugins/10-overview.md
index d37c969f55..ab8db3df37 100644
--- a/docs/docs/20-usage/51-plugins/10-overview.md
+++ b/docs/docs/20-usage/51-plugins/10-overview.md
@@ -8,19 +8,19 @@ Example pipeline using the Docker and Slack plugins:
 
 ```yaml
 steps:
-  build:
+  - name: build
     image: golang
     commands:
       - go build
       - go test
 
-  publish:
+  - name: publish
     image: plugins/docker
     settings:
       repo: foo/bar
       tags: latest
 
-  notify:
+  - name: notify
     image: plugins/slack
     settings:
       channel: dev
diff --git a/docs/docs/20-usage/51-plugins/20-creating-plugins.md b/docs/docs/20-usage/51-plugins/20-creating-plugins.md
index 893010ad2a..adbb4df3e2 100644
--- a/docs/docs/20-usage/51-plugins/20-creating-plugins.md
+++ b/docs/docs/20-usage/51-plugins/20-creating-plugins.md
@@ -28,7 +28,7 @@ It's also possible to use complex settings like this:
 
 ```yaml
 steps:
-  plugin:
+  - name: plugin
     image: foo/plugin
     settings:
       complex:
@@ -58,7 +58,7 @@ The below example demonstrates how we might configure a webhook plugin in the YA
 
 ```yaml
 steps:
-  webhook:
+  - name: webhook
     image: foo/webhook
     settings:
       url: https://example.com
diff --git a/docs/docs/20-usage/60-services.md b/docs/docs/20-usage/60-services.md
index 6d6a0b594f..4992e5dc27 100644
--- a/docs/docs/20-usage/60-services.md
+++ b/docs/docs/20-usage/60-services.md
@@ -8,17 +8,17 @@ In the example below, the MySQL service is assigned the hostname `database` and
 
 ```yaml
 steps:
-  build:
+  - name: build
     image: golang
     commands:
       - go build
       - go test
 
 services:
-  database:
+  - name: database
     image: mysql
 
-  cache:
+  - name: cache
     image: redis
 ```
 
@@ -26,12 +26,12 @@ You can define a port and a protocol explicitly:
 
 ```yaml
 services:
-  database:
+  - name: database
     image: mysql
     ports:
       - 3306
 
-  wireguard:
+  - name: wireguard
     image: wg
     ports:
       - 51820/udp
@@ -43,13 +43,13 @@ Service containers generally expose environment variables to customize service s
 
 ```diff
  services:
-   database:
+   - name: database
      image: mysql
 +    environment:
 +      - MYSQL_DATABASE=test
 +      - MYSQL_ALLOW_EMPTY_PASSWORD=yes
 
-   cache:
+   - name: cache
      image: redis
 ```
 
@@ -59,17 +59,17 @@ Service and long running containers can also be included in the pipeline section
 
 ```diff
  steps:
-   build:
+   - name: build
      image: golang
      commands:
        - go build
        - go test
 
-   database:
+   - name: database
      image: redis
 +    detach: true
 
-   test:
+   - name: test
      image: golang
      commands:
        - go test
@@ -83,7 +83,7 @@ Service containers require time to initialize and begin to accept connections. I
 
 ```diff
  steps:
-   test:
+   - name: test
      image: golang
      commands:
 +      - sleep 15
@@ -91,7 +91,7 @@ Service containers require time to initialize and begin to accept connections. I
        - go test
 
  services:
-   database:
+   - name: database
      image: mysql
 ```
 
@@ -99,13 +99,13 @@ Service containers require time to initialize and begin to accept connections. I
 
 ```yaml
 services:
-  database:
+  - name: database
     image: mysql
     environment:
       - MYSQL_DATABASE=test
       - MYSQL_ROOT_PASSWORD=example
 steps:
-  get-version:
+  - name: get-version
     image: ubuntu
     commands:
       - ( apt update && apt dist-upgrade -y && apt install -y mysql-client 2>&1 )> /dev/null
diff --git a/docs/docs/20-usage/70-volumes.md b/docs/docs/20-usage/70-volumes.md
index 989f416e1b..3397e879cb 100644
--- a/docs/docs/20-usage/70-volumes.md
+++ b/docs/docs/20-usage/70-volumes.md
@@ -8,7 +8,7 @@ Volumes are only available to trusted repositories and for security reasons shou
 
 ```diff
  steps:
-   build:
+   - name: build
      image: docker
      commands:
        - docker build --rm -t octocat/hello-world .
diff --git a/docs/docs/20-usage/90-advanced-usage.md b/docs/docs/20-usage/90-advanced-usage.md
index 8855e4430e..065386fdf0 100644
--- a/docs/docs/20-usage/90-advanced-usage.md
+++ b/docs/docs/20-usage/90-advanced-usage.md
@@ -12,10 +12,10 @@ To convert this:
 
 ```yaml
 steps:
-  test:
+  - name: test
     image: golang:1.18
     commands: go test ./...
-  build:
+  - name: build
     image: golang:1.18
     commands: build
 ```
@@ -27,11 +27,11 @@ Just add a new section called **variables** like this:
 +  - &golang_image 'golang:1.18'
 
  steps:
-   test:
+   - name: test
 -    image: golang:1.18
 +    image: *golang_image
      commands: go test ./...
-   build:
+   - name: build
 -    image: golang:1.18
 +    image: *golang_image
      commands: build
@@ -50,14 +50,14 @@ variables:
   - &some-plugin codeberg.org/6543/docker-images/print_env
 
 steps:
-  develop:
+  - name: develop
     image: *some-plugin
     settings:
       <<: [*base-plugin-settings, *special-setting] # merge two maps into an empty map
     when:
       branch: develop
 
-  main:
+  - name: main
     image: *some-plugin
     settings:
       <<: *base-plugin-settings # merge one map and ...
@@ -80,13 +80,13 @@ variables:
     - echo hello
 
 steps:
-  step1:
+  - name: step1
     image: debian
     commands:
       - <<: *pre_cmds # prepend a sequence
       - echo exec step now do dedicated things
       - <<: *post_cmds # append a sequence
-  step2:
+  - name: step2
     image: debian
     commands:
       - <<: [*pre_cmds, *hello_cmd] # prepend two sequences
@@ -105,13 +105,13 @@ One can create a file containing environment variables, and then source it in ea
 
 ```yaml
 steps:
-  init:
+  - name: init
     image: bash
     commands:
       - echo "FOO=hello" >> envvars
       - echo "BAR=world" >> envvars
 
-  debug:
+  - name: debug
     image: bash
     commands:
       - source envvars
diff --git a/docs/docs/30-administration/100-external-configuration-api.md b/docs/docs/30-administration/100-external-configuration-api.md
index a5e216159f..f951b14780 100644
--- a/docs/docs/30-administration/100-external-configuration-api.md
+++ b/docs/docs/30-administration/100-external-configuration-api.md
@@ -84,7 +84,7 @@ WOODPECKER_CONFIG_SERVICE_ENDPOINT=https://example.com/ciconfig
   "configs": [
     {
       "name": ".woodpecker.yaml",
-      "data": "steps:\n  backend:\n    image: alpine\n    commands:\n      - echo \"Hello there from Repo (.woodpecker.yaml)\"\n"
+      "data": "steps:\n  - name: backend\n    image: alpine\n    commands:\n      - echo \"Hello there from Repo (.woodpecker.yaml)\"\n"
     }
   ]
 }
@@ -97,7 +97,7 @@ WOODPECKER_CONFIG_SERVICE_ENDPOINT=https://example.com/ciconfig
   "configs": [
     {
       "name": "central-override",
-      "data": "steps:\n  backend:\n    image: alpine\n    commands:\n      - echo \"Hello there from ConfigAPI\"\n"
+      "data": "steps:\n  - name: backend\n    image: alpine\n    commands:\n      - echo \"Hello there from ConfigAPI\"\n"
     }
   ]
 }
diff --git a/docs/docs/30-administration/22-backends/20-local.md b/docs/docs/30-administration/22-backends/20-local.md
index c2d229d57b..4dca5d34ed 100644
--- a/docs/docs/30-administration/22-backends/20-local.md
+++ b/docs/docs/30-administration/22-backends/20-local.md
@@ -44,7 +44,7 @@ used to run the commands.
 
 ```yaml title=".woodpecker.yaml"
 steps:
-  build:
+  - name: build
     image: bash
     commands: [...]
 ```
@@ -55,7 +55,7 @@ Plugins are just executable binaries:
 
 ```yaml
 steps:
-  build:
+  - name: build
     image: /usr/bin/tree
 ```
 
diff --git a/docs/docs/30-administration/22-backends/40-kubernetes.md b/docs/docs/30-administration/22-backends/40-kubernetes.md
index b4cba009a5..2da6c65456 100644
--- a/docs/docs/30-administration/22-backends/40-kubernetes.md
+++ b/docs/docs/30-administration/22-backends/40-kubernetes.md
@@ -17,7 +17,7 @@ Here is an example definition with an arbitrary `resources` definition below the
 
 ```yaml
 steps:
-  'My kubernetes step':
+  - name: 'My kubernetes step'
     image: alpine
     commands:
       - echo "Hello world"
@@ -75,7 +75,7 @@ Example pipeline configuration:
 
 ```yaml
 steps:
-  build:
+  - name: build
     image: golang
     commands:
       - go get
@@ -107,7 +107,7 @@ Assuming a PVC named "woodpecker-cache" exists, it can be referenced as follows
 
 ```yaml
 steps:
-  "Restore Cache":
+  - name: "Restore Cache"
     image: meltwater/drone-cache
     volumes:
       - woodpecker-cache:/woodpecker/src/cache
@@ -123,7 +123,7 @@ Use the following configuration to set the `securityContext` for the pod/contain
 
 ```yaml
 steps:
-  test:
+  - name: test
     image: alpine
     commands:
       - echo Hello world

From 53f0b31fa606277a9ec1627f257e337866486560 Mon Sep 17 00:00:00 2001
From: qwerty287 <qwerty287@posteo.de>
Date: Sun, 21 Jan 2024 18:58:52 +0100
Subject: [PATCH 2/5] Consistent tocs

---
 docs/docs/30-administration/11-forges/20-github.md    | 4 ++++
 docs/docs/30-administration/11-forges/30-gitea.md     | 4 ++++
 docs/docs/30-administration/11-forges/40-gitlab.md    | 4 ++++
 docs/docs/30-administration/11-forges/50-bitbucket.md | 4 ++++
 4 files changed, 16 insertions(+)

diff --git a/docs/docs/30-administration/11-forges/20-github.md b/docs/docs/30-administration/11-forges/20-github.md
index a3e4abdedb..f3656f8fd4 100644
--- a/docs/docs/30-administration/11-forges/20-github.md
+++ b/docs/docs/30-administration/11-forges/20-github.md
@@ -1,3 +1,7 @@
+---
+toc_max_heading_level: 2
+---
+
 # GitHub
 
 Woodpecker comes with built-in support for GitHub and GitHub Enterprise.
diff --git a/docs/docs/30-administration/11-forges/30-gitea.md b/docs/docs/30-administration/11-forges/30-gitea.md
index 1bae1bd38d..b50d2e0115 100644
--- a/docs/docs/30-administration/11-forges/30-gitea.md
+++ b/docs/docs/30-administration/11-forges/30-gitea.md
@@ -1,3 +1,7 @@
+---
+toc_max_heading_level: 2
+---
+
 # Gitea / Forgejo
 
 Woodpecker comes with built-in support for Gitea and the "soft" fork Forgejo. To enable Gitea you should configure the Woodpecker container using the following environment variables:
diff --git a/docs/docs/30-administration/11-forges/40-gitlab.md b/docs/docs/30-administration/11-forges/40-gitlab.md
index 7c55d62631..3fff410c69 100644
--- a/docs/docs/30-administration/11-forges/40-gitlab.md
+++ b/docs/docs/30-administration/11-forges/40-gitlab.md
@@ -1,3 +1,7 @@
+---
+toc_max_heading_level: 2
+---
+
 # GitLab
 
 Woodpecker comes with built-in support for the GitLab version 8.2 and higher. To enable GitLab you should configure the Woodpecker container using the following environment variables:
diff --git a/docs/docs/30-administration/11-forges/50-bitbucket.md b/docs/docs/30-administration/11-forges/50-bitbucket.md
index 8d153258a4..b658238d60 100644
--- a/docs/docs/30-administration/11-forges/50-bitbucket.md
+++ b/docs/docs/30-administration/11-forges/50-bitbucket.md
@@ -1,3 +1,7 @@
+---
+toc_max_heading_level: 2
+---
+
 # Bitbucket
 
 Woodpecker comes with built-in support for Bitbucket Cloud. To enable Bitbucket Cloud you should configure the Woodpecker container using the following environment variables:

From 6dc017b7338cdd1fd34031f63439d0e6a7510db3 Mon Sep 17 00:00:00 2001
From: qwerty287 <qwerty287@posteo.de>
Date: Sun, 21 Jan 2024 19:01:32 +0100
Subject: [PATCH 3/5] improve host docs

---
 docs/docs/30-administration/10-server-config.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/docs/docs/30-administration/10-server-config.md b/docs/docs/30-administration/10-server-config.md
index be40ddb7d3..9c6e8372a9 100644
--- a/docs/docs/30-administration/10-server-config.md
+++ b/docs/docs/30-administration/10-server-config.md
@@ -189,9 +189,13 @@ Disable colored debug output.
 
 > Default: empty
 
-Server fully qualified URL of the user-facing hostname and path prefix.
+Server fully qualified URL of the user-facing hostname, port (if not default for HTTP/HTTPS) and path prefix.
 
-Example: `WOODPECKER_HOST=http://woodpecker.example.org` or `WOODPECKER_HOST=http://example.org/woodpecker`
+Examples:
+
+- `WOODPECKER_HOST=http://woodpecker.example.org`
+- `WOODPECKER_HOST=http://example.org/woodpecker`
+- `WOODPECKER_HOST=http://example.org:1234/woodpecker`
 
 ### `WOODPECKER_WEBHOOK_HOST`
 

From 72174e99e28c1191c32d7e413d31e1cdcf218f34 Mon Sep 17 00:00:00 2001
From: qwerty287 <qwerty287@posteo.de>
Date: Sun, 21 Jan 2024 19:06:43 +0100
Subject: [PATCH 4/5] Remove security

---
 docs/docs/92-development/09-security.md | 10 ----------
 1 file changed, 10 deletions(-)
 delete mode 100644 docs/docs/92-development/09-security.md

diff --git a/docs/docs/92-development/09-security.md b/docs/docs/92-development/09-security.md
deleted file mode 100644
index 24517c8432..0000000000
--- a/docs/docs/92-development/09-security.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# Security
-
-We take security seriously.
-If you discover a security issue, please bring it to our attention right away!
-
-## Reporting a Vulnerability
-
-Please **DO NOT** file a public issue, instead send your report privately to [`security @ woodpecker-ci.org`](mailto:security@woodpecker-ci.org).
-
-Security reports are greatly appreciated, and we will publicly thank you for it. If you choose to remain anonymous, we will respect your request and keep your name confidential.

From 8696bca721e5e1858ed31cbea74f24245205cf2c Mon Sep 17 00:00:00 2001
From: qwerty287 <qwerty287@posteo.de>
Date: Sun, 21 Jan 2024 19:08:20 +0100
Subject: [PATCH 5/5] Add release info

---
 .../00-deployment/00-overview.md               | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/docs/docs/30-administration/00-deployment/00-overview.md b/docs/docs/30-administration/00-deployment/00-overview.md
index 8400ae8cc1..758b76ad62 100644
--- a/docs/docs/30-administration/00-deployment/00-overview.md
+++ b/docs/docs/30-administration/00-deployment/00-overview.md
@@ -18,6 +18,24 @@ Woodpecker is having two different kinds of releases: **stable** and **next**.
 
 To find out more about the differences between the two releases, please read the [FAQ](/faq#which-version-of-woodpecker-should-i-use).
 
+### Stable releases
+
+We release a new version every four weeks and will release the current state of the `main` branch.
+If there are security fixes or critical bug fixes, we'll release them directly.
+There are no backports or similar.
+
+#### Versioning
+
+We use [Semantic Versioning](https://semver.org/) to be able,
+to communicate when admins have to do manual migration steps and when they can just bump versions up.
+
+#### Breaking changes
+
+As of semver guidelines, breaking changes will be released as a major version. We will hold back
+breaking changes to not release many majors each containing just a few breaking changes.
+Prior to the release of a major version, a release candidate (RC) will be published to allow easy testing,
+the actual release will be about a week later.
+
 ## Hardware Requirements
 
 Below are minimal resources requirements for Woodpecker components itself: