diff --git a/docs/Dockerfile b/docs/Dockerfile
index 9efa262832..468df9d6e6 100644
--- a/docs/Dockerfile
+++ b/docs/Dockerfile
@@ -1,8 +1,8 @@
 FROM docs/base:oss
-MAINTAINER Mary Anthony <mary@docker.com> (@moxiegirl)
+MAINTAINER Docker Docs <docs@docker.com>
 
 ENV PROJECT=swarm
 # 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 d837a12fec..2b085b9b78 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -1,18 +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=1 docs-shell` (to create a bind mount in docs)
 DOCS_MOUNT := $(if $(DOCSDIR),-v $(CURDIR):/docs/content/swarm/)
 
@@ -25,9 +11,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 +27,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) -p $(if $(DOCSPORT),$(DOCSPORT):)8000 "$(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/install-manual.md b/docs/install-manual.md
index b9814a9995..589ac1d5dc 100644
--- a/docs/install-manual.md
+++ b/docs/install-manual.md
@@ -26,7 +26,7 @@ you can deploy an equivalent Docker Swarm cluster on many other platforms. In th
 - [Test the high-availability Swarm managers](#step-7-test-swarm-failover)
 - [Additional Resources](#additional-resources)
 
-For a gentler introduction to Swarm, try the [Evaluate Swarm in a sandbox](install-w-machine) page.
+For a gentler introduction to Swarm, try the [Evaluate Swarm in a sandbox](install-w-machine.md) page.
 
 ## Prerequisites
 
diff --git a/docs/swarm_at_scale/deploy-app.md b/docs/swarm_at_scale/deploy-app.md
index f9b2d720c8..61882742e1 100644
--- a/docs/swarm_at_scale/deploy-app.md
+++ b/docs/swarm_at_scale/deploy-app.md
@@ -276,9 +276,9 @@ the containers at once. This extra credit
 
 2. Try to create Compose file on your own by reviewing the tasks in this tutorial.
 
-    <a href="http://192.168.99.100:8000/compose/compose-file/#entrypoint" target="_blank">The
-    version 2 Compose file format</a> is the best to use. Translate each `docker
-    run` command into a service in the `docker-compose.yml` file. For example,
+    [The version 2 Compose file format](/compose/compose-file.md)
+    is the best to use. Translate each `docker run` command into a service
+    in the `docker-compose.yml` file. For example,
     this command:
 
     ```bash