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

treewide: automatically md-convert option descriptions

37 files changed, 117 insertions, 117 deletions

diff --git a/nixos/modules/hardware/acpilight.nix b/nixos/modules/hardware/acpilight.nix
index 2de448a265c..d8d82b0e81a 100644
--- a/nixos/modules/hardware/acpilight.nix
+++ b/nixos/modules/hardware/acpilight.nix
@@ -10,7 +10,7 @@ in
       enable = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Enable acpilight.
           This will allow brightness control via xbacklight from users in the video group
         '';
diff --git a/nixos/modules/hardware/all-firmware.nix b/nixos/modules/hardware/all-firmware.nix
index bd5540646b0..2d5a0007ff0 100644
--- a/nixos/modules/hardware/all-firmware.nix
+++ b/nixos/modules/hardware/all-firmware.nix
@@ -21,7 +21,7 @@ in {
     hardware.enableAllFirmware = mkOption {
       default = false;
       type = types.bool;
-      description = ''
+      description = lib.mdDoc ''
         Turn on this option if you want to enable all the firmware.
       '';
     };
@@ -30,7 +30,7 @@ in {
       default = config.hardware.enableAllFirmware;
       defaultText = lib.literalExpression "config.hardware.enableAllFirmware";
       type = types.bool;
-      description = ''
+      description = lib.mdDoc ''
         Turn on this option if you want to enable all the firmware with a license allowing redistribution.
       '';
     };
@@ -38,7 +38,7 @@ in {
     hardware.wirelessRegulatoryDatabase = mkOption {
       default = false;
       type = types.bool;
-      description = ''
+      description = lib.mdDoc ''
         Load the wireless regulatory database at boot.
       '';
     };
diff --git a/nixos/modules/hardware/bladeRF.nix b/nixos/modules/hardware/bladeRF.nix
index 35b74b8382e..52a1f52024c 100644
--- a/nixos/modules/hardware/bladeRF.nix
+++ b/nixos/modules/hardware/bladeRF.nix
@@ -12,7 +12,7 @@ in
     enable = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Enables udev rules for BladeRF devices. By default grants access
         to users in the "bladerf" group. You may want to install the
         libbladeRF package.
diff --git a/nixos/modules/hardware/ckb-next.nix b/nixos/modules/hardware/ckb-next.nix
index 751ed663aab..287d287a775 100644
--- a/nixos/modules/hardware/ckb-next.nix
+++ b/nixos/modules/hardware/ckb-next.nix
@@ -19,7 +19,7 @@ in
         type = types.nullOr types.int;
         default = null;
         example = 100;
-        description = ''
+        description = lib.mdDoc ''
           Limit access to the ckb daemon to a particular group.
         '';
       };
@@ -28,7 +28,7 @@ in
         type = types.package;
         default = pkgs.ckb-next;
         defaultText = literalExpression "pkgs.ckb-next";
-        description = ''
+        description = lib.mdDoc ''
           The package implementing the Corsair keyboard/mouse driver.
         '';
       };
diff --git a/nixos/modules/hardware/cpu/amd-microcode.nix b/nixos/modules/hardware/cpu/amd-microcode.nix
index 621c7066bfe..3f52cb1fca3 100644
--- a/nixos/modules/hardware/cpu/amd-microcode.nix
+++ b/nixos/modules/hardware/cpu/amd-microcode.nix
@@ -11,7 +11,7 @@ with lib;
     hardware.cpu.amd.updateMicrocode = mkOption {
       default = false;
       type = types.bool;
-      description = ''
+      description = lib.mdDoc ''
         Update the CPU microcode for AMD processors.
       '';
     };
diff --git a/nixos/modules/hardware/cpu/intel-microcode.nix b/nixos/modules/hardware/cpu/intel-microcode.nix
index acce565fd80..d30ebfefeea 100644
--- a/nixos/modules/hardware/cpu/intel-microcode.nix
+++ b/nixos/modules/hardware/cpu/intel-microcode.nix
@@ -11,7 +11,7 @@ with lib;
     hardware.cpu.intel.updateMicrocode = mkOption {
       default = false;
       type = types.bool;
-      description = ''
+      description = lib.mdDoc ''
         Update the CPU microcode for Intel processors.
       '';
     };
diff --git a/nixos/modules/hardware/device-tree.nix b/nixos/modules/hardware/device-tree.nix
index 5a8a8e27bee..55852776220 100644
--- a/nixos/modules/hardware/device-tree.nix
+++ b/nixos/modules/hardware/device-tree.nix
@@ -9,14 +9,14 @@ let
     options = {
       name = mkOption {
         type = types.str;
-        description = ''
+        description = lib.mdDoc ''
           Name of this overlay
         '';
       };
 
       dtsFile = mkOption {
         type = types.nullOr types.path;
-        description = ''
+        description = lib.mdDoc ''
           Path to .dts overlay file, overlay is applied to
           each .dtb file matching "compatible" of the overlay.
         '';
@@ -27,7 +27,7 @@ let
       dtsText = mkOption {
         type = types.nullOr types.str;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Literal DTS contents, overlay is applied to
           each .dtb file matching "compatible" of the overlay.
         '';
@@ -49,7 +49,7 @@ let
       dtboFile = mkOption {
         type = types.nullOr types.path;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Path to .dtbo compiled overlay file.
         '';
       };
@@ -115,7 +115,7 @@ in
         enable = mkOption {
           default = pkgs.stdenv.hostPlatform.linux-kernel.DTB or false;
           type = types.bool;
-          description = ''
+          description = lib.mdDoc ''
             Build device tree files. These are used to describe the
             non-discoverable hardware of a system.
           '';
@@ -126,7 +126,7 @@ in
           defaultText = literalExpression "config.boot.kernelPackages.kernel";
           example = literalExpression "pkgs.linux_latest";
           type = types.path;
-          description = ''
+          description = lib.mdDoc ''
             Kernel package containing the base device-tree (.dtb) to boot. Uses
             device trees bundled with the Linux kernel by default.
           '';
@@ -136,7 +136,7 @@ in
           default = null;
           example = "some-dtb.dtb";
           type = types.nullOr types.str;
-          description = ''
+          description = lib.mdDoc ''
             The name of an explicit dtb to be loaded, relative to the dtb base.
             Useful in extlinux scenarios if the bootloader doesn't pick the
             right .dtb file from FDTDIR.
@@ -147,7 +147,7 @@ in
           type = types.nullOr types.str;
           default = null;
           example = "*rpi*.dtb";
-          description = ''
+          description = lib.mdDoc ''
             Only include .dtb files matching glob expression.
           '';
         };
@@ -167,7 +167,7 @@ in
             name = baseNameOf path;
             dtboFile = path;
           }) overlayType);
-          description = ''
+          description = lib.mdDoc ''
             List of overlays to apply to base device-tree (.dtb) files.
           '';
         };
diff --git a/nixos/modules/hardware/digitalbitbox.nix b/nixos/modules/hardware/digitalbitbox.nix
index 097448a74f4..74e46bd34ac 100644
--- a/nixos/modules/hardware/digitalbitbox.nix
+++ b/nixos/modules/hardware/digitalbitbox.nix
@@ -11,7 +11,7 @@ in
     enable = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Enables udev rules for Digital Bitbox devices.
       '';
     };
@@ -20,7 +20,7 @@ in
       type = types.package;
       default = pkgs.digitalbitbox;
       defaultText = literalExpression "pkgs.digitalbitbox";
-      description = "The Digital Bitbox package to use. This can be used to install a package with udev rules that differ from the defaults.";
+      description = lib.mdDoc "The Digital Bitbox package to use. This can be used to install a package with udev rules that differ from the defaults.";
     };
   };
 
diff --git a/nixos/modules/hardware/hackrf.nix b/nixos/modules/hardware/hackrf.nix
index 7f03b765bbd..38ef7fa6d3d 100644
--- a/nixos/modules/hardware/hackrf.nix
+++ b/nixos/modules/hardware/hackrf.nix
@@ -9,7 +9,7 @@ in
     enable = lib.mkOption {
       type = lib.types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Enables hackrf udev rules and ensures 'plugdev' group exists.
         This is a prerequisite to using HackRF devices without being root, since HackRF USB descriptors will be owned by plugdev through udev.
       '';
diff --git a/nixos/modules/hardware/i2c.nix b/nixos/modules/hardware/i2c.nix
index ff14b4b1c89..0b57cd1c28d 100644
--- a/nixos/modules/hardware/i2c.nix
+++ b/nixos/modules/hardware/i2c.nix
@@ -17,7 +17,7 @@ in
     group = mkOption {
       type = types.str;
       default = "i2c";
-      description = ''
+      description = lib.mdDoc ''
         Grant access to i2c devices (/dev/i2c-*) to users in this group.
       '';
     };
diff --git a/nixos/modules/hardware/keyboard/zsa.nix b/nixos/modules/hardware/keyboard/zsa.nix
index bb69cfa0bf0..5bf4022cdc4 100644
--- a/nixos/modules/hardware/keyboard/zsa.nix
+++ b/nixos/modules/hardware/keyboard/zsa.nix
@@ -9,7 +9,7 @@ in
     enable = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Enables udev rules for keyboards from ZSA like the ErgoDox EZ, Planck EZ and Moonlander Mark I.
         You need it when you want to flash a new configuration on the keyboard
         or use their live training in the browser.
diff --git a/nixos/modules/hardware/logitech.nix b/nixos/modules/hardware/logitech.nix
index 3ebe6aacf5d..2e3a71c0415 100644
--- a/nixos/modules/hardware/logitech.nix
+++ b/nixos/modules/hardware/logitech.nix
@@ -24,7 +24,7 @@ in
       startWhenNeeded = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Only run the service when an actual supported device is plugged.
         '';
       };
@@ -47,7 +47,7 @@ in
       enableGraphical = mkOption {
         type = types.bool;
         default = false;
-        description = "Enable graphical support applications.";
+        description = lib.mdDoc "Enable graphical support applications.";
       };
     };
   };
diff --git a/nixos/modules/hardware/mcelog.nix b/nixos/modules/hardware/mcelog.nix
index 13ad238870c..be8fc8cd192 100644
--- a/nixos/modules/hardware/mcelog.nix
+++ b/nixos/modules/hardware/mcelog.nix
@@ -10,7 +10,7 @@ with lib;
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Enable the Machine Check Exception logger.
         '';
       };
diff --git a/nixos/modules/hardware/network/ath-user-regd.nix b/nixos/modules/hardware/network/ath-user-regd.nix
index b5ade5ed501..a7f023d26ce 100644
--- a/nixos/modules/hardware/network/ath-user-regd.nix
+++ b/nixos/modules/hardware/network/ath-user-regd.nix
@@ -14,7 +14,7 @@ in
   options.networking.wireless.athUserRegulatoryDomain = mkOption {
     default = false;
     type = types.bool;
-    description = ''
+    description = lib.mdDoc ''
       If enabled, sets the ATH_USER_REGD kernel config switch to true to
       disable the enforcement of EEPROM regulatory restrictions for ath
       drivers. Requires at least Linux ${linuxKernelMinVersion}.
diff --git a/nixos/modules/hardware/network/b43.nix b/nixos/modules/hardware/network/b43.nix
index eb03bf223cc..7f045f7b70f 100644
--- a/nixos/modules/hardware/network/b43.nix
+++ b/nixos/modules/hardware/network/b43.nix
@@ -13,7 +13,7 @@ let kernelVersion = config.boot.kernelPackages.kernel.version; in
     networking.enableB43Firmware = mkOption {
       default = false;
       type = types.bool;
-      description = ''
+      description = lib.mdDoc ''
         Turn on this option if you want firmware for the NICs supported by the b43 module.
       '';
     };
diff --git a/nixos/modules/hardware/network/intel-2200bg.nix b/nixos/modules/hardware/network/intel-2200bg.nix
index 17b973474c9..e1ec8134129 100644
--- a/nixos/modules/hardware/network/intel-2200bg.nix
+++ b/nixos/modules/hardware/network/intel-2200bg.nix
@@ -9,7 +9,7 @@
     networking.enableIntel2200BGFirmware = lib.mkOption {
       default = false;
       type = lib.types.bool;
-      description = ''
+      description = lib.mdDoc ''
         Turn on this option if you want firmware for the Intel
         PRO/Wireless 2200BG to be loaded automatically.  This is
         required if you want to use this device.
diff --git a/nixos/modules/hardware/new-lg4ff.nix b/nixos/modules/hardware/new-lg4ff.nix
index 3c7f66f8d89..fac376eb7a7 100644
--- a/nixos/modules/hardware/new-lg4ff.nix
+++ b/nixos/modules/hardware/new-lg4ff.nix
@@ -10,7 +10,7 @@ in {
     enable = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Enables improved Linux module drivers for Logitech driving wheels.
         This will replace the existing in-kernel hid-logitech modules.
         Works most notably on the Logitech G25, G27, G29 and Driving Force (GT).
diff --git a/nixos/modules/hardware/nitrokey.nix b/nixos/modules/hardware/nitrokey.nix
index baa07203118..fa9dd4d6d8f 100644
--- a/nixos/modules/hardware/nitrokey.nix
+++ b/nixos/modules/hardware/nitrokey.nix
@@ -13,7 +13,7 @@ in
     enable = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Enables udev rules for Nitrokey devices. By default grants access
         to users in the "nitrokey" group. You may want to install the
         nitrokey-app package, depending on your device and needs.
diff --git a/nixos/modules/hardware/onlykey/default.nix b/nixos/modules/hardware/onlykey/default.nix
index 07358c8a878..59e159dce48 100644
--- a/nixos/modules/hardware/onlykey/default.nix
+++ b/nixos/modules/hardware/onlykey/default.nix
@@ -12,7 +12,7 @@ with lib;
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Enable OnlyKey device (https://crp.to/p/) support.
         '';
       };
diff --git a/nixos/modules/hardware/opengl.nix b/nixos/modules/hardware/opengl.nix
index 0d8aaf73459..dd30bd92b45 100644
--- a/nixos/modules/hardware/opengl.nix
+++ b/nixos/modules/hardware/opengl.nix
@@ -35,7 +35,7 @@ in
 
     hardware.opengl = {
       enable = mkOption {
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable OpenGL drivers. This is needed to enable
           OpenGL support in X11 systems, as well as for Wayland compositors
           like sway and Weston. It is enabled by default
@@ -51,7 +51,7 @@ in
       driSupport = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable accelerated OpenGL rendering through the
           Direct Rendering Interface (DRI).
         '';
@@ -60,11 +60,11 @@ in
       driSupport32Bit = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           On 64-bit systems, whether to support Direct Rendering for
           32-bit applications (such as Wine).  This is currently only
-          supported for the <literal>nvidia</literal> as well as
-          <literal>Mesa</literal>.
+          supported for the `nvidia` as well as
+          `Mesa`.
         '';
       };
 
@@ -90,7 +90,7 @@ in
         type = types.listOf types.package;
         default = [];
         example = literalExpression "with pkgs; [ vaapiIntel libvdpau-va-gl vaapiVdpau intel-ocl ]";
-        description = ''
+        description = lib.mdDoc ''
           Additional packages to add to OpenGL drivers. This can be used
           to add OpenCL drivers, VA-API/VDPAU drivers etc.
         '';
@@ -100,9 +100,9 @@ in
         type = types.listOf types.package;
         default = [];
         example = literalExpression "with pkgs.pkgsi686Linux; [ vaapiIntel libvdpau-va-gl vaapiVdpau ]";
-        description = ''
+        description = lib.mdDoc ''
           Additional packages to add to 32-bit OpenGL drivers on
-          64-bit systems. Used when <option>driSupport32Bit</option> is
+          64-bit systems. Used when {option}`driSupport32Bit` is
           set. This can be used to add OpenCL drivers, VA-API/VDPAU drivers etc.
         '';
       };
diff --git a/nixos/modules/hardware/openrazer.nix b/nixos/modules/hardware/openrazer.nix
index bd9fc485e17..315a4a6824b 100644
--- a/nixos/modules/hardware/openrazer.nix
+++ b/nixos/modules/hardware/openrazer.nix
@@ -56,7 +56,7 @@ in
       verboseLogging = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable verbose logging. Logs debug messages.
         '';
       };
@@ -64,7 +64,7 @@ in
       syncEffectsEnabled = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Set the sync effects flag to true so any assignment of
           effects will work across devices.
         '';
@@ -73,7 +73,7 @@ in
       devicesOffOnScreensaver = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Turn off the devices when the systems screensaver kicks in.
         '';
       };
@@ -81,7 +81,7 @@ in
       mouseBatteryNotifier = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Mouse battery notifier.
         '';
       };
@@ -89,7 +89,7 @@ in
       keyStatistics = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Collects number of keypresses per hour per key used to
           generate a heatmap.
         '';
@@ -98,7 +98,7 @@ in
       users = mkOption {
         type = with types; listOf str;
         default = [];
-        description = ''
+        description = lib.mdDoc ''
           Usernames to be added to the "openrazer" group, so that they
           can start and interact with the OpenRazer userspace daemon.
         '';
diff --git a/nixos/modules/hardware/opentabletdriver.nix b/nixos/modules/hardware/opentabletdriver.nix
index caba934ebe7..6c5ca3d949e 100644
--- a/nixos/modules/hardware/opentabletdriver.nix
+++ b/nixos/modules/hardware/opentabletdriver.nix
@@ -12,7 +12,7 @@ in
       enable = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Enable OpenTabletDriver udev rules, user service and blacklist kernel
           modules known to conflict with OpenTabletDriver.
         '';
@@ -21,7 +21,7 @@ in
       blacklistedKernelModules = mkOption {
         type = types.listOf types.str;
         default = [ "hid-uclogic" "wacom" ];
-        description = ''
+        description = lib.mdDoc ''
           Blacklist of kernel modules known to conflict with OpenTabletDriver.
         '';
       };
@@ -30,7 +30,7 @@ in
         type = types.package;
         default = pkgs.opentabletdriver;
         defaultText = literalExpression "pkgs.opentabletdriver";
-        description = ''
+        description = lib.mdDoc ''
           OpenTabletDriver derivation to use.
         '';
       };
@@ -39,7 +39,7 @@ in
         enable = mkOption {
           default = true;
           type = types.bool;
-          description = ''
+          description = lib.mdDoc ''
             Whether to start OpenTabletDriver daemon as a systemd user service.
           '';
         };
diff --git a/nixos/modules/hardware/pcmcia.nix b/nixos/modules/hardware/pcmcia.nix
index aef35a28e54..f7a5565d773 100644
--- a/nixos/modules/hardware/pcmcia.nix
+++ b/nixos/modules/hardware/pcmcia.nix
@@ -20,7 +20,7 @@ in
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Enable this option to support PCMCIA card.
         '';
       };
@@ -28,7 +28,7 @@ in
       firmware = mkOption {
         type = types.listOf types.path;
         default = [];
-        description = ''
+        description = lib.mdDoc ''
           List of firmware used to handle specific PCMCIA card.
         '';
       };
@@ -36,7 +36,7 @@ in
       config = mkOption {
         default = null;
         type = types.nullOr types.path;
-        description = ''
+        description = lib.mdDoc ''
           Path to the configuration file which maps the memory, IRQs
           and ports used by the PCMCIA hardware.
         '';
diff --git a/nixos/modules/hardware/printers.nix b/nixos/modules/hardware/printers.nix
index ef07542950b..64c29bb0a5b 100644
--- a/nixos/modules/hardware/printers.nix
+++ b/nixos/modules/hardware/printers.nix
@@ -30,17 +30,17 @@ in {
       ensureDefaultPrinter = mkOption {
         type = types.nullOr printerName;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Ensures the named printer is the default CUPS printer / printer queue.
         '';
       };
       ensurePrinters = mkOption {
-        description = ''
+        description = lib.mdDoc ''
           Will regularly ensure that the given CUPS printers are configured as declared here.
           If a printer's options are manually changed afterwards, they will be overwritten eventually.
           This option will never delete any printer, even if removed from this list.
-          You can check existing printers with <command>lpstat -s</command>
-          and remove printers with <command>lpadmin -x &lt;printer-name&gt;</command>.
+          You can check existing printers with {command}`lpstat -s`
+          and remove printers with {command}`lpadmin -x <printer-name>`.
           Printers not listed here can still be manually configured.
         '';
         default = [];
@@ -49,7 +49,7 @@ in {
             name = mkOption {
               type = printerName;
               example = "BrotherHL_Workroom";
-              description = ''
+              description = lib.mdDoc ''
                 Name of the printer / printer queue.
                 May contain any printable characters except "/", "#", and space.
               '';
@@ -58,7 +58,7 @@ in {
               type = types.nullOr types.str;
               default = null;
               example = "Workroom";
-              description = ''
+              description = lib.mdDoc ''
                 Optional human-readable location.
               '';
             };
@@ -66,7 +66,7 @@ in {
               type = types.nullOr types.str;
               default = null;
               example = "Brother HL-5140";
-              description = ''
+              description = lib.mdDoc ''
                 Optional human-readable description.
               '';
             };
@@ -76,9 +76,9 @@ in {
                 "ipp://printserver.local/printers/BrotherHL_Workroom"
                 "usb://HP/DESKJET%20940C?serial=CN16E6C364BH"
               '';
-              description = ''
+              description = lib.mdDoc ''
                 How to reach the printer.
-                <command>lpinfo -v</command> shows a list of supported device URIs and schemes.
+                {command}`lpinfo -v` shows a list of supported device URIs and schemes.
               '';
             };
             model = mkOption {
@@ -86,9 +86,9 @@ in {
               example = literalExpression ''
                 "gutenprint.''${lib.versions.majorMinor (lib.getVersion pkgs.gutenprint)}://brother-hl-5140/expert"
               '';
-              description = ''
+              description = lib.mdDoc ''
                 Location of the ppd driver file for the printer.
-                <command>lpinfo -m</command> shows a list of supported models.
+                {command}`lpinfo -m` shows a list of supported models.
               '';
             };
             ppdOptions = mkOption {
@@ -98,9 +98,9 @@ in {
                 Duplex = "DuplexNoTumble";
               };
               default = {};
-              description = ''
+              description = lib.mdDoc ''
                 Sets PPD options for the printer.
-                <command>lpoptions [-p printername] -l</command> shows suported PPD options for the given printer.
+                {command}`lpoptions [-p printername] -l` shows suported PPD options for the given printer.
               '';
             };
           };
diff --git a/nixos/modules/hardware/rtl-sdr.nix b/nixos/modules/hardware/rtl-sdr.nix
index e85fc04e29b..7f462005f15 100644
--- a/nixos/modules/hardware/rtl-sdr.nix
+++ b/nixos/modules/hardware/rtl-sdr.nix
@@ -8,7 +8,7 @@ in {
     enable = lib.mkOption {
       type = lib.types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Enables rtl-sdr udev rules, ensures 'plugdev' group exists, and blacklists DVB kernel modules.
         This is a prerequisite to using devices supported by rtl-sdr without being root, since rtl-sdr USB descriptors will be owned by plugdev through udev.
        '';
diff --git a/nixos/modules/hardware/saleae-logic.nix b/nixos/modules/hardware/saleae-logic.nix
index a3810d640c4..02d234cd3f0 100644
--- a/nixos/modules/hardware/saleae-logic.nix
+++ b/nixos/modules/hardware/saleae-logic.nix
@@ -11,7 +11,7 @@ in
       type = lib.types.package;
       default = pkgs.saleae-logic-2;
       defaultText = lib.literalExpression "pkgs.saleae-logic-2";
-      description = ''
+      description = lib.mdDoc ''
         Saleae Logic package to use.
       '';
     };
diff --git a/nixos/modules/hardware/sata.nix b/nixos/modules/hardware/sata.nix
index 81592997d6e..bac24236f7d 100644
--- a/nixos/modules/hardware/sata.nix
+++ b/nixos/modules/hardware/sata.nix
@@ -41,7 +41,7 @@ in
     deciSeconds = mkOption {
       example = 70;
       type = types.int;
-      description = ''
+      description = lib.mdDoc ''
         Set SCT Error Recovery Control timeout in deciseconds for use in RAID configurations.
 
         Values are as follows:
@@ -53,17 +53,17 @@ in
     };
 
     drives = mkOption {
-      description = "List of drives for which to configure the timeout.";
+      description = lib.mdDoc "List of drives for which to configure the timeout.";
       type = types.listOf
         (types.submodule {
           options = {
             name = mkOption {
-              description = "Drive name without the full path.";
+              description = lib.mdDoc "Drive name without the full path.";
               type = types.str;
             };
 
             idBy = mkOption {
-              description = "The method to identify the drive.";
+              description = lib.mdDoc "The method to identify the drive.";
               type = types.enum [ "path" "wwn" ];
               default = "path";
             };
diff --git a/nixos/modules/hardware/sensor/hddtemp.nix b/nixos/modules/hardware/sensor/hddtemp.nix
index df3f75e229a..b69d012b4d0 100644
--- a/nixos/modules/hardware/sensor/hddtemp.nix
+++ b/nixos/modules/hardware/sensor/hddtemp.nix
@@ -30,7 +30,7 @@ in
   options = {
     hardware.sensor.hddtemp = {
       enable = mkOption {
-        description = ''
+        description = lib.mdDoc ''
           Enable this option to support HDD/SSD temperature sensors.
         '';
         type = types.bool;
@@ -38,24 +38,24 @@ in
       };
 
       drives = mkOption {
-        description = "List of drives to monitor. If you pass /dev/disk/by-path/* entries the symlinks will be resolved as hddtemp doesn't like names with colons.";
+        description = lib.mdDoc "List of drives to monitor. If you pass /dev/disk/by-path/* entries the symlinks will be resolved as hddtemp doesn't like names with colons.";
         type = types.listOf types.str;
       };
 
       unit = mkOption {
-        description = "Celcius or Fahrenheit";
+        description = lib.mdDoc "Celcius or Fahrenheit";
         type = types.enum [ "C" "F" ];
         default = "C";
       };
 
       dbEntries = mkOption {
-        description = "Additional DB entries";
+        description = lib.mdDoc "Additional DB entries";
         type = types.listOf types.str;
         default = [ ];
       };
 
       extraArgs = mkOption {
-        description = "Additional arguments passed to the daemon.";
+        description = lib.mdDoc "Additional arguments passed to the daemon.";
         type = types.listOf types.str;
         default = [ ];
       };
diff --git a/nixos/modules/hardware/sensor/iio.nix b/nixos/modules/hardware/sensor/iio.nix
index 8b3ba87a7d9..6f7b1dc1f7f 100644
--- a/nixos/modules/hardware/sensor/iio.nix
+++ b/nixos/modules/hardware/sensor/iio.nix
@@ -8,7 +8,7 @@ with lib;
   options = {
     hardware.sensor.iio = {
       enable = mkOption {
-        description = ''
+        description = lib.mdDoc ''
           Enable this option to support IIO sensors with iio-sensor-proxy.
 
           IIO sensors are used for orientation and ambient light
diff --git a/nixos/modules/hardware/steam-hardware.nix b/nixos/modules/hardware/steam-hardware.nix
index 6218c9ffbb9..07edf687039 100644
--- a/nixos/modules/hardware/steam-hardware.nix
+++ b/nixos/modules/hardware/steam-hardware.nix
@@ -13,7 +13,7 @@ in
     enable = mkOption {
       type = types.bool;
       default = false;
-      description = "Enable udev rules for Steam hardware such as the Steam Controller, other supported controllers and the HTC Vive";
+      description = lib.mdDoc "Enable udev rules for Steam hardware such as the Steam Controller, other supported controllers and the HTC Vive";
     };
   };
 
diff --git a/nixos/modules/hardware/system-76.nix b/nixos/modules/hardware/system-76.nix
index ca40ee0ebb3..21cab4a3787 100644
--- a/nixos/modules/hardware/system-76.nix
+++ b/nixos/modules/hardware/system-76.nix
@@ -63,7 +63,7 @@ in {
         default = cfg.enableAll;
         defaultText = literalExpression "config.${opt.enableAll}";
         example = true;
-        description = "Whether to enable the system76 firmware daemon";
+        description = lib.mdDoc "Whether to enable the system76 firmware daemon";
         type = types.bool;
       };
 
@@ -71,7 +71,7 @@ in {
         default = cfg.enableAll;
         defaultText = literalExpression "config.${opt.enableAll}";
         example = true;
-        description = "Whether to make the system76 out-of-tree kernel modules available";
+        description = lib.mdDoc "Whether to make the system76 out-of-tree kernel modules available";
         type = types.bool;
       };
 
@@ -79,7 +79,7 @@ in {
         default = cfg.enableAll;
         defaultText = literalExpression "config.${opt.enableAll}";
         example = true;
-        description = "Whether to enable the system76 power daemon";
+        description = lib.mdDoc "Whether to enable the system76 power daemon";
         type = types.bool;
       };
     };
diff --git a/nixos/modules/hardware/ubertooth.nix b/nixos/modules/hardware/ubertooth.nix
index 637fddfb37d..e76fa45fea5 100644
--- a/nixos/modules/hardware/ubertooth.nix
+++ b/nixos/modules/hardware/ubertooth.nix
@@ -16,7 +16,7 @@ in {
       type = types.str;
       default = "ubertooth";
       example = "wheel";
-      description = "Group for Ubertooth's udev rules.";
+      description = lib.mdDoc "Group for Ubertooth's udev rules.";
     };
   };
 
diff --git a/nixos/modules/hardware/usb-wwan.nix b/nixos/modules/hardware/usb-wwan.nix
index 679a6c6497c..69673872cf9 100644
--- a/nixos/modules/hardware/usb-wwan.nix
+++ b/nixos/modules/hardware/usb-wwan.nix
@@ -11,7 +11,7 @@ with lib;
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Enable this option to support USB WWAN adapters.
         '';
       };
diff --git a/nixos/modules/hardware/video/bumblebee.nix b/nixos/modules/hardware/video/bumblebee.nix
index b6af4f80445..75f71d499e6 100644
--- a/nixos/modules/hardware/video/bumblebee.nix
+++ b/nixos/modules/hardware/video/bumblebee.nix
@@ -29,7 +29,7 @@ in
       enable = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Enable the bumblebee daemon to manage Optimus hybrid video cards.
           This should power off secondary GPU until its use is requested
           by running an application with optirun.
@@ -40,13 +40,13 @@ in
         default = "wheel";
         example = "video";
         type = types.str;
-        description = "Group for bumblebee socket";
+        description = lib.mdDoc "Group for bumblebee socket";
       };
 
       connectDisplay = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Set to true if you intend to connect your discrete card to a
           monitor. This option will set up your Nvidia card for EDID
           discovery and to turn on the monitor signal.
@@ -58,7 +58,7 @@ in
       driver = mkOption {
         default = "nvidia";
         type = types.enum [ "nvidia" "nouveau" ];
-        description = ''
+        description = lib.mdDoc ''
           Set driver used by bumblebeed. Supported are nouveau and nvidia.
         '';
       };
@@ -66,7 +66,7 @@ in
       pmMethod = mkOption {
         default = "auto";
         type = types.enum [ "auto" "bbswitch" "switcheroo" "none" ];
-        description = ''
+        description = lib.mdDoc ''
           Set preferred power management method for unused card.
         '';
       };
diff --git a/nixos/modules/hardware/video/nvidia.nix b/nixos/modules/hardware/video/nvidia.nix
index f0f7b8e449a..8c6c97f9b21 100644
--- a/nixos/modules/hardware/video/nvidia.nix
+++ b/nixos/modules/hardware/video/nvidia.nix
@@ -40,7 +40,7 @@ in
     hardware.nvidia.powerManagement.enable = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Experimental power management through systemd. For more information, see
         the NVIDIA docs, on Chapter 21. Configuring Power Management Support.
       '';
@@ -49,7 +49,7 @@ in
     hardware.nvidia.powerManagement.finegrained = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Experimental power management of PRIME offload. For more information, see
         the NVIDIA docs, chapter 22. PCI-Express runtime power management.
       '';
@@ -58,11 +58,11 @@ in
     hardware.nvidia.modesetting.enable = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Enable kernel modesetting when using the NVIDIA proprietary driver.
 
         Enabling this fixes screen tearing when using Optimus via PRIME (see
-        <option>hardware.nvidia.prime.sync.enable</option>. This is not enabled
+        {option}`hardware.nvidia.prime.sync.enable`. This is not enabled
         by default because it is not officially supported by NVIDIA and would not
         work with SLI.
       '';
@@ -72,7 +72,7 @@ in
       type = busIDType;
       default = "";
       example = "PCI:1:0:0";
-      description = ''
+      description = lib.mdDoc ''
         Bus ID of the NVIDIA GPU. You can find it using lspci; for example if lspci
         shows the NVIDIA GPU at "01:00.0", set this option to "PCI:1:0:0".
       '';
@@ -82,7 +82,7 @@ in
       type = busIDType;
       default = "";
       example = "PCI:0:2:0";
-      description = ''
+      description = lib.mdDoc ''
         Bus ID of the Intel GPU. You can find it using lspci; for example if lspci
         shows the Intel GPU at "00:02.0", set this option to "PCI:0:2:0".
       '';
@@ -92,7 +92,7 @@ in
       type = busIDType;
       default = "";
       example = "PCI:4:0:0";
-      description = ''
+      description = lib.mdDoc ''
         Bus ID of the AMD APU. You can find it using lspci; for example if lspci
         shows the AMD APU at "04:00.0", set this option to "PCI:4:0:0".
       '';
@@ -101,26 +101,26 @@ in
     hardware.nvidia.prime.sync.enable = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Enable NVIDIA Optimus support using the NVIDIA proprietary driver via PRIME.
         If enabled, the NVIDIA GPU will be always on and used for all rendering,
         while enabling output to displays attached only to the integrated Intel GPU
         without a multiplexer.
 
         Note that this option only has any effect if the "nvidia" driver is specified
-        in <option>services.xserver.videoDrivers</option>, and it should preferably
+        in {option}`services.xserver.videoDrivers`, and it should preferably
         be the only driver there.
 
         If this is enabled, then the bus IDs of the NVIDIA and Intel GPUs have to be
-        specified (<option>hardware.nvidia.prime.nvidiaBusId</option> and
-        <option>hardware.nvidia.prime.intelBusId</option>).
+        specified ({option}`hardware.nvidia.prime.nvidiaBusId` and
+        {option}`hardware.nvidia.prime.intelBusId`).
 
         If you enable this, you may want to also enable kernel modesetting for the
-        NVIDIA driver (<option>hardware.nvidia.modesetting.enable</option>) in order
+        NVIDIA driver ({option}`hardware.nvidia.modesetting.enable`) in order
         to prevent tearing.
 
         Note that this configuration will only be successful when a display manager
-        for which the <option>services.xserver.displayManager.setupCommands</option>
+        for which the {option}`services.xserver.displayManager.setupCommands`
         option is supported is used.
       '';
     };
@@ -128,7 +128,7 @@ in
     hardware.nvidia.prime.sync.allowExternalGpu = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Configure X to allow external NVIDIA GPUs when using optimus.
       '';
     };
@@ -136,19 +136,19 @@ in
     hardware.nvidia.prime.offload.enable = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Enable render offload support using the NVIDIA proprietary driver via PRIME.
 
         If this is enabled, then the bus IDs of the NVIDIA and Intel GPUs have to be
-        specified (<option>hardware.nvidia.prime.nvidiaBusId</option> and
-        <option>hardware.nvidia.prime.intelBusId</option>).
+        specified ({option}`hardware.nvidia.prime.nvidiaBusId` and
+        {option}`hardware.nvidia.prime.intelBusId`).
       '';
     };
 
     hardware.nvidia.nvidiaSettings = mkOption {
       default = true;
       type = types.bool;
-      description = ''
+      description = lib.mdDoc ''
         Whether to add nvidia-settings, NVIDIA's GUI configuration tool, to
         systemPackages.
       '';
@@ -157,7 +157,7 @@ in
     hardware.nvidia.nvidiaPersistenced = mkOption {
       default = false;
       type = types.bool;
-      description = ''
+      description = lib.mdDoc ''
         Update for NVIDA GPU headless mode, i.e. nvidia-persistenced. It ensures all
         GPUs stay awake even during headless mode.
       '';
@@ -166,7 +166,7 @@ in
     hardware.nvidia.forceFullCompositionPipeline = lib.mkOption {
       default = false;
       type = types.bool;
-      description = ''
+      description = lib.mdDoc ''
         Whether to force-enable the full composition pipeline.
         This sometimes fixes screen tearing issues.
         This has been reported to reduce the performance of some OpenGL applications and may produce issues in WebGL.
@@ -178,7 +178,7 @@ in
       type = types.package;
       default = config.boot.kernelPackages.nvidiaPackages.stable;
       defaultText = literalExpression "config.boot.kernelPackages.nvidiaPackages.stable";
-      description = ''
+      description = lib.mdDoc ''
         The NVIDIA X11 derivation to use.
       '';
       example = literalExpression "config.boot.kernelPackages.nvidiaPackages.legacy_340";
@@ -187,7 +187,7 @@ in
     hardware.nvidia.open = lib.mkOption {
       type = lib.types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether to use the open source kernel module
       '';
     };
diff --git a/nixos/modules/hardware/video/uvcvideo/default.nix b/nixos/modules/hardware/video/uvcvideo/default.nix
index 338062cf69b..bb59e2f2ed2 100644
--- a/nixos/modules/hardware/video/uvcvideo/default.nix
+++ b/nixos/modules/hardware/video/uvcvideo/default.nix
@@ -22,12 +22,12 @@ in
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
-          Whether to enable <command>uvcvideo</command> dynamic controls.
+        description = lib.mdDoc ''
+          Whether to enable {command}`uvcvideo` dynamic controls.
 
-          Note that enabling this brings the <command>uvcdynctrl</command> tool
+          Note that enabling this brings the {command}`uvcdynctrl` tool
           into your environment and register all dynamic controls from
-          specified <command>packages</command> to the <command>uvcvideo</command> driver.
+          specified {command}`packages` to the {command}`uvcvideo` driver.
         '';
       };
 
diff --git a/nixos/modules/hardware/video/webcam/facetimehd.nix b/nixos/modules/hardware/video/webcam/facetimehd.nix
index c48eac5e9c1..8940674ce53 100644
--- a/nixos/modules/hardware/video/webcam/facetimehd.nix
+++ b/nixos/modules/hardware/video/webcam/facetimehd.nix
@@ -18,10 +18,10 @@ in
     default = false;
     example = true;
     type = types.bool;
-    description = ''
+    description = lib.mdDoc ''
       Whether to include sensor calibration files for facetimehd.
       This makes colors look much better but is experimental, see
-      <link xlink:href="https://github.com/patjak/facetimehd/wiki/Extracting-the-sensor-calibration-files"/>
+      <https://github.com/patjak/facetimehd/wiki/Extracting-the-sensor-calibration-files>
       for details.
     '';
   };