markdown: replace new line in usage

README.md

@@ -1,5 +1,5 @@
 [![PkgGoDev](https://img.shields.io/badge/go.dev-docs-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/github.com/docker/cli-docs-tool)
-[![Test Status](https://img.shields.io/github/workflow/status/docker/cli-docs-tool/test?label=test&logo=github&style=flat-square)](https://github.com/docker/cli-docs-tool/actions?query=workflow%3Atest)
+[![Test Status](https://img.shields.io/github/actions/workflow/status/docker/cli-docs-tool/test.yml?branch=main&label=test&logo=github&style=flat-square)](https://github.com/docker/cli-docs-tool/actions?query=workflow%3Atest)
 [![Go Report Card](https://goreportcard.com/badge/github.com/docker/cli-docs-tool)](https://goreportcard.com/report/github.com/docker/cli-docs-tool)
 
 ## About

clidocstool_md.go

@@ -20,6 +20,7 @@ import (
 	"log"
 	"os"
 	"path/filepath"
+	"regexp"
 	"strings"
 	"text/template"
 
@@ -28,6 +29,10 @@ import (
 	"github.com/spf13/pflag"
 )
 
+var (
+	nlRegexp = regexp.MustCompile(`\r?\n`)
+)
+
 // GenMarkdownTree will generate a markdown page for this command and all
 // descendants in the directory given.
 func (c *Client) GenMarkdownTree(cmd *cobra.Command) error {
@@ -216,7 +221,7 @@ func mdCmdOutput(cmd *cobra.Command, old string) (string, error) {
 			} else if cd, ok := cmd.Annotations[annotation.CodeDelimiter]; ok {
 				usage = strings.ReplaceAll(usage, cd, "`")
 			}
-			fmt.Fprintf(b, "%s | %s | %s | %s |\n", mdEscapePipe(name), mdEscapePipe(ftype), mdEscapePipe(defval), mdEscapePipe(usage))
+			fmt.Fprintf(b, "%s | %s | %s | %s |\n", mdEscapePipe(name), mdEscapePipe(ftype), mdEscapePipe(defval), mdReplaceNewline(mdEscapePipe(usage)))
 		})
 		fmt.Fprintln(b, "")
 	}
@@ -227,3 +232,7 @@ func mdCmdOutput(cmd *cobra.Command, old string) (string, error) {
 func mdEscapePipe(s string) string {
 	return strings.ReplaceAll(s, `|`, `\|`)
 }
+
+func mdReplaceNewline(s string) string {
+	return nlRegexp.ReplaceAllString(s, "<br>")
+}

clidocstool_test.go

@@ -118,7 +118,8 @@ func init() {
 
 	buildxBuildFlags.StringVar(&ignore, "shm-size", "", `Size of "/dev/shm"`)
 
-	buildxBuildFlags.StringArray("ssh", []string{}, `SSH agent socket or keys to expose to the build (format: "default|<id>[=<socket>|<key>[,<key>]]")`)
+	buildxBuildFlags.StringArray("ssh", []string{}, `SSH agent socket or keys to expose to the build
+format: "default|<id>[=<socket>|<key>[,<key>]]"`)
 
 	buildxBuildFlags.StringArrayP("tag", "t", []string{}, `Name and optionally a tag (format: "name:tag")`)
 	buildxBuildFlags.SetAnnotation("tag", annotation.ExternalURL, []string{"https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t"})

fixtures/buildx_build.md

@@ -29,7 +29,7 @@ Start a build
 | `-q`, `--quiet` |  |  | Suppress the build output and print image ID on success |
 | `--secret` | `stringArray` |  | Secret file to expose to the build (format: `id=mysecret,src=/local/secret`) |
 | `--shm-size` | `string` |  | Size of `/dev/shm` |
-| `--ssh` | `stringArray` |  | SSH agent socket or keys to expose to the build (format: `default\|<id>[=<socket>\|<key>[,<key>]]`) |
+| `--ssh` | `stringArray` |  | SSH agent socket or keys to expose to the build<br>format: `default\|<id>[=<socket>\|<key>[,<key>]]` |
 | [`-t`](https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t), [`--tag`](https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t) | `stringArray` |  | Name and optionally a tag (format: `name:tag`) |
 | [`--target`](https://docs.docker.com/engine/reference/commandline/build/#specifying-target-build-stage---target) | `string` |  | Set the target build stage to build. |
 | `--ulimit` | `string` |  | Ulimit options |

fixtures/docker_buildx_build.yaml

@@ -314,8 +314,9 @@ options:
     - option: ssh
       value_type: stringArray
       default_value: '[]'
-      description: |
-        SSH agent socket or keys to expose to the build (format: `default|<id>[=<socket>|<key>[,<key>]]`)
+      description: |-
+        SSH agent socket or keys to expose to the build
+        format: `default|<id>[=<socket>|<key>[,<key>]]`
       deprecated: false
       hidden: false
       experimental: false