diff --git a/docs/Dockerfile b/docs/Dockerfile
index e2ad863905..3884418de9 100644
--- a/docs/Dockerfile
+++ b/docs/Dockerfile
@@ -1,9 +1,9 @@
 FROM docs/base:oss
-MAINTAINER Mary Anthony <mary@docker.com> (@moxiegirl)
+MAINTAINER Docker Docs <docs@docker.com>
 
 env PROJECT=machine
 
 # To get the git info for this repo
 COPY . /src
-RUN rm -r /docs/content/$PROJECT/
+RUN rm -rf /docs/content/$PROJECT/
 COPY . /docs/content/$PROJECT/
diff --git a/docs/Makefile b/docs/Makefile
index 021e8f6e5e..5a83bf6b37 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -1,17 +1,4 @@
-.PHONY: all binary build cross default docs docs-build docs-shell shell test test-unit test-integration test-integration-cli test-docker-py validate
-
-# env vars passed through directly to Docker's build scripts
-# to allow things like `make DOCKER_CLIENTONLY=1 binary` easily
-# `docs/sources/contributing/devenvironment.md ` and `project/PACKAGERS.md` have some limited documentation of some of these
-DOCKER_ENVS := \
-	-e BUILDFLAGS \
-	-e DOCKER_CLIENTONLY \
-	-e DOCKER_EXECDRIVER \
-	-e DOCKER_GRAPHDRIVER \
-	-e TESTDIRS \
-	-e TESTFLAGS \
-	-e TIMEOUT
-# note: we _cannot_ add "-e DOCKER_BUILDTAGS" here because even if it's unset in the shell, that would shadow the "ENV DOCKER_BUILDTAGS" set in our Dockerfile, which is very important for our official builds
+.PHONY: all default docs docs-build docs-shell shell test
 
 # to allow `make DOCSDIR=docs docs-shell` (to create a bind mount in docs)
 DOCS_MOUNT := $(if $(DOCSDIR),-v $(CURDIR)/$(DOCSDIR):/$(DOCSDIR))
@@ -25,9 +12,8 @@ HUGO_BASE_URL=$(shell test -z "$(DOCKER_IP)" && echo localhost || echo "$(DOCKER
 HUGO_BIND_IP=0.0.0.0
 
 GIT_BRANCH := $(shell git rev-parse --abbrev-ref HEAD 2>/dev/null)
-DOCKER_IMAGE := docker$(if $(GIT_BRANCH),:$(GIT_BRANCH))
-DOCKER_DOCS_IMAGE := docs-base$(if $(GIT_BRANCH),:$(GIT_BRANCH))
-
+GIT_BRANCH_CLEAN := $(shell echo $(GIT_BRANCH) | sed -e "s/[^[:alnum:]]/-/g")
+DOCKER_DOCS_IMAGE := docker-docs$(if $(GIT_BRANCH_CLEAN),:$(GIT_BRANCH_CLEAN))
 
 DOCKER_RUN_DOCS := docker run --rm -it $(DOCS_MOUNT) -e AWS_S3_BUCKET -e NOCACHE
 
@@ -42,14 +28,11 @@ docs: docs-build
 docs-draft: docs-build
 	$(DOCKER_RUN_DOCS) -p $(if $(DOCSPORT),$(DOCSPORT):)8000 -e DOCKERHOST "$(DOCKER_DOCS_IMAGE)" hugo server --buildDrafts="true" --port=$(DOCSPORT) --baseUrl=$(HUGO_BASE_URL) --bind=$(HUGO_BIND_IP)
 
-
 docs-shell: docs-build
 	$(DOCKER_RUN_DOCS) -p $(if $(DOCSPORT),$(DOCSPORT):)8000 "$(DOCKER_DOCS_IMAGE)" bash
 
+test: docs-build
+	$(DOCKER_RUN_DOCS) "$(DOCKER_DOCS_IMAGE)"
 
 docs-build:
-#	( git remote | grep -v upstream ) || git diff --name-status upstream/release..upstream/docs ./ > ./changed-files
-#	echo "$(GIT_BRANCH)" > GIT_BRANCH
-#	echo "$(AWS_S3_BUCKET)" > AWS_S3_BUCKET
-#	echo "$(GITCOMMIT)" > GITCOMMIT
 	docker build -t "$(DOCKER_DOCS_IMAGE)" .
diff --git a/docs/concepts.md b/docs/concepts.md
index b6c7457da7..3f290665f2 100644
--- a/docs/concepts.md
+++ b/docs/concepts.md
@@ -78,7 +78,7 @@ like-minded individuals, we have a number of open channels for communication.
     Github](https://github.com/docker/machine/pulls).
 
 For more information and resources, please visit
-[our help page](https://docs.docker.com/project/get-help/).
+[our help page](/opensource/get-help.md).
 
 ## Where to go next
 
diff --git a/docs/examples/aws.md b/docs/examples/aws.md
index b1efb627da..fc3e2215a1 100644
--- a/docs/examples/aws.md
+++ b/docs/examples/aws.md
@@ -129,4 +129,4 @@ To remove an instance and all of its containers and images, first stop the machi
 -   [Understand Machine concepts](../concepts.md)
 -   [Docker Machine driver reference](../drivers/index.md)
 -   [Docker Machine subcommand reference](../reference/index.md)
--   [Provision a Docker Swarm cluster with Docker Machine](https://docs.docker.com/swarm/provision-with-machine/)
+-   [Provision a Docker Swarm cluster with Docker Machine](/swarm/provision-with-machine.md)
diff --git a/docs/examples/ocean.md b/docs/examples/ocean.md
index 8881d3e4b1..23e036062d 100644
--- a/docs/examples/ocean.md
+++ b/docs/examples/ocean.md
@@ -140,4 +140,4 @@ If you create a host with Docker Machine, but remove it through the cloud provid
 -   [Understand Machine concepts](../concepts.md)
 -   [Docker Machine driver reference](../drivers/index.md)
 -   [Docker Machine subcommand reference](../reference/index.md)
--   [Provision a Docker Swarm cluster with Docker Machine](https://docs.docker.com/swarm/provision-with-machine/)
+-   [Provision a Docker Swarm cluster with Docker Machine](/swarm/provision-with-machine.md)
diff --git a/docs/get-started-cloud.md b/docs/get-started-cloud.md
index 936641c0fc..f84e8d1f84 100644
--- a/docs/get-started-cloud.md
+++ b/docs/get-started-cloud.md
@@ -84,4 +84,4 @@ Docker Machine can also provision <a href="https://docs.docker.com/swarm/overvie
 -   [Understand Machine concepts](concepts.md)
 -   [Docker Machine driver reference](drivers/index.md)
 -   [Docker Machine subcommand reference](reference/index.md)
--   [Provision a Docker Swarm cluster with Docker Machine](https://docs.docker.com/swarm/provision-with-machine/)
+-   [Provision a Docker Swarm cluster with Docker Machine](/swarm/provision-with-machine.md)
diff --git a/docs/overview.md b/docs/overview.md
index cfa19ebb59..470394f962 100644
--- a/docs/overview.md
+++ b/docs/overview.md
@@ -60,7 +60,7 @@ When people say "Docker" they typically mean **Docker Engine**, the client-serve
 -   [Install Docker Machine](install-machine.md)
 -   Create and run a Docker host on your [local system using VirtualBox](get-started.md)
 -   Provision multiple Docker hosts [on your cloud provider](get-started-cloud.md)
--   [Provision a Docker Swarm cluster with Docker Machine](https://docs.docker.com/swarm/provision-with-machine/)
+-   [Provision a Docker Swarm cluster with Docker Machine](/swarm/provision-with-machine.md)
 -   [Understand Machine concepts](concepts.md)
 -   [Docker Machine driver reference](drivers/index.md)
 -   [Docker Machine subcommand reference](reference/index.md)
diff --git a/docs/reference/create.md b/docs/reference/create.md
index a9892b1b0f..a9db9ed976 100644
--- a/docs/reference/create.md
+++ b/docs/reference/create.md
@@ -119,12 +119,12 @@ As part of the process of creation, Docker Machine installs Docker and
 configures it with some sensible defaults. For instance, it allows connection
 from the outside world over TCP with TLS-based encryption and defaults to AUFS
 as the [storage
-driver](https://docs.docker.com/reference/commandline/daemon/#daemon-storage-driver-option)
+driver](/engine/reference/commandline/dockerd.md#daemon-storage-driver-option)
 when available.
 
 There are several cases where the user might want to set options for the created
 Docker engine (also known as the Docker _daemon_) themselves. For example, they
-may want to allow connection to a [registry](https://docs.docker.com/registry/)
+may want to allow connection to a [registry](/registry/index.md)
 that they are running themselves using the `--insecure-registry` flag for the
 daemon. Docker Machine supports the configuration of such options for the
 created engines via the `create` command flags which begin with `--engine`.
@@ -165,10 +165,10 @@ output of `docker info`:
 
 The supported flags are as follows:
 
--   `--engine-insecure-registry`: Specify [insecure registries](https://docs.docker.com/reference/commandline/cli/#insecure-registries) to allow with the created engine
--   `--engine-registry-mirror`: Specify [registry mirrors](https://github.com/docker/distribution/blob/master/docs/mirror.md) to use
--   `--engine-label`: Specify [labels](https://docs.docker.com/userguide/labels-custom-metadata/#daemon-labels) for the created engine
--   `--engine-storage-driver`: Specify a [storage driver](https://docs.docker.com/reference/commandline/cli/#daemon-storage-driver-option) to use with the engine
+-   `--engine-insecure-registry`: Specify [insecure registries](/engine/reference/commandline/cli.md#insecure-registries) to allow with the created engine
+-   `--engine-registry-mirror`: Specify [registry mirrors](/registry/recipes/mirror.md) to use
+-   `--engine-label`: Specify [labels](/engine/userguide/labels-custom-metadata.md#daemon-labels) for the created engine
+-   `--engine-storage-driver`: Specify a [storage driver](/engine/reference/commandline/cli.md#daemon-storage-driver-option) to use with the engine
 
 If the engine supports specifying the flag multiple times (such as with
 `--label`), then so does Docker Machine.
@@ -178,7 +178,7 @@ Machine also supports an additional flag, `--engine-opt`, which can be used to
 specify arbitrary daemon options with the syntax `--engine-opt flagname=value`.
 For example, to specify that the daemon should use `8.8.8.8` as the DNS server
 for all containers, and always use the `syslog` [log
-driver](https://docs.docker.com/reference/run/#logging-drivers-log-driver) you
+driver](/engine/reference/run.md#logging-drivers-log-driver) you
 could run the following create command:
 
     $ docker-machine create -d virtualbox \
@@ -200,7 +200,7 @@ specify arbitrary environment variables to be set within the engine with the syn
 In addition to being able to configure Docker Engine options as listed above,
 you can use Machine to specify how the created Swarm master should be
 configured. There is a `--swarm-strategy` flag, which you can use to specify
-the [scheduling strategy](https://docs.docker.com/swarm/scheduler/strategy/)
+the [scheduling strategy](/swarm/scheduler/strategy.md)
 which Docker Swarm should use (Machine defaults to the `spread` strategy).
 There is also a general purpose `--swarm-opt` option which works similar to how
 the aforementioned `--engine-opt` option does, except that it specifies options
diff --git a/docs/reference/env.md b/docs/reference/env.md
index 5adc2d6add..5f793d64f5 100644
--- a/docs/reference/env.md
+++ b/docs/reference/env.md
@@ -106,4 +106,4 @@ required for internet access.
 
 You may also want to visit the [documentation on setting `HTTP_PROXY` for the
 created daemon using the `--engine-env` flag for `docker-machine
-create`](https://docs.docker.com/machine/reference/create/#specifying-configuration-options-for-the-created-docker-engine).
+create`](/machine/reference/create.md#specifying-configuration-options-for-the-created-docker-engine).