diff --git a/.gitignore b/.gitignore
index 60c284b2c6..12ca935e50 100644
--- a/.gitignore
+++ b/.gitignore
@@ -116,3 +116,7 @@ core.*
 *.log !run.log
 *.pyc
 Depends
+
+# Docs output
+_build*/
+_publish*/
diff --git a/Externals.cfg b/Externals.cfg
index bcee03c493..3731cc9959 100644
--- a/Externals.cfg
+++ b/Externals.cfg
@@ -37,7 +37,7 @@ required = True
 local_path = doc/doc-builder
 protocol = git
 repo_url = https://github.com/ESMCI/doc-builder
-tag = v1.0.4
+tag = v2.0.0
 required = False
 
 [externals_description]
diff --git a/doc/Makefile b/doc/Makefile
index 9b2c2dcd0d..7e74b6e545 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -12,14 +12,13 @@ BUILDDIR      = build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-# 'make fetch-images' should be run before building the
-# documentation. (If building via https://github.com/ESMCI/doc-builder,
-# this is run automatically for you.) This is needed because we have
-# configured this repository (via an .lfsconfig file at the top level)
-# to NOT automatically fetch any of the large files when cloning /
-# fetching.
+# 'make fetch-images' should be run before building the documentation. (If building via
+# the build_docs command, this is run automatically for you.) This is needed because we
+# have configured this repository (via an .lfsconfig file at the top level) to NOT
+# automatically fetch any of the large files when cloning / fetching.
 fetch-images:
-	git lfs pull --exclude=""
+	git lfs install --force
+	git lfs pull --exclude="" --include=""
 
 .PHONY: help fetch-images Makefile
 
diff --git a/doc/build_docs b/doc/build_docs
index 97fb7aa9b2..149d4edcb6 100755
--- a/doc/build_docs
+++ b/doc/build_docs
@@ -1,8 +1,17 @@
 #!/usr/bin/env bash
+set -e
 
-if [ -f doc-builder/build_docs ]; then
-    echo "Running: doc-builder/build_docs --fetch-images $@"
-    doc-builder/build_docs --fetch-images "$@"
-else
-    echo "Obtain doc-builder by running ./manage_externals/checkout_externals -o from the top-level"
+if [ ! -f doc-builder/build_docs ]; then
+    script_dir="$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+    pushd "${script_dir}/.." 1>/dev/null
+    manage_externals/checkout_externals doc-builder
+    popd 1>/dev/null
 fi
+
+echo "Running: make fetch-images"
+make fetch-images
+
+echo "Running: ./doc-builder/build_docs $@"
+./doc-builder/build_docs "$@"
+
+exit 0
\ No newline at end of file
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 0a03244887..0f25aa390b 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -1,8 +1,5 @@
 # -*- coding: utf-8 -*-
 #
-# clmdoc documentation build configuration file, created by
-# sphinx-quickstart on Thu Feb 23 17:14:30 2017.
-#
 # This file is execfile()d with the current directory set to its
 # containing dir.
 #
@@ -18,10 +15,15 @@
 #
 import os
 import sys
-# Note that we need a specific version of sphinx_rtd_theme. This can be obtained with:
-# pip install git+https://github.com/esmci/sphinx_rtd_theme.git@version-dropdown-with-fixes
 import sphinx_rtd_theme
-# sys.path.insert(0, os.path.abspath('.'))
+
+# Assumes you have substitutions.py on your path
+# pylint: disable=wrong-import-position
+dir2add = os.path.join(os.path.dirname(__file__))
+print(dir2add)
+sys.path.insert(0, dir2add)
+import substitutions as subs  # pylint: disable=import-error
+from version_list import VERSION_LIST
 
 
 # -- General configuration ------------------------------------------------
@@ -37,8 +39,9 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
-    'sphinx.ext.imgmath',
-    'sphinx.ext.githubpages']
+    'sphinx.ext.githubpages',
+    'sphinx_mdinclude',
+    ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -46,27 +49,18 @@
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ['.rst', '.md']
+# source_suffix = '.rst'
 
 # The master toctree document.
-master_doc = 'index'
+source_start_file = 'index'
 
-# General information about the project.
-project = u'ctsm'
-copyright = u'2020, UCAR'
-author = u''
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = u'CLM5.0'
-# The full version, including alpha/beta/rc tags.
-release = u'release-clm5.0'
-# CTSM-specific: version label used at the top of some pages.
-version_label = 'CLM5.0 (CESM2.1)'
+# Save standard Sphinx substitution vars separately
+project = subs.project
+copyright = subs.copyright  # pylint: disable=redefined-builtin
+author = subs.author
+version = subs.version
+release = subs.release
 
 # version_label is not a standard sphinx variable, so we need some custom rst to allow
 # pages to use it. We need a separate replacement for the bolded version because it
@@ -74,14 +68,14 @@
 rst_epilog = """
 .. |version_label| replace:: {version_label}
 .. |version_label_bold| replace:: **{version_label}**
-""".format(version_label=version_label)
+""".format(version_label=subs.version_label)
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -94,8 +88,6 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
-imgmath_image_format = 'svg'
-
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -106,15 +98,6 @@
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#
-# The 'versions' option needs to have at least two versions to work, but it doesn't need
-# to have all versions: others will be added dynamically. Note that this maps from version
-# names to html links. The current version can link to the current location (i.e., do
-# nothing). For the other version, we just add a place-holder; its name and value are
-# unimportant because these versions will get replaced dynamically.
-html_theme_options = {}
-html_theme_options['versions'] = {version: ''}
-html_theme_options['versions']['[placeholder]'] = ''
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -124,64 +107,70 @@
 
 # -- Options for HTMLHelp output ------------------------------------------
 
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'clmdocdoc'
+if getattr(subs, "htmlhelp", False):
+    htmlhelp_basename = subs.htmlhelp["basename"]
 
 
 # -- Options for LaTeX output ---------------------------------------------
-
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-
-    # Additional stuff for the LaTeX preamble.
-    #
-    'preamble': '\\usepackage{hyperref}',
-
-    'fncychap': '\\usepackage[Conny]{fncychap}',
-
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-latex_documents = [(master_doc, 'clmdoc.tex', u'CLM5 Documentation', '', 'manual'),]
-
-
-# -- Options for manual page output ---------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, 'clmdoc', u'clmdoc Documentation',
-     [author], 1)
-]
-
-
-# -- Options for Texinfo output -------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
-    (master_doc, 'clmdoc', u'clmdoc Documentation',
-     author, 'clmdoc', 'One line description of project.',
-     'Miscellaneous'),
-]
-
-
-
+if getattr(subs, "latex", False):
+
+    latex_elements = {
+        # The paper size ('letterpaper' or 'a4paper').
+        #
+        # 'papersize': 'letterpaper',
+
+        # The font size ('10pt', '11pt' or '12pt').
+        #
+        # 'pointsize': '10pt',
+
+        # Additional stuff for the LaTeX preamble.
+        #
+        'preamble': '\\usepackage{hyperref}',
+
+        'fncychap': '\\usepackage[Conny]{fncychap}',
+
+        # Latex figure (float) alignment
+        #
+        # 'figure_align': 'htbp',
+    }
+
+    # Grouping the document tree into LaTeX files. List of tuples
+    # (source start file, target name, title,
+    #  author, documentclass [howto, manual, or own class]).
+    latex_documents = [(
+        source_start_file,
+        subs.latex["target_name"],
+        subs.latex["title"],
+        author,
+        subs.latex["category"],
+    )]
+
+
+# Options for manual page and Texinfo output
+if getattr(subs, "mantex", False):
+
+    # One entry per manual page. List of tuples
+    # (source start file, name, title, authors, manual section).
+    man_pages = [
+        (source_start_file, subs.mantex["name"], subs.mantex["title"], [author], 1),
+    ]
+
+    if getattr(subs, "tex", False):
+        # Grouping the document tree into Texinfo files. List of tuples
+        # (source start file, target name, title, author,
+        #  dir menu entry, description, category)
+        texinfo_documents = [(
+            source_start_file,
+            subs.mantex["name"],
+            subs.mantex["title"],
+            author,
+            subs.tex["dirmenu_entry"],
+            subs.tex["description"],
+            subs.tex["category"]),
+        ]
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'python': ('https://docs.python.org/', None)}
 
 numfig = True
 numfig_format = {'figure': 'Figure %s',
@@ -192,4 +181,26 @@
 numfig_secnum_depth = 2
 
 def setup(app):
-    app.add_stylesheet('css/custom.css')
+    app.add_css_file('css/custom.css')
+
+try:
+    html_context
+except NameError:
+    html_context = dict()
+
+html_context["display_lower_left"] = True
+
+# Whether to show the version dropdown. If not set as environment variable, or environment variable
+# is Python-falsey, do not show it.
+version_dropdown = os.environ.get("version_dropdown")
+
+if version_dropdown:
+    html_context["current_version"] = os.environ["version_display_name"]
+
+    html_context["versions"] = []
+    pages_root = os.environ["pages_root"]
+    for this_version in VERSION_LIST:
+        html_context["versions"].append([
+            this_version.display_name,
+            os.path.join(pages_root, this_version.subdir()),
+        ])
diff --git a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst
index 439de8a7a1..d045381212 100644
--- a/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst
+++ b/doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst
@@ -47,9 +47,9 @@ and discharges the water to its downstream spatial unit or the ocean.
 
 .. _Figure MOSART conceptual diagram:
 
-.. figure:: mosart_diagram.png
-    :width: 800px
-    :height: 400px
+.. Figure:: mosart_diagram.png
+
+ MOSART conceptual diagram
 
 MOSART only routes positive runoff, although negative runoff can be generated
 occasionally by the land model (e.g., :math:`q_{gwl}`). Negative runoff in any
diff --git a/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst b/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst
index 04fad02db2..9c94370543 100644
--- a/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst
+++ b/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst
@@ -134,6 +134,3 @@ Example 6-1. Example of running PTCLMmkdata for US-UMB on cheyenne
 
 
 PTCLMmkdata includes a README file that gives some extra details and a simple example.
-
-.. include:: ../../../../tools/PTCLM/README
-   :literal:
diff --git a/doc/source/users_guide/testing/testing.rst b/doc/source/users_guide/testing/testing.rst
index a01630c293..1a41e84cdf 100644
--- a/doc/source/users_guide/testing/testing.rst
+++ b/doc/source/users_guide/testing/testing.rst
@@ -26,12 +26,6 @@ tests as well as lists of tests. The standard testname for CLM is "aux_clm" for
 well as the CGD machine hobart for intel, nag, and pgi compilers.  There's also a shorter test list called "clm_short". Also
 see the `CTSM Wiki on Testing <https://github.com/ESCOMP/ctsm/wiki/System-Testing-Guide>`_.
 
-CTSM Tools Testing
-==================
-
-.. include:: ../../../../test/tools/README
-   :literal:
-
 CTSM Fortran Unit Tests
 =======================
 
@@ -46,16 +40,3 @@ Run the following perl tester that
 ::
    > cd bld/unit_testers
    > ./build-namelist_test.pl
-
-
-Testing PTCLM
-=============
-
-.. include:: ../../../../tools/PTCLM/README
-   :literal:
-
-To run on cheyenne, you do the following:
-
-
-.. include:: ../../../../tools/PTCLM/test/README.run_cheyenne
-   :literal:
diff --git a/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst b/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst
index 14c3a75207..ee2af2712c 100644
--- a/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst
+++ b/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst
@@ -97,11 +97,6 @@ More details on each environment variable.
 
 .. note:: There are several files that are copies of the original files. By having copies the tools can all be made stand-alone, but any changes to the originals will have to be put into the tool directories as well.
 
-The *README.filecopies* (which can be found in ``$CTSMROOT/tools``) is repeated here.
-
-.. include:: ../../../../tools/README.filecopies
-   :literal:
-
 ================================================================
  Building the CLM tools that use the CIME configure/build system
 ================================================================
diff --git a/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst b/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst
index 6048baa98c..542d492782 100644
--- a/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst
+++ b/doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst
@@ -111,4 +111,4 @@ mkmapdata.sh has a help option with the following
 
   Details of running mkmapdata.sh
 
-Each of the raw datasets for **mksurfdata_map** needs a mapping file to map from the output grid you are running on to the grid and land-mask for that dataset. This is what **mkmapdata.sh** does. To create the mapping files you need a SCRIP grid file to correspond with each resolution and land mask that you have a raw data file in **mksurfdata_map**. Some raw datasets share the same grid and land mask -- hence they can share the same SCRIP grid file. The output maps created here go into **mksurfdata_map** see :numref:`Figure mksurfdatamap`.
+Each of the raw datasets for **mksurfdata_map** needs a mapping file to map from the output grid you are running on to the grid and land-mask for that dataset. This is what **mkmapdata.sh** does. To create the mapping files you need a SCRIP grid file to correspond with each resolution and land mask that you have a raw data file in **mksurfdata_map**. Some raw datasets share the same grid and land mask -- hence they can share the same SCRIP grid file. The output maps created here go into **mksurfdata_map**.
diff --git a/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst b/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst
index c974b9c886..e3bae44cd6 100644
--- a/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst
+++ b/doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst
@@ -14,9 +14,9 @@ When just creating a replacement file for an existing one, the relevant tool sho
 
   Data Flow for Creation of Surface Datasets from Raw SCRIP Grid Files
 
-Starting from a SCRIP grid file that describes the grid you will run the model on, you first run **mkmapdata.sh** to create a list of mapping files. See :numref:`Figure mkmapdata.sh` for a more detailed view of how **mkmapdata.sh** works. The mapping files tell **mksurfdata_map** how to map between the output grid and the raw datasets that it uses as input. The output of **mksurfdata_map** is a surface dataset that you then use for running the model. See `Figure :numref:`Figure mksurfdatamap` for a more detailed view of how **mksurfdata_map** works.
+Starting from a SCRIP grid file that describes the grid you will run the model on, you first run **mkmapdata.sh** to create a list of mapping files. See :numref:`Figure mkmapdata.sh` for a more detailed view of how **mkmapdata.sh** works. The mapping files tell **mksurfdata_map** how to map between the output grid and the raw datasets that it uses as input. The output of **mksurfdata_map** is a surface dataset that you then use for running the model.
 
-:numref:`Figure Data_Flow_Legend` is the legend for this figure (:numref:`Figure Data_Flow`) and other figures in this chapter (:numref:`Figure Global_Domain`, :numref:`Figure mknoocnmap.pl` and :numref:`Figure mksurfdatamap`).
+:numref:`Figure Data_Flow_Legend` is the legend for this figure (:numref:`Figure Data_Flow`) and other figures in this chapter (:numref:`Figure Global-Domain` and :numref:`Figure mknoocnmap.pl`).
 
 .. _Figure Data_Flow_Legend:
 
diff --git a/doc/substitutions.py b/doc/substitutions.py
new file mode 100644
index 0000000000..0c1308919c
--- /dev/null
+++ b/doc/substitutions.py
@@ -0,0 +1,63 @@
+"""
+Substitutions for Sphinx
+"""
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+
+# pylint: disable=invalid-name
+
+#################################
+### Standard Sphinx variables ###
+#################################
+
+# General information about the project.
+project = "ctsm"
+copyright = "2020, UCAR"  # pylint: disable=redefined-builtin
+author = ""
+
+# The short X.Y version.
+version = "CLM5.0"
+
+# The full version, including alpha/beta/rc tags.
+release = "release-clm5.0"
+
+#####################################################
+### Custom variables needed for doc-builder setup ###
+#####################################################
+
+# Version label used at the top of some pages.
+version_label = "CLM5.0 (CESM2.1)"
+
+#######################################################
+### Custom variables optional for doc-builder setup ###
+#######################################################
+
+tex_category = "Miscellaneous"
+
+# Used by HTML help builder
+htmlhelp = {
+    "basename": "clmdocdoc", # Output file base name
+}
+
+# Used for LaTeX output
+latex = {
+    "target_name": "clmdoc.tex",
+    "title": "CLM Documentation",
+    "documentclass": "manual", # howto, manual, or own class
+    "category": tex_category,
+}
+
+# Used for man_pages and texinfo_documents
+mantex = {
+    "name": "clmdoc",
+    "title": "clmdoc Documentation",
+}
+
+# Used for texinfo_documents
+tex = {
+    "dirmenu_entry": "clmdoc",
+    "description": "One line description of project.",
+    "category": tex_category,
+}
\ No newline at end of file