From 0aaade3acb6561537cae0c4b07e99fcff11f3b30 Mon Sep 17 00:00:00 2001
From: codewithdaniel1 <55808718+codewithdaniel1@users.noreply.github.com>
Date: Mon, 3 Aug 2026 14:24:01 -0400
Subject: [PATCH] docs: clarify OCI and Docker exporter output modes

---
 content/manuals/build/exporters/oci-docker.md | 35 +++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/content/manuals/build/exporters/oci-docker.md b/content/manuals/build/exporters/oci-docker.md
index b9d13be064d5..34838eb476c3 100644
--- a/content/manuals/build/exporters/oci-docker.md
+++ b/content/manuals/build/exporters/oci-docker.md
@@ -33,8 +33,8 @@ The following table describes the available parameters:
 | Parameter           | Type                                   | Default | Description                                                                                                                           |
 | ------------------- | -------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
 | `name`              | String                                 |         | Specify image name(s)                                                                                                                 |
-| `dest`              | String                                 |         | Path                                                                                                                                  |
-| `tar`               | `true`,`false`                         | `true`  | Bundle the output into a tarball layout                                                                                               |
+| `dest`              | String                                 |         | Destination path for the exported image layout                                                                                         |
+| `tar`               | `true`,`false`                         | `true`  | Bundle the output into a tar archive                                                                                                  |
 | `compression`       | `uncompressed`,`gzip`,`estargz`,`zstd` | `gzip`  | Compression type, see [compression][1]                                                                                                |
 | `compression-level` | `0..22`                                |         | Compression level, see [compression][1]                                                                                               |
 | `force-compression` | `true`,`false`                         | `false` | Forcefully apply compression, see [compression][1]                                                                                    |
@@ -47,6 +47,37 @@ The following table describes the available parameters:
 [3]: #annotations
 [4]: https://github.com/moby/buildkit/blob/master/docs/build-repro.md
 
+## Output modes
+
+By default, these exporters write the image layout as a tar archive. The `dest`
+parameter sets the path to the archive:
+
+```console
+$ docker buildx build --output type=oci,dest=./image.tar .
+```
+
+To write the image layout as an unpacked directory instead, set `tar=false`.
+In this mode, `dest` sets the output directory:
+
+```console
+$ docker buildx build --output type=oci,dest=./image-layout,tar=false .
+```
+
+For the `docker` exporter, omitting `dest` loads the image to the local image
+store when the builder supports loading images:
+
+```console
+$ docker buildx build \
+  --output type=docker,name=<registry>/<image> .
+```
+
+To save the Docker image layout to disk instead, specify `dest`:
+
+```console
+$ docker buildx build \
+  --output type=docker,dest=./image.tar,name=<registry>/<image> .
+```
+
 ## Annotations
 
 These exporters support adding OCI annotation using `annotation` parameter,