Merge pull request #3186 from crazy-max/fix-readme

update readme

Author: crazy-max

README.md

@@ -6,7 +6,7 @@
 [![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
+Buildx is a Docker CLI plugin for extended build capabilities with
 [BuildKit](https://github.com/moby/buildkit).
 
 Key features:
@@ -16,7 +16,7 @@ Key features:
 - Multiple builder instance support
 - Multi-node builds for cross-platform images
 - Compose build support
-- High-level build constructs (`bake`)
+- High-level build options (`bake`)
 - In-container driver support (both Docker and Kubernetes)
 
 # Table of Contents
@@ -26,10 +26,9 @@ Key features:
   - [Linux packages](#linux-packages)
   - [Manual download](#manual-download)
   - [Dockerfile](#dockerfile)
-- [Set buildx as the default builder](#set-buildx-as-the-default-builder)
 - [Building](#building)
 - [Getting started](#getting-started)
-  - [Building with buildx](#building-with-buildx)
+  - [Building with Buildx](#building-with-buildx)
   - [Working with builder instances](#working-with-builder-instances)
   - [Building multi-platform images](#building-multi-platform-images)
 - [Reference](docs/reference/buildx.md)
@@ -49,12 +48,9 @@ Key features:
   - [`buildx version`](docs/reference/buildx_version.md)
 - [Contributing](#contributing)
 
-For more information on how to use Buildx, see
-[Docker Build docs](https://docs.docker.com/build/).
-
 # Installing
 
-Using `buildx` with Docker requires Docker engine 19.03 or newer.
+Using Buildx with Docker requires Docker engine 19.03 or newer.
 
 > [!WARNING]
 > Using an incompatible version of Docker may result in unexpected behavior,
@@ -75,9 +71,9 @@ Docker Engine package repositories contain Docker Buildx packages when installed
 ## Manual download
 
 > [!IMPORTANT]
-> This section is for unattended installation of the buildx component. These
+> This section is for unattended installation of the Buildx component. These
 > instructions are mostly suitable for testing purposes. We do not recommend
-> installing buildx using manual download in production environments as they
+> installing Buildx using manual download in production environments as they
 > will not be updated automatically with security updates.
 >
 > On Windows and macOS, we recommend that you install [Docker Desktop](https://docs.docker.com/desktop/)
@@ -87,11 +83,11 @@ You can also download the latest binary from the [GitHub releases page](https://
 
 Rename the relevant binary and copy it to the destination matching your OS:
 
-| OS       | Binary name          | Destination folder                       |
-| -------- | -------------------- | -----------------------------------------|
-| Linux    | `docker-buildx`      | `$HOME/.docker/cli-plugins`              |
-| macOS    | `docker-buildx`      | `$HOME/.docker/cli-plugins`              |
-| Windows  | `docker-buildx.exe`  | `%USERPROFILE%\.docker\cli-plugins`      |
+| OS      | Binary name         | Destination folder                  |
+|---------|---------------------|-------------------------------------|
+| Linux   | `docker-buildx`     | `$HOME/.docker/cli-plugins`         |
+| macOS   | `docker-buildx`     | `$HOME/.docker/cli-plugins`         |
+| Windows | `docker-buildx.exe` | `%USERPROFILE%\.docker\cli-plugins` |
 
 Or copy it into one of these folders for installing it system-wide.
 
@@ -123,14 +119,6 @@ COPY --from=docker/buildx-bin /buildx /usr/libexec/docker/cli-plugins/docker-bui
 RUN docker buildx version
 ```
 
-# Set buildx as the default builder
-
-Running the command [`docker buildx install`](docs/reference/buildx_install.md)
-sets up docker builder command as an alias to `docker buildx build`. This
-results in the ability to have `docker build` use the current buildx builder.
-
-To remove this alias, run [`docker buildx uninstall`](docs/reference/buildx_uninstall.md).
-
 # Building
 
 ```console
@@ -151,17 +139,17 @@ $ make install
 
 # Getting started
 
-## Building with buildx
+## Building with Buildx
 
 Buildx is a Docker CLI plugin that extends the `docker build` command with the
-full support of the features provided by [Moby BuildKit](https://github.com/moby/buildkit)
+full support of the features provided by [Moby BuildKit](https://docs.docker.com/build/buildkit/)
 builder toolkit. It provides the same user experience as `docker build` with
 many new features like creating scoped builder instances and building against
 multiple nodes concurrently.
 
-After installation, buildx can be accessed through the `docker buildx` command
-with Docker 19.03.  `docker buildx build` is the command for starting a new
-build. With Docker versions older than 19.03 buildx binary can be called
+After installation, Buildx can be accessed through the `docker buildx` command
+with Docker 19.03. `docker buildx build` is the command for starting a new
+build. With Docker versions older than 19.03 Buildx binary can be called
 directly to access the `docker buildx` subcommands.
 
 ```console
@@ -180,20 +168,25 @@ are not yet available for regular `docker build` like building manifest lists,
 distributed caching, and exporting build results to OCI image tarballs.
 
 Buildx is flexible and can be run in different configurations that are exposed
-through various "drivers". Each driver defines how and where a build should
-run, and have different feature sets.
+through various [drivers](https://docs.docker.com/build/builders/drivers/).
+Each driver defines how and where a build should run, and have different
+feature sets.
 
 We currently support the following drivers:
-- The `docker` driver ([guide](https://docs.docker.com/build/drivers/docker/), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver))
-- The `docker-container` driver ([guide](https://docs.docker.com/build/drivers/docker-container/), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver))
-- The `kubernetes` driver ([guide](https://docs.docker.com/build/drivers/kubernetes/), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver))
-- The `remote` driver ([guide](https://docs.docker.com/build/drivers/remote/))
+- The `docker` driver ([manual](https://docs.docker.com/build/builders/drivers/docker/))
+- The `docker-container` driver ([manual](https://docs.docker.com/build/builders/drivers/docker-container/))
+- The `kubernetes` driver ([manual](https://docs.docker.com/build/drivers/kubernetes/))
+- The `remote` driver ([manual](https://docs.docker.com/build/builders/drivers/remote/))
+
+For more information, see the [builders](https://docs.docker.com/build/builders/)
+and [drivers](https://docs.docker.com/build/builders/drivers/) guide.
 
-For more information on drivers, see the [drivers guide](https://docs.docker.com/build/drivers/).
+> [!NOTE]
+> For more information, see [Docker Build docs](https://docs.docker.com/build/concepts/overview/).
 
 ## Working with builder instances
 
-By default, buildx will initially use the `docker` driver if it is supported,
+By default, Buildx will initially use the `docker` driver if it is supported,
 providing a very similar user experience to the native `docker build`. Note that
 you must use a local shared daemon to build your applications.
 
@@ -212,7 +205,7 @@ while creating the new builder. After creating a new instance, you can manage it
 lifecycle using the [`docker buildx inspect`](docs/reference/buildx_inspect.md),
 [`docker buildx stop`](docs/reference/buildx_stop.md), and
 [`docker buildx rm`](docs/reference/buildx_rm.md) commands. To list all
-available builders, use [`buildx ls`](docs/reference/buildx_ls.md). After
+available builders, use [`docker buildx ls`](docs/reference/buildx_ls.md). After
 creating a new builder you can also append new nodes to it.
 
 To switch between different builders, use [`docker buildx use <name>`](docs/reference/buildx_use.md).
@@ -223,9 +216,12 @@ Docker also features a [`docker context`](https://docs.docker.com/engine/referen
 command that can be used for giving names for remote Docker API endpoints.
 Buildx integrates with `docker context` so that all of your contexts
 automatically get a default builder instance. While creating a new builder
-instance or when adding a node to it you can also set the context name as the
+instance or when adding a node to it, you can also set the context name as the
 target.
 
+> [!NOTE]
+> For more information, see [Builders docs](https://docs.docker.com/build/builders/).
+
 ## Building multi-platform images
 
 BuildKit is designed to work well for building for multiple platforms and not
@@ -239,8 +235,8 @@ platform for the build output, (for example, `linux/amd64`, `linux/arm64`, or
 When the current builder instance is backed by the `docker-container` or
 `kubernetes` driver, you can specify multiple platforms together. In this case,
 it builds a manifest list which contains images for all specified architectures.
-When you use this image in [`docker run`](https://docs.docker.com/engine/reference/commandline/run/)
-or [`docker service`](https://docs.docker.com/engine/reference/commandline/service/),
+When you use this image in [`docker run`](https://docs.docker.com/reference/cli/docker/container/run/)
+or [`docker service`](https://docs.docker.com/reference/cli/docker/service/),
 Docker picks the correct image based on the node's platform.
 
 You can build multi-platform images using three different strategies that are
@@ -304,6 +300,9 @@ COPY --from=build /log /log
 You can also use [`tonistiigi/xx`](https://github.com/tonistiigi/xx) Dockerfile
 cross-compilation helpers for more advanced use-cases.
 
+> [!NOTE]
+> For more information, see [Multi-platform builds docs](https://docs.docker.com/build/building/multi-platform/).
+
 ## High-level build options
 
 See [High-level builds with Bake](https://docs.docker.com/build/bake/) for more details.