diff --git a/doc/requirements.txt b/doc/requirements.txt
index ab68d4701e..0a525ddbf0 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -2,7 +2,7 @@
 # of appearance. Changing the order has an impact on the overall integration
 # process, which may cause wedges in the gate later.
 doc8>=0.6.0 # Apache-2.0
-openstackdocstheme>=1.18.1 # Apache-2.0
+openstackdocstheme>=1.19.0 # Apache-2.0
 reno>=2.5.0 # Apache-2.0
 sphinx!=1.6.6,!=1.6.7,>=1.6.2,<2.0.0;python_version=='2.7' # BSD
 sphinx!=1.6.6,!=1.6.7,>=1.6.2;python_version>='3.4' # BSD
diff --git a/doc/source/admin/image-building.rst b/doc/source/admin/image-building.rst
index 1f099802bd..a0b756c8c7 100644
--- a/doc/source/admin/image-building.rst
+++ b/doc/source/admin/image-building.rst
@@ -1,5 +1,3 @@
-.. _image-building:
-
 =========================
 Building Container Images
 =========================
@@ -151,9 +149,8 @@ repository named ``mykollarepo``:
 
    kolla-build -n mykollarepo --push
 
-To push images to a `local registry
-<https://docs.openstack.org/kolla-ansible/latest/user/multinode.html#deploy-a-registry>`_,
-use ``--registry`` flag:
+To push images to a :kolla-ansible-doc:`local registry
+<user/multinode.html#deploy-a-registry>`, use ``--registry`` flag:
 
 .. code-block:: console
 
@@ -217,6 +214,8 @@ overrides file, add the following:
    RUN subscription-manager register --user=<user-name> \
    --password=<password> && subscription-manager attach --pool <pool-id>
 
+.. _dockerfile-customisation:
+
 Dockerfile Customisation
 ========================
 
@@ -534,9 +533,8 @@ Kolla-ansible with Local Registry
 To make kolla-ansible pull images from a local registry, set
 ``"docker_registry"`` to ``"172.22.2.81:5000"`` in
 ``"/etc/kolla/globals.yml"``. Make sure Docker is allowed to pull images from
-insecure registry. See
-`Docker Insecure Registry
-<https://docs.openstack.org/kolla-ansible/latest/user/multinode.html#deploy-a-registry>`_.
+insecure registry. See :kolla-ansible-doc:`Docker Insecure Registry
+<user/multinode.html#deploy-a-registry>`.
 
 Building behind a proxy
 -----------------------
diff --git a/doc/source/conf.py b/doc/source/conf.py
index d4a23cab23..862ab85e9b 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -88,3 +88,7 @@ latex_documents = [
 repository_name = 'openstack/kolla'
 bug_project = 'kolla'
 bug_tag = ''
+openstack_projects = [
+    'kolla-ansible',
+    'oslotest',
+]
diff --git a/doc/source/contributor/CONTRIBUTING.rst b/doc/source/contributor/CONTRIBUTING.rst
index 3d86d1c062..83632d44de 100644
--- a/doc/source/contributor/CONTRIBUTING.rst
+++ b/doc/source/contributor/CONTRIBUTING.rst
@@ -1,5 +1,3 @@
-.. _CONTRIBUTING:
-
 =================
 How To Contribute
 =================
@@ -77,8 +75,8 @@ multiple processes generally use a base image and child images, for example,
 ``glance-base``, ``glance-api``, and ``glance-registry``.
 
 Jinja2 'blocks' are employed throughout the Dockerfile's to help operators
-customise various stages of the build (refer to `Dockerfile Customisation
-<https://docs.openstack.org/kolla/latest/admin/image-building.html#dockerfile-customisation>`__)
+customise various stages of the build (refer to :ref:`Dockerfile Customisation
+<dockerfile-customisation>`)
 
 Some of these blocks are free form however, there are a subset that should be
 common to every Dockerfile. The overall structure for a multi container service
diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst
index 44766f0f69..40c5b0d190 100644
--- a/doc/source/contributor/index.rst
+++ b/doc/source/contributor/index.rst
@@ -12,7 +12,7 @@ We welcome everyone to join our project!
 .. toctree::
    :maxdepth: 2
 
-   CONTRIBUTING.rst
+   CONTRIBUTING
    running-tests
    bug-triage
    ptl-guide
diff --git a/doc/source/contributor/running-tests.rst b/doc/source/contributor/running-tests.rst
index ebd82007c9..5d30703be0 100644
--- a/doc/source/contributor/running-tests.rst
+++ b/doc/source/contributor/running-tests.rst
@@ -107,8 +107,8 @@ Then run :command:`tox` with the debug environment as one of the following:
    tox -e debug
    tox -e debug test_file_name.TestClass.test_name
 
-For more information see the `oslotest documentation
-<https://docs.openstack.org/oslotest/latest/user/features.html#debugging-with-oslo-debug-helper>`_.
+For more information see the :oslotest-doc:`oslotest documentation
+<user/features.html#debugging-with-oslo-debug-helper>`.
 
 
 .. rubric:: Footnotes
diff --git a/specs/containerize-openstack.rst b/specs/containerize-openstack.rst
index d9b8acfe63..9acdc99279 100644
--- a/specs/containerize-openstack.rst
+++ b/specs/containerize-openstack.rst
@@ -194,8 +194,7 @@ A different motive for not using EXPOSE is the 20 microsecond penalty
 applied to every packet forwarded and returned by docker-proxy.
 If EXPOSE functionality is desired, it can be added back by
 referencing the default list of OpenStack ports to each Dockerfile:
-
-    https://docs.openstack.org/trunk/config-reference/content/firewalls-default-ports.html
+`Firewalls and default ports <https://docs.openstack.org/install-guide/firewalls-default-ports.html>`__.
 
 We will use the docker flag --restart=always to provide some measure of
 high availability for the individual containers and ensure they operate