diff --git a/docs/Makefile b/docs/Makefile
index 08c6179..7468139 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -1,28 +1,52 @@
-DOCSDIR := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))
+# Makefile for building CORD docs site, guide.opencord.org
+# Building docs requires the following tools:
+#  - Gitbook toolchain: https://toolchain.gitbook.com/setup.html
+#  - NPM (for Gitbook and Swagger)
+#  - Python (for build glossary script)
+#  - linkchecker (for test target) http://wummel.github.io/linkchecker/
 
-swagger: swagger_clean swagger_docs swagger_serve_spec
+default: serve
 
-venv-xosdocs:
-	./venv-xosdocs.sh
+# use bash for pushd/popd, and to fail if commands within  a pipe fail
+SHELL = bash -o pipefail
 
-swagger_docs: venv-xosdocs
-	bash -c 'source $(DOCSDIR)venv-xosdocs/bin/activate && python $(DOCSDIR)scripts/swagger_docs.py'
+GENERATED_DOCS = 
 
-clean: swagger_clean venv_clean
+LINT_STYLE ?= mdl_relaxed.rb
 
-swagger_clean:
-	rm -rf swagger/specs/*
+serve: setup
+	gitbook serve
 
-venv_clean:
-	rm -rf $(DOCSDIR)venv-xosdocs
+build: setup
+	gitbook build
 
-swagger_serve_spec:
-	http-server --cors ./swagger
+setup: xos-gui xos-tosca
+	gitbook init
+	gitbook install
 
-# HOW TO
-# - load the virtual env (https://guide.opencord.org/xos/dev/local_env.html)
-# - run `make`
-# - open the browser at `http://127.0.0.1:8080/ui`
-# - you'll see the 'core' apis
-# - you can see a list of available apis at `http://127.0.0.1:8080/specs/`
-# - just replace the swagger file (top bar) with another one to see different APIs (to be improved)
+test: linkcheck lint
+
+linkcheck: build
+	linkchecker -a _book/
+
+lint:
+	@echo "markdownlint(mdl) version: `mdl --version`"
+	@echo "style config:"
+	@echo "---"
+	@cat $(LINT_STYLE)
+	@echo "---"
+	mdl -s $(LINT_STYLE) `find -L . ! -path "./_book/*" ! -path "./node_modules/*" -name "*.md"`
+
+# link directories that contain other documentation
+xos-gui:
+	ln -s ../../xos-gui/docs xos-gui
+
+xos-tosca:
+	ln -s ../../xos-tosca/docs xos-tosca
+
+
+clean:
+	rm -rf $(GENERATED_DOCS)
+	rm -rf _book
+	rm -rf node_modules
+	rm -rf xos xos-gui xos-tosca