diff --git a/Makefile b/Makefile
deleted file mode 100644
index d1b798edf8..0000000000
--- a/Makefile
+++ /dev/null
@@ -1,15 +0,0 @@
-# Currently this just contains the existing docs build cmds from docker/docker
-# Later, we will move this into an import
-DOCS_MOUNT := $(if $(DOCSDIR),-v $(CURDIR)/$(DOCSDIR):/$(DOCSDIR))
-DOCSPORT := 8000
-DOCKER_DOCS_IMAGE := docker-docs-$(VERSION)
-DOCKER_RUN_DOCS := docker run --rm -it $(DOCS_MOUNT) -e AWS_S3_BUCKET -e NOCACHE
-
-docs: docs-build
-	$(DOCKER_RUN_DOCS) -p $(DOCSPORT):8000 "$(DOCKER_DOCS_IMAGE)" mkdocs serve
-
-docs-shell: docs-build
-	$(DOCKER_RUN_DOCS) -p $(DOCSPORT):8000 "$(DOCKER_DOCS_IMAGE)" bash
-
-docs-build:
-	docker build -t "$(DOCKER_DOCS_IMAGE)" -f docs/Dockerfile .
\ No newline at end of file
diff --git a/docs/Dockerfile b/docs/Dockerfile
index 8652809660..0099ece440 100644
--- a/docs/Dockerfile
+++ b/docs/Dockerfile
@@ -1,19 +1,24 @@
-FROM docs/base:latest
-MAINTAINER Mary <mary@docker.com> (@moxiegirl)
+FROM docs/base:hugo
+MAINTAINER Mary Anthony <mary@docker.com> (@moxiegirl)
 
 # to get the git info for this repo
 COPY . /src
 
-# Reset the /docs dir so we can replace the theme meta with the new repo's git info
-# RUN git reset --hard
+COPY . /docs/content/swarm/
 
-RUN grep "VERSION =" /src/version/version.go  | sed 's/.*"\(.*\)".*/\1/' > /docs/VERSION
-
-
-COPY * /docs/sources/swarm/
-COPY scheduler/* /docs/sources/swarm/scheduler/
-COPY api/* /docs/sources/swarm/api/
-COPY mkdocs.yml /docs/mkdocs-swarm.yml
-
-# Then build everything together, ready for mkdocs
-RUN /docs/build.sh
+# Sed to process GitHub Markdown
+# 1-2 Remove comment code from metadata block
+# 3 Remove .md extension from link text
+# 4 Change ](/ to ](/project/ in links
+# 5 Change ](word) to ](/project/word)
+# 6 Change ](../../ to ](/project/
+# 7 Change ](../ to ](/project/word)
+# 
+# 
+RUN find /docs/content/swarm -type f -name "*.md" -exec sed -i.old \
+    -e '/^<!.*metadata]>/g' \
+    -e '/^<!.*end-metadata.*>/g' \
+    -e 's/\([(]\)\(.*\)\(\.md\)/\1\2/g' \
+    -e 's/\(\]\)\([(]\)\(\/\)/\1\2\/swarm\//g' \
+    -e 's/\(\][(]\)\([A-z]*[)]\)/\]\(\/swarm\/\2/g' \
+    -e 's/\(\][(]\)\(\.\.\/\)/\1\/swarm\//g' {} \;
diff --git a/docs/Makefile b/docs/Makefile
index 861a6cf341..021e8f6e5e 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -1,15 +1,55 @@
-# Currently this just contains the existing docs build cmds from docker/docker
-# Later, we will move this into an import
+.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
+
+# to allow `make DOCSDIR=docs docs-shell` (to create a bind mount in docs)
 DOCS_MOUNT := $(if $(DOCSDIR),-v $(CURDIR)/$(DOCSDIR):/$(DOCSDIR))
+
+# to allow `make DOCSPORT=9000 docs`
 DOCSPORT := 8000
-DOCKER_DOCS_IMAGE := docker-docs-$(VERSION)
+
+# Get the IP ADDRESS
+DOCKER_IP=$(shell python -c "import urlparse ; print urlparse.urlparse('$(DOCKER_HOST)').hostname or ''")
+HUGO_BASE_URL=$(shell test -z "$(DOCKER_IP)" && echo localhost || echo "$(DOCKER_IP)")
+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))
+
+
 DOCKER_RUN_DOCS := docker run --rm -it $(DOCS_MOUNT) -e AWS_S3_BUCKET -e NOCACHE
 
+# for some docs workarounds (see below in "docs-build" target)
+GITCOMMIT := $(shell git rev-parse --short HEAD 2>/dev/null)
+
+default: docs
+
 docs: docs-build
-	$(DOCKER_RUN_DOCS) -p $(DOCSPORT):8000 "$(DOCKER_DOCS_IMAGE)" mkdocs serve
+	$(DOCKER_RUN_DOCS) -p $(if $(DOCSPORT),$(DOCSPORT):)8000 -e DOCKERHOST "$(DOCKER_DOCS_IMAGE)" hugo server --port=$(DOCSPORT) --baseUrl=$(HUGO_BASE_URL) --bind=$(HUGO_BIND_IP)
+
+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 $(DOCSPORT):8000 "$(DOCKER_DOCS_IMAGE)" bash
+	$(DOCKER_RUN_DOCS) -p $(if $(DOCSPORT),$(DOCSPORT):)8000 "$(DOCKER_DOCS_IMAGE)" bash
+
 
 docs-build:
-	docker build -t "$(DOCKER_DOCS_IMAGE)" -f Dockerfile .
\ No newline at end of file
+#	( 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/api/swarm-api.md b/docs/api/swarm-api.md
index b3d2d1acd9..d4e5e5fcc8 100644
--- a/docs/api/swarm-api.md
+++ b/docs/api/swarm-api.md
@@ -1,8 +1,12 @@
----
-page_title: Docker Swarm API
-page_description: Swarm API
-page_keywords: docker, swarm, clustering, api
----
+<!--[metadata]>
++++
+title = "Docker Swarm API"
+description = "Swarm API"
+keywords = ["docker, swarm, clustering,  api"]
+[menu.main]
+parent="smn_swarm_ref"
++++
+<![end-metadata]-->
 
 # Docker Swarm API
 
diff --git a/docs/discovery.md b/docs/discovery.md
index 7f1389c705..f448a32b97 100644
--- a/docs/discovery.md
+++ b/docs/discovery.md
@@ -1,8 +1,13 @@
----
-page_title: Docker Swarm discovery
-page_description: Swarm discovery
-page_keywords: docker, swarm, clustering, discovery
----
+<!--[metadata]>
++++
+title = "Docker Swarm discovery"
+description = "Swarm discovery"
+keywords = ["docker, swarm, clustering,  discovery"]
+[menu.main]
+parent="smn_workw_swarm"
+weight=3
++++
+<![end-metadata]-->
 
 # Discovery
 
@@ -207,7 +212,7 @@ You can contribute a new discovery backend to Swarm. For information on how to d
 
 ## Docker Swarm documentation index
 
-- [User guide](./index.md)
+- [User guide](./swarm-overview.md)
 - [Sheduler strategies](./scheduler/strategy.md)
 - [Sheduler filters](./scheduler/filter.md)
 - [Swarm API](./api/swarm-api.md)
diff --git a/docs/install-manual.md b/docs/install-manual.md
index fabe7979ab..307b448d90 100644
--- a/docs/install-manual.md
+++ b/docs/install-manual.md
@@ -1,3 +1,13 @@
+<!--[metadata]>
++++
+title = "Create a swarm for development"
+description = "Swarm: a Docker-native clustering system"
+keywords = ["docker, swarm,  clustering"]
+[menu.main]
+parent="smn_workw_swarm"
+weight=2
++++
+<![end-metadata]-->
 
 # Create a swarm for development
 
diff --git a/docs/install-w-machine.md b/docs/install-w-machine.md
index 8ae540053b..1db0c5f261 100644
--- a/docs/install-w-machine.md
+++ b/docs/install-w-machine.md
@@ -1,8 +1,13 @@
----
-page_title: Get Started with Docker Swarm
-page_description: Swarm release notes
-page_keywords: docker, swarm, clustering, discovery, release, notes
----
+<!--[metadata]>
++++
+title = "Get Started with Docker Swarm"
+description = "Swarm release notes"
+keywords = ["docker, swarm, clustering, discovery, release,  notes"]
+[menu.main]
+parent="smn_workw_swarm"
+weight=1
++++
+<![end-metadata]-->
 
 # Get Started with Docker Swarm
 
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
deleted file mode 100644
index 1e1f7b1c31..0000000000
--- a/docs/mkdocs.yml
+++ /dev/null
@@ -1,9 +0,0 @@
-- ['swarm/index.md', 'User Guide', 'Docker Swarm' ]
-- ['swarm/install-w-machine.md', 'User Guide', '&nbsp;&nbsp;&nbsp;&nbsp;&blacksquare;&nbsp; Create a swarm with docker-machine' ]
-- ['swarm/install-manual.md', 'User Guide', '&nbsp;&nbsp;&nbsp;&nbsp;&blacksquare;&nbsp; Create a swarm for development' ]
-- ['swarm/release-notes.md', 'User Guide', '&nbsp;&nbsp;&nbsp;&nbsp;&blacksquare;&nbsp; Release Notes']
-- ['swarm/discovery.md', 'Reference', 'Swarm discovery']
-- ['swarm/api/swarm-api.md', 'Reference', 'Swarm API']
-- ['swarm/scheduler/filter.md', 'Reference', 'Swarm filters']
-- ['swarm/scheduler/strategy.md', 'Reference', 'Swarm strategies']
-
diff --git a/docs/release-notes.md b/docs/release-notes.md
index 1e4e20a2a2..a7377d553f 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -1,10 +1,15 @@
----
-page_title: Docker Swarm Release Notes
-page_description: Swarm release notes
-page_keywords: docker, swarm, clustering, discovery, release, notes
----
+<!--[metadata]>
++++
+title = "Docker Swarm"
+description = "Docker Swarm release notes"
+keywords = ["docker, swarm, clustering, discovery, release,  notes"]
+[menu.main]
+parent = "smn_release_notes"	
+weight = 5
++++
+<![end-metadata]-->
 
-# Docker Swarm Release Notes 
+# Docker Swarm
 
 This page shows the cumulative release notes across all releases of Docker Swarm.
 
diff --git a/docs/scheduler/filter.md b/docs/scheduler/filter.md
index 7dde792602..b255bd489c 100644
--- a/docs/scheduler/filter.md
+++ b/docs/scheduler/filter.md
@@ -1,8 +1,13 @@
----
-page_title: Docker Swarm filters
-page_description: Swarm filters
-page_keywords: docker, swarm, clustering, filters
----
+<!--[metadata]>
++++
+title = "Docker Swarm filters"
+description = "Swarm filters"
+keywords = ["docker, swarm, clustering,  filters"]
+[menu.main]
+parent="smn_workw_swarm"
+weight=4
++++
+<![end-metadata]-->
 
 # Filters
 
diff --git a/docs/scheduler/strategy.md b/docs/scheduler/strategy.md
index 6533a4cca0..b9dd2be981 100644
--- a/docs/scheduler/strategy.md
+++ b/docs/scheduler/strategy.md
@@ -1,8 +1,13 @@
----
-page_title: Docker Swarm strategies
-page_description: Swarm strategies
-page_keywords: docker, swarm, clustering, strategies
----
+<!--[metadata]>
++++
+title = "Docker Swarm strategies"
+description = "Swarm strategies"
+keywords = ["docker, swarm, clustering,  strategies"]
+[menu.main]
+parent="smn_workw_swarm"
+weight=5
++++
+<![end-metadata]-->
 
 # Strategies
 
diff --git a/docs/index.md b/docs/swarm-overview.md
similarity index 94%
rename from docs/index.md
rename to docs/swarm-overview.md
index 5eaa55af41..bc75656274 100644
--- a/docs/index.md
+++ b/docs/swarm-overview.md
@@ -1,8 +1,12 @@
----
-page_title: Docker Swarm
-page_description: Swarm: a Docker-native clustering system
-page_keywords: docker, swarm, clustering
----
+<!--[metadata]>
++++
+title = "Docker Swarm"
+description = "Swarm: a Docker-native clustering system"
+keywords = ["docker, swarm,  clustering"]
+[menu.main]
+parent="smn_workw_swarm"
++++
+<![end-metadata]-->
 
 # Docker Swarm