fix: invalid command, unrelated output chunks, too large minimal exam… (

#21859)

FIXes in the Docker Bake documentation.

## Description

[x] Commands not matching outputs: _(e.g.: the presence of a group on
the CLI affect the group section in the output)_
[x] Some file not being named bring about confusion to the reader
_(e.g.: [Using a Target as Build
Context](https://docs.docker.com/build/bake/contexts/#using-a-target-as-a-build-context)
is not clear about needed two distinct Dockerfiles, or [Using a
secondary source
directory](https://docs.docker.com/build/bake/contexts/#using-a-secondary-source-directory)
about the fact that the first stage in the Dockerfile does not have to
be defined at all)_
[x] Multiple confusing relationships between input and output _(e.g.:
the [Variables in Bake](https://docs.docker.com/build/bake/variables/)
part shows multiple `webapp` target in the outputs whilst the HCL input
only defines a `default` target)_

## Related issues or tickets

<!-- Related issues, pull requests, or Jira tickets -->

## Reviews

<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->

- [ ] Technical review
- [x] Editorial review
- [ ] Product review

---------

Signed-off-by: Salathiel <[email protected]>
Co-authored-by: David Karlsson <[email protected]>

content/manuals/build/bake/_index.md

@@ -14,7 +14,7 @@ A Bake file can be written in HCL, JSON, or YAML formats, where the YAML format
 is an extension of a Docker Compose file. Here's an example Bake file in HCL
 format:
 
-```hcl
+```hcl {title=docker-bake.hcl}
 group "default" {
   targets = ["frontend", "backend"]
 }

content/manuals/build/bake/contexts.md

@@ -29,14 +29,13 @@ Supported context values are:
 
 ## Pinning alpine image
 
-```dockerfile
+```dockerfile {title=Dockerfile}
 # syntax=docker/dockerfile:1
 FROM alpine
 RUN echo "Hello world"
 ```
 
-```hcl
-# docker-bake.hcl
+```hcl {title=docker-bake.hcl}
 target "app" {
   contexts = {
     alpine = "docker-image://alpine:3.13"
@@ -46,16 +45,14 @@ target "app" {
 
 ## Using a secondary source directory
 
-```dockerfile
-# syntax=docker/dockerfile:1
-FROM scratch AS src
-
+```dockerfile {title=Dockerfile}
 FROM golang
 COPY --from=src . .
 ```
 
-```hcl
-# docker-bake.hcl
+```hcl {title=docker-bake.hcl}
+# Running `docker buildx bake app` will result in `src` not pointing
+# to some previous build stage but to the client filesystem, not part of the context.
 target "app" {
   contexts = {
     src = "../path/to/source"
@@ -68,14 +65,16 @@ target "app" {
 To use a result of one target as a build context of another, specify the target
 name with `target:` prefix.
 
-```dockerfile
+```dockerfile {title=baseapp.Dockerfile}
+FROM scratch
+```
+```dockerfile {title=Dockerfile}
 # syntax=docker/dockerfile:1
 FROM baseapp
 RUN echo "Hello world"
 ```
 
-```hcl
-# docker-bake.hcl
+```hcl {title=docker-bake.hcl}
 target "base" {
   dockerfile = "baseapp.Dockerfile"
 }
@@ -119,7 +118,7 @@ result in significant impact on build time, depending on your build
 configuration. For example, say you have a Bake file that defines the following
 group of targets:
 
-```hcl
+```hcl {title=docker-bake.hcl}
 group "default" {
   targets = ["target1", "target2"]
 }
@@ -148,7 +147,7 @@ context that only loads the context files, and have each target that needs
 those files reference that named context. For example, the following Bake file
 defines a named target `ctx`, which is used by both `target1` and `target2`:
 
-```hcl
+```hcl {title=docker-bake.hcl}
 group "default" {
   targets = ["target1", "target2"]
 }
@@ -177,7 +176,7 @@ The named context `ctx` represents a Dockerfile stage, which copies the files
 from its context (`.`). Other stages in the Dockerfile can now reference the
 `ctx` named context and, for example, mount its files with `--mount=from=ctx`.
 
-```dockerfile
+```dockerfile {title=Dockerfile}
 FROM scratch AS ctx
 COPY --link . .
 

content/manuals/build/bake/expressions.md

@@ -30,7 +30,7 @@ Printing the Bake file with the `--print` flag shows the evaluated value for
 the `answer` build argument.
 
 ```console
-$ docker buildx bake --print app
+$ docker buildx bake --print
 ```
 
 ```json
@@ -76,13 +76,8 @@ $ docker buildx bake --print
 
 ```json
 {
-  "group": {
-    "default": {
-      "targets": ["default"]
-    }
-  },
   "target": {
-    "webapp": {
+    "default": {
       "context": ".",
       "dockerfile": "Dockerfile",
       "tags": ["my-image:latest"]

content/manuals/build/bake/inheritance.md

@@ -10,7 +10,7 @@ Targets can inherit attributes from other targets, using the `inherits`
 attribute. For example, imagine that you have a target that builds a Docker
 image for a development environment:
 
-```hcl
+```hcl {title=docker-bake.hcl}
 target "app-dev" {
   args = {
     GO_VERSION = "{{% param example_go_version %}}"
@@ -28,7 +28,7 @@ slightly different attributes for a production build. In this example, the
 `app-release` target inherits the `app-dev` target, but overrides the `tags`
 attribute and adds a new `platforms` attribute:
 
-```hcl
+```hcl {title=docker-bake.hcl}
 target "app-release" {
   inherits = ["app-dev"]
   tags = ["docker.io/username/myapp:latest"]
@@ -43,7 +43,7 @@ shared attributes for all or many of the build targets in the project. For
 example, the following `_common` target defines a common set of build
 arguments:
 
-```hcl
+```hcl {title=docker-bake.hcl}
 target "_common" {
   args = {
     GO_VERSION = "{{% param example_go_version %}}"
@@ -55,7 +55,7 @@ target "_common" {
 You can then inherit the `_common` target in other targets to apply the shared
 attributes:
 
-```hcl
+```hcl {title=docker-bake.hcl}
 target "lint" {
   inherits = ["_common"]
   dockerfile = "./dockerfiles/lint.Dockerfile"
@@ -88,7 +88,7 @@ When a target inherits another target, it can override any of the inherited
 attributes. For example, the following target overrides the `args` attribute
 from the inherited target:
 
-```hcl
+```hcl {title=docker-bake.hcl}
 target "app-dev" {
   inherits = ["_common"]
   args = {
@@ -110,7 +110,7 @@ The `inherits` attribute is a list, meaning you can reuse attributes from
 multiple other targets. In the following example, the app-release target reuses
 attributes from both the `app-dev` and `_common` targets.
 
-```hcl
+```hcl {title=docker-bake.hcl}
 target "_common" {
   args = {
     GO_VERSION = "{{% param example_go_version %}}"

content/manuals/build/bake/introduction.md

@@ -71,7 +71,7 @@ $ docker build \
 
 The Bake equivalent would be:
 
-```hcl
+```hcl {title=docker-bake.hcl}
 target "myapp" {
   context = "."
   dockerfile = "Dockerfile"

content/manuals/build/bake/matrices.md

@@ -19,7 +19,7 @@ should resolve, use the name attribute.
 The following example resolves the app target to `app-foo` and `app-bar`. It
 also uses the matrix value to define the [target build stage](/build/bake/reference/#targettarget).
 
-```hcl
+```hcl {title=docker-bake.hcl}
 target "app" {
   name = "app-${tgt}"
   matrix = {
@@ -73,7 +73,7 @@ The following example builds four targets:
 - `app-bar-1-0`
 - `app-bar-2-0`
 
-```hcl
+```hcl {title=docker-bake.hcl}
 target "app" {
   name = "app-${tgt}-${replace(version, ".", "-")}"
   matrix = {
@@ -98,7 +98,7 @@ The following example builds two targets:
 - `app-foo-1-0`
 - `app-bar-2-0`
 
-```hcl
+```hcl {title=docker-bake.hcl}
 target "app" {
   name = "app-${item.tgt}-${replace(item.version, ".", "-")}"
   matrix = {

content/manuals/build/bake/remote-definition.md

@@ -91,7 +91,7 @@ execution context as named contexts.
 The following example defines the `docs` context as `./src/docs/content`,
 relative to the current working directory where Bake is run as a named context.
 
-```hcl
+```hcl {title=docker-bake.hcl}
 target "default" {
   contexts = {
     docs = "cwd://src/docs/content"

content/manuals/build/bake/targets.md

@@ -9,7 +9,7 @@ keywords: bake, target, targets, buildx, docker, buildkit, default
 A target in a Bake file represents a build invocation. It holds all the
 information you would normally pass to a `docker build` command using flags.
 
-```hcl
+```hcl {title=docker-bake.hcl}
 target "webapp" {
   dockerfile = "webapp.Dockerfile"
   tags = ["docker.io/username/webapp:latest"]
@@ -35,7 +35,7 @@ $ docker buildx bake webapp api tests
 If you don't specify a target when running `docker buildx bake`, Bake will
 build the target named `default`.
 
-```hcl
+```hcl {title=docker-bake.hcl}
 target "default" {
   dockerfile = "webapp.Dockerfile"
   tags = ["docker.io/username/webapp:latest"]
@@ -61,7 +61,7 @@ For all the properties you can set for a target, see the [Bake reference](/build
 You can group targets together using the `group` block. This is useful when you
 want to build multiple targets at once.
 
-```hcl
+```hcl {title=docker-bake.hcl}
 group "all" {
   targets = ["webapp", "api", "tests"]
 }

content/manuals/build/bake/variables.md

@@ -15,16 +15,16 @@ environment variables.
 
 Use the `variable` block to define a variable.
 
-```hcl
+```hcl {title=docker-bake.hcl}
 variable "TAG" {
   default = "docker.io/username/webapp:latest"
 }
 ```
 
 The following example shows how to use the `TAG` variable in a target.
 
-```hcl
-target "default" {
+```hcl {title=docker-bake.hcl}
+target "webapp" {
   context = "."
   dockerfile = "Dockerfile"
   tags = [ TAG ]
@@ -37,7 +37,7 @@ Bake supports string interpolation of variables into values. You can use the
 `${}` syntax to interpolate a variable into a value. The following example
 defines a `TAG` variable with a value of `latest`.
 
-```hcl
+```hcl {title=docker-bake.hcl}
 variable "TAG" {
   default = "latest"
 }
@@ -46,8 +46,16 @@ variable "TAG" {
 To interpolate the `TAG` variable into the value of an attribute, use the
 `${TAG}` syntax.
 
-```hcl
-target "default" {
+```hcl {title=docker-bake.hcl}
+group "default" {
+  targets = [ "webapp" ]
+}
+
+variable "TAG" {
+  default = "latest"
+}
+
+target "webapp" {
   context = "."
   dockerfile = "Dockerfile"
   tags = ["docker.io/username/webapp:${TAG}"]
@@ -87,7 +95,7 @@ range, or other condition, you can define custom validation rules using the
 In the following example, validation is used to enforce a numeric constraint on
 a variable value; the `PORT` variable must be 1024 or higher.
 
-```hcl
+```hcl {title=docker-bake.hcl}
 # Define a variable `PORT` with a default value and a validation rule
 variable "PORT" {
   default = 3000  # Default value assigned to `PORT`
@@ -115,7 +123,7 @@ the variable. All conditions must be `true`.
 
 Here’s an example:
 
-```hcl
+```hcl {title=docker-bake.hcl}
 # Define a variable `VAR` with multiple validation rules
 variable "VAR" {
   # First validation block: Ensure the variable is not empty
@@ -148,7 +156,7 @@ dependent variables are set correctly before proceeding.
 
 Here’s an example:
 
-```hcl
+```hcl {title=docker-bake.hcl}
 # Define a variable `FOO`
 variable "FOO" {}
 
@@ -171,8 +179,8 @@ will trigger the validation error.
 If you want to bypass variable interpolation when parsing the Bake definition,
 use double dollar signs (`$${VARIABLE}`).
 
-```hcl
-target "default" {
+```hcl {title=docker-bake.hcl}
+target "webapp" {
   dockerfile-inline = <<EOF
   FROM alpine
   ARG TARGETARCH
@@ -215,7 +223,7 @@ variable "BASE_LATEST" {
   default = "${BASE_IMAGE}:latest"
 }
 
-target "default" {
+target "webapp" {
   contexts = {
     base = BASE_LATEST
   }
@@ -233,7 +241,7 @@ $ docker buildx bake -f vars.hcl -f docker-bake.hcl --print app
 ```json
 {
   "target": {
-    "default": {
+    "webapp": {
       "context": ".",
       "contexts": {
         "base": "docker.io/library/alpine:latest"