diff --git a/doc/requirements.txt b/doc/requirements.txt
index 04dc27f14..51a2c6498 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -6,3 +6,4 @@ openstackdocstheme>=2.2.1 # Apache-2.0
reno>=3.1.0 # Apache-2.0
sphinx>=2.0.0,!=2.1.0 # BSD
sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD
+whereto>=0.3.0 # Apache-2.0
diff --git a/doc/source/_extra/.htaccess b/doc/source/_extra/.htaccess
new file mode 100644
index 000000000..df4bd364c
--- /dev/null
+++ b/doc/source/_extra/.htaccess
@@ -0,0 +1,14 @@
+# The following redirects were added when configuration/* was moved to
+# configuration/reference/*.
+redirectmatch 301 ^/([^/]+/[^/]+)/configuration/ansible.html$ /$1/configuration/reference/ansible.html
+redirectmatch 301 ^/([^/]+/[^/]+)/configuration/bifrost.html$ /$1/configuration/reference/bifrost.html
+redirectmatch 301 ^/([^/]+/[^/]+)/configuration/docker-registry.html$ /$1/configuration/reference/docker-registry.html
+redirectmatch 301 ^/([^/]+/[^/]+)/configuration/hosts.html$ /$1/configuration/reference/hosts.html
+redirectmatch 301 ^/([^/]+/[^/]+)/configuration/ironic-python-agent.html$ /$1/configuration/reference/ironic-python-agent.html
+redirectmatch 301 ^/([^/]+/[^/]+)/configuration/kayobe.html$ /$1/configuration/reference/kayobe.html
+redirectmatch 301 ^/([^/]+/[^/]+)/configuration/kolla-ansible.html$ /$1/configuration/reference/kolla-ansible.html
+redirectmatch 301 ^/([^/]+/[^/]+)/configuration/kolla.html$ /$1/configuration/reference/kolla.html
+redirectmatch 301 ^/([^/]+/[^/]+)/configuration/network.html$ /$1/configuration/reference/network.html
+redirectmatch 301 ^/([^/]+/[^/]+)/configuration/nova-cells.html$ /$1/configuration/reference/nova-cells.html
+redirectmatch 301 ^/([^/]+/[^/]+)/configuration/physical-network.html$ /$1/configuration/reference/physical-network.html
+redirectmatch 301 ^/([^/]+/[^/]+)/configuration/seed-custom-containers.html$ /$1/configuration/reference/seed-custom-containers.html
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 1e1589d7e..22ec97df0 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -69,6 +69,10 @@ pygments_style = 'native'
html_theme = 'openstackdocs'
# html_static_path = ['static']
+# Add any paths that contain "extra" files, such as .htaccess or
+# robots.txt.
+html_extra_path = ['_extra']
+
html_theme_options = {
"show_other_versions": True,
}
diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst
index 5ee94898a..1aba4a839 100644
--- a/doc/source/configuration/index.rst
+++ b/doc/source/configuration/index.rst
@@ -5,15 +5,4 @@ Configuration Guide
.. toctree::
:maxdepth: 2
- kayobe
- ansible
- physical-network
- network
- hosts
- kolla
- kolla-ansible
- bifrost
- ironic-python-agent
- docker-registry
- seed-custom-containers
- nova-cells
+ reference/index
diff --git a/doc/source/configuration/ansible.rst b/doc/source/configuration/reference/ansible.rst
similarity index 100%
rename from doc/source/configuration/ansible.rst
rename to doc/source/configuration/reference/ansible.rst
diff --git a/doc/source/configuration/bifrost.rst b/doc/source/configuration/reference/bifrost.rst
similarity index 100%
rename from doc/source/configuration/bifrost.rst
rename to doc/source/configuration/reference/bifrost.rst
diff --git a/doc/source/configuration/docker-registry.rst b/doc/source/configuration/reference/docker-registry.rst
similarity index 100%
rename from doc/source/configuration/docker-registry.rst
rename to doc/source/configuration/reference/docker-registry.rst
diff --git a/doc/source/configuration/hosts.rst b/doc/source/configuration/reference/hosts.rst
similarity index 100%
rename from doc/source/configuration/hosts.rst
rename to doc/source/configuration/reference/hosts.rst
diff --git a/doc/source/configuration/reference/index.rst b/doc/source/configuration/reference/index.rst
new file mode 100644
index 000000000..d68b71b12
--- /dev/null
+++ b/doc/source/configuration/reference/index.rst
@@ -0,0 +1,22 @@
+=======================
+Configuration Reference
+=======================
+
+This section provides detailed information on many of Kayobe's configuration
+options.
+
+.. toctree::
+ :maxdepth: 2
+
+ kayobe
+ ansible
+ physical-network
+ network
+ hosts
+ kolla
+ kolla-ansible
+ bifrost
+ ironic-python-agent
+ docker-registry
+ seed-custom-containers
+ nova-cells
diff --git a/doc/source/configuration/ironic-python-agent.rst b/doc/source/configuration/reference/ironic-python-agent.rst
similarity index 100%
rename from doc/source/configuration/ironic-python-agent.rst
rename to doc/source/configuration/reference/ironic-python-agent.rst
diff --git a/doc/source/configuration/kayobe.rst b/doc/source/configuration/reference/kayobe.rst
similarity index 100%
rename from doc/source/configuration/kayobe.rst
rename to doc/source/configuration/reference/kayobe.rst
diff --git a/doc/source/configuration/kolla-ansible.rst b/doc/source/configuration/reference/kolla-ansible.rst
similarity index 100%
rename from doc/source/configuration/kolla-ansible.rst
rename to doc/source/configuration/reference/kolla-ansible.rst
diff --git a/doc/source/configuration/kolla.rst b/doc/source/configuration/reference/kolla.rst
similarity index 100%
rename from doc/source/configuration/kolla.rst
rename to doc/source/configuration/reference/kolla.rst
diff --git a/doc/source/configuration/network.rst b/doc/source/configuration/reference/network.rst
similarity index 100%
rename from doc/source/configuration/network.rst
rename to doc/source/configuration/reference/network.rst
diff --git a/doc/source/configuration/nova-cells.rst b/doc/source/configuration/reference/nova-cells.rst
similarity index 100%
rename from doc/source/configuration/nova-cells.rst
rename to doc/source/configuration/reference/nova-cells.rst
diff --git a/doc/source/configuration/physical-network.rst b/doc/source/configuration/reference/physical-network.rst
similarity index 100%
rename from doc/source/configuration/physical-network.rst
rename to doc/source/configuration/reference/physical-network.rst
diff --git a/doc/source/configuration/seed-custom-containers.rst b/doc/source/configuration/reference/seed-custom-containers.rst
similarity index 94%
rename from doc/source/configuration/seed-custom-containers.rst
rename to doc/source/configuration/reference/seed-custom-containers.rst
index ed2a42ac8..6d9e05d5f 100644
--- a/doc/source/configuration/seed-custom-containers.rst
+++ b/doc/source/configuration/reference/seed-custom-containers.rst
@@ -56,6 +56,6 @@ module page.
List of Kayobe applied defaults to required docker_container variables:
-.. literalinclude:: ../../../ansible/roles/deploy-containers/defaults/main.yml
+.. literalinclude:: ../../../../ansible/roles/deploy-containers/defaults/main.yml
:language: yaml
diff --git a/doc/test/redirect-tests.txt b/doc/test/redirect-tests.txt
new file mode 100644
index 000000000..400068f4f
--- /dev/null
+++ b/doc/test/redirect-tests.txt
@@ -0,0 +1,25 @@
+# This file contains tests for redirects to handle existing URLs for
+# specs that have been moved. See
+# https://docs.openstack.org/whereto/latest/ for details.
+
+# No redirect.
+/ 200
+/kayobe 200
+/kayobe/latest 200
+/kayobe/latest/configuration/ 200
+/kayobe/latest/configuration/index.html 200
+/kayobe/latest/configuration/reference/index.html 200
+
+# Moved /kayobe/latest/configuration/*.html to /kayobe/latest/configuration/reference/
+/kayobe/latest/configuration/ansible.html 301 /kayobe/latest/configuration/reference/ansible.html
+/kayobe/latest/configuration/bifrost.html 301 /kayobe/latest/configuration/reference/bifrost.html
+/kayobe/latest/configuration/docker-registry.html 301 /kayobe/latest/configuration/reference/docker-registry.html
+/kayobe/latest/configuration/hosts.html 301 /kayobe/latest/configuration/reference/hosts.html
+/kayobe/latest/configuration/ironic-python-agent.html 301 /kayobe/latest/configuration/reference/ironic-python-agent.html
+/kayobe/latest/configuration/kayobe.html 301 /kayobe/latest/configuration/reference/kayobe.html
+/kayobe/latest/configuration/kolla-ansible.html 301 /kayobe/latest/configuration/reference/kolla-ansible.html
+/kayobe/latest/configuration/kolla.html 301 /kayobe/latest/configuration/reference/kolla.html
+/kayobe/latest/configuration/network.html 301 /kayobe/latest/configuration/reference/network.html
+/kayobe/latest/configuration/nova-cells.html 301 /kayobe/latest/configuration/reference/nova-cells.html
+/kayobe/latest/configuration/physical-network.html 301 /kayobe/latest/configuration/reference/physical-network.html
+/kayobe/latest/configuration/seed-custom-containers.html 301 /kayobe/latest/configuration/reference/seed-custom-containers.html
diff --git a/tox.ini b/tox.ini
index 76c1f771c..8d473f161 100644
--- a/tox.ini
+++ b/tox.ini
@@ -115,6 +115,7 @@ deps =
commands =
rm -rf doc/build/html
sphinx-build -W --keep-going -b html doc/source doc/build/html
+ whereto doc/source/_extra/.htaccess doc/test/redirect-tests.txt
[testenv:pdf-docs]
whitelist_externals = make