Merge pull request #183491 from pennae/automatic-md-conversions

treewide: automatically md-convert option descriptions

18 files changed, 118 insertions, 118 deletions

diff --git a/nixos/modules/services/audio/alsa.nix b/nixos/modules/services/audio/alsa.nix
index 0d743ed31da8a..155780199fd64 100644
--- a/nixos/modules/services/audio/alsa.nix
+++ b/nixos/modules/services/audio/alsa.nix
@@ -25,7 +25,7 @@ in
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable ALSA sound.
         '';
       };
@@ -33,7 +33,7 @@ in
       enableOSSEmulation = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable ALSA OSS emulation (with certain cards sound mixing may not work!).
         '';
       };
@@ -44,7 +44,7 @@ in
         example = ''
           defaults.pcm.!card 3
         '';
-        description = ''
+        description = lib.mdDoc ''
           Set addition configuration for system-wide alsa.
         '';
       };
@@ -54,7 +54,7 @@ in
         enable = mkOption {
           type = types.bool;
           default = false;
-          description = ''
+          description = lib.mdDoc ''
             Whether to enable volume and capture control with keyboard media keys.
 
             You want to leave this disabled if you run a desktop environment
@@ -62,7 +62,7 @@ in
             You might want to enable this if you run a minimalistic desktop
             environment or work from bare linux ttys/framebuffers.
 
-            Enabling this will turn on <option>services.actkbd</option>.
+            Enabling this will turn on {option}`services.actkbd`.
           '';
         };
 
@@ -70,7 +70,7 @@ in
           type = types.str;
           default = "1";
           example = "1%";
-          description = ''
+          description = lib.mdDoc ''
             The value by which to increment/decrement volume on media keys.
 
             See amixer(1) for allowed values.
diff --git a/nixos/modules/services/audio/botamusique.nix b/nixos/modules/services/audio/botamusique.nix
index f4fa0ead4f055..edb59a49fd1fb 100644
--- a/nixos/modules/services/audio/botamusique.nix
+++ b/nixos/modules/services/audio/botamusique.nix
@@ -18,7 +18,7 @@ in
       type = types.package;
       default = pkgs.botamusique;
       defaultText = literalExpression "pkgs.botamusique";
-      description = "The botamusique package to use.";
+      description = lib.mdDoc "The botamusique package to use.";
     };
 
     settings = mkOption {
@@ -29,32 +29,32 @@ in
             type = types.str;
             default = "localhost";
             example = "mumble.example.com";
-            description = "Hostname of the mumble server to connect to.";
+            description = lib.mdDoc "Hostname of the mumble server to connect to.";
           };
 
           server.port = mkOption {
             type = types.port;
             default = 64738;
-            description = "Port of the mumble server to connect to.";
+            description = lib.mdDoc "Port of the mumble server to connect to.";
           };
 
           bot.username = mkOption {
             type = types.str;
             default = "botamusique";
-            description = "Name the bot should appear with.";
+            description = lib.mdDoc "Name the bot should appear with.";
           };
 
           bot.comment = mkOption {
             type = types.str;
             default = "Hi, I'm here to play radio, local music or youtube/soundcloud music. Have fun!";
-            description = "Comment displayed for the bot.";
+            description = lib.mdDoc "Comment displayed for the bot.";
           };
         };
       };
       default = {};
-      description = ''
-        Your <filename>configuration.ini</filename> as a Nix attribute set. Look up
-        possible options in the <link xlink:href="https://github.com/azlux/botamusique/blob/master/configuration.example.ini">configuration.example.ini</link>.
+      description = lib.mdDoc ''
+        Your {file}`configuration.ini` as a Nix attribute set. Look up
+        possible options in the [configuration.example.ini](https://github.com/azlux/botamusique/blob/master/configuration.example.ini).
       '';
     };
   };
diff --git a/nixos/modules/services/audio/hqplayerd.nix b/nixos/modules/services/audio/hqplayerd.nix
index 822a8abef2439..4045a34b40df0 100644
--- a/nixos/modules/services/audio/hqplayerd.nix
+++ b/nixos/modules/services/audio/hqplayerd.nix
@@ -18,7 +18,7 @@ in
         username = mkOption {
           type = types.nullOr types.str;
           default = null;
-          description = ''
+          description = lib.mdDoc ''
             Username used for HQPlayer's WebUI.
 
             Without this you will need to manually create the credentials after
@@ -29,7 +29,7 @@ in
         password = mkOption {
           type = types.nullOr types.str;
           default = null;
-          description = ''
+          description = lib.mdDoc ''
             Password used for HQPlayer's WebUI.
 
             Without this you will need to manually create the credentials after
@@ -41,7 +41,7 @@ in
       licenseFile = mkOption {
         type = types.nullOr types.path;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Path to the HQPlayer license key file.
 
           Without this, the service will run in trial mode and restart every 30
@@ -52,7 +52,7 @@ in
       openFirewall = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Opens ports needed for the WebUI and controller API.
         '';
       };
@@ -60,7 +60,7 @@ in
       config = mkOption {
         type = types.nullOr types.lines;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           HQplayer daemon configuration, written to /etc/hqplayer/hqplayerd.xml.
 
           Refer to share/doc/hqplayerd/readme.txt in the hqplayerd derivation for possible values.
diff --git a/nixos/modules/services/audio/icecast.nix b/nixos/modules/services/audio/icecast.nix
index 5ee5bd745f96e..0a81d71b56908 100644
--- a/nixos/modules/services/audio/icecast.nix
+++ b/nixos/modules/services/audio/icecast.nix
@@ -48,7 +48,7 @@ in {
 
       hostname = mkOption {
         type = types.nullOr types.str;
-        description = "DNS name or IP address that will be used for the stream directory lookups or possibily the playlist generation if a Host header is not provided.";
+        description = lib.mdDoc "DNS name or IP address that will be used for the stream directory lookups or possibily the playlist generation if a Host header is not provided.";
         default = config.networking.domain;
         defaultText = literalExpression "config.networking.domain";
       };
@@ -56,51 +56,51 @@ in {
       admin = {
         user = mkOption {
           type = types.str;
-          description = "Username used for all administration functions.";
+          description = lib.mdDoc "Username used for all administration functions.";
           default = "admin";
         };
 
         password = mkOption {
           type = types.str;
-          description = "Password used for all administration functions.";
+          description = lib.mdDoc "Password used for all administration functions.";
         };
       };
 
       logDir = mkOption {
         type = types.path;
-        description = "Base directory used for logging.";
+        description = lib.mdDoc "Base directory used for logging.";
         default = "/var/log/icecast";
       };
 
       listen = {
         port = mkOption {
           type = types.int;
-          description = "TCP port that will be used to accept client connections.";
+          description = lib.mdDoc "TCP port that will be used to accept client connections.";
           default = 8000;
         };
 
         address = mkOption {
           type = types.str;
-          description = "Address Icecast will listen on.";
+          description = lib.mdDoc "Address Icecast will listen on.";
           default = "::";
         };
       };
 
       user = mkOption {
         type = types.str;
-        description = "User privileges for the server.";
+        description = lib.mdDoc "User privileges for the server.";
         default = "nobody";
       };
 
       group = mkOption {
         type = types.str;
-        description = "Group privileges for the server.";
+        description = lib.mdDoc "Group privileges for the server.";
         default = "nogroup";
       };
 
       extraConf = mkOption {
         type = types.lines;
-        description = "icecast.xml content.";
+        description = lib.mdDoc "icecast.xml content.";
         default = "";
       };
 
diff --git a/nixos/modules/services/audio/jack.nix b/nixos/modules/services/audio/jack.nix
index 84fc9957b879f..ae566bba84e4f 100644
--- a/nixos/modules/services/audio/jack.nix
+++ b/nixos/modules/services/audio/jack.nix
@@ -40,14 +40,14 @@ in {
           example = literalExpression ''
             [ "-dalsa" "--device" "hw:1" ];
           '';
-          description = ''
+          description = lib.mdDoc ''
             Specifies startup command line arguments to pass to JACK server.
           '';
         };
 
         session = mkOption {
           type = types.lines;
-          description = ''
+          description = lib.mdDoc ''
             Commands to run after JACK is started.
           '';
         };
@@ -58,7 +58,7 @@ in {
         enable = mkOption {
           type = types.bool;
           default = true;
-          description = ''
+          description = lib.mdDoc ''
             Route audio to/from generic ALSA-using applications using ALSA JACK PCM plugin.
           '';
         };
@@ -66,7 +66,7 @@ in {
         support32Bit = mkOption {
           type = types.bool;
           default = false;
-          description = ''
+          description = lib.mdDoc ''
             Whether to support sound for 32-bit ALSA applications on 64-bit system.
           '';
         };
@@ -76,7 +76,7 @@ in {
         enable = mkOption {
           type = types.bool;
           default = false;
-          description = ''
+          description = lib.mdDoc ''
             Create ALSA loopback device, instead of using PCM plugin. Has broader
             application support (things like Steam will work), but may need fine-tuning
             for concrete hardware.
@@ -86,14 +86,14 @@ in {
         index = mkOption {
           type = types.int;
           default = 10;
-          description = ''
+          description = lib.mdDoc ''
             Index of an ALSA loopback device.
           '';
         };
 
         config = mkOption {
           type = types.lines;
-          description = ''
+          description = lib.mdDoc ''
             ALSA config for loopback device.
           '';
         };
@@ -105,7 +105,7 @@ in {
             period_size 2048
             periods 2
           '';
-          description = ''
+          description = lib.mdDoc ''
             For music production software that still doesn't support JACK natively you
             would like to put buffer/period adjustments here
             to decrease dmix device latency.
@@ -114,7 +114,7 @@ in {
 
         session = mkOption {
           type = types.lines;
-          description = ''
+          description = lib.mdDoc ''
             Additional commands to run to setup loopback device.
           '';
         };
diff --git a/nixos/modules/services/audio/jmusicbot.nix b/nixos/modules/services/audio/jmusicbot.nix
index e0f8d461af076..7e23ffe6bf2c0 100644
--- a/nixos/modules/services/audio/jmusicbot.nix
+++ b/nixos/modules/services/audio/jmusicbot.nix
@@ -13,12 +13,12 @@ in
         type = types.package;
         default = pkgs.jmusicbot;
         defaultText = literalExpression "pkgs.jmusicbot";
-        description = "JMusicBot package to use";
+        description = lib.mdDoc "JMusicBot package to use";
       };
 
       stateDir = mkOption {
         type = types.path;
-        description = ''
+        description = lib.mdDoc ''
           The directory where config.txt and serversettings.json is saved.
           If left as the default value this directory will automatically be created before JMusicBot starts, otherwise the sysadmin is responsible for ensuring the directory exists with appropriate ownership and permissions.
           Untouched by the value of this option config.txt needs to be placed manually into this directory.
diff --git a/nixos/modules/services/audio/liquidsoap.nix b/nixos/modules/services/audio/liquidsoap.nix
index ffeefc0f988e1..c313104c46096 100644
--- a/nixos/modules/services/audio/liquidsoap.nix
+++ b/nixos/modules/services/audio/liquidsoap.nix
@@ -31,7 +31,7 @@ in
     services.liquidsoap.streams = mkOption {
 
       description =
-        ''
+        lib.mdDoc ''
           Set of Liquidsoap streams to start,
           one systemd service per stream.
         '';
diff --git a/nixos/modules/services/audio/mopidy.nix b/nixos/modules/services/audio/mopidy.nix
index 9937feadaeb6b..9c8e9b693c3f7 100644
--- a/nixos/modules/services/audio/mopidy.nix
+++ b/nixos/modules/services/audio/mopidy.nix
@@ -31,7 +31,7 @@ in {
       dataDir = mkOption {
         default = "/var/lib/mopidy";
         type = types.str;
-        description = ''
+        description = lib.mdDoc ''
           The directory where Mopidy stores its state.
         '';
       };
@@ -40,7 +40,7 @@ in {
         default = [];
         type = types.listOf types.package;
         example = literalExpression "[ pkgs.mopidy-spotify ]";
-        description = ''
+        description = lib.mdDoc ''
           Mopidy extensions that should be loaded by the service.
         '';
       };
@@ -48,7 +48,7 @@ in {
       configuration = mkOption {
         default = "";
         type = types.lines;
-        description = ''
+        description = lib.mdDoc ''
           The configuration that Mopidy should use.
         '';
       };
@@ -56,7 +56,7 @@ in {
       extraConfigFiles = mkOption {
         default = [];
         type = types.listOf types.str;
-        description = ''
+        description = lib.mdDoc ''
           Extra config file read by Mopidy when the service starts.
           Later files in the list overrides earlier configuration.
         '';
diff --git a/nixos/modules/services/audio/mpd.nix b/nixos/modules/services/audio/mpd.nix
index 11733d99fca65..bbfccec98c4af 100644
--- a/nixos/modules/services/audio/mpd.nix
+++ b/nixos/modules/services/audio/mpd.nix
@@ -56,7 +56,7 @@ in {
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable MPD, the music player daemon.
         '';
       };
@@ -64,8 +64,8 @@ in {
       startWhenNeeded = mkOption {
         type = types.bool;
         default = false;
-        description = ''
-          If set, <command>mpd</command> is socket-activated; that
+        description = lib.mdDoc ''
+          If set, {command}`mpd` is socket-activated; that
           is, instead of having it permanently running as a daemon,
           systemd will start it on the first incoming connection.
         '';
@@ -75,7 +75,7 @@ in {
         type = with types; either path (strMatching "(http|https|nfs|smb)://.+");
         default = "${cfg.dataDir}/music";
         defaultText = literalExpression ''"''${dataDir}/music"'';
-        description = ''
+        description = lib.mdDoc ''
           The directory or NFS/SMB network share where MPD reads music from. If left
           as the default value this directory will automatically be created before
           the MPD server starts, otherwise the sysadmin is responsible for ensuring
@@ -87,7 +87,7 @@ in {
         type = types.path;
         default = "${cfg.dataDir}/playlists";
         defaultText = literalExpression ''"''${dataDir}/playlists"'';
-        description = ''
+        description = lib.mdDoc ''
           The directory where MPD stores playlists. If left as the default value
           this directory will automatically be created before the MPD server starts,
           otherwise the sysadmin is responsible for ensuring the directory exists
@@ -98,18 +98,18 @@ in {
       extraConfig = mkOption {
         type = types.lines;
         default = "";
-        description = ''
+        description = lib.mdDoc ''
           Extra directives added to to the end of MPD's configuration file,
           mpd.conf. Basic configuration like file location and uid/gid
           is added automatically to the beginning of the file. For available
-          options see <literal>man 5 mpd.conf</literal>'.
+          options see `man 5 mpd.conf`'.
         '';
       };
 
       dataDir = mkOption {
         type = types.path;
         default = "/var/lib/${name}";
-        description = ''
+        description = lib.mdDoc ''
           The directory where MPD stores its state, tag cache, playlists etc. If
           left as the default value this directory will automatically be created
           before the MPD server starts, otherwise the sysadmin is responsible for
@@ -120,13 +120,13 @@ in {
       user = mkOption {
         type = types.str;
         default = name;
-        description = "User account under which MPD runs.";
+        description = lib.mdDoc "User account under which MPD runs.";
       };
 
       group = mkOption {
         type = types.str;
         default = name;
-        description = "Group account under which MPD runs.";
+        description = lib.mdDoc "Group account under which MPD runs.";
       };
 
       network = {
@@ -135,16 +135,16 @@ in {
           type = types.str;
           default = "127.0.0.1";
           example = "any";
-          description = ''
+          description = lib.mdDoc ''
             The address for the daemon to listen on.
-            Use <literal>any</literal> to listen on all addresses.
+            Use `any` to listen on all addresses.
           '';
         };
 
         port = mkOption {
           type = types.int;
           default = 6600;
-          description = ''
+          description = lib.mdDoc ''
             This setting is the TCP port that is desired for the daemon to get assigned
             to.
           '';
@@ -156,8 +156,8 @@ in {
         type = types.nullOr types.str;
         default = "${cfg.dataDir}/tag_cache";
         defaultText = literalExpression ''"''${dataDir}/tag_cache"'';
-        description = ''
-          The path to MPD's database. If set to <literal>null</literal> the
+        description = lib.mdDoc ''
+          The path to MPD's database. If set to `null` the
           parameter is omitted from the configuration.
         '';
       };
@@ -167,7 +167,7 @@ in {
           options = {
             passwordFile = mkOption {
               type = types.path;
-              description = ''
+              description = lib.mdDoc ''
                 Path to file containing the password.
               '';
             };
@@ -176,14 +176,14 @@ in {
             in mkOption {
               type = types.listOf (types.enum perms);
               default = [ "read" ];
-              description = ''
+              description = lib.mdDoc ''
                 List of permissions that are granted with this password.
                 Permissions can be "${concatStringsSep "\", \"" perms}".
               '';
             };
           };
         });
-        description = ''
+        description = lib.mdDoc ''
           Credentials and permissions for accessing the mpd server.
         '';
         default = [];
@@ -196,7 +196,7 @@ in {
       fluidsynth = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           If set, add fluidsynth soundfont and configure the plugin.
         '';
       };
diff --git a/nixos/modules/services/audio/mpdscribble.nix b/nixos/modules/services/audio/mpdscribble.nix
index 333ffb709410a..d829bc7ae0d01 100644
--- a/nixos/modules/services/audio/mpdscribble.nix
+++ b/nixos/modules/services/audio/mpdscribble.nix
@@ -82,7 +82,7 @@ in {
     proxy = mkOption {
       default = null;
       type = types.nullOr types.str;
-      description = ''
+      description = lib.mdDoc ''
         HTTP proxy URL.
       '';
     };
@@ -90,7 +90,7 @@ in {
     verbose = mkOption {
       default = 1;
       type = types.int;
-      description = ''
+      description = lib.mdDoc ''
         Log level for the mpdscribble daemon.
       '';
     };
@@ -99,7 +99,7 @@ in {
       default = 600;
       example = 60;
       type = types.int;
-      description = ''
+      description = lib.mdDoc ''
         How often should mpdscribble save the journal file? [seconds]
       '';
     };
@@ -115,7 +115,7 @@ in {
         else "localhost"
       '';
       type = types.str;
-      description = ''
+      description = lib.mdDoc ''
         Host for the mpdscribble daemon to search for a mpd daemon on.
       '';
     };
@@ -133,9 +133,9 @@ in {
         otherwise <literal>null</literal>.
       '';
       type = types.nullOr types.str;
-      description = ''
+      description = lib.mdDoc ''
         File containing the password for the mpd daemon.
-        If there is a local mpd configured using <option>services.mpd.credentials</option>
+        If there is a local mpd configured using {option}`services.mpd.credentials`
         the default is automatically set to a matching passwordFile of the local mpd.
       '';
     };
@@ -144,7 +144,7 @@ in {
       default = mpdCfg.network.port;
       defaultText = literalExpression "config.${mpdOpt.network.port}";
       type = types.port;
-      description = ''
+      description = lib.mdDoc ''
         Port for the mpdscribble daemon to search for a mpd daemon on.
       '';
     };
@@ -157,18 +157,18 @@ in {
               type = types.str;
               default = endpointUrls.${name} or "";
               description =
-                "The url endpoint where the scrobble API is listening.";
+                lib.mdDoc "The url endpoint where the scrobble API is listening.";
             };
             username = mkOption {
               type = types.str;
-              description = ''
+              description = lib.mdDoc ''
                 Username for the scrobble service.
               '';
             };
             passwordFile = mkOption {
               type = types.nullOr types.str;
               description =
-                "File containing the password, either as MD5SUM or cleartext.";
+                lib.mdDoc "File containing the password, either as MD5SUM or cleartext.";
             };
           };
         };
@@ -180,7 +180,7 @@ in {
           passwordFile = "/run/secrets/lastfm_password";
         };
       };
-      description = ''
+      description = lib.mdDoc ''
         Endpoints to scrobble to.
         If the endpoint is one of "${
           concatStringsSep "\", \"" (attrNames endpointUrls)
diff --git a/nixos/modules/services/audio/navidrome.nix b/nixos/modules/services/audio/navidrome.nix
index 319212c020777..a7c8953f5107e 100644
--- a/nixos/modules/services/audio/navidrome.nix
+++ b/nixos/modules/services/audio/navidrome.nix
@@ -21,8 +21,8 @@ in {
         example = {
           MusicFolder = "/mnt/music";
         };
-        description = ''
-          Configuration for Navidrome, see <link xlink:href="https://www.navidrome.org/docs/usage/configuration-options/"/> for supported values.
+        description = lib.mdDoc ''
+          Configuration for Navidrome, see <https://www.navidrome.org/docs/usage/configuration-options/> for supported values.
         '';
       };
 
diff --git a/nixos/modules/services/audio/roon-bridge.nix b/nixos/modules/services/audio/roon-bridge.nix
index e08f8a4f9e7a0..9a9a6479efc8c 100644
--- a/nixos/modules/services/audio/roon-bridge.nix
+++ b/nixos/modules/services/audio/roon-bridge.nix
@@ -12,21 +12,21 @@ in {
       openFirewall = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Open ports in the firewall for the bridge.
         '';
       };
       user = mkOption {
         type = types.str;
         default = "roon-bridge";
-        description = ''
+        description = lib.mdDoc ''
           User to run the Roon bridge as.
         '';
       };
       group = mkOption {
         type = types.str;
         default = "roon-bridge";
-        description = ''
+        description = lib.mdDoc ''
           Group to run the Roon Bridge as.
         '';
       };
diff --git a/nixos/modules/services/audio/roon-server.nix b/nixos/modules/services/audio/roon-server.nix
index c8a2071c15592..535950f75656f 100644
--- a/nixos/modules/services/audio/roon-server.nix
+++ b/nixos/modules/services/audio/roon-server.nix
@@ -12,21 +12,21 @@ in {
       openFirewall = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Open ports in the firewall for the server.
         '';
       };
       user = mkOption {
         type = types.str;
         default = "roon-server";
-        description = ''
+        description = lib.mdDoc ''
           User to run the Roon Server as.
         '';
       };
       group = mkOption {
         type = types.str;
         default = "roon-server";
-        description = ''
+        description = lib.mdDoc ''
           Group to run the Roon Server as.
         '';
       };
diff --git a/nixos/modules/services/audio/slimserver.nix b/nixos/modules/services/audio/slimserver.nix
index ecd2652849909..9fbc68b71364e 100644
--- a/nixos/modules/services/audio/slimserver.nix
+++ b/nixos/modules/services/audio/slimserver.nix
@@ -14,7 +14,7 @@ in {
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable slimserver.
         '';
       };
@@ -23,13 +23,13 @@ in {
         type = types.package;
         default = pkgs.slimserver;
         defaultText = literalExpression "pkgs.slimserver";
-        description = "Slimserver package to use.";
+        description = lib.mdDoc "Slimserver package to use.";
       };
 
       dataDir = mkOption {
         type = types.path;
         default = "/var/lib/slimserver";
-        description = ''
+        description = lib.mdDoc ''
           The directory where slimserver stores its state, tag cache,
           playlists etc.
         '';
diff --git a/nixos/modules/services/audio/snapserver.nix b/nixos/modules/services/audio/snapserver.nix
index 91d97a0b551e2..fdc1f605bb32a 100644
--- a/nixos/modules/services/audio/snapserver.nix
+++ b/nixos/modules/services/audio/snapserver.nix
@@ -12,7 +12,7 @@ let
   sampleFormat = mkOption {
     type = with types; nullOr str;
     default = null;
-    description = ''
+    description = lib.mdDoc ''
       Default sample format.
     '';
     example = "48000:16:2";
@@ -21,7 +21,7 @@ let
   codec = mkOption {
     type = with types; nullOr str;
     default = null;
-    description = ''
+    description = lib.mdDoc ''
       Default audio compression method.
     '';
     example = "flac";
@@ -77,7 +77,7 @@ in {
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable snapserver.
         '';
       };
@@ -86,7 +86,7 @@ in {
         type = types.str;
         default = "::";
         example = "0.0.0.0";
-        description = ''
+        description = lib.mdDoc ''
           The address where snapclients can connect.
         '';
       };
@@ -94,7 +94,7 @@ in {
       port = mkOption {
         type = types.port;
         default = 1704;
-        description = ''
+        description = lib.mdDoc ''
           The port that snapclients can connect to.
         '';
       };
@@ -104,7 +104,7 @@ in {
         # Make the behavior consistent with other services. Set the default to
         # false and remove the accompanying warning after NixOS 22.05 is released.
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Whether to automatically open the specified ports in the firewall.
         '';
       };
@@ -115,7 +115,7 @@ in {
       streamBuffer = mkOption {
         type = with types; nullOr int;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Stream read (input) buffer in ms.
         '';
         example = 20;
@@ -124,7 +124,7 @@ in {
       buffer = mkOption {
         type = with types; nullOr int;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Network buffer in ms.
         '';
         example = 1000;
@@ -133,7 +133,7 @@ in {
       sendToMuted = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Send audio to muted clients.
         '';
       };
@@ -141,7 +141,7 @@ in {
       tcp.enable = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable the JSON-RPC via TCP.
         '';
       };
@@ -150,7 +150,7 @@ in {
         type = types.str;
         default = "::";
         example = "0.0.0.0";
-        description = ''
+        description = lib.mdDoc ''
           The address where the TCP JSON-RPC listens on.
         '';
       };
@@ -158,7 +158,7 @@ in {
       tcp.port = mkOption {
         type = types.port;
         default = 1705;
-        description = ''
+        description = lib.mdDoc ''
           The port where the TCP JSON-RPC listens on.
         '';
       };
@@ -166,7 +166,7 @@ in {
       http.enable = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable the JSON-RPC via HTTP.
         '';
       };
@@ -175,7 +175,7 @@ in {
         type = types.str;
         default = "::";
         example = "0.0.0.0";
-        description = ''
+        description = lib.mdDoc ''
           The address where the HTTP JSON-RPC listens on.
         '';
       };
@@ -183,7 +183,7 @@ in {
       http.port = mkOption {
         type = types.port;
         default = 1780;
-        description = ''
+        description = lib.mdDoc ''
           The port where the HTTP JSON-RPC listens on.
         '';
       };
@@ -191,7 +191,7 @@ in {
       http.docRoot = mkOption {
         type = with types; nullOr path;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Path to serve from the HTTP servers root.
         '';
       };
@@ -201,12 +201,12 @@ in {
           options = {
             location = mkOption {
               type = types.oneOf [ types.path types.str ];
-              description = ''
-                For type <literal>pipe</literal> or <literal>file</literal>, the path to the pipe or file.
-                For type <literal>librespot</literal>, <literal>airplay</literal> or <literal>process</literal>, the path to the corresponding binary.
-                For type <literal>tcp</literal>, the <literal>host:port</literal> address to connect to or listen on.
-                For type <literal>meta</literal>, a list of stream names in the form <literal>/one/two/...</literal>. Don't forget the leading slash.
-                For type <literal>alsa</literal>, use an empty string.
+              description = lib.mdDoc ''
+                For type `pipe` or `file`, the path to the pipe or file.
+                For type `librespot`, `airplay` or `process`, the path to the corresponding binary.
+                For type `tcp`, the `host:port` address to connect to or listen on.
+                For type `meta`, a list of stream names in the form `/one/two/...`. Don't forget the leading slash.
+                For type `alsa`, use an empty string.
               '';
               example = literalExpression ''
                 "/path/to/pipe"
@@ -218,14 +218,14 @@ in {
             type = mkOption {
               type = types.enum [ "pipe" "librespot" "airplay" "file" "process" "tcp" "alsa" "spotify" "meta" ];
               default = "pipe";
-              description = ''
+              description = lib.mdDoc ''
                 The type of input stream.
               '';
             };
             query = mkOption {
               type = attrsOf str;
               default = {};
-              description = ''
+              description = lib.mdDoc ''
                 Key-value pairs that convey additional parameters about a stream.
               '';
               example = literalExpression ''
@@ -253,7 +253,7 @@ in {
           };
         });
         default = { default = {}; };
-        description = ''
+        description = lib.mdDoc ''
           The definition for an input source.
         '';
         example = literalExpression ''
diff --git a/nixos/modules/services/audio/spotifyd.nix b/nixos/modules/services/audio/spotifyd.nix
index 22848ed98000d..87ee083e74b7d 100644
--- a/nixos/modules/services/audio/spotifyd.nix
+++ b/nixos/modules/services/audio/spotifyd.nix
@@ -22,9 +22,9 @@ in
       config = mkOption {
         default = "";
         type = types.lines;
-        description = ''
+        description = lib.mdDoc ''
           (Deprecated) Configuration for Spotifyd. For syntax and directives, see
-          <link xlink:href="https://github.com/Spotifyd/spotifyd#Configuration"/>.
+          <https://github.com/Spotifyd/spotifyd#Configuration>.
         '';
       };
 
@@ -32,9 +32,9 @@ in
         default = {};
         type = toml.type;
         example = { global.bitrate = 320; };
-        description = ''
+        description = lib.mdDoc ''
           Configuration for Spotifyd. For syntax and directives, see
-          <link xlink:href="https://github.com/Spotifyd/spotifyd#Configuration"/>.
+          <https://github.com/Spotifyd/spotifyd#Configuration>.
         '';
       };
     };
diff --git a/nixos/modules/services/audio/squeezelite.nix b/nixos/modules/services/audio/squeezelite.nix
index 36295e21c60f9..767eeda177f3c 100644
--- a/nixos/modules/services/audio/squeezelite.nix
+++ b/nixos/modules/services/audio/squeezelite.nix
@@ -21,7 +21,7 @@ in
     extraArguments = mkOption {
       default = "";
       type = types.str;
-      description = ''
+      description = lib.mdDoc ''
         Additional command line arguments to pass to Squeezelite.
       '';
     };
diff --git a/nixos/modules/services/audio/ympd.nix b/nixos/modules/services/audio/ympd.nix
index 84b72d1425132..98522f2542396 100644
--- a/nixos/modules/services/audio/ympd.nix
+++ b/nixos/modules/services/audio/ympd.nix
@@ -17,7 +17,7 @@ in {
       webPort = mkOption {
         type = types.either types.str types.port; # string for backwards compat
         default = "8080";
-        description = "The port where ympd's web interface will be available.";
+        description = lib.mdDoc "The port where ympd's web interface will be available.";
         example = "ssl://8080:/path/to/ssl-private-key.pem";
       };
 
@@ -25,14 +25,14 @@ in {
         host = mkOption {
           type = types.str;
           default = "localhost";
-          description = "The host where MPD is listening.";
+          description = lib.mdDoc "The host where MPD is listening.";
         };
 
         port = mkOption {
           type = types.int;
           default = config.services.mpd.network.port;
           defaultText = literalExpression "config.services.mpd.network.port";
-          description = "The port where MPD is listening.";
+          description = lib.mdDoc "The port where MPD is listening.";
           example = 6600;
         };
       };