diff --git a/docs/plugins/discogs.rst b/docs/plugins/discogs.rst
index a9125e737..17a1645bb 100644
--- a/docs/plugins/discogs.rst
+++ b/docs/plugins/discogs.rst
@@ -11,9 +11,11 @@ Installation
 ------------
 
 To use the ``discogs`` plugin, first enable it in your configuration (see
-:ref:`using-plugins`). Then, install the `python3-discogs-client`_ library by typing::
+:ref:`using-plugins`). Then, install the `python3-discogs-client`_ library by typing:
 
-    pip install python3-discogs-client
+.. code-block:: console
+
+    $ pip install python3-discogs-client
 
 You will also need to register for a `Discogs`_ account, and provide
 authentication credentials via a personal access token or an OAuth2
@@ -39,11 +41,19 @@ Authentication via Personal Access Token
 As an alternative to OAuth, you can get a token from Discogs and add it to
 your configuration.
 To get a personal access token (called a "user token" in the `python3-discogs-client`_
-documentation), login to `Discogs`_, and visit the
-`Developer settings page
-<https://www.discogs.com/settings/developers>`_. Press the ``Generate new
-token`` button, and place the generated token in your configuration, as the
-``user_token`` config option in the ``discogs`` section.
+documentation):
+
+#. login to `Discogs`_;
+#. visit the `Developer settings page <https://www.discogs.com/settings/developers>`_;
+#. press the *Generate new token* button;
+#. copy the generated token;
+#. place it in your configuration in the ``discogs`` section as the ``user_token`` option:
+
+   .. code-block:: yaml
+
+      discogs:
+          user_token: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+
 
 Configuration
 -------------
@@ -54,22 +64,30 @@ There is one additional option in the ``discogs:`` section, ``index_tracks``.
 Index tracks (see the `Discogs guidelines
 <https://support.discogs.com/hc/en-us/articles/360005055373-Database-Guidelines-12-Tracklisting#Index_Tracks_And_Headings>`_),
 along with headers, mark divisions between distinct works on the same release
-or within works. When ``index_tracks`` is enabled::
+or within works. When ``index_tracks`` is enabled:
+
+.. code-block:: yaml
 
     discogs:
         index_tracks: yes
 
 beets will incorporate the names of the divisions containing each track into
-the imported track's title. For example, importing
+the imported track's title.
+
+For example, importing
 `this album
 <https://www.discogs.com/Handel-Sutherland-Kirkby-Kwella-Nelson-Watkinson-Bowman-Rolfe-Johnson-Elliott-Partridge-Thomas-The-A/release/2026070>`_
-would result in track names like::
+would result in track names like:
+
+.. code-block:: text
 
     Messiah, Part I: No.1: Sinfony
     Messiah, Part II: No.22: Chorus- Behold The Lamb Of God
     Athalia, Act I, Scene I: Sinfonia
 
-whereas with ``index_tracks`` disabled you'd get::
+whereas with ``index_tracks`` disabled you'd get:
+
+.. code-block:: text
 
     No.1: Sinfony
     No.22: Chorus- Behold The Lamb Of God
@@ -81,7 +99,7 @@ Other configurations available under ``discogs:`` are:
 
 - **append_style_genre**: Appends the Discogs style (if found) to the genre tag. This can be useful if you want more granular genres to categorize your music.
   For example, a release in Discogs might have a genre of "Electronic" and a style of "Techno": enabling this setting would set the genre to be "Electronic, Techno" (assuming default separator of ``", "``) instead of just "Electronic".
-  Default: ``false``
+  Default: ``False``
 - **separator**: How to join multiple genre and style values from Discogs into a string.
   Default: ``", "``