diff --git a/Makefile b/Makefile
index 81bde6b..1b1a129 100644
--- a/Makefile
+++ b/Makefile
@@ -117,6 +117,9 @@
 shell: build ## start a shell inside the build env
 	$(DOCKER_RUN_DOCKER) bash
 
+yaml-docs-gen: build ## generate documentation YAML files consumed by docs repo
+	$(DOCKER_RUN_DOCKER) sh -c 'hack/make.sh yaml-docs-generator && ( root=$$(pwd); cd bundles/latest/yaml-docs-generator; mkdir docs; ./yaml-docs-generator --root $${root} --target $$(pwd)/docs )'
+
 test: build ## run the unit, integration and docker-py tests
 	$(DOCKER_RUN_DOCKER) hack/make.sh dynbinary cross test-unit test-integration-cli test-docker-py
 
diff --git a/docs/reference/commandline/attach.md b/docs/reference/commandline/attach.md
index 307068a..9f76a54 100644
--- a/docs/reference/commandline/attach.md
+++ b/docs/reference/commandline/attach.md
@@ -27,6 +27,8 @@
       --sig-proxy            Proxy all received signals to the process (default true)
 ```
 
+## Description
+
 Use `docker attach` to attach to a running container using the container's ID
 or name, either to view its ongoing output or to control it interactively.
 You can attach to the same contained process multiple times simultaneously,
@@ -55,8 +57,7 @@
 foreground over a slow client connection. Instead, users should use the
 `docker logs` command to get access to the logs.
 
-
-## Override the detach sequence
+### Override the detach sequence
 
 If you want, you can configure an override the Docker key sequence for detach.
 This is useful if the Docker default sequence conflicts with key sequence you
@@ -80,52 +81,72 @@
 sequences. To configure a different configuration default key sequence for all
 containers, see [**Configuration file** section](cli.md#configuration-files).
 
-#### Examples
+## Examples
 
-    $ docker run -d --name topdemo ubuntu /usr/bin/top -b
-    $ docker attach topdemo
-    top - 02:05:52 up  3:05,  0 users,  load average: 0.01, 0.02, 0.05
-    Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
-    Cpu(s):  0.1%us,  0.2%sy,  0.0%ni, 99.7%id,  0.0%wa,  0.0%hi,  0.0%si,  0.0%st
-    Mem:    373572k total,   355560k used,    18012k free,    27872k buffers
-    Swap:   786428k total,        0k used,   786428k free,   221740k cached
+### Attach to and detach from a running container
 
-    PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
-     1 root      20   0 17200 1116  912 R    0  0.3   0:00.03 top
+```bash
+$ docker run -d --name topdemo ubuntu /usr/bin/top -b
 
-     top - 02:05:55 up  3:05,  0 users,  load average: 0.01, 0.02, 0.05
-     Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
-     Cpu(s):  0.0%us,  0.2%sy,  0.0%ni, 99.8%id,  0.0%wa,  0.0%hi,  0.0%si,  0.0%st
-     Mem:    373572k total,   355244k used,    18328k free,    27872k buffers
-     Swap:   786428k total,        0k used,   786428k free,   221776k cached
+$ docker attach topdemo
 
-       PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
-           1 root      20   0 17208 1144  932 R    0  0.3   0:00.03 top
+top - 02:05:52 up  3:05,  0 users,  load average: 0.01, 0.02, 0.05
+Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
+Cpu(s):  0.1%us,  0.2%sy,  0.0%ni, 99.7%id,  0.0%wa,  0.0%hi,  0.0%si,  0.0%st
+Mem:    373572k total,   355560k used,    18012k free,    27872k buffers
+Swap:   786428k total,        0k used,   786428k free,   221740k cached
+
+PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
+ 1 root      20   0 17200 1116  912 R    0  0.3   0:00.03 top
+
+ top - 02:05:55 up  3:05,  0 users,  load average: 0.01, 0.02, 0.05
+ Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
+ Cpu(s):  0.0%us,  0.2%sy,  0.0%ni, 99.8%id,  0.0%wa,  0.0%hi,  0.0%si,  0.0%st
+ Mem:    373572k total,   355244k used,    18328k free,    27872k buffers
+ Swap:   786428k total,        0k used,   786428k free,   221776k cached
+
+   PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
+       1 root      20   0 17208 1144  932 R    0  0.3   0:00.03 top
 
 
-     top - 02:05:58 up  3:06,  0 users,  load average: 0.01, 0.02, 0.05
-     Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
-     Cpu(s):  0.2%us,  0.3%sy,  0.0%ni, 99.5%id,  0.0%wa,  0.0%hi,  0.0%si,  0.0%st
-     Mem:    373572k total,   355780k used,    17792k free,    27880k buffers
-     Swap:   786428k total,        0k used,   786428k free,   221776k cached
+ top - 02:05:58 up  3:06,  0 users,  load average: 0.01, 0.02, 0.05
+ Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
+ Cpu(s):  0.2%us,  0.3%sy,  0.0%ni, 99.5%id,  0.0%wa,  0.0%hi,  0.0%si,  0.0%st
+ Mem:    373572k total,   355780k used,    17792k free,    27880k buffers
+ Swap:   786428k total,        0k used,   786428k free,   221776k cached
 
-     PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
-          1 root      20   0 17208 1144  932 R    0  0.3   0:00.03 top
-    ^C$
-    $ echo $?
-    0
-    $ docker ps -a | grep topdemo
-    7998ac8581f9        ubuntu:14.04        "/usr/bin/top -b"   38 seconds ago      Exited (0) 21 seconds ago                          topdemo
+ PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
+      1 root      20   0 17208 1144  932 R    0  0.3   0:00.03 top
+^C$
+
+$ echo $?
+0
+$ docker ps -a | grep topdemo
+
+7998ac8581f9        ubuntu:14.04        "/usr/bin/top -b"   38 seconds ago      Exited (0) 21 seconds ago                          topdemo
+```
+
+### Get the exit code of the container's command
 
 And in this second example, you can see the exit code returned by the `bash`
 process is returned by the `docker attach` command to its caller too:
 
+```bash
     $ docker run --name test -d -it debian
+
     275c44472aebd77c926d4527885bb09f2f6db21d878c75f0a1c212c03d3bcfab
+
     $ docker attach test
+
     root@f38c87f2a42d:/# exit 13
+
     exit
+
     $ echo $?
+
     13
+
     $ docker ps -a | grep test
+
     275c44472aeb        debian:7            "/bin/bash"         26 seconds ago      Exited (13) 17 seconds ago                         test
+```
diff --git a/docs/reference/commandline/build.md b/docs/reference/commandline/build.md
index 42c3ecf..b141e74 100644
--- a/docs/reference/commandline/build.md
+++ b/docs/reference/commandline/build.md
@@ -58,6 +58,8 @@
       --ulimit value            Ulimit options (default [])
 ```
 
+## Description
+
 Builds Docker images from a Dockerfile and a "context". A build's context is
 the files located in the specified `PATH` or `URL`. The build process can refer
 to any of the files in the context. For example, your build can use an
@@ -285,7 +287,7 @@
 This will build an image for a compressed context read from `STDIN`.  Supported
 formats are: bzip2, gzip and xz.
 
-### Usage of .dockerignore
+### Use a .dockerignore file
 
 ```bash
 $ docker build .
@@ -315,7 +317,7 @@
 uploaded context. The builder reference contains detailed information on
 [creating a .dockerignore file](../builder.md#dockerignore-file)
 
-### Tag image (-t)
+### Tag an image (-t)
 
 ```bash
 $ docker build -t vieux/apache:2.0 .
@@ -334,7 +336,7 @@
 ```bash
 $ docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1 .
 ```
-### Specify Dockerfile (-f)
+### Specify a Dockerfile (-f)
 
 ```bash
 $ docker build -f Dockerfile.debug .
@@ -373,7 +375,7 @@
 > repeatable builds on remote Docker hosts. This is also the reason why
 > `ADD ../file` will not work.
 
-### Optional parent cgroup (--cgroup-parent)
+### Use a custom parent cgroup (--cgroup-parent)
 
 When `docker build` is run with the `--cgroup-parent` option the containers
 used in the build will be run with the [corresponding `docker run`
diff --git a/docs/reference/commandline/cli.md b/docs/reference/commandline/cli.md
index e56fb9f..3b4577a 100644
--- a/docs/reference/commandline/cli.md
+++ b/docs/reference/commandline/cli.md
@@ -13,7 +13,7 @@
      will be rejected.
 -->
 
-# Use the Docker command line
+# docker
 
 To list available commands, either run `docker` with no parameters
 or execute `docker help`:
@@ -43,6 +43,8 @@
     # […]
 ```
 
+## Description
+
 Depending on your Docker system configuration, you may be required to preface
 each `docker` command with `sudo`. To avoid having to use `sudo` with the
 `docker` command, your system administrator can create a Unix group called
@@ -51,7 +53,7 @@
 For more information about installing Docker or `sudo` configuration, refer to
 the [installation](https://docs.docker.com/engine/installation/) instructions for your operating system.
 
-## Environment variables
+### Environment variables
 
 For easy reference, the following list of environment variables are supported
 by the `docker` command line:
@@ -69,7 +71,7 @@
   Equates to `--disable-content-trust=false` for build, create, pull, push, run.
 * `DOCKER_CONTENT_TRUST_SERVER` The URL of the Notary server to use. This defaults
   to the same URL as the registry.
-* `DOCKER_HIDE_LEGACY_COMMANDS` When set, Docker hides "legacy" top-level commands (such as `docker rm`, and 
+* `DOCKER_HIDE_LEGACY_COMMANDS` When set, Docker hides "legacy" top-level commands (such as `docker rm`, and
   `docker pull`) in `docker help` output, and only `Management commands` per object-type (e.g., `docker container`) are
   printed. This may become the default in a future release, at which point this environment-variable is removed.
 * `DOCKER_TMPDIR` Location for temporary Docker files.
@@ -85,7 +87,7 @@
 [Go specification](http://golang.org/pkg/net/http/) for details on these
 variables.
 
-## Configuration files
+### Configuration files
 
 By default, the Docker command line stores its configuration files in a
 directory called `.docker` within your `$HOME` directory. However, you can
@@ -165,18 +167,23 @@
 
 Following is a sample `config.json` file:
 
-    {% raw %}
-    {
-      "HttpHeaders": {
-        "MyHeader": "MyValue"
-      },
-      "psFormat": "table {{.ID}}\\t{{.Image}}\\t{{.Command}}\\t{{.Labels}}",
-      "imagesFormat": "table {{.ID}}\\t{{.Repository}}\\t{{.Tag}}\\t{{.CreatedAt}}",
-      "statsFormat": "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}",
-      "serviceInspectFormat": "pretty",
-      "detachKeys": "ctrl-e,e"
-    }
-    {% endraw %}
+```json
+{
+  "HttpHeaders": {
+    "MyHeader": "MyValue"
+  },
+  "psFormat": "table {{.ID}}\\t{{.Image}}\\t{{.Command}}\\t{{.Labels}}",
+  "imagesFormat": "table {{.ID}}\\t{{.Repository}}\\t{{.Tag}}\\t{{.CreatedAt}}",
+  "statsFormat": "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}",
+  "serviceInspectFormat": "pretty",
+  "detachKeys": "ctrl-e,e",
+  "credsStore": "secretservice",
+  "credHelpers": {
+    "awesomereg.example.org": "hip-star",
+    "unicorn.example.com": "vcbait"
+  }
+}
+```
 
 ### Notary
 
@@ -187,7 +194,9 @@
 Alternatively you can trust the certificate globally by adding it to your system's
 list of root Certificate Authorities.
 
-## Help
+## Examples
+
+### Display help text
 
 To list the help on any command just execute the command, followed by the
 `--help` option.
@@ -203,13 +212,13 @@
       -a, --attach value               Attach to STDIN, STDOUT or STDERR (default [])
     ...
 
-## Option types
+### Option types
 
 Single character command line options can be combined, so rather than
 typing `docker run -i -t --name test busybox sh`,
 you can write `docker run -it --name test busybox sh`.
 
-### Boolean
+#### Boolean
 
 Boolean options take the form `-d=false`. The value you see in the help text is
 the default value which is set if you do **not** specify that flag. If you
@@ -222,27 +231,33 @@
 Options which default to `true` (e.g., `docker build --rm=true`) can only be
 set to the non-default value by explicitly setting them to `false`:
 
-    $ docker build --rm=false .
+```bash
+$ docker build --rm=false .
+```
 
-### Multi
+#### Multi
 
 You can specify options like `-a=[]` multiple times in a single command line,
 for example in these commands:
 
-    $ docker run -a stdin -a stdout -i -t ubuntu /bin/bash
-    $ docker run -a stdin -a stdout -a stderr ubuntu /bin/ls
+```bash
+$ docker run -a stdin -a stdout -i -t ubuntu /bin/bash
+
+$ docker run -a stdin -a stdout -a stderr ubuntu /bin/ls
+```
 
 Sometimes, multiple options can call for a more complex value string as for
 `-v`:
 
-    $ docker run -v /host:/container example/mysql
+```bash
+$ docker run -v /host:/container example/mysql
+```
 
-> **Note:**
-> Do not use the `-t` and `-a stderr` options together due to
+> **Note**: Do not use the `-t` and `-a stderr` options together due to
 > limitations in the `pty` implementation. All `stderr` in `pty` mode
 > simply goes to `stdout`.
 
-### Strings and Integers
+#### Strings and Integers
 
 Options like `--name=""` expect a string, and they
 can only be specified once. Options like `-c=0`
diff --git a/docs/reference/commandline/commit.md b/docs/reference/commandline/commit.md
index 8f971a5..22c98e3 100644
--- a/docs/reference/commandline/commit.md
+++ b/docs/reference/commandline/commit.md
@@ -28,6 +28,8 @@
   -p, --pause            Pause container during commit (default true)
 ```
 
+## Description
+
 It can be useful to commit a container's file changes or settings into a new
 image. This allows you debug a container by running an interactive shell, or to
 export a working dataset to another server. Generally, it is better to use
@@ -46,48 +48,70 @@
 created.  Supported `Dockerfile` instructions:
 `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`LABEL`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR`
 
-## Commit a container
+## Examples
 
-    $ docker ps
-    ID                  IMAGE               COMMAND             CREATED             STATUS              PORTS
-    c3f279d17e0a        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours
-    197387f1b436        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours
-    $ docker commit c3f279d17e0a  svendowideit/testimage:version3
-    f5283438590d
-    $ docker images
-    REPOSITORY                        TAG                 ID                  CREATED             SIZE
-    svendowideit/testimage            version3            f5283438590d        16 seconds ago      335.7 MB
+### Commit a container
 
-## Commit a container with new configurations
+```bash
+$ docker ps
 
-    {% raw %}
-    $ docker ps
-    ID                  IMAGE               COMMAND             CREATED             STATUS              PORTS
-    c3f279d17e0a        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours
-    197387f1b436        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours
-    $ docker inspect -f "{{ .Config.Env }}" c3f279d17e0a
-    [HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin]
-    $ docker commit --change "ENV DEBUG true" c3f279d17e0a  svendowideit/testimage:version3
-    f5283438590d
-    $ docker inspect -f "{{ .Config.Env }}" f5283438590d
-    [HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin DEBUG=true]
-    {% endraw %}
+CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS              NAMES
+c3f279d17e0a        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours                            desperate_dubinsky
+197387f1b436        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours                            focused_hamilton
 
-## Commit a container with new `CMD` and `EXPOSE` instructions
+$ docker commit c3f279d17e0a  svendowideit/testimage:version3
 
-    $ docker ps
-    ID                  IMAGE               COMMAND             CREATED             STATUS              PORTS
-    c3f279d17e0a        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours
-    197387f1b436        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours
+f5283438590d
 
-    $ docker commit --change='CMD ["apachectl", "-DFOREGROUND"]' -c "EXPOSE 80" c3f279d17e0a  svendowideit/testimage:version4
-    f5283438590d
+$ docker images
 
-    $ docker run -d svendowideit/testimage:version4
-    89373736e2e7f00bc149bd783073ac43d0507da250e999f3f1036e0db60817c0
+REPOSITORY                        TAG                 ID                  CREATED             SIZE
+svendowideit/testimage            version3            f5283438590d        16 seconds ago      335.7 MB
+```
 
-    $ docker ps
-    ID                  IMAGE               COMMAND                 CREATED             STATUS              PORTS
-    89373736e2e7        testimage:version4  "apachectl -DFOREGROU"  3 seconds ago       Up 2 seconds        80/tcp
-    c3f279d17e0a        ubuntu:12.04        /bin/bash               7 days ago          Up 25 hours
-    197387f1b436        ubuntu:12.04        /bin/bash               7 days ago          Up 25 hours
+### Commit a container with new configurations
+
+```bash
+$ docker ps
+
+ICONTAINER ID       IMAGE               COMMAND             CREATED             STATUS              PORTS              NAMES
+c3f279d17e0a        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours                            desperate_dubinsky
+197387f1b436        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours                            focused_hamilton
+
+$ docker inspect -f "{{ .Config.Env }}" c3f279d17e0a
+
+[HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin]
+
+$ docker commit --change "ENV DEBUG true" c3f279d17e0a  svendowideit/testimage:version3
+
+f5283438590d
+
+$ docker inspect -f "{{ .Config.Env }}" f5283438590d
+
+[HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin DEBUG=true]
+```
+
+### Commit a container with new `CMD` and `EXPOSE` instructions
+
+```bash
+$ docker ps
+
+CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS              NAMES
+c3f279d17e0a        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours                            desperate_dubinsky
+197387f1b436        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours                            focused_hamilton
+
+$ docker commit --change='CMD ["apachectl", "-DFOREGROUND"]' -c "EXPOSE 80" c3f279d17e0a  svendowideit/testimage:version4
+
+f5283438590d
+
+$ docker run -d svendowideit/testimage:version4
+
+89373736e2e7f00bc149bd783073ac43d0507da250e999f3f1036e0db60817c0
+
+$ docker ps
+
+CONTAINER ID        IMAGE               COMMAND                 CREATED             STATUS              PORTS              NAMES
+89373736e2e7        testimage:version4  "apachectl -DFOREGROU"  3 seconds ago       Up 2 seconds        80/tcp             distracted_fermat
+c3f279d17e0a        ubuntu:12.04        /bin/bash               7 days ago          Up 25 hours                            desperate_dubinsky
+197387f1b436        ubuntu:12.04        /bin/bash               7 days ago          Up 25 hours                            focused_hamilton
+```
diff --git a/docs/reference/commandline/container_prune.md b/docs/reference/commandline/container_prune.md
index 4315640..3b917b2 100644
--- a/docs/reference/commandline/container_prune.md
+++ b/docs/reference/commandline/container_prune.md
@@ -25,8 +25,14 @@
       --help    Print usage
 ```
 
+## Description
+
+Removes all stopped containers.
+
 ## Examples
 
+### Prune containers
+
 ```bash
 $ docker container prune
 WARNING! This will remove all stopped containers.
@@ -38,7 +44,7 @@
 Total reclaimed space: 212 B
 ```
 
-## Related information
+## Related commands
 
 * [system df](system_df.md)
 * [volume prune](volume_prune.md)
diff --git a/docs/reference/commandline/cp.md b/docs/reference/commandline/cp.md
index fcfd35f..abd3a37 100644
--- a/docs/reference/commandline/cp.md
+++ b/docs/reference/commandline/cp.md
@@ -31,6 +31,8 @@
       --help          Print usage
 ```
 
+## Description
+
 The `docker cp` utility copies the contents of `SRC_PATH` to the `DEST_PATH`.
 You can copy from the container's file system to the local machine or the
 reverse, from the local filesystem to the container. If `-` is specified for
@@ -96,15 +98,16 @@
 It is not possible to copy certain system files such as resources under
 `/proc`, `/sys`, `/dev`, [tmpfs](run.md#mount-tmpfs-tmpfs), and mounts created by
 the user in the container. However, you can still copy such files by manually
-running `tar` in `docker exec`. For example (consider `SRC_PATH` and `DEST_PATH`
-are directories):
+running `tar` in `docker exec`. Both of the following examples do the same thing
+in different ways (consider `SRC_PATH` and `DEST_PATH` are directories):
 
-    $ docker exec foo tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | tar Cxf DEST_PATH -
+```bash
+$ docker exec foo tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | tar Cxf DEST_PATH -
+```
 
-or
-
-    $ tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | docker exec -i foo tar Cxf DEST_PATH -
-
+```bash
+$ tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | docker exec -i foo tar Cxf DEST_PATH -
+```
 
 Using `-` as the `SRC_PATH` streams the contents of `STDIN` as a tar archive.
 The command extracts the content of the tar to the `DEST_PATH` in container's
diff --git a/docs/reference/commandline/create.md b/docs/reference/commandline/create.md
index e6582e4..00de1dc 100644
--- a/docs/reference/commandline/create.md
+++ b/docs/reference/commandline/create.md
@@ -132,6 +132,7 @@
       --volumes-from value          Mount volumes from the specified container(s) (default [])
   -w, --workdir string              Working directory inside the container
 ```
+## Description
 
 The `docker create` command creates a writeable container layer over the
 specified image and prepares it for running the specified command.  The
@@ -147,42 +148,64 @@
 
 ## Examples
 
-    $ docker create -t -i fedora bash
-    6d8af538ec541dd581ebc2a24153a28329acb5268abe5ef868c1f1a261221752
-    $ docker start -a -i 6d8af538ec5
-    bash-4.2#
+### Create and start a container
+
+```bash
+$ docker create -t -i fedora bash
+
+6d8af538ec541dd581ebc2a24153a28329acb5268abe5ef868c1f1a261221752
+
+$ docker start -a -i 6d8af538ec5
+
+bash-4.2#
+```
+
+### Initialize volumes
 
 As of v1.4.0 container volumes are initialized during the `docker create` phase
 (i.e., `docker run` too). For example, this allows you to `create` the `data`
 volume container, and then use it from another container:
 
-    $ docker create -v /data --name data ubuntu
-    240633dfbb98128fa77473d3d9018f6123b99c454b3251427ae190a7d951ad57
-    $ docker run --rm --volumes-from data ubuntu ls -la /data
-    total 8
-    drwxr-xr-x  2 root root 4096 Dec  5 04:10 .
-    drwxr-xr-x 48 root root 4096 Dec  5 04:11 ..
+```bash
+$ docker create -v /data --name data ubuntu
+
+240633dfbb98128fa77473d3d9018f6123b99c454b3251427ae190a7d951ad57
+
+$ docker run --rm --volumes-from data ubuntu ls -la /data
+
+total 8
+drwxr-xr-x  2 root root 4096 Dec  5 04:10 .
+drwxr-xr-x 48 root root 4096 Dec  5 04:11 ..
+```
 
 Similarly, `create` a host directory bind mounted volume container, which can
 then be used from the subsequent container:
 
-    $ docker create -v /home/docker:/docker --name docker ubuntu
-    9aa88c08f319cd1e4515c3c46b0de7cc9aa75e878357b1e96f91e2c773029f03
-    $ docker run --rm --volumes-from docker ubuntu ls -la /docker
-    total 20
-    drwxr-sr-x  5 1000 staff  180 Dec  5 04:00 .
-    drwxr-xr-x 48 root root  4096 Dec  5 04:13 ..
-    -rw-rw-r--  1 1000 staff 3833 Dec  5 04:01 .ash_history
-    -rw-r--r--  1 1000 staff  446 Nov 28 11:51 .ashrc
-    -rw-r--r--  1 1000 staff   25 Dec  5 04:00 .gitconfig
-    drwxr-sr-x  3 1000 staff   60 Dec  1 03:28 .local
-    -rw-r--r--  1 1000 staff  920 Nov 28 11:51 .profile
-    drwx--S---  2 1000 staff  460 Dec  5 00:51 .ssh
-    drwxr-xr-x 32 1000 staff 1140 Dec  5 04:01 docker
+```bash
+$ docker create -v /home/docker:/docker --name docker ubuntu
+
+9aa88c08f319cd1e4515c3c46b0de7cc9aa75e878357b1e96f91e2c773029f03
+
+$ docker run --rm --volumes-from docker ubuntu ls -la /docker
+
+total 20
+drwxr-sr-x  5 1000 staff  180 Dec  5 04:00 .
+drwxr-xr-x 48 root root  4096 Dec  5 04:13 ..
+-rw-rw-r--  1 1000 staff 3833 Dec  5 04:01 .ash_history
+-rw-r--r--  1 1000 staff  446 Nov 28 11:51 .ashrc
+-rw-r--r--  1 1000 staff   25 Dec  5 04:00 .gitconfig
+drwxr-sr-x  3 1000 staff   60 Dec  1 03:28 .local
+-rw-r--r--  1 1000 staff  920 Nov 28 11:51 .profile
+drwx--S---  2 1000 staff  460 Dec  5 00:51 .ssh
+drwxr-xr-x 32 1000 staff 1140 Dec  5 04:01 docker
+```
+
 
 Set storage driver options per container.
 
-    $ docker create -it --storage-opt size=120G fedora /bin/bash
+```bash
+$ docker create -it --storage-opt size=120G fedora /bin/bash
+```
 
 This (size) will allow to set the container rootfs size to 120G at creation time.
 This option is only available for the `devicemapper`, `btrfs`, `overlay2`,
diff --git a/docs/reference/commandline/deploy.md b/docs/reference/commandline/deploy.md
index 53074b2..a430a90 100644
--- a/docs/reference/commandline/deploy.md
+++ b/docs/reference/commandline/deploy.md
@@ -14,7 +14,9 @@
      will be rejected.
 -->
 
-# deploy (alias for stack deploy) (experimental)
+# deploy (experimental)
+
+An alias for `stack deploy`.
 
 ```markdown
 Usage:  docker deploy [OPTIONS] STACK
@@ -31,15 +33,20 @@
       --with-registry-auth    Send registry authentication details to Swarm agents
 ```
 
+## Description
+
 Create and update a stack from a `compose` or a `dab` file on the swarm. This command
 has to be run targeting a manager node.
 
-## Compose file
+## Examples
+
+### Compose file
 
 The `deploy` command supports compose file version `3.0` and above.
 
 ```bash
 $ docker stack deploy --compose-file docker-compose.yml vossibility
+
 Ignoring unsupported options: links
 
 Creating network vossibility_vossibility
@@ -54,8 +61,9 @@
 
 You can verify that the services were correctly created
 
-```
+```bash
 $ docker service ls
+
 ID            NAME                               MODE        REPLICAS  IMAGE
 29bv0vnlm903  vossibility_lookupd                replicated  1/1       nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662
 4awt47624qwh  vossibility_nsqd                   replicated  1/1       nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662
@@ -65,10 +73,11 @@
 axqh55ipl40h  vossibility_vossibility-collector  replicated  1/1       icecrime/vossibility-collector@sha256:f03f2977203ba6253988c18d04061c5ec7aab46bca9dfd89a9a1fa4500989fba
 ```
 
-## DAB file
+### DAB file
 
 ```bash
 $ docker stack deploy --bundle-file vossibility-stack.dab vossibility
+
 Loading bundle from vossibility-stack.dab
 Creating service vossibility_elasticsearch
 Creating service vossibility_kibana
@@ -82,6 +91,7 @@
 
 ```bash
 $ docker service ls
+
 ID            NAME                               MODE        REPLICAS  IMAGE
 29bv0vnlm903  vossibility_lookupd                replicated  1/1       nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662
 4awt47624qwh  vossibility_nsqd                   replicated  1/1       nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662
@@ -91,7 +101,7 @@
 axqh55ipl40h  vossibility_vossibility-collector  replicated  1/1       icecrime/vossibility-collector@sha256:f03f2977203ba6253988c18d04061c5ec7aab46bca9dfd89a9a1fa4500989fba
 ```
 
-## Related information
+## Related commands
 
 * [stack config](stack_config.md)
 * [stack deploy](stack_deploy.md)
diff --git a/docs/reference/commandline/diff.md b/docs/reference/commandline/diff.md
index be27678..823831e 100644
--- a/docs/reference/commandline/diff.md
+++ b/docs/reference/commandline/diff.md
@@ -24,8 +24,10 @@
       --help   Print usage
 ```
 
-List the changed files and directories in a container᾿s filesystem.
- There are 3 events that are listed in the `diff`:
+## Description
+
+List the changed files and directories in a container᾿s filesystem since the
+container was created. Three different types of change are tracked:
 
 1. `A` - Add
 2. `D` - Delete
diff --git a/docs/reference/commandline/dockerd.md b/docs/reference/commandline/dockerd.md
index 24ac776..869e4ac 100644
--- a/docs/reference/commandline/dockerd.md
+++ b/docs/reference/commandline/dockerd.md
@@ -92,13 +92,17 @@
 
 Options with [] may be specified multiple times.
 
-dockerd is the persistent process that manages containers. Docker
+## Description
+
+`dockerd` is the persistent process that manages containers. Docker
 uses different binaries for the daemon and client. To run the daemon you
 type `dockerd`.
 
 To run the daemon with debug output, use `dockerd -D`.
 
-## Daemon socket option
+## Examples
+
+### Daemon socket option
 
 The Docker daemon can listen for [Docker Engine API](../api/)
 requests via three different types of Socket: `unix`, `tcp`, and `fd`.
@@ -117,8 +121,7 @@
 conventional to use port `2375` for un-encrypted, and port `2376` for encrypted
 communication with the daemon.
 
-> **Note:**
-> If you're using an HTTPS encrypted socket, keep in mind that only
+> **Note**: If you're using an HTTPS encrypted socket, keep in mind that only
 > TLS1.0 and greater are supported. Protocols SSLv3 and under are not
 > supported anymore for security reasons.
 
@@ -135,18 +138,21 @@
 
 ```bash
 # listen using the default unix socket, and on 2 specific IP addresses on this host.
+
 $ sudo dockerd -H unix:///var/run/docker.sock -H tcp://192.168.59.106 -H tcp://10.10.10.2
 ```
 
 The Docker client will honor the `DOCKER_HOST` environment variable to set the
-`-H` flag for the client.
+`-H` flag for the client. Use **one** of the following commands:
 
 ```bash
 $ docker -H tcp://0.0.0.0:2375 ps
-# or
+```
+
+```bash
 $ export DOCKER_HOST="tcp://0.0.0.0:2375"
+
 $ docker ps
-# both are equal
 ```
 
 Setting the `DOCKER_TLS_VERIFY` environment variable to any value other than
@@ -164,7 +170,7 @@
 environment variables (or the lowercase versions thereof). `HTTPS_PROXY` takes
 precedence over `HTTP_PROXY`.
 
-### Bind Docker to another host/port or a Unix socket
+#### Bind Docker to another host/port or a Unix socket
 
 > **Warning**:
 > Changing the default `docker` daemon binding to a
@@ -230,7 +236,7 @@
 $ docker -H tcp://127.0.0.1:2375 pull ubuntu
 ```
 
-### Daemon storage-driver option
+### Daemon storage-driver
 
 The Docker daemon has support for several different image layer storage
 drivers: `aufs`, `devicemapper`, `btrfs`, `zfs`, `overlay` and `overlay2`.
@@ -267,22 +273,20 @@
 `overlay` as efficient with memory as `aufs` driver. Call
 `dockerd -s overlay` to use it.
 
-> **Note:**
-> As promising as `overlay` is, the feature is still quite young and should not
-> be used in production. Most notably, using `overlay` can cause excessive
-> inode consumption (especially as the number of images grows), as well as
-> being incompatible with the use of RPMs.
+> **Note**: As promising as `overlay` is, the feature is still quite young and
+> should not be used in production. Most notably, using `overlay` can cause
+> excessive inode consumption (especially as the number of images grows), as
+> well as > being incompatible with the use of RPMs.
 
 The `overlay2` uses the same fast union filesystem but takes advantage of
 [additional features](https://lkml.org/lkml/2015/2/11/106) added in Linux
 kernel 4.0 to avoid excessive inode consumption. Call `dockerd -s overlay2`
 to use it.
 
-> **Note:**
-> Both `overlay` and `overlay2` are currently unsupported on `btrfs` or any
-> Copy on Write filesystem and should only be used over `ext4` partitions.
+> **Note**: Both `overlay` and `overlay2` are currently unsupported on `btrfs`
+> or any Copy on Write filesystem and should only be used over `ext4` partitions.
 
-### Storage driver options
+### Options per storage driver
 
 Particular storage-driver can be configured with options specified with
 `--storage-opt` flags. Options for `devicemapper` are prefixed with `dm`,
@@ -290,380 +294,376 @@
 
 #### Devicemapper options
 
-*   `dm.thinpooldev`
+##### `dm.thinpooldev`
 
-    Specifies a custom block storage device to use for the thin pool.
+Specifies a custom block storage device to use for the thin pool.
 
-    If using a block device for device mapper storage, it is best to use `lvm`
-    to create and manage the thin-pool volume. This volume is then handed to Docker
-    to exclusively create snapshot volumes needed for images and containers.
+If using a block device for device mapper storage, it is best to use `lvm`
+to create and manage the thin-pool volume. This volume is then handed to Docker
+to exclusively create snapshot volumes needed for images and containers.
 
-    Managing the thin-pool outside of Engine makes for the most feature-rich
-    method of having Docker utilize device mapper thin provisioning as the
-    backing storage for Docker containers. The highlights of the lvm-based
-    thin-pool management feature include: automatic or interactive thin-pool
-    resize support, dynamically changing thin-pool features, automatic thinp
-    metadata checking when lvm activates the thin-pool, etc.
+Managing the thin-pool outside of Engine makes for the most feature-rich
+method of having Docker utilize device mapper thin provisioning as the
+backing storage for Docker containers. The highlights of the lvm-based
+thin-pool management feature include: automatic or interactive thin-pool
+resize support, dynamically changing thin-pool features, automatic thinp
+metadata checking when lvm activates the thin-pool, etc.
 
-    As a fallback if no thin pool is provided, loopback files are
-    created. Loopback is very slow, but can be used without any
-    pre-configuration of storage. It is strongly recommended that you do
-    not use loopback in production. Ensure your Engine daemon has a
-    `--storage-opt dm.thinpooldev` argument provided.
+As a fallback if no thin pool is provided, loopback files are
+created. Loopback is very slow, but can be used without any
+pre-configuration of storage. It is strongly recommended that you do
+not use loopback in production. Ensure your Engine daemon has a
+`--storage-opt dm.thinpooldev` argument provided.
 
-    Example use:
+###### Example:
 
-    ```bash
-    $ sudo dockerd --storage-opt dm.thinpooldev=/dev/mapper/thin-pool
-    ```
+```bash
+$ sudo dockerd --storage-opt dm.thinpooldev=/dev/mapper/thin-pool
+```
 
-*   `dm.basesize`
+##### `dm.basesize`
 
-    Specifies the size to use when creating the base device, which limits the
-    size of images and containers. The default value is 10G. Note, thin devices
-    are inherently "sparse", so a 10G device which is mostly empty doesn't use
-    10 GB of space on the pool. However, the filesystem will use more space for
-    the empty case the larger the device is.
+Specifies the size to use when creating the base device, which limits the
+size of images and containers. The default value is 10G. Note, thin devices
+are inherently "sparse", so a 10G device which is mostly empty doesn't use
+10 GB of space on the pool. However, the filesystem will use more space for
+the empty case the larger the device is.
 
-    The base device size can be increased at daemon restart which will allow
-    all future images and containers (based on those new images) to be of the
-    new base device size.
+The base device size can be increased at daemon restart which will allow
+all future images and containers (based on those new images) to be of the
+new base device size.
 
-    Example use:
+###### Examples
 
-    ```bash
-    $ sudo dockerd --storage-opt dm.basesize=50G
-    ```
+```bash
+$ sudo dockerd --storage-opt dm.basesize=50G
+```
 
-    This will increase the base device size to 50G. The Docker daemon will throw an
-    error if existing base device size is larger than 50G. A user can use
-    this option to expand the base device size however shrinking is not permitted.
+This will increase the base device size to 50G. The Docker daemon will throw an
+error if existing base device size is larger than 50G. A user can use
+this option to expand the base device size however shrinking is not permitted.
 
-    This value affects the system-wide "base" empty filesystem
-    that may already be initialized and inherited by pulled images. Typically,
-    a change to this value requires additional steps to take effect:
+This value affects the system-wide "base" empty filesystem
+that may already be initialized and inherited by pulled images. Typically,
+a change to this value requires additional steps to take effect:
 
-     ```bash
-    $ sudo service docker stop
-    $ sudo rm -rf /var/lib/docker
-    $ sudo service docker start
-    ```
+ ```bash
+$ sudo service docker stop
 
-    Example use:
+$ sudo rm -rf /var/lib/docker
 
-    ```bash
-    $ sudo dockerd --storage-opt dm.basesize=20G
-    ```
+$ sudo service docker start
+```
 
-*   `dm.loopdatasize`
 
-    > **Note**:
-    > This option configures devicemapper loopback, which should not
-    > be used in production.
+##### `dm.loopdatasize`
 
-    Specifies the size to use when creating the loopback file for the
-    "data" device which is used for the thin pool. The default size is
-    100G. The file is sparse, so it will not initially take up this
-    much space.
+> **Note**: This option configures devicemapper loopback, which should not
+> be used in production.
 
-    Example use:
+Specifies the size to use when creating the loopback file for the
+"data" device which is used for the thin pool. The default size is
+100G. The file is sparse, so it will not initially take up this
+much space.
 
-    ```bash
-    $ sudo dockerd --storage-opt dm.loopdatasize=200G
-    ```
+###### Example
 
-*   `dm.loopmetadatasize`
+```bash
+$ sudo dockerd --storage-opt dm.loopdatasize=200G
+```
 
-    > **Note**:
-    > This option configures devicemapper loopback, which should not
-    > be used in production.
+##### `dm.loopmetadatasize`
 
-    Specifies the size to use when creating the loopback file for the
-    "metadata" device which is used for the thin pool. The default size
-    is 2G. The file is sparse, so it will not initially take up
-    this much space.
+> **Note**: This option configures devicemapper loopback, which should not
+> be used in production.
 
-    Example use:
+Specifies the size to use when creating the loopback file for the
+"metadata" device which is used for the thin pool. The default size
+is 2G. The file is sparse, so it will not initially take up
+this much space.
 
-    ```bash
-    $ sudo dockerd --storage-opt dm.loopmetadatasize=4G
-    ```
+###### Example
 
-*   `dm.fs`
+```bash
+$ sudo dockerd --storage-opt dm.loopmetadatasize=4G
+```
 
-    Specifies the filesystem type to use for the base device. The supported
-    options are "ext4" and "xfs". The default is "xfs"
+##### `dm.fs`
 
-    Example use:
+Specifies the filesystem type to use for the base device. The supported
+options are "ext4" and "xfs". The default is "xfs"
 
-    ```bash
-    $ sudo dockerd --storage-opt dm.fs=ext4
-    ```
+###### Example
 
-*   `dm.mkfsarg`
+```bash
+$ sudo dockerd --storage-opt dm.fs=ext4
+```
 
-    Specifies extra mkfs arguments to be used when creating the base device.
+##### `dm.mkfsarg`
 
-    Example use:
+Specifies extra mkfs arguments to be used when creating the base device.
 
-    ```bash
-    $ sudo dockerd --storage-opt "dm.mkfsarg=-O ^has_journal"
-    ```
+###### Example
 
-*   `dm.mountopt`
+```bash
+$ sudo dockerd --storage-opt "dm.mkfsarg=-O ^has_journal"
+```
 
-    Specifies extra mount options used when mounting the thin devices.
+##### `dm.mountopt`
 
-    Example use:
+Specifies extra mount options used when mounting the thin devices.
 
-    ```bash
-    $ sudo dockerd --storage-opt dm.mountopt=nodiscard
-    ```
+###### Example
 
-*   `dm.datadev`
+```bash
+$ sudo dockerd --storage-opt dm.mountopt=nodiscard
+```
 
-    (Deprecated, use `dm.thinpooldev`)
+##### `dm.datadev`
 
-    Specifies a custom blockdevice to use for data for the thin pool.
+(Deprecated, use `dm.thinpooldev`)
 
-    If using a block device for device mapper storage, ideally both datadev and
-    metadatadev should be specified to completely avoid using the loopback
-    device.
+Specifies a custom blockdevice to use for data for the thin pool.
 
-    Example use:
+If using a block device for device mapper storage, ideally both `datadev` and
+`metadatadev` should be specified to completely avoid using the loopback
+device.
 
-    ```bash
-    $ sudo dockerd \
-          --storage-opt dm.datadev=/dev/sdb1 \
-          --storage-opt dm.metadatadev=/dev/sdc1
-    ```
+###### Example
 
-*   `dm.metadatadev`
+```bash
+$ sudo dockerd \
+      --storage-opt dm.datadev=/dev/sdb1 \
+      --storage-opt dm.metadatadev=/dev/sdc1
+```
 
-    (Deprecated, use `dm.thinpooldev`)
+##### `dm.metadatadev`
 
-    Specifies a custom blockdevice to use for metadata for the thin pool.
+(Deprecated, use `dm.thinpooldev`)
 
-    For best performance the metadata should be on a different spindle than the
-    data, or even better on an SSD.
+Specifies a custom blockdevice to use for metadata for the thin pool.
 
-    If setting up a new metadata pool it is required to be valid. This can be
-    achieved by zeroing the first 4k to indicate empty metadata, like this:
+For best performance the metadata should be on a different spindle than the
+data, or even better on an SSD.
 
-    ```bash
-    $ dd if=/dev/zero of=$metadata_dev bs=4096 count=1
-    ```
+If setting up a new metadata pool it is required to be valid. This can be
+achieved by zeroing the first 4k to indicate empty metadata, like this:
 
-    Example use:
+```bash
+$ dd if=/dev/zero of=$metadata_dev bs=4096 count=1
+```
 
-    ```bash
-    $ sudo dockerd \
-          --storage-opt dm.datadev=/dev/sdb1 \
-          --storage-opt dm.metadatadev=/dev/sdc1
-    ```
+###### Example
 
-*   `dm.blocksize`
+```bash
+$ sudo dockerd \
+      --storage-opt dm.datadev=/dev/sdb1 \
+      --storage-opt dm.metadatadev=/dev/sdc1
+```
+
+##### `dm.blocksize`
 
-    Specifies a custom blocksize to use for the thin pool. The default
-    blocksize is 64K.
+Specifies a custom blocksize to use for the thin pool. The default
+blocksize is 64K.
 
-    Example use:
+###### Example
 
-    ```bash
-    $ sudo dockerd --storage-opt dm.blocksize=512K
-    ```
+```bash
+$ sudo dockerd --storage-opt dm.blocksize=512K
+```
 
-*   `dm.blkdiscard`
+##### `dm.blkdiscard`
 
-    Enables or disables the use of blkdiscard when removing devicemapper
-    devices. This is enabled by default (only) if using loopback devices and is
-    required to resparsify the loopback file on image/container removal.
+Enables or disables the use of `blkdiscard` when removing devicemapper
+devices. This is enabled by default (only) if using loopback devices and is
+required to resparsify the loopback file on image/container removal.
 
-    Disabling this on loopback can lead to *much* faster container removal
-    times, but will make the space used in `/var/lib/docker` directory not be
-    returned to the system for other use when containers are removed.
+Disabling this on loopback can lead to *much* faster container removal
+times, but will make the space used in `/var/lib/docker` directory not be
+returned to the system for other use when containers are removed.
 
-    Example use:
+###### Examples
 
-    ```bash
-    $ sudo dockerd --storage-opt dm.blkdiscard=false
-    ```
+```bash
+$ sudo dockerd --storage-opt dm.blkdiscard=false
+```
 
-*   `dm.override_udev_sync_check`
+##### `dm.override_udev_sync_check`
 
-    Overrides the `udev` synchronization checks between `devicemapper` and `udev`.
-    `udev` is the device manager for the Linux kernel.
+Overrides the `udev` synchronization checks between `devicemapper` and `udev`.
+`udev` is the device manager for the Linux kernel.
 
-    To view the `udev` sync support of a Docker daemon that is using the
-    `devicemapper` driver, run:
+To view the `udev` sync support of a Docker daemon that is using the
+`devicemapper` driver, run:
 
-    ```bash
-    $ docker info
-    [...]
-    Udev Sync Supported: true
-    [...]
-    ```
+```bash
+$ docker info
+[...]
+Udev Sync Supported: true
+[...]
+```
 
-    When `udev` sync support is `true`, then `devicemapper` and udev can
-    coordinate the activation and deactivation of devices for containers.
+When `udev` sync support is `true`, then `devicemapper` and udev can
+coordinate the activation and deactivation of devices for containers.
 
-    When `udev` sync support is `false`, a race condition occurs between
-    the`devicemapper` and `udev` during create and cleanup. The race condition
-    results in errors and failures. (For information on these failures, see
-    [docker#4036](https://github.com/docker/docker/issues/4036))
+When `udev` sync support is `false`, a race condition occurs between
+the`devicemapper` and `udev` during create and cleanup. The race condition
+results in errors and failures. (For information on these failures, see
+[docker#4036](https://github.com/docker/docker/issues/4036))
 
-    To allow the `docker` daemon to start, regardless of `udev` sync not being
-    supported, set `dm.override_udev_sync_check` to true:
+To allow the `docker` daemon to start, regardless of `udev` sync not being
+supported, set `dm.override_udev_sync_check` to true:
 
-    ```bash
-    $ sudo dockerd --storage-opt dm.override_udev_sync_check=true
-    ```
+```bash
+$ sudo dockerd --storage-opt dm.override_udev_sync_check=true
+```
 
-    When this value is `true`, the  `devicemapper` continues and simply warns
-    you the errors are happening.
+When this value is `true`, the  `devicemapper` continues and simply warns
+you the errors are happening.
 
-    > **Note:**
-    > The ideal is to pursue a `docker` daemon and environment that does
-    > support synchronizing with `udev`. For further discussion on this
-    > topic, see [docker#4036](https://github.com/docker/docker/issues/4036).
-    > Otherwise, set this flag for migrating existing Docker daemons to
-    > a daemon with a supported environment.
+> **Note**: The ideal is to pursue a `docker` daemon and environment that does
+> support synchronizing with `udev`. For further discussion on this
+> topic, see [docker#4036](https://github.com/docker/docker/issues/4036).
+> Otherwise, set this flag for migrating existing Docker daemons to
+> a daemon with a supported environment.
 
-*   `dm.use_deferred_removal`
+##### `dm.use_deferred_removal`
 
-    Enables use of deferred device removal if `libdm` and the kernel driver
-    support the mechanism.
+Enables use of deferred device removal if `libdm` and the kernel driver
+support the mechanism.
 
-    Deferred device removal means that if device is busy when devices are
-    being removed/deactivated, then a deferred removal is scheduled on
-    device. And devices automatically go away when last user of the device
-    exits.
+Deferred device removal means that if device is busy when devices are
+being removed/deactivated, then a deferred removal is scheduled on
+device. And devices automatically go away when last user of the device
+exits.
 
-    For example, when a container exits, its associated thin device is removed.
-    If that device has leaked into some other mount namespace and can't be
-    removed, the container exit still succeeds and this option causes the
-    system to schedule the device for deferred removal. It does not wait in a
-    loop trying to remove a busy device.
+For example, when a container exits, its associated thin device is removed.
+If that device has leaked into some other mount namespace and can't be
+removed, the container exit still succeeds and this option causes the
+system to schedule the device for deferred removal. It does not wait in a
+loop trying to remove a busy device.
 
-    Example use:
+###### Example
 
-    ```bash
-    $ sudo dockerd --storage-opt dm.use_deferred_removal=true
-    ```
+```bash
+$ sudo dockerd --storage-opt dm.use_deferred_removal=true
+```
 
-*   `dm.use_deferred_deletion`
+##### `dm.use_deferred_deletion`
 
-    Enables use of deferred device deletion for thin pool devices. By default,
-    thin pool device deletion is synchronous. Before a container is deleted,
-    the Docker daemon removes any associated devices. If the storage driver
-    can not remove a device, the container deletion fails and daemon returns.
+Enables use of deferred device deletion for thin pool devices. By default,
+thin pool device deletion is synchronous. Before a container is deleted,
+the Docker daemon removes any associated devices. If the storage driver
+can not remove a device, the container deletion fails and daemon returns.
 
-        Error deleting container: Error response from daemon: Cannot destroy container
+```none
+Error deleting container: Error response from daemon: Cannot destroy container
+```
 
-    To avoid this failure, enable both deferred device deletion and deferred
-    device removal on the daemon.
+To avoid this failure, enable both deferred device deletion and deferred
+device removal on the daemon.
 
-    ```bash
-    $ sudo dockerd \
-          --storage-opt dm.use_deferred_deletion=true \
-          --storage-opt dm.use_deferred_removal=true
-    ```
+```bash
+$ sudo dockerd \
+      --storage-opt dm.use_deferred_deletion=true \
+      --storage-opt dm.use_deferred_removal=true
+```
 
-    With these two options enabled, if a device is busy when the driver is
-    deleting a container, the driver marks the device as deleted. Later, when
-    the device isn't in use, the driver deletes it.
+With these two options enabled, if a device is busy when the driver is
+deleting a container, the driver marks the device as deleted. Later, when
+the device isn't in use, the driver deletes it.
 
-    In general it should be safe to enable this option by default. It will help
-    when unintentional leaking of mount point happens across multiple mount
-    namespaces.
+In general it should be safe to enable this option by default. It will help
+when unintentional leaking of mount point happens across multiple mount
+namespaces.
 
-*   `dm.min_free_space`
+##### `dm.min_free_space`
 
-    Specifies the min free space percent in a thin pool require for new device
-    creation to succeed. This check applies to both free data space as well
-    as free metadata space. Valid values are from 0% - 99%. Value 0% disables
-    free space checking logic. If user does not specify a value for this option,
-    the Engine uses a default value of 10%.
+Specifies the min free space percent in a thin pool require for new device
+creation to succeed. This check applies to both free data space as well
+as free metadata space. Valid values are from 0% - 99%. Value 0% disables
+free space checking logic. If user does not specify a value for this option,
+the Engine uses a default value of 10%.
 
-    Whenever a new a thin pool device is created (during `docker pull` or during
-    container creation), the Engine checks if the minimum free space is
-    available. If sufficient space is unavailable, then device creation fails
-    and any relevant `docker` operation fails.
+Whenever a new a thin pool device is created (during `docker pull` or during
+container creation), the Engine checks if the minimum free space is
+available. If sufficient space is unavailable, then device creation fails
+and any relevant `docker` operation fails.
 
-    To recover from this error, you must create more free space in the thin pool
-    to recover from the error. You can create free space by deleting some images
-    and containers from the thin pool. You can also add more storage to the thin
-    pool.
+To recover from this error, you must create more free space in the thin pool
+to recover from the error. You can create free space by deleting some images
+and containers from the thin pool. You can also add more storage to the thin
+pool.
 
-    To add more space to a LVM (logical volume management) thin pool, just add
-    more storage to the volume group container thin pool; this should automatically
-    resolve any errors. If your configuration uses loop devices, then stop the
-    Engine daemon, grow the size of loop files and restart the daemon to resolve
-    the issue.
+To add more space to a LVM (logical volume management) thin pool, just add
+more storage to the volume group container thin pool; this should automatically
+resolve any errors. If your configuration uses loop devices, then stop the
+Engine daemon, grow the size of loop files and restart the daemon to resolve
+the issue.
 
-    Example use:
+###### Example
 
-    ```bash
-    $ sudo dockerd --storage-opt dm.min_free_space=10%
-    ```
+```bash
+$ sudo dockerd --storage-opt dm.min_free_space=10%
+```
 
-*  `dm.xfs_nospace_max_retries`
+##### `dm.xfs_nospace_max_retries`
 
-    Specifies the maximum number of retries XFS should attempt to complete
-    IO when ENOSPC (no space) error is returned by underlying storage device.
+Specifies the maximum number of retries XFS should attempt to complete
+IO when ENOSPC (no space) error is returned by underlying storage device.
 
-    By default XFS retries infinitely for IO to finish and this can result
-    in unkillable process. To change this behavior one can set
-    xfs_nospace_max_retries to say 0 and XFS will not retry IO after getting
-    ENOSPC and will shutdown filesystem.
+By default XFS retries infinitely for IO to finish and this can result
+in unkillable process. To change this behavior one can set
+xfs_nospace_max_retries to say 0 and XFS will not retry IO after getting
+ENOSPC and will shutdown filesystem.
 
-    Example use:
+###### Example
 
-    ```bash
-    $ sudo dockerd --storage-opt dm.xfs_nospace_max_retries=0
-    ```
+```bash
+$ sudo dockerd --storage-opt dm.xfs_nospace_max_retries=0
+```
 
 #### ZFS options
 
-*   `zfs.fsname`
+##### `zfs.fsname`
 
-    Set zfs filesystem under which docker will create its own datasets.
-    By default docker will pick up the zfs filesystem where docker graph
-    (`/var/lib/docker`) is located.
+Set zfs filesystem under which docker will create its own datasets.
+By default docker will pick up the zfs filesystem where docker graph
+(`/var/lib/docker`) is located.
 
-    Example use:
+###### Example
 
-    ```bash
-    $ sudo dockerd -s zfs --storage-opt zfs.fsname=zroot/docker
-    ```
+```bash
+$ sudo dockerd -s zfs --storage-opt zfs.fsname=zroot/docker
+```
 
 #### Btrfs options
 
-*   `btrfs.min_space`
+##### `btrfs.min_space`
 
-    Specifies the minimum size to use when creating the subvolume which is used
-    for containers. If user uses disk quota for btrfs when creating or running
-    a container with **--storage-opt size** option, docker should ensure the
-    **size** cannot be smaller than **btrfs.min_space**.
+Specifies the minimum size to use when creating the subvolume which is used
+for containers. If user uses disk quota for btrfs when creating or running
+a container with **--storage-opt size** option, docker should ensure the
+**size** cannot be smaller than **btrfs.min_space**.
 
-    Example use:
+###### Example
 
-    ```bash
-    $ sudo dockerd -s btrfs --storage-opt btrfs.min_space=10G
-    ```
+```bash
+$ sudo dockerd -s btrfs --storage-opt btrfs.min_space=10G
+```
 
 #### Overlay2 options
 
-*   `overlay2.override_kernel_check`
+##### `overlay2.override_kernel_check`
 
-    Overrides the Linux kernel version check allowing overlay2. Support for
-    specifying multiple lower directories needed by overlay2 was added to the
-    Linux kernel in 4.0.0. However some older kernel versions may be patched
-    to add multiple lower directory support for OverlayFS. This option should
-    only be used after verifying this support exists in the kernel. Applying
-    this option on a kernel without this support will cause failures on mount.
+Overrides the Linux kernel version check allowing overlay2. Support for
+specifying multiple lower directories needed by overlay2 was added to the
+Linux kernel in 4.0.0. However, some older kernel versions may be patched
+to add multiple lower directory support for OverlayFS. This option should
+only be used after verifying this support exists in the kernel. Applying
+this option on a kernel without this support will cause failures on mount.
 
-## Docker runtime execution options
+### Docker runtime execution options
 
 The Docker daemon relies on a
 [OCI](https://github.com/opencontainers/runtime-spec) compliant runtime
@@ -706,9 +706,9 @@
 $ sudo dockerd --add-runtime runc=runc --add-runtime custom=/usr/local/bin/my-runc-replacement
 ```
 
-> **Note**: defining runtime arguments via the command line is not supported.
+> **Note**: Defining runtime arguments via the command line is not supported.
 
-## Options for the runtime
+#### Options for the runtime
 
 You can configure the runtime using options specified
 with the `--exec-opt` flag. All the flag's options have the `native` prefix. A
@@ -738,7 +738,7 @@
 value is specified on daemon start, on Windows client, the default is
 `hyperv`, and on Windows server, the default is `process`.
 
-## Daemon DNS options
+#### Daemon DNS options
 
 To set the DNS server for all Docker containers, use:
 
@@ -753,8 +753,7 @@
 $ sudo dockerd --dns-search example.com
 ```
 
-
-## Insecure registries
+#### Insecure registries
 
 Docker considers a private registry either secure or insecure. In the rest of
 this section, *registry* is used for *private registry*, and `myregistry:5000`
@@ -798,11 +797,11 @@
 testing purposes.  For increased security, users should add their CA to their
 system's list of trusted CAs instead of enabling `--insecure-registry`.
 
-## Legacy Registries
+##### Legacy Registries
 
 Enabling `--disable-legacy-registry` forces a docker daemon to only interact with registries which support the V2 protocol.  Specifically, the daemon will not attempt `push`, `pull` and `login` to v1 registries.  The exception to this is `search` which can still be performed on v1 registries.
 
-## Running a Docker daemon behind an HTTPS_PROXY
+#### Running a Docker daemon behind an HTTPS_PROXY
 
 When running inside a LAN that uses an `HTTPS` proxy, the Docker Hub
 certificates will be replaced by the proxy's certificates. These certificates
@@ -819,7 +818,7 @@
 your `docker build`s and running containers will need extra configuration to
 use the proxy
 
-## Default Ulimits
+#### Default `ulimit` settings
 
 `--default-ulimit` allows you to set the default `ulimit` options to use for
 all containers. It takes the same options as `--ulimit` for `docker run`. If
@@ -831,7 +830,7 @@
 set the maximum number of processes available to a user, not to a container. For details
 please check the [run](run.md) reference.
 
-## Nodes discovery
+#### Node discovery
 
 The `--cluster-advertise` option specifies the `host:port` or `interface:port`
 combination that this particular daemon instance should use when advertising
@@ -857,39 +856,16 @@
 
 The currently supported cluster store options are:
 
-*   `discovery.heartbeat`
+| Option                | Description |
+|-----------------------|-------------|
+| `discovery.heartbeat` | Specifies the heartbeat timer in seconds which is used by the daemon as a `keepalive` mechanism to make sure discovery module treats the node as alive in the cluster. If not configured, the default value is 20 seconds. |
+| `discovery.ttl`       | Specifies the TTL (time-to-live) in seconds which is used by the discovery module to timeout a node if a valid heartbeat is not received within the configured ttl value. If not configured, the default value is 60 seconds. |
+| `kv.cacertfile`       | Specifies the path to a local file with PEM encoded CA certificates to trust. |
+| `kv.certfile`         | Specifies the path to a local file with a PEM encoded certificate. This certificate is used as the client cert for communication with the Key/Value store. |
+| `kv.keyfile`          | Specifies the path to a local file with a PEM encoded private key. This private key is used as the client key for communication with the Key/Value store. |
+| `kv.path`             | Specifies the path in the Key/Value store. If not configured, the default value is 'docker/nodes'. |
 
-    Specifies the heartbeat timer in seconds which is used by the daemon as a
-    keepalive mechanism to make sure discovery module treats the node as alive
-    in the cluster. If not configured, the default value is 20 seconds.
-
-*   `discovery.ttl`
-
-    Specifies the ttl (time-to-live) in seconds which is used by the discovery
-    module to timeout a node if a valid heartbeat is not received within the
-    configured ttl value. If not configured, the default value is 60 seconds.
-
-*   `kv.cacertfile`
-
-    Specifies the path to a local file with PEM encoded CA certificates to trust
-
-*   `kv.certfile`
-
-    Specifies the path to a local file with a PEM encoded certificate.  This
-    certificate is used as the client cert for communication with the
-    Key/Value store.
-
-*   `kv.keyfile`
-
-    Specifies the path to a local file with a PEM encoded private key.  This
-    private key is used as the client key for communication with the
-    Key/Value store.
-
-*   `kv.path`
-
-    Specifies the path in the Key/Value store. If not configured, the default value is 'docker/nodes'.
-
-## Access authorization
+#### Access authorization
 
 Docker's access authorization can be extended by authorization plugins that your
 organization can purchase or build themselves. You can install one or more
@@ -914,7 +890,7 @@
 plugin](../../extend/plugins_authorization.md) section in the Docker extend section of this documentation.
 
 
-## Daemon user namespace options
+#### Daemon user namespace options
 
 The Linux kernel [user namespace support](http://man7.org/linux/man-pages/man7/user_namespaces.7.html) provides additional security by enabling
 a process, and therefore a container, to have a unique range of user and
@@ -947,7 +923,7 @@
 > pull`, `docker push`, and container startup as users expect with
 > user namespaces disabled.
 
-### Starting the daemon with user namespaces enabled
+##### Start the daemon with user namespaces enabled
 
 To enable user namespace support, start the daemon with the
 `--userns-remap` flag, which accepts values in the following formats:
@@ -994,7 +970,20 @@
 namespaces, the Security Options entry in the response will list "userns" as
 one of the enabled security features.
 
-### Detailed information on `subuid`/`subgid` ranges
+##### Behavior differences when user namespaces are enabled
+
+When you start the Docker daemon with `--userns-remap`, Docker segregates the graph directory
+where the images are stored by adding an extra directory with a name corresponding to the
+remapped UID and GID. For example, if the remapped UID and GID begin with `165536`, all
+images and containers running with that remap setting are located in `/var/lib/docker/165536.165536`
+instead of `/var/lib/docker/`.
+
+In addition, the files and directories within the new directory, which correspond to
+images and container layers, are also owned by the new UID and GID. To set the ownership
+correctly, you need to re-pull the images and restart the containers after starting the
+daemon with `--userns-remap`.
+
+##### Detailed information on `subuid`/`subgid` ranges
 
 Given potential advanced use of the subordinate ID ranges by power users, the
 following paragraphs define how the Docker daemon currently uses the range entries
@@ -1017,7 +1006,7 @@
 2. Map segments will be created from each range in increasing value with a length matching the length of each segment. Therefore the range segment with the lowest numeric starting value will be equal to the remapped root, and continue up through host uid/gid equal to the range segment length. As an example, if the lowest segment starts at ID 1000 and has a length of 100, then a map of 1000 -> 0 (the remapped root) up through 1100 -> 100 will be created from this segment. If the next segment starts at ID 10000, then the next map will start with mapping 10000 -> 101 up to the length of this second segment. This will continue until no more segments are found in the subordinate files for this user.
 3. If more than five range segments exist for a single user, only the first five will be utilized, matching the kernel's limitation of only five entries in `/proc/self/uid_map` and `proc/self/gid_map`.
 
-### Disable user namespace for a container
+##### Disable user namespace for a container
 
 If you enable user namespaces on the daemon, all containers are started
 with user namespaces enabled. In some situations you might want to disable
@@ -1027,7 +1016,7 @@
 in the `run/exec/create` command.
 This option will completely disable user namespace mapping for the container's user.
 
-### User namespace known restrictions
+##### User namespace known restrictions
 
 The following standard Docker features are currently incompatible when
 running a Docker daemon with user namespaces enabled:
@@ -1050,7 +1039,7 @@
 inability to use `mknod`. Permission will be denied for device creation even as
 container `root` inside a user namespace.
 
-## Miscellaneous options
+### Miscellaneous options
 
 IP masquerading uses address translation to allow containers without a public
 IP to talk to other machines on the Internet. This may interfere with some
@@ -1065,7 +1054,7 @@
     export DOCKER_TMPDIR=/mnt/disk2/tmp
     /usr/local/bin/dockerd -D -g /var/lib/docker -H unix:// > /var/lib/docker-machine/docker.log 2>&1
 
-## Default cgroup parent
+#### Default cgroup parent
 
 The `--cgroup-parent` option allows you to set the default cgroup parent
 to use for containers. If this option is not set, it defaults to `/docker` for
@@ -1092,7 +1081,7 @@
 option on `docker create` and `docker run`, and takes precedence over
 the `--cgroup-parent` option on the daemon.
 
-## Daemon Metrics
+#### Daemon metrics
 
 The `--metrics-addr` option takes a tcp address to serve the metrics API.
 This feature is still experimental, therefore, the daemon must be running in experimental
@@ -1106,7 +1095,7 @@
 to have prometheus collect metrics on Docker.  For more information
 on prometheus you can view the website [here](https://prometheus.io/).
 
-```yml
+```none
 scrape_configs:
   - job_name: 'docker'
     static_configs:
@@ -1117,7 +1106,7 @@
 names could change while this feature is still in experimental.  Please provide
 feedback on what you would like to see collected in the API.
 
-## Daemon configuration file
+#### Daemon configuration file
 
 The `--config-file` option allows you to set any configuration option
 for the daemon in a JSON format. This file uses the same flag names as keys,
@@ -1132,7 +1121,7 @@
 in the configuration file and also set daemon labels via the `--label` flag.
 Options that are not present in the file are ignored when the daemon starts.
 
-### Linux configuration file
+##### On Linux
 
 The default location of the configuration file on Linux is
 `/etc/docker/daemon.json`. The `--config-file` flag can be used to specify a
@@ -1216,7 +1205,7 @@
 }
 ```
 
-### Windows configuration file
+##### On Windows
 
 The default location of the configuration file on Windows is
  `%programdata%\docker\config\daemon.json`. The `--config-file` flag can be
@@ -1263,7 +1252,7 @@
 }
 ```
 
-### Configuration reloading
+#### Configuration reload behavior
 
 Some options can be reconfigured when the daemon is running without requiring
 to restart the process. We use the `SIGHUP` signal in Linux to reload, and a global event
@@ -1299,7 +1288,7 @@
 previously configured cluster configurations.
 
 
-## Running multiple daemons
+### Run multiple daemons
 
 > **Note:** Running multiple daemons on a single host is considered as "experimental". The user should be aware of
 > unsolved problems. This solution may not work properly in some cases. Solutions are currently under development
@@ -1312,7 +1301,7 @@
 
 The following daemon options must be configured for each daemon:
 
-```bash
+```none
 -b, --bridge=                          Attach containers to a network bridge
 --exec-root=/var/run/docker            Root of the Docker execdriver
 -g, --graph=/var/lib/docker            Root of the Docker runtime
diff --git a/docs/reference/commandline/events.md b/docs/reference/commandline/events.md
index 71f07fc..9bf0513 100644
--- a/docs/reference/commandline/events.md
+++ b/docs/reference/commandline/events.md
@@ -28,29 +28,90 @@
       --until string   Stream events until this timestamp
 ```
 
+## Description
+
+Use `docker events` to get real-time events from the server. These events differ
+per Docker object type.
+
+### Object types
+
+#### Containers
+
 Docker containers report the following events:
 
-    attach, commit, copy, create, destroy, detach, die, exec_create, exec_detach, exec_start, export, health_status, kill, oom, pause, rename, resize, restart, start, stop, top, unpause, update
+- `attach`
+- `commit`
+- `copy`
+- `create`
+- `destroy`
+- `detach`
+- `die`
+- `exec_create`
+- `exec_detach`
+- `exec_start`
+- `export`
+- `health_status`
+- `kill`
+- `oom`
+- `pause`
+- `rename`
+- `resize`
+- `restart`
+- `start`
+- `stop`
+- `top`
+- `unpause`
+- `update`
+
+#### Images
 
 Docker images report the following events:
 
-    delete, import, load, pull, push, save, tag, untag
+- `delete`
+- `import`
+- `load`
+- `pull`
+- `push`
+- `save`
+- `tag`
+- `untag`
+
+#### Plugins
 
 Docker plugins report the following events:
 
-    install, enable, disable, remove
+- `install`
+- `enable`
+- `disable`
+- `remove`
+
+#### Volumes
 
 Docker volumes report the following events:
 
-    create, mount, unmount, destroy
+- `create`
+- `mount`
+- `unmount`
+- `destroy`
+
+#### Networks
 
 Docker networks report the following events:
 
-    create, connect, disconnect, destroy
+- `create`
+- `connect`
+- `disconnect`
+- `destroy`
 
-Docker daemon reports the following events:
+#### Daemons
 
-    reload
+Docker daemons report the following events:
+
+- `reload`
+
+### Limiting, filtering, and formatting the output
+
+#### Limit events by time
 
 The `--since` and `--until` parameters can be Unix timestamps, date formatted
 timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed
@@ -65,7 +126,7 @@
 seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a
 fraction of a second no more than nine digits long.
 
-## Filtering
+#### Filtering
 
 The filtering flag (`-f` or `--filter`) format is of "key=value". If you would
 like to use multiple filters, pass multiple flags (e.g.,
@@ -91,7 +152,7 @@
 * type (`type=<container or image or volume or network or daemon>`)
 * volume (`volume=<name or id>`)
 
-## Format
+#### Format
 
 If a format (`--format`) is specified, the given template will be executed
 instead of the default
@@ -103,132 +164,186 @@
 
 ## Examples
 
+### Basic example
+
 You'll need two shells for this example.
 
 **Shell 1: Listening for events:**
 
-    $ docker events
+```bash
+$ docker events
+```
 
 **Shell 2: Start and Stop containers:**
 
-    $ docker create --name test alpine:latest top
-    $ docker start test
-    $ docker stop test
+```bash
+$ docker create --name test alpine:latest top
+$ docker start test
+$ docker stop test
+```
 
 **Shell 1: (Again .. now showing events):**
 
-    2017-01-05T00:35:58.859401177+08:00 container create 0fdb48addc82871eb34eb23a847cfd033dedd1a0a37bef2e6d9eb3870fc7ff37 (image=alpine:latest, name=test)
-    2017-01-05T00:36:04.703631903+08:00 network connect e2e1f5ceda09d4300f3a846f0acfaa9a8bb0d89e775eb744c5acecd60e0529e2 (container=0fdb...ff37, name=bridge, type=bridge)
-    2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
-    2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
-    2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
-    2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
-    2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
+```none
+2017-01-05T00:35:58.859401177+08:00 container create 0fdb48addc82871eb34eb23a847cfd033dedd1a0a37bef2e6d9eb3870fc7ff37 (image=alpine:latest, name=test)
+2017-01-05T00:36:04.703631903+08:00 network connect e2e1f5ceda09d4300f3a846f0acfaa9a8bb0d89e775eb744c5acecd60e0529e2 (container=0fdb...ff37, name=bridge, type=bridge)
+2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
+2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
+2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
+2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
+2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
+```
 
-**Show events in the past from a specified time:**
+To exit the `docker events` command, use `CTRL+C`.
 
-    $ docker events --since 1483283804
-    2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
-    2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
-    2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
-    2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
-    2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
-    2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
-    2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
-    2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
+### Filter events by time
 
-    $ docker events --since '2017-01-05'
-    2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
-    2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
-    2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
-    2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
-    2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
-    2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
-    2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
-    2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
+You can filter the output by an absolute timestamp or relative time on the host
+machine, using the following different time syntaxes:
 
-    $ docker events --since '2013-09-03T15:49:29'
-    2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
-    2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
-    2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
-    2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
-    2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
-    2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
-    2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
-    2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
+```bash
+$ docker events --since 1483283804
+2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
+2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
+2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
+2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
+2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
+2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
+2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
+2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
 
-This example outputs all events that were generated in the last 3 minutes,
-relative to the current time on the client machine:
+$ docker events --since '2017-01-05'
+2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
+2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
+2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
+2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
+2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
+2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
+2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
+2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
 
-    $ docker events --since '10m'
-    2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
-    2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
-    2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
-    2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
-    2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
-    2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
-    2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
-    2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
+$ docker events --since '2013-09-03T15:49:29'
+2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
+2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
+2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
+2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
+2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
+2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
+2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
+2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
 
-**Filter events:**
+$ docker events --since '10m'
+2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
+2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
+2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
+2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
+2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
+2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
+2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
+2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
+```
 
-    $ docker events --filter 'event=stop'
-    2017-01-05T00:40:22.880175420+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
-    2017-01-05T00:41:17.888104182+08:00 container stop 2a8f...4e78 (image=alpine, name=kickass_brattain)
+### Filter events by criteria
 
-    $ docker events --filter 'image=alpine'
-    2017-01-05T00:41:55.784240236+08:00 container create d9cd...4d70 (image=alpine, name=happy_meitner)
-    2017-01-05T00:41:55.913156783+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner)
-    2017-01-05T00:42:01.106875249+08:00 container kill d9cd...4d70 (image=alpine, name=happy_meitner, signal=15)
-    2017-01-05T00:42:11.111934041+08:00 container kill d9cd...4d70 (image=alpine, name=happy_meitner, signal=9)
-    2017-01-05T00:42:11.119578204+08:00 container die d9cd...4d70 (exitCode=137, image=alpine, name=happy_meitner)
-    2017-01-05T00:42:11.173276611+08:00 container stop d9cd...4d70 (image=alpine, name=happy_meitner)
+The following commands show several different ways to filter the `docker event`
+output.
 
-    $ docker events --filter 'container=test'
-    2017-01-05T00:43:00.139719934+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
-    2017-01-05T00:43:09.259951086+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
-    2017-01-05T00:43:09.270102715+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
-    2017-01-05T00:43:09.312556440+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
+```bash
+$ docker events --filter 'event=stop'
 
-    $ docker events --filter 'container=test' --filter 'container=d9cdb1525ea8'
-    2017-01-05T00:44:11.517071981+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
-    2017-01-05T00:44:17.685870901+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner)
-    2017-01-05T00:44:29.757658470+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=9)
-    2017-01-05T00:44:29.767718510+08:00 container die 0fdb...ff37 (exitCode=137, image=alpine:latest, name=test)
-    2017-01-05T00:44:29.815798344+08:00 container destroy 0fdb...ff37 (image=alpine:latest, name=test)
+2017-01-05T00:40:22.880175420+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
+2017-01-05T00:41:17.888104182+08:00 container stop 2a8f...4e78 (image=alpine, name=kickass_brattain)
 
-    $ docker events --filter 'container=test' --filter 'event=stop'
-    2017-01-05T00:46:13.664099505+08:00 container stop a9d1...e130 (image=alpine, name=test)
+$ docker events --filter 'image=alpine'
 
-    $ docker events --filter 'type=volume'
-    2015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local)
-    2015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562f...5025, destination=/foo, driver=local, propagation=rprivate)
-    2015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562f...5025, driver=local)
-    2015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local)
+2017-01-05T00:41:55.784240236+08:00 container create d9cd...4d70 (image=alpine, name=happy_meitner)
+2017-01-05T00:41:55.913156783+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner)
+2017-01-05T00:42:01.106875249+08:00 container kill d9cd...4d70 (image=alpine, name=happy_meitner, signal=15)
+2017-01-05T00:42:11.111934041+08:00 container kill d9cd...4d70 (image=alpine, name=happy_meitner, signal=9)
+2017-01-05T00:42:11.119578204+08:00 container die d9cd...4d70 (exitCode=137, image=alpine, name=happy_meitner)
+2017-01-05T00:42:11.173276611+08:00 container stop d9cd...4d70 (image=alpine, name=happy_meitner)
 
-    $ docker events --filter 'type=network'
-    2015-12-23T21:38:24.705709133Z network create 8b11...2c5b (name=test-event-network-local, type=bridge)
-    2015-12-23T21:38:25.119625123Z network connect 8b11...2c5b (name=test-event-network-local, container=b4be...c54e, type=bridge)
+$ docker events --filter 'container=test'
 
-    $ docker events --filter 'type=plugin' (experimental)
-    2016-07-25T17:30:14.825557616Z plugin pull ec7b...993f (name=tiborvass/sample-volume-plugin:latest)
-    2016-07-25T17:30:14.888127370Z plugin enable ec7b...993f (name=tiborvass/sample-volume-plugin:latest)
+2017-01-05T00:43:00.139719934+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
+2017-01-05T00:43:09.259951086+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
+2017-01-05T00:43:09.270102715+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
+2017-01-05T00:43:09.312556440+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
 
-**Format:**
+$ docker events --filter 'container=test' --filter 'container=d9cdb1525ea8'
 
-    $ docker events --filter 'type=container' --format 'Type={{.Type}}  Status={{.Status}}  ID={{.ID}}'
-    Type=container  Status=create  ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
-    Type=container  Status=attach  ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
-    Type=container  Status=start  ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
-    Type=container  Status=resize  ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
-    Type=container  Status=die  ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
-    Type=container  Status=destroy  ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
+2017-01-05T00:44:11.517071981+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
+2017-01-05T00:44:17.685870901+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner)
+2017-01-05T00:44:29.757658470+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=9)
+2017-01-05T00:44:29.767718510+08:00 container die 0fdb...ff37 (exitCode=137, image=alpine:latest, name=test)
+2017-01-05T00:44:29.815798344+08:00 container destroy 0fdb...ff37 (image=alpine:latest, name=test)
 
-**Format (as JSON Lines):**
+$ docker events --filter 'container=test' --filter 'event=stop'
 
+2017-01-05T00:46:13.664099505+08:00 container stop a9d1...e130 (image=alpine, name=test)
+
+$ docker events --filter 'type=volume'
+
+2015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local)
+2015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562f...5025, destination=/foo, driver=local, propagation=rprivate)
+2015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562f...5025, driver=local)
+2015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local)
+
+$ docker events --filter 'type=network'
+
+2015-12-23T21:38:24.705709133Z network create 8b11...2c5b (name=test-event-network-local, type=bridge)
+2015-12-23T21:38:25.119625123Z network connect 8b11...2c5b (name=test-event-network-local, container=b4be...c54e, type=bridge)
+
+$ docker events --filter 'container=container_1' --filter 'container=container_2'
+
+2014-09-03T15:49:29.999999999Z07:00 container die 4386fb97867d (image=ubuntu-1:14.04)
+2014-05-10T17:42:14.999999999Z07:00 container stop 4386fb97867d (image=ubuntu-1:14.04)
+2014-05-10T17:42:14.999999999Z07:00 container die 7805c1d35632 (imager=redis:2.8)
+2014-09-03T15:49:29.999999999Z07:00 container stop 7805c1d35632 (image=redis:2.8)
+
+$ docker events --filter 'type=volume'
+
+2015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local)
+2015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562fe10671e9273da25eed36cdce26159085ac7ee6707105fd534866340a5025, destination=/foo, driver=local, propagation=rprivate)
+2015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562fe10671e9273da25eed36cdce26159085ac7ee6707105fd534866340a5025, driver=local)
+2015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local)
+
+$ docker events --filter 'type=network'
+
+2015-12-23T21:38:24.705709133Z network create 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, type=bridge)
+2015-12-23T21:38:25.119625123Z network connect 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, container=b4be644031a3d90b400f88ab3d4bdf4dc23adb250e696b6328b85441abe2c54e, type=bridge)
+```
+
+The `type=plugin` filter is experimental.
+
+```bash
+$ docker events --filter 'type=plugin'
+
+2016-07-25T17:30:14.825557616Z plugin pull ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest)
+2016-07-25T17:30:14.888127370Z plugin enable ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest)
+```
+
+### Format the output
+
+```bash
+$ docker events --filter 'type=container' --format 'Type={{.Type}}  Status={{.Status}}  ID={{.ID}}'
+
+Type=container  Status=create  ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
+Type=container  Status=attach  ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
+Type=container  Status=start  ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
+Type=container  Status=resize  ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
+Type=container  Status=die  ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
+Type=container  Status=destroy  ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
+```
+
+#### Format as JSON
+
+```none
     $ docker events --format '{{json .}}'
+
     {"status":"create","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
     {"status":"attach","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
     {"Type":"network","Action":"connect","Actor":{"ID":"1b50a5bf755f6021dfa78e..
     {"status":"start","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f42..
     {"status":"resize","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
+```
diff --git a/docs/reference/commandline/exec.md b/docs/reference/commandline/exec.md
index 38891c9..1ae46cf 100644
--- a/docs/reference/commandline/exec.md
+++ b/docs/reference/commandline/exec.md
@@ -31,35 +31,61 @@
   -u, --user           Username or UID (format: <name|uid>[:<group|gid>])
 ```
 
+## Description
+
 The `docker exec` command runs a new command in a running container.
 
 The command started using `docker exec` only runs while the container's primary
 process (`PID 1`) is running, and it is not restarted if the container is
 restarted.
 
-If the container is paused, then the `docker exec` command will fail with an error:
-
-    $ docker pause test
-    test
-    $ docker ps
-    CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS                   PORTS               NAMES
-    1ae3b36715d2        ubuntu:latest       "bash"              17 seconds ago      Up 16 seconds (Paused)                       test
-    $ docker exec test ls
-    FATA[0000] Error response from daemon: Container test is paused, unpause the container before exec
-    $ echo $?
-    1
-
 ## Examples
 
-    $ docker run --name ubuntu_bash --rm -i -t ubuntu bash
+### Run `docker exec` on a running container
+
+First, start a container.
+
+```bash
+$ docker run --name ubuntu_bash --rm -i -t ubuntu bash
+```
 
 This will create a container named `ubuntu_bash` and start a Bash session.
 
-    $ docker exec -d ubuntu_bash touch /tmp/execWorks
+Next, execute a command on the container.
+
+```bash
+$ docker exec -d ubuntu_bash touch /tmp/execWorks
+```
 
 This will create a new file `/tmp/execWorks` inside the running container
 `ubuntu_bash`, in the background.
 
-    $ docker exec -it ubuntu_bash bash
+Next, execute an interactive `bash` shell on the container.
+
+```bash
+$ docker exec -it ubuntu_bash bash
+```
 
 This will create a new Bash session in the container `ubuntu_bash`.
+
+### Try to run `docker exec` on a paused container
+
+If the container is paused, then the `docker exec` command will fail with an error:
+
+```bash
+$ docker pause test
+
+test
+
+$ docker ps
+
+CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS                   PORTS               NAMES
+1ae3b36715d2        ubuntu:latest       "bash"              17 seconds ago      Up 16 seconds (Paused)                       test
+
+$ docker exec test ls
+
+FATA[0000] Error response from daemon: Container test is paused, unpause the container before exec
+
+$ echo $?
+1
+```
diff --git a/docs/reference/commandline/export.md b/docs/reference/commandline/export.md
index 1004fc3..9de5097 100644
--- a/docs/reference/commandline/export.md
+++ b/docs/reference/commandline/export.md
@@ -25,19 +25,24 @@
   -o, --output string   Write to a file, instead of STDOUT
 ```
 
+## Description
+
 The `docker export` command does not export the contents of volumes associated
 with the container. If a volume is mounted on top of an existing directory in
 the container, `docker export` will export the contents of the *underlying*
 directory, not the contents of the volume.
 
-Refer to [Backup, restore, or migrate data
-volumes](https://docs.docker.com/engine/tutorials/dockervolumes/#backup-restore-or-migrate-data-volumes) in
-the user guide for examples on exporting data in a volume.
+Refer to [Backup, restore, or migrate data volumes](https://docs.docker.com/engine/tutorials/dockervolumes/#backup-restore-or-migrate-data-volumes)
+in the user guide for examples on exporting data in a volume.
 
 ## Examples
 
-    $ docker export red_panda > latest.tar
+Each of these commands has the same result.
 
-Or
+```bash
+$ docker export red_panda > latest.tar
+```
 
-    $ docker export --output="latest.tar" red_panda
+```bash
+$ docker export --output="latest.tar" red_panda
+```
diff --git a/docs/reference/commandline/history.md b/docs/reference/commandline/history.md
index 00f88db..b68cc86 100644
--- a/docs/reference/commandline/history.md
+++ b/docs/reference/commandline/history.md
@@ -27,22 +27,30 @@
   -q, --quiet      Only show numeric IDs
 ```
 
+
+## Examples
+
 To see how the `docker:latest` image was built:
 
-    $ docker history docker
-    IMAGE               CREATED             CREATED BY                                      SIZE                COMMENT
-    3e23a5875458        8 days ago          /bin/sh -c #(nop) ENV LC_ALL=C.UTF-8            0 B
-    8578938dd170        8 days ago          /bin/sh -c dpkg-reconfigure locales &&    loc   1.245 MB
-    be51b77efb42        8 days ago          /bin/sh -c apt-get update && apt-get install    338.3 MB
-    4b137612be55        6 weeks ago         /bin/sh -c #(nop) ADD jessie.tar.xz in /        121 MB
-    750d58736b4b        6 weeks ago         /bin/sh -c #(nop) MAINTAINER Tianon Gravi <ad   0 B
-    511136ea3c5a        9 months ago                                                        0 B                 Imported from -
+```bash
+$ docker history docker
+
+IMAGE               CREATED             CREATED BY                                      SIZE                COMMENT
+3e23a5875458        8 days ago          /bin/sh -c #(nop) ENV LC_ALL=C.UTF-8            0 B
+8578938dd170        8 days ago          /bin/sh -c dpkg-reconfigure locales &&    loc   1.245 MB
+be51b77efb42        8 days ago          /bin/sh -c apt-get update && apt-get install    338.3 MB
+4b137612be55        6 weeks ago         /bin/sh -c #(nop) ADD jessie.tar.xz in /        121 MB
+750d58736b4b        6 weeks ago         /bin/sh -c #(nop) MAINTAINER Tianon Gravi <ad   0 B
+511136ea3c5a        9 months ago                                                        0 B                 Imported from -
+```
 
 To see how the `docker:apache` image was added to a container's base image:
 
-    $ docker history docker:scm
-    IMAGE               CREATED             CREATED BY                                      SIZE                COMMENT
-    2ac9d1098bf1        3 months ago        /bin/bash                                       241.4 MB            Added Apache to Fedora base image
-    88b42ffd1f7c        5 months ago        /bin/sh -c #(nop) ADD file:1fd8d7f9f6557cafc7   373.7 MB
-    c69cab00d6ef        5 months ago        /bin/sh -c #(nop) MAINTAINER Lokesh Mandvekar   0 B
-    511136ea3c5a        19 months ago                                                       0 B                 Imported from -
+```bash
+$ docker history docker:scm
+IMAGE               CREATED             CREATED BY                                      SIZE                COMMENT
+2ac9d1098bf1        3 months ago        /bin/bash                                       241.4 MB            Added Apache to Fedora base image
+88b42ffd1f7c        5 months ago        /bin/sh -c #(nop) ADD file:1fd8d7f9f6557cafc7   373.7 MB
+c69cab00d6ef        5 months ago        /bin/sh -c #(nop) MAINTAINER Lokesh Mandvekar   0 B
+511136ea3c5a        19 months ago                                                       0 B                 Imported from -
+```
diff --git a/docs/reference/commandline/image_prune.md b/docs/reference/commandline/image_prune.md
index a80b8d3..6e1fd26 100644
--- a/docs/reference/commandline/image_prune.md
+++ b/docs/reference/commandline/image_prune.md
@@ -26,12 +26,17 @@
       --help    Print usage
 ```
 
+## Description
+
 Remove all dangling images. If `-a` is specified, will also remove all images not referenced by any container.
 
+## Examples
+
 Example output:
 
 ```bash
 $ docker image prune -a
+
 WARNING! This will remove all images without at least one container associated to them.
 Are you sure you want to continue? [y/N] y
 Deleted Images:
@@ -62,7 +67,7 @@
 Total reclaimed space: 16.43 MB
 ```
 
-## Related information
+## Related commands
 
 * [system df](system_df.md)
 * [container prune](container_prune.md)
diff --git a/docs/reference/commandline/images.md b/docs/reference/commandline/images.md
index 3b9ea1f..82c572e 100644
--- a/docs/reference/commandline/images.md
+++ b/docs/reference/commandline/images.md
@@ -35,6 +35,8 @@
   -q, --quiet           Only show numeric IDs
 ```
 
+## Description
+
 The default `docker images` will show all top level
 images, their repository and tags, and their size.
 
@@ -51,21 +53,26 @@
 or tags. This single image (identifiable by its matching `IMAGE ID`)
 uses up the `SIZE` listed only once.
 
-### Listing the most recently created images
+## Examples
 
-    $ docker images
-    REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
-    <none>                    <none>              77af4d6b9913        19 hours ago        1.089 GB
-    committ                   latest              b6fa739cedf5        19 hours ago        1.089 GB
-    <none>                    <none>              78a85c484f71        19 hours ago        1.089 GB
-    docker                    latest              30557a29d5ab        20 hours ago        1.089 GB
-    <none>                    <none>              5ed6274db6ce        24 hours ago        1.089 GB
-    postgres                  9                   746b819f315e        4 days ago          213.4 MB
-    postgres                  9.3                 746b819f315e        4 days ago          213.4 MB
-    postgres                  9.3.5               746b819f315e        4 days ago          213.4 MB
-    postgres                  latest              746b819f315e        4 days ago          213.4 MB
+### List the most recently created images
 
-### Listing images by name and tag
+```bash
+$ docker images
+
+REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
+<none>                    <none>              77af4d6b9913        19 hours ago        1.089 GB
+committ                   latest              b6fa739cedf5        19 hours ago        1.089 GB
+<none>                    <none>              78a85c484f71        19 hours ago        1.089 GB
+docker                    latest              30557a29d5ab        20 hours ago        1.089 GB
+<none>                    <none>              5ed6274db6ce        24 hours ago        1.089 GB
+postgres                  9                   746b819f315e        4 days ago          213.4 MB
+postgres                  9.3                 746b819f315e        4 days ago          213.4 MB
+postgres                  9.3.5               746b819f315e        4 days ago          213.4 MB
+postgres                  latest              746b819f315e        4 days ago          213.4 MB
+```
+
+### List images by name and tag
 
 The `docker images` command takes an optional `[REPOSITORY[:TAG]]` argument
 that restricts the list to images that match the argument. If you specify
@@ -74,11 +81,14 @@
 
 For example, to list all images in the "java" repository, run this command :
 
-    $ docker images java
-    REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
-    java                8                   308e519aac60        6 days ago          824.5 MB
-    java                7                   493d82594c15        3 months ago        656.3 MB
-    java                latest              2711b1d6f3aa        5 months ago        603.9 MB
+```bash
+$ docker images java
+
+REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
+java                8                   308e519aac60        6 days ago          824.5 MB
+java                7                   493d82594c15        3 months ago        656.3 MB
+java                latest              2711b1d6f3aa        5 months ago        603.9 MB
+```
 
 The `[REPOSITORY[:TAG]]` value must be an "exact match". This means that, for example,
 `docker images jav` does not match the image `java`.
@@ -87,46 +97,57 @@
 repository and tag are listed.  To find all local images in the "java"
 repository with tag "8" you can use:
 
-    $ docker images java:8
-    REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
-    java                8                   308e519aac60        6 days ago          824.5 MB
+```bash
+$ docker images java:8
+
+REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
+java                8                   308e519aac60        6 days ago          824.5 MB
+```
 
 If nothing matches `REPOSITORY[:TAG]`, the list is empty.
 
-    $ docker images java:0
-    REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
+```bash
+$ docker images java:0
 
-## Listing the full length image IDs
+REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
+```
 
-    $ docker images --no-trunc
-    REPOSITORY                    TAG                 IMAGE ID                                                                  CREATED             SIZE
-    <none>                        <none>              sha256:77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182   19 hours ago        1.089 GB
-    committest                    latest              sha256:b6fa739cedf5ea12a620a439402b6004d057da800f91c7524b5086a5e4749c9f   19 hours ago        1.089 GB
-    <none>                        <none>              sha256:78a85c484f71509adeaace20e72e941f6bdd2b25b4c75da8693efd9f61a37921   19 hours ago        1.089 GB
-    docker                        latest              sha256:30557a29d5abc51e5f1d5b472e79b7e296f595abcf19fe6b9199dbbc809c6ff4   20 hours ago        1.089 GB
-    <none>                        <none>              sha256:0124422dd9f9cf7ef15c0617cda3931ee68346455441d66ab8bdc5b05e9fdce5   20 hours ago        1.089 GB
-    <none>                        <none>              sha256:18ad6fad340262ac2a636efd98a6d1f0ea775ae3d45240d3418466495a19a81b   22 hours ago        1.082 GB
-    <none>                        <none>              sha256:f9f1e26352f0a3ba6a0ff68167559f64f3e21ff7ada60366e2d44a04befd1d3a   23 hours ago        1.089 GB
-    tryout                        latest              sha256:2629d1fa0b81b222fca63371ca16cbf6a0772d07759ff80e8d1369b926940074   23 hours ago        131.5 MB
-    <none>                        <none>              sha256:5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df   24 hours ago        1.089 GB
+### List the full length image IDs
 
-## Listing image digests
+```bash
+$ docker images --no-trunc
+
+REPOSITORY                    TAG                 IMAGE ID                                                                  CREATED             SIZE
+<none>                        <none>              sha256:77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182   19 hours ago        1.089 GB
+committest                    latest              sha256:b6fa739cedf5ea12a620a439402b6004d057da800f91c7524b5086a5e4749c9f   19 hours ago        1.089 GB
+<none>                        <none>              sha256:78a85c484f71509adeaace20e72e941f6bdd2b25b4c75da8693efd9f61a37921   19 hours ago        1.089 GB
+docker                        latest              sha256:30557a29d5abc51e5f1d5b472e79b7e296f595abcf19fe6b9199dbbc809c6ff4   20 hours ago        1.089 GB
+<none>                        <none>              sha256:0124422dd9f9cf7ef15c0617cda3931ee68346455441d66ab8bdc5b05e9fdce5   20 hours ago        1.089 GB
+<none>                        <none>              sha256:18ad6fad340262ac2a636efd98a6d1f0ea775ae3d45240d3418466495a19a81b   22 hours ago        1.082 GB
+<none>                        <none>              sha256:f9f1e26352f0a3ba6a0ff68167559f64f3e21ff7ada60366e2d44a04befd1d3a   23 hours ago        1.089 GB
+tryout                        latest              sha256:2629d1fa0b81b222fca63371ca16cbf6a0772d07759ff80e8d1369b926940074   23 hours ago        131.5 MB
+<none>                        <none>              sha256:5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df   24 hours ago        1.089 GB
+```
+
+### List image digests
 
 Images that use the v2 or later format have a content-addressable identifier
 called a `digest`. As long as the input used to generate the image is
 unchanged, the digest value is predictable. To list image digest values, use
 the `--digests` flag:
 
-    $ docker images --digests
-    REPOSITORY                         TAG                 DIGEST                                                                    IMAGE ID            CREATED             SIZE
-    localhost:5000/test/busybox        <none>              sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf   4986bf8c1536        9 weeks ago         2.43 MB
+```bash
+$ docker images --digests
+REPOSITORY                         TAG                 DIGEST                                                                    IMAGE ID            CREATED             SIZE
+localhost:5000/test/busybox        <none>              sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf   4986bf8c1536        9 weeks ago         2.43 MB
+```
 
 When pushing or pulling to a 2.0 registry, the `push` or `pull` command
 output includes the image digest. You can `pull` using a digest value. You can
 also reference by digest in `create`, `run`, and `rmi` commands, as well as the
 `FROM` image reference in a Dockerfile.
 
-## Filtering
+### Filtering
 
 The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more
 than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`)
@@ -138,133 +159,147 @@
 * before (`<image-name>[:<tag>]`,  `<image id>` or `<image@digest>`) - filter images created before given id or references
 * since (`<image-name>[:<tag>]`,  `<image id>` or `<image@digest>`) - filter images created since given id or references
 
-##### Untagged images (dangling)
+#### Show untagged images (dangling)
 
-    $ docker images --filter "dangling=true"
+```bash
+$ docker images --filter "dangling=true"
 
-    REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
-    <none>              <none>              8abc22fbb042        4 weeks ago         0 B
-    <none>              <none>              48e5f45168b9        4 weeks ago         2.489 MB
-    <none>              <none>              bf747efa0e2f        4 weeks ago         0 B
-    <none>              <none>              980fe10e5736        12 weeks ago        101.4 MB
-    <none>              <none>              dea752e4e117        12 weeks ago        101.4 MB
-    <none>              <none>              511136ea3c5a        8 months ago        0 B
+REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
+<none>              <none>              8abc22fbb042        4 weeks ago         0 B
+<none>              <none>              48e5f45168b9        4 weeks ago         2.489 MB
+<none>              <none>              bf747efa0e2f        4 weeks ago         0 B
+<none>              <none>              980fe10e5736        12 weeks ago        101.4 MB
+<none>              <none>              dea752e4e117        12 weeks ago        101.4 MB
+<none>              <none>              511136ea3c5a        8 months ago        0 B
+```
 
-This will display untagged images, that are the leaves of the images tree (not
+This will display untagged images that are the leaves of the images tree (not
 intermediary layers). These images occur when a new build of an image takes the
 `repo:tag` away from the image ID, leaving it as `<none>:<none>` or untagged.
 A warning will be issued if trying to remove an image when a container is presently
 using it. By having this flag it allows for batch cleanup.
 
-Ready for use by `docker rmi ...`, like:
+You can use this in conjunction with `docker rmi ...`:
 
-    $ docker rmi $(docker images -f "dangling=true" -q)
+```bash
+$ docker rmi $(docker images -f "dangling=true" -q)
 
-    8abc22fbb042
-    48e5f45168b9
-    bf747efa0e2f
-    980fe10e5736
-    dea752e4e117
-    511136ea3c5a
+8abc22fbb042
+48e5f45168b9
+bf747efa0e2f
+980fe10e5736
+dea752e4e117
+511136ea3c5a
+```
 
-NOTE: Docker will warn you if any containers exist that are using these untagged images.
+> **Note**: Docker warns you if any containers exist that are using these
+> untagged images.
 
 
-##### Labeled images
+#### Show images with a given label
 
 The `label` filter matches images based on the presence of a `label` alone or a `label` and a
 value.
 
 The following filter matches images with the `com.example.version` label regardless of its value.
 
-    $ docker images --filter "label=com.example.version"
+```bash
+$ docker images --filter "label=com.example.version"
 
-    REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
-    match-me-1          latest              eeae25ada2aa        About a minute ago   188.3 MB
-    match-me-2          latest              dea752e4e117        About a minute ago   188.3 MB
+REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
+match-me-1          latest              eeae25ada2aa        About a minute ago   188.3 MB
+match-me-2          latest              dea752e4e117        About a minute ago   188.3 MB
+```
 
 The following filter matches images with the `com.example.version` label with the `1.0` value.
 
-    $ docker images --filter "label=com.example.version=1.0"
-    REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
-    match-me            latest              511136ea3c5a        About a minute ago   188.3 MB
+```bash
+$ docker images --filter "label=com.example.version=1.0"
+
+REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
+match-me            latest              511136ea3c5a        About a minute ago   188.3 MB
+```
 
 In this example, with the `0.1` value, it returns an empty set because no matches were found.
 
-    $ docker images --filter "label=com.example.version=0.1"
-    REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
+```bash
+$ docker images --filter "label=com.example.version=0.1"
+REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
+```
 
-#### Before
+#### Filter images by time
 
 The `before` filter shows only images created before the image with
 given id or reference. For example, having these images:
 
-    $ docker images
-    REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
-    image1              latest              eeae25ada2aa        4 minutes ago        188.3 MB
-    image2              latest              dea752e4e117        9 minutes ago        188.3 MB
-    image3              latest              511136ea3c5a        25 minutes ago       188.3 MB
+```bash
+$ docker images
+
+REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
+image1              latest              eeae25ada2aa        4 minutes ago        188.3 MB
+image2              latest              dea752e4e117        9 minutes ago        188.3 MB
+image3              latest              511136ea3c5a        25 minutes ago       188.3 MB
+```
 
 Filtering with `before` would give:
 
-    $ docker images --filter "before=image1"
-    REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
-    image2              latest              dea752e4e117        9 minutes ago        188.3 MB
-    image3              latest              511136ea3c5a        25 minutes ago       188.3 MB
+```bash
+$ docker images --filter "before=image1"
 
-#### Since
-
-The `since` filter shows only images created after the image with
-given id or reference. For example, having these images:
-
-    $ docker images
-    REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
-    image1              latest              eeae25ada2aa        4 minutes ago        188.3 MB
-    image2              latest              dea752e4e117        9 minutes ago        188.3 MB
-    image3              latest              511136ea3c5a        25 minutes ago       188.3 MB
+REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
+image2              latest              dea752e4e117        9 minutes ago        188.3 MB
+image3              latest              511136ea3c5a        25 minutes ago       188.3 MB
+```
 
 Filtering with `since` would give:
 
-    $ docker images --filter "since=image3"
-    REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
-    image1              latest              eeae25ada2aa        4 minutes ago        188.3 MB
-    image2              latest              dea752e4e117        9 minutes ago        188.3 MB
+```bash
+$ docker images --filter "since=image3"
+REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
+image1              latest              eeae25ada2aa        4 minutes ago        188.3 MB
+image2              latest              dea752e4e117        9 minutes ago        188.3 MB
+```
 
-#### Reference
+#### Filter images by reference
 
 The `reference` filter shows only images whose reference matches
 the specified pattern.
 
+```bash
     $ docker images
+
     REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
     busybox             latest              e02e811dd08f        5 weeks ago         1.09 MB
     busybox             uclibc              e02e811dd08f        5 weeks ago         1.09 MB
     busybox             musl                733eb3059dce        5 weeks ago         1.21 MB
     busybox             glibc               21c16b6787c6        5 weeks ago         4.19 MB
+```
 
 Filtering with `reference` would give:
 
+```bash
     $ docker images --filter=reference='busy*:*libc'
     REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
     busybox             uclibc              e02e811dd08f        5 weeks ago         1.09 MB
     busybox             glibc               21c16b6787c6        5 weeks ago         4.19 MB
+```
 
-## Formatting
+### Format the output
 
 The formatting option (`--format`) will pretty print container output
 using a Go template.
 
 Valid placeholders for the Go template are listed below:
 
-Placeholder | Description
----- | ----
-`.ID` | Image ID
-`.Repository` | Image repository
-`.Tag` | Image tag
-`.Digest` | Image digest
-`.CreatedSince` | Elapsed time since the image was created
-`.CreatedAt` | Time when the image was created
-`.Size` | Image disk size
+| Placeholder | Description|
+| ---- | ---- |
+| `.ID` | Image ID |
+| `.Repository` | Image repository |
+| `.Tag` | Image tag |
+| `.Digest` | Image digest |
+| `.CreatedSince` | Elapsed time since the image was created |
+| `.CreatedAt` | Time when the image was created |
+| `.Size` | Image disk size |
 
 When using the `--format` option, the `image` command will either
 output the data exactly as the template declares or, when using the
@@ -273,32 +308,34 @@
 The following example uses a template without headers and outputs the
 `ID` and `Repository` entries separated by a colon for all images:
 
-    {% raw %}
-    $ docker images --format "{{.ID}}: {{.Repository}}"
-    77af4d6b9913: <none>
-    b6fa739cedf5: committ
-    78a85c484f71: <none>
-    30557a29d5ab: docker
-    5ed6274db6ce: <none>
-    746b819f315e: postgres
-    746b819f315e: postgres
-    746b819f315e: postgres
-    746b819f315e: postgres
-    {% endraw %}
+```bash
+$ docker images --format "{{.ID}}: {{.Repository}}"
+
+77af4d6b9913: <none>
+b6fa739cedf5: committ
+78a85c484f71: <none>
+30557a29d5ab: docker
+5ed6274db6ce: <none>
+746b819f315e: postgres
+746b819f315e: postgres
+746b819f315e: postgres
+746b819f315e: postgres
+```
 
 To list all images with their repository and tag in a table format you
 can use:
 
-    {% raw %}
-    $ docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"
-    IMAGE ID            REPOSITORY                TAG
-    77af4d6b9913        <none>                    <none>
-    b6fa739cedf5        committ                   latest
-    78a85c484f71        <none>                    <none>
-    30557a29d5ab        docker                    latest
-    5ed6274db6ce        <none>                    <none>
-    746b819f315e        postgres                  9
-    746b819f315e        postgres                  9.3
-    746b819f315e        postgres                  9.3.5
-    746b819f315e        postgres                  latest
-    {% endraw %}
+```bash
+$ docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"
+
+IMAGE ID            REPOSITORY                TAG
+77af4d6b9913        <none>                    <none>
+b6fa739cedf5        committ                   latest
+78a85c484f71        <none>                    <none>
+30557a29d5ab        docker                    latest
+5ed6274db6ce        <none>                    <none>
+746b819f315e        postgres                  9
+746b819f315e        postgres                  9.3
+746b819f315e        postgres                  9.3.5
+746b819f315e        postgres                  latest
+```
diff --git a/docs/reference/commandline/import.md b/docs/reference/commandline/import.md
index 20e90a6..57edf65 100644
--- a/docs/reference/commandline/import.md
+++ b/docs/reference/commandline/import.md
@@ -26,6 +26,8 @@
   -m, --message string   Set commit message for imported image
 ```
 
+## Description
+
 You can specify a `URL` or `-` (dash) to take data directly from `STDIN`. The
 `URL` can point to an archive (.tar, .tar.gz, .tgz, .bzip, .tar.xz, or .txz)
 containing a filesystem or to an individual file on the Docker host.  If you
@@ -41,33 +43,45 @@
 
 ## Examples
 
-**Import from a remote location:**
+### Import from a remote location
 
 This will create a new untagged image.
 
-    $ docker import http://example.com/exampleimage.tgz
+```bash
+$ docker import http://example.com/exampleimage.tgz
+```
 
-**Import from a local file:**
+### Import from a local file
 
-Import to docker via pipe and `STDIN`.
+- Import to docker via pipe and `STDIN`.
 
-    $ cat exampleimage.tgz | docker import - exampleimagelocal:new
+  ```bash
+  $ cat exampleimage.tgz | docker import - exampleimagelocal:new
+  ```
 
-Import with a commit message.
+- Import with a commit message.
 
-    $ cat exampleimage.tgz | docker import --message "New image imported from tarball" - exampleimagelocal:new
+  ```bash
+  $ cat exampleimage.tgz | docker import --message "New image imported from tarball" - exampleimagelocal:new
+  ```
 
-Import to docker from a local archive.
+- Import to docker from a local archive.
 
+  ```bash
     $ docker import /path/to/exampleimage.tgz
+  ```
 
-**Import from a local directory:**
+### Import from a local directory
 
-    $ sudo tar -c . | docker import - exampleimagedir
+```bash
+$ sudo tar -c . | docker import - exampleimagedir
+```
 
-**Import from a local directory with new configurations:**
+### Import from a local directory with new configurations
 
-    $ sudo tar -c . | docker import --change "ENV DEBUG true" - exampleimagedir
+```bash
+$ sudo tar -c . | docker import --change "ENV DEBUG true" - exampleimagedir
+```
 
 Note the `sudo` in this example – you must preserve
 the ownership of the files (especially root ownership) during the
diff --git a/docs/reference/commandline/index.md b/docs/reference/commandline/index.md
index 952fa09..59c816e 100644
--- a/docs/reference/commandline/index.md
+++ b/docs/reference/commandline/index.md
@@ -25,6 +25,8 @@
 affects your Docker containers. For that reason you should also make sure to
 read the [`dockerd`](dockerd.md) reference page.
 
+## Commands by object
+
 ### Docker management commands
 
 | Command | Description                                                        |
@@ -122,7 +124,7 @@
 | [node ls](node_ls.md) | List nodes in the swarm                              |
 | [node rm](node_rm.md) | Remove one or more nodes from the swarm                         |
 
-### Swarm swarm commands
+### Swarm management commands
 
 | Command | Description                                                        |
 |:--------|:-------------------------------------------------------------------|
diff --git a/docs/reference/commandline/info.md b/docs/reference/commandline/info.md
index 50a084f..798c3f0 100644
--- a/docs/reference/commandline/info.md
+++ b/docs/reference/commandline/info.md
@@ -25,6 +25,8 @@
       --help            Print usage
 ```
 
+## Description
+
 This command displays system wide information regarding the Docker installation.
 Information displayed includes the kernel version, number of containers and images.
 The number of images shown is the number of unique images. The same image tagged
@@ -43,182 +45,200 @@
 allocates a certain amount of data space and meta data space from the space
 available on the volume where `/var/lib/docker` is mounted.
 
-# Examples
+## Examples
 
-## Display Docker system information
+### Show output
+
+The example below shows the output for a daemon running on Red Hat Enterprise Linux,
+using the `devicemapper` storage driver. As can be seen in the output, additional
+information about the `devicemapper` storage driver is shown:
+
+```bash
+$ docker info
+
+Containers: 14
+ Running: 3
+ Paused: 1
+ Stopped: 10
+Images: 52
+Server Version: 1.10.3
+Storage Driver: devicemapper
+ Pool Name: docker-202:2-25583803-pool
+ Pool Blocksize: 65.54 kB
+ Base Device Size: 10.74 GB
+ Backing Filesystem: xfs
+ Data file: /dev/loop0
+ Metadata file: /dev/loop1
+ Data Space Used: 1.68 GB
+ Data Space Total: 107.4 GB
+ Data Space Available: 7.548 GB
+ Metadata Space Used: 2.322 MB
+ Metadata Space Total: 2.147 GB
+ Metadata Space Available: 2.145 GB
+ Udev Sync Supported: true
+ Deferred Removal Enabled: false
+ Deferred Deletion Enabled: false
+ Deferred Deleted Device Count: 0
+ Data loop file: /var/lib/docker/devicemapper/devicemapper/data
+ Metadata loop file: /var/lib/docker/devicemapper/devicemapper/metadata
+ Library Version: 1.02.107-RHEL7 (2015-12-01)
+Execution Driver: native-0.2
+Logging Driver: json-file
+Plugins:
+ Volume: local
+ Network: null host bridge
+Kernel Version: 3.10.0-327.el7.x86_64
+Operating System: Red Hat Enterprise Linux Server 7.2 (Maipo)
+OSType: linux
+Architecture: x86_64
+CPUs: 1
+Total Memory: 991.7 MiB
+Name: ip-172-30-0-91.ec2.internal
+ID: I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S
+Docker Root Dir: /var/lib/docker
+Debug mode (client): false
+Debug mode (server): false
+Username: gordontheturtle
+Registry: https://index.docker.io/v1/
+Insecure registries:
+ myinsecurehost:5000
+ 127.0.0.0/8
+```
+
+### Show debugging output
 
 Here is a sample output for a daemon running on Ubuntu, using the overlay2
 storage driver and a node that is part of a 2-node swarm:
 
-    $ docker -D info
-    Containers: 14
-     Running: 3
-     Paused: 1
-     Stopped: 10
-    Images: 52
-    Server Version: 1.13.0
-    Storage Driver: overlay2
-     Backing Filesystem: extfs
-     Supports d_type: true
-     Native Overlay Diff: false
-    Logging Driver: json-file
-    Cgroup Driver: cgroupfs
-    Plugins:
-     Volume: local
-     Network: bridge host macvlan null overlay
-    Swarm: active
-     NodeID: rdjq45w1op418waxlairloqbm
-     Is Manager: true
-     ClusterID: te8kdyw33n36fqiz74bfjeixd
-     Managers: 1
-     Nodes: 2
-     Orchestration:
-      Task History Retention Limit: 5
-     Raft:
-      Snapshot Interval: 10000
-      Number of Old Snapshots to Retain: 0
-      Heartbeat Tick: 1
-      Election Tick: 3
-     Dispatcher:
-      Heartbeat Period: 5 seconds
-     CA Configuration:
-      Expiry Duration: 3 months
-     Node Address: 172.16.66.128 172.16.66.129
-     Manager Addresses:
-      172.16.66.128:2477
-    Runtimes: runc
-    Default Runtime: runc
-    Init Binary: docker-init
-    containerd version: 8517738ba4b82aff5662c97ca4627e7e4d03b531
-    runc version: ac031b5bf1cc92239461125f4c1ffb760522bbf2
-    init version: N/A (expected: v0.13.0)
-    Security Options:
-     apparmor
-     seccomp
-      Profile: default
-    Kernel Version: 4.4.0-31-generic
-    Operating System: Ubuntu 16.04.1 LTS
-    OSType: linux
-    Architecture: x86_64
-    CPUs: 2
-    Total Memory: 1.937 GiB
-    Name: ubuntu
-    ID: H52R:7ZR6:EIIA:76JG:ORIY:BVKF:GSFU:HNPG:B5MK:APSC:SZ3Q:N326
-    Docker Root Dir: /var/lib/docker
-    Debug Mode (client): true
-    Debug Mode (server): true
-     File Descriptors: 30
-     Goroutines: 123
-     System Time: 2016-11-12T17:24:37.955404361-08:00
-     EventsListeners: 0
-    Http Proxy: http://test:test@proxy.example.com:8080
-    Https Proxy: https://test:test@proxy.example.com:8080
-    No Proxy: localhost,127.0.0.1,docker-registry.somecorporation.com
-    Registry: https://index.docker.io/v1/
-    WARNING: No swap limit support
-    Labels:
-     storage=ssd
-     staging=true
-    Experimental: false
-    Insecure Registries:
-     127.0.0.0/8
-    Registry Mirrors:
-      http://192.168.1.2/
-      http://registry-mirror.example.com:5000/
-    Live Restore Enabled: false
+```bash
+$ docker -D info
 
-The global `-D` option tells all `docker` commands to output debug information.
+Containers: 14
+ Running: 3
+ Paused: 1
+ Stopped: 10
+Images: 52
+Server Version: 1.13.0
+Storage Driver: overlay2
+ Backing Filesystem: extfs
+ Supports d_type: true
+ Native Overlay Diff: false
+Logging Driver: json-file
+Cgroup Driver: cgroupfs
+Plugins:
+ Volume: local
+ Network: bridge host macvlan null overlay
+Swarm: active
+ NodeID: rdjq45w1op418waxlairloqbm
+ Is Manager: true
+ ClusterID: te8kdyw33n36fqiz74bfjeixd
+ Managers: 1
+ Nodes: 2
+ Orchestration:
+  Task History Retention Limit: 5
+ Raft:
+  Snapshot Interval: 10000
+  Number of Old Snapshots to Retain: 0
+  Heartbeat Tick: 1
+  Election Tick: 3
+ Dispatcher:
+  Heartbeat Period: 5 seconds
+ CA Configuration:
+  Expiry Duration: 3 months
+ Node Address: 172.16.66.128 172.16.66.129
+ Manager Addresses:
+  172.16.66.128:2477
+Runtimes: runc
+Default Runtime: runc
+Init Binary: docker-init
+containerd version: 8517738ba4b82aff5662c97ca4627e7e4d03b531
+runc version: ac031b5bf1cc92239461125f4c1ffb760522bbf2
+init version: N/A (expected: v0.13.0)
+Security Options:
+ apparmor
+ seccomp
+  Profile: default
+Kernel Version: 4.4.0-31-generic
+Operating System: Ubuntu 16.04.1 LTS
+OSType: linux
+Architecture: x86_64
+CPUs: 2
+Total Memory: 1.937 GiB
+Name: ubuntu
+ID: H52R:7ZR6:EIIA:76JG:ORIY:BVKF:GSFU:HNPG:B5MK:APSC:SZ3Q:N326
+Docker Root Dir: /var/lib/docker
+Debug Mode (client): true
+Debug Mode (server): true
+ File Descriptors: 30
+ Goroutines: 123
+ System Time: 2016-11-12T17:24:37.955404361-08:00
+ EventsListeners: 0
+Http Proxy: http://test:test@proxy.example.com:8080
+Https Proxy: https://test:test@proxy.example.com:8080
+No Proxy: localhost,127.0.0.1,docker-registry.somecorporation.com
+Registry: https://index.docker.io/v1/
+WARNING: No swap limit support
+Labels:
+ storage=ssd
+ staging=true
+Experimental: false
+Insecure Registries:
+ 127.0.0.0/8
+Registry Mirrors:
+  http://192.168.1.2/
+  http://registry-mirror.example.com:5000/
+Live Restore Enabled: false
+```
 
-The example below shows the output for a daemon running on Red Hat Enterprise Linux,
-using the devicemapper storage driver. As can be seen in the output, additional
-information about the devicemapper storage driver is shown:
+The global `-D` option causes all `docker` commands to output debug information.
 
-    $ docker info
-    Containers: 14
-     Running: 3
-     Paused: 1
-     Stopped: 10
-    Images: 52
-    Server Version: 1.10.3
-    Storage Driver: devicemapper
-     Pool Name: docker-202:2-25583803-pool
-     Pool Blocksize: 65.54 kB
-     Base Device Size: 10.74 GB
-     Backing Filesystem: xfs
-     Data file: /dev/loop0
-     Metadata file: /dev/loop1
-     Data Space Used: 1.68 GB
-     Data Space Total: 107.4 GB
-     Data Space Available: 7.548 GB
-     Metadata Space Used: 2.322 MB
-     Metadata Space Total: 2.147 GB
-     Metadata Space Available: 2.145 GB
-     Udev Sync Supported: true
-     Deferred Removal Enabled: false
-     Deferred Deletion Enabled: false
-     Deferred Deleted Device Count: 0
-     Data loop file: /var/lib/docker/devicemapper/devicemapper/data
-     Metadata loop file: /var/lib/docker/devicemapper/devicemapper/metadata
-     Library Version: 1.02.107-RHEL7 (2015-12-01)
-    Execution Driver: native-0.2
-    Logging Driver: json-file
-    Plugins:
-     Volume: local
-     Network: null host bridge
-    Kernel Version: 3.10.0-327.el7.x86_64
-    Operating System: Red Hat Enterprise Linux Server 7.2 (Maipo)
-    OSType: linux
-    Architecture: x86_64
-    CPUs: 1
-    Total Memory: 991.7 MiB
-    Name: ip-172-30-0-91.ec2.internal
-    ID: I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S
-    Docker Root Dir: /var/lib/docker
-    Debug mode (client): false
-    Debug mode (server): false
-    Username: gordontheturtle
-    Registry: https://index.docker.io/v1/
-    Insecure registries:
-     myinsecurehost:5000
-     127.0.0.0/8
+### Format the output
 
 You can also specify the output format:
 
-    $ docker info --format '{{json .}}'
-	{"ID":"I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S","Containers":14, ...}
+```bash
+$ docker info --format '{{json .}}'
+
+{"ID":"I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S","Containers":14, ...}
+```
+
+### Run `docker info` on Windows
 
 Here is a sample output for a daemon running on Windows Server 2016:
 
-    E:\docker>docker info
-    Containers: 1
-     Running: 0
-     Paused: 0
-     Stopped: 1
-    Images: 17
-    Server Version: 1.13.0
-    Storage Driver: windowsfilter
-     Windows:
-    Logging Driver: json-file
-    Plugins:
-     Volume: local
-     Network: nat null overlay
-    Swarm: inactive
-    Default Isolation: process
-    Kernel Version: 10.0 14393 (14393.206.amd64fre.rs1_release.160912-1937)
-    Operating System: Windows Server 2016 Datacenter
-    OSType: windows
-    Architecture: x86_64
-    CPUs: 8
-    Total Memory: 3.999 GiB
-    Name: WIN-V0V70C0LU5P
-    ID: NYMS:B5VK:UMSL:FVDZ:EWB5:FKVK:LPFL:FJMQ:H6FT:BZJ6:L2TD:XH62
-    Docker Root Dir: C:\control
-    Debug Mode (client): false
-    Debug Mode (server): false
-    Registry: https://index.docker.io/v1/
-    Insecure Registries:
-     127.0.0.0/8
-    Registry Mirrors:
-      http://192.168.1.2/
-      http://registry-mirror.example.com:5000/
-    Live Restore Enabled: false
+```none
+E:\docker>docker info
+
+Containers: 1
+ Running: 0
+ Paused: 0
+ Stopped: 1
+Images: 17
+Server Version: 1.13.0
+Storage Driver: windowsfilter
+ Windows:
+Logging Driver: json-file
+Plugins:
+ Volume: local
+ Network: nat null overlay
+Swarm: inactive
+Default Isolation: process
+Kernel Version: 10.0 14393 (14393.206.amd64fre.rs1_release.160912-1937)
+Operating System: Windows Server 2016 Datacenter
+OSType: windows
+Architecture: x86_64
+CPUs: 8
+Total Memory: 3.999 GiB
+Name: WIN-V0V70C0LU5P
+ID: NYMS:B5VK:UMSL:FVDZ:EWB5:FKVK:LPFL:FJMQ:H6FT:BZJ6:L2TD:XH62
+Docker Root Dir: C:\control
+Debug Mode (client): false
+Debug Mode (server): false
+Registry: https://index.docker.io/v1/
+Insecure Registries:
+ 127.0.0.0/8
+Registry Mirrors:
+  http://192.168.1.2/
+  http://registry-mirror.example.com:5000/
+Live Restore Enabled: false
+```
diff --git a/docs/reference/commandline/inspect.md b/docs/reference/commandline/inspect.md
index 7a0c3a0..842faf9 100644
--- a/docs/reference/commandline/inspect.md
+++ b/docs/reference/commandline/inspect.md
@@ -28,7 +28,9 @@
       --type         Return JSON for specified type
 ```
 
-By default, this will render all results in a JSON array. If the container and
+## Description
+
+By default, `docker inspect` will render all results in a JSON array. If the container and
 image have the same name, this will return container JSON for unspecified type.
 If a format is specified, the given template will be executed for each result.
 
@@ -37,46 +39,43 @@
 
 ## Examples
 
-**Get an instance's IP address:**
+### Get an instance's IP address
 
 For the most part, you can pick out any field from the JSON in a fairly
 straightforward manner.
 
-    {% raw %}
-    $ docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $INSTANCE_ID
-    {% endraw %}
+```bash
+$ docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $INSTANCE_ID
+```
 
-**Get an instance's MAC address:**
+### Get an instance's MAC address
 
-For the most part, you can pick out any field from the JSON in a fairly
-straightforward manner.
+```bash
+$ docker inspect --format='{{range .NetworkSettings.Networks}}{{.MacAddress}}{{end}}' $INSTANCE_ID
+```
 
-    {% raw %}
-    $ docker inspect --format='{{range .NetworkSettings.Networks}}{{.MacAddress}}{{end}}' $INSTANCE_ID
-    {% endraw %}
+### Get an instance's log path
 
-**Get an instance's log path:**
+```bash
+$ docker inspect --format='{{.LogPath}}' $INSTANCE_ID
+```
 
-    {% raw %}
-    $ docker inspect --format='{{.LogPath}}' $INSTANCE_ID
-    {% endraw %}
+### Get an instance's image name
 
-**Get a Task's image name:**
+```bash
+$ docker inspect --format='{{.Container.Spec.Image}}' $INSTANCE_ID
+```
 
-    {% raw %}
-    $ docker inspect --format='{{.Container.Spec.Image}}' $INSTANCE_ID
-    {% endraw %}
+### List all port bindings
 
-**List all port bindings:**
-
-One can loop over arrays and maps in the results to produce simple text
+You can loop over arrays and maps in the results to produce simple text
 output:
 
-    {% raw %}
-    $ docker inspect --format='{{range $p, $conf := .NetworkSettings.Ports}} {{$p}} -> {{(index $conf 0).HostPort}} {{end}}' $INSTANCE_ID
-    {% endraw %}
+```bash
+$ docker inspect --format='{{range $p, $conf := .NetworkSettings.Ports}} {{$p}} -> {{(index $conf 0).HostPort}} {{end}}' $INSTANCE_ID
+```
 
-**Find a specific port mapping:**
+### Find a specific port mapping
 
 The `.Field` syntax doesn't work when the field name begins with a
 number, but the template language's `index` function does. The
@@ -86,17 +85,17 @@
 then `index` 0 contains the first object inside of that. Then we ask for
 the `HostPort` field to get the public address.
 
-    {% raw %}
-    $ docker inspect --format='{{(index (index .NetworkSettings.Ports "8787/tcp") 0).HostPort}}' $INSTANCE_ID
-    {% endraw %}
+```bash
+$ docker inspect --format='{{(index (index .NetworkSettings.Ports "8787/tcp") 0).HostPort}}' $INSTANCE_ID
+```
 
-**Get a subsection in JSON format:**
+### Get a subsection in JSON format
 
 If you request a field which is itself a structure containing other
 fields, by default you get a Go-style dump of the inner values.
 Docker adds a template function, `json`, which can be applied to get
 results in JSON format.
 
-    {% raw %}
-    $ docker inspect --format='{{json .Config}}' $INSTANCE_ID
-    {% endraw %}
+```bash
+$ docker inspect --format='{{json .Config}}' $INSTANCE_ID
+```
diff --git a/docs/reference/commandline/kill.md b/docs/reference/commandline/kill.md
index 32fde3d..97b15ad 100644
--- a/docs/reference/commandline/kill.md
+++ b/docs/reference/commandline/kill.md
@@ -25,10 +25,11 @@
   -s, --signal string   Signal to send to the container (default "KILL")
 ```
 
+## Description
+
 The main process inside the container will be sent `SIGKILL`, or any
 signal specified with option `--signal`.
 
-> **Note:**
-> `ENTRYPOINT` and `CMD` in the *shell* form run as a subcommand of `/bin/sh -c`,
-> which does not pass signals. This means that the executable is not the container’s PID 1
-> and does not receive Unix signals.
+> **Note**: `ENTRYPOINT` and `CMD` in the *shell* form run as a subcommand of
+> `/bin/sh -c`, which does not pass signals. This means that the executable is
+> not the container’s PID 1 and does not receive Unix signals.
diff --git a/docs/reference/commandline/load.md b/docs/reference/commandline/load.md
index 04a5bc7..3ce6c19 100644
--- a/docs/reference/commandline/load.md
+++ b/docs/reference/commandline/load.md
@@ -26,28 +26,37 @@
                        The tarball may be compressed with gzip, bzip, or xz
   -q, --quiet          Suppress the load output but still outputs the imported images
 ```
+## Description
 
-Loads a tarred repository from a file or the standard input stream.
-Restores both images and tags.
+`docker load` loads a tarred repository from a file or the standard input stream.
+It restores both images and tags.
 
-    $ docker images
-    REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
-    $ docker load < busybox.tar.gz
-    # […]
-    Loaded image: busybox:latest
-    $ docker images
-    REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
-    busybox             latest              769b9341d937        7 weeks ago         2.489 MB
-    $ docker load --input fedora.tar
-    # […]
-    Loaded image: fedora:rawhide
-    # […]
-    Loaded image: fedora:20
-    # […]
-    $ docker images
-    REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
-    busybox             latest              769b9341d937        7 weeks ago         2.489 MB
-    fedora              rawhide             0d20aec6529d        7 weeks ago         387 MB
-    fedora              20                  58394af37342        7 weeks ago         385.5 MB
-    fedora              heisenbug           58394af37342        7 weeks ago         385.5 MB
-    fedora              latest              58394af37342        7 weeks ago         385.5 MB
+## Examples
+
+```bash
+$ docker images
+
+REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
+
+$ docker load < busybox.tar.gz
+
+Loaded image: busybox:latest
+$ docker images
+REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
+busybox             latest              769b9341d937        7 weeks ago         2.489 MB
+
+$ docker load --input fedora.tar
+
+Loaded image: fedora:rawhide
+
+Loaded image: fedora:20
+
+$ docker images
+
+REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
+busybox             latest              769b9341d937        7 weeks ago         2.489 MB
+fedora              rawhide             0d20aec6529d        7 weeks ago         387 MB
+fedora              20                  58394af37342        7 weeks ago         385.5 MB
+fedora              heisenbug           58394af37342        7 weeks ago         385.5 MB
+fedora              latest              58394af37342        7 weeks ago         385.5 MB
+```
diff --git a/docs/reference/commandline/login.md b/docs/reference/commandline/login.md
index a0f35fd..e5d1656 100644
--- a/docs/reference/commandline/login.md
+++ b/docs/reference/commandline/login.md
@@ -27,12 +27,20 @@
   -u, --username string   Username
 ```
 
+## Description
+
+Login to a registry.
+
+### Login to a self-hosted registry
+
 If you want to login to a self-hosted registry you can specify this by
 adding the server name.
 
-    example:
-    $ docker login localhost:8080
+```bash
+$ docker login localhost:8080
+```
 
+### Privileged user requirement
 
 `docker login` requires user to use `sudo` or be `root`, except when:
 
@@ -43,7 +51,7 @@
 credentials.  When you log in, the command stores encoded credentials in
 `$HOME/.docker/config.json` on Linux or `%USERPROFILE%/.docker/config.json` on Windows.
 
-## Credentials store
+### Credentials store
 
 The Docker Engine can keep user credentials in an external credentials store,
 such as the native keychain of the operating system. Using an external store
@@ -60,8 +68,6 @@
 - Apple macOS keychain: https://github.com/docker/docker-credential-helpers/releases
 - Microsoft Windows Credential Manager: https://github.com/docker/docker-credential-helpers/releases
 
-### Usage
-
 You need to specify the credentials store in `$HOME/.docker/config.json`
 to tell the docker engine to use it:
 
@@ -74,7 +80,7 @@
 If you are currently logged in, run `docker logout` to remove
 the credentials from the file and run `docker login` again.
 
-### Protocol
+### Credential helper protocol
 
 Credential helpers can be any program or script that follows a very simple protocol.
 This protocol is heavily inspired by Git, but it differs in the information shared.
@@ -120,3 +126,31 @@
 
 The `erase` command can write error messages to `STDOUT` that the docker engine
 will show if there was an issue.
+
+### Credential helpers
+
+Credential helpers are similar to the credential store above, but act as the
+designated programs to handle credentials for *specific registries*. The default
+credential store (`credsStore` or the config file itself) will not be used for
+operations concerning credentials of the specified registries.
+
+### Logging out
+
+If you are currently logged in, run `docker logout` to remove
+the credentials from the default store.
+
+Credential helpers are specified in a similar way to `credsStore`, but
+allow for multiple helpers to be configured at a time. Keys specify the
+registry domain, and values specify the suffix of the program to use
+(i.e. everything after `docker-credential-`).
+For example:
+
+```json
+{
+  "credHelpers": {
+    "registry.example.com": "registryhelper",
+    "awesomereg.example.org": "hip-star",
+    "unicorn.example.io": "vcbait"
+  }
+}
+```
diff --git a/docs/reference/commandline/logout.md b/docs/reference/commandline/logout.md
index 1635e22..1e150eb 100644
--- a/docs/reference/commandline/logout.md
+++ b/docs/reference/commandline/logout.md
@@ -25,6 +25,8 @@
       --help   Print usage
 ```
 
-For example:
+## Examples
 
-    $ docker logout localhost:8080
+```bash
+$ docker logout localhost:8080
+```
diff --git a/docs/reference/commandline/logs.md b/docs/reference/commandline/logs.md
index 891e10b..a2d71bf 100644
--- a/docs/reference/commandline/logs.md
+++ b/docs/reference/commandline/logs.md
@@ -29,6 +29,8 @@
   -t, --timestamps     Show timestamps
 ```
 
+## Description
+
 The `docker logs` command batch-retrieves logs present at the time of execution.
 
 > **Note**: this command is only functional for containers that are started with
diff --git a/docs/reference/commandline/menu.md b/docs/reference/commandline/menu.md
deleted file mode 100644
index d58afac..0000000
--- a/docs/reference/commandline/menu.md
+++ /dev/null
@@ -1,28 +0,0 @@
----
-title: "Command line reference"
-description: "Docker's CLI command description and usage"
-keywords: "Docker, Docker documentation, CLI, command line"
-identifier:  "smn_cli"
----
-
-<!-- This file is maintained within the docker/docker Github
-     repository at https://github.com/docker/docker/. Make all
-     pull requests against that repo. If you see this file in
-     another repository, consider it read-only there, as it will
-     periodically be overwritten by the definitive file. Pull
-     requests which include edits to this file in other repositories
-     will be rejected.
--->
-
-# The Docker commands
-
-This section contains reference information on using Docker's command line
-client. Each command has a reference page along with samples. If you are
-unfamiliar with the command line, you should start by reading about how to
-[Use the Docker command line](cli.md).
-
-You start the Docker daemon with the command line. How you start the daemon
-affects your Docker containers. For that reason you should also make sure to
-read the [`dockerd`](dockerd.md) reference page.
-
-For a list of Docker commands see [Command line reference guide](index.md).
diff --git a/docs/reference/commandline/network_connect.md b/docs/reference/commandline/network_connect.md
index 52459a5..7c5a586 100644
--- a/docs/reference/commandline/network_connect.md
+++ b/docs/reference/commandline/network_connect.md
@@ -29,38 +29,55 @@
       --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 @@
 
 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)
diff --git a/docs/reference/commandline/network_create.md b/docs/reference/commandline/network_create.md
index e238217..4540d53 100644
--- a/docs/reference/commandline/network_create.md
+++ b/docs/reference/commandline/network_create.md
@@ -38,6 +38,8 @@
                              network segment (default [])
 ```
 
+## Description
+
 Creates a new network. The `DRIVER` accepts `bridge` or `overlay` which are the
 built-in network drivers. If you have installed a third party or your own custom
 network driver you can specify that `DRIVER` here also. If you don't specify the
@@ -86,7 +88,9 @@
 conflicts but this is not guaranteed. It is the user's responsibility to avoid
 name conflicts.
 
-## Connect containers
+## Examples
+
+### Connect containers
 
 When you start a container, use the `--network` flag to connect it to a network.
 This example adds the `busybox` container to the `mynet` network:
@@ -107,7 +111,7 @@
 You can disconnect a container from a network using the `docker network
 disconnect` command.
 
-## Specifying advanced options
+### Specify advanced options
 
 When you create a network, Engine creates a non-overlapping subnetwork for the
 network by default. This subnetwork is not a subdivision of an existing
@@ -150,7 +154,7 @@
 Be sure that your subnetworks do not overlap. If they do, the network create
 fails and Engine returns an error.
 
-# Bridge driver options
+### Bridge driver options
 
 When creating a custom network, the default network driver (i.e. `bridge`) has
 additional options that can be passed. The following are those options and the
@@ -191,7 +195,7 @@
 to create an externally isolated `overlay` network, you can specify the
 `--internal` option.
 
-## Related information
+## Related commands
 
 * [network inspect](network_inspect.md)
 * [network connect](network_connect.md)
diff --git a/docs/reference/commandline/network_disconnect.md b/docs/reference/commandline/network_disconnect.md
index 42e976a..e855894 100644
--- a/docs/reference/commandline/network_disconnect.md
+++ b/docs/reference/commandline/network_disconnect.md
@@ -25,14 +25,19 @@
       --help    Print usage
 ```
 
-Disconnects a container from a network. The container must be running to disconnect it from the network.
+## Description
+
+Disconnects a container from a network. The container must be running to
+disconnect it from the network.
+
+## Examples
 
 ```bash
   $ docker network disconnect multi-host-network container1
 ```
 
 
-## Related information
+## Related commands
 
 * [network inspect](network_inspect.md)
 * [network connect](network_connect.md)
diff --git a/docs/reference/commandline/network_inspect.md b/docs/reference/commandline/network_inspect.md
index bc0005e..2b4c423 100644
--- a/docs/reference/commandline/network_inspect.md
+++ b/docs/reference/commandline/network_inspect.md
@@ -25,7 +25,16 @@
       --help            Print usage
 ```
 
-Returns information about one or more networks. By default, this command renders all results in a JSON object. For example, if you connect two containers to the default `bridge` network:
+## Description
+
+Returns information about one or more networks. By default, this command renders
+all results in a JSON object.
+
+## Examples
+
+## Inspect the `bridge` network
+
+Connect two containers to the default `bridge` network:
 
 ```bash
 $ sudo docker run -itd --name=container1 busybox
@@ -47,8 +56,9 @@
 [text/template](http://golang.org/pkg/text/template/) package describes all the
 details of the format.
 
-```bash
+```none
 $ sudo docker network inspect bridge
+
 [
     {
         "Name": "bridge",
@@ -95,12 +105,19 @@
 ]
 ```
 
-Returns the information about the user-defined network:
+### Inspect a user-defined network
+
+Create and inspect a user-defined network:
 
 ```bash
 $ docker network create simple-network
+
 69568e6336d8c96bbf57869030919f7c69524f71183b44d80948bd3927c87f6a
+```
+
+```none
 $ docker network inspect simple-network
+
 [
     {
         "Name": "simple-network",
@@ -124,12 +141,15 @@
 ]
 ```
 
-For swarm mode overlay networks `network inspect` also shows the IP address and node name 
-of the peers. Peers are the nodes in the swarm cluster which have at least one task attached 
+### Inspect the `ingress` network
+
+For swarm mode overlay networks `network inspect` also shows the IP address and node name
+of the peers. Peers are the nodes in the swarm cluster which have at least one task attached
 to the network. Node name is of the format `<hostname>-<unique ID>`.
 
-```bash
+```none
 $ docker network inspect ingress
+
 [
     {
         "Name": "ingress",
@@ -181,7 +201,7 @@
 ]
 ```
 
-## Related information
+## Related commands
 
 * [network disconnect ](network_disconnect.md)
 * [network connect](network_connect.md)
diff --git a/docs/reference/commandline/network_ls.md b/docs/reference/commandline/network_ls.md
index a4f671d..446fc4a 100644
--- a/docs/reference/commandline/network_ls.md
+++ b/docs/reference/commandline/network_ls.md
@@ -31,8 +31,14 @@
   -q, --quiet           Only display network IDs
 ```
 
+## Description
+
 Lists all the networks the Engine `daemon` knows about. This includes the
-networks that span across multiple hosts in a cluster, for example:
+networks that span across multiple hosts in a cluster.
+
+## Examples
+
+### List all networks
 
 ```bash
 $ sudo docker network ls
@@ -55,7 +61,7 @@
 63d1ff1f77b07ca51070a8c227e962238358bd310bde1529cf62e6c307ade161   dev                 bridge           local
 ```
 
-## Filtering
+### Filtering
 
 The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there
 is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`).
@@ -175,7 +181,7 @@
 A warning will be issued when trying to remove a network that has containers
 attached.
 
-## Formatting
+### Formatting
 
 The formatting options (`--format`) pretty-prints networks output
 using a Go template.
@@ -207,7 +213,7 @@
 391df270dc66: null
 ```
 
-## Related information
+## Related commands
 
 * [network disconnect ](network_disconnect.md)
 * [network connect](network_connect.md)
diff --git a/docs/reference/commandline/network_prune.md b/docs/reference/commandline/network_prune.md
index 5b65465..e57741d 100644
--- a/docs/reference/commandline/network_prune.md
+++ b/docs/reference/commandline/network_prune.md
@@ -16,12 +16,16 @@
       --help    Print usage
 ```
 
-Remove all unused networks. Unused networks are those which are not referenced by any containers.
+## Description
 
-Example output:
+Remove all unused networks. Unused networks are those which are not referenced
+by any containers.
+
+## Examples
 
 ```bash
 $ docker network prune
+
 WARNING! This will remove all networks not used by at least one container.
 Are you sure you want to continue? [y/N] y
 Deleted Networks:
@@ -29,7 +33,7 @@
 n2
 ```
 
-## Related information
+## Related commands
 
 * [network disconnect ](network_disconnect.md)
 * [network connect](network_connect.md)
diff --git a/docs/reference/commandline/network_rm.md b/docs/reference/commandline/network_rm.md
index f06b4c0..aab487a 100644
--- a/docs/reference/commandline/network_rm.md
+++ b/docs/reference/commandline/network_rm.md
@@ -27,14 +27,23 @@
       --help   Print usage
 ```
 
+## Description
+
 Removes one or more networks by name or identifier. To remove a network,
 you must first disconnect any containers connected to it.
+
+## Examples
+
+### Remove a network
+
 To remove the network named 'my-network':
 
 ```bash
   $ docker network rm my-network
 ```
 
+### Remove multiple networks
+
 To delete multiple networks in a single `docker network rm` command, provide
 multiple network names or ids. The following example deletes a network with id
 `3695c422697f` and a network named `my-network`:
@@ -48,7 +57,7 @@
 list and tries to delete that. The command reports success or failure for each
 deletion.
 
-## Related information
+## Related commands
 
 * [network disconnect ](network_disconnect.md)
 * [network connect](network_connect.md)
diff --git a/docs/reference/commandline/node_demote.md b/docs/reference/commandline/node_demote.md
index 9a81bb9..e6e59d8 100644
--- a/docs/reference/commandline/node_demote.md
+++ b/docs/reference/commandline/node_demote.md
@@ -25,14 +25,19 @@
 
 ```
 
-Demotes an existing manager so that it is no longer a manager. This command targets a docker engine that is a manager in the swarm.
+## Description
 
+Demotes an existing manager so that it is no longer a manager. This command
+targets a docker engine that is a manager in the swarm.
+
+
+## Examples
 
 ```bash
 $ docker node demote <node name>
 ```
 
-## Related information
+## Related commands
 
 * [node inspect](node_inspect.md)
 * [node ls](node_ls.md)
diff --git a/docs/reference/commandline/node_inspect.md b/docs/reference/commandline/node_inspect.md
index fac688f..b958e3d 100644
--- a/docs/reference/commandline/node_inspect.md
+++ b/docs/reference/commandline/node_inspect.md
@@ -26,108 +26,118 @@
       --pretty          Print the information in a human friendly format.
 ```
 
+## Description
+
 Returns information about a node. By default, this command renders all results
 in a JSON array. You can specify an alternate format to execute a
 given template for each result. Go's
 [text/template](http://golang.org/pkg/text/template/) package describes all the
 details of the format.
 
-Example output:
+## Examples
 
-    $ docker node inspect swarm-manager
-    [
-    {
-        "ID": "e216jshn25ckzbvmwlnh5jr3g",
-        "Version": {
-            "Index": 10
+### Inspect a node
+
+```none
+$ docker node inspect swarm-manager
+
+[
+{
+    "ID": "e216jshn25ckzbvmwlnh5jr3g",
+    "Version": {
+        "Index": 10
+    },
+    "CreatedAt": "2016-06-16T22:52:44.9910662Z",
+    "UpdatedAt": "2016-06-16T22:52:45.230878043Z",
+    "Spec": {
+        "Role": "manager",
+        "Availability": "active"
+    },
+    "Description": {
+        "Hostname": "swarm-manager",
+        "Platform": {
+            "Architecture": "x86_64",
+            "OS": "linux"
         },
-        "CreatedAt": "2016-06-16T22:52:44.9910662Z",
-        "UpdatedAt": "2016-06-16T22:52:45.230878043Z",
-        "Spec": {
-            "Role": "manager",
-            "Availability": "active"
+        "Resources": {
+            "NanoCPUs": 1000000000,
+            "MemoryBytes": 1039843328
         },
-        "Description": {
-            "Hostname": "swarm-manager",
-            "Platform": {
-                "Architecture": "x86_64",
-                "OS": "linux"
-            },
-            "Resources": {
-                "NanoCPUs": 1000000000,
-                "MemoryBytes": 1039843328
-            },
-            "Engine": {
-                "EngineVersion": "1.12.0",
-                "Plugins": [
-                    {
-                        "Type": "Volume",
-                        "Name": "local"
-                    },
-                    {
-                        "Type": "Network",
-                        "Name": "overlay"
-                    },
-                    {
-                        "Type": "Network",
-                        "Name": "null"
-                    },
-                    {
-                        "Type": "Network",
-                        "Name": "host"
-                    },
-                    {
-                        "Type": "Network",
-                        "Name": "bridge"
-                    },
-                    {
-                        "Type": "Network",
-                        "Name": "overlay"
-                    }
-                ]
-            }
-        },
-        "Status": {
-            "State": "ready",
-            "Addr": "168.0.32.137"
-        },
-        "ManagerStatus": {
-            "Leader": true,
-            "Reachability": "reachable",
-            "Addr": "168.0.32.137:2377"
+        "Engine": {
+            "EngineVersion": "1.12.0",
+            "Plugins": [
+                {
+                    "Type": "Volume",
+                    "Name": "local"
+                },
+                {
+                    "Type": "Network",
+                    "Name": "overlay"
+                },
+                {
+                    "Type": "Network",
+                    "Name": "null"
+                },
+                {
+                    "Type": "Network",
+                    "Name": "host"
+                },
+                {
+                    "Type": "Network",
+                    "Name": "bridge"
+                },
+                {
+                    "Type": "Network",
+                    "Name": "overlay"
+                }
+            ]
         }
+    },
+    "Status": {
+        "State": "ready",
+        "Addr": "168.0.32.137"
+    },
+    "ManagerStatus": {
+        "Leader": true,
+        "Reachability": "reachable",
+        "Addr": "168.0.32.137:2377"
     }
-    ]
+}
+]
+```
 
-    {% raw %}
-    $ docker node inspect --format '{{ .ManagerStatus.Leader }}' self
-    false
-    {% endraw %}
+### Specify an output format
 
-    $ docker node inspect --pretty self
-    ID:                     e216jshn25ckzbvmwlnh5jr3g
-    Hostname:               swarm-manager
-    Joined at:              2016-06-16 22:52:44.9910662 +0000 utc
-    Status:
-     State:                 Ready
-     Availability:          Active
-     Address:               172.17.0.2
-    Manager Status:
-     Address:               172.17.0.2:2377
-     Raft Status:           Reachable
-     Leader:                Yes
-    Platform:
-     Operating System:      linux
-     Architecture:          x86_64
-    Resources:
-     CPUs:                  4
-     Memory:                7.704 GiB
-    Plugins:
-      Network:              overlay, bridge, null, host, overlay
-      Volume:               local
-    Engine Version:         1.12.0
+```none
+$ docker node inspect --format '{{ .ManagerStatus.Leader }}' self
 
-## Related information
+false
+
+$ docker node inspect --pretty self
+ID:                     e216jshn25ckzbvmwlnh5jr3g
+Hostname:               swarm-manager
+Joined at:              2016-06-16 22:52:44.9910662 +0000 utc
+Status:
+ State:                 Ready
+ Availability:          Active
+ Address:               172.17.0.2
+Manager Status:
+ Address:               172.17.0.2:2377
+ Raft Status:           Reachable
+ Leader:                Yes
+Platform:
+ Operating System:      linux
+ Architecture:          x86_64
+Resources:
+ CPUs:                  4
+ Memory:                7.704 GiB
+Plugins:
+  Network:              overlay, bridge, null, host, overlay
+  Volume:               local
+Engine Version:         1.12.0
+```
+
+## Related commands
 
 * [node demote](node_demote.md)
 * [node ls](node_ls.md)
diff --git a/docs/reference/commandline/node_ls.md b/docs/reference/commandline/node_ls.md
index 5f61713..836fcea 100644
--- a/docs/reference/commandline/node_ls.md
+++ b/docs/reference/commandline/node_ls.md
@@ -29,9 +29,13 @@
   -q, --quiet          Only display IDs
 ```
 
-Lists all the nodes that the Docker Swarm manager knows about. You can filter using the `-f` or `--filter` flag. Refer to the [filtering](#filtering) section for more information about available filter options.
+## Description
 
-Example output:
+Lists all the nodes that the Docker Swarm manager knows about. You can filter
+using the `-f` or `--filter` flag. Refer to the [filtering](#filtering) section
+for more information about available filter options.
+
+## Examples
 
 ```bash
 $ docker node ls
@@ -42,7 +46,7 @@
 e216jshn25ckzbvmwlnh5jr3g *  swarm-manager1  Ready   Active        Leader
 ```
 
-## Filtering
+### Filtering
 
 The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more
 than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`)
@@ -55,7 +59,7 @@
 * [name](node_ls.md#name)
 * [role](node_ls.md#role)
 
-#### ID
+#### id
 
 The `id` filter matches all or part of a node's id.
 
@@ -66,7 +70,7 @@
 1bcef6utixb0l0ca7gxuivsj0  swarm-worker2  Ready   Active
 ```
 
-#### Label
+#### label
 
 The `label` filter matches nodes based on engine labels and on the presence of a `label` alone or a `label` and a value. Node labels are currently not used for filtering.
 
@@ -79,7 +83,7 @@
 1bcef6utixb0l0ca7gxuivsj0  swarm-worker2  Ready   Active
 ```
 
-#### Membership
+#### membersip
 
 The `membership` filter matches nodes based on the presence of a `membership` and a value
 `accepted` or `pending`.
@@ -94,7 +98,7 @@
 38ciaotwjuritcdtn9npbnkuz    swarm-worker1   Ready   Active
 ```
 
-#### Name
+#### name
 
 The `name` filter matches on all or part of a node hostname.
 
@@ -107,7 +111,7 @@
 e216jshn25ckzbvmwlnh5jr3g *  swarm-manager1  Ready   Active        Leader
 ```
 
-#### Role
+#### role
 
 The `role` filter matches nodes based on the presence of a `role` and a value `worker` or `manager`.
 
@@ -120,7 +124,7 @@
 e216jshn25ckzbvmwlnh5jr3g *  swarm-manager1  Ready   Active        Leader
 ```
 
-## Related information
+## Related commands
 
 * [node demote](node_demote.md)
 * [node inspect](node_inspect.md)
diff --git a/docs/reference/commandline/node_promote.md b/docs/reference/commandline/node_promote.md
index 92092a8..1ebbe95 100644
--- a/docs/reference/commandline/node_promote.md
+++ b/docs/reference/commandline/node_promote.md
@@ -24,14 +24,18 @@
       --help   Print usage
 ```
 
-Promotes a node to manager. This command targets a docker engine that is a manager in the swarm.
+## Description
 
+Promotes a node to manager. This command targets a docker engine that is a
+manager in the swarm.
+
+## Examples
 
 ```bash
 $ docker node promote <node name>
 ```
 
-## Related information
+## Related commands
 
 * [node demote](node_demote.md)
 * [node inspect](node_inspect.md)
diff --git a/docs/reference/commandline/node_ps.md b/docs/reference/commandline/node_ps.md
index 7f07c5e..e2e1418 100644
--- a/docs/reference/commandline/node_ps.md
+++ b/docs/reference/commandline/node_ps.md
@@ -28,20 +28,23 @@
       --no-trunc       Do not truncate output
 ```
 
+## Description
+
 Lists all the tasks on a Node that Docker knows about. You can filter using the `-f` or `--filter` flag. Refer to the [filtering](#filtering) section for more information about available filter options.
 
-Example output:
+## Examples
 
-    $ docker node ps swarm-manager1
-    NAME                                IMAGE        NODE            DESIRED STATE  CURRENT STATE
-    redis.1.7q92v0nr1hcgts2amcjyqg3pq   redis:3.0.6  swarm-manager1  Running        Running 5 hours
-    redis.6.b465edgho06e318egmgjbqo4o   redis:3.0.6  swarm-manager1  Running        Running 29 seconds
-    redis.7.bg8c07zzg87di2mufeq51a2qp   redis:3.0.6  swarm-manager1  Running        Running 5 seconds
-    redis.9.dkkual96p4bb3s6b10r7coxxt   redis:3.0.6  swarm-manager1  Running        Running 5 seconds
-    redis.10.0tgctg8h8cech4w0k0gwrmr23  redis:3.0.6  swarm-manager1  Running        Running 5 seconds
+```bash
+$ docker node ps swarm-manager1
+NAME                                IMAGE        NODE            DESIRED STATE  CURRENT STATE
+redis.1.7q92v0nr1hcgts2amcjyqg3pq   redis:3.0.6  swarm-manager1  Running        Running 5 hours
+redis.6.b465edgho06e318egmgjbqo4o   redis:3.0.6  swarm-manager1  Running        Running 29 seconds
+redis.7.bg8c07zzg87di2mufeq51a2qp   redis:3.0.6  swarm-manager1  Running        Running 5 seconds
+redis.9.dkkual96p4bb3s6b10r7coxxt   redis:3.0.6  swarm-manager1  Running        Running 5 seconds
+redis.10.0tgctg8h8cech4w0k0gwrmr23  redis:3.0.6  swarm-manager1  Running        Running 5 seconds
+```
 
-
-## Filtering
+### Filtering
 
 The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more
 than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`)
@@ -59,23 +62,27 @@
 
 The following filter matches all tasks with a name containing the `redis` string.
 
-    $ docker node ps -f name=redis swarm-manager1
-    NAME                                IMAGE        NODE            DESIRED STATE  CURRENT STATE
-    redis.1.7q92v0nr1hcgts2amcjyqg3pq   redis:3.0.6  swarm-manager1  Running        Running 5 hours
-    redis.6.b465edgho06e318egmgjbqo4o   redis:3.0.6  swarm-manager1  Running        Running 29 seconds
-    redis.7.bg8c07zzg87di2mufeq51a2qp   redis:3.0.6  swarm-manager1  Running        Running 5 seconds
-    redis.9.dkkual96p4bb3s6b10r7coxxt   redis:3.0.6  swarm-manager1  Running        Running 5 seconds
-    redis.10.0tgctg8h8cech4w0k0gwrmr23  redis:3.0.6  swarm-manager1  Running        Running 5 seconds
+```bash
+$ docker node ps -f name=redis swarm-manager1
 
+NAME                                IMAGE        NODE            DESIRED STATE  CURRENT STATE
+redis.1.7q92v0nr1hcgts2amcjyqg3pq   redis:3.0.6  swarm-manager1  Running        Running 5 hours
+redis.6.b465edgho06e318egmgjbqo4o   redis:3.0.6  swarm-manager1  Running        Running 29 seconds
+redis.7.bg8c07zzg87di2mufeq51a2qp   redis:3.0.6  swarm-manager1  Running        Running 5 seconds
+redis.9.dkkual96p4bb3s6b10r7coxxt   redis:3.0.6  swarm-manager1  Running        Running 5 seconds
+redis.10.0tgctg8h8cech4w0k0gwrmr23  redis:3.0.6  swarm-manager1  Running        Running 5 seconds
+```
 
 #### id
 
 The `id` filter matches a task's id.
 
-    $ docker node ps -f id=bg8c07zzg87di2mufeq51a2qp swarm-manager1
-    NAME                                IMAGE        NODE            DESIRED STATE  CURRENT STATE
-    redis.7.bg8c07zzg87di2mufeq51a2qp   redis:3.0.6  swarm-manager1  Running        Running 5 seconds
+```bash
+$ docker node ps -f id=bg8c07zzg87di2mufeq51a2qp swarm-manager1
 
+NAME                                IMAGE        NODE            DESIRED STATE  CURRENT STATE
+redis.7.bg8c07zzg87di2mufeq51a2qp   redis:3.0.6  swarm-manager1  Running        Running 5 seconds
+```
 
 #### label
 
@@ -86,6 +93,7 @@
 
 ```bash
 $ docker node ps -f "label=usage"
+
 NAME                               IMAGE        NODE            DESIRED STATE  CURRENT STATE
 redis.6.b465edgho06e318egmgjbqo4o  redis:3.0.6  swarm-manager1  Running        Running 10 minutes
 redis.7.bg8c07zzg87di2mufeq51a2qp  redis:3.0.6  swarm-manager1  Running        Running 9 minutes
@@ -97,7 +105,7 @@
 The `desired-state` filter can take the values `running`, `shutdown`, and `accepted`.
 
 
-## Related information
+## Related commands
 
 * [node demote](node_demote.md)
 * [node inspect](node_inspect.md)
diff --git a/docs/reference/commandline/node_rm.md b/docs/reference/commandline/node_rm.md
index b245d63..c2fdd4d 100644
--- a/docs/reference/commandline/node_rm.md
+++ b/docs/reference/commandline/node_rm.md
@@ -28,33 +28,40 @@
       --help    Print usage
 ```
 
+## Description
+
 When run from a manager node, removes the specified nodes from a swarm.
 
 
-Example output:
+## Examples
 
-```nohighlight
+### Remove a stopped node from the swarm
+
+```bash
 $ docker node rm swarm-node-02
 
 Node swarm-node-02 removed from swarm
 ```
+### Attempt to remove a running node from a swarm
 
 Removes the specified nodes from the swarm, but only if the nodes are in the
 down state. If you attempt to remove an active node you will receive an error:
 
-```nohighlight
+```non
 $ docker node rm swarm-node-03
 
 Error response from daemon: rpc error: code = 9 desc = node swarm-node-03 is not
 down and can't be removed
 ```
 
+### Forcibly remove an inaccessible node from a swarm
+
 If you lose access to a worker node or need to shut it down because it has been
 compromised or is not behaving as expected, you can use the `--force` option.
 This may cause transient errors or interruptions, depending on the type of task
 being run on the node.
 
-```nohighlight
+```bash
 $ docker node rm --force swarm-node-03
 
 Node swarm-node-03 removed from swarm
@@ -63,7 +70,7 @@
 A manager node must be demoted to a worker node (using `docker node demote`)
 before you can remove it from the swarm.
 
-## Related information
+## Related commands
 
 * [node demote](node_demote.md)
 * [node inspect](node_inspect.md)
diff --git a/docs/reference/commandline/node_update.md b/docs/reference/commandline/node_update.md
index aa65d03..ba824c9 100644
--- a/docs/reference/commandline/node_update.md
+++ b/docs/reference/commandline/node_update.md
@@ -13,7 +13,7 @@
      will be rejected.
 -->
 
-## update
+# update
 
 ```markdown
 Usage:  docker node update [OPTIONS] NODE
@@ -28,6 +28,12 @@
       --role string           Role of the node (worker/manager)
 ```
 
+## Description
+
+Update metadata about a node, such as its availability, labels, or roles.
+
+## Examples
+
 ### Add label metadata to a node
 
 Add metadata to a swarm node using node labels. You can specify a node label as
@@ -39,7 +45,7 @@
 
 To add multiple labels to a node, pass the `--label-add` flag for each label:
 
-``` bash
+```bash
 $ docker node update --label-add foo --label-add bar worker1
 ```
 
@@ -61,7 +67,7 @@
 For more information about labels, refer to [apply custom
 metadata](https://docs.docker.com/engine/userguide/labels-custom-metadata/).
 
-## Related information
+## Related commands
 
 * [node demote](node_demote.md)
 * [node inspect](node_inspect.md)
diff --git a/docs/reference/commandline/pause.md b/docs/reference/commandline/pause.md
index e2dd800..5bb652b 100644
--- a/docs/reference/commandline/pause.md
+++ b/docs/reference/commandline/pause.md
@@ -24,6 +24,8 @@
       --help   Print usage
 ```
 
+## Description
+
 The `docker pause` command suspends all processes in the specified containers.
 On Linux, this uses the cgroups freezer. Traditionally, when suspending a process
 the `SIGSTOP` signal is used, which is observable by the process being suspended.
@@ -35,6 +37,12 @@
 [cgroups freezer documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt)
 for further details.
 
-## Related information
+## Examples
+
+```bash
+$ docker pause my_container
+```
+
+## Related commands
 
 * [unpause](unpause.md)
diff --git a/docs/reference/commandline/plugin_create.md b/docs/reference/commandline/plugin_create.md
index 9d4e99e..6f17543 100644
--- a/docs/reference/commandline/plugin_create.md
+++ b/docs/reference/commandline/plugin_create.md
@@ -21,33 +21,38 @@
 Create a plugin from a rootfs and configuration. Plugin data directory must contain config.json and rootfs directory.
 
 Options:
-      --compress   Compress the context using gzip 
+      --compress   Compress the context using gzip
       --help       Print usage
 ```
 
+## Description
+
 Creates a plugin. Before creating the plugin, prepare the plugin's root filesystem as well as
 [the config.json](../../extend/config.md)
 
+## Examples
 
 The following example shows how to create a sample `plugin`.
 
 ```bash
-
 $ ls -ls /home/pluginDir
 
 4 -rw-r--r--  1 root root 431 Nov  7 01:40 config.json
 0 drwxr-xr-x 19 root root 420 Nov  7 01:40 rootfs
 
 $ docker plugin create plugin /home/pluginDir
+
 plugin
 
-NAME                  	TAG                 DESCRIPTION                  ENABLED
-plugin                  latest              A sample plugin for Docker   true
+$ docker plugin ls
+
+ID                  NAME                TAG                 DESCRIPTION                  ENABLED
+672d8144ec02        plugin              latest              A sample plugin for Docker   false
 ```
 
 The plugin can subsequently be enabled for local use or pushed to the public registry.
 
-## Related information
+## Related commands
 
 * [plugin disable](plugin_disable.md)
 * [plugin enable](plugin_enable.md)
diff --git a/docs/reference/commandline/plugin_disable.md b/docs/reference/commandline/plugin_disable.md
index 451f1ac..2ff8188 100644
--- a/docs/reference/commandline/plugin_disable.md
+++ b/docs/reference/commandline/plugin_disable.md
@@ -25,10 +25,13 @@
       --help    Print usage
 ```
 
+## Description
+
 Disables a plugin. The plugin must be installed before it can be disabled,
 see [`docker plugin install`](plugin_install.md). Without the `-f` option,
 a plugin that has references (eg, volumes, networks) cannot be disabled.
 
+## Examples
 
 The following example shows that the `sample-volume-plugin` plugin is installed
 and enabled:
@@ -53,7 +56,7 @@
 69553ca1d123        tiborvass/sample-volume-plugin   latest              A test plugin for Docker   false
 ```
 
-## Related information
+## Related commands
 
 * [plugin create](plugin_create.md)
 * [plugin enable](plugin_enable.md)
diff --git a/docs/reference/commandline/plugin_enable.md b/docs/reference/commandline/plugin_enable.md
index df8bee3..2098a11 100644
--- a/docs/reference/commandline/plugin_enable.md
+++ b/docs/reference/commandline/plugin_enable.md
@@ -25,9 +25,12 @@
       --timeout int   HTTP client timeout (in seconds)
 ```
 
+## Description
+
 Enables a plugin. The plugin must be installed before it can be enabled,
 see [`docker plugin install`](plugin_install.md).
 
+## Examples
 
 The following example shows that the `sample-volume-plugin` plugin is installed,
 but disabled:
@@ -52,7 +55,7 @@
 69553ca1d123        tiborvass/sample-volume-plugin   latest              A test plugin for Docker   true
 ```
 
-## Related information
+## Related commands
 
 * [plugin create](plugin_create.md)
 * [plugin disable](plugin_disable.md)
diff --git a/docs/reference/commandline/plugin_inspect.md b/docs/reference/commandline/plugin_inspect.md
index fdcc030..c0e6573 100644
--- a/docs/reference/commandline/plugin_inspect.md
+++ b/docs/reference/commandline/plugin_inspect.md
@@ -25,15 +25,17 @@
       --help            Print usage
 ```
 
+## Description
+
 Returns information about a plugin. By default, this command renders all results
 in a JSON array.
 
-Example output:
+## Examples
 
-```bash
+
+```none
 $ docker plugin inspect tiborvass/sample-volume-plugin:latest
-```
-```JSON
+
 {
   "Id": "8c74c978c434745c3ade82f1bc0acf38d04990eaf494fa507c16d9f1daa99c21",
   "Name": "tiborvass/sample-volume-plugin:latest",
@@ -140,18 +142,19 @@
   }
 }
 ```
+
 (output formatted for readability)
 
+### Formatting the output
 
 ```bash
 $ docker plugin inspect -f '{{.Id}}' tiborvass/sample-volume-plugin:latest
-```
-```
+
 8c74c978c434745c3ade82f1bc0acf38d04990eaf494fa507c16d9f1daa99c21
 ```
 
 
-## Related information
+## Related commands
 
 * [plugin create](plugin_create.md)
 * [plugin enable](plugin_enable.md)
diff --git a/docs/reference/commandline/plugin_install.md b/docs/reference/commandline/plugin_install.md
index 0601193..f7ad36d 100644
--- a/docs/reference/commandline/plugin_install.md
+++ b/docs/reference/commandline/plugin_install.md
@@ -27,16 +27,19 @@
       --help                    Print usage
 ```
 
+## Description
+
 Installs and enables a plugin. Docker looks first for the plugin on your Docker
 host. If the plugin does not exist locally, then the plugin is pulled from
 the registry. Note that the minimum required registry version to distribute
 plugins is 2.3.0
 
+## Examples
 
-The following example installs `vieus/sshfs` plugin and [set](plugin_set.md) it's env variable
-`DEBUG` to 1. Install consists of pulling the plugin from Docker Hub, prompting
-the user to accept the list of privileges that the plugin needs, settings parameters
- and enabling the plugin.
+The following example installs `vieus/sshfs` plugin and [sets](plugin_set.md) its
+`DEBUG` environment variable to `1`. To install, `pull` the plugin from Docker
+Hub and prompt the user to accept the list of privileges that the plugin needs,
+set the plugin's parameters and enable the plugin.
 
 ```bash
 $ docker plugin install vieux/sshfs DEBUG=1
@@ -58,7 +61,7 @@
 69553ca1d123        vieux/sshfs           latest              sshFS plugin for Docker    true
 ```
 
-## Related information
+## Related commands
 
 * [plugin create](plugin_create.md)
 * [plugin disable](plugin_disable.md)
diff --git a/docs/reference/commandline/plugin_ls.md b/docs/reference/commandline/plugin_ls.md
index 7a3426d..64661de 100644
--- a/docs/reference/commandline/plugin_ls.md
+++ b/docs/reference/commandline/plugin_ls.md
@@ -28,10 +28,12 @@
       --no-trunc   Don't truncate output
 ```
 
+## Description
+
 Lists all the plugins that are currently installed. You can install plugins
 using the [`docker plugin install`](plugin_install.md) command.
 
-Example output:
+## Examples
 
 ```bash
 $ docker plugin ls
@@ -40,7 +42,7 @@
 69553ca1d123        tiborvass/sample-volume-plugin   latest              A test plugin for Docker   true
 ```
 
-## Related information
+## Related commands
 
 * [plugin create](plugin_create.md)
 * [plugin disable](plugin_disable.md)
diff --git a/docs/reference/commandline/plugin_push.md b/docs/reference/commandline/plugin_push.md
index e61d109..905fa82 100644
--- a/docs/reference/commandline/plugin_push.md
+++ b/docs/reference/commandline/plugin_push.md
@@ -22,22 +22,27 @@
       --help       Print usage
 ```
 
-Use `docker plugin create` to create the plugin. Once the plugin is ready for distribution,
-use `docker plugin push` to share your images to the Docker Hub registry or to a self-hosted one.
+## Description
+
+After you have created a plugin using `docker plugin create` and the plugin is
+ready for distribution, use `docker plugin push` to share your images to Docker
+Hub or a self-hosted registry.
 
 Registry credentials are managed by [docker login](login.md).
 
+## Examples
+
 The following example shows how to push a sample `user/plugin`.
 
 ```bash
-
 $ docker plugin ls
+
 ID                  NAME                  TAG                 DESCRIPTION                ENABLED
 69553ca1d456        user/plugin           latest              A sample plugin for Docker false
 $ docker plugin push user/plugin
 ```
 
-## Related information
+## Related commands
 
 * [plugin create](plugin_create.md)
 * [plugin disable](plugin_disable.md)
diff --git a/docs/reference/commandline/plugin_rm.md b/docs/reference/commandline/plugin_rm.md
index 323ce83..c820c86 100644
--- a/docs/reference/commandline/plugin_rm.md
+++ b/docs/reference/commandline/plugin_rm.md
@@ -28,12 +28,17 @@
           --help   Print usage
 ```
 
+## Description
+
 Removes a plugin. You cannot remove a plugin if it is enabled, you must disable
 a plugin using the [`docker plugin disable`](plugin_disable.md) before removing
 it (or use --force, use of force is not recommended, since it can affect
 functioning of running containers using the plugin).
 
-The following example disables and removes the `sample-volume-plugin:latest` plugin;
+## Examples
+
+The following example disables and removes the `sample-volume-plugin:latest`
+plugin:
 
 ```bash
 $ docker plugin disable tiborvass/sample-volume-plugin
@@ -43,7 +48,7 @@
 tiborvass/sample-volume-plugin
 ```
 
-## Related information
+## Related commands
 
 * [plugin create](plugin_create.md)
 * [plugin disable](plugin_disable.md)
diff --git a/docs/reference/commandline/plugin_set.md b/docs/reference/commandline/plugin_set.md
index c206a8a..4b7ce61 100644
--- a/docs/reference/commandline/plugin_set.md
+++ b/docs/reference/commandline/plugin_set.md
@@ -24,6 +24,8 @@
       --help                    Print usage
 ```
 
+## Description
+
 Change settings for a plugin. The plugin must be disabled.
 
 The settings currently supported are:
@@ -32,11 +34,16 @@
  * path of devices
  * args
 
+## Examples
+
+### Change an environment variable
+
 The following example change the env variable `DEBUG` on the
 `sample-volume-plugin` plugin.
 
 ```bash
 $ docker plugin inspect -f {{.Settings.Env}} tiborvass/sample-volume-plugin
+
 [DEBUG=0]
 
 $ docker plugin set tiborvass/sample-volume-plugin DEBUG=1
@@ -45,6 +52,8 @@
 [DEBUG=1]
 ```
 
+### Change the source of a mount
+
 The following example change the source of the `mymount` mount on
 the `myplugin` plugin.
 
@@ -58,7 +67,10 @@
 /bar
 ```
 
-Note: since only `source` is settable in `mymount`, `docker plugins set mymount=/bar myplugin` would work too.
+> **Note**: Since only `source` is settable in `mymount`,
+> `docker plugins set mymount=/bar myplugin` would work too.
+
+### Change a device path
 
 The following example change the path of the `mydevice` device on
 the `myplugin` plugin.
@@ -73,7 +85,10 @@
 /dev/bar
 ```
 
-Note: since only `path` is settable in `mydevice`, `docker plugins set mydevice=/dev/bar myplugin` would work too.
+> **Note**: Since only `path` is settable in `mydevice`,
+> `docker plugins set mydevice=/dev/bar myplugin` would work too.
+
+### Change the source of the arguments
 
 The following example change the source of the args on the `myplugin` plugin.
 
@@ -87,7 +102,7 @@
 ["foo", "bar", "baz"]
 ```
 
-## Related information
+## Related commands
 
 * [plugin create](plugin_create.md)
 * [plugin disable](plugin_disable.md)
diff --git a/docs/reference/commandline/plugin_upgrade.md b/docs/reference/commandline/plugin_upgrade.md
index 20efc57..38191ff 100644
--- a/docs/reference/commandline/plugin_upgrade.md
+++ b/docs/reference/commandline/plugin_upgrade.md
@@ -27,11 +27,15 @@
       --skip-remote-check       Do not check if specified remote plugin matches existing plugin image
 ```
 
+## Description
+
 Upgrades an existing plugin to the specified remote plugin image. If no remote
 is specified, Docker will re-pull the current image and use the updated version.
 All existing references to the plugin will continue to work.
 The plugin must be disabled before running the upgrade.
 
+## Examples
+
 The following example installs `vieus/sshfs` plugin, uses it to create and use
 a volume, then upgrades the plugin.
 
@@ -71,7 +75,7 @@
 hello
 ```
 
-## Related information
+## Related commands
 
 * [plugin create](plugin_create.md)
 * [plugin disable](plugin_disable.md)
diff --git a/docs/reference/commandline/port.md b/docs/reference/commandline/port.md
index bc90b6e..c38763e 100644
--- a/docs/reference/commandline/port.md
+++ b/docs/reference/commandline/port.md
@@ -24,18 +24,24 @@
       --help   Print usage
 ```
 
+## Examples
+
+### Show all mapped ports
+
 You can find out all the ports mapped by not specifying a `PRIVATE_PORT`, or
 just a specific mapping:
 
-    $ docker ps
-    CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS                                            NAMES
-    b650456536c7        busybox:latest      top                 54 minutes ago      Up 54 minutes       0.0.0.0:1234->9876/tcp, 0.0.0.0:4321->7890/tcp   test
-    $ docker port test
-    7890/tcp -> 0.0.0.0:4321
-    9876/tcp -> 0.0.0.0:1234
-    $ docker port test 7890/tcp
-    0.0.0.0:4321
-    $ docker port test 7890/udp
-    2014/06/24 11:53:36 Error: No public port '7890/udp' published for test
-    $ docker port test 7890
-    0.0.0.0:4321
+```bash
+$ docker ps
+CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS                                            NAMES
+b650456536c7        busybox:latest      top                 54 minutes ago      Up 54 minutes       0.0.0.0:1234->9876/tcp, 0.0.0.0:4321->7890/tcp   test
+$ docker port test
+7890/tcp -> 0.0.0.0:4321
+9876/tcp -> 0.0.0.0:1234
+$ docker port test 7890/tcp
+0.0.0.0:4321
+$ docker port test 7890/udp
+2014/06/24 11:53:36 Error: No public port '7890/udp' published for test
+$ docker port test 7890
+0.0.0.0:4321
+```
diff --git a/docs/reference/commandline/ps.md b/docs/reference/commandline/ps.md
index 164e364..be88f9a 100644
--- a/docs/reference/commandline/ps.md
+++ b/docs/reference/commandline/ps.md
@@ -35,7 +35,7 @@
                         - name=<string> a container's name
                         - network=(<network-id>|<network-name>)
                         - since=(<container-name>|<container-id>)
-                        - status=(created|restarting|removing|running|paused|exited) 
+                        - status=(created|restarting|removing|running|paused|exited)
                         - volume=(<volume name>|<mount point destination>)
       --format string   Pretty-print containers using a Go template
       --help            Print usage
@@ -46,6 +46,10 @@
   -s, --size            Display total file sizes
 ```
 
+## Examples
+
+### Prevent truncating output
+
 Running `docker ps --no-trunc` showing 2 linked containers.
 
 ```bash
@@ -56,6 +60,8 @@
 d7886598dbe2        crosbymichael/redis:latest   /redis-server --dir    33 minutes ago       Up 33 minutes       6379/tcp            redis,webapp/db
 ```
 
+### Show both running and stopped containers
+
 The `docker ps` command only shows running containers by default. To see all
 containers, use the `-a` (or `--all`) flag:
 
@@ -67,7 +73,7 @@
 container that exposes TCP ports `100, 101, 102` displays `100-102/tcp` in
 the `PORTS` column.
 
-## Filtering
+### Filtering
 
 The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more
 than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`)
@@ -87,7 +93,7 @@
 * network (network id or name) - filters containers connected to the provided network
 * health (starting|healthy|unhealthy|none) - filters containers based on healthcheck status
 
-#### Label
+#### label
 
 The `label` filter matches containers based on the presence of a `label` alone or a `label` and a
 value.
@@ -111,7 +117,7 @@
 d85756f57265        busybox             "top"               About a minute ago   Up About a minute                       high_albattani
 ```
 
-#### Name
+#### name
 
 The `name` filter matches on all or part of a container's name.
 
@@ -135,7 +141,7 @@
 673394ef1d4c        busybox             "top"               38 minutes ago      Up 38 minutes                           nostalgic_shockley
 ```
 
-#### Exited
+#### exited
 
 The `exited` filter matches containers by exist status code. For example, to
 filter for containers that have exited successfully:
@@ -149,13 +155,14 @@
 48ee228c9464        fedora:20         bash                   2 weeks ago         Exited (0) 2 weeks ago                              tender_torvalds
 ```
 
-#### Killed containers
+#### Filter by exit signal
 
 You can use a filter to locate containers that exited with status of `137`
 meaning a `SIGKILL(9)` killed them.
 
-```bash
+```none
 $ docker ps -a --filter 'exited=137'
+
 CONTAINER ID        IMAGE               COMMAND                CREATED             STATUS                       PORTS               NAMES
 b3e1c0ed5bfe        ubuntu:latest       "sleep 1000"           12 seconds ago      Exited (137) 5 seconds ago                       grave_kowalevski
 a2eb5558d669        redis:latest        "/entrypoint.sh redi   2 hours ago         Exited (137) 2 hours ago                         sharp_lalande
@@ -167,7 +174,7 @@
 * `docker kill` kills the container
 * Docker daemon restarts which kills all running containers
 
-#### Status
+#### status
 
 The `status` filter matches containers by status. You can filter using
 `created`, `restarting`, `running`, `removing`, `paused`, `exited` and `dead`. For example,
@@ -191,7 +198,7 @@
 673394ef1d4c        busybox             "top"               About an hour ago   Up About an hour (Paused)                       nostalgic_shockley
 ```
 
-#### Ancestor
+#### ancestor
 
 The `ancestor` filter matches containers based on its image or a descendant of
 it. The filter supports the following image representation:
@@ -244,7 +251,9 @@
 82a598284012        ubuntu:12.04.5      "top"               3 minutes ago        Up 3 minutes                            sleepy_bose
 ```
 
-#### Before
+#### Create time
+
+##### before
 
 The `before` filter shows only containers created before the container with
 given id or name. For example, having these containers created:
@@ -268,7 +277,7 @@
 6e63f6ff38b0        busybox     "top"         About a minute ago   Up About a minute                      distracted_fermat
 ```
 
-#### Since
+##### since
 
 The `since` filter shows only containers created since the container with given
 id or name. For example, with the same containers as in `before` filter:
@@ -281,12 +290,12 @@
 4aace5031105        busybox     "top"         10 minutes ago      Up 10 minutes                           focused_hamilton
 ```
 
-#### Volume
+#### volume
 
 The `volume` filter shows only containers that mount a specific volume or have
 a volume mounted in a specific path:
 
-```bash{% raw %}
+```bash
 $ docker ps --filter volume=remote-volume --format "table {{.ID}}\t{{.Mounts}}"
 CONTAINER ID        MOUNTS
 9c3527ed70ce        remote-volume
@@ -294,9 +303,9 @@
 $ docker ps --filter volume=/data --format "table {{.ID}}\t{{.Mounts}}"
 CONTAINER ID        MOUNTS
 9c3527ed70ce        remote-volume
-{% endraw %}```
+```
 
-#### Network
+#### network
 
 The `network` filter shows only containers that are connected to a network with
 a given name or id.
@@ -319,9 +328,7 @@
 the network id as a filter;
 
 ```bash
-{% raw %}
 $ docker network inspect --format "{{.ID}}" net1
-{% endraw %}
 
 8c0b4110ae930dbe26b258de9bc34a03f98056ed6f27f991d32919bfe401d7c5
 
@@ -331,7 +338,7 @@
 9d4893ed80fe        ubuntu      "top"         10 minutes ago      Up 10 minutes                           test1
 ```
 
-## Formatting
+### Formatting
 
 The formatting option (`--format`) pretty-prints container output using a Go
 template.
@@ -350,7 +357,7 @@
 `.Size`       | Container disk size.
 `.Names`      | Container names.
 `.Labels`     | All labels assigned to the container.
-`.Label`      | Value of a specific label for this container. For example `'{% raw %}{{.Label "com.docker.swarm.cpu"}}{% endraw %}'`
+`.Label`      | Value of a specific label for this container. For example `'{{.Label "com.docker.swarm.cpu"}}'`
 `.Mounts`     | Names of the volumes mounted in this container.
 `.Networks`   | Names of the networks attached to this container.
 
@@ -362,9 +369,7 @@
 `Command` entries separated by a colon for all running containers:
 
 ```bash
-{% raw %}
 $ docker ps --format "{{.ID}}: {{.Command}}"
-{% endraw %}
 
 a87ecb4f327c: /bin/sh -c #(nop) MA
 01946d9d34d8: /bin/sh -c #(nop) MA
@@ -375,9 +380,7 @@
 To list all running containers with their labels in a table format you can use:
 
 ```bash
-{% raw %}
 $ docker ps --format "table {{.ID}}\t{{.Labels}}"
-{% endraw %}
 
 CONTAINER ID        LABELS
 a87ecb4f327c        com.docker.swarm.node=ubuntu,com.docker.swarm.storage=ssd
diff --git a/docs/reference/commandline/pull.md b/docs/reference/commandline/pull.md
index 0c960b4..7bf3df8 100644
--- a/docs/reference/commandline/pull.md
+++ b/docs/reference/commandline/pull.md
@@ -26,6 +26,8 @@
       --help                    Print usage
 ```
 
+## Description
+
 Most of your images will be created on top of a base image from the
 [Docker Hub](https://hub.docker.com) registry.
 
@@ -35,7 +37,7 @@
 To download a particular image, or set of images (i.e., a repository),
 use `docker pull`.
 
-## Proxy configuration
+### Proxy configuration
 
 If you are behind an HTTP proxy server, for example in corporate settings,
 before open a connect to registry, you may need to configure the Docker
@@ -44,7 +46,7 @@
 `systemd`, refer to the [control and configure Docker with systemd](https://docs.docker.com/engine/admin/systemd/#http-proxy)
 for variables configuration.
 
-## Concurrent downloads
+### Concurrent downloads
 
 By default the Docker daemon will pull three layers of an image at a time.
 If you are on a low bandwidth connection this may cause timeout issues and you may want to lower
@@ -110,7 +112,7 @@
 refer to [understand images, containers, and storage drivers](https://docs.docker.com/engine/userguide/storagedriver/imagesandcontainers/).
 
 
-## Pull an image by digest (immutable identifier)
+### Pull an image by digest (immutable identifier)
 
 So far, you've pulled images by their name (and "tag"). Using names and tags is
 a convenient way to work with images. When using tags, you can `docker pull` an
@@ -175,7 +177,7 @@
 > digest accordingly.
 
 
-## Pulling from a different registry
+### Pull from a different registry
 
 By default, `docker pull` pulls images from [Docker Hub](https://hub.docker.com). It is also possible to
 manually specify the path of a registry to pull from. For example, if you have
@@ -196,7 +198,7 @@
 [insecure registries](dockerd.md#insecure-registries) section for more information.
 
 
-## Pull a repository with multiple images
+### Pull a repository with multiple images
 
 By default, `docker pull` pulls a *single* image from the registry. A repository
 can contain multiple images. To pull all images from a repository, provide the
@@ -231,7 +233,7 @@
 fedora       latest      105182bb5e8b    5 days ago   372.7 MB
 ```
 
-## Canceling a pull
+### Cancel a pull
 
 Killing the `docker pull` process, for example by pressing `CTRL-c` while it is
 running in a terminal, will terminate the pull operation.
diff --git a/docs/reference/commandline/push.md b/docs/reference/commandline/push.md
index e36fd02..d33804d 100644
--- a/docs/reference/commandline/push.md
+++ b/docs/reference/commandline/push.md
@@ -25,6 +25,8 @@
       --help                    Print usage
 ```
 
+## Description
+
 Use `docker push` to share your images to the [Docker Hub](https://hub.docker.com)
 registry or to a self-hosted one.
 
@@ -36,7 +38,7 @@
 
 Registry credentials are managed by [docker login](login.md).
 
-## Concurrent uploads
+### Concurrent uploads
 
 By default the Docker daemon will push five layers of an image at a time.
 If you are on a low bandwidth connection this may cause timeout issues and you may want to lower
@@ -45,7 +47,7 @@
 
 ## Examples
 
-### Pushing a new image to a registry
+### Push a new image to a registry
 
 First save the new image by finding the container ID (using [`docker ps`](ps.md))
 and then committing it to a new image name.  Note that only `a-z0-9-_.` are
@@ -62,6 +64,7 @@
 
 ```bash
 $ docker tag rhel-httpd registry-host:5000/myadmin/rhel-httpd
+
 $ docker push registry-host:5000/myadmin/rhel-httpd
 ```
 
diff --git a/docs/reference/commandline/rename.md b/docs/reference/commandline/rename.md
index be035f1..90268a2 100644
--- a/docs/reference/commandline/rename.md
+++ b/docs/reference/commandline/rename.md
@@ -24,4 +24,12 @@
       --help   Print usage
 ```
 
-The `docker rename` command allows the container to be renamed to a different name.
+## Description
+
+The `docker rename` command renames a container.
+
+## Examples
+
+```bash
+$ docker rename my_container my_new_container
+```
diff --git a/docs/reference/commandline/restart.md b/docs/reference/commandline/restart.md
index 9f7ed00..a2796af 100644
--- a/docs/reference/commandline/restart.md
+++ b/docs/reference/commandline/restart.md
@@ -24,3 +24,9 @@
       --help       Print usage
   -t, --time int   Seconds to wait for stop before killing the container (default 10)
 ```
+
+## Examples
+
+```bash
+$ docker restart my_container
+```
diff --git a/docs/reference/commandline/rm.md b/docs/reference/commandline/rm.md
index 1c3e795..8ee5b28 100644
--- a/docs/reference/commandline/rm.md
+++ b/docs/reference/commandline/rm.md
@@ -29,40 +29,71 @@
 
 ## Examples
 
-    $ docker rm /redis
-    /redis
+### Remove a container
 
 This will remove the container referenced under the link
 `/redis`.
 
-    $ docker rm --link /webapp/redis
-    /webapp/redis
+```bash
+$ docker rm /redis
+
+/redis
+```
+
+### Remove a link specified with `--link` on the default bridge network
 
 This will remove the underlying link between `/webapp` and the `/redis`
-containers removing all network communication.
+containers on the default bridge network, removing all network communication
+between the two containers. This does not apply when `--link` is used with
+user-specified networks.
 
-    $ docker rm --force redis
-    redis
+```bash
+$ docker rm --link /webapp/redis
 
-The main process inside the container referenced under the link `/redis` will receive
+/webapp/redis
+```
+
+### Force-remove a running container
+
+This command will force-remove a running container.
+
+```bash
+$ docker rm --force redis
+
+redis
+```
+
+The main process inside the container referenced under the link `redis` will receive
 `SIGKILL`, then the container will be removed.
 
-    $ docker rm $(docker ps -a -q)
+### Remove all stopped containers
+
+```bash
+$ docker rm $(docker ps -a -q)
+```
 
 This command will delete all stopped containers. The command
 `docker ps -a -q` will return all existing container IDs and pass them to
 the `rm` command which will delete them. Any running containers will not be
 deleted.
 
-    $ docker rm -v redis
-    redis
+### Remove a container and its volumes
+
+```bash
+$ docker rm -v redis
+redis
+```
 
 This command will remove the container and any volumes associated with it.
 Note that if a volume was specified with a name, it will not be removed.
 
-    $ docker create -v awesome:/foo -v /bar --name hello redis
-    hello
-    $ docker rm -v hello
+### Remove a container and selectively remove volumes
+
+```bash
+$ docker create -v awesome:/foo -v /bar --name hello redis
+hello
+$ docker rm -v hello
+```
 
 In this example, the volume for `/foo` will remain intact, but the volume for
 `/bar` will be removed. The same behavior holds for volumes inherited with
diff --git a/docs/reference/commandline/rmi.md b/docs/reference/commandline/rmi.md
index 149b763..28e21d4 100644
--- a/docs/reference/commandline/rmi.md
+++ b/docs/reference/commandline/rmi.md
@@ -26,58 +26,80 @@
       --no-prune   Do not delete untagged parents
 ```
 
+## Examples
+
 You can remove an image using its short or long ID, its tag, or its digest. If
 an image has one or more tag referencing it, you must remove all of them before
 the image is removed. Digest references are removed automatically when an image
 is removed by tag.
 
-    $ docker images
-    REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
-    test1                     latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
-    test                      latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
-    test2                     latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
+```bash
+$ docker images
 
-    $ docker rmi fd484f19954f
-    Error: Conflict, cannot delete image fd484f19954f because it is tagged in multiple repositories, use -f to force
-    2013/12/11 05:47:16 Error: failed to remove one or more images
+REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
+test1                     latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
+test                      latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
+test2                     latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
 
-    $ docker rmi test1
-    Untagged: test1:latest
-    $ docker rmi test2
-    Untagged: test2:latest
+$ docker rmi fd484f19954f
 
-    $ docker images
-    REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
-    test                      latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
-    $ docker rmi test
-    Untagged: test:latest
-    Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8
+Error: Conflict, cannot delete image fd484f19954f because it is tagged in multiple repositories, use -f to force
+2013/12/11 05:47:16 Error: failed to remove one or more images
+
+$ docker rmi test1
+
+Untagged: test1:latest
+
+$ docker rmi test2
+
+Untagged: test2:latest
+
+
+$ docker images
+
+REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
+test                      latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
+
+$ docker rmi test
+
+Untagged: test:latest
+Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8
+```
 
 If you use the `-f` flag and specify the image's short or long ID, then this
 command untags and removes all images that match the specified ID.
 
-    $ docker images
-    REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
-    test1                     latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
-    test                      latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
-    test2                     latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
+```bash
+$ docker images
 
-    $ docker rmi -f fd484f19954f
-    Untagged: test1:latest
-    Untagged: test:latest
-    Untagged: test2:latest
-    Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8
+REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
+test1                     latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
+test                      latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
+test2                     latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
+
+$ docker rmi -f fd484f19954f
+
+Untagged: test1:latest
+Untagged: test:latest
+Untagged: test2:latest
+Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8
+```
 
 An image pulled by digest has no tag associated with it:
 
-    $ docker images --digests
-    REPOSITORY                     TAG       DIGEST                                                                    IMAGE ID        CREATED         SIZE
-    localhost:5000/test/busybox    <none>    sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf   4986bf8c1536    9 weeks ago     2.43 MB
+```bash
+$ docker images --digests
+
+REPOSITORY                     TAG       DIGEST                                                                    IMAGE ID        CREATED         SIZE
+localhost:5000/test/busybox    <none>    sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf   4986bf8c1536    9 weeks ago     2.43 MB
+```
 
 To remove an image using its digest:
 
-    $ docker rmi localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf
-    Untagged: localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf
-    Deleted: 4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125
-    Deleted: ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2
-    Deleted: df7546f9f060a2268024c8a230d8639878585defcc1bc6f79d2728a13957871b
+```bash
+$ docker rmi localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf
+Untagged: localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf
+Deleted: 4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125
+Deleted: ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2
+Deleted: df7546f9f060a2268024c8a230d8639878585defcc1bc6f79d2728a13957871b
+```
diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md
index e57ba4b..920e23f 100644
--- a/docs/reference/commandline/run.md
+++ b/docs/reference/commandline/run.md
@@ -144,6 +144,8 @@
   -w, --workdir string              Working directory inside the container
 ```
 
+## Description
+
 The `docker run` command first `creates` a writeable container layer over the
 specified image, and then `starts` it using the specified command. That is,
 `docker run` is equivalent to the API `/containers/create` then
@@ -160,12 +162,15 @@
 
 ### Assign name and allocate pseudo-TTY (--name, -it)
 
-    $ docker run --name test -it debian
-    root@d6c0fe130dba:/# exit 13
-    $ echo $?
-    13
-    $ docker ps -a | grep test
-    d6c0fe130dba        debian:7            "/bin/bash"         26 seconds ago      Exited (13) 17 seconds ago                         test
+```bash
+$ docker run --name test -it debian
+
+root@d6c0fe130dba:/# exit 13
+$ echo $?
+13
+$ docker ps -a | grep test
+d6c0fe130dba        debian:7            "/bin/bash"         26 seconds ago      Exited (13) 17 seconds ago                         test
+```
 
 This example runs a container named `test` using the `debian:latest`
 image. The `-it` instructs Docker to allocate a pseudo-TTY connected to
@@ -176,7 +181,9 @@
 
 ### Capture container ID (--cidfile)
 
-    $ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test"
+```bash
+$ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test"
+```
 
 This will create a container and print `test` to the console. The `cidfile`
 flag makes Docker attempt to create a new file and write the container ID to it.
@@ -185,19 +192,23 @@
 
 ### Full container capabilities (--privileged)
 
-    $ docker run -t -i --rm ubuntu bash
-    root@bc338942ef20:/# mount -t tmpfs none /mnt
-    mount: permission denied
+```bash
+$ docker run -t -i --rm ubuntu bash
+root@bc338942ef20:/# mount -t tmpfs none /mnt
+mount: permission denied
+```
 
 This will *not* work, because by default, most potentially dangerous kernel
 capabilities are dropped; including `cap_sys_admin` (which is required to mount
 filesystems). However, the `--privileged` flag will allow it to run:
 
-    $ docker run -t -i --privileged ubuntu bash
-    root@50e3f57e16e6:/# mount -t tmpfs none /mnt
-    root@50e3f57e16e6:/# df -h
-    Filesystem      Size  Used Avail Use% Mounted on
-    none            1.9G     0  1.9G   0% /mnt
+```bash
+$ docker run -t -i --privileged ubuntu bash
+root@50e3f57e16e6:/# mount -t tmpfs none /mnt
+root@50e3f57e16e6:/# df -h
+Filesystem      Size  Used Avail Use% Mounted on
+none            1.9G     0  1.9G   0% /mnt
+```
 
 The `--privileged` flag gives *all* capabilities to the container, and it also
 lifts all the limitations enforced by the `device` cgroup controller. In other
@@ -206,14 +217,18 @@
 
 ### Set working directory (-w)
 
-    $ docker  run -w /path/to/dir/ -i -t  ubuntu pwd
+```bash
+$ docker  run -w /path/to/dir/ -i -t  ubuntu pwd
+```
 
 The `-w` lets the command being executed inside directory given, here
 `/path/to/dir/`. If the path does not exist it is created inside the container.
 
 ### Set storage driver options per container
 
-    $ docker run -it --storage-opt size=120G fedora /bin/bash
+```bash
+$ docker run -it --storage-opt size=120G fedora /bin/bash
+```
 
 This (size) will allow to set the container rootfs size to 120G at creation time.
 This option is only available for the `devicemapper`, `btrfs`, `overlay2`,
@@ -226,14 +241,18 @@
 
 ### Mount tmpfs (--tmpfs)
 
-    $ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image
+```bash
+$ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image
+```
 
 The `--tmpfs` flag mounts an empty tmpfs into the container with the `rw`,
 `noexec`, `nosuid`, `size=65536k` options.
 
 ### Mount volume (-v, --read-only)
 
-    $ docker  run  -v `pwd`:`pwd` -w `pwd` -i -t  ubuntu pwd
+```bash
+$ docker  run  -v `pwd`:`pwd` -w `pwd` -i -t  ubuntu pwd
+```
 
 The `-v` flag mounts the current working directory into the container. The `-w`
 lets the command being executed inside the current working directory, by
@@ -241,21 +260,27 @@
 combination executes the command using the container, but inside the
 current working directory.
 
-    $ docker run -v /doesnt/exist:/foo -w /foo -i -t ubuntu bash
+```bash
+$ docker run -v /doesnt/exist:/foo -w /foo -i -t ubuntu bash
+```
 
 When the host directory of a bind-mounted volume doesn't exist, Docker
 will automatically create this directory on the host for you. In the
 example above, Docker will create the `/doesnt/exist`
 folder before starting your container.
 
-    $ docker run --read-only -v /icanwrite busybox touch /icanwrite/here
+```bash
+$ docker run --read-only -v /icanwrite busybox touch /icanwrite/here
+```
 
 Volumes can be used in combination with `--read-only` to control where
 a container writes files. The `--read-only` flag mounts the container's root
 filesystem as read only prohibiting writes to locations other than the
 specified volumes for the container.
 
-    $ docker run -t -i -v /var/run/docker.sock:/var/run/docker.sock -v /path/to/static-docker-binary:/usr/bin/docker busybox sh
+```bash
+$ docker run -t -i -v /var/run/docker.sock:/var/run/docker.sock -v /path/to/static-docker-binary:/usr/bin/docker busybox sh
+```
 
 By bind-mounting the docker unix socket and statically linked docker
 binary (refer to [get the linux binary](
@@ -263,45 +288,55 @@
 you give the container the full access to create and manipulate the host's
 Docker daemon.
 
-On Windows, the paths must be specified using Windows-style semantics. 
+On Windows, the paths must be specified using Windows-style semantics.
 
-    PS C:\> docker run -v c:\foo:c:\dest microsoft/nanoserver cmd /s /c type c:\dest\somefile.txt
-    Contents of file
-	
-    PS C:\> docker run -v c:\foo:d: microsoft/nanoserver cmd /s /c type d:\somefile.txt
-    Contents of file
+```powershell
+PS C:\> docker run -v c:\foo:c:\dest microsoft/nanoserver cmd /s /c type c:\dest\somefile.txt
+Contents of file
 
-The following examples will fail when using Windows-based containers, as the 
-destination of a volume or bind-mount inside the container must be one of: 
+PS C:\> docker run -v c:\foo:d: microsoft/nanoserver cmd /s /c type d:\somefile.txt
+Contents of file
+```
+
+The following examples will fail when using Windows-based containers, as the
+destination of a volume or bind-mount inside the container must be one of:
 a non-existing or empty directory; or a drive other than C:. Further, the source
 of a bind mount must be a local directory, not a file.
 
-    net use z: \\remotemachine\share
-    docker run -v z:\foo:c:\dest ...
-    docker run -v \\uncpath\to\directory:c:\dest ...
-    docker run -v c:\foo\somefile.txt:c:\dest ...
-    docker run -v c:\foo:c: ...
-    docker run -v c:\foo:c:\existing-directory-with-contents ...
+```powershell
+net use z: \\remotemachine\share
+docker run -v z:\foo:c:\dest ...
+docker run -v \\uncpath\to\directory:c:\dest ...
+docker run -v c:\foo\somefile.txt:c:\dest ...
+docker run -v c:\foo:c: ...
+docker run -v c:\foo:c:\existing-directory-with-contents ...
+```
 
 For in-depth information about volumes, refer to [manage data in containers](https://docs.docker.com/engine/tutorials/dockervolumes/)
 
 ### Publish or expose port (-p, --expose)
 
-    $ docker run -p 127.0.0.1:80:8080 ubuntu bash
+```bash
+$ docker run -p 127.0.0.1:80:8080 ubuntu bash
+```
 
 This binds port `8080` of the container to port `80` on `127.0.0.1` of the host
 machine. The [Docker User
 Guide](https://docs.docker.com/engine/userguide/networking/default_network/dockerlinks/)
 explains in detail how to manipulate ports in Docker.
 
-    $ docker run --expose 80 ubuntu bash
+```bash
+$ docker run --expose 80 ubuntu bash
+```
 
 This exposes port `80` of the container without publishing the port to the host
 system's interfaces.
 
 ### Set environment variables (-e, --env, --env-file)
 
-    $ docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash
+```bash
+$ docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash
+```
 
 This sets simple (non-array) environmental variables in the container. For
 illustration all three
@@ -317,10 +352,12 @@
 first, and then `-e`, `--env` flags. This way, the `-e` or `--env` will
 override variables as needed.
 
-    $ cat ./env.list
-    TEST_FOO=BAR
-    $ docker run --env TEST_FOO="This is a test" --env-file ./env.list busybox env | grep TEST_FOO
-    TEST_FOO=This is a test
+```bash
+$ cat ./env.list
+TEST_FOO=BAR
+$ docker run --env TEST_FOO="This is a test" --env-file ./env.list busybox env | grep TEST_FOO
+TEST_FOO=This is a test
+```
 
 The `--env-file` flag takes a filename as an argument and expects each line
 to be in the `VAR=VAL` format, mimicking the argument passed to `--env`. Comment
@@ -328,53 +365,57 @@
 
 An example of a file passed with `--env-file`
 
-    $ cat ./env.list
-    TEST_FOO=BAR
+```bash
+$ cat ./env.list
+TEST_FOO=BAR
 
-    # this is a comment
-    TEST_APP_DEST_HOST=10.10.0.127
-    TEST_APP_DEST_PORT=8888
-    _TEST_BAR=FOO
-    TEST_APP_42=magic
-    helloWorld=true
-    123qwe=bar
-    org.spring.config=something
+# this is a comment
+TEST_APP_DEST_HOST=10.10.0.127
+TEST_APP_DEST_PORT=8888
+_TEST_BAR=FOO
+TEST_APP_42=magic
+helloWorld=true
+123qwe=bar
+org.spring.config=something
 
-    # pass through this variable from the caller
-    TEST_PASSTHROUGH
-    $ TEST_PASSTHROUGH=howdy docker run --env-file ./env.list busybox env
-    PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
-    HOSTNAME=5198e0745561
-    TEST_FOO=BAR
-    TEST_APP_DEST_HOST=10.10.0.127
-    TEST_APP_DEST_PORT=8888
-    _TEST_BAR=FOO
-    TEST_APP_42=magic
-    helloWorld=true
-    TEST_PASSTHROUGH=howdy
-    HOME=/root
-    123qwe=bar
-    org.spring.config=something
+# pass through this variable from the caller
+TEST_PASSTHROUGH
+$ TEST_PASSTHROUGH=howdy docker run --env-file ./env.list busybox env
+PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+HOSTNAME=5198e0745561
+TEST_FOO=BAR
+TEST_APP_DEST_HOST=10.10.0.127
+TEST_APP_DEST_PORT=8888
+_TEST_BAR=FOO
+TEST_APP_42=magic
+helloWorld=true
+TEST_PASSTHROUGH=howdy
+HOME=/root
+123qwe=bar
+org.spring.config=something
 
-    $ docker run --env-file ./env.list busybox env
-    PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
-    HOSTNAME=5198e0745561
-    TEST_FOO=BAR
-    TEST_APP_DEST_HOST=10.10.0.127
-    TEST_APP_DEST_PORT=8888
-    _TEST_BAR=FOO
-    TEST_APP_42=magic
-    helloWorld=true
-    TEST_PASSTHROUGH=
-    HOME=/root
-    123qwe=bar
-    org.spring.config=something
+$ docker run --env-file ./env.list busybox env
+PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+HOSTNAME=5198e0745561
+TEST_FOO=BAR
+TEST_APP_DEST_HOST=10.10.0.127
+TEST_APP_DEST_PORT=8888
+_TEST_BAR=FOO
+TEST_APP_42=magic
+helloWorld=true
+TEST_PASSTHROUGH=
+HOME=/root
+123qwe=bar
+org.spring.config=something
+```
 
 ### Set metadata on container (-l, --label, --label-file)
 
 A label is a `key=value` pair that applies metadata to a container. To label a container with two labels:
 
-    $ docker run -l my-label --label com.example.foo=bar ubuntu bash
+```bash
+$ docker run -l my-label --label com.example.foo=bar ubuntu bash
+```
 
 The `my-label` key doesn't specify a value so the label defaults to an empty
 string(`""`). To add multiple labels, repeat the label flag (`-l` or `--label`).
@@ -387,18 +428,22 @@
 label in the file with an EOL mark. The example below loads labels from a
 labels file in the current directory:
 
-    $ docker run --label-file ./labels ubuntu bash
+```bash
+$ docker run --label-file ./labels ubuntu bash
+```
 
 The label-file format is similar to the format for loading environment
 variables. (Unlike environment variables, labels are not visible to processes
 running inside a container.) The following example illustrates a label-file
 format:
 
-    com.example.label1="a label"
+```none
+com.example.label1="a label"
 
-    # this is a comment
-    com.example.label2=another\ label
-    com.example.label3
+# this is a comment
+com.example.label2=another\ label
+com.example.label3
+```
 
 You can load multiple label-files by supplying multiple  `--label-file` flags.
 
@@ -430,16 +475,18 @@
 connectivity, containers connected to the same multi-host network but launched
 from different Engines can also communicate in this way.
 
-**Note**: Service discovery is unavailable on the default bridge network.
-Containers can communicate via their IP addresses by default. To communicate
-by name, they must be linked.
+> **Note**: Service discovery is unavailable on the default bridge network.
+> Containers can communicate via their IP addresses by default. To communicate
+> by name, they must be linked.
 
 You can disconnect a container from a network using the `docker network
 disconnect` command.
 
 ### Mount volumes from container (--volumes-from)
 
-    $ docker run --volumes-from 777f7dc92da7 --volumes-from ba8c0c54f0f2:ro -i -t ubuntu pwd
+```bash
+$ docker run --volumes-from 777f7dc92da7 --volumes-from ba8c0c54f0f2:ro -i -t ubuntu pwd
+```
 
 The `--volumes-from` flag mounts all the defined volumes from the referenced
 containers. Containers can be specified by repetitions of the `--volumes-from`
@@ -467,18 +514,24 @@
 or `STDERR`. This makes it possible to manipulate the output and input as
 needed.
 
-    $ echo "test" | docker run -i -a stdin ubuntu cat -
+```bash
+$ echo "test" | docker run -i -a stdin ubuntu cat -
+```
 
 This pipes data into a container and prints the container's ID by attaching
 only to the container's `STDIN`.
 
-    $ docker run -a stderr ubuntu echo test
+```bash
+$ docker run -a stderr ubuntu echo test
+```
 
 This isn't going to print anything unless there's an error because we've
 only attached to the `STDERR` of the container. The container's logs
 still store what's been written to `STDERR` and `STDOUT`.
 
-    $ cat somefile | docker run -i -a stdin mybuilder dobuild
+```bash
+$ cat somefile | docker run -i -a stdin mybuilder dobuild
+```
 
 This is how piping a file into a container could be done for a build.
 The container's ID will be printed after the build is done and the build
@@ -488,10 +541,16 @@
 
 ### Add host device to container (--device)
 
-    $ docker run --device=/dev/sdc:/dev/xvdc --device=/dev/sdd --device=/dev/zero:/dev/nulo -i -t ubuntu ls -l /dev/{xvdc,sdd,nulo}
-    brw-rw---- 1 root disk 8, 2 Feb  9 16:05 /dev/xvdc
-    brw-rw---- 1 root disk 8, 3 Feb  9 16:05 /dev/sdd
-    crw-rw-rw- 1 root root 1, 5 Feb  9 16:05 /dev/nulo
+```bash
+$ docker run --device=/dev/sdc:/dev/xvdc \
+             --device=/dev/sdd --device=/dev/zero:/dev/nulo \
+             -i -t \
+             ubuntu ls -l /dev/{xvdc,sdd,nulo}
+
+brw-rw---- 1 root disk 8, 2 Feb  9 16:05 /dev/xvdc
+brw-rw---- 1 root disk 8, 3 Feb  9 16:05 /dev/sdd
+crw-rw-rw- 1 root root 1, 5 Feb  9 16:05 /dev/nulo
+```
 
 It is often necessary to directly expose devices to a container. The `--device`
 option enables that. For example, a specific block storage device or loop
@@ -502,24 +561,24 @@
 This can be overridden using a third `:rwm` set of options to each `--device`
 flag:
 
+```bash
+$ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk  /dev/xvdc
 
-    $ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk  /dev/xvdc
+Command (m for help): q
+$ docker run --device=/dev/sda:/dev/xvdc:r --rm -it ubuntu fdisk  /dev/xvdc
+You will not be able to write the partition table.
 
-    Command (m for help): q
-    $ docker run --device=/dev/sda:/dev/xvdc:r --rm -it ubuntu fdisk  /dev/xvdc
-    You will not be able to write the partition table.
+Command (m for help): q
 
-    Command (m for help): q
+$ docker run --device=/dev/sda:/dev/xvdc:rw --rm -it ubuntu fdisk  /dev/xvdc
 
-    $ docker run --device=/dev/sda:/dev/xvdc:rw --rm -it ubuntu fdisk  /dev/xvdc
+Command (m for help): q
 
-    Command (m for help): q
+$ docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk  /dev/xvdc
+fdisk: unable to open /dev/xvdc: Operation not permitted
+```
 
-    $ docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk  /dev/xvdc
-    fdisk: unable to open /dev/xvdc: Operation not permitted
-
-> **Note:**
-> `--device` cannot be safely used with ephemeral devices. Block devices
+> **Note**: `--device` cannot be safely used with ephemeral devices. Block devices
 > that may be removed should not be added to untrusted containers with
 > `--device`.
 
@@ -529,54 +588,15 @@
 policy controls whether the Docker daemon restarts a container after exit.
 Docker supports the following restart policies:
 
-<table>
-  <thead>
-    <tr>
-      <th>Policy</th>
-      <th>Result</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td><strong>no</strong></td>
-      <td>
-        Do not automatically restart the container when it exits. This is the
-        default.
-      </td>
-    </tr>
-    <tr>
-      <td>
-        <span style="white-space: nowrap">
-          <strong>on-failure</strong>[:max-retries]
-        </span>
-      </td>
-      <td>
-        Restart only if the container exits with a non-zero exit status.
-        Optionally, limit the number of restart retries the Docker
-        daemon attempts.
-      </td>
-    </tr>
-    <tr>
-      <td><strong>always</strong></td>
-      <td>
-        Always restart the container regardless of the exit status.
-        When you specify always, the Docker daemon will try to restart
-        the container indefinitely. The container will also always start
-        on daemon startup, regardless of the current state of the container.
-      </td>
-    </tr>
-    <tr>
-      <td><strong>unless-stopped</strong></td>
-      <td>
-        Always restart the container regardless of the exit status, but
-        do not start it on daemon startup if the container has been put
-        to a stopped state before.
-      </td>
-    </tr>
-  </tbody>
-</table>
+| Policy            | Result                                  |
+|-------------------|-----------------------------------------|
+| `no`              | Do not automatically restart the container when it exits. This is the default. |
+| `failure`         | Restart only if the container exits with a non-zero exit status. Optionally, limit the number of restart retries the Docker daemon attempts. |
+| `always`          | Always restart the container regardless of the exit status. When you specify always, the Docker daemon will try to restart the container indefinitely. The container will also always start on daemon startup, regardless of the current state of the container. |
 
-    $ docker run --restart=always redis
+```bash
+$ docker run --restart=always redis
+```
 
 This will run the `redis` container with a restart policy of **always**
 so that if the container exits, Docker will restart it.
@@ -591,14 +611,17 @@
 more `--add-host` flags. This example adds a static address for a host named
 `docker`:
 
-    $ docker run --add-host=docker:10.180.0.1 --rm -it debian
-    root@f38c87f2a42d:/# ping docker
-    PING docker (10.180.0.1): 48 data bytes
-    56 bytes from 10.180.0.1: icmp_seq=0 ttl=254 time=7.600 ms
-    56 bytes from 10.180.0.1: icmp_seq=1 ttl=254 time=30.705 ms
-    ^C--- docker ping statistics ---
-    2 packets transmitted, 2 packets received, 0% packet loss
-    round-trip min/avg/max/stddev = 7.600/19.152/30.705/11.553 ms
+```bash
+$ docker run --add-host=docker:10.180.0.1 --rm -it debian
+
+root@f38c87f2a42d:/# ping docker
+PING docker (10.180.0.1): 48 data bytes
+56 bytes from 10.180.0.1: icmp_seq=0 ttl=254 time=7.600 ms
+56 bytes from 10.180.0.1: icmp_seq=1 ttl=254 time=30.705 ms
+^C--- docker ping statistics ---
+2 packets transmitted, 2 packets received, 0% packet loss
+round-trip min/avg/max/stddev = 7.600/19.152/30.705/11.553 ms
+```
 
 Sometimes you need to connect to the Docker host from within your
 container. To enable this, pass the Docker host's IP address to
@@ -609,8 +632,10 @@
 using IPv4 or IPv6 networking in your containers. Use the following
 flags for IPv4 address retrieval for a network device named `eth0`:
 
-    $ HOSTIP=`ip -4 addr show scope global dev eth0 | grep inet | awk '{print \$2}' | cut -d / -f 1`
-    $ docker run  --add-host=docker:${HOSTIP} --rm -it debian
+```bash
+$ HOSTIP=`ip -4 addr show scope global dev eth0 | grep inet | awk '{print \$2}' | cut -d / -f 1`
+$ docker run  --add-host=docker:${HOSTIP} --rm -it debian
+```
 
 For IPv6 use the `-6` flag instead of the `-4` flag. For other network
 devices, replace `eth0` with the correct device name (for example `docker0`
@@ -623,15 +648,19 @@
 `--ulimit` is specified with a soft and hard limit as such:
 `<type>=<soft limit>[:<hard limit>]`, for example:
 
-    $ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n"
-    1024
+```bash
+$ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n"
+1024
+```
 
-> **Note:**
-> If you do not provide a `hard limit`, the `soft limit` will be used
+> **Note**: If you do not provide a `hard limit`, the `soft limit` will be used
 > for both values. If no `ulimits` are set, they will be inherited from
 > the default `ulimits` set on the daemon.  `as` option is disabled now.
 > In other words, the following script is not supported:
-> `$ docker run -it --ulimit as=1024 fedora /bin/bash`
+>
+> ```bash
+> $ docker run -it --ulimit as=1024 fedora /bin/bash`
+> ```
 
 The values are sent to the appropriate `syscall` as they are set.
 Docker doesn't perform any byte conversion. Take this into account when setting the values.
@@ -642,10 +671,15 @@
 maximum number of processes available to a user, not to a container.  For example, start four
 containers with `daemon` user:
 
-    docker run -d -u daemon --ulimit nproc=3 busybox top
-    docker run -d -u daemon --ulimit nproc=3 busybox top
-    docker run -d -u daemon --ulimit nproc=3 busybox top
-    docker run -d -u daemon --ulimit nproc=3 busybox top
+```bash
+$ docker run -d -u daemon --ulimit nproc=3 busybox top
+
+$ docker run -d -u daemon --ulimit nproc=3 busybox top
+
+$ docker run -d -u daemon --ulimit nproc=3 busybox top
+
+$ docker run -d -u daemon --ulimit nproc=3 busybox top
+```
 
 The 4th container fails and reports "[8] System error: resource temporarily unavailable" error.
 This fails because the caller set `nproc=3` resulting in the first three containers using up
@@ -710,8 +744,9 @@
 container. For example, to turn on IP forwarding in the containers
 network namespace, run this command:
 
-    $ docker run --sysctl net.ipv4.ip_forward=1 someimage
-
+```bash
+$ docker run --sysctl net.ipv4.ip_forward=1 someimage
+```
 
 > **Note**: Not all sysctls are namespaced. Docker does not support changing sysctls
 > inside of a container that also modify the host system. As the kernel
@@ -719,14 +754,17 @@
 
 #### Currently supported sysctls
 
-  `IPC Namespace`:
+- `IPC Namespace`:
 
+  ```none
   kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced
   Sysctls beginning with fs.mqueue.*
+  ```
 
   If you use the `--ipc=host` option these sysctls will not be allowed.
 
-  `Network Namespace`:
-      Sysctls beginning with net.*
+- `Network Namespace`:
+
+  Sysctls beginning with net.*
 
   If you use the `--network=host` option using these sysctls will not be allowed.
diff --git a/docs/reference/commandline/save.md b/docs/reference/commandline/save.md
index 88a5fed..cba7385 100644
--- a/docs/reference/commandline/save.md
+++ b/docs/reference/commandline/save.md
@@ -25,21 +25,38 @@
   -o, --output string   Write to a file, instead of STDOUT
 ```
 
+## Description
+
 Produces a tarred repository to the standard output stream.
 Contains all parent layers, and all tags + versions, or specified `repo:tag`, for
 each argument provided.
 
-It is used to create a backup that can then be used with `docker load`
+## Examples
 
-    $ docker save busybox > busybox.tar
-    $ ls -sh busybox.tar
-    2.7M busybox.tar
-    $ docker save --output busybox.tar busybox
-    $ ls -sh busybox.tar
-    2.7M busybox.tar
-    $ docker save -o fedora-all.tar fedora
-    $ docker save -o fedora-latest.tar fedora:latest
+### Create a backup that can then be used with `docker load`.
 
-It is even useful to cherry-pick particular tags of an image repository
+```bash
+$ docker save busybox > busybox.tar
 
-    $ docker save -o ubuntu.tar ubuntu:lucid ubuntu:saucy
+$ ls -sh busybox.tar
+
+2.7M busybox.tar
+
+$ docker save --output busybox.tar busybox
+
+$ ls -sh busybox.tar
+
+2.7M busybox.tar
+
+$ docker save -o fedora-all.tar fedora
+
+$ docker save -o fedora-latest.tar fedora:latest
+```
+
+### Cherry-pick particular tags
+
+You can even cherry-pick particular tags of an image repository.
+
+```bash
+$ docker save -o ubuntu.tar ubuntu:lucid ubuntu:saucy
+```
diff --git a/docs/reference/commandline/search.md b/docs/reference/commandline/search.md
index 31faf37..f645c78 100644
--- a/docs/reference/commandline/search.md
+++ b/docs/reference/commandline/search.md
@@ -30,13 +30,14 @@
       --no-trunc       Don't truncate output
 ```
 
+## Description
+
 Search [Docker Hub](https://hub.docker.com) for images
 
 See [*Find Public Images on Docker Hub*](https://docs.docker.com/engine/tutorials/dockerrepos/#searching-for-images) for
 more details on finding shared images from the command line.
 
-> **Note:**
-> Search queries will only return up to 25 results
+> **Note**: Search queries return a maximum of 25 results.
 
 ## Examples
 
@@ -44,52 +45,57 @@
 
 This example displays images with a name containing 'busybox':
 
-    $ docker search busybox
-    NAME                             DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
-    busybox                          Busybox base image.                             316       [OK]       
-    progrium/busybox                                                                 50                   [OK]
-    radial/busyboxplus               Full-chain, Internet enabled, busybox made...   8                    [OK]
-    odise/busybox-python                                                             2                    [OK]
-    azukiapp/busybox                 This image is meant to be used as the base...   2                    [OK]
-    ofayau/busybox-jvm               Prepare busybox to install a 32 bits JVM.       1                    [OK]
-    shingonoide/archlinux-busybox    Arch Linux, a lightweight and flexible Lin...   1                    [OK]
-    odise/busybox-curl                                                               1                    [OK]
-    ofayau/busybox-libc32            Busybox with 32 bits (and 64 bits) libs         1                    [OK]
-    peelsky/zulu-openjdk-busybox                                                     1                    [OK]
-    skomma/busybox-data              Docker image suitable for data volume cont...   1                    [OK]
-    elektritter/busybox-teamspeak    Lightweight teamspeak3 container based on...    1                    [OK]
-    socketplane/busybox                                                              1                    [OK]
-    oveits/docker-nginx-busybox      This is a tiny NginX docker image based on...   0                    [OK]
-    ggtools/busybox-ubuntu           Busybox ubuntu version with extra goodies       0                    [OK]
-    nikfoundas/busybox-confd         Minimal busybox based distribution of confd     0                    [OK]
-    openshift/busybox-http-app                                                       0                    [OK]
-    jllopis/busybox                                                                  0                    [OK]
-    swyckoff/busybox                                                                 0                    [OK]
-    powellquiring/busybox                                                            0                    [OK]
-    williamyeh/busybox-sh            Docker image for BusyBox's sh                   0                    [OK]
-    simplexsys/busybox-cli-powered   Docker busybox images, with a few often us...   0                    [OK]
-    fhisamoto/busybox-java           Busybox java                                    0                    [OK]
-    scottabernethy/busybox                                                           0                    [OK]
-    marclop/busybox-solr
+```none
+$ docker search busybox
+
+NAME                             DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
+busybox                          Busybox base image.                             316       [OK]       
+progrium/busybox                                                                 50                   [OK]
+radial/busyboxplus               Full-chain, Internet enabled, busybox made...   8                    [OK]
+odise/busybox-python                                                             2                    [OK]
+azukiapp/busybox                 This image is meant to be used as the base...   2                    [OK]
+ofayau/busybox-jvm               Prepare busybox to install a 32 bits JVM.       1                    [OK]
+shingonoide/archlinux-busybox    Arch Linux, a lightweight and flexible Lin...   1                    [OK]
+odise/busybox-curl                                                               1                    [OK]
+ofayau/busybox-libc32            Busybox with 32 bits (and 64 bits) libs         1                    [OK]
+peelsky/zulu-openjdk-busybox                                                     1                    [OK]
+skomma/busybox-data              Docker image suitable for data volume cont...   1                    [OK]
+elektritter/busybox-teamspeak    Lightweight teamspeak3 container based on...    1                    [OK]
+socketplane/busybox                                                              1                    [OK]
+oveits/docker-nginx-busybox      This is a tiny NginX docker image based on...   0                    [OK]
+ggtools/busybox-ubuntu           Busybox ubuntu version with extra goodies       0                    [OK]
+nikfoundas/busybox-confd         Minimal busybox based distribution of confd     0                    [OK]
+openshift/busybox-http-app                                                       0                    [OK]
+jllopis/busybox                                                                  0                    [OK]
+swyckoff/busybox                                                                 0                    [OK]
+powellquiring/busybox                                                            0                    [OK]
+williamyeh/busybox-sh            Docker image for BusyBox's sh                   0                    [OK]
+simplexsys/busybox-cli-powered   Docker busybox images, with a few often us...   0                    [OK]
+fhisamoto/busybox-java           Busybox java                                    0                    [OK]
+scottabernethy/busybox                                                           0                    [OK]
+marclop/busybox-solr
+```
 
 ### Display non-truncated description (--no-trunc)
 
 This example displays images with a name containing 'busybox',
 at least 3 stars and the description isn't truncated in the output:
 
-    $ docker search --stars=3 --no-trunc busybox
-    NAME                 DESCRIPTION                                                                               STARS     OFFICIAL   AUTOMATED
-    busybox              Busybox base image.                                                                       325       [OK]       
-    progrium/busybox                                                                                               50                   [OK]
-    radial/busyboxplus   Full-chain, Internet enabled, busybox made from scratch. Comes in git and cURL flavors.   8                    [OK]
+```bash
+$ docker search --stars=3 --no-trunc busybox
+NAME                 DESCRIPTION                                                                               STARS     OFFICIAL   AUTOMATED
+busybox              Busybox base image.                                                                       325       [OK]       
+progrium/busybox                                                                                               50                   [OK]
+radial/busyboxplus   Full-chain, Internet enabled, busybox made from scratch. Comes in git and cURL flavors.   8                    [OK]
+```
 
-## Limit search results (--limit)
+### Limit search results (--limit)
 
 The flag `--limit` is the maximum number of results returned by a search. This value could
 be in the range between 1 and 100. The default value of `--limit` is 25.
 
 
-## Filtering
+### Filtering
 
 The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more
 than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`)
@@ -101,34 +107,43 @@
 * is-official (true|false) - is the image official or not
 
 
-### stars
+#### stars
 
 This example displays images with a name containing 'busybox' and at
 least 3 stars:
 
-    $ docker search --filter stars=3 busybox
-    NAME                 DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
-    busybox              Busybox base image.                             325       [OK]       
-    progrium/busybox                                                     50                   [OK]
-    radial/busyboxplus   Full-chain, Internet enabled, busybox made...   8                    [OK]
+```bash
+$ docker search --filter stars=3 busybox
+
+NAME                 DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
+busybox              Busybox base image.                             325       [OK]       
+progrium/busybox                                                     50                   [OK]
+radial/busyboxplus   Full-chain, Internet enabled, busybox made...   8                    [OK]
+```
 
 
-### is-automated
+#### is-automated
 
 This example displays images with a name containing 'busybox'
 and are automated builds:
 
-    $ docker search --filter is-automated busybox
-    NAME                 DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
-    progrium/busybox                                                     50                   [OK]
-    radial/busyboxplus   Full-chain, Internet enabled, busybox made...   8                    [OK]
+```bash
+$ docker search --filter is-automated busybox
 
-### is-official
+NAME                 DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
+progrium/busybox                                                     50                   [OK]
+radial/busyboxplus   Full-chain, Internet enabled, busybox made...   8                    [OK]
+```
+
+#### is-official
 
 This example displays images with a name containing 'busybox', at least
 3 stars and are official builds:
 
-    $ docker search --filter "is-official=true" --filter "stars=3" busybox
-    NAME                 DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
-    progrium/busybox                                                     50                   [OK]
-    radial/busyboxplus   Full-chain, Internet enabled, busybox made...   8                    [OK]
+```bash
+$ docker search --filter "is-official=true" --filter "stars=3" busybox
+
+NAME                 DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
+progrium/busybox                                                     50                   [OK]
+radial/busyboxplus   Full-chain, Internet enabled, busybox made...   8                    [OK]
+```
diff --git a/docs/reference/commandline/secret_create.md b/docs/reference/commandline/secret_create.md
index aebcebb..74839f7 100644
--- a/docs/reference/commandline/secret_create.md
+++ b/docs/reference/commandline/secret_create.md
@@ -25,6 +25,8 @@
   -l, --label list    Secret labels (default [])
 ```
 
+## Description
+
 Creates a secret using standard input or from a file for the secret content. You must run this
 command on a manager node.
 
@@ -45,9 +47,11 @@
 
 ```bash
 $ docker secret create my_secret ./secret.json
+
 mhv17xfe3gh6xc4rij5orpfds
 
 $ docker secret ls
+
 ID                          NAME                    CREATED                                   UPDATED                                   SIZE
 mhv17xfe3gh6xc4rij5orpfds   my_secret               2016-10-27 23:25:43.909181089 +0000 UTC   2016-10-27 23:25:43.909181089 +0000 UTC   1679
 ```
@@ -55,10 +59,16 @@
 ### Create a secret with labels
 
 ```bash
-$ docker secret create --label env=dev --label rev=20161102 my_secret ./secret.json
-jtn7g6aukl5ky7nr9gvwafoxh
+$ docker secret create --label env=dev \
+                       --label rev=20161102 \
+                       my_secret ./secret.json
 
+jtn7g6aukl5ky7nr9gvwafoxh
+```
+
+```none
 $ docker secret inspect my_secret
+
 [
     {
         "ID": "jtn7g6aukl5ky7nr9gvwafoxh",
@@ -79,11 +89,10 @@
         "SecretSize": 1679
     }
 ]
-
 ```
 
 
-## Related information
+## Related commands
 
 * [secret inspect](secret_inspect.md)
 * [secret ls](secret_ls.md)
diff --git a/docs/reference/commandline/secret_inspect.md b/docs/reference/commandline/secret_inspect.md
index de878f7..098274e 100644
--- a/docs/reference/commandline/secret_inspect.md
+++ b/docs/reference/commandline/secret_inspect.md
@@ -25,6 +25,7 @@
       --help            Print usage
 ```
 
+## Description
 
 Inspects the specified secret. This command has to be run targeting a manager
 node.
@@ -37,7 +38,7 @@
 
 ## Examples
 
-### Inspecting a secret by name or ID
+### Inspect a secret by name or ID
 
 You can inspect a secret, either by its *name*, or *ID*
 
@@ -49,8 +50,9 @@
 mhv17xfe3gh6xc4rij5orpfds   secret.json             2016-10-27 23:25:43.909181089 +0000 UTC   2016-10-27 23:25:43.909181089 +0000 UTC
 ```
 
-```bash
+```none
 $ docker secret inspect secret.json
+
 [
     {
         "ID": "mhv17xfe3gh6xc4rij5orpfds",
@@ -66,19 +68,20 @@
 ]
 ```
 
-### Formatting secret output
+### Formatting
 
 You can use the --format option to obtain specific information about a
 secret. The following example command outputs the creation time of the
 secret.
 
-```bash{% raw %}
+```bash
 $ docker secret inspect --format='{{.CreatedAt}}' mhv17xfe3gh6xc4rij5orpfds
+
 2016-10-27 23:25:43.909181089 +0000 UTC
-{% endraw %}```
+```
 
 
-## Related information
+## Related commands
 
 * [secret create](secret_create.md)
 * [secret ls](secret_ls.md)
diff --git a/docs/reference/commandline/secret_ls.md b/docs/reference/commandline/secret_ls.md
index 6b34fc2..72b9e46 100644
--- a/docs/reference/commandline/secret_ls.md
+++ b/docs/reference/commandline/secret_ls.md
@@ -27,16 +27,20 @@
   -q, --quiet          Only display IDs
 ```
 
-Run this command on a manager node to list the secrets in the Swarm.
+## Description
+
+Run this command on a manager node to list the secrets in the swarm.
 
 ## Examples
 
 ```bash
 $ docker secret ls
+
 ID                          NAME                    CREATED                                   UPDATED
 mhv17xfe3gh6xc4rij5orpfds   secret.json             2016-10-27 23:25:43.909181089 +0000 UTC   2016-10-27 23:25:43.909181089 +0000 UTC
 ```
-## Related information
+
+## Related commands
 
 * [secret create](secret_create.md)
 * [secret inspect](secret_inspect.md)
diff --git a/docs/reference/commandline/secret_rm.md b/docs/reference/commandline/secret_rm.md
index f504b1b..9887d33 100644
--- a/docs/reference/commandline/secret_rm.md
+++ b/docs/reference/commandline/secret_rm.md
@@ -27,9 +27,13 @@
       --help   Print usage
 ```
 
+## Description
+
 Removes the specified secrets from the swarm. This command has to be run
 targeting a manager node.
 
+## Examples
+
 This example removes a secret:
 
 ```bash
@@ -41,7 +45,7 @@
 > before removing a secret.
 
 
-## Related information
+## Related commands
 
 * [secret create](secret_create.md)
 * [secret inspect](secret_inspect.md)
diff --git a/docs/reference/commandline/service_create.md b/docs/reference/commandline/service_create.md
index c9e2980..33fe24b 100644
--- a/docs/reference/commandline/service_create.md
+++ b/docs/reference/commandline/service_create.md
@@ -68,6 +68,8 @@
   -w, --workdir string                   Working directory inside the container
 ```
 
+## Description
+
 Creates a service as described by the specified parameters. You must run this
 command on a manager node.
 
@@ -77,12 +79,15 @@
 
 ```bash
 $ docker service create --name redis redis:3.0.6
+
 dmu1ept4cxcfe8k8lhtux3ro3
 
 $ docker service create --mode global --name redis2 redis:3.0.6
+
 a8q9dasaafudfs8q8w32udass
 
 $ docker service ls
+
 ID            NAME    MODE        REPLICAS  IMAGE
 dmu1ept4cxcf  redis   replicated  1/1       redis:3.0.6
 a8q9dasaafud  redis2  global      1/1       redis:3.0.6
@@ -95,6 +100,7 @@
 
 ```bash
 $ docker service create --name redis --replicas=5 redis:3.0.6
+
 4cdgfyky7ozwh3htjfw0d12qv
 ```
 
@@ -108,6 +114,7 @@
 
 ```bash
 $ docker service ls
+
 ID            NAME   MODE        REPLICAS  IMAGE
 4cdgfyky7ozw  redis  replicated  3/5       redis:3.0.7
 ```
@@ -117,11 +124,13 @@
 
 ```bash
 $ docker service ls
+
 ID            NAME   MODE        REPLICAS  IMAGE
 4cdgfyky7ozw  redis  replicated  5/5       redis:3.0.7
 ```
 
 ### Create a service with secrets
+
 Use the `--secret` flag to give a container access to a
 [secret](secret_create.md).
 
@@ -129,6 +138,7 @@
 
 ```bash
 $ docker service create --name redis --secret secret.json redis:3.0.6
+
 4cdgfyky7ozwh3htjfw0d12qv
 ```
 
@@ -139,6 +149,7 @@
     --secret source=ssh-key,target=ssh \
     --secret source=app-key,target=app,uid=1000,gid=1001,mode=0400 \
     redis:3.0.6
+
 4cdgfyky7ozwh3htjfw0d12qv
 ```
 
@@ -172,12 +183,15 @@
 $ docker service create --name redis_2 --replicas 5 --env MYVAR=foo redis:3.0.6
 ```
 
-### Create a docker service with specific hostname (--hostname)
+### Create a service with specific hostname (--hostname)
 
-This option sets the docker service containers hostname to a specific string. For example:
+This option sets the docker service containers hostname to a specific string.
+For example:
+
 ```bash
 $ docker service create --name redis --hostname myredis redis:3.0.6
 ```
+
 ### Set metadata on a service (-l, --label)
 
 A label is a `key=value` pair that applies metadata to a service. To label a
@@ -201,7 +215,7 @@
 system. These types are _data volumes_ (often referred to simply as volumes) and
 _bind-mounts_.
 
-Additionally, Docker also supports tmpfs mounts.
+Additionally, Docker supports `tmpfs` mounts.
 
 A **bind-mount** makes a file or directory on the host available to the
 container it is mounted within. A bind-mount may be either read-only or
@@ -303,19 +317,19 @@
 or `--volume` flag for `docker run`, with some important exceptions:
 
 - The `--mount` flag allows you to specify a volume driver and volume driver
-    options *per volume*, without creating the volumes in advance. In contrast,
-    `docker run` allows you to specify a single volume driver which is shared
-    by all volumes, using the `--volume-driver` flag.
+  options *per volume*, without creating the volumes in advance. In contrast,
+  `docker run` allows you to specify a single volume driver which is shared
+  by all volumes, using the `--volume-driver` flag.
 
 - The `--mount` flag allows you to specify custom metadata ("labels") for a volume,
-    before the volume is created.
+  before the volume is created.
 
 - When you use `--mount` with `type=bind`, the host-path must refer to an *existing*
-    path on the host. The path will not be created for you and the service will fail
-    with an error if the path does not exist.
+  path on the host. The path will not be created for you and the service will fail
+  with an error if the path does not exist.
 
 - The `--mount` flag does not allow you to relabel a volume with `Z` or `z` flags,
-    which are used for `selinux` labeling.
+  which are used for `selinux` labeling.
 
 #### Create a service using a named volume
 
@@ -532,18 +546,23 @@
 service's name and the node's ID where it sits.
 
 ```bash
-$ docker service create --name hosttempl --hostname={% raw %}"{{.Node.ID}}-{{.Service.Name}}"{% endraw %} busybox top
+$ docker service create --name hosttempl \
+                        --hostname="{{.Node.ID}}-{{.Service.Name}}"\
+                         busybox top
+
 va8ew30grofhjoychbr6iot8c
 
 $ docker service ps va8ew30grofhjoychbr6iot8c
+
 ID            NAME         IMAGE                                                                                   NODE          DESIRED STATE  CURRENT STATE               ERROR  PORTS
 wo41w8hg8qan  hosttempl.1  busybox:latest@sha256:29f5d56d12684887bdfa50dcd29fc31eea4aaf4ad3bec43daf19026a7ce69912  2e7a8a9c4da2  Running        Running about a minute ago
 
-$ docker inspect --format={% raw %}"{{.Config.Hostname}}"{% endraw %} hosttempl.1.wo41w8hg8qanxwjwsg4kxpprj
+$ docker inspect --format="{{.Config.Hostname}}" hosttempl.1.wo41w8hg8qanxwjwsg4kxpprj
+
 x3ti0erg11rjpg64m75kej2mz-hosttempl
 ```
 
-## Related information
+## Related commands
 
 * [service inspect](service_inspect.md)
 * [service logs](service_logs.md)
diff --git a/docs/reference/commandline/service_inspect.md b/docs/reference/commandline/service_inspect.md
index 8b4ab62..b2088d2 100644
--- a/docs/reference/commandline/service_inspect.md
+++ b/docs/reference/commandline/service_inspect.md
@@ -26,6 +26,7 @@
       --pretty          Print the information in a human friendly format.
 ```
 
+## Description
 
 Inspects the specified service. This command has to be run targeting a manager
 node.
@@ -38,7 +39,7 @@
 
 ## Examples
 
-### Inspecting a service  by name or ID
+### Inspect a service by name or ID
 
 You can inspect a service, either by its *name*, or *ID*
 
@@ -53,8 +54,9 @@
 Both `docker service inspect redis`, and `docker service inspect dmu1ept4cxcf`
 produce the same result:
 
-```bash
+```none
 $ docker service inspect redis
+
 [
     {
         "ID": "dmu1ept4cxcfe8k8lhtux3ro3",
@@ -98,6 +100,7 @@
 
 ```bash
 $ docker service inspect dmu1ept4cxcf
+
 [
     {
         "ID": "dmu1ept4cxcfe8k8lhtux3ro3",
@@ -109,13 +112,14 @@
 ]
 ```
 
-### Inspect a service using pretty-print
+### Formatting
 
 You can print the inspect output in a human-readable format instead of the default
 JSON output, by using the `--pretty` option:
 
 ```bash
 $ docker service inspect --pretty frontend
+
 ID:		c8wgl7q4ndfd52ni6qftkvnnp
 Name:		frontend
 Labels:
@@ -139,19 +143,20 @@
 You can also use `--format pretty` for the same effect.
 
 
-### Finding the number of tasks running as part of a service
+#### Find the number of tasks running as part of a service
 
 The `--format` option can be used to obtain specific information about a
 service. For example, the following command outputs the number of replicas
 of the "redis" service.
 
-```bash{% raw %}
+```bash
 $ docker service inspect --format='{{.Spec.Mode.Replicated.Replicas}}' redis
+
 10
-{% endraw %}```
+```
 
 
-## Related information
+## Related commands
 
 * [service create](service_create.md)
 * [service logs](service_logs.md)
diff --git a/docs/reference/commandline/service_logs.md b/docs/reference/commandline/service_logs.md
index fdf6a3a..844a58e 100644
--- a/docs/reference/commandline/service_logs.md
+++ b/docs/reference/commandline/service_logs.md
@@ -30,9 +30,11 @@
   -t, --timestamps     Show timestamps
 ```
 
+## Description
+
 The `docker service logs` command batch-retrieves logs present at the time of execution.
 
-> **Note**: this command is only functional for services that are started with
+> **Note**: This command is only functional for services that are started with
 > the `json-file` or `journald` logging driver.
 
 For more information about selecting and configuring logging drivers, refer to
@@ -66,7 +68,7 @@
 fraction of a second no more than nine digits long. You can combine the
 `--since` option with either or both of the `--follow` or `--tail` options.
 
-## Related information
+## Related commands
 
 * [service create](service_create.md)
 * [service inspect](service_inspect.md)
diff --git a/docs/reference/commandline/service_ls.md b/docs/reference/commandline/service_ls.md
index ccd68af..c6c2ace 100644
--- a/docs/reference/commandline/service_ls.md
+++ b/docs/reference/commandline/service_ls.md
@@ -29,12 +29,18 @@
   -q, --quiet          Only display IDs
 ```
 
+## Description
+
 This command when run targeting a manager, lists services are running in the
 swarm.
 
+## Examples
+
 On a manager node:
+
 ```bash
 $ docker service ls
+
 ID            NAME      MODE        REPLICAS    IMAGE
 c8wgl7q4ndfd  frontend  replicated  5/5         nginx:alpine
 dmu1ept4cxcf  redis     replicated  3/3         redis:3.0.6
@@ -44,7 +50,7 @@
 The `REPLICAS` column shows both the *actual* and *desired* number of tasks for
 the service.
 
-## Filtering
+### Filtering
 
 The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more
 than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`)
@@ -55,7 +61,7 @@
 * [label](service_ls.md#label)
 * [name](service_ls.md#name)
 
-#### ID
+#### id
 
 The `id` filter matches all or part of a service's id.
 
@@ -65,7 +71,7 @@
 0bcjwfh8ychr  redis  replicated  1/1       redis:3.0.6
 ```
 
-#### Label
+#### label
 
 The `label` filter matches services based on the presence of a `label` alone or
 a `label` and a value.
@@ -91,7 +97,7 @@
 74nzcxxjv6fq  backend   replicated  3/3       redis:3.0.6
 ```
 
-#### Name
+#### name
 
 The `name` filter matches on all or part of a service's name.
 
@@ -103,7 +109,7 @@
 0bcjwfh8ychr  redis  replicated  1/1       redis:3.0.6
 ```
 
-## Related information
+## Related commands
 
 * [service create](service_create.md)
 * [service inspect](service_inspect.md)
diff --git a/docs/reference/commandline/service_ps.md b/docs/reference/commandline/service_ps.md
index 61abb15..4b0118f 100644
--- a/docs/reference/commandline/service_ps.md
+++ b/docs/reference/commandline/service_ps.md
@@ -29,12 +29,14 @@
   -q, --quiet           Only display task IDs
 ```
 
-Lists the tasks that are running as part of the specified service. This command
+## Description
+
+Lists the tasks that are running as part of the specified services. This command
 has to be run targeting a manager node.
 
 ## Examples
 
-### Listing the tasks that are part of a service
+### List the tasks that are part of a service
 
 The following command shows all the tasks that are part of the `redis` service:
 
@@ -93,7 +95,7 @@
 nvjljf7rmor4htv7l8rwcx7i7   \_ redis.2   redis:3.0.6@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842  worker2   Shutdown       Rejected 5 minutes ago   "No such image: redis@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842"
 ```
 
-## Filtering
+### Filtering
 
 The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there
 is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`).
@@ -108,7 +110,7 @@
 * [desired-state](#desired-state)
 
 
-#### ID
+#### id
 
 The `id` filter matches on all or a prefix of a task's ID.
 
@@ -120,7 +122,7 @@
 8eaxrb2fqpbn   redis.10  redis:3.0.6  manager1  Running        Running 8 seconds
 ```
 
-#### Name
+#### name
 
 The `name` filter matches on task names.
 
@@ -131,7 +133,7 @@
 ```
 
 
-#### Node
+#### node
 
 The `node` filter matches on a node name or a node ID.
 
@@ -150,7 +152,7 @@
 The `desired-state` filter can take the values `running`, `shutdown`, and `accepted`.
 
 
-## Related information
+## Related commands
 
 * [service create](service_create.md)
 * [service inspect](service_inspect.md)
diff --git a/docs/reference/commandline/service_rm.md b/docs/reference/commandline/service_rm.md
index d0ba90b..448f2c3 100644
--- a/docs/reference/commandline/service_rm.md
+++ b/docs/reference/commandline/service_rm.md
@@ -27,24 +27,29 @@
       --help   Print usage
 ```
 
+## Description
+
 Removes the specified services from the swarm. This command has to be run
 targeting a manager node.
 
-For example, to remove the redis service:
+## Examples
+
+Remove the `redis` service:
 
 ```bash
 $ docker service rm redis
+
 redis
+
 $ docker service ls
+
 ID  NAME  MODE  REPLICAS  IMAGE
 ```
 
 > **Warning**: Unlike `docker rm`, this command does not ask for confirmation
 > before removing a running service.
 
-
-
-## Related information
+## Related commands
 
 * [service create](service_create.md)
 * [service inspect](service_inspect.md)
diff --git a/docs/reference/commandline/service_scale.md b/docs/reference/commandline/service_scale.md
index 64075ed..a3aef5f 100644
--- a/docs/reference/commandline/service_scale.md
+++ b/docs/reference/commandline/service_scale.md
@@ -24,9 +24,7 @@
       --help   Print usage
 ```
 
-## Examples
-
-### Scale a service
+## Description
 
 The scale command enables you to scale one or more replicated services either up
 or down to the desired number of replicas. This command cannot be applied on
@@ -34,19 +32,27 @@
 actual scaling of the service may take some time. To stop all replicas of a
 service while keeping the service active in the swarm you can set the scale to 0.
 
-For example, the following command scales the "frontend" service to 50 tasks.
+## Examples
+
+### Scale a single service
+
+The following command scales the "frontend" service to 50 tasks.
 
 ```bash
 $ docker service scale frontend=50
+
 frontend scaled to 50
 ```
 
 The following command tries to scale a global service to 10 tasks and returns an error.
 
-```
+```bash
 $ docker service create --mode global --name backend backend:latest
+
 b4g08uwuairexjub6ome6usqh
+
 $ docker service scale backend=10
+
 backend: scale can only be used with replicated mode
 ```
 
@@ -76,16 +82,18 @@
 
 ```bash
 $ docker service scale backend=3 frontend=5
+
 backend scaled to 3
 frontend scaled to 5
 
 $ docker service ls
+
 ID            NAME      MODE        REPLICAS  IMAGE
 3pr5mlvu3fh9  frontend  replicated  5/5       nginx:alpine
 74nzcxxjv6fq  backend   replicated  3/3       redis:3.0.6
 ```
 
-## Related information
+## Related commands
 
 * [service create](service_create.md)
 * [service inspect](service_inspect.md)
diff --git a/docs/reference/commandline/service_update.md b/docs/reference/commandline/service_update.md
index 301a0ea..a98923e 100644
--- a/docs/reference/commandline/service_update.md
+++ b/docs/reference/commandline/service_update.md
@@ -80,6 +80,8 @@
   -w, --workdir string                   Working directory inside the container
 ```
 
+## Description
+
 Updates a service as described by the specified parameters. This command has to be run targeting a manager node.
 The parameters are the same as [`docker service create`](service_create.md). Please look at the description there
 for further information.
@@ -111,7 +113,7 @@
 `--update-delay 30s` setting introduces a 30 second delay between tasks, so
 that the rolling restart happens gradually.
 
-### Adding and removing mounts
+### Add or remove mounts
 
 Use the `--mount-add` or `--mount-rm` options add or remove a service's bind-mounts
 or volumes.
@@ -151,7 +153,7 @@
 myservice
 ```
 
-### Adding and removing secrets
+### Add or remove secrets
 
 Use the `--secret-add` or `--secret-rm` options add or remove a service's
 secrets.
@@ -170,7 +172,7 @@
 Some flags of `service update` support the use of templating.
 See [`service create`](./service_create.md#templating) for the reference.
 
-## Related information
+## Related commands
 
 * [service create](service_create.md)
 * [service inspect](service_inspect.md)
diff --git a/docs/reference/commandline/stack_deploy.md b/docs/reference/commandline/stack_deploy.md
index 037feae..39456b7 100644
--- a/docs/reference/commandline/stack_deploy.md
+++ b/docs/reference/commandline/stack_deploy.md
@@ -30,15 +30,20 @@
       --with-registry-auth    Send registry authentication details to Swarm agents
 ```
 
+## Description
+
 Create and update a stack from a `compose` or a `dab` file on the swarm. This command
 has to be run targeting a manager node.
 
-## Compose file
+## Examples
+
+### Compose file
 
 The `deploy` command supports compose file version `3.0` and above."
 
 ```bash
 $ docker stack deploy --compose-file docker-compose.yml vossibility
+
 Ignoring unsupported options: links
 
 Creating network vossibility_vossibility
@@ -53,8 +58,9 @@
 
 You can verify that the services were correctly created
 
-```
+```bash
 $ docker service ls
+
 ID            NAME                               MODE        REPLICAS  IMAGE
 29bv0vnlm903  vossibility_lookupd                replicated  1/1       nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662
 4awt47624qwh  vossibility_nsqd                   replicated  1/1       nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662
@@ -64,10 +70,11 @@
 axqh55ipl40h  vossibility_vossibility-collector  replicated  1/1       icecrime/vossibility-collector@sha256:f03f2977203ba6253988c18d04061c5ec7aab46bca9dfd89a9a1fa4500989fba
 ```
 
-## DAB file
+### DAB file
 
 ```bash
 $ docker stack deploy --bundle-file vossibility-stack.dab vossibility
+
 Loading bundle from vossibility-stack.dab
 Creating service vossibility_elasticsearch
 Creating service vossibility_kibana
@@ -81,6 +88,7 @@
 
 ```bash
 $ docker service ls
+
 ID            NAME                               MODE        REPLICAS  IMAGE
 29bv0vnlm903  vossibility_lookupd                replicated  1/1       nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662
 4awt47624qwh  vossibility_nsqd                   replicated  1/1       nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662
@@ -90,7 +98,7 @@
 axqh55ipl40h  vossibility_vossibility-collector  replicated  1/1       icecrime/vossibility-collector@sha256:f03f2977203ba6253988c18d04061c5ec7aab46bca9dfd89a9a1fa4500989fba
 ```
 
-## Related information
+## Related commands
 
 * [stack ls](stack_ls.md)
 * [stack ps](stack_ps.md)
diff --git a/docs/reference/commandline/stack_ls.md b/docs/reference/commandline/stack_ls.md
index 05c7215..567d947 100644
--- a/docs/reference/commandline/stack_ls.md
+++ b/docs/reference/commandline/stack_ls.md
@@ -27,9 +27,13 @@
       --help   Print usage
 ```
 
+## Description
+
 Lists the stacks.
 
-For example, the following command shows all stacks and some additional information:
+## Examples
+
+The following command shows all stacks and some additional information:
 
 ```bash
 $ docker stack ls
@@ -39,7 +43,7 @@
 myapp              2
 ```
 
-## Related information
+## Related commands
 
 * [stack deploy](stack_deploy.md)
 * [stack ps](stack_ps.md)
diff --git a/docs/reference/commandline/stack_ps.md b/docs/reference/commandline/stack_ps.md
index 101e9fe..9f221d8 100644
--- a/docs/reference/commandline/stack_ps.md
+++ b/docs/reference/commandline/stack_ps.md
@@ -27,10 +27,18 @@
       --no-trunc        Do not truncate output
 ```
 
+## Description
+
 Lists the tasks that are running as part of the specified stack. This
 command has to be run targeting a manager node.
 
-## Filtering
+## Examples
+
+```bash
+$ docker stack ps
+```
+
+### Filtering
 
 The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there
 is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`).
@@ -43,7 +51,7 @@
 * name
 * desired-state
 
-## Related information
+## Related commands
 
 * [stack deploy](stack_deploy.md)
 * [stack ls](stack_ls.md)
diff --git a/docs/reference/commandline/stack_rm.md b/docs/reference/commandline/stack_rm.md
index fd63997..d9d5043 100644
--- a/docs/reference/commandline/stack_rm.md
+++ b/docs/reference/commandline/stack_rm.md
@@ -27,10 +27,12 @@
       --help   Print usage
 ```
 
+## Description
+
 Remove the stack from the swarm. This command has to be run targeting
 a manager node.
 
-## Related information
+## Related commands
 
 * [stack deploy](stack_deploy.md)
 * [stack ls](stack_ls.md)
diff --git a/docs/reference/commandline/stack_services.md b/docs/reference/commandline/stack_services.md
index 62779b4..d688795 100644
--- a/docs/reference/commandline/stack_services.md
+++ b/docs/reference/commandline/stack_services.md
@@ -27,10 +27,14 @@
   -q, --quiet          Only display IDs
 ```
 
+### Description
+
 Lists the services that are running as part of the specified stack. This
 command has to be run targeting a manager node.
 
-For example, the following command shows all services in the `myapp` stack:
+### Examples
+
+The following command shows all services in the `myapp` stack:
 
 ```bash
 $ docker stack services myapp
@@ -40,7 +44,7 @@
 dn7m7nhhfb9y  myapp_db        1/1       mysql@sha256:a9a5b559f8821fe73d58c3606c812d1c044868d42c63817fa5125fd9d8b7b539
 ```
 
-## Filtering
+### Filtering
 
 The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there
 is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`).
@@ -62,7 +66,7 @@
 * name (`--filter name=myapp_web`)
 * label (`--filter label=key=value`)
 
-## Related information
+## Related commands
 
 * [stack deploy](stack_deploy.md)
 * [stack ls](stack_ls.md)
diff --git a/docs/reference/commandline/start.md b/docs/reference/commandline/start.md
index 980bce9..aa67228 100644
--- a/docs/reference/commandline/start.md
+++ b/docs/reference/commandline/start.md
@@ -26,3 +26,9 @@
       --help                 Print usage
   -i, --interactive          Attach container's STDIN
 ```
+
+## Examples
+
+```bash
+$ docker start my_container
+```
diff --git a/docs/reference/commandline/stats.md b/docs/reference/commandline/stats.md
index f5d0d54..55d5a44 100644
--- a/docs/reference/commandline/stats.md
+++ b/docs/reference/commandline/stats.md
@@ -27,6 +27,8 @@
       --no-stream       Disable streaming stats and only pull the first result
 ```
 
+## Description
+
 The `docker stats` command returns a live data stream for running containers. To limit data to one or more specific containers, specify a list of container names or ids separated by a space. You can specify a stopped container but stopped containers do not return any data.
 
 If you want more detailed information about a container's resource usage, use the `/containers/(id)/stats` API endpoint.
@@ -35,41 +37,49 @@
 
 Running `docker stats` on all running containers against a Linux daemon.
 
-    $ docker stats
-    CONTAINER           CPU %               MEM USAGE / LIMIT     MEM %               NET I/O             BLOCK I/O
-    1285939c1fd3        0.07%               796 KiB / 64 MiB        1.21%               788 B / 648 B       3.568 MB / 512 KB
-    9c76f7834ae2        0.07%               2.746 MiB / 64 MiB      4.29%               1.266 KB / 648 B    12.4 MB / 0 B
-    d1ea048f04e4        0.03%               4.583 MiB / 64 MiB      6.30%               2.854 KB / 648 B    27.7 MB / 0 B
+```bash
+$ docker stats
+CONTAINER           CPU %               MEM USAGE / LIMIT     MEM %               NET I/O             BLOCK I/O
+1285939c1fd3        0.07%               796 KiB / 64 MiB        1.21%               788 B / 648 B       3.568 MB / 512 KB
+9c76f7834ae2        0.07%               2.746 MiB / 64 MiB      4.29%               1.266 KB / 648 B    12.4 MB / 0 B
+d1ea048f04e4        0.03%               4.583 MiB / 64 MiB      6.30%               2.854 KB / 648 B    27.7 MB / 0 B
+```
 
 Running `docker stats` on multiple containers by name and id against a Linux daemon.
 
-    $ docker stats fervent_panini 5acfcb1b4fd1
-    CONTAINER           CPU %               MEM USAGE/LIMIT       MEM %               NET I/O
-    5acfcb1b4fd1        0.00%               115.2 MiB/1.045 GiB   11.03%              1.422 kB/648 B
-    fervent_panini      0.02%               11.08 MiB/1.045 GiB   1.06%               648 B/648 B
+```bash
+$ docker stats fervent_panini 5acfcb1b4fd1
+CONTAINER           CPU %               MEM USAGE/LIMIT       MEM %               NET I/O
+5acfcb1b4fd1        0.00%               115.2 MiB/1.045 GiB   11.03%              1.422 kB/648 B
+fervent_panini      0.02%               11.08 MiB/1.045 GiB   1.06%               648 B/648 B
+```
 
 Running `docker stats` on all running containers against a Windows daemon.
 
-    PS E:\> docker stats
-    CONTAINER           CPU %               PRIV WORKING SET    NET I/O             BLOCK I/O
-    09d3bb5b1604        6.61%               38.21 MiB           17.1 kB / 7.73 kB   10.7 MB / 3.57 MB
-    9db7aa4d986d        9.19%               38.26 MiB           15.2 kB / 7.65 kB   10.6 MB / 3.3 MB
-    3f214c61ad1d        0.00%               28.64 MiB           64 kB / 6.84 kB     4.42 MB / 6.93 MB
+```powershell
+PS E:\> docker stats
+CONTAINER           CPU %               PRIV WORKING SET    NET I/O             BLOCK I/O
+09d3bb5b1604        6.61%               38.21 MiB           17.1 kB / 7.73 kB   10.7 MB / 3.57 MB
+9db7aa4d986d        9.19%               38.26 MiB           15.2 kB / 7.65 kB   10.6 MB / 3.3 MB
+3f214c61ad1d        0.00%               28.64 MiB           64 kB / 6.84 kB     4.42 MB / 6.93 MB
+```
 
 Running `docker stats` on multiple containers by name and id against a Windows daemon.
 
-    PS E:\> docker ps -a
-    CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
-    3f214c61ad1d        nanoserver          "cmd"               2 minutes ago       Up 2 minutes                            big_minsky
-    9db7aa4d986d        windowsservercore   "cmd"               2 minutes ago       Up 2 minutes                            mad_wilson
-    09d3bb5b1604        windowsservercore   "cmd"               2 minutes ago       Up 2 minutes                            affectionate_easley
+```powershell
+PS E:\> docker ps -a
+CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
+3f214c61ad1d        nanoserver          "cmd"               2 minutes ago       Up 2 minutes                            big_minsky
+9db7aa4d986d        windowsservercore   "cmd"               2 minutes ago       Up 2 minutes                            mad_wilson
+09d3bb5b1604        windowsservercore   "cmd"               2 minutes ago       Up 2 minutes                            affectionate_easley
 
-    PS E:\> docker stats 3f214c61ad1d mad_wilson
-    CONTAINER           CPU %               PRIV WORKING SET    NET I/O             BLOCK I/O
-    3f214c61ad1d        0.00%               46.25 MiB           76.3 kB / 7.92 kB   10.3 MB / 14.7 MB
-    mad_wilson          9.59%               40.09 MiB           27.6 kB / 8.81 kB   17 MB / 20.1 MB
+PS E:\> docker stats 3f214c61ad1d mad_wilson
+CONTAINER           CPU %               PRIV WORKING SET    NET I/O             BLOCK I/O
+3f214c61ad1d        0.00%               46.25 MiB           76.3 kB / 7.92 kB   10.3 MB / 14.7 MB
+mad_wilson          9.59%               40.09 MiB           27.6 kB / 8.81 kB   17 MB / 20.1 MB
+```
 
-## Formatting
+### Formatting
 
 The formatting option (`--format`) pretty prints container output
 using a Go template.
diff --git a/docs/reference/commandline/stop.md b/docs/reference/commandline/stop.md
index 3090db9..dc00b38 100644
--- a/docs/reference/commandline/stop.md
+++ b/docs/reference/commandline/stop.md
@@ -25,5 +25,13 @@
   -t, --time int   Seconds to wait for stop before killing it (default 10)
 ```
 
+## Description
+
 The main process inside the container will receive `SIGTERM`, and after a grace
 period, `SIGKILL`.
+
+## Examples
+
+```bash
+$ docker stop my_container
+```
diff --git a/docs/reference/commandline/swarm_init.md b/docs/reference/commandline/swarm_init.md
index 44afc27..8cba118 100644
--- a/docs/reference/commandline/swarm_init.md
+++ b/docs/reference/commandline/swarm_init.md
@@ -34,9 +34,12 @@
       --task-history-limit int          Task history retention limit (default 5)
 ```
 
+## Description
+
 Initialize a swarm. The docker engine targeted by this command becomes a manager
 in the newly created single-node swarm.
 
+## Examples
 
 ```bash
 $ docker swarm init --advertise-addr 192.168.99.121
@@ -133,7 +136,7 @@
 state to new managers. However, there is a performance cost to taking snapshots
 frequently.
 
-## Related information
+## Related commands
 
 * [swarm join](swarm_join.md)
 * [swarm leave](swarm_leave.md)
diff --git a/docs/reference/commandline/swarm_join.md b/docs/reference/commandline/swarm_join.md
index 0cde0d7..d0b6685 100644
--- a/docs/reference/commandline/swarm_join.md
+++ b/docs/reference/commandline/swarm_join.md
@@ -27,10 +27,14 @@
       --token string            Token for entry into the swarm
 ```
 
+## Description
+
 Join a node to a swarm. The node joins as a manager node or worker node based upon the token you
 pass with the `--token` flag. If you pass a manager token, the node joins as a manager. If you
 pass a worker token, the node joins as a worker.
 
+## Examples
+
 ### Join a node to swarm as a manager
 
 The example below demonstrates joining a manager node using a manager token.
@@ -95,7 +99,7 @@
 Secret value required for nodes to join the swarm
 
 
-## Related information
+## Related commands
 
 * [swarm init](swarm_init.md)
 * [swarm leave](swarm_leave.md)
diff --git a/docs/reference/commandline/swarm_join_token.md b/docs/reference/commandline/swarm_join_token.md
index d731f02..60f5622 100644
--- a/docs/reference/commandline/swarm_join_token.md
+++ b/docs/reference/commandline/swarm_join_token.md
@@ -26,12 +26,16 @@
       --rotate   Rotate join token
 ```
 
+## Description
+
 Join tokens are secrets that allow a node to join the swarm. There are two
 different join tokens available, one for the worker role and one for the manager
 role. You pass the token using the `--token` flag when you run
 [swarm join](swarm_join.md). Nodes use the join token only when they join the
 swarm.
 
+## Examples
+
 You can view or rotate the join tokens using `swarm join-token`.
 
 As a convenience, you can pass `worker` or `manager` as an argument to
@@ -100,6 +104,6 @@
 
 Only print the token. Do not print a complete command for joining.
 
-## Related information
+## Related commands
 
 * [swarm join](swarm_join.md)
diff --git a/docs/reference/commandline/swarm_leave.md b/docs/reference/commandline/swarm_leave.md
index c0d9437..4b5569b 100644
--- a/docs/reference/commandline/swarm_leave.md
+++ b/docs/reference/commandline/swarm_leave.md
@@ -25,6 +25,8 @@
       --help    Print usage
 ```
 
+## Description
+
 When you run this command on a worker, that worker leaves the swarm.
 
 You can use the `--force` option to on a manager to remove it from the swarm.
@@ -34,7 +36,10 @@
 without using `--force`. Only use `--force` in situations where the swarm will
 no longer be used after the manager leaves, such as in a single-node swarm.
 
+## Examples
+
 Consider the following swarm, as seen from the manager:
+
 ```bash
 $ docker node ls
 ID                           HOSTNAME  STATUS  AVAILABILITY  MANAGER STATUS
@@ -50,7 +55,12 @@
 ```
 To remove an inactive node, use the [`node rm`](node_rm.md) command instead.
 
-## Related information
+The node will still appear in the node list, and marked as `down`. It no longer
+affects swarm operation, but a long list of `down` nodes can clutter the node
+list. To remove an inactive node from the list, use the [`node rm`](node_rm.md)
+command.
+
+## Related commands
 
 * [node rm](node_rm.md)
 * [swarm init](swarm_init.md)
diff --git a/docs/reference/commandline/swarm_unlock.md b/docs/reference/commandline/swarm_unlock.md
index 164b7d3..bd7ed14 100644
--- a/docs/reference/commandline/swarm_unlock.md
+++ b/docs/reference/commandline/swarm_unlock.md
@@ -24,18 +24,21 @@
       --help   Print usage
 ```
 
+## Description
+
 Unlocks a locked manager using a user-supplied unlock key. This command must be
 used to reactivate a manager after its Docker daemon restarts if the autolock
 setting is turned on. The unlock key is printed at the time when autolock is
 enabled, and is also available from the `docker swarm unlock-key` command.
 
+## Examples
 
 ```bash
 $ docker swarm unlock
 Please enter unlock key:
 ```
 
-## Related information
+## Related commands
 
 * [swarm init](swarm_init.md)
 * [swarm update](swarm_update.md)
diff --git a/docs/reference/commandline/swarm_unlock_key.md b/docs/reference/commandline/swarm_unlock_key.md
index a2597fe..6dc3aae 100644
--- a/docs/reference/commandline/swarm_unlock_key.md
+++ b/docs/reference/commandline/swarm_unlock_key.md
@@ -26,6 +26,8 @@
       --rotate   Rotate unlock key
 ```
 
+## Description
+
 An unlock key is a secret key needed to unlock a manager after its Docker daemon
 restarts. These keys are only used when the autolock feature is enabled for the
 swarm.
@@ -33,9 +35,11 @@
 You can view or rotate the unlock key using `swarm unlock-key`. To view the key,
 run the `docker swarm unlock-key` command without any arguments:
 
+## Examples
 
 ```bash
 $ docker swarm unlock-key
+
 To unlock a swarm manager after it restarts, run the `docker swarm unlock`
 command and provide the following key:
 
@@ -77,7 +81,7 @@
 
 Only print the unlock key, without instructions.
 
-## Related information
+## Related commands
 
 * [swarm unlock](swarm_unlock.md)
 * [swarm init](swarm_init.md)
diff --git a/docs/reference/commandline/swarm_update.md b/docs/reference/commandline/swarm_update.md
index 0af63fe..aed72d0 100644
--- a/docs/reference/commandline/swarm_update.md
+++ b/docs/reference/commandline/swarm_update.md
@@ -31,14 +31,17 @@
       --task-history-limit int          Task history retention limit (default 5)
 ```
 
+## Description
+
 Updates a swarm with new parameter values. This command must target a manager node.
 
+## Examples
 
 ```bash
 $ docker swarm update --cert-expiry 720h
 ```
 
-## Related information
+## Related commands
 
 * [swarm init](swarm_init.md)
 * [swarm join](swarm_join.md)
diff --git a/docs/reference/commandline/system_df.md b/docs/reference/commandline/system_df.md
index c6e8bbd..6758bde 100644
--- a/docs/reference/commandline/system_df.md
+++ b/docs/reference/commandline/system_df.md
@@ -25,12 +25,18 @@
   -v, --verbose   Show detailed information on space usage
 ```
 
+## Description
+
 The `docker system df` command displays information regarding the
 amount of disk space used by the docker daemon.
 
+## Examples
+
 By default the command will just show a summary of the data used:
+
 ```bash
 $ docker system df
+
 TYPE                TOTAL               ACTIVE              SIZE                RECLAIMABLE
 Images              5                   2                   16.43 MB            11.63 MB (70%)
 Containers          2                   0                   212 B               212 B (100%)
@@ -38,8 +44,10 @@
 ```
 
 A more detailed view can be requested using the `-v, --verbose` flag:
+
 ```bash
 $ docker system df -v
+
 Images space usage:
 
 REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE                SHARED SIZE         UNIQUE SIZE         CONTAINERS
@@ -66,9 +74,10 @@
 * `UNIQUE SIZE` is the amount of space that is only used by a given image
 * `SIZE` is the virtual size of the image, it is the sum of `SHARED SIZE` and `UNIQUE SIZE`
 
-Note that network information is not shown because it doesn't consume the disk space.
+> **Note**: Network information is not shown because it doesn't consume the disk
+> space.
 
-## Related Information
+## Related commands
 * [system prune](system_prune.md)
 * [container prune](container_prune.md)
 * [volume prune](volume_prune.md)
diff --git a/docs/reference/commandline/system_prune.md b/docs/reference/commandline/system_prune.md
index 46f8c43..4959b65 100644
--- a/docs/reference/commandline/system_prune.md
+++ b/docs/reference/commandline/system_prune.md
@@ -26,12 +26,15 @@
       --help    Print usage
 ```
 
+## Description
+
 Remove all unused containers, volumes, networks and images (both dangling and unreferenced).
 
-Example output:
+## Examples
 
 ```bash
 $ docker system prune -a
+
 WARNING! This will remove:
 	- all stopped containers
 	- all volumes not used by at least one container
@@ -64,7 +67,7 @@
 Total reclaimed space: 13.5 MB
 ```
 
-## Related information
+## Related commands
 
 * [volume create](volume_create.md)
 * [volume ls](volume_ls.md)
diff --git a/docs/reference/commandline/tag.md b/docs/reference/commandline/tag.md
index 983bfe2..347dd3f 100644
--- a/docs/reference/commandline/tag.md
+++ b/docs/reference/commandline/tag.md
@@ -24,6 +24,8 @@
       --help   Print usage
 ```
 
+## Description
+
 An image name is made up of slash-separated name components, optionally prefixed
 by a registry hostname. The hostname must comply with standard DNS rules, but
 may not contain underscores. If a hostname is present, it may optionally be
@@ -40,35 +42,43 @@
 You can group your images together using names and tags, and then upload them
 to [*Share Images via Repositories*](https://docs.docker.com/engine/tutorials/dockerrepos/#/contributing-to-docker-hub).
 
-# Examples
+## Examples
 
-## Tagging an image referenced by ID
+### Tag an image referenced by ID
 
 To tag a local image with ID "0e5574283393" into the "fedora" repository with
 "version1.0":
 
-    docker tag 0e5574283393 fedora/httpd:version1.0
+```bash
+$ docker tag 0e5574283393 fedora/httpd:version1.0
+```
 
-## Tagging an image referenced by Name
+### Tag an image referenced by Name
 
 To tag a local image with name "httpd" into the "fedora" repository with
 "version1.0":
 
-    docker tag httpd fedora/httpd:version1.0
+```bash
+$ docker tag httpd fedora/httpd:version1.0
+```
 
 Note that since the tag name is not specified, the alias is created for an
 existing local version `httpd:latest`.
 
-## Tagging an image referenced by Name and Tag
+### Tag an image referenced by Name and Tag
 
 To tag a local image with name "httpd" and tag "test" into the "fedora"
 repository with "version1.0.test":
 
-    docker tag httpd:test fedora/httpd:version1.0.test
+```bash
+$ docker tag httpd:test fedora/httpd:version1.0.test
+```
 
-## Tagging an image for a private repository
+### Tag an image for a private repository
 
 To push an image to a private registry and not the central Docker
 registry you must tag it with the registry hostname and port (if needed).
 
-    docker tag 0e5574283393 myregistryhost:5000/fedora/httpd:version1.0
+```bash
+$ docker tag 0e5574283393 myregistryhost:5000/fedora/httpd:version1.0
+```
diff --git a/docs/reference/commandline/unpause.md b/docs/reference/commandline/unpause.md
index aa2326f..8915a43 100644
--- a/docs/reference/commandline/unpause.md
+++ b/docs/reference/commandline/unpause.md
@@ -24,6 +24,8 @@
       --help   Print usage
 ```
 
+## Description
+
 The `docker unpause` command un-suspends all processes in the specified containers.
 On Linux, it does this using the cgroups freezer.
 
@@ -31,6 +33,12 @@
 [cgroups freezer documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt)
 for further details.
 
-## Related information
+## Examples
+
+```bash
+$ docker unpause my_container
+```
+
+## Related commands
 
 * [pause](pause.md)
diff --git a/docs/reference/commandline/update.md b/docs/reference/commandline/update.md
index a139004..f41cf39 100644
--- a/docs/reference/commandline/update.md
+++ b/docs/reference/commandline/update.md
@@ -37,6 +37,8 @@
       --restart string              Restart policy to apply when a container exits
 ```
 
+## Description
+
 The `docker update` command dynamically updates container configuration.
 You can use this command to prevent containers from consuming too many
 resources from their Docker host.  With a single command, you can place
diff --git a/docs/reference/commandline/version.md b/docs/reference/commandline/version.md
index cb1bcee..b15d13b 100644
--- a/docs/reference/commandline/version.md
+++ b/docs/reference/commandline/version.md
@@ -25,6 +25,8 @@
       --help            Print usage
 ```
 
+## Description
+
 By default, this will render all version information in an easy to read
 layout. If a format is specified, the given template will be executed instead.
 
@@ -33,35 +35,40 @@
 
 ## Examples
 
-**Default output:**
+### Default output
 
-    $ docker version
-	Client:
-	 Version:      1.8.0
-	 API version:  1.20
-	 Go version:   go1.4.2
-	 Git commit:   f5bae0a
-	 Built:        Tue Jun 23 17:56:00 UTC 2015
-	 OS/Arch:      linux/amd64
+```bash
+$ docker version
 
-	Server:
-	 Version:      1.8.0
-	 API version:  1.20
-	 Go version:   go1.4.2
-	 Git commit:   f5bae0a
-	 Built:        Tue Jun 23 17:56:00 UTC 2015
-	 OS/Arch:      linux/amd64
+Client:
+Version:      1.8.0
+API version:  1.20
+Go version:   go1.4.2
+Git commit:   f5bae0a
+Built:        Tue Jun 23 17:56:00 UTC 2015
+OS/Arch:      linux/amd64
 
-**Get server version:**
+Server:
+Version:      1.8.0
+API version:  1.20
+Go version:   go1.4.2
+Git commit:   f5bae0a
+Built:        Tue Jun 23 17:56:00 UTC 2015
+OS/Arch:      linux/amd64
+```
 
-    {% raw %}
-    $ docker version --format '{{.Server.Version}}'
-	1.8.0
-    {% endraw %}
+### Get the server version
 
-**Dump raw data:**
+```bash
+$ docker version --format '{{.Server.Version}}'
 
-    {% raw %}
-    $ docker version --format '{{json .}}'
-    {"Client":{"Version":"1.8.0","ApiVersion":"1.20","GitCommit":"f5bae0a","GoVersion":"go1.4.2","Os":"linux","Arch":"amd64","BuildTime":"Tue Jun 23 17:56:00 UTC 2015"},"ServerOK":true,"Server":{"Version":"1.8.0","ApiVersion":"1.20","GitCommit":"f5bae0a","GoVersion":"go1.4.2","Os":"linux","Arch":"amd64","KernelVersion":"3.13.2-gentoo","BuildTime":"Tue Jun 23 17:56:00 UTC 2015"}}
-    {% endraw %}
+1.8.0
+```
+
+### Dump raw JSON data
+
+```bash
+$ docker version --format '{{json .}}'
+
+{"Client":{"Version":"1.8.0","ApiVersion":"1.20","GitCommit":"f5bae0a","GoVersion":"go1.4.2","Os":"linux","Arch":"amd64","BuildTime":"Tue Jun 23 17:56:00 UTC 2015"},"ServerOK":true,"Server":{"Version":"1.8.0","ApiVersion":"1.20","GitCommit":"f5bae0a","GoVersion":"go1.4.2","Os":"linux","Arch":"amd64","KernelVersion":"3.13.2-gentoo","BuildTime":"Tue Jun 23 17:56:00 UTC 2015"}}
+```
diff --git a/docs/reference/commandline/volume_create.md b/docs/reference/commandline/volume_create.md
index 9b188a9..b1eed37 100644
--- a/docs/reference/commandline/volume_create.md
+++ b/docs/reference/commandline/volume_create.md
@@ -27,33 +27,51 @@
   -o, --opt value       Set driver specific options (default map[])
 ```
 
-Creates a new volume that containers can consume and store data in. If a name is not specified, Docker generates a random name. You create a volume and then configure the container to use it, for example:
+## Description
+
+Creates a new volume that containers can consume and store data in. If a name is
+not specified, Docker generates a random name.
+
+## Examples
+
+Create a volume and then configure the container to use it:
 
 ```bash
 $ docker volume create hello
+
 hello
 
 $ docker run -d -v hello:/world busybox ls /world
 ```
 
-The mount is created inside the container's `/world` directory. Docker does not support relative paths for mount points inside the container.
+The mount is created inside the container's `/world` directory. Docker does not
+support relative paths for mount points inside the container.
 
-Multiple containers can use the same volume in the same time period. This is useful if two containers need access to shared data. For example, if one container writes and the other reads the data.
+Multiple containers can use the same volume in the same time period. This is
+useful if two containers need access to shared data. For example, if one
+container writes and the other reads the data.
 
-Volume names must be unique among drivers.  This means you cannot use the same volume name with two different drivers.  If you attempt this `docker` returns an error:
+Volume names must be unique among drivers. This means you cannot use the same
+volume name with two different drivers. If you attempt this `docker` returns an
+error:
 
-```
+```none
 A volume named  "hello"  already exists with the "some-other" driver. Choose a different volume name.
 ```
 
-If you specify a volume name already in use on the current driver, Docker assumes you want to re-use the existing volume and does not return an error.   
+If you specify a volume name already in use on the current driver, Docker
+assumes you want to re-use the existing volume and does not return an error.
 
-## Driver specific options
+### Driver-specific options
 
-Some volume drivers may take options to customize the volume creation. Use the `-o` or `--opt` flags to pass driver options:
+Some volume drivers may take options to customize the volume creation. Use the
+`-o` or `--opt` flags to pass driver options:
 
 ```bash
-$ docker volume create --driver fake --opt tardis=blue --opt timey=wimey
+$ docker volume create --driver fake \
+    --opt tardis=blue \
+    --opt timey=wimey \
+    foo
 ```
 
 These options are passed directly to the volume driver. Options for
@@ -61,28 +79,44 @@
 
 The built-in `local` driver on Windows does not support any options.
 
-The built-in `local` driver on Linux accepts options similar to the linux `mount` command. You can provide multiple options by passing the `--opt` flag multiple times. Some `mount` options (such as the `o` option) can take a comma-separated list of options. Complete list of available mount options can be found [here](http://man7.org/linux/man-pages/man8/mount.8.html).
+The built-in `local` driver on Linux accepts options similar to the linux
+`mount` command. You can provide multiple options by passing the `--opt` flag
+multiple times. Some `mount` options (such as the `o` option) can take a
+comma-separated list of options. Complete list of available mount options can be
+found [here](http://man7.org/linux/man-pages/man8/mount.8.html).
 
-For example, the following creates a `tmpfs` volume called `foo` with a size of 100 megabyte and `uid` of 1000.
+For example, the following creates a `tmpfs` volume called `foo` with a size of
+100 megabyte and `uid` of 1000.
 
 ```bash
-$ docker volume create --driver local --opt type=tmpfs --opt device=tmpfs --opt o=size=100m,uid=1000 foo
+$ docker volume create --driver local \
+    --opt type=tmpfs \
+    --opt device=tmpfs \
+    --opt o=size=100m,uid=1000 \
+    foo
 ```
 
 Another example that uses `btrfs`:
 
 ```bash
-$ docker volume create --driver local --opt type=btrfs --opt device=/dev/sda2 foo
+$ docker volume create --driver local \
+    --opt type=btrfs \
+    --opt device=/dev/sda2 \
+    foo
 ```
 
-Another example that uses `nfs` to mount the `/path/to/dir` in `rw` mode from `192.168.1.1`:
+Another example that uses `nfs` to mount the `/path/to/dir` in `rw` mode from
+`192.168.1.1`:
 
 ```bash
-$ docker volume create --driver local --opt type=nfs --opt o=addr=192.168.1.1,rw --opt device=:/path/to/dir foo
+$ docker volume create --driver local \
+    --opt type=nfs \
+    --opt o=addr=192.168.1.1,rw \
+    --opt device=:/path/to/dir \
+    foo
 ```
 
-
-## Related information
+## Related commands
 
 * [volume inspect](volume_inspect.md)
 * [volume ls](volume_ls.md)
diff --git a/docs/reference/commandline/volume_inspect.md b/docs/reference/commandline/volume_inspect.md
index 98e0ee5..bbdc6bd 100644
--- a/docs/reference/commandline/volume_inspect.md
+++ b/docs/reference/commandline/volume_inspect.md
@@ -25,32 +25,34 @@
       --help            Print usage
 ```
 
+## Description
+
 Returns information about a volume. By default, this command renders all results
 in a JSON array. You can specify an alternate format to execute a
 given template for each result. Go's
 [text/template](http://golang.org/pkg/text/template/) package describes all the
 details of the format.
 
-Example output:
+## Examples
 
-    $ docker volume create
-    85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d
-    $ docker volume inspect 85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d
-    [
-      {
-          "Name": "85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d",
-          "Driver": "local",
-          "Mountpoint": "/var/lib/docker/volumes/85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d/_data",
-          "Status": null
-      }
-    ]
+```bash
+$ docker volume create
+85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d
+$ docker volume inspect 85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d
+[
+  {
+      "Name": "85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d",
+      "Driver": "local",
+      "Mountpoint": "/var/lib/docker/volumes/85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d/_data",
+      "Status": null
+  }
+]
 
-    {% raw %}
-    $ docker volume inspect --format '{{ .Mountpoint }}' 85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d
-    /var/lib/docker/volumes/85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d/_data
-    {% endraw %}
+$ docker volume inspect --format '{{ .Mountpoint }}' 85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d
+/var/lib/docker/volumes/85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d/_data
+```
 
-## Related information
+## Related commands
 
 * [volume create](volume_create.md)
 * [volume ls](volume_ls.md)
diff --git a/docs/reference/commandline/volume_ls.md b/docs/reference/commandline/volume_ls.md
index 90ecef2..c35e662 100644
--- a/docs/reference/commandline/volume_ls.md
+++ b/docs/reference/commandline/volume_ls.md
@@ -34,22 +34,32 @@
   -q, --quiet          Only display volume names
 ```
 
-List all the volumes Docker knows about. You can filter using the `-f` or `--filter` flag. Refer to the [filtering](#filtering) section for more information about available filter options.
+## Description
 
-Example output:
+List all the volumes known to Docker. You can filter using the `-f` or
+`--filter` flag. Refer to the [filtering](#filtering) section for more
+information about available filter options.
 
+## Examples
+
+### Create a volume
 ```bash
 $ docker volume create rosemary
+
 rosemary
-$docker volume create tyler
+
+$ docker volume create tyler
+
 tyler
+
 $ docker volume ls
+
 DRIVER              VOLUME NAME
 local               rosemary
 local               tyler
 ```
 
-## Filtering
+### Filtering
 
 The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more
 than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`)
@@ -61,7 +71,7 @@
 * label (`label=<key>` or `label=<key>=<value>`)
 * name (a volume's name)
 
-### dangling
+#### dangling
 
 The `dangling` filter matches on all volumes not referenced by any containers
 
@@ -74,7 +84,7 @@
 local               rosemary
 ```
 
-### driver
+#### driver
 
 The `driver` filter matches on all or part of a volume's driver name.
 
@@ -88,7 +98,7 @@
 local               tyler
 ```
 
-#### Label
+#### label
 
 The `label` filter matches volumes based on the presence of a `label` alone or
 a `label` and a value.
@@ -97,8 +107,10 @@
 
 ```bash
 $ docker volume create the-doctor --label is-timelord=yes
+
 the-doctor
 $ docker volume create daleks --label is-timelord=no
+
 daleks
 ```
 
@@ -113,7 +125,7 @@
 local               the-doctor
 ```
 
-As can be seen in the above example, both volumes with `is-timelord=yes`, and
+As the above example demonstrates, both volumes with `is-timelord=yes`, and
 `is-timelord=no` are returned.
 
 Filtering on both `key` *and* `value` of the label, produces the expected result:
@@ -134,17 +146,20 @@
 DRIVER              VOLUME NAME
 ```
 
-### name
+#### name
 
 The `name` filter matches on all or part of a volume's name.
 
 The following filter matches all volumes with a name containing the `rose` string.
 
-    $ docker volume ls -f name=rose
-    DRIVER              VOLUME NAME
-    local               rosemary
+```bash
+$ docker volume ls -f name=rose
 
-## Formatting
+DRIVER              VOLUME NAME
+local               rosemary
+```
+
+### Formatting
 
 The formatting options (`--format`) pretty-prints volumes output
 using a Go template.
@@ -169,12 +184,13 @@
 
 ```bash
 $ docker volume ls --format "{{.Name}}: {{.Driver}}"
+
 vol1: local
 vol2: local
 vol3: local
 ```
 
-## Related information
+## Related commands
 
 * [volume create](volume_create.md)
 * [volume inspect](volume_inspect.md)
diff --git a/docs/reference/commandline/volume_prune.md b/docs/reference/commandline/volume_prune.md
index d910a49..a9c4b70 100644
--- a/docs/reference/commandline/volume_prune.md
+++ b/docs/reference/commandline/volume_prune.md
@@ -25,12 +25,15 @@
       --help    Print usage
 ```
 
+## Description
+
 Remove all unused volumes. Unused volumes are those which are not referenced by any containers
 
-Example output:
+## Examples
 
 ```bash
 $ docker volume prune
+
 WARNING! This will remove all volumes not used by at least one container.
 Are you sure you want to continue? [y/N] y
 Deleted Volumes:
@@ -40,7 +43,7 @@
 Total reclaimed space: 36 B
 ```
 
-## Related information
+## Related commands
 
 * [volume create](volume_create.md)
 * [volume ls](volume_ls.md)
diff --git a/docs/reference/commandline/volume_rm.md b/docs/reference/commandline/volume_rm.md
index 1bf9dba..a1f2d3b 100644
--- a/docs/reference/commandline/volume_rm.md
+++ b/docs/reference/commandline/volume_rm.md
@@ -28,12 +28,18 @@
       --help   Print usage
 ```
 
+## Description
+
 Remove one or more volumes. You cannot remove a volume that is in use by a container.
 
-    $ docker volume rm hello
-    hello
+## Examples
 
-## Related information
+```bash
+  $ docker volume rm hello
+  hello
+```
+
+## Related commands
 
 * [volume create](volume_create.md)
 * [volume inspect](volume_inspect.md)
diff --git a/docs/reference/commandline/wait.md b/docs/reference/commandline/wait.md
index a07b82b..ee8f9ab 100644
--- a/docs/reference/commandline/wait.md
+++ b/docs/reference/commandline/wait.md
@@ -23,3 +23,36 @@
 Options:
       --help   Print usage
 ```
+
+> **Note**: `docker wait` returns `0` when run against a container which had
+> already exited before the `docker wait` command was run.
+
+## Examples
+
+Start a container in the background.
+
+```bash
+$ docker run -dit --name=my_container ubuntu bash
+```
+
+Run `docker wait`, which should block until the container exits.
+
+```bash
+$ docker wait my_container
+```
+
+In another terminal, stop the first container. The `docker wait` command above
+returns the exit code.
+
+```bash
+$ docker stop my_container
+```
+
+This is the same `docker wait` command from above, but it now exits, returning
+`0`.
+
+```bash
+$ docker wait my_container
+
+0
+```
diff --git a/docs/yaml/Dockerfile b/docs/yaml/Dockerfile
new file mode 100644
index 0000000..059b97a
--- /dev/null
+++ b/docs/yaml/Dockerfile
@@ -0,0 +1,4 @@
+FROM scratch
+COPY docs /docs
+# CMD cannot be nil so we set it to empty string
+CMD  [""]
diff --git a/docs/yaml/generate.go b/docs/yaml/generate.go
new file mode 100644
index 0000000..ea5c00e
--- /dev/null
+++ b/docs/yaml/generate.go
@@ -0,0 +1,86 @@
+package main
+
+import (
+	"fmt"
+	"io/ioutil"
+	"log"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/docker/docker/cli/command"
+	"github.com/docker/docker/cli/command/commands"
+	"github.com/docker/docker/pkg/term"
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+const descriptionSourcePath = "docs/reference/commandline/"
+
+func generateCliYaml(opts *options) error {
+	stdin, stdout, stderr := term.StdStreams()
+	dockerCli := command.NewDockerCli(stdin, stdout, stderr)
+	cmd := &cobra.Command{Use: "docker"}
+	commands.AddCommands(cmd, dockerCli)
+	source := filepath.Join(opts.source, descriptionSourcePath)
+	if err := loadLongDescription(cmd, source); err != nil {
+		return err
+	}
+
+	cmd.DisableAutoGenTag = true
+	return GenYamlTree(cmd, opts.target)
+}
+
+func loadLongDescription(cmd *cobra.Command, path ...string) error {
+	for _, cmd := range cmd.Commands() {
+		if cmd.Name() == "" {
+			continue
+		}
+		fullpath := filepath.Join(path[0], strings.Join(append(path[1:], cmd.Name()), "_")+".md")
+
+		if cmd.HasSubCommands() {
+			loadLongDescription(cmd, path[0], cmd.Name())
+		}
+
+		if _, err := os.Stat(fullpath); err != nil {
+			log.Printf("WARN: %s does not exist, skipping\n", fullpath)
+			continue
+		}
+
+		content, err := ioutil.ReadFile(fullpath)
+		if err != nil {
+			return err
+		}
+		description, examples := parseMDContent(string(content))
+		cmd.Long = description
+		cmd.Example = examples
+	}
+	return nil
+}
+
+type options struct {
+	source string
+	target string
+}
+
+func parseArgs() (*options, error) {
+	opts := &options{}
+	cwd, _ := os.Getwd()
+	flags := pflag.NewFlagSet(os.Args[0], pflag.ContinueOnError)
+	flags.StringVar(&opts.source, "root", cwd, "Path to project root")
+	flags.StringVar(&opts.target, "target", "/tmp", "Target path for generated yaml files")
+	err := flags.Parse(os.Args[1:])
+	return opts, err
+}
+
+func main() {
+	opts, err := parseArgs()
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err.Error())
+	}
+	fmt.Printf("Project root: %s\n", opts.source)
+	fmt.Printf("Generating yaml files into %s\n", opts.target)
+	if err := generateCliYaml(opts); err != nil {
+		fmt.Fprintf(os.Stderr, "Failed to generate yaml files: %s\n", err.Error())
+	}
+}
diff --git a/docs/yaml/yaml.go b/docs/yaml/yaml.go
new file mode 100644
index 0000000..575f9be
--- /dev/null
+++ b/docs/yaml/yaml.go
@@ -0,0 +1,212 @@
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+	"gopkg.in/yaml.v2"
+)
+
+type cmdOption struct {
+	Option       string
+	Shorthand    string `yaml:",omitempty"`
+	DefaultValue string `yaml:"default_value,omitempty"`
+	Description  string `yaml:",omitempty"`
+}
+
+type cmdDoc struct {
+	Name             string      `yaml:"command"`
+	SeeAlso          []string    `yaml:"parent,omitempty"`
+	Version          string      `yaml:"engine_version,omitempty"`
+	Aliases          string      `yaml:",omitempty"`
+	Short            string      `yaml:",omitempty"`
+	Long             string      `yaml:",omitempty"`
+	Usage            string      `yaml:",omitempty"`
+	Pname            string      `yaml:",omitempty"`
+	Plink            string      `yaml:",omitempty"`
+	Cname            []string    `yaml:",omitempty"`
+	Clink            []string    `yaml:",omitempty"`
+	Options          []cmdOption `yaml:",omitempty"`
+	InheritedOptions []cmdOption `yaml:"inherited_options,omitempty"`
+	Example          string      `yaml:"examples,omitempty"`
+}
+
+// GenYamlTree creates yaml structured ref files
+func GenYamlTree(cmd *cobra.Command, dir string) error {
+	identity := func(s string) string { return s }
+	emptyStr := func(s string) string { return "" }
+	return GenYamlTreeCustom(cmd, dir, emptyStr, identity)
+}
+
+// GenYamlTreeCustom creates yaml structured ref files
+func GenYamlTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHandler func(string) string) error {
+	for _, c := range cmd.Commands() {
+		if !c.IsAvailableCommand() || c.IsHelpCommand() {
+			continue
+		}
+		if err := GenYamlTreeCustom(c, dir, filePrepender, linkHandler); err != nil {
+			return err
+		}
+	}
+
+	basename := strings.Replace(cmd.CommandPath(), " ", "_", -1) + ".yaml"
+	filename := filepath.Join(dir, basename)
+	f, err := os.Create(filename)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+
+	if _, err := io.WriteString(f, filePrepender(filename)); err != nil {
+		return err
+	}
+	if err := GenYamlCustom(cmd, f, linkHandler); err != nil {
+		return err
+	}
+	return nil
+}
+
+// GenYamlCustom creates custom yaml output
+func GenYamlCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string) string) error {
+	cliDoc := cmdDoc{}
+	cliDoc.Name = cmd.CommandPath()
+
+	// Check experimental: ok := cmd.Tags["experimental"]
+
+	cliDoc.Aliases = strings.Join(cmd.Aliases, ", ")
+	cliDoc.Short = cmd.Short
+	cliDoc.Long = cmd.Long
+	if len(cliDoc.Long) == 0 {
+		cliDoc.Long = cliDoc.Short
+	}
+
+	if cmd.Runnable() {
+		cliDoc.Usage = cmd.UseLine()
+	}
+
+	if len(cmd.Example) > 0 {
+		cliDoc.Example = cmd.Example
+	}
+
+	flags := cmd.NonInheritedFlags()
+	if flags.HasFlags() {
+		cliDoc.Options = genFlagResult(flags)
+	}
+	flags = cmd.InheritedFlags()
+	if flags.HasFlags() {
+		cliDoc.InheritedOptions = genFlagResult(flags)
+	}
+
+	if hasSeeAlso(cmd) {
+		if cmd.HasParent() {
+			parent := cmd.Parent()
+			cliDoc.Pname = parent.CommandPath()
+			link := cliDoc.Pname + ".yaml"
+			cliDoc.Plink = strings.Replace(link, " ", "_", -1)
+			cmd.VisitParents(func(c *cobra.Command) {
+				if c.DisableAutoGenTag {
+					cmd.DisableAutoGenTag = c.DisableAutoGenTag
+				}
+			})
+		}
+
+		children := cmd.Commands()
+		sort.Sort(byName(children))
+
+		for _, child := range children {
+			if !child.IsAvailableCommand() || child.IsHelpCommand() {
+				continue
+			}
+			currentChild := cliDoc.Name + " " + child.Name()
+			cliDoc.Cname = append(cliDoc.Cname, cliDoc.Name+" "+child.Name())
+			link := currentChild + ".yaml"
+			cliDoc.Clink = append(cliDoc.Clink, strings.Replace(link, " ", "_", -1))
+		}
+	}
+
+	final, err := yaml.Marshal(&cliDoc)
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+	if _, err := fmt.Fprintln(w, string(final)); err != nil {
+		return err
+	}
+	return nil
+}
+
+func genFlagResult(flags *pflag.FlagSet) []cmdOption {
+	var result []cmdOption
+
+	flags.VisitAll(func(flag *pflag.Flag) {
+		// Todo, when we mark a shorthand is deprecated, but specify an empty message.
+		// The flag.ShorthandDeprecated is empty as the shorthand is deprecated.
+		// Using len(flag.ShorthandDeprecated) > 0 can't handle this, others are ok.
+		if !(len(flag.ShorthandDeprecated) > 0) && len(flag.Shorthand) > 0 {
+			opt := cmdOption{
+				Option:       flag.Name,
+				Shorthand:    flag.Shorthand,
+				DefaultValue: flag.DefValue,
+				Description:  forceMultiLine(flag.Usage),
+			}
+			result = append(result, opt)
+		} else {
+			opt := cmdOption{
+				Option:       flag.Name,
+				DefaultValue: forceMultiLine(flag.DefValue),
+				Description:  forceMultiLine(flag.Usage),
+			}
+			result = append(result, opt)
+		}
+	})
+
+	return result
+}
+
+// Temporary workaround for yaml lib generating incorrect yaml with long strings
+// that do not contain \n.
+func forceMultiLine(s string) string {
+	if len(s) > 60 && !strings.Contains(s, "\n") {
+		s = s + "\n"
+	}
+	return s
+}
+
+// Small duplication for cobra utils
+func hasSeeAlso(cmd *cobra.Command) bool {
+	if cmd.HasParent() {
+		return true
+	}
+	for _, c := range cmd.Commands() {
+		if !c.IsAvailableCommand() || c.IsHelpCommand() {
+			continue
+		}
+		return true
+	}
+	return false
+}
+
+func parseMDContent(mdString string) (description string, examples string) {
+	parsedContent := strings.Split(mdString, "\n## ")
+	for _, s := range parsedContent {
+		if strings.Index(s, "Description") == 0 {
+			description = strings.Trim(s, "Description\n")
+		}
+		if strings.Index(s, "Examples") == 0 {
+			examples = strings.Trim(s, "Examples\n")
+		}
+	}
+	return
+}
+
+type byName []*cobra.Command
+
+func (s byName) Len() int           { return len(s) }
+func (s byName) Swap(i, j int)      { s[i], s[j] = s[j], s[i] }
+func (s byName) Less(i, j int) bool { return s[i].Name() < s[j].Name() }
diff --git a/hack/make/yaml-docs-generator b/hack/make/yaml-docs-generator
new file mode 100644
index 0000000..8548dee
--- /dev/null
+++ b/hack/make/yaml-docs-generator
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -e
+
+[ -z "$KEEPDEST" ] && \
+	rm -rf "$DEST"
+
+(
+	source "${MAKEDIR}/.binary-setup"
+	export BINARY_SHORT_NAME="yaml-docs-generator"
+	export GO_PACKAGE='github.com/docker/docker/docs/yaml'
+	source "${MAKEDIR}/.binary"
+)
diff --git a/hooks/post_build b/hooks/post_build
new file mode 100755
index 0000000..5281707
--- /dev/null
+++ b/hooks/post_build
@@ -0,0 +1,19 @@
+#!/bin/bash
+
+if [ -n "${BUILD_DOCS}" ]; then
+	set -e
+	DOCS_IMAGE=${DOCS_IMAGE:-${IMAGE_NAME}-docs}
+	docker run \
+		--entrypoint '' \
+		--privileged \
+		-e DOCKER_GITCOMMIT=$(git rev-parse --short HEAD) \
+		-v $(pwd)/docs/yaml/docs:/docs \
+		"${IMAGE_NAME}" \
+		sh -c 'hack/make.sh yaml-docs-generator && bundles/latest/yaml-docs-generator/yaml-docs-generator --target /docs'
+
+	(
+		cd docs/yaml
+		docker build -t ${DOCS_IMAGE} .
+		docker push ${DOCS_IMAGE}
+	)
+fi