Merge pull request #32332 from mstanleyjones/1.13.x1.13.x

Cherry-pick command-line ref improvements

1 files changed, 18 insertions, 1 deletions

diff --git a/docs/reference/commandline/network_connect.md b/docs/reference/commandline/network_connect.md
index 52459a5d5f..7c5a5867f0 100644
--- a/docs/reference/commandline/network_connect.md
+++ b/docs/reference/commandline/network_connect.md
@@ -29,38 +29,55 @@ Options:
       --link-local-ip value   Add a link-local address for the container (default [])
 ```
 
+## Description
+
 Connects a container to a network. You can connect a container by name
 or by ID. Once connected, the container can communicate with other containers in
 the same network.
 
+## Examples
+
+### Connect a running container to a network
+
 ```bash
 $ docker network connect multi-host-network container1
 ```
 
+### Connect a container to a network when it starts
+
 You can also use the `docker run --network=<network-name>` option to start a container and immediately connect it to a network.
 
 ```bash
 $ docker run -itd --network=multi-host-network busybox
 ```
 
+### Specify the IP address a container will use on a given network
+
 You can specify the IP address you want to be assigned to the container's interface.
 
 ```bash
 $ docker network connect --ip 10.10.36.122 multi-host-network container2
 ```
 
+### Use the legacy `--link` option
+
 You can use `--link` option to link another container with a preferred alias
 
 ```bash
 $ docker network connect --link container1:c1 multi-host-network container2
 ```
 
+### Create a network alias for a container
+
 `--alias` option can be used to resolve the container by another name in the network
 being connected to.
 
 ```bash
 $ docker network connect --alias db --alias mysql multi-host-network container2
 ```
+
+### Network implications of stopping, pausing, or restarting containers
+
 You can pause, restart, and stop containers that are connected to a network.
 A container connects to its configured networks when it runs.
 
@@ -88,7 +105,7 @@ network but launched from different Engines can also communicate in this way.
 
 You can connect a container to one or more networks. The networks need not be the same type. For example, you can connect a single container bridge and overlay networks.
 
-## Related information
+## Related commands
 
 * [network inspect](network_inspect.md)
 * [network create](network_create.md)