diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e1b5209c..82e66a5d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -21,6 +21,7 @@ Or `nix`:
 ./scripts/generate-nix-files.sh   # Get up-to-date shell.nix files
 ```
 
+To build the docs, see `doc/README.md`.
 
 ## General
 
diff --git a/doc/README.md b/doc/README.md
new file mode 100644
index 00000000..8fcfc1f6
--- /dev/null
+++ b/doc/README.md
@@ -0,0 +1,8 @@
+To build the docs locally:
+
+    $ virtualenv venv
+    $ . ./venv/bin/activate
+    $ pip install -r requirements.txt
+    $ make html
+
+Docs will be built in _build/html/index.html .
diff --git a/doc/building-the-docs b/doc/building-the-docs
deleted file mode 100644
index 34f8b16f..00000000
--- a/doc/building-the-docs
+++ /dev/null
@@ -1,8 +0,0 @@
-To build the docs locally:
-
-$ virtualenv venv
-$ . ./venv/bin/activate
-$ pip install -r requirements.txt
-$ make html
-
-Docs will be built in _build/html/index.html .
diff --git a/doc/conf.py b/doc/conf.py
index 20b7c2d6..834ca7fa 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -167,7 +167,6 @@ texinfo_documents = [
 # -- Markdown -------------------------------------------------------------
 
 source_parsers = {
-    '.md': CommonMarkParser,
     '.lhs': CommonMarkParser,
 }
 
diff --git a/doc/requirements.txt b/doc/requirements.txt
index 8ebf5848..54edda34 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -1,3 +1,3 @@
-recommonmark==0.4.0
-Sphinx==1.7.5
-sphinx_rtd_theme>=0.4.0
+recommonmark==0.5.0
+Sphinx==1.8.4
+sphinx_rtd_theme>=0.4.2