docs: lint

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

README.md

@@ -1,9 +1,10 @@
 # buildx
 
-[![PkgGoDev](https://img.shields.io/badge/go.dev-docs-007d9c?logo=go&logoColor=white)](https://pkg.go.dev/github.com/docker/buildx)
+[![GitHub release](https://img.shields.io/github/release/docker/buildx.svg?style=flat-square)](https://github.com/docker/buildx/releases/latest)
-[![Build Status](https://github.com/docker/buildx/workflows/build/badge.svg)](https://github.com/docker/buildx/actions?query=workflow%3Abuild)
+[![PkgGoDev](https://img.shields.io/badge/go.dev-docs-007d9c?style=flat-square&logo=go&logoColor=white)](https://pkg.go.dev/github.com/docker/buildx)
-[![Go Report Card](https://goreportcard.com/badge/github.com/docker/buildx)](https://goreportcard.com/report/github.com/docker/buildx)
+[![Build Status](https://img.shields.io/github/workflow/status/docker/buildx/build?label=build&logo=github&style=flat-square)](https://github.com/docker/buildx/actions?query=workflow%3Abuild)
-[![codecov](https://codecov.io/gh/docker/buildx/branch/master/graph/badge.svg)](https://codecov.io/gh/docker/buildx)
+[![Go Report Card](https://goreportcard.com/badge/github.com/docker/buildx?style=flat-square)](https://goreportcard.com/report/github.com/docker/buildx)
+[![codecov](https://img.shields.io/codecov/c/github/docker/buildx?logo=codecov&style=flat-square)](https://codecov.io/gh/docker/buildx)
 
 `buildx` is a Docker CLI plugin for extended build capabilities with
 [BuildKit](https://github.com/moby/buildkit).

docs/reference/buildx_bake.md

@@ -264,7 +264,6 @@ $ docker buildx bake --progress=plain
 ...
 ```
 
-
 ### <a name="pull"></a> Always attempt to pull a newer version of the image (--pull)
 
 Same as `build --pull`.
@@ -278,9 +277,6 @@ Same as `build --pull`.
 Override target configurations from command line. The pattern matching syntax
 is defined in https://golang.org/pkg/path/#Match.
 
-
-**Examples**
-
 ```console
 $ docker buildx bake --set target.args.mybuildarg=value
 $ docker buildx bake --set target.platform=linux/arm64
@@ -313,8 +309,7 @@ groups to inherit from.
 Note: Design of bake command is work in progress, the user experience may change
 based on feedback.
 
-
+HCL definition example:
-**Example HCL definition**
 
 ```hcl
 group "default" {
@@ -870,7 +865,6 @@ target "app" {
 
 Please note that in most cases you should just use a single multi-stage Dockerfile with multiple targets for similar behavior. This case is recommended when you have multiple Dockerfiles that can't be easily merged into one.
 
-
 ### Extension field with Compose
 
 [Special extension](https://github.com/compose-spec/compose-spec/blob/master/spec.md#extension)

docs/reference/buildx_build.md

@@ -58,78 +58,135 @@ here we’ll document a subset of the new flags.
 
 ## Examples
 
-### <a name="builder"></a> Override the configured builder instance (--builder)
+### <a name="allow"></a> Allow extra privileged entitlement (--allow)
-
-Same as [`buildx --builder`](buildx.md#builder).
-
-### <a name="platform"></a> Set the target platforms for the build (--platform)
 
 ```
---platform=value[,value]
+--allow=ENTITLEMENT
 ```
 
-Set the target platform for the build. All `FROM` commands inside the Dockerfile
+Allow extra privileged entitlement. List of entitlements:
-without their own `--platform` flag will pull base images for this platform and
-this value will also be the platform of the resulting image. The default value
-will be the current platform of the buildkit daemon.
 
-When using `docker-container` driver with `buildx`, this flag can accept multiple
+- `network.host` - Allows executions with host networking.
-values as an input separated by a comma. With multiple values the result will be
+- `security.insecure` - Allows executions without sandbox. See
-built for all of the specified platforms and joined together into a single manifest
+  [related Dockerfile extensions](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/experimental.md#run---securityinsecuresandbox).
-list.
 
-If the `Dockerfile` needs to invoke the `RUN` command, the builder needs runtime
+For entitlements to be enabled, the `buildkitd` daemon also needs to allow them
-support for the specified platform. In a clean setup, you can only execute `RUN`
+with `--allow-insecure-entitlement` (see [`create --buildkitd-flags`](buildx_create.md#buildkitd-flags))
-commands for your system architecture.
-If your kernel supports [`binfmt_misc`](https://en.wikipedia.org/wiki/Binfmt_misc)
-launchers for secondary architectures, buildx will pick them up automatically.
-Docker desktop releases come with `binfmt_misc` automatically configured for `arm64`
-and `arm` architectures. You can see what runtime platforms your current builder
-instance supports by running `docker buildx inspect --bootstrap`.
-
-Inside a `Dockerfile`, you can access the current platform value through
-`TARGETPLATFORM` build argument. Please refer to the [`docker build`
-documentation](https://docs.docker.com/engine/reference/builder/#automatic-platform-args-in-the-global-scope)
-for the full description of automatic platform argument variants .
-
-The formatting for the platform specifier is defined in the [containerd source
-code](https://github.com/containerd/containerd/blob/v1.4.3/platforms/platforms.go#L63).
 
 **Examples**
 
 ```console
-$ docker buildx build --platform=linux/arm64 .
+$ docker buildx create --use --name insecure-builder --buildkitd-flags '--allow-insecure-entitlement security.insecure'
-$ docker buildx build --platform=linux/amd64,linux/arm64,linux/arm/v7 .
+$ docker buildx build --allow security.insecure .
-$ docker buildx build --platform=darwin .
 ```
 
-### <a name="progress"></a> Set type of progress output (--progress)
+### <a name="build-context"></a> Additional build contexts (--build-context)
 
 ```
---progress=VALUE
+--build-context=name=VALUE
 ```
 
-Set type of progress output (auto, plain, tty). Use plain to show container
+Define additional build context with specified contents. In Dockerfile the context can be accessed when `FROM name` or `--from=name` is used.
-output (default "auto").
+When Dockerfile defines a stage with the same name it is overwritten.
 
-> You can also use the `BUILDKIT_PROGRESS` environment variable to set
+The value can be a local source directory, container image (with docker-image:// prefix), Git or HTTP URL.
-> its value.
 
-The following example uses `plain` output during the build:
+Replace `alpine:latest` with a pinned one:
 
 ```console
-$ docker buildx build --load --progress=plain .
+$ docker buildx build --build-context alpine=docker-image://alpine@sha256:0123456789 .
-
-#1 [internal] load build definition from Dockerfile
-#1 transferring dockerfile: 227B 0.0s done
-#1 DONE 0.1s
-
-#2 [internal] load .dockerignore
-#2 transferring context: 129B 0.0s done
-#2 DONE 0.0s
-...
 ```
 
+Expose a secondary local source directory:
+
+```console
+$ docker buildx build --build-context project=path/to/project/source .
+# docker buildx build --build-context project=https://github.com/myuser/project.git .
+```
+
+```Dockerfile
+FROM alpine
+COPY --from=project myfile /
+```
+
+### <a name="builder"></a> Override the configured builder instance (--builder)
+
+Same as [`buildx --builder`](buildx.md#builder).
+
+### <a name="cache-from"></a> Use an external cache source for a build (--cache-from)
+
+```
+--cache-from=[NAME|type=TYPE[,KEY=VALUE]]
+```
+
+Use an external cache source for a build. Supported types are `registry`,
+`local` and `gha`.
+
+- [`registry` source](https://github.com/moby/buildkit#registry-push-image-and-cache-separately)
+  can import cache from a cache manifest or (special) image configuration on the
+  registry.
+- [`local` source](https://github.com/moby/buildkit#local-directory-1) can
+  import cache from local files previously exported with `--cache-to`.
+- [`gha` source](https://github.com/moby/buildkit#github-actions-cache-experimental)
+  can import cache from a previously exported cache with `--cache-to` in your
+  GitHub repository
+
+If no type is specified, `registry` exporter is used with a specified reference.
+
+`docker` driver currently only supports importing build cache from the registry.
+
+```console
+$ docker buildx build --cache-from=user/app:cache .
+$ docker buildx build --cache-from=user/app .
+$ docker buildx build --cache-from=type=registry,ref=user/app .
+$ docker buildx build --cache-from=type=local,src=path/to/cache .
+$ docker buildx build --cache-from=type=gha .
+```
+
+More info about cache exporters and available attributes: https://github.com/moby/buildkit#export-cache
+
+### <a name="cache-to"></a> Export build cache to an external cache destination (--cache-to)
+
+```
+--cache-to=[NAME|type=TYPE[,KEY=VALUE]]
+```
+
+Export build cache to an external cache destination. Supported types are
+`registry`, `local`, `inline` and `gha`.
+
+- [`registry` type](https://github.com/moby/buildkit#registry-push-image-and-cache-separately) exports build cache to a cache manifest in the registry.
+- [`local` type](https://github.com/moby/buildkit#local-directory-1) type
+  exports cache to a local directory on the client.
+- [`inline` type](https://github.com/moby/buildkit#inline-push-image-and-cache-together)
+  type writes the cache metadata into the image configuration.
+- [`gha` type](https://github.com/moby/buildkit#github-actions-cache-experimental)
+  type exports cache through the [Github Actions Cache service API](https://github.com/tonistiigi/go-actions-cache/blob/master/api.md#authentication).
+
+`docker` driver currently only supports exporting inline cache metadata to image
+configuration. Alternatively, `--build-arg BUILDKIT_INLINE_CACHE=1` can be used
+to trigger inline cache exporter.
+
+Attribute key:
+
+- `mode` - Specifies how many layers are exported with the cache. `min` on only
+  exports layers already in the final build stage, `max` exports layers for
+  all stages. Metadata is always exported for the whole build.
+
+```console
+$ docker buildx build --cache-to=user/app:cache .
+$ docker buildx build --cache-to=type=inline .
+$ docker buildx build --cache-to=type=registry,ref=user/app .
+$ docker buildx build --cache-to=type=local,dest=path/to/cache .
+$ docker buildx build --cache-to=type=gha .
+```
+
+More info about cache exporters and available attributes: https://github.com/moby/buildkit#export-cache
+
+### <a name="load"></a> Load the single-platform build result to `docker images` (--load)
+
+Shorthand for [`--output=type=docker`](#docker). Will automatically load the
+single-platform build result to `docker images`.
+
 ### <a name="output"></a> Set the export action for the build result (-o, --output)
 
 ```
@@ -148,8 +205,6 @@ If just the path is specified as a value, `buildx` will use the local exporter
 with this path as the destination. If the value is "-", `buildx` will use `tar`
 exporter and write to `stdout`.
 
-**Examples**
-
 ```console
 $ docker buildx build -o . .
 $ docker buildx build -o outdir .
@@ -221,146 +276,78 @@ Attribute keys:
 
 The `registry` exporter is a shortcut for `type=image,push=true`.
 
+### <a name="platform"></a> Set the target platforms for the build (--platform)
+
+```
+--platform=value[,value]
+```
+
+Set the target platform for the build. All `FROM` commands inside the Dockerfile
+without their own `--platform` flag will pull base images for this platform and
+this value will also be the platform of the resulting image. The default value
+will be the current platform of the buildkit daemon.
+
+When using `docker-container` driver with `buildx`, this flag can accept multiple
+values as an input separated by a comma. With multiple values the result will be
+built for all of the specified platforms and joined together into a single manifest
+list.
+
+If the `Dockerfile` needs to invoke the `RUN` command, the builder needs runtime
+support for the specified platform. In a clean setup, you can only execute `RUN`
+commands for your system architecture.
+If your kernel supports [`binfmt_misc`](https://en.wikipedia.org/wiki/Binfmt_misc)
+launchers for secondary architectures, buildx will pick them up automatically.
+Docker desktop releases come with `binfmt_misc` automatically configured for `arm64`
+and `arm` architectures. You can see what runtime platforms your current builder
+instance supports by running `docker buildx inspect --bootstrap`.
+
+Inside a `Dockerfile`, you can access the current platform value through
+`TARGETPLATFORM` build argument. Please refer to the [`docker build`
+documentation](https://docs.docker.com/engine/reference/builder/#automatic-platform-args-in-the-global-scope)
+for the full description of automatic platform argument variants .
+
+The formatting for the platform specifier is defined in the [containerd source
+code](https://github.com/containerd/containerd/blob/v1.4.3/platforms/platforms.go#L63).
+
+```console
+$ docker buildx build --platform=linux/arm64 .
+$ docker buildx build --platform=linux/amd64,linux/arm64,linux/arm/v7 .
+$ docker buildx build --platform=darwin .
+```
+
+### <a name="progress"></a> Set type of progress output (--progress)
+
+```
+--progress=VALUE
+```
+
+Set type of progress output (auto, plain, tty). Use plain to show container
+output (default "auto").
+
+> You can also use the `BUILDKIT_PROGRESS` environment variable to set
+> its value.
+
+The following example uses `plain` output during the build:
+
+```console
+$ docker buildx build --load --progress=plain .
+
+#1 [internal] load build definition from Dockerfile
+#1 transferring dockerfile: 227B 0.0s done
+#1 DONE 0.1s
+
+#2 [internal] load .dockerignore
+#2 transferring context: 129B 0.0s done
+#2 DONE 0.0s
+...
+```
 
 ### <a name="push"></a> Push the build result to a registry (--push)
 
 Shorthand for [`--output=type=registry`](#registry). Will automatically push the
 build result to registry.
 
-### <a name="load"></a> Load the single-platform build result to `docker images` (--load)
+### <a name="secret"></a> Secret to expose to the build (--secret)
-
-Shorthand for [`--output=type=docker`](#docker). Will automatically load the
-single-platform build result to `docker images`.
-
-### <a name="cache-from"></a> Use an external cache source for a build (--cache-from)
-
-```
---cache-from=[NAME|type=TYPE[,KEY=VALUE]]
-```
-
-Use an external cache source for a build. Supported types are `registry`,
-`local` and `gha`.
-
-- [`registry` source](https://github.com/moby/buildkit#registry-push-image-and-cache-separately)
-can import cache from a cache manifest or (special) image configuration on the
-registry.
-- [`local` source](https://github.com/moby/buildkit#local-directory-1) can
-import cache from local files previously exported with `--cache-to`.
-- [`gha` source](https://github.com/moby/buildkit#github-actions-cache-experimental)
-can import cache from a previously exported cache with `--cache-to` in your
-GitHub repository
-
-If no type is specified, `registry` exporter is used with a specified reference.
-
-`docker` driver currently only supports importing build cache from the registry.
-
-**Examples**
-
-```console
-$ docker buildx build --cache-from=user/app:cache .
-$ docker buildx build --cache-from=user/app .
-$ docker buildx build --cache-from=type=registry,ref=user/app .
-$ docker buildx build --cache-from=type=local,src=path/to/cache .
-$ docker buildx build --cache-from=type=gha .
-```
-
-More info about cache exporters and available attributes: https://github.com/moby/buildkit#export-cache
-
-### <a name="cache-to"></a> Export build cache to an external cache destination (--cache-to)
-
-```
---cache-to=[NAME|type=TYPE[,KEY=VALUE]]
-```
-
-Export build cache to an external cache destination. Supported types are
-`registry`, `local`, `inline` and `gha`.
-
-- [`registry` type](https://github.com/moby/buildkit#registry-push-image-and-cache-separately) exports build cache to a cache manifest in the registry.
-- [`local` type](https://github.com/moby/buildkit#local-directory-1) type
-exports cache to a local directory on the client.
-- [`inline` type](https://github.com/moby/buildkit#inline-push-image-and-cache-together)
-type writes the cache metadata into the image configuration.
-- [`gha` type](https://github.com/moby/buildkit#github-actions-cache-experimental)
-type exports cache through the [Github Actions Cache service API](https://github.com/tonistiigi/go-actions-cache/blob/master/api.md#authentication).
-
-`docker` driver currently only supports exporting inline cache metadata to image
-configuration. Alternatively, `--build-arg BUILDKIT_INLINE_CACHE=1` can be used
-to trigger inline cache exporter.
-
-Attribute key:
-
-- `mode` - Specifies how many layers are exported with the cache. `min` on only
-exports layers already in the final build stage, `max` exports layers for
-all stages. Metadata is always exported for the whole build.
-
-**Examples**
-
-```console
-$ docker buildx build --cache-to=user/app:cache .
-$ docker buildx build --cache-to=type=inline .
-$ docker buildx build --cache-to=type=registry,ref=user/app .
-$ docker buildx build --cache-to=type=local,dest=path/to/cache .
-$ docker buildx build --cache-to=type=gha .
-```
-
-More info about cache exporters and available attributes: https://github.com/moby/buildkit#export-cache
-
-
-### <a name="build-context"></a> Additional build contexts (--build-context)
-
-```
---build-context=name=VALUE
-```
-
-Define additional build context with specified contents. In Dockerfile the context can be accessed when `FROM name` or `--from=name` is used.
-When Dockerfile defines a stage with the same name it is overwritten.
-
-The value can be a local source directory, container image (with docker-image:// prefix), Git or HTTP URL.
-
-**Examples**
-
-Replace `alpine:latest` with a pinned one:
-
-```console
-$ docker buildx build --build-context alpine=docker-image://alpine@sha256:0123456789 .
-```
-
-Expose a secondary local source directory:
-
-```console
-$ docker buildx build --build-context project=path/to/project/source .
-# docker buildx build --build-context project=https://github.com/myuser/project.git .
-```
-
-```Dockerfile
-FROM alpine
-COPY --from=project myfile /
-```
-
-
-### <a name="allow"></a> Allow extra privileged entitlement (--allow)
-
-```
---allow=ENTITLEMENT
-```
-
-Allow extra privileged entitlement. List of entitlements:
-
-- `network.host` - Allows executions with host networking.
-- `security.insecure` - Allows executions without sandbox. See
-[related Dockerfile extensions](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/experimental.md#run---securityinsecuresandbox).
-
-For entitlements to be enabled, the `buildkitd` daemon also needs to allow them
-with `--allow-insecure-entitlement` (see [`create --buildkitd-flags`](buildx_create.md#buildkitd-flags))
-
-**Examples**
-
-```console
-$ docker buildx create --use --name insecure-builder --buildkitd-flags '--allow-insecure-entitlement security.insecure'
-$ docker buildx build --allow security.insecure .
-```
-
-### <a name="secret"></a> Secret to expose to the build (`--secret`)
 
 ```
 --secret=[type=TYPE[,KEY=VALUE]
@@ -386,8 +373,8 @@ RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
   aws s3 cp s3://... ...
 ```
 
-```shell
+```console
-docker buildx build --secret id=aws,src=$HOME/.aws/credentials .
+$ docker buildx build --secret id=aws,src=$HOME/.aws/credentials .
 ```
 
 #### `env`
@@ -405,11 +392,11 @@ RUN --mount=type=bind,target=. \
   SECRET_TOKEN=$(cat /run/secrets/SECRET_TOKEN) yarn run test
 ```
 
-```shell
+```console
-SECRET_TOKEN=token docker buildx build --secret id=SECRET_TOKEN .
+$ SECRET_TOKEN=token docker buildx build --secret id=SECRET_TOKEN .
 ```
 
-### <a name="shm-size"></a> Size of `/dev/shm` (--shm-size)
+### <a name="shm-size"></a> Size of /dev/shm (--shm-size)
 
 The format is `<number><unit>`. `number` must be greater than `0`. Unit is
 optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g`

docs/reference/buildx_create.md

@@ -47,8 +47,6 @@ The `--append` flag changes the action of the command to append a new node to an
 existing builder specified by `--name`. Buildx will choose an appropriate node
 for a build based on the platforms it supports.
 
-**Examples**
-
 ```console
 $ docker buildx create mycontext1
 eager_beaver
@@ -67,8 +65,6 @@ Adds flags when starting the buildkitd daemon. They take precedence over the
 configuration file specified by [`--config`](#config). See `buildkitd --help`
 for the available flags.
 
-**Example**
-
 ```
 --buildkitd-flags '--debug --debugaddr 0.0.0.0:6666'
 ```
@@ -149,38 +145,12 @@ Passes additional driver-specific options. Details for each driver:
   - `qemu.install=(true|false)` - Install QEMU emulation for multi platforms support.
   - `qemu.image=IMAGE` - Sets the QEMU emulation image. Defaults to `tonistiigi/binfmt:latest`
 
-**Examples**
-
-#### Use a custom network
-
-```console
-$ docker network create foonet
-$ docker buildx create --name builder --driver docker-container --driver-opt network=foonet --use
-$ docker buildx inspect --bootstrap
-$ docker inspect buildx_buildkit_builder0 --format={{.NetworkSettings.Networks}}
-map[foonet:0xc00018c0c0]
-```
-
-#### OpenTelemetry support
-
-To capture the trace to [Jaeger](https://github.com/jaegertracing/jaeger), set
-`JAEGER_TRACE` environment variable to the collection address using the `driver-opt`:
-
-```console
-$ docker run -d --name jaeger -p 6831:6831/udp -p 16686:16686 jaegertracing/all-in-one
-$ docker buildx create --name builder --driver docker-container --driver-opt network=host --driver-opt env.JAEGER_TRACE=localhost:6831 --use
-$ docker buildx inspect --bootstrap
-# buildx command should be traced at http://127.0.0.1:16686/
-```
-
 ### <a name="leave"></a> Remove a node from a builder (--leave)
 
 The `--leave` flag changes the action of the command to remove a node from a
 builder. The builder needs to be specified with `--name` and node that is removed
 is set with `--node`.
 
-**Examples**
-
 ```console
 $ docker buildx create --name mybuilder --node mybuilder0 --leave
 ```
@@ -204,7 +174,7 @@ The `--node` flag specifies the name of the node to be created or modified. If
 none is specified, it is the name of the builder it belongs to, with an index
 number suffix.
 
-### <a name="platform"></a> Set the platforms supported by the node
+### <a name="platform"></a> Set the platforms supported by the node (--platform)
 
 ```
 --platform PLATFORMS
@@ -216,14 +186,12 @@ will also automatically detect the platforms it supports, but manual values take
 priority over the detected ones and can be used when multiple nodes support
 building for the same platform.
 
-**Examples**
-
 ```console
 $ docker buildx create --platform linux/amd64
 $ docker buildx create --platform linux/arm64,linux/arm/v8
 ```
 
-### <a name="use"></a> Automatically switch to the newly created builder
+### <a name="use"></a> Automatically switch to the newly created builder (--use)
 
 The `--use` flag automatically switches the current builder to the newly created
 one. Equivalent to running `docker buildx use $(docker buildx create ...)`.

docs/reference/buildx_imagetools_create.md

@@ -57,16 +57,15 @@ or a JSON of OCI descriptor object.
 In order to define annotations or additional platform properties like `os.version` and
 `os.features` you need to add them in the OCI descriptor object encoded in JSON.
 
-```
+```console
-docker buildx imagetools inspect --raw alpine | jq '.manifests[0] | .platform."os.version"="10.1"' > descr.json
+$ docker buildx imagetools inspect --raw alpine | jq '.manifests[0] | .platform."os.version"="10.1"' > descr.json
-docker buildx imagetools create -f descr.json myuser/image
+$ docker buildx imagetools create -f descr.json myuser/image
 ```
 
 The descriptor in the file is merged with existing descriptor in the registry if it exists.
 
 The supported fields for the descriptor are defined in [OCI spec](https://github.com/opencontainers/image-spec/blob/master/descriptor.md#properties) .
 
-
 ### <a name="tag"></a> Set reference for new image  (-t, --tag)
 
 ```
@@ -75,10 +74,7 @@ The supported fields for the descriptor are defined in [OCI spec](https://github
 
 Use the `-t` or `--tag` flag to set the name of the image to be created.
 
-**Examples**
-
 ```console
 $ docker buildx imagetools create --dry-run alpine@sha256:5c40b3c27b9f13c873fefb2139765c56ce97fd50230f1f2d5c91e55dec171907 sha256:c4ba6347b0e4258ce6a6de2401619316f982b7bcc529f73d2a410d0097730204
-
 $ docker buildx imagetools create -t tonistiigi/myapp -f image1 -f image2
 ```

docs/reference/buildx_imagetools_inspect.md

@@ -21,8 +21,6 @@ Show details of image in the registry
 
 Show details of image in the registry.
 
-Example:
-
 ```console
 $ docker buildx imagetools inspect alpine
 

docs/reference/buildx_ls.md

@@ -14,18 +14,17 @@ List builder instances
 
 Lists all builder instances and the nodes for each instance
 
-**Example**
-
 ```console
 $ docker buildx ls
 
 NAME/NODE       DRIVER/ENDPOINT             STATUS  PLATFORMS
 elated_tesla *  docker-container
   elated_tesla0 unix:///var/run/docker.sock running linux/amd64
-  elated_tesla1 ssh://ubuntu@1.2.3.4        running linux/arm64, linux/arm/v7, linux/arm/v6
+  elated_tesla1 ssh://ubuntu@1.2.3.4        running linux/arm64*, linux/arm/v7, linux/arm/v6
 default         docker
   default       default                     running linux/amd64
 ```
 
 Each builder has one or more nodes associated with it. The current builder's
-name is marked with a `*`.
+name is marked with a `*` in `NAME/NODE` and explicit node to build against for
+the target platform marked with a `*` in the `PLATFORMS` column.

docs/reference/buildx_version.md

@@ -10,10 +10,9 @@ Show buildx version information
 
 <!---MARKER_GEN_END-->
 
-## Examples
+## Description
-
-### View version information
 
+View version information
 
 ```console
 $ docker buildx version