diff --git a/_config.yml b/_config.yml
index 45df16f9f7..925f79f42d 100644
--- a/_config.yml
+++ b/_config.yml
@@ -19,7 +19,8 @@ lsi: false
exclude: ["_samples", "_scripts", "404.html", "datacenter", "ee", "index.html", "js/metadata.json"]
# Component versions -- address like site.docker_ce_version
-# You can't have - characters in these for non-YAML reasons
+# You can't have - characters in these for non-YAML reasons.
+# When updating 'latest_engine_api_version', also update 'min_api_threshold' below.
latest_engine_api_version: "1.41"
docker_ce_version: "20.10"
compose_v1_version: "1.29.2"
@@ -30,6 +31,25 @@ machine_version: "0.16.0"
distribution_version: "2.7"
compose_switch_version: "1.0.4"
+# Options for displaying minimum API version requirements in the reference pages.
+#
+# The reference pages show badges for commands and options (flags) that require
+# a minimum API version. While this information can be useful if an option was
+# added in a recent version of the Docker Engine (and API), these badges are no
+# longer relevant to most users if the minimum required version is quite "old".
+#
+# We assume users reading these pages to be on the current version, or at most
+# on the version before that (which is already "unsupported"). Users running
+# older versions have bigger problems on their hand, so we're not accounting for
+# those.
+#
+# So, to reduce unnecessary clutter on the page, we only show the minimum required
+# API version if it requires a relatively recent version of the Engine.
+#
+# The "min_api_threshold" option specifies the minimum required API version for
+# which we show a badge (currently: API v1.40, or "Docker 19.03").
+min_api_threshold: 1.40
+
# List of plugins to enable for local development builds. Mostly the same as
# for production, but without the "jekyll-sitemap" plugin, which is not needed
# for previewing, and excluding saves some time to build
diff --git a/_includes/cli.md b/_includes/cli.md
index bdc07c1d28..cd4e314d8f 100644
--- a/_includes/cli.md
+++ b/_includes/cli.md
@@ -2,11 +2,22 @@
{% assign controller_data = site.data[include.datafolder][include.datafile] %}
{% assign parentPath = page.path | prepend: "/" | remove: page.name %}
-## Description
+
{{ controller_data.short | replace_relative_links: page.path }}
{% if controller_data.min_api_version %}
+{% comment %}
+ To reduce unnecessary clutter on the page, we only show the minimum required
+ API version if it requires a relatively recent version of the Engine, which
+ is configured through the "min_api_threshold" option in _config.yml
+
+ Below, we first convert the min_api_version from a string to a number, so that
+ we can compare versions (see https://stackoverflow.com/a/27200972/1811501),
+ then compare it, to decide whether to show the "minimum required API version".
+{% endcomment %}
+{% assign min_api_version = controller_data.min_api_version | plus: 0 %}
+{% if min_api_version >= site.min_api_threshold %}
API {{ controller_data.min_api_version }}+
The client and daemon API must both be at least
@@ -14,6 +25,7 @@ The client and daemon API must both be at least
to use this command. Use the `docker version` command on the client to check
your client and daemon API versions.
+{% endif %}
{% endif %}
{% if controller_data.deprecated %}
@@ -25,15 +37,6 @@ your client and daemon API versions.
{% endif %}
-{% if page.enterprise_only == true %}
-
-> This command is only available on Docker Enterprise Edition.
->
-> Learn more about [Docker Enterprise products](/ee/supported-platforms/){: target="_blank" rel="noopener" class="_"}.
-{: .important }
-
-{% endif %}
-
{% if controller_data.experimental %}
> This command is experimental.
@@ -50,14 +53,11 @@ your client and daemon API versions.
{% if controller_data.experimentalcli %}
-> This command is experimental on the Docker client.
+> This command is experimental.
>
-> **It should not be used in production environments.**
->
-> To enable experimental features in the Docker CLI, edit the
-> [config.json](/engine/reference/commandline/cli/#configuration-files)
-> and set `experimental` to `enabled`. You can go [here](https://docs.docker.com/engine/reference/commandline/cli/#experimental-features)
-> for more information.
+> [Experimental features](https://docs.docker.com/engine/reference/commandline/cli/#experimental-features)
+> are intended for testing and feedback as their functionality or UX may change
+> between releases without warning or can be removed entirely in a future release.
{: .important }
{% endif %}
@@ -86,8 +86,13 @@ $ {{ controller_data.usage | replace: tabChar, "" | strip }}{% if controller_dat
{% endif %}
{% unless controller_data.long == controller_data.short %}
+{% if controller_data.options %}
+Refer to the [options section](#options) for an overview of available [`OPTIONS`](#options) for this command.
+{% endif %}
-## Extended description
+## Description
+
+{: name="extended-description"}
{{ controller_data.long | replace_relative_links: page.path }}
@@ -118,7 +123,14 @@ For example uses of this command, refer to the [examples section](#examples) bel
{% capture deprecated-badge %}{% if option.deprecated %}deprecated{% endif %}{% endcapture %}
{% capture experimental-daemon-badge %}{% if option.experimental %}experimental (daemon){% endif %}{% endcapture %}
{% capture experimental-cli-badge %}{% if option.experimentalcli %}experimental (CLI){% endif %}{% endcapture %}
- {% capture min-api %}{% if option.min_api_version %}API {{ option.min_api_version }}+{% endif %}{%endcapture%}
+ {%- if option.min_api_version -%}
+ {% assign min_api_version = option.min_api_version | plus: 0 %}
+ {% if min_api_version >= site.min_api_threshold %}
+ {% capture min-api %}API {{ option.min_api_version }}+{%endcapture%}
+ {%- endif -%}
+ {%- else -%}
+ {% capture min-api %}{%endcapture%}
+ {%- endif -%}
{% capture flag-orchestrator %}{% if option.swarm %}Swarm{% endif %}{% if option.kubernetes %}Kubernetes{% endif %}{% endcapture %}
{% capture all-badges %}{{ deprecated-badge }}{{ experimental-daemon-badge }}{{ experimental-cli-badge }}{{ min-api }}{{ flag-orchestrator }}{% endcapture %}
{% assign defaults-to-skip = "[],map[],false,0,0s,default,'',\"\"" | split: ',' %}
@@ -146,7 +158,7 @@ For example uses of this command, refer to the [examples section](#examples) bel
{% endif %}
{% if controller_data.pname %}
-{% unless controller_data.pname == include.datafile %}
+{% unless controller_data.pname == include.datafile or controller_data.pname == "docker" %}
## Parent command
@@ -154,9 +166,9 @@ For example uses of this command, refer to the [examples section](#examples) bel
{% capture parentdatafile %}{{ controller_data.plink | remove_first: ".yaml" }}{% endcapture %}
{% capture parentDesc %}{{ site.data[include.datafolder][parentdatafile].short }}{% endcapture %}
-| Command | Description |
-| ------- | ----------- |
-| [{{ controller_data.pname }}]({{parentPath}}{{ parentfile }}/) | {{ parentDesc }}|
+| Command | Description |
+|:---------------------------------------------------------------|:-----------------|
+| [{{ controller_data.pname }}]({{parentPath}}{{ parentfile }}/) | {{ parentDesc }} |
{% endunless %}
{% endif %}