diff --git a/docs/README.md b/docs/README.md
index de3999ba78..b3e9b32306 100755
--- a/docs/README.md
+++ b/docs/README.md
@@ -33,6 +33,11 @@ In the root of the `docker` source directory:
 If you have any issues you need to debug, you can use `make docs-shell` and then
 run `mkdocs serve`
 
+## Testing the links
+
+You can use `make docs-test` to generate a report of missing links that are referenced in
+the documentation - there should be none.
+
 ## Adding a new document
 
 New document (`.md`) files are added to the documentation builds by adding them
diff --git a/docs/sources/reference/builder.md b/docs/sources/reference/builder.md
index adc308c9d6..10689bb1f8 100644
--- a/docs/sources/reference/builder.md
+++ b/docs/sources/reference/builder.md
@@ -79,7 +79,7 @@ guide](/articles/dockerfile_best-practices/#build-cache) for more information):
     Successfully built 1a5ffc17324d
 
 When you're done with your build, you're ready to look into [*Pushing a
-repository to its registry*]( /userguide/dockerrepos/#image-push).
+repository to its registry*]( /userguide/dockerrepos/#contributing-to-docker-hub).
 
 ## Format
 
@@ -93,7 +93,7 @@ be UPPERCASE in order to distinguish them from arguments more easily.
 
 Docker runs the instructions in a `Dockerfile` in order. **The
 first instruction must be \`FROM\`** in order to specify the [*Base
-Image*](/terms/image/#base-image-def) from which you are building.
+Image*](/terms/image/#base-image) from which you are building.
 
 Docker will treat lines that *begin* with `#` as a
 comment. A `#` marker anywhere else in the line will
@@ -186,11 +186,11 @@ Or
 
     FROM <image>:<tag>
 
-The `FROM` instruction sets the [*Base Image*](/terms/image/#base-image-def)
+The `FROM` instruction sets the [*Base Image*](/terms/image/#base-image)
 for subsequent instructions. As such, a valid `Dockerfile` must have `FROM` as
 its first instruction. The image can be any valid image – it is especially easy
 to start by **pulling an image** from the [*Public Repositories*](
-/userguide/dockerrepos/#using-public-repositories).
+/userguide/dockerrepos).
 
 `FROM` must be the first non-comment instruction in the `Dockerfile`.
 
@@ -763,7 +763,7 @@ and mark it as holding externally mounted volumes from native host or other
 containers. The value can be a JSON array, `VOLUME ["/var/log/"]`, or a plain
 string with multiple arguments, such as `VOLUME /var/log` or `VOLUME /var/log
 /var/db`.  For more information/examples and mounting instructions via the
-Docker client, refer to [*Share Directories via Volumes*](/userguide/dockervolumes/#volume-def)
+Docker client, refer to [*Share Directories via Volumes*](/userguide/dockervolumes/#volume)
 documentation.
 
 > **Note**:
diff --git a/docs/sources/reference/commandline/cli.md b/docs/sources/reference/commandline/cli.md
index b7175561fc..cbf18c5ef2 100644
--- a/docs/sources/reference/commandline/cli.md
+++ b/docs/sources/reference/commandline/cli.md
@@ -459,7 +459,7 @@ Use this command to build Docker images from a Dockerfile and a
 
 The files at `PATH` or `URL` are called the "context" of the build. The
 build process may refer to any of the files in the context, for example
-when using an [*ADD*](/reference/builder/#dockerfile-add) instruction.
+when using an [*ADD*](/reference/builder/#add) instruction.
 When a single Dockerfile is given as `URL` or is piped through `STDIN`
 (`docker build - < Dockerfile`), then no context is set.
 
@@ -539,7 +539,7 @@ machine and that no parsing of the Dockerfile
 happens at the client side (where you're running
 `docker build`). That means that *all* the files at
 `PATH` get sent, not just the ones listed to
-[*ADD*](/reference/builder/#dockerfile-add) in the Dockerfile.
+[*ADD*](/reference/builder/#add) in the Dockerfile.
 
 The transfer of context from the local machine to the Docker daemon is
 what the `docker` client means when you see the
@@ -1817,7 +1817,7 @@ Search [Docker Hub](https://hub.docker.com) for images
       -s, --stars=0        Only displays with at least x stars
 
 See [*Find Public Images on Docker Hub*](
-/userguide/dockerrepos/#find-public-images-on-docker-hub) for
+/userguide/dockerrepos/#searching-for-images) for
 more details on finding shared images from the command line.
 
 ## start
@@ -1853,7 +1853,7 @@ grace period, `SIGKILL`.
 
 You can group your images together using names and tags, and then upload
 them to [*Share Images via Repositories*](
-/userguide/dockerrepos/#working-with-the-repository).
+/userguide/dockerrepos/#contributing-to-docker-hub).
 
 ## top
 
diff --git a/docs/sources/reference/run.md b/docs/sources/reference/run.md
index e9ecfff442..d13284b5d0 100644
--- a/docs/sources/reference/run.md
+++ b/docs/sources/reference/run.md
@@ -7,7 +7,7 @@ page_keywords: docker, run, configure, runtime
 **Docker runs processes in isolated containers**. When an operator
 executes `docker run`, she starts a process with its own file system,
 its own networking, and its own isolated process tree.  The
-[*Image*](/terms/image/#image-def) which starts the process may define
+[*Image*](/terms/image/#image) which starts the process may define
 defaults related to the binary to run, the networking to expose, and
 more, but `docker run` gives final control to the operator who starts
 the container from the image. That's the main reason
@@ -114,7 +114,7 @@ The UUID identifiers come from the Docker daemon, and if you do not
 assign a name to the container with `--name` then the daemon will also
 generate a random string name too. The name can become a handy way to
 add meaning to a container since you can use this name when defining
-[*links*](/userguide/dockerlinks/#working-with-links-names) (or any
+[*links*](/userguide/dockerlinks) (or any
 other place you need to identify a container). This works for both
 background and foreground Docker containers.
 
@@ -420,7 +420,7 @@ familiar with using LXC directly.
 
 ## Overriding Dockerfile image defaults
 
-When a developer builds an image from a [*Dockerfile*](/reference/builder/#dockerbuilder)
+When a developer builds an image from a [*Dockerfile*](/reference/builder)
 or when she commits it, the developer can set a number of default parameters
 that take effect when the image starts up as a container.
 
@@ -634,7 +634,7 @@ container's `/etc/hosts` entry will be automatically updated.
 
 The volumes commands are complex enough to have their own documentation
 in section [*Managing data in 
-containers*](/userguide/dockervolumes/#volume-def). A developer can define
+containers*](/userguide/dockervolumes). A developer can define
 one or more `VOLUME`'s associated with an image, but only the operator
 can give access from one container to another (or from a container to a
 volume mounted on the host).