Clarify usage of secrets in docs

docs/docs/20-usage/40-secrets.md

@@ -18,48 +18,93 @@ once their usage is declared in the `secrets` section:
 
 ```diff
  steps:
-   - name: docker
-     image: docker
+   - name: test
+     image: bash
      commands:
-+      - echo $docker_username
-+      - echo $DOCKER_PASSWORD
-+    secrets: [ docker_username, DOCKER_PASSWORD ]
++      - echo $some_username
++      - echo $SOME_PASSWORD
++    secrets: [ some_username, SOME_PASSWORD ]
 ```
 
 The case of the environment variables is not changed, but secret matching is done case-insensitively. In the example above, `DOCKER_PASSWORD` would also match if the secret is called `docker_password`.
 
-### Use secrets in settings and environment
+### Using secrets in non-plugin steps via "environment:"
 
-You can set an setting or environment value 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), and to the environment variable `TOKEN_ENV`.
+You can set an environment value from secrets using the `from_secret` syntax.
+This way, the secret key and environment variable name can differ.
 
 ```diff
  steps:
-   - name: docker
-     image: my-plugin
+   - name: test
+     image: bash
+     commands:
+       - env | grep OWN
+-    secrets: [ some_username, SOME_PASSWORD ]
 +    environment:
-+      TOKEN_ENV:
-+        from_secret: secret_token
-+    settings:
-+      token:
-+        from_secret: secret_token
++      SOME_OWN_DEFINED_VAR:
++        from_secret: some_username
+```
+
+### Using secrets in plugins-steps via "settings:"
+
+The `from_secret` syntax also works for settings in any hierarchy.
+
+:::info Important
+You cannot use `secrets` or `environment` directly in plugin steps, as this could alter plugin execution. Instead, use the `settings` field for secrets in plugins:
+
+- It's safer: Plugin settings are a controlled interface for customization.
+- It's consistent: Plugins define which settings they accept and how to handle them.
+- It maintains security: This approach doesn't compromise the plugin's integrity or security model.
+
+This restriction is enforced by the linter to ensure plugin safety and predictable behavior.
+:::
+
+In the example below, the secret `SURGE_TOKEN` would be passed to the setting named `surge_token`, which will be available in the plugin as an environment variable named `PLUGIN_SURGE_TOKEN` (See [plugins](./51-plugins/20-creating-plugins.md#settings) for details).
+
+```yaml
+steps:
+  - name: deploy-preview:
+    image: woodpeckerci/plugin-surge-preview
+    settings:
+      path: 'docs/build/'
+      surge_token:
+        from_secret: SURGE_TOKEN
 ```
 
+As settings can have complex structures, `from_secret` is supported at any level:
+
+```yaml
+steps:
+  - name: deploy-test:
+    image: plugin-example
+    settings:
+      path: 'artifacts'
+      simple_token:
+        from_secret: A_TOKEN
+      advanced_setting:
+        items:
+          - "value1"
+          - some:
+              from_secret: secret_value
+          - "value3"
+```
+
+This approach allows for flexible and secure use of secrets within plugin settings while maintaining the integrity and security of the plugin execution environment.
+
 ### Note about parameter pre-processing
 
 Please note parameter expressions are subject to pre-processing. When using secrets in parameter expressions they should be escaped.
 
 ```diff
  steps:
-   - name: docker
-     image: docker
+   - name: "echo password"
+     image: bash
      commands:
--      - echo ${docker_username}
--      - echo ${DOCKER_PASSWORD}
-+      - echo $${docker_username}
-+      - echo $${DOCKER_PASSWORD}
-     secrets: [ docker_username, DOCKER_PASSWORD ]
+-      - echo ${some_username}
+-      - echo ${SOME_PASSWORD}
++      - echo $${some_username}
++      - echo $${SOME_PASSWORD}
+     secrets: [ some_username, SOME_PASSWORD ]
 ```
 
 ### Use in Pull Requests events

docs/docs/20-usage/51-plugins/20-creating-plugins.md

@@ -42,7 +42,7 @@ Values like this are converted to JSON and then passed to your plugin. In the ex
 
 ### Secrets
 
-Secrets should be passed as settings too. Therefore, users should use [`from_secret`](../40-secrets.md#use-secrets-in-settings-and-environment).
+Secrets should be passed as a setting option. Therefore, users should use [`from_secret`](../40-secrets.md#using-secrets-in-non-plugin-steps-via-environment).
 
 ## Plugin library