diff --git a/Makefile b/Makefile
index 104a489ae16..a2779bcb3a6 100644
--- a/Makefile
+++ b/Makefile
@@ -5,7 +5,7 @@ FMT = $(ROOT)/make/erlang-formatter-master/fmt.sh
 
 KAZOODIRS = core/Makefile applications/Makefile
 
-.PHONY: $(KAZOODIRS) deps core apps xref xref_release dialyze dialyze-it dialyze-apps dialyze-core dialyze-kazoo clean clean-test clean-release build-release build-ci-release tar-release release read-release-cookie elvis install ci diff fmt bump-copyright apis validate-swagger coverage-report fs-headers
+.PHONY: $(KAZOODIRS) deps core apps xref xref_release dialyze dialyze-it dialyze-apps dialyze-core dialyze-kazoo clean clean-test clean-release build-release build-ci-release tar-release release read-release-cookie elvis install ci diff fmt bump-copyright apis validate-swagger coverage-report fs-headers docs
 
 all: compile rel/dev-vm.args
 
@@ -193,6 +193,9 @@ apis:
 	@$(ROOT)/scripts/format-json.sh applications/crossbar/priv/api/*.json
 	@ERL_LIBS=deps/:core/:applications/ $(ROOT)/scripts/generate-fs-headers-hrl.escript
 
+docs:
+	$(ROOT)/scripts/validate_mkdocs.py
+
 fs-headers:
 	@ERL_LIBS=deps/:core/:applications/ $(ROOT)/scripts/generate-fs-headers-hrl.escript
 
diff --git a/circle.yml b/circle.yml
index 9a3a41dfd6b..63c98561349 100644
--- a/circle.yml
+++ b/circle.yml
@@ -19,6 +19,8 @@ dependencies:
   pre:
       - bash ./scripts/circleci-build-erlang.sh:
           timeout: 1800
+      - pip install --upgrade pip
+      - pip install PyYAML
 
 test:
   pre:
@@ -34,6 +36,7 @@ test:
     - . ~/.kerl/$OTP_VERSION/activate && make code_checks
     - ./scripts/validate-js.sh $($CHANGED)
     - . ~/.kerl/$OTP_VERSION/activate && make apis
+    - make docs
     - make validate-swagger
     - |
       if [[ 0 -ne `git status --porcelain | wc -l` ]]; then
diff --git a/doc/engineering/dialyzer.md b/doc/engineering/dialyzer.md
index 8b6d0b35bac..932fd55031b 100644
--- a/doc/engineering/dialyzer.md
+++ b/doc/engineering/dialyzer.md
@@ -1,7 +1,3 @@
-/*
-Section: Kazoo
-Title: Dialyzer
-*/
 
 # Using Dialyzer on Kazoo
 
diff --git a/doc/engineering/releases.md b/doc/engineering/releases.md
index 647a52dd406..5682175b700 100644
--- a/doc/engineering/releases.md
+++ b/doc/engineering/releases.md
@@ -1,7 +1,3 @@
-/*
-Section: Kazoo
-Title: Releases
-*/
 
 # How to use Erlang releases with Kazoo
 
diff --git a/doc/installation.md b/doc/installation.md
index 44e75f654e1..75824a1714e 100644
--- a/doc/installation.md
+++ b/doc/installation.md
@@ -15,6 +15,13 @@ $ sudo apt-get install build-essential libxslt-dev \
 
 Note: `htmldoc` is required only if [you want to be able to download PDFs](./announcements.md#company-directory-pdf).
 
+#### Docs-relatd
+
+When running `make docs`, some Python libraries are useful:
+
+```shell
+$ sudo apt-get install python2.7 python-yaml
+```
 
 ### Erlang
 
diff --git a/doc/kazoocon/pivot2014.md b/doc/kazoocon/pivot2014.md
index d3add865ecf..a9fbfd14d2b 100644
--- a/doc/kazoocon/pivot2014.md
+++ b/doc/kazoocon/pivot2014.md
@@ -1,8 +1,3 @@
-/*
-Section: Pivot
-Title: Pivot KazooCon 2014 Demo
-Language: en-US
-*/
 
 # Infrastructure by Pastie.org
 
diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml
index 114962dc164..ae374da7536 100644
--- a/doc/mkdocs/mkdocs.yml
+++ b/doc/mkdocs/mkdocs.yml
@@ -1,5 +1,4 @@
 site_name: Dev Reference
-theme: null
 theme_dir: '2600Hz_theme'
 
 pages:
@@ -78,7 +77,7 @@ pages:
     - 'Twiml':
       - 'applications/pivot/doc/twiml/README.md'
     - 'Tutorials':
-      - 'applications/pivot/doc/kazoocon-2014.md'
+      - 'doc/kazoocon/pivot2014.md'
     - 'Known_Issues':
       - 'applications/pivot/doc/issues.md'
     - 'Kazoo':
diff --git a/doc/reference/caller_id_formatting.md b/doc/reference/caller_id_formatting.md
index 5b19ef77031..5f157e690b0 100644
--- a/doc/reference/caller_id_formatting.md
+++ b/doc/reference/caller_id_formatting.md
@@ -1,7 +1,3 @@
-/*
-Section: Kazoo
-Title: Caller ID Formatting
-*/
 
 # Caller ID Formatting
 
diff --git a/doc/reference/routing.md b/doc/reference/routing.md
index 458b0bb7f53..dd86c4f49b5 100644
--- a/doc/reference/routing.md
+++ b/doc/reference/routing.md
@@ -1,9 +1,3 @@
-/*
-Section: Reference
-Title: Rating and Limits
-Language: en-US
-Version: 3.22
-*/
 
 # Rating and Limits
 
diff --git a/scripts/validate_mkdocs.py b/scripts/validate_mkdocs.py
new file mode 100755
index 00000000000..1d14e073d9f
--- /dev/null
+++ b/scripts/validate_mkdocs.py
@@ -0,0 +1,46 @@
+#!/usr/bin/env python2
+from __future__ import print_function
+
+import yaml, os.path, sys
+
+# from https://stackoverflow.com/questions/5574702/how-to-print-to-stderr-in-python
+def eprint(*args, **kwargs):
+    print(*args, file=sys.stderr, **kwargs)
+
+def parse_page_dict(errors_detected, kv):
+    (header, pages) = kv
+    if pages is None:
+        eprint("section ", header, " is incomplete")
+        return True
+    else:
+        return parse_page(errors_detected, pages)
+
+def parse_page_string(errors_detected, page):
+    if "index.md" != page and (not os.path.isfile(page)):
+        eprint("page ", page, " is not valid")
+        return True
+    else:
+        return errors_detected
+
+def parse_page(errors_detected, page):
+    "parse a page for existence"
+    if isinstance(page, dict):
+        return reduce(parse_page_dict, page.items(), errors_detected)
+    elif isinstance(page, list):
+        return reduce(parse_page, page, errors_detected)
+    elif isinstance(page, str):
+        return parse_page_string(errors_detected, page)
+    else:
+        return errors_detected
+
+stream = open("doc/mkdocs/mkdocs.yml", 'r')
+mkdocs = yaml.load_all(stream)
+errors_detected = False
+
+for doc in mkdocs:
+    for k,v in doc.items():
+        if "pages" == k:
+            errors_detected = parse_page(False, v)
+
+if errors_detected:
+    sys.exit(1)