Cleanup README

Author: dstansby

README.rst renamed to README.md

@@ -1,5 +1,4 @@
-Matplotlib Sphinx Theme
-=======================
+# Matplotlib Sphinx Theme
 
 This is the official Sphinx theme for Matplotlib documentation.  It extends the
 ``pydata-sphinx-theme`` project, but adds custom styling and a navigation bar.
@@ -10,9 +9,9 @@ https://matplotlib.org/mpl-sphinx-theme/.
 When creating a Matplotlib subproject you can include this theme by changing this
 line in your ``conf.py`` file
 
-.. code-block:: python
-
-   html_theme = 'mpl_sphinx_theme'
+```python
+html_theme = 'mpl_sphinx_theme'
+```
 
 And by including ``mpl_sphinx_theme`` as a requirement in your documentation
 installation.
@@ -21,11 +20,10 @@ See the ``docs/conf.py`` file for other settings.
 
 There are two main templates that replace the defaults in ``pydata-sphinx-theme``:
 
-.. code-block::
-
-   navbar_center = mpl_nav_bar.html
-   navbar_end = mpl_icon_links.html
-
+```
+navbar_center = mpl_nav_bar.html
+navbar_end = mpl_icon_links.html
+```
 Note that the logo options need not be specified as they are included in theme
 initialization. The logo is stored at
 ``mpl_sphinx_theme/static/logo_{light,dark}.svg``.
@@ -36,35 +34,33 @@ To change the social icons, edit ``mpl_sphinx_theme/mpl_icon_links.html``
 
 To change the style, edit ``mpl_sphinx_theme/static/css/style.css``
 
-Overriding hard coded elements
-------------------------------
+## Overriding hard coded elements
+
 This theme is primarily designed to be used with subprojects that are part of the main
-Matplotlib webiste (e.g., [our cheatseets](https://github.com/matplotlib/cheatsheets]
+Matplotlib webiste (e.g., [our cheatseets](https://github.com/matplotlib/cheatsheets)
 and [list of third-party packages](https://github.com/matplotlib/mpl-third-party)).
 As such several elements are hard coded. However, the theme may also be used by
 other subprojects that need to change the hard-coded defaults.
 The following sections explain how to reset these back to their defaults by modifying
 ``html_theme_options`` in ``conf.py``.
 
-Header section links
-~~~~~~~~~~~~~~~~~~~~
+### Header section links
+
 Use a copy of [the default pydata-sphinx-theme navbar](https://github.com/pydata/pydata-sphinx-theme/blob/main/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-nav.html) and set the ``'navbar_center'`` key to this HTML file in ``html_theme_options``.
 
-Building
---------
-To build the theme with a sample page, navigate into the ``doc/`` directory and run
+## Building
 
-.. code-block::
+To build the theme with a sample page, navigate into the ``doc/`` directory and run
 
-   make html
+```
+make html
+```
 
 The built html pages can be found in ``doc/_build/html/``
 
-Releasing
----------
+## Releasing
 
-This project `uses GitHub Actions
-<https://github.com/matplotlib/mpl-sphinx-theme/blob/main/.github/workflows/release.yml>`_
+This project [uses GitHub Actions](https://github.com/matplotlib/mpl-sphinx-theme/blob/main/.github/workflows/release.yml)
 to automatically push a new release to PyPI whenever a release is made.
 
 For example, to release a new ``3.9.0`` version of ``mpl-sphinx-theme``:
@@ -74,19 +70,18 @@ For example, to release a new ``3.9.0`` version of ``mpl-sphinx-theme``:
 - add a git tag
 - push the tag to the ``matplotlib/mpl-sphinx-theme`` repository
 
-.. code-block::
-
-   $ git checkout <commit-hash>
-   $ git tag -s -a v3.9.0 -m 'REL: 3.9.0'
-   $ git push upstream --tags
+```sh
+git checkout <commit-hash>
+git tag -s -a v3.9.0 -m 'REL: 3.9.0'
+git push upstream --tags
+```
 
-Finally, `turn the tag into a GitHub release
-<https://github.com/matplotlib/mpl-sphinx-theme/releases/new>`_.
+Finally, [turn the tag into a GitHub release](https://github.com/matplotlib/mpl-sphinx-theme/releases/new).
 
 Update the required ``mpl-sphinx-theme`` version in the following files:
 
-* matplotlib/matplotlib: requirements/doc/doc-requirements.txt
-* matplotlib/mpl-brochure-site: requirements.txt
-* matplotlib/mpl-third-party: docs/requirements.txt
-* matplotlib/governance: requirements-doc.txt
-* matplotlib/mpl-gui: requirements-doc.txt
+* [matplotlib/matplotlib](https://github.com/matplotlib/matplotlib): requirements/doc/doc-requirements.txt
+* [matplotlib/mpl-brochure-site](https://github.com/matplotlib/mpl-brochure-site): requirements.txt
+* [matplotlib/mpl-third-party](https://github.com/matplotlib/mpl-third-party): docs/requirements.txt
+* [matplotlib/governance](https://github.com/matplotlib/governance): requirements-doc.txt
+* [matplotlib/mpl-gui](https://github.com/matplotlib/mpl-gui): requirements-doc.txt