diff --git a/README.md b/README.md
deleted file mode 100644
index 11acba5..0000000
--- a/README.md
+++ /dev/null
@@ -1,143 +0,0 @@
-[![Build Status](https://dev.azure.com/asottile/asottile/_apis/build/status/asottile.blacken-docs?branchName=main)](https://dev.azure.com/asottile/asottile/_build/latest?definitionId=36&branchName=main)
-[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/asottile/blacken-docs/main.svg)](https://results.pre-commit.ci/latest/github/asottile/blacken-docs/main)
-
-blacken-docs
-============
-
-Run `black` on python code blocks in documentation files.
-
-## install
-
-```bash
-pip install blacken-docs
-```
-
-## usage
-
-`blacken-docs` provides a single executable (`blacken-docs`) which will modify
-`.rst` / `.md` / `.tex` files in place.
-
-If a file is modified, `blacken-docs` exits nonzero.
-
-It currently supports the following [`black`](https://github.com/psf/black)
-options:
-
-- `-l` / `--line-length`
-- `-t` / `--target-version`
-- `-S` / `--skip-string-normalization`
-
-Following additional parameters can be used:
-
- - `-E` / `--skip-errors`
- - `--rst-literal-blocks`
-
-`blacken-docs` will format code in the following block types:
-
-(markdown)
-```markdown
- ```python
- def hello():
- print("hello world")
- ```
-```
-
-(markdown `pycon`)
-```markdown
- ```pycon
-
- >>> def hello():
- ... print("hello world")
- ...
-
- ```
-```
-
-(rst)
-```rst
- .. code-block:: python
-
- def hello():
- print("hello world")
-```
-
-This style is enabled with the `--use-sphinx-default` option.
-
-(rst `pycon`)
-```rst
- .. code-block:: pycon
-
- >>> def hello():
- ... print("hello world")
- ...
-```
-
-(rst literal blocks - activated with ``--rst-literal-blocks``)
-
-reStructuredText [literal blocks](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#literal-blocks) are marked with `::` and can be any monospaced text by default.
-However Sphinx interprets them as Python code [by default](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-literal-blocks).
-If your project uses Sphinx and such a configuration, add `--rst-literal-blocks` to also format such blocks.
-
-``rst
- An example::
-
- def hello():
- print("hello world")
-```
-
-(latex)
-```latex
-\begin{minted}{python}
-def hello():
- print("hello world")
-\end{minted}
-```
-
-(latex `pycon`)
-```latex
-\begin{minted}{pycon}
->>> def hello():
-... print("hello world")
-...
-\end{minted}
-```
-
-(latex with pythontex)
-```latex
-\begin{pycode}
-def hello():
- print("hello world")
-\end{pycode}
-```
-
-(markdown/rst in python docstrings)
-```python
-def f():
- """docstring here
-
- .. code-block:: python
-
- print("hello world")
-
- ```python
- print("hello world")
- ```
- """
-```
-
-## usage with pre-commit
-
-See [pre-commit](https://pre-commit.com) for instructions
-
-Sample `.pre-commit-config.yaml`:
-
-
-```yaml
-- repo: https://github.com/adamchainz/blacken-docs
- rev: v1.12.1
- hooks:
- - id: blacken-docs
- additional_dependencies: [black==...]
-```
-
-Since `black` is currently a moving target, it is suggested to pin `black`
-to a specific version using `additional_dependencies`.
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..9d1c78a
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,209 @@
+============
+blacken-docs
+============
+
+.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/blacken-docs/main.yml?branch=main&style=for-the-badge
+ :target: https://github.com/adamchainz/blacken-docs/actions?workflow=CI
+
+.. image:: https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge
+ :target: https://github.com/adamchainz/blacken-docs/actions?workflow=CI
+
+.. image:: https://img.shields.io/pypi/v/blacken-docs.svg?style=for-the-badge
+ :target: https://pypi.org/project/blacken-docs/
+
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge
+ :target: https://github.com/psf/black
+
+.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge
+ :target: https://github.com/pre-commit/pre-commit
+ :alt: pre-commit
+
+Run `Black `__ on Python code blocks in documentation files.
+
+Installation
+============
+
+Use **pip**:
+
+.. code-block:: sh
+
+ python -m pip install blacken-docs
+
+Python 3.7 to 3.11 supported.
+
+Black 22.1.0+ supported.
+
+pre-commit hook
+---------------
+
+You can also install blacken-docs as a `pre-commit `__ hook.
+Add the following to the ``repos`` section of your ``.pre-commit-config.yaml`` file (`docs `__):
+
+.. code-block:: yaml
+
+ - repo: https://github.com/adamchainz/blacken-docs
+ rev: "" # replace with latest tag on GitHub
+ hooks:
+ - id: blacken-docs
+ additional_dependencies:
+ - black==22.12.0
+
+Then, reformat your entire project:
+
+.. code-block:: sh
+
+ pre-commit run blacken-docs --all-files
+
+Since Black is a moving target, it’s best to pin it in ``additional_dependencies``.
+Upgrade as appropriate.
+
+Usage
+=====
+
+blacken-docs is a commandline tool that rewrites documentation files in place.
+It supports Markdown, reStructuredText, and LaTex files.
+Additionally, you can run it on Python files to reformat Markdown and reStructuredText within docstrings.
+
+Run ``blacken-docs`` with the filenames to rewrite:
+
+.. code-block:: sh
+
+ blacken-docs README.rst
+
+If any file is modified, ``blacken-docs`` exits nonzero.
+
+blacken-docs currently passes the following options through to Black:
+
+* ``-l`` / ``--line-length``
+* ``-t`` / ``--target-version``
+* ``-S`` / ``--skip-string-normalization``
+
+It also has the below extra options:
+
+* ``-E`` / ``--skip-errors`` - Don’t exit non-zero for errors from Black (normally syntax errors).
+* ``--rst-literal-blocks`` - Also format literal blocks in reStructuredText files (more below).
+
+History
+=======
+
+blacken-docs was created by `Anthony Sottile `__ in 2018.
+At the end of 2022, Adam Johnson took over maintenance.
+
+Supported code block formats
+============================
+
+blacken-docs formats code blocks matching the following patterns.
+
+Markdown
+--------
+
+In “python” blocks:
+
+.. code-block:: markdown
+
+ ```python
+ def hello():
+ print("hello world")
+ ```
+
+And “pycon” blocks:
+
+.. code-block:: markdown
+
+ ```pycon
+
+ >>> def hello():
+ ... print("hello world")
+ ...
+
+ ```
+
+Within Python files, docstrings that contain Markdown code blocks may be reformatted:
+
+.. code-block:: python
+
+ def f():
+ """docstring here
+
+ ```python
+ print("hello world")
+ ```
+ """
+
+reStructuredText
+----------------
+
+In “python” blocks:
+
+.. code-block:: rst
+
+ .. code-block:: python
+
+ def hello():
+ print("hello world")
+
+In “pycon” blocks:
+
+.. code-block:: rst
+
+ .. code-block:: pycon
+
+ >>> def hello():
+ ... print("hello world")
+ ...
+
+Use ``--rst-literal-blocks`` to also format `literal blocks `__:
+
+.. code-block:: rst
+
+ An example::
+
+ def hello():
+ print("hello world")
+
+Literal blocks are marked with ``::`` and can be any monospaced text by default.
+However Sphinx interprets them as Python code `by default `__.
+If your project uses Sphinx and such a configuration, add ``--rst-literal-blocks`` to also format such blocks.
+
+Within Python files, docstrings that contain reStructuredText code blocks may be reformatted:
+
+.. code-block:: python
+
+ def f():
+ """docstring here
+
+ .. code-block:: python
+
+ print("hello world")
+ """
+
+LaTeX
+-----
+
+In minted “python” blocks:
+
+.. code-block:: latex
+
+ \begin{minted}{python}
+ def hello():
+ print("hello world")
+ \end{minted}
+
+In minted “pycon” blocks:
+
+.. code-block:: latex
+
+ \begin{minted}{pycon}
+ >>> def hello():
+ ... print("hello world")
+ ...
+ \end{minted}
+
+In PythonTeX blocks:
+
+.. code-block:: latex
+
+ \begin{pycode}
+ def hello():
+ print("hello world")
+ \end{pycode}
diff --git a/setup.cfg b/setup.cfg
index 2141c5d..e981fbd 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -1,9 +1,9 @@
[metadata]
name = blacken_docs
version = 1.12.1
-description = Run `black` on python code blocks in documentation files
-long_description = file: README.md
-long_description_content_type = text/markdown
+description = Run Black on Python code blocks in documentation files.
+long_description = file: README.rst
+long_description_content_type = text/rst
url = https://github.com/asottile/blacken-docs
author = Anthony Sottile
author_email = asottile@umich.edu