ENGDOCS-1744 (#18491)

* ENGDOCS-1744

* tweak

content/storage/_index.md

@@ -1,7 +1,7 @@
 ---
 description: Overview of persisting data in containers
 title: Manage data in Docker
-keywords: storage, persistence, data persistence, volumes, mounts, bind mounts
+keywords: storage, persistence, data persistence, volumes, mounts, bind mounts, tmpfs
 aliases:
 - engine/admin/volumes/
 ---
@@ -20,14 +20,12 @@ container layer. This means that:
   _data volumes_, which write directly to the host filesystem.
 
 Docker has two options for containers to store files on the host machine, so
-that the files are persisted even after the container stops: _volumes_, and
+that the files are persisted even after the container stops: volumes, and
-_bind mounts_. 
+bind mounts. 
 
 Docker also supports containers storing files in-memory on the host machine. Such files are not persisted.
-If you're running Docker on Linux, _tmpfs mount_ is used to store files in the host's system memory.
+If you're running Docker on Linux, `tmpfs` mount is used to store files in the host's system memory.
-If you're running Docker on Windows, _named pipe_ is used to store files in the host's system memory.
+If you're running Docker on Windows, named pipe is used to store files in the host's system memory.
-
-Keep reading for more information about persisting data or taking advantage of in-memory files.
 
 ## Choose the right type of mount
 
@@ -40,21 +38,21 @@ mounts is to think about where the data lives on the Docker host.
 
 ![Types of mounts and where they live on the Docker host](images/types-of-mounts.png)
 
-- **Volumes** are stored in a part of the host filesystem which is _managed by
+- Volumes are stored in a part of the host filesystem which is _managed by
   Docker_ (`/var/lib/docker/volumes/` on Linux). Non-Docker processes should not
   modify this part of the filesystem. Volumes are the best way to persist data
   in Docker.
 
-- **Bind mounts** may be stored *anywhere* on the host system. They may even be
+- Bind mounts may be stored anywhere on the host system. They may even be
   important system files or directories. Non-Docker processes on the Docker host
   or a Docker container can modify them at any time.
 
-- **`tmpfs` mounts** are stored in the host system's memory only, and are never
+- `tmpfs` mounts are stored in the host system's memory only, and are never
   written to the host system's filesystem.
 
 ### More details about mount types
 
-- **[Volumes](volumes.md)**: Created and managed by Docker. You can create a
+- [Volumes](volumes.md): Created and managed by Docker. You can create a
   volume explicitly using the `docker volume create` command, or Docker can
   create a volume during container or service creation.
 
@@ -69,31 +67,33 @@ mounts is to think about where the data lives on the Docker host.
   and is not removed automatically. You can remove unused volumes using `docker
   volume prune`.
 
-  When you mount a volume, it may be **named** or **anonymous**. Anonymous
+  When you mount a volume, it may be named or anonymous. Anonymous
   volumes are not given an explicit name when they are first mounted into a
   container, so Docker gives them a random name that is guaranteed to be unique
   within a given Docker host. Besides the name, named and anonymous volumes
   behave in the same ways.
 
-  Volumes also support the use of _volume drivers_, which allow you to store
+  Volumes also support the use of volume drivers, which allow you to store
   your data on remote hosts or cloud providers, among other possibilities.
 
-- **[Bind mounts](bind-mounts.md)**: Available since the early days of Docker.
+- [Bind mounts](bind-mounts.md): Available since the early days of Docker.
   Bind mounts have limited functionality compared to volumes. When you use a
-  bind mount, a file or directory on the _host machine_ is mounted into a
+  bind mount, a file or directory on the host machine is mounted into a
   container. The file or directory is referenced by its full path on the host
-  machine. The file or directory does not need to exist on the Docker host
+  machine. The file or directory doesn't need to exist on the Docker host
   already. It is created on demand if it does not yet exist. Bind mounts are
   very performant, but they rely on the host machine's filesystem having a
   specific directory structure available. If you are developing new Docker
   applications, consider using named volumes instead. You can't use
   Docker CLI commands to directly manage bind mounts.
 
-  > Bind mounts allow access to sensitive files
+  > **Important**
+  >
+  > Bind mounts allow access to sensitive files.
   >
   > One side effect of using bind mounts, for better or for worse,
-  > is that you can change the **host** filesystem via processes running in a
+  > is that you can change the host filesystem via processes running in a
-  > **container**, including creating, modifying, or deleting important system
+  > container, including creating, modifying, or deleting important system
   > files or directories. This is a powerful ability which can have security
   > implications, including impacting non-Docker processes on the host system.
   { .important }

content/storage/bind-mounts.md

@@ -8,7 +8,7 @@ aliases:
 
 Bind mounts have been around since the early days of Docker. Bind mounts have
 limited functionality compared to [volumes](volumes.md). When you use a bind
-mount, a file or directory on the _host machine_ is mounted into a container.
+mount, a file or directory on the host machine is mounted into a container.
 The file or directory is referenced by its absolute path on the host
 machine. By contrast, when you use a volume, a new directory is created within
 Docker's storage directory on the host machine, and Docker manages that
@@ -34,8 +34,9 @@ syntax separates them. Here is a comparison of the syntax for each flag.
 > New users should use the `--mount` syntax. Experienced users may
 > be more familiar with the `-v` or `--volume` syntax, but are encouraged to
 > use `--mount`, because research has shown it to be easier to use.
+{ .tip }
 
-- **`-v` or `--volume`**: Consists of three fields, separated by colon characters
+- `-v` or `--volume`: Consists of three fields, separated by colon characters
   (`:`). The fields must be in the correct order, and the meaning of each field
   is not immediately obvious.
   - In the case of bind mounts, the first field is the path to the file or
@@ -46,7 +47,7 @@ syntax separates them. Here is a comparison of the syntax for each flag.
     as `ro`, `z`, and `Z`. These options
     are discussed below.
 
-- **`--mount`**: Consists of multiple key-value pairs, separated by commas and each
+- `--mount`: Consists of multiple key-value pairs, separated by commas and each
   consisting of a `<key>=<value>` tuple. The `--mount` syntax is more verbose
   than `-v` or `--volume`, but the order of the keys is not significant, and
   the value of the flag is easier to understand.
@@ -72,15 +73,15 @@ The examples below show both the `--mount` and `-v` syntax where possible, and
 ### Differences between `-v` and `--mount` behavior
 
 Because the `-v` and `--volume` flags have been a part of Docker for a long
-time, their behavior cannot be changed. This means that **there is one behavior
+time, their behavior cannot be changed. This means that there is one behavior
-that is different between `-v` and `--mount`.**
+that is different between `-v` and `--mount`.
 
 If you use `-v` or `--volume` to bind-mount a file or directory that does not
-yet exist on the Docker host, `-v` creates the endpoint for you. **It is
+yet exist on the Docker host, `-v` creates the endpoint for you. It is
-always created as a directory.**
+always created as a directory.
 
 If you use `--mount` to bind-mount a file or directory that does not
-yet exist on the Docker host, Docker does **not** automatically create it for
+yet exist on the Docker host, Docker does not automatically create it for
 you, but generates an error.
 
 ## Start a container with a bind mount
@@ -279,7 +280,7 @@ propagation setting has a recursive counterpoint. In the case of recursion,
 consider that `/tmp/a` is also mounted as `/foo`. The propagation settings
 control whether `/mnt/a` and/or `/tmp/a` would exist.
 
-> Warning
+> **Warning**
 >
 > Mount propagation doesn't work with Docker Desktop.
 { .warning }
@@ -337,7 +338,7 @@ Now if you create `/app/foo/`, `/app2/foo/` also exists.
 ## Configure the selinux label
 
 If you use `selinux` you can add the `z` or `Z` options to modify the selinux
-label of the **host file or directory** being mounted into the container. This
+label of the host file or directory being mounted into the container. This
 affects the file or directory on the host machine itself and can have
 consequences outside of the scope of Docker.
 
@@ -345,11 +346,13 @@ consequences outside of the scope of Docker.
   containers.
 - The `Z` option indicates that the bind mount content is private and unshared.
 
-Use **extreme** caution with these options. Bind-mounting a system directory
+Use extreme caution with these options. Bind-mounting a system directory
 such as `/home` or `/usr` with the `Z` option renders your host machine
 inoperable and you may need to relabel the host machine files by hand.
 
-> **Important**: When using bind mounts with services, selinux labels
+> **Important**
+>
+> When using bind mounts with services, selinux labels
 > (`:Z` and `:z`), as well as `:ro` are ignored. See
 > [moby/moby #32579](https://github.com/moby/moby/issues/32579) for details.
 { .important }

content/storage/tmpfs.md

@@ -35,10 +35,10 @@ containers.
 In general, `--mount` is more explicit and verbose. The biggest difference is
 that the `--tmpfs` flag does not support any configurable options.
 
-- **`--tmpfs`**: Mounts a `tmpfs` mount without allowing you to specify any
+- `--tmpfs`: Mounts a `tmpfs` mount without allowing you to specify any
   configurable options, and can only be used with standalone containers.
 
-- **`--mount`**: Consists of multiple key-value pairs, separated by commas and each
+- `--mount`: Consists of multiple key-value pairs, separated by commas and each
   consisting of a `<key>=<value>` tuple. The `--mount` syntax is more verbose
   than `--tmpfs`:
   - The `type` of the mount, which can be [`bind`](bind-mounts.md), `volume`, or

content/storage/troubleshooting_volume_errors.md

@@ -1,7 +1,7 @@
 ---
 description: Troubleshooting volume errors
 keywords: cadvisor, troubleshooting, volumes, bind-mounts
-title: Troubleshoot volume errors
+title: Troubleshoot storage errors
 aliases:
 - /engine/admin/troubleshooting_volume_errors/
 ---

content/storage/volumes.md

@@ -49,7 +49,7 @@ syntax separates them. Here is a comparison of the syntax for each flag.
 
 If you need to specify volume driver options, you must use `--mount`.
 
-- **`-v` or `--volume`**: Consists of three fields, separated by colon characters
+- `-v` or `--volume`: Consists of three fields, separated by colon characters
   (`:`). The fields must be in the correct order, and the meaning of each field
   isn't immediately obvious.
 
@@ -61,7 +61,7 @@ If you need to specify volume driver options, you must use `--mount`.
   - The third field is optional, and is a comma-separated list of options, such
     as `ro`. These options are discussed below.
 
-- **`--mount`**: Consists of multiple key-value pairs, separated by commas and each
+- `--mount`: Consists of multiple key-value pairs, separated by commas and each
   consisting of a `<key>=<value>` tuple. The `--mount` syntax is more verbose
   than `-v` or `--volume`, but the order of the keys isn't significant, and
   the value of the flag is easier to understand.
@@ -79,7 +79,7 @@ If you need to specify volume driver options, you must use `--mount`.
   - The `volume-opt` option, which can be specified more than once, takes a
     key-value pair consisting of the option name and its value.
 
-> Escape values from outer CSV parser
+> **Warning**
 >
 > If your volume driver accepts a comma-separated list as an option,
 > you must escape the value from the outer CSV parser. To escape a `volume-opt`,
@@ -89,17 +89,18 @@ If you need to specify volume driver options, you must use `--mount`.
 > For example, the `local` driver accepts mount options as a comma-separated
 > list in the `o` parameter. This example shows the correct way to escape the list.
 >
->     $ docker service create \
+> ```console
->         --mount 'type=volume,src=<VOLUME-NAME>,dst=<CONTAINER-PATH>,volume-driver=local,volume-opt=type=nfs,volume-opt=device=<nfs-server>:<nfs-path>,"volume-opt=o=addr=<nfs-address>,vers=4,soft,timeo=180,bg,tcp,rw"'
+> $ docker service create \
->         --name myservice \
+>  --mount 'type=volume,src=<VOLUME-NAME>,dst=<CONTAINER-PATH>,volume-driver=local,volume-opt=type=nfs,volume-opt=device=<nfs-server>:<nfs-path>,"volume-opt=o=addr=<nfs-address>,vers=4,soft,timeo=180,bg,tcp,rw"'
->         <IMAGE>
+>  --name myservice \
->
+>  <IMAGE>
-> { .warning }
+> ```
+{ .warning }
 
 The examples below show both the `--mount` and `-v` syntax where possible, with
 `--mount` first.
 
-### Differences between `-v` and `--mount` behavior
+### Differences between `-v` and `--mount` behavior 
 
 As opposed to bind mounts, all options for volumes are available for both
 `--mount` and `-v` flags.
@@ -111,13 +112,13 @@ Volumes used with services, only support `--mount`.
 Unlike a bind mount, you can create and manage volumes outside the scope of any
 container.
 
-**Create a volume**:
+Create a volume:
 
 ```console
 $ docker volume create my-vol
 ```
 
-**List volumes**:
+List volumes:
 
 ```console
 $ docker volume ls
@@ -125,7 +126,7 @@ $ docker volume ls
 local               my-vol
 ```
 
-**Inspect a volume**:
+Inspect a volume:
 
 ```console
 $ docker volume inspect my-vol
@@ -141,7 +142,7 @@ $ docker volume inspect my-vol
 ]
 ```
 
-**Remove a volume**:
+Remove a volume:
 
 ```console
 $ docker volume rm my-vol
@@ -229,7 +230,7 @@ volumes:
 Running `docker compose up` for the first time creates a volume. Docker reuses the same volume when you run the command subsequently.
 
 You can create a volume directly outside of Compose using `docker volume create` and
-then reference it inside `docker-compose.yml` as follows:
+then reference it inside `compose.yaml` as follows:
 
 ```yaml
 services:
@@ -458,7 +459,7 @@ The following example specifies an SSH password. However, if the two hosts have
 shared keys configured, you can exclude the password.
 Each volume driver may have zero or more configurable options.
 
-> **Note:**
+> **Note**
 >
 > If the volume driver requires you to pass any options,
 > you must use the `--mount` flag to mount the volume, and not `-v`.
@@ -669,7 +670,7 @@ the Docker Engine removes the `/foo` volume but not the `awesome` volume.
 $ docker run --rm -v /foo -v awesome:/bar busybox top
 ```
 
-> **Note**:
+> **Note**
 >
 > If another container binds the volumes with
 > `--volumes-from`, the volume definitions are _copied_ and the