diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8c3de82
--- /dev/null
+++ b/README.md
@@ -0,0 +1,38 @@
+# OpenStack Charms Deployment Guide
+
+[![tags][image-badge-cdg]][image-link-openstack-tags]
+
+The [OpenStack Charms Deployment Guide][cdg] is the main source of information
+for the usage of the [OpenStack Charms][openstack-charms].
+
+## Building
+
+To build the guide run this simple command:
+
+    tox
+
+The resulting HTML files will be found in the `deploy-guide/build/html`
+directory. These can be opened individually with a web browser or hosted by a
+local web server.
+
+## Contributing
+
+Documentation issues can be filed on [Launchpad][lp-bugs-cdg].
+
+This repository is under version control and is managed via the [OpenStack
+Gerrit system][gerrit-openstack] (see the [OpenDev Developer’s
+Guide][opendev-dev-guide]). For specific guidance on working with the
+documentation hosted on [docs.openstack.org][link] please read the [OpenStack
+Documentation Contributor Guide][openstack-doc-guide].
+
+<!-- LINKS -->
+
+[image-badge-cdg]: http://governance.openstack.org/badges/charm-deployment-guide.svg
+[image-link-openstack-tags]: http://governance.openstack.org/reference/tags/index.html
+[cdg]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide
+[openstack-charms]: https://launchpad.net/openstack-charms
+[lp-bugs-cdg]: https://bugs.launchpad.net/charm-deployment-guide/+filebug
+[gerrit-openstack]: https://review.openstack.org
+[opendev-dev-guide]: https://docs.openstack.org/infra/manual/developers.html
+[openstack-doc-guide]: https://docs.openstack.org/doc-contrib-guide/index.html
+[link]: https://docs.openstack.org
diff --git a/README.rst b/README.rst
deleted file mode 100644
index a1dcb3d..0000000
--- a/README.rst
+++ /dev/null
@@ -1,40 +0,0 @@
-=================================
-OpenStack Charms Deployment Guide
-=================================
-
-.. image:: http://governance.openstack.org/badges/charm-deployment-guide.svg
-   :target: http://governance.openstack.org/reference/tags/index.html
-
-The `OpenStack Charms Deployment Guide`_ is the main source of information for
-the usage of the `OpenStack Charms`_.
-
-Building
---------
-
-To build the guide run this simple command:
-
-.. code-block:: none
-
-   tox
-
-The resulting HTML files will be found in the ``deploy-guide/build/html``
-directory. These can be opened individually with a web browser or hosted by a
-local web server.
-
-Contributing
-------------
-
-Documentation issues can be filed on `Launchpad`_.
-
-This repository is under version control and is managed via the `OpenStack
-Gerrit system`_ (see the `OpenDev Developer’s Guide`_). For specific guidance
-on working with the documentation hosted on https://docs.openstack.org please
-read the `OpenStack Documentation Contributor Guide`_.
-
-.. LINKS
-.. _OpenStack Charms Deployment Guide: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide
-.. _OpenStack Charms: https://launchpad.net/openstack-charms
-.. _Launchpad: https://bugs.launchpad.net/charm-deployment-guide/+filebug
-.. _OpenStack Gerrit system: https://review.openstack.org
-.. _OpenDev Developer’s Guide: https://docs.openstack.org/infra/manual/developers.html
-.. _OpenStack Documentation Contributor Guide: https://docs.openstack.org/doc-contrib-guide/index.html
diff --git a/setup.cfg b/setup.cfg
index ddf6bf0..b89347d 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -2,7 +2,7 @@
 name = charm-deployment-guide
 summary = OpenStack Charm Deployment Guide
 description-file =
-    README.rst
+    README.md
 author = OpenStack
 author-email = openstack-discuss@lists.openstack.org
 home-page = https://docs.openstack.org/project-deploy-guide/charm-deployment-guide