From 144c8b1f8f820ee3969cab74d69d0222fc8c7953 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Sat, 30 Apr 2022 17:05:46 +0200 Subject: [PATCH] reference: remove "description" header, and use it for "extended description" The "description" header included the short description of each command. In most cases, this description was very short ("run a container"), and adding the extra header before it only was adding extra noise. This patch: - removes the top "description" header - renames the existing "extended description" header to "description" (a hidden "extended-description" anchor is added for backward compatibility) As the extended description can be long (hopefully!), there may be a long distance between the `Usage` section and the `Options` section. To help users navigate to the list of available options, an extra line is printed if an extended description is available for the command, including a link to the corresponding section: > Refer to the options section for an overview of available OPTIONS for this command. Signed-off-by: Sebastiaan van Stijn --- _includes/cli.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/_includes/cli.md b/_includes/cli.md index 705af60357..ad30639e46 100644 --- a/_includes/cli.md +++ b/_includes/cli.md @@ -2,7 +2,7 @@ {% 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 }} @@ -77,8 +77,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 }}