diff --git a/content/manuals/engine/swarm/secrets.md b/content/manuals/engine/swarm/secrets.md
index 1cc272b643e8..2c8e18ccd339 100644
--- a/content/manuals/engine/swarm/secrets.md
+++ b/content/manuals/engine/swarm/secrets.md
@@ -125,6 +125,35 @@ Use these links to read about specific commands, or continue to the
 - [`--secret`](/reference/cli/docker/service/create/#secret) flag for `docker service create`
 - [`--secret-add` and `--secret-rm`](/reference/cli/docker/service/update/#secret-add) flags for `docker service update`
 
+## Defining and using secrets in compose files
+
+Using secrets in compose files alongside Docker Swarm is as simple as defining a secret
+using `docker secret create`.
+
+```console
+$ printf "my-secret" | docker secret create some_secret -
+```
+
+In the `compose.yml` file you can declare the secret as `external` in the top-level `secrets` attribute.
+
+```yaml
+services:
+    api:
+        image: my-web-app
+        environment:
+            MY_ENV: /run/secrets/some_secret
+        secrets:
+            - some_secret
+
+secrets:
+    some_secret:
+        external: true
+```
+
+Both the `docker-compose` and `docker stack` commands support defining secrets
+in a compose file. See
+[the Compose file reference](/reference/compose-file/secrets.md) for details.
+
 ## Examples
 
 This section includes three graduated examples which illustrate how to use
@@ -139,12 +168,6 @@ a similar way, see
 > simplicity. The examples use Linux containers, but Windows containers also
 > support secrets. See [Windows support](#windows-support).
 
-### Defining and using secrets in compose files
-
-Both the `docker-compose` and `docker stack` commands support defining secrets
-in a compose file. See
-[the Compose file reference](/reference/compose-file/legacy-versions.md) for details.
-
 ### Simple example: Get started with secrets
 
 This simple example shows how secrets work in just a few commands. For a
diff --git a/content/reference/compose-file/secrets.md b/content/reference/compose-file/secrets.md
index 07870fbbf96d..91bccd986976 100644
--- a/content/reference/compose-file/secrets.md
+++ b/content/reference/compose-file/secrets.md
@@ -15,8 +15,12 @@ The top-level `secrets` declaration defines or references sensitive data that is
 application. The source of the secret is either `file` or `environment`.
 
 - `file`: The secret is created with the contents of the file at the specified path.
-- `environment`: The secret is created with the value of an environment variable on the host. This is only supported by Docker Compose. It is not supported when deploying with [`docker stack deploy`](/manuals/engine/swarm/stack-deploy.md).
- 
+- `environment`: The secret is created with the value of an environment variable on the host. This is only supported by Docker Compose. It is not supported when deploying with [`docker stack deploy`](/manuals/engine/swarm/stack-deploy.md). 
+
+> [!NOTE]
+> `external` property is available only for Docker Swarm. Docker Compose will ignore this attribute.
+
+- `external`: If set to true, `external` specifies that this secret has already been created via `docker secret create`. Docker does not attempt to create it, and if it does not exist, an error occurs.
 
 ## Example 1