diff --git a/Makefile b/Makefile
index 32cd23aa..a1daeaf6 100644
--- a/Makefile
+++ b/Makefile
@@ -64,18 +64,3 @@ clean:
 	@rm -rf "${PREFIX}/bin/registry" "${PREFIX}/bin/registry-api-descriptor-template"
 
 	
-# Use 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 .
diff --git a/docs/Dockerfile b/docs/Dockerfile
index d4e60012..9f3cfa5e 100644
--- a/docs/Dockerfile
+++ b/docs/Dockerfile
@@ -1,37 +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
+# 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/distribution/
 
-RUN grep "VERSION =" /src/version/version.go  | sed 's/.*"\(.*\)".*/\1/' > /docs/VERSION
-
-
-#
-# RUN git describe --match 'v[0-9]*' --dirty='.m' --always > /docs/VERSION
-# The above line causes a floating point error in our tools
-#
-COPY docs/* /docs/sources/registry/
-COPY docs/images/* /docs/sources/registry/images/
-COPY docs/spec/* /docs/sources/registry/spec/
-COPY docs/spec/auth/* /docs/sources/registry/spec/auth/
-COPY docs/storage-drivers/* /docs/sources/registry/storage-drivers/
-COPY docs/mkdocs.yml /docs/mkdocs-distribution.yml
-
-RUN sed -i.old '1s;^;no_version_dropdown: true;' \
-  /docs/sources/registry/*.md \
-  /docs/sources/registry/spec/*.md \
-  /docs/sources/registry/spec/auth/*.md \
-  /docs/sources/registry/storage-drivers/*.md 
-
-RUN sed -i.old  -e '/^<!--GITHUB/g' -e '/^IGNORES-->/g'\
-  /docs/sources/registry/*.md \
-  /docs/sources/registry/spec/*.md \
-  /docs/sources/registry/spec/auth/*.md \
-  /docs/sources/registry/storage-drivers/*.md 
-
-# 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/distribution -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\/distribution\//g' \
+    -e 's/\(\][(]\)\([A-z]*[)]\)/\]\(\/distribution\/\2/g' \
+    -e 's/\(\][(]\)\(\.\.\/\)/\1\/distribution\//g' {} \;
\ No newline at end of file
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 00000000..021e8f6e
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,55 @@
+.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
+
+# 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 $(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 $(if $(DOCSPORT),$(DOCSPORT):)8000 "$(DOCKER_DOCS_IMAGE)" bash
+
+
+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/architecture.md b/docs/architecture.md
index 09dce42f..558a1199 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1,3 +1,9 @@
+<!--[metadata]>
++++
+draft = "true"
++++
+<![end-metadata]-->
+
 # Architecture
 
 ## Design
diff --git a/docs/building.md b/docs/building.md
index 9d4960bd..cd7b082a 100644
--- a/docs/building.md
+++ b/docs/building.md
@@ -1,3 +1,9 @@
+<!--[metadata]>
++++
+draft = "true"
++++
+<![end-metadata]-->
+
 # Build the development environment
 
 The first prequisite of properly building distribution targets is to have a Go
diff --git a/docs/configuration.md b/docs/configuration.md
index 6c423d60..ec342ac1 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1,8 +1,14 @@
-<!--GITHUB
-page_title: Configure a Registry
-page_description: Explains how to configure a registry
-page_keywords: registry, service, images, repository, configuration
-IGNORES-->
+<!--[metadata]>
++++
+title = "Configure a Registry"
+description = "Explains how to deploy a registry"
+keywords = ["registry, service, images,  repository"]
+[menu.main]
+parent="smn_registry"
+weight=2
++++
+<![end-metadata]-->
+
 
 
 # Registry Configuration Reference
diff --git a/docs/deploying.md b/docs/deploying.md
index 9f9950b8..226f3307 100644
--- a/docs/deploying.md
+++ b/docs/deploying.md
@@ -1,8 +1,14 @@
-<!--GITHUB
-page_title: Deploying a registry server
-page_description: Explains how to deploy a registry server
-page_keywords: registry, service, images, repository, deploy
-IGNORES-->
+<!--[metadata]>
++++
+title = "Deploying a registry server"
+description = "Explains how to deploy a registry server"
+keywords = ["registry, service, images,  repository"]
+[menu.main]
+parent="smn_registry"
+weight=1
++++
+<![end-metadata]-->
+
 
 # Deploying a registry server
 
diff --git a/docs/distribution.md b/docs/distribution.md
deleted file mode 100644
index bad7362f..00000000
--- a/docs/distribution.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# Project
-
-## Contents
-- [Docker Registry 2.0](index.md)
-- [Architecture](architecture.md)
-- [Build the development environment](building.md)
-- [Configure a registry](configuration.md)
-- [Deploying a registry server](deploying.md)
-- [Microsoft Azure storage driver](storage-drivers/azure.md)
-- [Filesystem storage driver](storage-drivers/filesystem.md)
-- [In-memory storage driver](storage-drivers/inmemory.md)
-- [S3 storage driver](storage-drivers/s3.md)
-- [Notifications](notifications.md)
-- [Docker Registry HTTP API V2](spec/api.md)
-- [Docker Registry v2 authentication via central service](spec/auth/token.md)
-- [Docker Distribution JSON Canonicalization](spec/json.md)
-- [Docker-Registry Storage Driver](storagedrivers.md)
diff --git a/docs/glossary.md b/docs/glossary.md
index 6f07a190..fbe502cc 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -1,8 +1,8 @@
-<!--GITHUB
-page_title: Distribution glossary
-page_description: Provides definition for distribution terms
-page_keywords: registry, service, images, repository, distribution, glossary, layer, blob
-IGNORES-->
+<!--[metadata]>
++++
+draft = "true"
++++
+<![end-metadata]-->
 
 # Glossary
 
diff --git a/docs/migration.md b/docs/migration.md
index be3f02bb..5dbd766f 100644
--- a/docs/migration.md
+++ b/docs/migration.md
@@ -1,3 +1,9 @@
+<!--[metadata]>
++++
+draft = "true"
++++
+<![end-metadata]-->
+
 # Migrating a 1.0 registry to 2.0
 
 TODO: This needs to be revised in light of Olivier's work
diff --git a/docs/notifications.md b/docs/notifications.md
index fb5897fc..233b35c7 100644
--- a/docs/notifications.md
+++ b/docs/notifications.md
@@ -1,8 +1,14 @@
-<!--GITHUB
-page_title: Work with Notifications
-page_description: Explains how to deploy a registry server
-page_keywords: registry, service, images, repository
-IGNORES-->
+<!--[metadata]>
++++
+title = "Work with Notifications"
+description = "Explains work with registry notifications"
+keywords = ["registry, service, images, notifications,  repository"]
+[menu.main]
+parent="smn_registry"
+weight=1
++++
+<![end-metadata]-->
+
 
 
 # Notifications
diff --git a/docs/osx-setup-guide.md b/docs/osx-setup-guide.md
index cd9a2429..c924d457 100644
--- a/docs/osx-setup-guide.md
+++ b/docs/osx-setup-guide.md
@@ -1,3 +1,9 @@
+<!--[metadata]>
++++
+draft = "true"
++++
+<![end-metadata]-->
+
 # OS X Setup Guide
 
 This guide will walk you through running the new Go based [Docker registry](https://github.com/docker/distribution) on your local OS X machine.
diff --git a/docs/index.md b/docs/overview.md
similarity index 91%
rename from docs/index.md
rename to docs/overview.md
index 2a7f08f2..df9ec95b 100644
--- a/docs/index.md
+++ b/docs/overview.md
@@ -1,8 +1,13 @@
-<!--GITHUB
-page_title: Docker Registry 2.0
-page_description: Introduces the Docker Registry
-page_keywords: registry, images, repository
-IGNORES-->
+<!--[metadata]>
++++
+title = "Docker Registry 2.0"
+description = "Introduces the Docker Registry"
+keywords = ["registry, images,  repository"]
+[menu.main]
+parent="smn_registry"
++++
+<![end-metadata]-->
+
 
 # Docker Registry
 
diff --git a/docs/spec/api.md b/docs/spec/api.md
index 6e050ef2..56eef796 100644
--- a/docs/spec/api.md
+++ b/docs/spec/api.md
@@ -1,8 +1,14 @@
-<!--GITHUB
-page_title: Docker Registry HTTP API V2
-page_description: Explains how to use registry API
-page_keywords: registry, service, driver, images, storage, api
-IGNORES-->
+<!--[metadata]>
++++
+draft = true
+title = "Docker Registry HTTP API V2"
+description = "This is a specification for the API."
+keywords = ["registry, service, driver, images, storage,  api"]
+[menu.main]
+parent="smn_registry_ref"
++++
+<![end-metadata]-->
+
 
 # Docker Registry HTTP API V2
 
diff --git a/docs/spec/api.md.tmpl b/docs/spec/api.md.tmpl
index b808a2ad..20bd2e85 100644
--- a/docs/spec/api.md.tmpl
+++ b/docs/spec/api.md.tmpl
@@ -1,8 +1,13 @@
-<!--GITHUB
-page_title: Docker Registry HTTP API V2
-page_description: Explains how to use registry API
-page_keywords: registry, service, driver, images, storage, api
-IGNORES-->
+<!--[metadata]>
++++
+draft = true
+title = "Docker Registry HTTP API V2"
+description = "This is a specification for the API."
+keywords = ["registry, service, driver, images, storage,  api"]
+[menu.main]
+parent="smn_registry_ref"
++++
+<![end-metadata]-->
 
 # Docker Registry HTTP API V2
 
diff --git a/docs/spec/auth/token.md b/docs/spec/auth/token.md
index 5a394cbe..907eb413 100644
--- a/docs/spec/auth/token.md
+++ b/docs/spec/auth/token.md
@@ -1,8 +1,13 @@
-<!--GITHUB
-page_title: Docker Registry v2 Authentication
-page_description: Introduces the Docker Registry v2 authentication
-page_keywords: registry, images, repository, v2, authentication
-IGNORES-->
+<!--[metadata]>
++++
+title = "Docker Registry v2 Authentication"
+description = "Introduces the Docker Registry v2 authentication"
+keywords = ["registry, images, repository, v2,  authentication"]
+[menu.main]
+parent="smn_registry_ref"
++++
+<![end-metadata]-->
+
 
 
 # Docker Registry v2 authentication via central service
diff --git a/docs/spec/json.md b/docs/spec/json.md
index 34440c71..2f49bae1 100644
--- a/docs/spec/json.md
+++ b/docs/spec/json.md
@@ -1,8 +1,13 @@
-<!--GITHUB
-page_title: Docker Distribution JSON Canonicalization
-page_description: Explains registry JSON objects
-page_keywords: registry, service, images, repository, json
-IGNORES-->
+<!--[metadata]>
++++
+title = "Docker Distribution JSON Canonicalization"
+description = "Explains registry JSON objects"
+keywords = ["registry, service, images, repository,  json"]
+[menu.main]
+parent="smn_registry_ref"
++++
+<![end-metadata]-->
+
 
 
 # Docker Distribution JSON Canonicalization
diff --git a/docs/storage-drivers/azure.md b/docs/storage-drivers/azure.md
index 01cba5c3..9d1db12e 100644
--- a/docs/storage-drivers/azure.md
+++ b/docs/storage-drivers/azure.md
@@ -1,8 +1,13 @@
-<!--GITHUB
-page_title: Microsoft Azure storage driver
-page_description: Explains how to use the Azure storage drivers
-page_keywords: registry, service, driver, images, storage, azure
-IGNORES-->
+<!--[metadata]>
++++
+title = "Microsoft Azure storage driver"
+description = "Explains how to use the Azure storage drivers"
+keywords = ["registry, service, driver, images, storage,  azure"]
+[menu.main]
+parent="smn_registry_drivers"
++++
+<![end-metadata]-->
+
 
 # Microsoft Azure storage driver
 
diff --git a/docs/storage-drivers/filesystem.md b/docs/storage-drivers/filesystem.md
index 23d4afba..50030d30 100644
--- a/docs/storage-drivers/filesystem.md
+++ b/docs/storage-drivers/filesystem.md
@@ -1,8 +1,13 @@
-<!--GITHUB
-page_title: Filesystem storage driver
-page_description: Explains how to use the filesystem storage drivers
-page_keywords: registry, service, driver, images, storage, filesystem
-IGNORES-->
+<!--[metadata]>
++++
+title = "Filesystem storage driver"
+description = "Explains how to use the filesystem storage drivers"
+keywords = ["registry, service, driver, images, storage,  filesystem"]
+[menu.main]
+parent="smn_registry_drivers"
++++
+<![end-metadata]-->
+
 
 # Filesystem storage driver
 
diff --git a/docs/storage-drivers/inmemory.md b/docs/storage-drivers/inmemory.md
index 948cd5bc..7256b941 100644
--- a/docs/storage-drivers/inmemory.md
+++ b/docs/storage-drivers/inmemory.md
@@ -1,8 +1,13 @@
-<!--GITHUB
-page_title: In-memory storage driver
-page_description: Explains how to use the in-memory storage drivers
-page_keywords: registry, service, driver, images, storage, in-memory
-IGNORES-->
+<!--[metadata]>
++++
+title = "In-memory storage driver"
+description = "Explains how to use the in-memory storage drivers"
+keywords = ["registry, service, driver, images, storage,  in-memory"]
+[menu.main]
+parent="smn_registry_drivers"
++++
+<![end-metadata]-->
+
 
 # In-memory storage driver
 
diff --git a/docs/storage-drivers/rados.md b/docs/storage-drivers/rados.md
index 41f51c33..83cdea26 100644
--- a/docs/storage-drivers/rados.md
+++ b/docs/storage-drivers/rados.md
@@ -1,8 +1,13 @@
-<!--GITHUB
-page_title: Ceph RADOS storage driver
-page_description: Explains how to use the Ceph RADOS storage driver
-page_keywords: registry, service, driver, images, storage, ceph, rados
-IGNORES-->
+<!--[metadata]>
++++
+title = "Ceph RADOS storage driver"
+description = "Explains how to use the Ceph RADOS storage driver"
+keywords = ["registry, service, driver, images, storage, ceph,  rados"]
+[menu.main]
+parent="smn_registry_drivers"
++++
+<![end-metadata]-->
+
 
 # Ceph RADOS storage driver
 
diff --git a/docs/storage-drivers/s3.md b/docs/storage-drivers/s3.md
index e6c11348..4393bd76 100644
--- a/docs/storage-drivers/s3.md
+++ b/docs/storage-drivers/s3.md
@@ -1,8 +1,13 @@
-<!--GITHUB
-page_title: S3 storage driver
-page_description: Explains how to use the S3 storage drivers
-page_keywords: registry, service, driver, images, storage, S3
-IGNORES-->
+<!--[metadata]>
++++
+title = "S3 storage driver"
+description = "Explains how to use the S3 storage drivers"
+keywords = ["registry, service, driver, images, storage,  S3"]
+[menu.main]
+parent="smn_registry_drivers"
++++
+<![end-metadata]-->
+
 
 # S3 storage driver
 
diff --git a/docs/storagedrivers.md b/docs/storagedrivers.md
index f0bba664..b7445f42 100644
--- a/docs/storagedrivers.md
+++ b/docs/storagedrivers.md
@@ -1,8 +1,14 @@
-<!--GITHUB
-page_title: Docker Registry Storage Driver
-page_description: Explains how to use the storage drivers
-page_keywords: registry, service, driver, images, storage
-IGNORES-->
+<!--[metadata]>
++++
+title = "Docker Registry Storage Driver"
+description = "Explains how to use the storage drivers"
+keywords = ["registry, service, driver, images,  storage"]
+[menu.main]
+parent="smn_registry_ref"
+identifier="smn_registry_drivers"
++++
+<![end-metadata]-->
+
 
 # Docker Registry Storage Driver