dockerfile: switch location and release notes

_config.yml

@@ -178,6 +178,6 @@ fetch-remote:
     default_branch: "master"
     ref: "master"
     paths:
-      - dest: "engine/reference/builder.md"
+      - dest: "reference/dockerfile"
         src:
           - "frontend/dockerfile/docs/reference.md"

_data/toc.yaml

@@ -1039,8 +1039,14 @@ reference:
         title: ExecResultV0
       - path: /desktop/extensions-sdk/dev/api/reference/interfaces/BackendV0/
         title: BackendV0  
-- title: Dockerfile reference
-  path: /engine/reference/builder/
+
+- sectiontitle: Dockerfile reference
+  section:
+    - path: /reference/dockerfile/
+      title: Dockerfile specification
+    - path: /reference/dockerfile/release-notes/
+      title: Release notes
+
 - sectiontitle: Compose file reference
   section:
     - path: /compose/compose-file/

_includes/guides/create-dockerfile.md

@@ -23,10 +23,10 @@ your text editor.
 > We recommend using the default (`Dockerfile`) for your project's primary
 > Dockerfile, which is what we'll use for most examples in this guide.
 
-The first line to add to a Dockerfile is a [`# syntax` parser directive](/engine/reference/builder/#syntax).
+The first line to add to a Dockerfile is a [`# syntax` parser directive](/reference/dockerfile/index.md#syntax).
 While _optional_, this directive instructs the Docker builder what syntax to use
 when parsing the Dockerfile, and allows older Docker versions with BuildKit enabled
-to upgrade the parser before starting the build. [Parser directives](/engine/reference/builder/#parser-directives)
+to upgrade the parser before starting the build. [Parser directives](/reference/dockerfile/index.md#parser-directives)
 must appear before any other comment, whitespace, or Dockerfile instruction in
 your Dockerfile, and should be the first line in Dockerfiles.
 

_layouts/landing.html

@@ -126,7 +126,7 @@ <h5 class="title">How do I?</h5>
           </div>
           <div class="row">
             <div class="col-xs-12 col-md-6"><a href="/language/">Containerize language-specific apps using Docker</a></div>
-            <div class="col-xs-12 col-md-6"><a href="/engine/reference/builder/">Write a Dockerfile</a></div>
+            <div class="col-xs-12 col-md-6"><a href="/reference/dockerfile/">Write a Dockerfile</a></div>
             <div class="col-xs-12 col-md-6"><a href="/network/">Manage container networking</a></div>
             <div class="col-xs-12 col-md-6"><a href="/compose/compose-file/">Write a Docker Compose file</a></div>
             <div class="col-xs-12 col-md-6"><a href="/storage/">Work with volumes and bind mounts</a></div>
@@ -288,7 +288,7 @@ <h6>Getting Started with Docker</h6>
               <h6>Popular articles</h6>
               <p><a href="/engine/install/ubuntu/">Install Docker Engine on Ubuntu</a></p>
               <p><a href="/engine/reference/commandline/run/">Run a command in a container</a></p>
-              <p><a href="/engine/reference/builder/">Dockerfile reference</a></p>
+              <p><a href="/reference/dockerfile/">Dockerfile reference</a></p>
               <p><a href="/engine/reference/commandline/dockerd/#description">Docker daemon reference</a></p>
               <p><a href="/engine/reference/commandline/build/">Docker build reference</a></p>
             </div>

compose/compose-file/compose-file-v2.md

@@ -215,7 +215,7 @@ build:
 > In your Dockerfile, if you specify `ARG` before the `FROM` instruction,
 > `ARG` is not available in the build instructions under `FROM`.
 > If you need an argument to be available in both places, also specify it under
-> the `FROM` instruction. Refer to the [understand how ARGS and FROM interact](../../engine/reference/builder.md#understand-how-arg-and-from-interact)
+> the `FROM` instruction. Refer to the [understand how ARGS and FROM interact](../../reference/dockerfile/index.md#understand-how-arg-and-from-interact)
 > section in the documentation for usage details.
 
 You can omit the value when specifying a build argument, in which case its value
@@ -397,7 +397,7 @@ command: bundle exec thin -p 3000
 ```
 
 The command can also be a list, in a manner similar to
-[dockerfile](../../engine/reference/builder.md#cmd):
+[dockerfile](../../reference/dockerfile/index.md#cmd):
 
 ```yaml
 command: ["bundle", "exec", "thin", "-p", "3000"]
@@ -572,7 +572,7 @@ entrypoint: /code/entrypoint.sh
 ```
 
 The entrypoint can also be a list, in a manner similar to
-[dockerfile](../../engine/reference/builder.md#entrypoint):
+[dockerfile](../../reference/dockerfile/index.md#entrypoint):
 
 ```yaml
 entrypoint: ["php", "-d", "memory_limit=-1", "vendor/bin/phpunit"]
@@ -800,7 +800,7 @@ used.
 
 Configure a check that's run to determine whether or not containers for this
 service are "healthy". See the docs for the
-[HEALTHCHECK Dockerfile instruction](../../engine/reference/builder.md#healthcheck)
+[HEALTHCHECK Dockerfile instruction](../../reference/dockerfile/index.md#healthcheck)
 for details on how healthchecks work.
 
 ```yaml

compose/compose-file/compose-file-v3.md

@@ -280,7 +280,7 @@ build:
 > In your Dockerfile, if you specify `ARG` before the `FROM` instruction,
 > `ARG` is not available in the build instructions under `FROM`.
 > If you need an argument to be available in both places, also specify it under
-> the `FROM` instruction. Refer to the [understand how ARGS and FROM interact](../../engine/reference/builder.md#understand-how-arg-and-from-interact)
+> the `FROM` instruction. Refer to the [understand how ARGS and FROM interact](../../reference/dockerfile/index.md#understand-how-arg-and-from-interact)
 > section in the documentation for usage details.
 
 You can omit the value when specifying a build argument, in which case its value
@@ -444,7 +444,7 @@ command: bundle exec thin -p 3000
 ```
 
 The command can also be a list, in a manner similar to
-[dockerfile](../../engine/reference/builder.md#cmd):
+[dockerfile](../../reference/dockerfile/index.md#cmd):
 
 ```yaml
 command: ["bundle", "exec", "thin", "-p", "3000"]
@@ -1063,7 +1063,7 @@ entrypoint: /code/entrypoint.sh
 ```
 
 The entrypoint can also be a list, in a manner similar to
-[dockerfile](../../engine/reference/builder.md#entrypoint):
+[dockerfile](../../reference/dockerfile/index.md#entrypoint):
 
 ```yaml
 entrypoint: ["php", "-d", "memory_limit=-1", "vendor/bin/phpunit"]
@@ -1247,7 +1247,7 @@ An entry with the ip address and hostname is created in `/etc/hosts` inside cont
 
 Configure a check that's run to determine whether or not containers for this
 service are "healthy". See the docs for the
-[HEALTHCHECK Dockerfile instruction](../../engine/reference/builder.md#healthcheck)
+[HEALTHCHECK Dockerfile instruction](../../reference/dockerfile/index.md#healthcheck)
 for details on how healthchecks work.
 
 ```yaml

compose/compose-file/index.md

@@ -433,7 +433,7 @@ cgroup_parent: m-executor-abcd
 command: bundle exec thin -p 3000
 ```
 
-The command can also be a list, in a manner similar to [Dockerfile](https://docs.docker.com/engine/reference/builder/#cmd):
+The command can also be a list, in a manner similar to [Dockerfile](https://docs.docker.com/reference/dockerfile/#cmd):
 
 ```
 command: [ "bundle", "exec", "thin", "-p", "3000" ]
@@ -737,7 +737,7 @@ entrypoint: /code/entrypoint.sh
 ```
 
 The entrypoint can also be a list, in a manner similar to
-[Dockerfile](https://docs.docker.com/engine/reference/builder/#cmd):
+[Dockerfile](https://docs.docker.com/reference/dockerfile/#cmd):
 
 ```yml
 entrypoint:
@@ -1082,7 +1082,7 @@ been the case if `group_add` were not declared.
 
 `healthcheck` declares a check that's run to determine whether or not containers for this
 service are "healthy". This overrides
-[HEALTHCHECK Dockerfile instruction](https://docs.docker.com/engine/reference/builder/#healthcheck)
+[HEALTHCHECK Dockerfile instruction](https://docs.docker.com/reference/dockerfile/#healthcheck)
 set by the service's Docker image.
 
 ```yml

compose/gettingstarted.md

@@ -111,7 +111,7 @@ This tells Docker to:
 
 For more information on how to write Dockerfiles, see the
 [Docker user guide](../develop/index.md)
-and the [Dockerfile reference](/engine/reference/builder/).
+and the [Dockerfile reference](/reference/dockerfile/).
 
 
 ## Step 3: Define services in a Compose file

compose/samples-for-compose.md

@@ -16,7 +16,7 @@ The samples should help you to:
   [Compose files](compose-file/index.md) `docker-compose.yml` and
   `docker-stack.yml` files
 - understand the relationship between `docker-compose.yml` and
-  [Dockerfiles](/engine/reference/builder/)
+  [Dockerfiles](/reference/dockerfile/)
 - learn how to make calls to your application services from Compose files
 - learn how to deploy applications and services to a [swarm](../engine/swarm/index.md)
 

config/containers/logging/index.md

@@ -50,4 +50,4 @@ its errors to `/proc/self/fd/2` (which is `STDERR`). See the
 ## Next steps
 
 - Configure [logging drivers](configure.md).
-- Write a [Dockerfile](../../../engine/reference/builder.md).
+- Write a [Dockerfile](../../../reference/dockerfile/index.md).

config/labels-custom-metadata.md

@@ -78,7 +78,7 @@ the lifetime of the object. To change these labels you must recreate the object.
 Labels on swarm nodes and services can be updated dynamically.
 
 - Images and containers
-  - [Adding labels to images](../engine/reference/builder.md#label)
+  - [Adding labels to images](../reference/dockerfile/index.md#label)
   - [Overriding a container's labels at runtime](../engine/reference/commandline/run.md#set-metadata-on-container--l---label---label-file)
   - [Inspecting labels on images or containers](../engine/reference/commandline/inspect.md)
   - [Filtering images by label](../engine/reference/commandline/images.md#filtering)

desktop/extensions-sdk/extensions/labels.md

@@ -4,7 +4,7 @@ description: Docker extension labels
 keywords: Docker, extensions, sdk, labels
 ---
 
-[Labels](https://docs.docker.com/engine/reference/builder/#label) are specified in the extension's `Dockerfile` and used to provide information about the extension.
+[Labels](https://docs.docker.com/reference/dockerfile/#label) are specified in the extension's `Dockerfile` and used to provide information about the extension.
 
 | Label | Required | Description | Example |
 | --- | --- | --- | ---|

develop/develop-images/baseimages.md

@@ -107,7 +107,7 @@ If you want to test it out, you can clone
 
 There are lots of resources available to help you write your `Dockerfile`.
 
-* There's a [complete guide to all the instructions](../../engine/reference/builder.md) available for use in a `Dockerfile` in the reference section.
+* There's a [complete guide to all the instructions](../../reference/dockerfile/index.md) available for use in a `Dockerfile` in the reference section.
 * To help you write a clear, readable, maintainable `Dockerfile`, we've also
 written a [`Dockerfile` best practices guide](dockerfile_best-practices.md).
 * If your goal is to create a new Docker Official Image, read [Docker Official Images](../../docker-hub/official_images.md).

develop/develop-images/build_enhancements.md

@@ -20,7 +20,7 @@ on performance, storage management, feature functionality, and security.
 
 For more information on build options, see the reference guide on the
 [command line build options](../../engine/reference/commandline/build.md) and
-the [Dockerfile reference](/engine/reference/builder/) page.
+the [Dockerfile reference](/reference/dockerfile/) page.
 
 
 ## Requirements
@@ -124,7 +124,7 @@ version 1.2.0 and up. We recommend using `docker/dockerfile:1`, which always
 points to the latest release of the version 1 syntax. BuildKit automatically
 checks for updates of the syntax before building, making sure you are using the
 most current version. Learn more about the `syntax` directive in the
-[Dockerfile reference](/engine/reference/builder/#syntax).
+[Dockerfile reference](/reference/dockerfile/#syntax).
 
 ## New Docker Build secret information
 

develop/develop-images/dockerfile_best-practices.md

@@ -16,7 +16,7 @@ efficient images.
 Docker builds images automatically by reading the instructions from a
 `Dockerfile` -- a text file that contains all commands, in order, needed to
 build a given image. A `Dockerfile` adheres to a specific format and set of
-instructions which you can find at [Dockerfile reference](../../engine/reference/builder.md).
+instructions which you can find at [Dockerfile reference](../../reference/dockerfile/index.md).
 
 A Docker image consists of read-only layers each of which represents a
 Dockerfile  instruction. The layers are stacked and each one is a delta of the
@@ -248,7 +248,7 @@ EOF
 To exclude files not relevant to the build (without restructuring your source
 repository) use a `.dockerignore` file. This file supports exclusion patterns
 similar to `.gitignore` files. For information on creating one, see the
-[.dockerignore file](../../engine/reference/builder.md#dockerignore-file).
+[.dockerignore file](../../reference/dockerfile/index.md#dockerignore-file).
 
 ### Use multi-stage builds
 
@@ -402,7 +402,7 @@ maintainable `Dockerfile`.
 
 ### FROM
 
-[Dockerfile reference for the FROM instruction](../../engine/reference/builder.md#from)
+[Dockerfile reference for the FROM instruction](../../reference/dockerfile/index.md#from)
 
 Whenever possible, use current official images as the basis for your
 images. We recommend the [Alpine image](https://hub.docker.com/_/alpine/) as it
@@ -455,11 +455,11 @@ See [Understanding object labels](../../config/labels-custom-metadata.md)
 for guidelines about acceptable label keys and values. For information about
 querying labels, refer to the items related to filtering in
 [Managing labels on objects](../../config/labels-custom-metadata.md#manage-labels-on-objects).
-See also [LABEL](../../engine/reference/builder.md#label) in the Dockerfile reference.
+See also [LABEL](../../reference/dockerfile/index.md#label) in the Dockerfile reference.
 
 ### RUN
 
-[Dockerfile reference for the RUN instruction](../../engine/reference/builder.md#run)
+[Dockerfile reference for the RUN instruction](../../reference/dockerfile/index.md#run)
 
 Split long or complex `RUN` statements on multiple lines separated with
 backslashes to make your `Dockerfile` more readable, understandable, and
@@ -592,7 +592,7 @@ RUN set -o pipefail && wget -O - https://some.site | wc -l > /number
 
 ### CMD
 
-[Dockerfile reference for the CMD instruction](../../engine/reference/builder.md#cmd)
+[Dockerfile reference for the CMD instruction](../../reference/dockerfile/index.md#cmd)
 
 The `CMD` instruction should be used to run the software contained in your
 image, along with any arguments. `CMD` should almost always be used in the form
@@ -606,13 +606,13 @@ python and perl. For example, `CMD ["perl", "-de0"]`, `CMD ["python"]`, or `CMD
 ["php", "-a"]`. Using this form means that when you execute something like
 `docker run -it python`, you’ll get dropped into a usable shell, ready to go.
 `CMD` should rarely be used in the manner of `CMD ["param", "param"]` in
-conjunction with [`ENTRYPOINT`](../../engine/reference/builder.md#entrypoint), unless
+conjunction with [`ENTRYPOINT`](../../reference/dockerfile/index.md#entrypoint), unless
 you and your expected users are already quite familiar with how `ENTRYPOINT`
 works.
 
 ### EXPOSE
 
-[Dockerfile reference for the EXPOSE instruction](../../engine/reference/builder.md#expose)
+[Dockerfile reference for the EXPOSE instruction](../../reference/dockerfile/index.md#expose)
 
 The `EXPOSE` instruction indicates the ports on which a container listens
 for connections. Consequently, you should use the common, traditional port for
@@ -627,7 +627,7 @@ the recipient container back to the source (ie, `MYSQL_PORT_3306_TCP`).
 
 ### ENV
 
-[Dockerfile reference for the ENV instruction](../../engine/reference/builder.md#env)
+[Dockerfile reference for the ENV instruction](../../reference/dockerfile/index.md#env)
 
 To make new software easier to run, you can use `ENV` to update the
 `PATH` environment variable for the software your container installs. For
@@ -696,8 +696,8 @@ $ docker run --rm test sh -c 'echo $ADMIN_USER'
 
 ### ADD or COPY
 
-- [Dockerfile reference for the ADD instruction](../../engine/reference/builder.md#add)
-- [Dockerfile reference for the COPY instruction](../../engine/reference/builder.md#copy)
+- [Dockerfile reference for the ADD instruction](../../reference/dockerfile/index.md#add)
+- [Dockerfile reference for the COPY instruction](../../reference/dockerfile/index.md#copy)
 
 Although `ADD` and `COPY` are functionally similar, generally speaking, `COPY`
 is preferred. That’s because it’s more transparent than `ADD`. `COPY` only
@@ -748,7 +748,7 @@ auto-extraction capability, you should always use `COPY`.
 
 ### ENTRYPOINT
 
-[Dockerfile reference for the ENTRYPOINT instruction](../../engine/reference/builder.md#entrypoint)
+[Dockerfile reference for the ENTRYPOINT instruction](../../reference/dockerfile/index.md#entrypoint)
 
 The best use for `ENTRYPOINT` is to set the image's main command, allowing that
 image to be run as though it was that command (and then use `CMD` as the
@@ -805,7 +805,7 @@ exec "$@"
 > This script uses [the `exec` Bash command](https://wiki.bash-hackers.org/commands/builtin/exec)
 > so that the final running application becomes the container's PID 1. This
 > allows the application to receive any Unix signals sent to the container.
-> For more, see the [`ENTRYPOINT` reference](../../engine/reference/builder.md#entrypoint).
+> For more, see the [`ENTRYPOINT` reference](../../reference/dockerfile/index.md#entrypoint).
 
 The helper script is copied into the container and run via `ENTRYPOINT` on
 container start:
@@ -838,7 +838,7 @@ $ docker run --rm -it postgres bash
 
 ### VOLUME
 
-[Dockerfile reference for the VOLUME instruction](../../engine/reference/builder.md#volume)
+[Dockerfile reference for the VOLUME instruction](../../reference/dockerfile/index.md#volume)
 
 The `VOLUME` instruction should be used to expose any database storage area,
 configuration storage, or files/folders created by your docker container. You
@@ -847,7 +847,7 @@ parts of your image.
 
 ### USER
 
-[Dockerfile reference for the USER instruction](../../engine/reference/builder.md#user)
+[Dockerfile reference for the USER instruction](../../reference/dockerfile/index.md#user)
 
 If a service can run without privileges, use `USER` to change to a non-root
 user. Start by creating the user and group in the `Dockerfile` with something
@@ -880,7 +880,7 @@ frequently.
 
 ### WORKDIR
 
-[Dockerfile reference for the WORKDIR instruction](../../engine/reference/builder.md#workdir)
+[Dockerfile reference for the WORKDIR instruction](../../reference/dockerfile/index.md#workdir)
 
 For clarity and reliability, you should always use absolute paths for your
 `WORKDIR`. Also, you should use `WORKDIR` instead of  proliferating instructions
@@ -889,7 +889,7 @@ maintain.
 
 ### ONBUILD
 
-[Dockerfile reference for the ONBUILD instruction](../../engine/reference/builder.md#onbuild)
+[Dockerfile reference for the ONBUILD instruction](../../reference/dockerfile/index.md#onbuild)
 
 An `ONBUILD` command executes after the current `Dockerfile` build completes.
 `ONBUILD` executes in any child image derived `FROM` the current image.  Think
@@ -923,7 +923,7 @@ These Official Images have exemplary `Dockerfile`s:
 
 ## Additional resources:
 
-* [Dockerfile Reference](../../engine/reference/builder.md)
+* [Dockerfile Reference](../../reference/dockerfile/index.md)
 * [More about Base Images](baseimages.md)
 * [More about Automated Builds](../../docker-hub/builds/index.md)
 * [Guidelines for Creating Docker Official Images](../../docker-hub/official_images.md)

develop/index.md

@@ -16,7 +16,7 @@ If you're just getting started developing a brand new app on Docker, check out
 these resources to understand some of the most common patterns for getting the
 most benefits from Docker.
 
-- Learn how to [build an image](../engine/reference/builder/){: target="_blank" rel="noopener" class="_"} using a Dockerfile
+- Learn how to [build an image](../reference/dockerfile/){: target="_blank" rel="noopener" class="_"} using a Dockerfile
 - Use [multi-stage builds](develop-images/multistage-build.md){: target="_blank" rel="noopener" class="_"} to keep your images lean
 - Manage application data using [volumes](../storage/volumes.md) and [bind mounts](../storage/bind-mounts.md){: target="_blank" rel="noopener" class="_"}
 - [Scale your app with Kubernetes](../get-started/kube-deploy.md){: target="_blank" rel="noopener" class="_"}