diff --git a/docs/Makefile b/docs/Makefile
index b554a1454..3a5bba8df 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -2,9 +2,8 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = python -msphinx
-SPHINXPROJ    = openforcefield
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
 
@@ -17,4 +16,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/conf.py b/docs/conf.py
index f4b4bb15d..57286e2e9 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -26,6 +26,9 @@
 
 import openforcefield
 
+from recommonmark.transform import AutoStructify
+from m2r import MdInclude
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -46,7 +49,7 @@
     'sphinx.ext.viewcode',
     'sphinx.ext.intersphinx',
     'nbsphinx',
-    'm2r', # render markdown
+    'recommonmark', # render markdown
     ]
 
 autosummary_generate = True
@@ -285,3 +288,22 @@
      author, 'openforcefield', 'One line description of project.',
      'Miscellaneous'),
 ]
+
+# workaround for using m2r only for mdinclude and recommonmark for everything else
+# m2r unmaintained, but has features that aren't easy to replicate in recommonmark
+# https://github.com/readthedocs/recommonmark/issues/191#issuecomment-622369992
+# credit: @orsinium
+def setup(app):
+    config = {
+        'auto_toc_tree_section': 'Contents',
+        'enable_eval_rst': True,
+    }
+    app.add_config_value('recommonmark_config', config, True)
+    app.add_transform(AutoStructify)
+
+    # from m2r to make `mdinclude` work
+    app.add_config_value('no_underscore_emphasis', False, 'env')
+    app.add_config_value('m2r_parse_relative_links', False, 'env')
+    app.add_config_value('m2r_anonymous_references', False, 'env')
+    app.add_config_value('m2r_disable_inline_math', False, 'env')
+    app.add_directive('mdinclude', MdInclude)