From f208c6c4253812a24ce36dfa134e74de94b787c8 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Tue, 10 Feb 2026 11:12:26 +0000
Subject: [PATCH] docs: address issue #23757
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This change was automatically generated by the documentation agent team
in response to issue #23757.

🤖 Generated with cagent

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 _vale/config/vocabularies/Docker/accept.txt |  2 ++
 content/manuals/build/exporters/_index.md   | 16 ++++++++++++++++
 2 files changed, 18 insertions(+)

diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt
index cdbf04825fac..4efe0d69af47 100644
--- a/_vale/config/vocabularies/Docker/accept.txt
+++ b/_vale/config/vocabularies/Docker/accept.txt
@@ -1,5 +1,7 @@
 (?i)[A-Z]{2,}'?s
 jq
+zstd
+Zstandard
 untracked
 ripgrep
 exfiltration
diff --git a/content/manuals/build/exporters/_index.md b/content/manuals/build/exporters/_index.md
index 67ddf0df668a..1d601b469560 100644
--- a/content/manuals/build/exporters/_index.md
+++ b/content/manuals/build/exporters/_index.md
@@ -252,6 +252,22 @@ the previous compression algorithm.
 > The `gzip` and `estargz` compression methods use the [`compress/gzip` package](https://pkg.go.dev/compress/gzip),
 > while `zstd` uses the [`github.com/klauspost/compress/zstd` package](https://github.com/klauspost/compress/tree/master/zstd).
 
+#### zstd compression levels
+
+When you specify `compression=zstd`, the `compression-level` parameter accepts
+values from 0 to 22. BuildKit maps these values to four internal compression
+levels:
+
+| compression-level | Internal level | Approximate zstd level | Description                           |
+| ----------------- | -------------- | ---------------------- | ------------------------------------- |
+| 0-2               | Fastest        | ~1                     | Fastest compression, larger file size |
+| 3-6 (default)     | Default        | ~3                     | Balanced compression and speed        |
+| 7-8               | Better         | ~7                     | Better compression, slower            |
+| 9-22              | Best           | ~11                    | Best compression, slowest             |
+
+For example, setting `compression-level=5` and `compression-level=6` produces
+the same compression output, since both map to the "Default" internal level.
+
 ### OCI media types
 
 The `image`, `registry`, `oci` and `docker` exporters create container images.