docs: rework bake "Configuring builds" page

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

docs/guides/bake/configuring-build.md

@@ -3,6 +3,14 @@ title: "Configuring builds"
 keywords: build, buildx, bake, buildkit, hcl, json
 ---
 
+Bake supports loading build definition from files, but sometimes you need even
+more flexibility to configure this definition.
+
+For this use case, you can define variables inside the bake files that can be
+set by the user with environment variables or by [attribute definitions](#global-scope-attributes)
+in other bake files. If you wish to change a specific value for a single
+invocation you can use the `--set` flag [from the command line](#from-command-line).
+
 ## Global scope attributes
 
 You can define global scope attributes in HCL/JSON and use them for code reuse
@@ -85,7 +93,8 @@ $ docker buildx bake -f docker-bake.hcl -f env.hcl --print app
 
 ## From command line
 
-You can also override target configurations from the command line with [`--set` flag](https://docs.docker.com/engine/reference/commandline/buildx_bake/#set):
+You can also override target configurations from the command line with the
+[`--set` flag](https://docs.docker.com/engine/reference/commandline/buildx_bake/#set):
 
 ```hcl
 # docker-bake.hcl
@@ -148,3 +157,63 @@ Complete list of overridable fields:
 * `ssh`
 * `tags`
 * `target`
+
+## Using variables in variables across files
+
+When multiple files are specified, one file can use variables defined in
+another file.
+
+```hcl
+# docker-bake1.hcl
+variable "FOO" {
+  default = upper("${BASE}def")
+}
+
+variable "BAR" {
+  default = "-${FOO}-"
+}
+
+target "app" {
+  args = {
+    v1 = "pre-${BAR}"
+  }
+}
+```
+
+```hcl
+# docker-bake2.hcl
+variable "BASE" {
+  default = "abc"
+}
+
+target "app" {
+  args = {
+    v2 = "${FOO}-post"
+  }
+}
+```
+
+```console
+$ docker buildx bake -f docker-bake1.hcl -f docker-bake2.hcl --print app
+```
+```json
+{
+  "group": {
+    "default": {
+      "targets": [
+        "app"
+      ]
+    }
+  },
+  "target": {
+    "app": {
+      "context": ".",
+      "dockerfile": "Dockerfile",
+      "args": {
+        "v1": "pre--ABCDEF-",
+        "v2": "ABCDEF-post"
+      }
+    }
+  }
+}
+```

docs/guides/bake/file-definition.md

@@ -4,9 +4,9 @@ keywords: build, buildx, bake, buildkit, hcl, json, compose
 ---
 
 `buildx bake` supports HCL, JSON and Compose file format for defining build
-groups, targets as well as [variables and functions](hcl-vars-funcs.md). It
+[groups](#group), [targets](#target) as well as [variables](#variable) and
-looks for build definition files in the current directory in the following
+[functions](#functions). It looks for build definition files in the current
-order:
+directory in the following order:
 
 * `docker-compose.yml`
 * `docker-compose.yaml`
@@ -87,7 +87,9 @@ $ docker buildx bake build
 
 ### Variable
 
-You can define variables with values provided by the current environment, or a
+Similar to how Terraform provides a way to [define variables](https://www.terraform.io/docs/configuration/variables.html#declaring-an-input-variable),
+the HCL file format also supports variable block definitions. These can be used
+to define variables with values provided by the current environment, or a
 default value when unset:
 
 ```hcl
@@ -112,7 +114,9 @@ $ TAG=dev docker buildx bake webapp-dev  # will use the TAG environment variable
 
 ### Functions
 
-A set of generally useful functions are available for use in HCL files:
+A [set of generally useful functions](https://github.com/docker/buildx/blob/master/bake/hclparser/stdlib.go)
+provided by [go-cty](https://github.com/zclconf/go-cty/tree/main/cty/function/stdlib)
+are available for use in HCL files:
 
 ```hcl
 # docker-bake.hcl
@@ -125,7 +129,8 @@ target "webapp-dev" {
 }
 ```
 
-User defined functions are also supported:
+In addition, [user defined functions](https://github.com/hashicorp/hcl/tree/main/ext/userfunc)
+are also supported:
 
 ```hcl
 # docker-bake.hcl
@@ -145,7 +150,14 @@ target "webapp-dev" {
 
 > **Note**
 >
-> See [HCL variables and functions](hcl-vars-funcs.md) page for more details.
+> See [User defined HCL functions](hcl-funcs.md) page for more details.
+
+## Built-in variables
+
+* `BAKE_CMD_CONTEXT` can be used to access the main `context` for bake command
+  from a bake file that has been [imported remotely](file-definition.md#remote-definition).
+* `BAKE_LOCAL_PLATFORM` returns the current platform's default platform
+  specification (e.g. `linux/amd64`).
 
 ## Merging and inheritance
 
@@ -363,7 +375,7 @@ As you can see the context is fixed to `https://github.com/docker/cli.git` even
 in the definition.
 
 If you want to access the main context for bake command from a bake file
-that has been imported remotely, you can use the [`BAKE_CMD_CONTEXT` built-in var](hcl-vars-funcs.md#built-in-variables).
+that has been imported remotely, you can use the [`BAKE_CMD_CONTEXT` built-in var](#built-in-variables).
 
 ```console
 $ cat https://raw.githubusercontent.com/tonistiigi/buildx/remote-test/docker-bake.hcl

docs/guides/bake/hcl-funcs.md

@@ -1,18 +1,8 @@
 ---
-title: "HCL variables and functions"
+title: "User defined HCL functions"
 keywords: build, buildx, bake, buildkit, hcl
 ---
 
-Similar to how Terraform provides a way to [define variables](https://www.terraform.io/docs/configuration/variables.html#declaring-an-input-variable),
-the HCL file format also supports variable block definitions. These can be used
-to define variables with values provided by the current environment, or a
-default value when unset.
-
-A [set of generally useful functions](https://github.com/docker/buildx/blob/master/bake/hclparser/stdlib.go)
-provided by [go-cty](https://github.com/zclconf/go-cty/tree/main/cty/function/stdlib)
-are available for use in HCL files. In addition, [user defined functions](https://github.com/hashicorp/hcl/tree/main/ext/userfunc)
-are also supported.
-
 ## Using interpolation to tag an image with the git sha
 
 As shown in the [File definition](file-definition.md#variable) page, `bake`
@@ -291,66 +281,6 @@ $ docker buildx bake --print webapp
 }
 ```
 
-## Using variables in variables across files
-
-When multiple files are specified, one file can use variables defined in
-another file.
-
-```hcl
-# docker-bake1.hcl
-variable "FOO" {
-  default = upper("${BASE}def")
-}
-
-variable "BAR" {
-  default = "-${FOO}-"
-}
-
-target "app" {
-  args = {
-    v1 = "pre-${BAR}"
-  }
-}
-```
-
-```hcl
-# docker-bake2.hcl
-variable "BASE" {
-  default = "abc"
-}
-
-target "app" {
-  args = {
-    v2 = "${FOO}-post"
-  }
-}
-```
-
-```console
-$ docker buildx bake -f docker-bake1.hcl -f docker-bake2.hcl --print app
-```
-```json
-{
-  "group": {
-    "default": {
-      "targets": [
-        "app"
-      ]
-    }
-  },
-  "target": {
-    "app": {
-      "context": ".",
-      "dockerfile": "Dockerfile",
-      "args": {
-        "v1": "pre--ABCDEF-",
-        "v2": "ABCDEF-post"
-      }
-    }
-  }
-}
-```
-
 ## Using typed variables
 
 Non-string variables are also accepted. The value passed with env is parsed
@@ -398,10 +328,3 @@ $ docker buildx bake --print app
   }
 }
 ```
-
-## Built-in variables
-
-* `BAKE_CMD_CONTEXT` can be used to access the main `context` for bake command
-  from a bake file that has been [imported remotely](file-definition.md#remote-definition).
-* `BAKE_LOCAL_PLATFORM` returns the current platform's default platform
-  specification (e.g. `linux/amd64`).

docs/guides/bake/index.md

@@ -34,6 +34,6 @@ and also allows better code reuse, different target groups and extended features
 
 * [File definition](file-definition.md)
 * [Configuring builds](configuring-build.md)
-* [HCL variables and functions](hcl-vars-funcs.md)
+* [User defined HCL functions](hcl-funcs.md)
 * [Defining additional build contexts and linking targets](build-contexts.md)
 * [Extension field with Compose](compose-xbake.md)