compose-file: add missing code-hints, sync formatting between versions

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

compose/compose-file/compose-file-v1.md

@@ -27,7 +27,8 @@ The Version 1 Compose file is a [YAML](http://yaml.org/) file that defines [serv
 
 The default path for a Compose file is `./docker-compose.yml`.
 
->**Tip**: You can use either a `.yml` or `.yaml` extension for this file. They both work.
+> **Tip**: You can use either a `.yml` or `.yaml` extension for this file.
+> They both work.
 
 A service definition contains configuration which is applied to each
 container started for that service, much like passing command-line parameters to
@@ -47,17 +48,19 @@ Configuration options that are applied at build time.
 `build` can specified as a string containing a path to the build
 context.
 
+```yaml
 build: ./dir
+```
 
 > **Note**
 >
-> In [version 1 file format](compose-versioning.md#version-1),
+> In [version 1 file format](compose-versioning.md#version-1), `build` is
-`build` is  different in two ways:
+> different in two ways:
 >
 > * Only the string form (`build: .`) is allowed - not the object
 >   form that is allowed in Version 2 and up.
 > * Using `build` together with [`image`](#image) is not allowed.
-Attempting to do so results in an error.
+>   Attempting to do so results in an error.
 
 #### dockerfile
 
@@ -66,28 +69,33 @@ Alternate Dockerfile.
 Compose uses an alternate file to build with. A build path must also be
 specified.
 
+```yaml
 build: .
 dockerfile: Dockerfile-alternate
+```
 
 > **Note**
 >
-> In the [version 1 file format](compose-versioning.md#version-1), `dockerfile` is different from newer versions in two ways:
+> In the [version 1 file format](compose-versioning.md#version-1), `dockerfile`
+> is different from newer versions in two ways:
 >
 > * It appears alongside `build`, not as a sub-option:
->
+> * Using `dockerfile` together with [`image`](#image) is not allowed.
->*  Using `dockerfile` together with [`image`](#image) is not allowed. Attempting to do so results in an error.
+>   Attempting to do so results in an error.
 
 ### cap_add, cap_drop
 
 Add or drop container capabilities.
 See `man 7 capabilities` for a full list.
 
+```yaml
 cap_add:
   - ALL
 
 cap_drop:
   - NET_ADMIN
   - SYS_ADMIN
+```
 
 > **Note**: These options are ignored when
 > [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
@@ -97,24 +105,32 @@ See `man 7 capabilities` for a full list.
 
 Override the default command.
 
+```yaml
 command: bundle exec thin -p 3000
+```
 
 The command can also be a list, in a manner similar to
 [dockerfile](/engine/reference/builder.md#cmd):
 
+```yaml
 command: ["bundle", "exec", "thin", "-p", "3000"]
+```
 
 ### cgroup_parent
 
 Specify an optional parent cgroup for the container.
 
+```yaml
 cgroup_parent: m-executor-abcd
+```
 
 ### container_name
 
 Specify a custom container name, rather than a generated default name.
 
+```yaml
 container_name: my-web-container
+```
 
 Because Docker container names must be unique, you cannot scale a service
 beyond 1 container if you have specified a custom name. Attempting to do so
@@ -125,36 +141,51 @@ results in an error.
 List of device mappings.  Uses the same format as the `--device` docker
 client create option.
 
+```yaml
 devices:
   - "/dev/ttyUSB0:/dev/ttyUSB0"
+```
 
 ### dns
 
 Custom DNS servers. Can be a single value or a list.
 
+```yaml
 dns: 8.8.8.8
+```
+
+```yaml
 dns:
   - 8.8.8.8
   - 9.9.9.9
+```
 
 ### dns_search
 
 Custom DNS search domains. Can be a single value or a list.
 
+```yaml
 dns_search: example.com
+```
+
+```yaml
 dns_search:
   - dc1.example.com
   - dc2.example.com
+```
 
 ### entrypoint
 
 Override the default entrypoint.
 
+```yaml
 entrypoint: /code/entrypoint.sh
+```
 
 The entrypoint can also be a list, in a manner similar to
 [dockerfile](/engine/reference/builder.md#entrypoint):
 
+```yaml
 entrypoint:
   - php
   - -d
@@ -162,6 +193,7 @@ The entrypoint can also be a list, in a manner similar to
   - -d
   - memory_limit=-1
   - vendor/bin/phpunit
+```
 
 > **Note**: Setting `entrypoint` both overrides any default entrypoint set
 > on the service's image with the `ENTRYPOINT` Dockerfile instruction, *and*
@@ -175,22 +207,29 @@ Add environment variables from a file. Can be a single value or a list.
 If you have specified a Compose file with `docker-compose -f FILE`, paths in
 `env_file` are relative to the directory that file is in.
 
-Environment variables specified in [environment](#environment) _override_
+Environment variables declared in the [environment](#environment) section
-these values.
+_override_ these values – this holds true even if those values are
+empty or undefined.
 
+```yaml
 env_file: .env
+```
 
+```yaml
 env_file:
   - ./common.env
   - ./apps/web.env
-      - /opt/secrets.env
+  - /opt/runtime_opts.env
+```
 
 Compose expects each line in an env file to be in `VAR=VAL` format. Lines
 beginning with `#` are processed as comments and are ignored. Blank lines are
 also ignored.
 
+```console
 # Set Rails/Rack environment
 RACK_ENV=development
+```
 
 > **Note**: If your service specifies a [build](#build) option, variables
 > defined in environment files are _not_ automatically visible during the
@@ -217,38 +256,42 @@ services:
 
 And the following files:
 
-```none
+```console
 # a.env
 VAR=1
 ```
 
 and
 
-```none
+```console
 # b.env
 VAR=hello
 ```
 
-$VAR is `hello`.
+`$VAR` is `hello`.
 
 ### environment
 
 Add environment variables. You can use either an array or a dictionary. Any
-boolean values; true, false, yes no, need to be enclosed in quotes to ensure
+boolean values (true, false, yes, no) need to be enclosed in quotes to ensure
 they are not converted to True or False by the YML parser.
 
 Environment variables with only a key are resolved to their values on the
 machine Compose is running on, which can be helpful for secret or host-specific values.
 
+```yaml
 environment:
   RACK_ENV: development
   SHOW: 'true'
   SESSION_SECRET:
+```
 
+```yaml
 environment:
   - RACK_ENV=development
   - SHOW=true
   - SESSION_SECRET
+```
 
 > **Note**: If your service specifies a [build](#build) option, variables
 > defined in `environment` are _not_ automatically visible during the
@@ -259,9 +302,11 @@ machine Compose is running on, which can be helpful for secret or host-specific
 Expose ports without publishing them to the host machine - they'll only be
 accessible to linked services. Only the internal port can be specified.
 
+```yaml
 expose:
   - "3000"
   - "8000"
+```
 
 ### extends
 
@@ -272,9 +317,11 @@ You can use `extends` on any service together with other configuration keys.
 The `extends` value must be a dictionary defined with a required `service`
 and an optional `file` key.
 
+```yaml
 extends:
   file: common.yml
   service: webapp
+```
 
 The `service` the name of the service being extended, for example
 `web` or `database`. The `file` is the location of a Compose configuration
@@ -294,46 +341,63 @@ For more on `extends`, see the
 
 ### external_links
 
-Link to containers started outside this `docker-compose.yml` or even outside
+Link to containers started outside this `docker-compose.yml` or even outside of
-of Compose, especially for containers that provide shared or common services.
+Compose, especially for containers that provide shared or common services.
-`external_links` follow semantics similar to `links` when specifying both the
+`external_links` follow semantics similar to `links` when
-container name and the link alias (`CONTAINER:ALIAS`).
+specifying both the container name and the link alias (`CONTAINER:ALIAS`).
 
+```yaml
 external_links:
   - redis_1
   - project_db_1:mysql
   - project_db_1:postgresql
+```
 
 ### extra_hosts
 
 Add hostname mappings. Use the same values as the docker client `--add-host` parameter.
 
+```yaml
 extra_hosts:
   - "somehost:162.242.195.82"
   - "otherhost:50.31.209.229"
+```
 
 An entry with the ip address and hostname is created in `/etc/hosts` inside containers for this service, e.g:
 
+```console
 162.242.195.82  somehost
 50.31.209.229   otherhost
+```
 
 ### image
 
 Specify the image to start the container from. Can either be a repository/tag or
 a partial image ID.
 
+```yaml
 image: redis
-    image: ubuntu:14.04
+```
+```yaml
+image: ubuntu:18.04
+```
+```yaml
 image: tutum/influxdb
+```
+```yaml
 image: example-registry.com:4000/postgresql
+```
+```yaml
 image: a4bc65fd
+```
 
 If the image does not exist, Compose attempts to pull it, unless you have also
 specified [build](#build), in which case it builds it using the specified
 options and tags it with the specified tag.
 
-> **Note**: In the [version 1 file format](compose-versioning.md#version-1), using [`build`](#build) together
+> **Note**: In the [version 1 file format](compose-versioning.md#version-1),
-> with `image` is not allowed. Attempting to do so results in an error.
+> using [`build`](#build) together with `image` is not allowed. Attempting to do
+> so results in an error.
 
 ### labels
 
@@ -341,29 +405,35 @@ Add metadata to containers using [Docker labels](/engine/userguide/labels-custom
 
 It's recommended that you use reverse-DNS notation to prevent your labels from conflicting with those used by other software.
 
+```yaml
 labels:
   com.example.description: "Accounting webapp"
   com.example.department: "Finance"
   com.example.label-with-empty-value: ""
+```
 
+```yaml
 labels:
   - "com.example.description=Accounting webapp"
   - "com.example.department=Finance"
   - "com.example.label-with-empty-value"
+```
 
 ### links
 
 Link to containers in another service. Either specify both the service name and
-a link alias (`SERVICE:ALIAS`), or just the service name.
+a link alias (`"SERVICE:ALIAS"`), or just the service name.
 
 > Links are a legacy option. We recommend using
 > [networks](#networks) instead.
 
+```yaml
 web:
   links:
-       - db
+    - "db"
-       - db:database
+    - "db:database"
-       - redis
+    - "redis"
+```
 
 Containers for the linked service are reachable at a hostname identical to
 the alias, or the service name if no alias was specified.
@@ -371,7 +441,9 @@ the alias, or the service name if no alias was specified.
 Links also express dependency between services in the same way as
 [depends_on](#depends_on), so they determine the order of service startup.
 
-> **Note**: If you define both links and [networks](#networks), services with
+> **Note**
+>
+> If you define both links and [networks](#networks), services with
 > links between them must share at least one network in common in order to
 > communicate.
 
@@ -382,7 +454,9 @@ Links also express dependency between services in the same way as
 
 Specify a log driver. The default is `json-file`.
 
+```yaml
 log_driver: syslog
+```
 
 ### log_opt
 
@@ -391,8 +465,10 @@ Specify a log driver. The default is `json-file`.
 
 Specify logging options as key-value pairs. An example of `syslog` options:
 
+```yaml
 log_opt:
   syslog-address: "tcp://192.168.0.42:123"
+```
 
 ### net
 
@@ -403,14 +479,27 @@ Network mode. Use the same values as the docker client `--net` parameter.
 The `container:...` form can take a service name instead of a container name or
 id.
 
+```yaml
 net: "bridge"
+```
+```yaml
 net: "host"
+```
+```yaml
 net: "none"
-    net: "container:[service name or container name/id]"
+```
+```yaml
+net: "service:[service name]"
+```
+```yaml
+net: "container:[container name/id]"
+```
 
 ### pid
 
+```yaml
 pid: "host"
+```
 
 Sets the PID mode to the host PID mode. This turns on sharing between
 container and the host operating system the PID address space. Containers
@@ -427,6 +516,7 @@ port (an ephemeral host port is chosen).
 > parses numbers in the format `xx:yy` as a base-60 value. For this reason,
 > we recommend always explicitly specifying your port mappings as strings.
 
+```yaml
 ports:
   - "3000"
   - "3000-3005"
@@ -436,14 +526,18 @@ port (an ephemeral host port is chosen).
   - "127.0.0.1:8001:8001"
   - "127.0.0.1:5000-5010:5000-5010"
   - "6060:6060/udp"
+  - "12400-12500:1240"
+```
 
 ### security_opt
 
 Override the default labeling scheme for each container.
 
+```yaml
 security_opt:
   - label:user:USER
   - label:role:ROLE
+```
 
 ### stop_signal
 
@@ -451,19 +545,22 @@ Sets an alternative signal to stop the container. By default `stop` uses
 SIGTERM. Setting an alternative signal using `stop_signal` causes
 `stop` to send that signal instead.
 
+```yaml
 stop_signal: SIGUSR1
+```
 
 ### ulimits
 
 Override the default ulimits for a container. You can either specify a single
 limit as an integer or soft/hard limits as a mapping.
 
-
+```yaml
 ulimits:
   nproc: 65535
   nofile:
     soft: 20000
     hard: 40000
+```
 
 ### volumes, volume\_driver
 
@@ -478,6 +575,7 @@ You can mount a relative path on the host, which expands relative to
 the directory of the Compose configuration file being used. Relative paths
 should always begin with `.` or `..`.
 
+```yaml
 volumes:
   # Just specify a path and let the Engine create a volume
   - /var/lib/mysql
@@ -493,17 +591,19 @@ should always begin with `.` or `..`.
 
   # Named volume
   - datavolume:/var/lib/mysql
+```
 
 If you do not use a host path, you may specify a `volume_driver`.
 
+```yaml
 volume_driver: mydriver
+```
 
 There are several things to note, depending on which
 [Compose file version](compose-versioning#versioning) you're using:
 
 - For [version 1 files](compose-versioning#version-1), both named volumes and
   container volumes use the specified driver.
-
 - No path expansion is done if you have also specified a `volume_driver`.
   For example, if you specify a mapping of `./foo:/data`, the `./foo` part
   is passed straight to the volume driver without being expanded.
@@ -517,15 +617,18 @@ Mount all of the volumes from another service or container, optionally
 specifying read-only access (``ro``) or read-write (``rw``). If no access level
 is specified, then read-write is used.
 
+```yaml
 volumes_from:
   - service_name
   - service_name:ro
+```
 
 ### cpu\_shares, cpu\_quota, cpuset, domainname, hostname, ipc, mac\_address, mem\_limit, memswap\_limit, mem\_swappiness, privileged, read\_only, restart, shm\_size, stdin\_open, tty, user, working\_dir
 
 Each of these is a single value, analogous to its
 [docker run](/engine/reference/run.md) counterpart.
 
+```yaml
 cpu_shares: 73
 cpu_quota: 50000
 cpuset: 0,1
@@ -548,13 +651,12 @@ Each of these is a single value, analogous to its
 shm_size: 64M
 stdin_open: true
 tty: true
+```
 
 ## Compose documentation
 
 - [User guide](/compose/index.md)
-- [Installing Compose](/compose/install/)
+- [Installing Compose](/compose/install.md)
 - [Compose file versions and upgrading](compose-versioning.md)
-- [Get started with Django](/compose/django/)
+- [Samples](/samples/)
-- [Get started with Rails](/compose/rails/)
-- [Get started with WordPress](/compose/wordpress/)
 - [Command line reference](/compose/reference/)

compose/compose-file/index.md

@@ -3,7 +3,7 @@ description: Compose file reference
 keywords: fig, composition, compose, docker
 redirect_from:
 - /compose/yml
-- /compose/compose-file-v3.md
+- /compose/compose-file-v3/
 title: Compose file version 3 reference
 toc_max: 4
 toc_min: 1
@@ -147,20 +147,20 @@ The Compose file is a [YAML](http://yaml.org/) file defining
 The default path for a Compose file is `./docker-compose.yml`.
 
 > **Tip**: You can use either a `.yml` or `.yaml` extension for this file.
-They both work.
+> They both work.
 
 A service definition contains configuration that is applied to each
 container started for that service, much like passing command-line parameters to
-`docker container create`. Likewise, network and volume definitions are analogous to
+`docker run`. Likewise, network and volume definitions are analogous to
 `docker network create` and `docker volume create`.
 
-As with `docker container create`, options specified in the Dockerfile, such as `CMD`,
+As with `docker run`, options specified in the Dockerfile, such as `CMD`,
 `EXPOSE`, `VOLUME`, `ENV`, are respected by default - you don't need to
 specify them again in `docker-compose.yml`.
 
 You can use environment variables in configuration values with a Bash-like
-`${VARIABLE}` syntax - see
+`${VARIABLE}` syntax - see [variable substitution](#variable-substitution) for
-[variable substitution](#variable-substitution) for full details.
+full details.
 
 This section contains a list of all configuration options supported by a service
 definition in version 3.
@@ -243,7 +243,7 @@ build process.
 
 First, specify the arguments in your Dockerfile:
 
-```Dockerfile
+```dockerfile
 ARG buildno
 ARG gitcommithash
 
@@ -289,7 +289,7 @@ args:
 
 #### cache_from
 
-> **Note**: This option is new in v3.2
+> Added in [version 3.2](compose-versioning.md#version-32) file format
 
 A list of images that the engine uses for cache resolution.
 
@@ -303,13 +303,13 @@ build:
 
 #### labels
 
-> **Note**: This option is new in v3.3
+> Added in [version 3.3](compose-versioning.md#version-33) file format
 
 Add metadata to the resulting image using [Docker labels](/engine/userguide/labels-custom-metadata.md).
 You can use either an array or a dictionary.
 
-We recommend that you use reverse-DNS notation to prevent your labels from conflicting with
+It's recommended that you use reverse-DNS notation to prevent your labels from
-those used by other software.
+conflicting with those used by other software.
 
 ```yaml
 build:
@@ -520,7 +520,8 @@ an error.
 
 ### credential_spec
 
-> **Note**: This option was added in v3.3. Using group Managed Service Account (gMSA) configurations with compose files is supported in Compose version 3.8.
+> **Note**: This option was added in v3.3. Using group Managed Service Account
+> (gMSA) configurations with compose files is supported in Compose version 3.8.
 
 Configure the credential spec for managed service account. This option is only
 used for services using Windows containers. The `credential_spec` must be in the
@@ -552,8 +553,9 @@ credential_spec:
 #### Example gMSA configuration
 When configuring a gMSA credential spec for a service, you only need
 to specify a credential spec with `config`, as shown in the following example:
-```
+
-version: "3.8"
+```yaml
+version: "{{ site.compose_file_v3 }}"
 services:
   myservice:
     image: myimage:latest
@@ -567,16 +569,14 @@ configs:
 
 ### depends_on
 
-Express dependency between services, Service dependencies cause the following
+Express dependency between services. Service dependencies cause the following
 behaviors:
 
 - `docker-compose up` starts services in dependency order. In the following
   example, `db` and `redis` are started before `web`.
-
 - `docker-compose up SERVICE` automatically includes `SERVICE`'s
-  dependencies. In the following example, `docker-compose up web` also
+  dependencies. In the example below, `docker-compose up web` also
   creates and starts `db` and `redis`.
-
 - `docker-compose stop` stops services in dependency order. In the following
   example, `web` is stopped before `db` and `redis`.
 
@@ -602,9 +602,7 @@ services:
 >   starting `web` - only until they have been started. If you need to wait
 >   for a service to be ready, see [Controlling startup order](/compose/startup-order.md)
 >   for more on this problem and strategies for solving it.
->
 > - Version 3 no longer supports the `condition` form of `depends_on`.
->
 > - The `depends_on` option is ignored when
 >   [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
 >   with a version 3 Compose file.
@@ -1018,14 +1016,14 @@ env_file: .env
 env_file:
   - ./common.env
   - ./apps/web.env
-  - /opt/secrets.env
+  - /opt/runtime_opts.env
 ```
 
 Compose expects each line in an env file to be in `VAR=VAL` format. Lines
 beginning with `#` are treated as comments and are ignored. Blank lines are
 also ignored.
 
-```bash
+```console
 # Set Rails/Rack environment
 RACK_ENV=development
 ```
@@ -1056,14 +1054,14 @@ services:
 
 And the following files:
 
-```bash
+```console
 # a.env
 VAR=1
 ```
 
 and
 
-```bash
+```console
 # b.env
 VAR=hello
 ```
@@ -1125,13 +1123,13 @@ external_links:
 
 > **Notes:**
 >
-> If you're using the [version 2 or above file format](compose-versioning.md#version-2), the externally-created  containers
+> If you're using the [version 2 or above file format](compose-versioning.md#version-2),
-must be connected to at least one of the same networks as the service that is
+> the externally-created  containers must be connected to at least one of the same
-linking to them. [Links](compose-file-v2#links) are a
+> networks as the service that is linking to them. [Links](compose-file-v2#links)
-legacy option. We recommend using [networks](#networks) instead.
+> are a legacy option. We recommend using [networks](#networks) instead.
 >
 > This option is ignored when [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
-with a (version 3) Compose file.
+> with a (version 3) Compose file.
 
 ### extra_hosts
 
@@ -1145,7 +1143,7 @@ extra_hosts:
 
 An entry with the ip address and hostname is created in `/etc/hosts` inside containers for this service, e.g:
 
-```none
+```console
 162.242.195.82  somehost
 50.31.209.229   otherhost
 ```
@@ -1168,10 +1166,11 @@ healthcheck:
   start_period: 40s
 ```
 
-`interval`, `timeout` and `start_period` are specified as [durations](#specifying-durations).
+`interval`, `timeout` and `start_period` are specified as
+[durations](#specifying-durations).
 
 > **Note**: `start_period` is only supported for v3.4 and higher of the compose
-file format.
+> file format.
 
 `test` must be either a string or a list. If it's a list, the first item must be
 either `NONE`, `CMD` or `CMD-SHELL`. If it's a string, it's equivalent to
@@ -1192,8 +1191,8 @@ test: ["CMD-SHELL", "curl -f http://localhost || exit 1"]
 test: curl -f https://localhost || exit 1
 ```
 
-To disable any default healthcheck set by the image, you can use `disable:
+To disable any default healthcheck set by the image, you can use `disable: true`.
-true`. This is equivalent to specifying `test: ["NONE"]`.
+This is equivalent to specifying `test: ["NONE"]`.
 
 ```yaml
 healthcheck:
@@ -1205,11 +1204,21 @@ healthcheck:
 Specify the image to start the container from. Can either be a repository/tag or
 a partial image ID.
 
+```yaml
 image: redis
-    image: ubuntu:14.04
+```
+```yaml
+image: ubuntu:18.04
+```
+```yaml
 image: tutum/influxdb
+```
+```yaml
 image: example-registry.com:4000/postgresql
+```
+```yaml
 image: a4bc65fd
+```
 
 If the image does not exist, Compose attempts to pull it, unless you have also
 specified [build](#build), in which case it builds it using the specified
@@ -1276,14 +1285,14 @@ containers in a more controlled way.
 {:.warning}
 
 Link to containers in another service. Either specify both the service name and
-a link alias (`SERVICE:ALIAS`), or just the service name.
+a link alias (`"SERVICE:ALIAS"`), or just the service name.
 
 ```yaml
 web:
   links:
-   - db
+    - "db"
-   - db:database
+    - "db:database"
-   - redis
+    - "redis"
 ```
 
 Containers for the linked service are reachable at a hostname identical to
@@ -1301,7 +1310,6 @@ Links also express dependency between services in the same way as
 > * If you define both links and [networks](#networks), services with
 >   links between them must share at least one network in common to
 >   communicate.
->
 > * This option is ignored when
 >   [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
 >   with a (version 3) Compose file.
@@ -1323,13 +1331,19 @@ containers, as with the ``--log-driver`` option for docker run
 
 The default value is json-file.
 
+```yaml
 driver: "json-file"
+```
+```yaml
 driver: "syslog"
+```
+```yaml
 driver: "none"
+```
 
-> **Note**: Only the `json-file` and `journald` drivers make the logs
+> **Note**: Only the `json-file` and `journald` drivers make the logs available
-available directly from `docker-compose up` and `docker-compose logs`.
+> directly from `docker-compose up` and `docker-compose logs`. Using any other
-Using any other driver does not print any logs.
+> driver does not print any logs.
 
 Specify logging options for the logging driver with the ``options`` key, as with the ``--log-opt`` option for `docker run`.
 
@@ -1381,11 +1395,21 @@ For a full list of supported logging drivers and their options, see
 Network mode. Use the same values as the docker client `--network` parameter, plus
 the special form `service:[service name]`.
 
+```yaml
 network_mode: "bridge"
+```
+```yaml
 network_mode: "host"
+```
+```yaml
 network_mode: "none"
+```
+```yaml
 network_mode: "service:[service name]"
+```
+```yaml
 network_mode: "container:[container name/id]"
+```
 
 > **Notes**
 >
@@ -1502,7 +1526,9 @@ networks:
 
 ### pid
 
+```yaml
 pid: "host"
+```
 
 Sets the PID mode to the host PID mode.  This turns on sharing between
 container and the host operating system the PID address space.  Containers
@@ -1535,6 +1561,7 @@ ports:
   - "127.0.0.1:8001:8001"
   - "127.0.0.1:5000-5010:5000-5010"
   - "6060:6060/udp"
+  - "12400-12500:1240"
 ```
 
 #### Long syntax
@@ -1687,8 +1714,13 @@ handle SIGTERM (or whatever stop signal has been specified with
 [`stop_signal`](#stopsignal)), before sending SIGKILL. Specified
 as a [duration](#specifying-durations).
 
+```yaml
 stop_grace_period: 1s
+```
+
+```yaml
 stop_grace_period: 1m30s
+```
 
 By default, `stop` waits 10 seconds for the container to exit before sending
 SIGKILL.
@@ -1731,8 +1763,6 @@ parameters (sysctls) at runtime](/engine/reference/commandline/run/#configure-na
 
 ### tmpfs
 
-> [Version 2 file format](compose-versioning.md#version-2) and up.
-
 Mount a temporary file system inside the container. Can be a single value or a list.
 
 ```yaml
@@ -1766,7 +1796,6 @@ of the tmpfs mount in bytes. Unlimited by default.
 Override the default ulimits for a container. You can either specify a single
 limit as an integer or soft/hard limits as a mapping.
 
-
 ```yaml
 ulimits:
   nproc: 65535
@@ -1848,7 +1877,7 @@ volumes:
 Optionally specify a path on the host machine
 (`HOST:CONTAINER`), or an access mode (`HOST:CONTAINER:ro`).
 
-You can mount a relative path on the host, that expands relative to
+You can mount a relative path on the host, which expands relative to
 the directory of the Compose configuration file being used. Relative paths
 should always begin with `.` or `..`.
 
@@ -1888,7 +1917,9 @@ expressed in the short form.
     created
 - `tmpfs`: configure additional tmpfs options
   - `size`: the size for the tmpfs mount in bytes
-- `consistency`: the consistency requirements of the mount, one of `consistent` (host and container have identical view), `cached` (read cache, host view is authoritative) or `delegated` (read-write cache, container's view is authoritative)
+- `consistency`: the consistency requirements of the mount, one of `consistent`
+  (host and container have identical view), `cached` (read cache, host view is
+  authoritative) or `delegated` (read-write cache, container's view is authoritative)
 
 ```yaml
 version: "{{ site.compose_file_v3 }}"
@@ -1954,23 +1985,19 @@ services:
 
 #### Caching options for volume mounts (Docker Desktop for Mac)
 
-On Docker 17.04 CE Edge and up, including 17.06 CE Edge and Stable, you can
+You can configure container-and-host consistency requirements for bind-mounted
-configure container-and-host consistency requirements for bind-mounted
 directories in Compose files to allow for better performance on read/write of
 volume mounts. These options address issues specific to `osxfs` file sharing,
 and therefore are only applicable on Docker Desktop for Mac.
 
 The flags are:
 
-* `consistent`: Full consistency. The container runtime and the
+* `consistent`: Full consistency. The container runtime and the host maintain an
-host maintain an identical view of the mount at all times.  This is the default.
+  identical view of the mount at all times.  This is the default.
-
+* `cached`: The host's view of the mount is authoritative. There may be delays
-* `cached`: The host's view of the mount is authoritative. There may be
+  before updates made on the host are visible within a container.
-delays before updates made on the host are visible within a container.
+* `delegated`: The container runtime's view of the mount is authoritative. There
-
+  may be delays before updates made in a container are visible on the host.
-* `delegated`: The container runtime's view of the mount is
-authoritative. There may be delays before updates made in a container
-are visible on the host.
 
 Here is an example of configuring a volume as `cached`:
 
@@ -2026,7 +2053,6 @@ format that looks like this:
 
 The supported units are `us`, `ms`, `s`, `m` and `h`.
 
-
 ## Specifying byte values
 
 Some configuration options, such as the `shm_size` sub-option for
@@ -2042,18 +2068,17 @@ that looks like this:
 The supported units are `b`, `k`, `m` and `g`, and their alternative notation `kb`,
 `mb` and `gb`. Decimal values are not supported at this time.
 
-
 ## Volume configuration reference
 
-While it is possible to declare [volumes](#volumes) on the file as part of the
+While it is possible to declare [volumes](#volumes) on the fly as part of the
-service declaration, this section allows you to create named volumes (without
+service declaration, this section allows you to create named volumes that can be
-relying on `volumes_from`) that can be reused across multiple services, and are
+reused across multiple services (without relying on `volumes_from`), and are
-easily retrieved and inspected using the docker command line or API. See the
+easily retrieved and inspected using the docker command line or API.
-[docker volume](/engine/reference/commandline/volume_create.md) subcommand
+See the [docker volume](/engine/reference/commandline/volume_create.md)
-documentation for more information.
+subcommand documentation for more information.
 
-See [Use volumes](/engine/admin/volumes/volumes.md) and [Volume
+See [use volumes](/engine/admin/volumes/volumes.md) and [volume
-Plugins](/engine/extend/plugins_volume.md) for general information on volumes.
+plugins](/engine/extend/plugins_volume.md) for general information on volumes.
 
 Here's an example of a two-service setup where a database's data directory is
 shared with another service as a volume so that it can be periodically backed
@@ -2212,12 +2237,10 @@ volumes:
 The top-level `networks` key lets you specify networks to be created.
 
 * For a full explanation of Compose's use of Docker networking features and all
-network driver options, see the [Networking guide](../networking.md).
+  network driver options, see the [Networking guide](/compose/networking.md).
-
 * For [Docker Labs](https://github.com/docker/labs/blob/master/README.md)
   tutorials on networking, start with [Designing Scalable, Portable Docker
-Container
+  Container Networks](https://github.com/docker/labs/blob/master/networking/README.md)
-Networks](https://github.com/docker/labs/blob/master/networking/README.md)
 
 ### driver
 
@@ -2584,7 +2607,7 @@ stack.
 ## Compose documentation
 
 - [User guide](/compose/index.md)
-- [Installing Compose](/compose/install/)
+- [Installing Compose](/compose/install.md)
 - [Compose file versions and upgrading](compose-versioning.md)
 - [Samples](/samples/)
 - [Command line reference](/compose/reference/)