diff --git a/docs/option-decorators.rst b/docs/option-decorators.md
similarity index 69%
rename from docs/option-decorators.rst
rename to docs/option-decorators.md
index 208b193f1..37a426dd4 100644
--- a/docs/option-decorators.rst
+++ b/docs/option-decorators.md
@@ -1,20 +1,22 @@
-Options Shortcut Decorators
-===========================
+# Options Shortcut Decorators
 
-.. currentmodule:: click
+```{currentmodule} click
+```
 
 For convenience commonly used combinations of options arguments are available as their own decorators.
 
-.. contents::
-    :depth: 2
-    :local:
+```{contents}
+---
+depth: 2
+local: true
+---
+```
 
-Password Option
-------------------
+## Password Option
 
-Click supports hidden prompts and asking for confirmation.  This is
-useful for password input:
+Click supports hidden prompts and asking for confirmation. This is useful for password input:
 
+```{eval-rst}
 .. click:example::
 
     import codecs
@@ -30,25 +32,24 @@ useful for password input:
 .. click:run::
 
     invoke(encode, input=['secret', 'secret'])
+```
 
 Because this combination of parameters is quite common, this can also be
-replaced with the :func:`password_option` decorator:
-
-.. code-block:: python
+replaced with the {func}`password_option` decorator:
 
+```python
     @click.command()
     @click.password_option()
     def encrypt(password):
         click.echo(f"encoded: to {codecs.encode(password, 'rot13')}")
+```
 
-Confirmation Option
---------------------
+## Confirmation Option
 
-For dangerous operations, it's very useful to be able to ask a user for
-confirmation.  This can be done by adding a boolean ``--yes`` flag and
-asking for confirmation if the user did not provide it and to fail in a
-callback:
+For dangerous operations, it's very useful to be able to ask a user for confirmation. This can be done by adding a
+boolean `--yes` flag and asking for confirmation if the user did not provide it and to fail in a callback:
 
+```{eval-rst}
 .. click:example::
 
     def abort_if_false(ctx, param, value):
@@ -78,7 +79,8 @@ replaced with the :func:`confirmation_option` decorator:
     @click.confirmation_option(prompt='Are you sure you want to drop the db?')
     def dropdb():
         click.echo('Dropped all tables!')
+```
+
+## Version Option
 
-Version Option
-----------------
-:func:`version_option` adds a ``--version`` option which immediately prints the version number and exits the program.
+{func}`version_option` adds a `--version` option which immediately prints the version number and exits the program.