docs: follow-ups to builders page refactor

docs-v2/content/en/docs/builders/_index.md

@@ -0,0 +1,29 @@
+---
+title: "Build"
+linkTitle: "Build"
+weight: 42
+featureId: build
+aliases: [/docs/how-tos/builders, docs/pipeline-stages/builders]
+no_list: true
+---
+
+Skaffold supports different [tools]({{< relref "/docs/builders/builder-types" >}}) for building images across different [build environments]({{< relref "/docs/builders/build-environments" >}}).
+
+|    | [Local Build]({{< relref "/docs/builders/build-environments/local" >}}) | [In Cluster Build]({{< relref "/docs/builders/build-environments/in-cluster" >}}) | [Remote on Google Cloud Build]({{< relref "/docs/builders/build-environments/cloud-build" >}}) |
+|----|:-----------:|:----------------:|:----------------------------:|
+| **Dockerfile** | [Yes]({{< relref "/docs/builders/builder-types/docker#dockerfile-locally" >}}) | [Yes]({{< relref "/docs/builders/builder-types/docker#dockerfile-in-cluster-with-kaniko" >}}) | [Yes]({{< relref "/docs/builders/builder-types/docker#dockerfile-remotely-with-google-cloud-build" >}}) |
+| **Jib Maven and Gradle** | [Yes]({{< relref "/docs/builders/builder-types/jib#jib-maven-and-gradle-locally" >}}) | - | [Yes]({{< relref "/docs/builders/builder-types/jib#remotely-with-google-cloud-build" >}}) |
+| **Cloud Native Buildpacks** | [Yes]({{< relref "/docs/builders/builder-types/buildpacks" >}}) | - | [Yes]({{< relref "/docs/builders/builder-types/buildpacks" >}}) |
+| **Bazel** | [Yes]({{< relref "/docs/builders/builder-types/bazel" >}}) | - | - |
+| **ko** | [Yes]({{< relref "/docs/builders/builder-types/ko" >}}) | - | [Yes]({{< relref "/docs/builders/builder-types/ko#remote-builds" >}}) |
+| **Custom Script** | [Yes]({{<relref "/docs/builders/builder-types/custom#custom-build-script-locally" >}}) | [Yes]({{<relref "/docs/builders/builder-types/custom#custom-build-script-in-cluster" >}}) | - |
+
+## Configuration
+
+The `build` section in the Skaffold configuration file, `skaffold.yaml`,
+controls how artifacts are built. To use a specific tool for building
+artifacts, add the value representing the tool and options for using that tool
+to the `build` section.
+
+For detailed per-builder [Skaffold Configuration]({{< relref "/docs/design/config.md" >}}) options,
+see [skaffold.yaml References]({{< relref "/docs/references/yaml" >}}).

docs-v2/content/en/docs/builders/build-environments/_index.md

@@ -0,0 +1,11 @@
+---
+title: "Build environments"
+linkTitle: "Environments"
+weight: 20
+no_list: true
+---
+
+Skaffold supports the following build environments:
+* [Local build]({{< relref "/docs/builders/build-environments/local" >}})
+* [In cluster build]({{< relref "/docs/builders/build-environments/in-cluster" >}})
+* [Remotely on Google Cloud Build]({{< relref "/docs/builders/build-environments/cloud-build" >}})

docs-v2/content/en/docs/pipeline-stages/builders/build-environments/cloud-build.md → docs-v2/content/en/docs/builders/build-environments/cloud-build.md

@@ -49,6 +49,6 @@ When artifacts are built in parallel, the build logs are still printed in sequen
 
 ## Restrictions
 
-Skaffold currently supports [Docker]({{<relref "/docs/pipeline-stages/builders/builder-types/docker#dockerfile-remotely-with-google-cloud-build">}}),
-[Jib]({{<relref "/docs/pipeline-stages/builders/builder-types/jib#remotely-with-google-cloud-build">}})
+Skaffold currently supports [Docker]({{<relref "/docs/builders/builder-types/docker#dockerfile-remotely-with-google-cloud-build">}}),
+[Jib]({{<relref "/docs/builders/builder-types/jib#remotely-with-google-cloud-build">}})
 on Google Cloud Build.

docs-v2/content/en/docs/pipeline-stages/builders/build-environments/in-cluster.md → docs-v2/content/en/docs/builders/build-environments/in-cluster.md

@@ -4,8 +4,8 @@ linkTitle: "In cluster"
 weight: 20
 ---
 
-Skaffold supports building in cluster via [Kaniko]({{< relref "/docs/pipeline-stages/builders/builder-types/docker#dockerfile-in-cluster-with-kaniko" >}}) 
-or [Custom Build Script]({{<relref "/docs/pipeline-stages/builders/builder-types/custom#custom-build-script-in-cluster" >}}).
+Skaffold supports building in cluster via [Kaniko]({{< relref "/docs/builders/builder-types/docker#dockerfile-in-cluster-with-kaniko" >}}) 
+or [Custom Build Script]({{<relref "/docs/builders/builder-types/custom#custom-build-script-in-cluster" >}}).
 
 ## Configuration
 

docs-v2/content/en/docs/pipeline-stages/builders/build-environments/local.md → docs-v2/content/en/docs/builders/build-environments/local.md

@@ -53,6 +53,6 @@ useful for images that are expensive to build.
 a _stale image_, where the imported image is different from the image
 that would have been built from the artifact source.
 `tryImportMissing` is best used with a
-[tagging policy]({{<relref "/docs/pipeline-stages/taggers" >}}) such as
+[tagging policy]({{<relref "/docs/taggers" >}}) such as
 `imageDigest` or `gitCommit`'s `TreeSha` or `AbbrevTreeSha` variants,
 where the tag is computed using the artifact's contents.

docs-v2/content/en/docs/builders/builder-types/_index.md

@@ -0,0 +1,13 @@
+---
+title: "Builder types"
+linkTitle: "Builder types"
+weight: 10
+no_list: true
+---
+
+Skaffold supports the following builder types:
+* [Docker]({{< relref "/docs/builders/builder-types/docker" >}})
+* [Jib]({{< relref "/docs/builders/builder-types/jib" >}})
+* [Bazel]({{< relref "/docs/builders/builder-types/bazel" >}})
+* [Custom build script]({{< relref "/docs/builders/builder-types/custom" >}})
+* [ko]({{< relref "/docs/builders/builder-types/ko" >}})

docs-v2/content/en/docs/pipeline-stages/builders/builder-types/bazel.md → docs-v2/content/en/docs/builders/builder-types/bazel.md

@@ -3,7 +3,7 @@ title: "Bazel"
 linkTitle: "Bazel"
 weight: 30
 featureId: build
-aliases: [/docs/builders/bazel]
+aliases: [/docs/pipeline-stages/builders/bazel]
 ---
 
 [Bazel](https://bazel.build/) is a fast, scalable, multi-language, and

docs-v2/content/en/docs/pipeline-stages/builders/builder-types/buildpacks.md → docs-v2/content/en/docs/builders/builder-types/buildpacks.md

@@ -3,7 +3,7 @@ title: "Cloud Native Buildpacks"
 linkTitle: "Buildpacks"
 weight: 50
 featureId: build.buildpacks
-aliases: [/docs/how-tos/buildpacks, /docs/builders/buildpacks]
+aliases: [/docs/how-tos/buildpacks, /docs/pipeline-stages/builders/buildpacks]
 ---
 
 [Cloud Native Buildpacks](https://buildpacks.io/) enable building

docs-v2/content/en/docs/pipeline-stages/builders/builder-types/custom.md → docs-v2/content/en/docs/builders/builder-types/custom.md

@@ -3,7 +3,7 @@ title: "Custom Build Script"
 linkTitle: "Custom"
 weight: 40
 featureId: build.custom
-aliases: [/docs/builders/custom]
+aliases: [/docs/pipeline-stages/builders/custom]
 ---
 
 Custom build scripts allow Skaffold users the flexibility to build artifacts with any builder they desire. 

docs-v2/content/en/docs/pipeline-stages/builders/builder-types/docker.md → docs-v2/content/en/docs/builders/builder-types/docker.md

@@ -3,14 +3,14 @@ title: "Docker Build"
 linkTitle: "Docker"
 weight: 10
 featureId: build
-aliases: [/docs/builders/docker]
+aliases: [/docs/pipeline-stages/builders/docker]
 ---
 
 Skaffold supports building with Dockerfile
 
-1. [locally]({{< relref "/docs/pipeline-stages/builders/builder-types/docker#dockerfile-with-docker-locally">}})
-2. [in cluster]({{< relref "/docs/pipeline-stages/builders/builder-types/docker#dockerfile-in-cluster-with-kaniko">}})
-3. [on Google CloudBuild ]({{< relref "/docs/pipeline-stages/builders/builder-types/docker#dockerfile-remotely-with-google-cloud-build">}})
+1. [locally]({{< relref "/docs/builders/builder-types/docker#dockerfile-with-docker-locally">}})
+2. [in cluster]({{< relref "/docs/builders/builder-types/docker#dockerfile-in-cluster-with-kaniko">}})
+3. [on Google CloudBuild ]({{< relref "/docs/builders/builder-types/docker#dockerfile-remotely-with-google-cloud-build">}})
 
 ## Dockerfile with Docker locally
 
@@ -117,7 +117,7 @@ Docker image `gcr.io/k8s-skaffold/example` with Kaniko:
 
 ## Dockerfile remotely with Google Cloud Build
 
-Skaffold can build the Dockerfile image remotely with [Google Cloud Build]({{<relref "/docs/pipeline-stages/builders#remotely-on-google-cloud-build">}}).
+Skaffold can build the Dockerfile image remotely with [Google Cloud Build]({{<relref "/docs/builders#remotely-on-google-cloud-build">}}).
 
 **Configuration**
 

docs-v2/content/en/docs/pipeline-stages/builders/builder-types/jib.md → docs-v2/content/en/docs/builders/builder-types/jib.md

@@ -3,7 +3,7 @@ title: "Jib Build"
 linkTitle: "Jib"
 weight: 20
 featureId: build
-aliases: [/docs/builders/jib]
+aliases: [/docs/pipeline-stages/builders/jib]
 ---
 
 [Jib](https://github.com/GoogleContainerTools/jib#jib) is a set of plugins for
@@ -19,8 +19,8 @@ Skaffold requires using Jib v1.4.0 or later.
 
 Skaffold supports building with Jib
 
-1. [locally]({{< relref "/docs/pipeline-stages/builders/builder-types/jib#jib-maven-and-gradle-locally" >}}) and
-2. [remotely on Google Cloud Build]({{< relref "/docs/pipeline-stages/builders/builder-types/jib#remotely-with-google-cloud-build" >}})
+1. [locally]({{< relref "/docs/builders/builder-types/jib#jib-maven-and-gradle-locally" >}}) and
+2. [remotely on Google Cloud Build]({{< relref "/docs/builders/builder-types/jib#remotely-with-google-cloud-build" >}})
 
 ## Jib Maven and Gradle locally
 **Configuration**
@@ -92,7 +92,7 @@ a container image.  Then for each such sub-project:
 
 ## Remotely with Google Cloud Build
 
-Skaffold can build artifacts using Jib remotely on [Google Cloud Build]({{<relref "/docs/pipeline-stages/builders#remotely-on-google-cloud-build">}}).
+Skaffold can build artifacts using Jib remotely on [Google Cloud Build]({{<relref "/docs/builders#remotely-on-google-cloud-build">}}).
 
 **Configuration**
 
@@ -122,7 +122,7 @@ artifacts:
 
 ### Using the `custom` builder
 
-Some users may have more complicated builds that may be better suited to using the [`custom` builder](https://skaffold.dev/docs/pipeline-stages/builders/builder-types/custom/).  For example, the `jib` builder normally invokes the `prepare-package` goal rather than `package` as Jib packages the `.class` files rather than package in the jar.  But some plugins require the `package` goal.
+Some users may have more complicated builds that may be better suited to using the [`custom` builder](https://skaffold.dev/docs/builders/builder-types/custom/).  For example, the `jib` builder normally invokes the `prepare-package` goal rather than `package` as Jib packages the `.class` files rather than package in the jar.  But some plugins require the `package` goal.
 ```
 artifacts:
 - image: jib-gradle-image

docs-v2/content/en/docs/pipeline-stages/builders/builder-types/ko.md → docs-v2/content/en/docs/builders/builder-types/ko.md

@@ -3,7 +3,7 @@ title: "ko"
 linkTitle: "ko"
 weight: 60
 featureId: build.ko
-aliases: [/docs/builders/ko]
+aliases: [/docs/pipeline-stages/builders/ko]
 ---
 
 [`ko`](https://github.com/google/ko) enables fast, standardized, reproducible,
@@ -17,28 +17,28 @@ to use the ko builder.
 
 Compared to ...
 
-- [the Cloud Native buildpacks builder]({{< relref "/docs/pipeline-stages/builders/builder-types/buildpacks" >}}),
+- [the Cloud Native buildpacks builder]({{< relref "/docs/builders/builder-types/buildpacks" >}}),
   the ko builder is
   [fast](https://cloud.google.com/blog/topics/developers-practitioners/ship-your-go-applications-faster-cloud-run-ko),
   doesn't require Docker, and uses a default base image that has a small
   attack surface
   ([distroless](https://github.com/GoogleContainerTools/distroless)).
 
-- [the Docker builder]({{< relref "/docs/pipeline-stages/builders/builder-types/docker" >}}),
+- [the Docker builder]({{< relref "/docs/builders/builder-types/docker" >}}),
   the ko builder standardizes builds, avoiding artisanal
   [snowflake](https://martinfowler.com/bliki/SnowflakeServer.html)
   `Dockerfile`s. It also doesn't require the Docker daemon, so builds can run
   in environments where Docker isn't available for security reasons.
 
-- [the Kaniko builder]({{< relref "/docs/pipeline-stages/builders/builder-types/docker#dockerfile-in-cluster-with-kaniko" >}}),
+- [the Kaniko builder]({{< relref "/docs/builders/builder-types/docker#dockerfile-in-cluster-with-kaniko" >}}),
   the ko builder doesn't need a Kubernetes cluster, and it avoids the
   previously-mentioned artisanal `Dockerfile`s.
 
-- [the Bazel builder]({{< relref "/docs/pipeline-stages/builders/builder-types/bazel" >}}),
+- [the Bazel builder]({{< relref "/docs/builders/builder-types/bazel" >}}),
   the ko builder doesn't require users to adopt Bazel. However, we recommend
   the Bazel builder for users who already use Bazel for their Go apps.
 
-- [the custom builder]({{< relref "/docs/pipeline-stages/builders/builder-types/custom" >}}),
+- [the custom builder]({{< relref "/docs/builders/builder-types/custom" >}}),
   the ko builder standardizes builds, as it doesn't require running `ko` using
   custom shell scripts.
 
@@ -257,7 +257,7 @@ Useful tips for existing `ko` users:
 
 - You can generate `skaffold.yaml` files by examining an existing code base,
   using the command
-  [`skaffold init --XXenableKoInit=true`]({{< relref "/docs/pipeline-stages/init" >}}).
+  [`skaffold init --XXenableKoInit=true`]({{< relref "/docs/init" >}}).
   Select the Ko builder for your images when prompted.
 
 ### `ko` commands and workflows in Skaffold
@@ -391,7 +391,7 @@ To learn more about how Skaffold debugs Go applications, read the
 ### File sync
 
 The `ko` builder can
-[sync files to a running container]({{< relref "/docs/pipeline-stages/filesync" >}})
+[sync files to a running container]({{< relref "/docs/filesync" >}})
 when you run `skaffold dev`.
 
 The sync feature for the `ko` builder only works for 
@@ -439,7 +439,7 @@ The `ko` builder supports remote builds on Google Cloud Build. See the
 ### Using the `custom` builder
 
 If the ko builder doesn't support your use of `ko`, you can instead use the
-[`custom` builder]({{< relref "/docs/pipeline-stages/builders/builder-types/custom" >}}).
+[`custom` builder]({{< relref "/docs/builders/builder-types/custom" >}}).
 
 See the `custom` builder
 [example](https://github.com/GoogleContainerTools/skaffold/tree/main/examples/custom).

docs-v2/content/en/docs/pipeline-stages/builders/build-environments/cross-platform.md → docs-v2/content/en/docs/builders/cross-platform.md

@@ -32,5 +32,5 @@ The final list of target platforms need to ultimately be supported by the target
 | **Custom Script** | Cross-platform and multi-platform supported but requires user to implement it in the build script | Cross-platform and multi-platform supported but requires user to implement it in the build script | - |
 
 {{< alert title="Note" >}}
-Skaffold supports multi-platform image builds natively for the [jib builder]({{<relref "/docs/pipeline-stages/builders/builder-types/jib" >}}), the [ko builder]({{<relref "/docs/pipeline-stages/builders/builder-types/ko">}}) and the [custom builder]({{<relref "/docs/pipeline-stages/builders/builder-types/custom" >}}). For other builders that support building cross-architecture images, Skaffold will iteratively build a single platform image for each target architecture and stitch them together into a multi-platform image, and push it to the registry.
+Skaffold supports multi-platform image builds natively for the [jib builder]({{<relref "/docs/builders/builder-types/jib" >}}), the [ko builder]({{<relref "/docs/builders/builder-types/ko">}}) and the [custom builder]({{<relref "/docs/builders/builder-types/custom" >}}). For other builders that support building cross-architecture images, Skaffold will iteratively build a single platform image for each target architecture and stitch them together into a multi-platform image, and push it to the registry.
 {{< /alert >}}

docs-v2/content/en/docs/pipeline-stages/cleanup.md → docs-v2/content/en/docs/cleanup.md

@@ -1,11 +1,12 @@
 ---
 title: "Cleanup"
 linkTitle: "Cleanup"
-weight: 60
+weight: 47
 featureId: cleanup
+aliases: [/docs/pipeline-stages/cleanup]
 ---
 
-Skaffold works with [image builders]({{<relref "/docs/pipeline-stages/builders">}}) and [deployers]({{<relref "/docs/pipeline-stages/deployers">}}) 
+Skaffold works with [image builders]({{<relref "/docs/builders">}}) and [deployers]({{<relref "/docs/deployers">}}) 
 that both have side effects on both your local and deployment environments: 
 
 - resources are created in one or more namespaces in a Kubernetes cluster 

docs-v2/content/en/docs/pipeline-stages/deployers/_index.md → docs-v2/content/en/docs/deployers/_index.md

@@ -1,9 +1,9 @@
 ---
 title: "Deploy [UPDATED]"
 linkTitle: "Deploy [UPDATED]"
-weight: 10
+weight: 42
 featureId: deploy
-aliases: [/docs/how-tos/deployers]
+aliases: [/docs/how-tos/deployers, /docs/pipeline-stages/deployers]
 no_list: true
 ---
 
@@ -13,7 +13,7 @@ In the default case (no manifest provided using the kubectl or kpt deployer ), s
 * the Skaffold renderer _renders_ the final Kubernetes manifests: Skaffold replaces untagged image names in the Kubernetes manifests with the final tagged image names.
 It also might go through the extra intermediate step of expanding templates (for helm) or calculating overlays (for kustomize).  Additionally some deployers (docker) do not render manifests as such don't use this phase.
 * the Skaffold deployer _deploys_ the final Kubernetes manifests to the cluster (or to local docker for the docker deployer)
-* the Skaffold deployer performs [status checks]({{< relref "/docs/pipeline-stages/status-check" >}}) and waits for the deployed resources to stabilize.
+* the Skaffold deployer performs [status checks]({{< relref "/docs/status-check" >}}) and waits for the deployed resources to stabilize.
 ### Supported deployers
 
 Skaffold supports the following tools for deploying applications:

docs-v2/content/en/docs/pipeline-stages/deployers/cloudrun.md → docs-v2/content/en/docs/deployers/cloudrun.md

@@ -3,6 +3,7 @@ title: "Google Cloud Run [NEW]"
 linkTitle: "Google Cloud Run [NEW]"
 weight: 60
 featureId: deploy.cloudrun
+aliases: [/docs/pipeline-stages/deployers/cloudrun]
 ---
 
 {{< alert title="Note" >}}

docs-v2/content/en/docs/pipeline-stages/deployers/docker.md → docs-v2/content/en/docs/deployers/docker.md

@@ -3,6 +3,7 @@ title: "Docker"
 linkTitle: "Docker"
 weight: 50
 featureId: deploy.docker
+aliases: [/docs/pipeline-stages/deployers/docker]
 ---
 
 {{< alert title="Note" >}}

docs-v2/content/en/docs/pipeline-stages/deployers/helm.md → docs-v2/content/en/docs/deployers/helm.md

@@ -3,6 +3,7 @@ title: "Helm [UPDATED]"
 linkTitle: "Helm [UPDATED]"
 weight: 40
 featureId: deploy
+aliases: [/docs/pipeline-stages/deployers/helm]
 ---
 
 [`helm`](https://helm.sh/) is a package manager for Kubernetes that helps you

docs-v2/content/en/docs/pipeline-stages/deployers/kpt.md → docs-v2/content/en/docs/deployers/kpt.md

@@ -3,6 +3,7 @@ title: "Kpt [UPDATED]"
 linkTitle: "Kpt [UPDATED]"
 weight: 30
 featureId: deploy
+aliases: [/docs/pipeline-stages/deployers/kpt]
 ---
 
 ## Rendering with kpt

docs-v2/content/en/docs/pipeline-stages/deployers/kubectl.md → docs-v2/content/en/docs/deployers/kubectl.md

@@ -3,6 +3,7 @@ title: "Kubectl"
 linkTitle: "Kubectl"
 weight: 20
 featureId: deploy
+aliases: [/docs/pipeline-stages/deployers/kubectl]
 ---
 
 ## Deploying with kubectl

docs-v2/content/en/docs/design/config.md

@@ -13,9 +13,9 @@ You can configure Skaffold with the Skaffold configuration file,
 | `apiVersion` | The Skaffold API version you would like to use. The current API version is {{< skaffold-version >}}. |
 | `kind`  |  The Skaffold configuration file has the kind `Config`.  |
 | `metadata`  |  Holds additional properties like the `name` of this configuration.  |
-| `build`  |  Specifies how Skaffold builds artifacts. You have control over what tool Skaffold can use, how Skaffold tags artifacts and how Skaffold pushes artifacts. Skaffold supports using local Docker daemon, Google Cloud Build, Kaniko, or Bazel to build artifacts. See [Builders](/docs/pipeline-stages/builders) and [Taggers]({{< relref "/docs/pipeline-stages/taggers" >}}) for more information. |
-| `test` |  Specifies how Skaffold tests artifacts. Skaffold supports [container-structure-tests](https://github.com/GoogleContainerTools/container-structure-test) to test built artifacts and custom tests to run custom commands as part of the development pipeline. See [Testers]({{< relref "/docs/pipeline-stages/testers" >}}) for more information. |
-| `deploy` |  Specifies how Skaffold deploys artifacts. Skaffold supports using `kubectl`, `helm`, or `kustomize` to deploy artifacts. See [Deployers]({{< relref "/docs/pipeline-stages/deployers" >}}) for more information. |
+| `build`  |  Specifies how Skaffold builds artifacts. You have control over what tool Skaffold can use, how Skaffold tags artifacts and how Skaffold pushes artifacts. Skaffold supports using local Docker daemon, Google Cloud Build, Kaniko, or Bazel to build artifacts. See [Builders](/docs/builders) and [Taggers]({{< relref "/docs/taggers" >}}) for more information. |
+| `test` |  Specifies how Skaffold tests artifacts. Skaffold supports [container-structure-tests](https://github.com/GoogleContainerTools/container-structure-test) to test built artifacts and custom tests to run custom commands as part of the development pipeline. See [Testers]({{< relref "/docs/testers" >}}) for more information. |
+| `deploy` |  Specifies how Skaffold deploys artifacts. Skaffold supports using `kubectl`, `helm`, or `kustomize` to deploy artifacts. See [Deployers]({{< relref "/docs/deployers" >}}) for more information. |
 | `profiles`|  Profile is a set of settings that, when activated, overrides the current configuration. You can use Profile to override the `build`, `test` and `deploy` sections. |
 | `requires`|  Specifies a list of other skaffold configurations to import into the current config |