treewide: automatically md-convert option descriptions

the conversion procedure is simple:

 - find all things that look like options, ie calls to either `mkOption`
   or `lib.mkOption` that take an attrset. remember the attrset as the
   option
 - for all options, find a `description` attribute who's value is not a
   call to `mdDoc` or `lib.mdDoc`
 - textually convert the entire value of the attribute to MD with a few
   simple regexes (the set from mdize-module.sh)
 - if the change produced a change in the manual output, discard
 - if the change kept the manual unchanged, add some text to the
   description to make sure we've actually found an option. if the
   manual changes this time, keep the converted description

this procedure converts 80% of nixos options to markdown. around 2000
options remain to be inspected, but most of those fail the "does not
change the manual output check": currently the MD conversion process
does not faithfully convert docbook tags like <code> and <package>, so
any option using such tags will not be converted at all.

37 files changed, 117 insertions, 117 deletions

diff --git a/nixos/modules/hardware/acpilight.nix b/nixos/modules/hardware/acpilight.nix
index 2de448a265c79..d8d82b0e81a47 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 89a1217dfb313..30b84eefce7d2 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 35b74b8382e3a..52a1f52024c8f 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 751ed663aab57..287d287a775c9 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 621c7066bfe1b..3f52cb1fca3e1 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 acce565fd808b..d30ebfefeeacf 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 5a8a8e27bee1b..55852776220d3 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 097448a74f4d9..74e46bd34acea 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 7f03b765bbdaf..38ef7fa6d3d4d 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 ff14b4b1c891d..0b57cd1c28df7 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 bb69cfa0bf091..5bf4022cdc435 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 3ebe6aacf5d68..2e3a71c041585 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 13ad238870c29..be8fc8cd1925d 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 b5ade5ed50105..a7f023d26ce79 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 eb03bf223ccfe..7f045f7b70f93 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 17b973474c93b..e1ec8134129e4 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 3c7f66f8d89b5..fac376eb7a75d 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 baa07203118c6..fa9dd4d6d8f99 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 07358c8a87820..59e159dce4821 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 0d8aaf734591d..dd30bd92b4575 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 bd9fc485e17ea..315a4a6824bb4 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 caba934ebe773..6c5ca3d949e8b 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 aef35a28e54da..f7a5565d773e6 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 ef07542950bac..64c29bb0a5b3b 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 e85fc04e29bb6..7f462005f1570 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 a3810d640c483..02d234cd3f05b 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 81592997d6e3d..bac24236f7dc8 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 df3f75e229a2f..b69d012b4d092 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 8b3ba87a7d9c4..6f7b1dc1f7f8b 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 6218c9ffbb9b1..07edf68703904 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 ca40ee0ebb37a..21cab4a3787c6 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 637fddfb37dff..e76fa45fea515 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 679a6c6497cb6..69673872cf9b7 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 b6af4f80445ab..75f71d499e662 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 f0f7b8e449a27..8c6c97f9b21d0 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 338062cf69b7f..bb59e2f2ed2b0 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 c48eac5e9c116..8940674ce53be 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.
     '';
   };