diff --git a/docs/docs/20-usage/40-secrets.md b/docs/docs/20-usage/40-secrets.md
index 09fc00c45b..4c814fae51 100644
--- a/docs/docs/20-usage/40-secrets.md
+++ b/docs/docs/20-usage/40-secrets.md
@@ -31,7 +31,9 @@ once their usage is declared in the `secrets` section:
 Alternatively, you can get a `setting` from secrets using the `from_secret` syntax.
 In this example, the secret named `secret_token` would be passed to the setting named `token`, which will be available in the plugin as environment variable named `PLUGIN_TOKEN`. See [Plugins](./51-plugins/20-creating-plugins.md#settings) for details.
 
-**NOTE:** the `from_secret` syntax only works with the newer `settings` block.
+:::note
+The `from_secret` syntax only works with the newer `settings` block.
+:::
 
 ```diff
  steps:
@@ -77,7 +79,9 @@ There may be scenarios where you are required to store secrets using alternate n
 
 Secrets are not exposed to pull requests by default. You can override this behavior by creating the secret and enabling the `pull_request` event type, either in UI or by CLI, see below.
 
-**NOTE:** Please be careful when exposing secrets to pull requests. If your repository is open source and accepts pull requests your secrets are not safe. A bad actor can submit a malicious pull request that exposes your secrets.
+:::note
+Please be careful when exposing secrets to pull requests. If your repository is open source and accepts pull requests your secrets are not safe. A bad actor can submit a malicious pull request that exposes your secrets.
+:::
 
 ## Image filter
 
diff --git a/docs/docs/30-administration/22-backends/20-local.md b/docs/docs/30-administration/22-backends/20-local.md
index 4dca5d34ed..7ec95f0f86 100644
--- a/docs/docs/30-administration/22-backends/20-local.md
+++ b/docs/docs/30-administration/22-backends/20-local.md
@@ -22,7 +22,7 @@ pipeline can be trusted. You shouldn't use it for a public facing CI where
 anyone can submit code or add new repositories. You shouldn't execute the agent
 as a privileged user (root).
 
-The local backend will use a random directory in $TMPDIR to store the cloned
+The local backend will use a random directory in `$TMPDIR` to store the cloned
 code and execute commands.
 
 In order to use this backend, you need to download (or build) the
diff --git a/docs/docs/92-development/10-custom-agent-backends.md b/docs/docs/30-administration/22-backends/50-custom-backends.md
similarity index 81%
rename from docs/docs/92-development/10-custom-agent-backends.md
rename to docs/docs/30-administration/22-backends/50-custom-backends.md
index 3514e73d9e..3c771c4ef1 100644
--- a/docs/docs/92-development/10-custom-agent-backends.md
+++ b/docs/docs/30-administration/22-backends/50-custom-backends.md
@@ -1,4 +1,4 @@
-# Custom agent backends
+# Custom backends
 
 If none of our backends fits your usecases, you can write your own.
 
@@ -20,4 +20,4 @@ func main() {
 }
 ```
 
-It is also possible to use multiple backends, you can select with [`WOODPECKER_BACKEND`](../30-administration/15-agent-config.md#woodpecker_backend) between them.
+It is also possible to use multiple backends, you can select with [`WOODPECKER_BACKEND`](../15-agent-config.md#woodpecker_backend) between them.
diff --git a/docs/docs/30-administration/60-ssl.md b/docs/docs/30-administration/60-ssl.md
index 74de210230..755ba205d8 100644
--- a/docs/docs/30-administration/60-ssl.md
+++ b/docs/docs/30-administration/60-ssl.md
@@ -78,7 +78,7 @@ Update your configuration to mount your certificate and key:
 
 Update your configuration to provide the paths of your certificate and key:
 
-```yaml title="docker-compose.yaml"
+```diff title="docker-compose.yaml"
  version: '3'
 
  services: