docs: refactored file and directory structure

Signed-off-by: David Karlsson <david.karlsson@docker.com>

README.md

@@ -32,15 +32,18 @@ Key features:
   - [Building with buildx](#building-with-buildx)
   - [Working with builder instances](#working-with-builder-instances)
   - [Building multi-platform images](#building-multi-platform-images)
+- [Manuals](docs/manuals)
+  - [High-level build options with Bake](docs/manuals/bake/index.md)
+  - [Drivers](docs/manuals/drivers/index.md)
+  - [Exporters](docs/manuals/exporters/index.md)
+  - [Cache backends](docs/manuals/cache/backends/index.md)
 - [Guides](docs/guides)
-  - [High-level build options with Bake](docs/guides/bake/index.md)
   - [CI/CD](docs/guides/cicd.md)
   - [CNI networking](docs/guides/cni-networking.md)
   - [Using a custom network](docs/guides/custom-network.md)
   - [Using a custom registry configuration](docs/guides/custom-registry-config.md)
   - [OpenTelemetry support](docs/guides/opentelemetry.md)
   - [Registry mirror](docs/guides/registry-mirror.md)
-  - [Drivers](docs/guides/drivers/index.md)
   - [Resource limiting](docs/guides/resource-limiting.md)
 - [Reference](docs/reference/buildx.md)
   - [`buildx bake`](docs/reference/buildx_bake.md)
@@ -191,12 +194,12 @@ through various "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](docs/guides/drivers/docker.md), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver))
-- The `docker-container` driver ([guide](docs/guides/drivers/docker-container.md), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver))
-- The `kubernetes` driver ([guide](docs/guides/drivers/kubernetes.md), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver))
-- The `remote` driver ([guide](docs/guides/drivers/remote.md))
+- The `docker` driver ([guide](docs/manuals/drivers/docker.md), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver))
+- The `docker-container` driver ([guide](docs/manuals/drivers/docker-container.md), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver))
+- The `kubernetes` driver ([guide](docs/manuals/drivers/kubernetes.md), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver))
+- The `remote` driver ([guide](docs/manuals/drivers/remote.md))
 
-For more information on drivers, see the [drivers guide](docs/guides/drivers/index.md).
+For more information on drivers, see the [drivers guide](docs/manuals/drivers/index.md).
 
 ## Working with builder instances
 
@@ -313,7 +316,7 @@ cross-compilation helpers for more advanced use-cases.
 
 ## High-level build options
 
-See [`docs/guides/bake/index.md`](docs/guides/bake/index.md) for more details.
+See [`docs/manuals/bake/index.md`](docs/manuals/bake/index.md) for more details.
 
 # Contributing
 

bake/bake.go

@@ -569,7 +569,7 @@ type Target struct {
 	NoCache          *bool             `json:"no-cache,omitempty" hcl:"no-cache,optional"`
 	NetworkMode      *string           `json:"-" hcl:"-"`
 	NoCacheFilter    []string          `json:"no-cache-filter,omitempty" hcl:"no-cache-filter,optional"`
-	// IMPORTANT: if you add more fields here, do not forget to update newOverrides and docs/guides/bake/file-definition.md.
+	// IMPORTANT: if you add more fields here, do not forget to update newOverrides and docs/manuals/bake/file-definition.md.
 
 	// linked is a private field to mark a target used as a linked one
 	linked bool

bake/compose.go

@@ -222,7 +222,7 @@ type xbake struct {
 	NoCacheFilter stringArray `yaml:"no-cache-filter,omitempty"`
 	Contexts      stringMap   `yaml:"contexts,omitempty"`
 	// don't forget to update documentation if you add a new field:
-	// docs/guides/bake/compose-file.md#extension-field-with-x-bake
+	// docs/manuals/bake/compose-file.md#extension-field-with-x-bake
 }
 
 type stringMap map[string]string

commands/bake.go

@@ -112,7 +112,7 @@ func runBake(dockerCli command.Cli, targets []string, in bakeOptions) (err error
 
 	tgts, grps, err := bake.ReadTargets(ctx, files, targets, overrides, map[string]string{
 		// don't forget to update documentation if you add a new
-		// built-in variable: docs/guides/bake/file-definition.md#built-in-variables
+		// built-in variable: docs/manuals/bake/file-definition.md#built-in-variables
 		"BAKE_CMD_CONTEXT":    cmdContext,
 		"BAKE_LOCAL_PLATFORM": platforms.DefaultString(),
 	})

docs/manuals/README.md

@@ -0,0 +1,14 @@
+# Buildx manuals 📚
+
+This directory contains a bunch of useful docs for how to use Buildx features.
+
+> **Note**
+>
+> The markdown files in this directory (excluding this README) are reused
+> downstream by the
+> [Docker documentation repository](https://github.com/docker/docs).
+>
+> If you wish to contribute to these docs, be sure to first review the
+> [documentation contribution guidelines](https://docs.docker.com/contribute/overview/).
+>
+> Thank you!

docs/manuals/cache/backends/index.md

@@ -50,7 +50,7 @@ to import the cache from the storage backend into the current build. Unlike the
 local BuildKit cache (which is always enabled), all of the cache storage
 backends must be explicitly exported to, and explicitly imported from. All cache
 exporters except for the `inline` cache requires that you
-[select an alternative Buildx driver](https://docs.docker.com/build/building/drivers/).
+[select an alternative Buildx driver](../../drivers/index.md).
 
 Example `buildx` command using the `registry` backend, using import and export
 cache:
@@ -127,10 +127,8 @@ with both parameters to find the results that work best for you.
 
 ### Cache compression
 
-<!-- TODO: change this link to a local link -->
-
 The cache compression options are the same as the
-[exporter compression options](https://docs.docker.com/build/building/exporters/#compression).
+[exporter compression options](../../exporters/index.md#compression).
 
 For example, to compress the `registry` cache with `zstd` compression:
 
@@ -142,10 +140,8 @@ $ docker buildx build --push -t <registry>/<image> \
 
 ### OCI media types
 
-<!-- TODO: change this link to a local link -->
-
 The cache OCI options are the same as the
-[exporter OCI options](https://docs.docker.com/build/building/exporters/#oci-media-types).
+[exporter OCI options](../../exporters/index.md#oci-media-types).
 
 For example, to export OCI media type cache, use the `oci-mediatypes` property:
 

docs/manuals/drivers/docker-container.md

@@ -9,7 +9,7 @@ Docker driver. For example:
 - Specify custom BuildKit versions to use.
 - Build multi-arch images, see [QEMU](#qemu)
 - Advanced options for
-  [cache import and export](https://docs.docker.com/build/building/cache/)
+  [cache import and export](../cache/backends/index.md)
 
 ## Synopsis
 

docs/manuals/exporters/index.md

@@ -144,8 +144,9 @@ $ docker buildx build --output type=tar,dest=<path/to/output> .
 ```
 
 The `local` exporter is useful in
-[multi-stage builds](/build/building/multi-stage/) since it allows you to export
-only a minimal number of build artifacts. For example, self-contained binaries.
+[multi-stage builds](https://docs.docker.com/build/building/multi-stage/) since
+it allows you to export only a minimal number of build artifacts. For example,
+self-contained binaries.
 
 ### Cache-only export