diff --git a/CHANGES b/CHANGES
index d6ab9d92..f7c88346 100644
--- a/CHANGES
+++ b/CHANGES
@@ -13,7 +13,8 @@ The rules for this file:
* release numbers follow "Semantic Versioning" https://semver.org
------------------------------------------------------------------------------
-??/??/2024 orbeckst
+
+08/07/2024 orbeckst, xiki-tempula
* 2.3.1
diff --git a/MANIFEST.in b/MANIFEST.in
index ea2e81a4..055d52c3 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,6 +1,6 @@
include *.rst
recursive-include src/alchemlyb *.gz *.bz2 *.zip *.rst *.txt
-include README.rst
+include README.md
include LICENSE
include versioneer.py
include src/alchemlyb/_version.py
diff --git a/README.md b/README.md
new file mode 100644
index 00000000..6d93fddb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,54 @@
+# alchemlyb: the simple alchemistry library
+
+[](https://zenodo.org/badge/latestdoi/68669096) [](http://alchemlyb.readthedocs.io/en/latest/) [](https://github.com/alchemistry/alchemlyb/actions/workflows/ci.yaml) [](https://codecov.io/gh/alchemistry/alchemlyb) [](https://anaconda.org/conda-forge/alchemlyb)
+
+**alchemlyb** makes alchemical free energy calculations easier to do by leveraging the full power and flexibility of the PyData stack. It includes:
+
+1. Parsers for extracting raw data from output files of common molecular dynamics engines such as [GROMACS](http://www.gromacs.org/), [AMBER](http://ambermd.org/), [NAMD](http://www.ks.uiuc.edu/Research/namd/) and [other simulation codes](https://alchemlyb.readthedocs.io/en/latest/parsing.html).
+
+2. Subsamplers for obtaining uncorrelated samples from timeseries data (including extracting independent, equilibrated samples [Chodera2016](#chodera2016) as implemented in the [pymbar](http://pymbar.readthedocs.io/) package).
+
+3. Estimators for obtaining free energies directly from this data, using best-practices approaches for multistate Bennett acceptance ratio (MBAR) [Shirts2008](#shirts2008) and BAR (from [pymbar](http://pymbar.readthedocs.io/)) and thermodynamic integration (TI).
+
+## Installation
+
+**Install** via `pip` from [PyPi (alchemlyb)](https://pypi.org/project/alchemlyb):
+
+```bash
+pip install alchemlyb
+```
+
+or as a `conda` package from the [conda-forge (alchemlyb)](https://anaconda.org/conda-forge/alchemlyb) channel:
+
+```bash
+conda install -c conda-forge alchemlyb
+```
+
+**Update** with `pip`:
+
+```bash
+pip install --update alchemlyb
+```
+
+or with `conda` run:
+
+```bash
+conda update -c conda-forge alchemlyb
+```
+
+to get the latest released version.
+
+## Getting involved
+
+Contributions of all kinds are very welcome.
+
+If you have questions or want to discuss alchemlyb please post in the [alchemlyb Discussions](https://github.com/alchemistry/alchemlyb/discussions).
+
+If you have bug reports or feature requests then please get in touch with us through the [Issue Tracker](https://github.com/alchemistry/alchemlyb/issues).
+
+We also welcome code contributions: have a look at our [Developer Guide](https://github.com/alchemistry/alchemlyb/wiki/Developer-Guide). Open an issue with the proposed fix or change in the [Issue Tracker](https://github.com/alchemistry/alchemlyb/issues) and submit a pull request against the [alchemistry/alchemlyb](https://github.com/alchemistry/alchemlyb) GitHub repository.
+
+## References
+
+- Shirts, M.R., and Chodera, J.D. (2008). Statistically optimal analysis of samples from multiple equilibrium states. The Journal of Chemical Physics 129, 124105.
+- Chodera, J.D. (2016). A Simple Method for Automated Equilibration Detection in Molecular Simulations. Journal of Chemical Theory and Computation 12, 1799–1805.
diff --git a/README.rst b/README.rst
deleted file mode 100644
index 95301f5f..00000000
--- a/README.rst
+++ /dev/null
@@ -1,110 +0,0 @@
-alchemlyb: the simple alchemistry library
-=========================================
-
-|doi| |docs| |build| |cov| |anaconda|
-
-**alchemlyb** makes alchemical free energy calculations easier to do
-by leveraging the full power and flexibility of the PyData stack. It
-includes:
-
-1. Parsers for extracting raw data from output files of common
- molecular dynamics engines such as `GROMACS`_, `AMBER`_, `NAMD`_
- and `other simulation codes`_.
-
-2. Subsamplers for obtaining uncorrelated samples from timeseries data
- (including extracting independent, equilibrated samples
- [Chodera2016]_ as implemented in the pymbar_ package).
-
-3. Estimators for obtaining free energies directly from this data, using
- best-practices approaches for multistate Bennett acceptance ratio (MBAR)
- [Shirts2008]_ and BAR (from pymbar_) and thermodynamic integration (TI).
-
-.. _GROMACS: http://www.gromacs.org/
-.. _AMBER: http://ambermd.org/
-.. _NAMD: http://www.ks.uiuc.edu/Research/namd/
-.. _`other simulation codes`: https://alchemlyb.readthedocs.io/en/latest/parsing.html
-.. _`pymbar`: http://pymbar.readthedocs.io/
-
-
-Installation
-------------
-
-**Install** via ``pip`` from `PyPi (alchemlyb)`_ ::
-
- pip install alchemlyb
-
-or as a `conda`_ package from the `conda-forge (alchemlyb)`_ channel
-::
-
- conda install -c conda-forge alchemlyb
-
-
-**Update** with ``pip`` ::
-
- pip install --update alchemlyb
-
-or with ``conda`` run ::
-
- conda update -c conda-forge alchemlyb
-
-to get the latest released version.
-
-.. _`PyPi (alchemlyb)`: https://pypi.org/project/alchemlyb/
-.. _`conda`: https://conda.io/
-.. _`conda-forge (alchemlyb)`: https://anaconda.org/conda-forge/alchemlyb
-
-Getting involved
-----------------
-
-Contributions of all kinds are very welcome.
-
-If you have questions or want to discuss alchemlyb please post in the `alchemlyb Discussions`_.
-
-If you have bug reports or feature requests then please get in touch with us through the `Issue Tracker`_.
-
-We also welcome code contributions: have a look at our `Developer Guide`_. Open an issue with the proposed fix or change in the `Issue Tracker`_ and submit a pull request against the `alchemistry/alchemlyb`_ GitHub repository.
-
-.. _`alchemlyb Discussions`: https://github.com/alchemistry/alchemlyb/discussions
-.. _`Developer Guide`: https://github.com/alchemistry/alchemlyb/wiki/Developer-Guide
-.. _`Issue Tracker`: https://github.com/alchemistry/alchemlyb/issues
-.. _`alchemistry/alchemlyb`: https://github.com/alchemistry/alchemlyb
-
-
-
-References
-----------
-
-.. [Shirts2008] Shirts, M.R., and Chodera, J.D. (2008). Statistically optimal
- analysis of samples from multiple equilibrium states. The Journal of Chemical
- Physics 129, 124105.
-
-.. [Chodera2016] Chodera, J.D. (2016). A Simple Method for Automated
- Equilibration Detection in Molecular Simulations. Journal of Chemical Theory
- and Computation 12, 1799–1805.
-
-
-.. |doi| image:: https://zenodo.org/badge/68669096.svg
- :alt: Zenodo DOI
- :scale: 100%
- :target: https://zenodo.org/badge/latestdoi/68669096
-
-.. |docs| image:: https://readthedocs.org/projects/alchemlyb/badge/?version=latest
- :alt: Documentation
- :scale: 100%
- :target: http://alchemlyb.readthedocs.io/en/latest/
-
-.. |build| image:: https://github.com/alchemistry/alchemlyb/actions/workflows/ci.yaml/badge.svg?branch=master
- :alt: Build Status
- :scale: 100%
- :target: https://github.com/alchemistry/alchemlyb/actions/workflows/ci.yaml
-
-.. |cov| image:: https://codecov.io/gh/alchemistry/alchemlyb/branch/master/graph/badge.svg
- :alt: Code coverage
- :scale: 100%
- :target: https://codecov.io/gh/alchemistry/alchemlyb
-
-
-.. |anaconda| image:: https://anaconda.org/conda-forge/alchemlyb/badges/version.svg
- :alt: anaconda package
- :scale: 100%
- :target: https://anaconda.org/conda-forge/alchemlyb
diff --git a/setup.py b/setup.py
index 668a9c3b..1d9c7ca5 100755
--- a/setup.py
+++ b/setup.py
@@ -41,8 +41,8 @@
packages=find_packages("src"),
package_dir={"": "src"},
license="BSD",
- long_description=open("README.rst").read(),
- long_description_content_type="text/x-rst",
+ long_description=open("README.md").read(),
+ long_description_content_type="text/markdown",
python_requires=">=3.9",
tests_require=["pytest", "alchemtest"],
install_requires=[