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

treewide: automatically md-convert option descriptions

8 files changed, 191 insertions, 191 deletions

diff --git a/nixos/modules/tasks/auto-upgrade.nix b/nixos/modules/tasks/auto-upgrade.nix
index 54eee19dc771b..46a30c53ea889 100644
--- a/nixos/modules/tasks/auto-upgrade.nix
+++ b/nixos/modules/tasks/auto-upgrade.nix
@@ -13,10 +13,10 @@ in {
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to periodically upgrade NixOS to the latest
           version. If enabled, a systemd timer will run
-          <literal>nixos-rebuild switch --upgrade</literal> once a
+          `nixos-rebuild switch --upgrade` once a
           day.
         '';
       };
@@ -36,9 +36,9 @@ in {
         type = types.nullOr types.str;
         default = null;
         example = "github:kloenk/nix";
-        description = ''
+        description = lib.mdDoc ''
           The Flake URI of the NixOS configuration to build.
-          Disables the option <option>system.autoUpgrade.channel</option>.
+          Disables the option {option}`system.autoUpgrade.channel`.
         '';
       };
 
@@ -64,11 +64,11 @@ in {
           "extra-binary-caches"
           "http://my-cache.example.org/"
         ];
-        description = ''
-          Any additional flags passed to <command>nixos-rebuild</command>.
+        description = lib.mdDoc ''
+          Any additional flags passed to {command}`nixos-rebuild`.
 
           If you are using flakes and use a local repo you can add
-          <command>[ "--update-input" "nixpkgs" "--commit-lock-file" ]</command>
+          {command}`[ "--update-input" "nixpkgs" "--commit-lock-file" ]`
           to update nixpkgs.
         '';
       };
@@ -90,11 +90,11 @@ in {
       allowReboot = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Reboot the system into the new generation instead of a switch
           if the new generation uses a different kernel, kernel modules
           or initrd than the booted system.
-          See <option>rebootWindow</option> for configuring the times at which a reboot is allowed.
+          See {option}`rebootWindow` for configuring the times at which a reboot is allowed.
         '';
       };
 
@@ -112,24 +112,24 @@ in {
       };
 
       rebootWindow = mkOption {
-        description = ''
+        description = lib.mdDoc ''
           Define a lower and upper time value (in HH:MM format) which
           constitute a time window during which reboots are allowed after an upgrade.
-          This option only has an effect when <option>allowReboot</option> is enabled.
-          The default value of <literal>null</literal> means that reboots are allowed at any time.
+          This option only has an effect when {option}`allowReboot` is enabled.
+          The default value of `null` means that reboots are allowed at any time.
         '';
         default = null;
         example = { lower = "01:00"; upper = "05:00"; };
         type = with types; nullOr (submodule {
           options = {
             lower = mkOption {
-              description = "Lower limit of the reboot window";
+              description = lib.mdDoc "Lower limit of the reboot window";
               type = types.strMatching "[[:digit:]]{2}:[[:digit:]]{2}";
               example = "01:00";
             };
 
             upper = mkOption {
-              description = "Upper limit of the reboot window";
+              description = lib.mdDoc "Upper limit of the reboot window";
               type = types.strMatching "[[:digit:]]{2}:[[:digit:]]{2}";
               example = "05:00";
             };
@@ -141,7 +141,7 @@ in {
         default = true;
         type = types.bool;
         example = false;
-        description = ''
+        description = lib.mdDoc ''
           Takes a boolean argument. If true, the time when the service
           unit was last triggered is stored on disk. When the timer is
           activated, the service unit is triggered immediately if it
diff --git a/nixos/modules/tasks/cpu-freq.nix b/nixos/modules/tasks/cpu-freq.nix
index f1219c07c5013..6869ef8b79154 100644
--- a/nixos/modules/tasks/cpu-freq.nix
+++ b/nixos/modules/tasks/cpu-freq.nix
@@ -18,7 +18,7 @@ in
       type = types.nullOr types.str;
       default = null;
       example = "ondemand";
-      description = ''
+      description = lib.mdDoc ''
         Configure the governor used to regulate the frequency of the
         available CPUs. By default, the kernel configures the
         performance governor, although this may be overwritten in your
@@ -34,7 +34,7 @@ in
         type = types.nullOr types.ints.unsigned;
         default = null;
         example = 2200000;
-        description = ''
+        description = lib.mdDoc ''
           The maximum frequency the CPU will use.  Defaults to the maximum possible.
         '';
       };
@@ -43,7 +43,7 @@ in
         type = types.nullOr types.ints.unsigned;
         default = null;
         example = 800000;
-        description = ''
+        description = lib.mdDoc ''
           The minimum frequency the CPU will use.
         '';
       };
diff --git a/nixos/modules/tasks/filesystems.nix b/nixos/modules/tasks/filesystems.nix
index 82adc499ad0e7..c1e96e7aede77 100644
--- a/nixos/modules/tasks/filesystems.nix
+++ b/nixos/modules/tasks/filesystems.nix
@@ -33,27 +33,27 @@ let
       mountPoint = mkOption {
         example = "/mnt/usb";
         type = nonEmptyWithoutTrailingSlash;
-        description = "Location of the mounted the file system.";
+        description = lib.mdDoc "Location of the mounted the file system.";
       };
 
       device = mkOption {
         default = null;
         example = "/dev/sda";
         type = types.nullOr nonEmptyStr;
-        description = "Location of the device.";
+        description = lib.mdDoc "Location of the device.";
       };
 
       fsType = mkOption {
         default = "auto";
         example = "ext3";
         type = nonEmptyStr;
-        description = "Type of the file system.";
+        description = lib.mdDoc "Type of the file system.";
       };
 
       options = mkOption {
         default = [ "defaults" ];
         example = [ "data=journal" ];
-        description = "Options used to mount the file system.";
+        description = lib.mdDoc "Options used to mount the file system.";
         type = types.listOf nonEmptyStr;
       };
 
@@ -61,13 +61,13 @@ let
         default = [ ];
         example = [ "/persist" ];
         type = types.listOf nonEmptyWithoutTrailingSlash;
-        description = ''
+        description = lib.mdDoc ''
           List of paths that should be mounted before this one. This filesystem's
-          <option>device</option> and <option>mountPoint</option> are always
+          {option}`device` and {option}`mountPoint` are always
           checked and do not need to be included explicitly. If a path is added
           to this list, any other filesystem whose mount point is a parent of
           the path will be mounted before this filesystem. The paths do not need
-          to actually be the <option>mountPoint</option> of some other filesystem.
+          to actually be the {option}`mountPoint` of some other filesystem.
         '';
       };
 
@@ -88,25 +88,25 @@ let
         default = null;
         example = "root-partition";
         type = types.nullOr nonEmptyStr;
-        description = "Label of the device (if any).";
+        description = lib.mdDoc "Label of the device (if any).";
       };
 
       autoFormat = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           If the device does not currently contain a filesystem (as
-          determined by <command>blkid</command>, then automatically
+          determined by {command}`blkid`, then automatically
           format it with the filesystem type specified in
-          <option>fsType</option>.  Use with caution.
+          {option}`fsType`.  Use with caution.
         '';
       };
 
       formatOptions = mkOption {
         default = "";
         type = types.str;
-        description = ''
-          If <option>autoFormat</option> option is set specifies
+        description = lib.mdDoc ''
+          If {option}`autoFormat` option is set specifies
           extra options passed to mkfs.
         '';
       };
@@ -114,7 +114,7 @@ let
       autoResize = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           If set, the filesystem is grown to its maximum size before
           being mounted. (This is typically the size of the containing
           partition.) This is currently only supported for ext2/3/4
@@ -125,7 +125,7 @@ let
       noCheck = mkOption {
         default = false;
         type = types.bool;
-        description = "Disable running fsck on this filesystem.";
+        description = lib.mdDoc "Disable running fsck on this filesystem.";
       };
 
     };
@@ -203,7 +203,7 @@ in
       default = [ ];
       example = [ "btrfs" ];
       type = types.listOf types.str;
-      description = "Names of supported filesystem types.";
+      description = lib.mdDoc "Names of supported filesystem types.";
     };
 
     boot.specialFileSystems = mkOption {
@@ -219,7 +219,7 @@ in
       default = "5%";
       example = "32m";
       type = types.str;
-      description = ''
+      description = lib.mdDoc ''
         Size limit for the /dev tmpfs. Look at mount(8), tmpfs size option,
         for the accepted syntax.
       '';
@@ -229,7 +229,7 @@ in
       default = "50%";
       example = "256m";
       type = types.str;
-      description = ''
+      description = lib.mdDoc ''
         Size limit for the /dev/shm tmpfs. Look at mount(8), tmpfs size option,
         for the accepted syntax.
       '';
@@ -239,7 +239,7 @@ in
       default = "25%";
       example = "256m";
       type = types.str;
-      description = ''
+      description = lib.mdDoc ''
         Size limit for the /run tmpfs. Look at mount(8), tmpfs size option,
         for the accepted syntax.
       '';
diff --git a/nixos/modules/tasks/filesystems/btrfs.nix b/nixos/modules/tasks/filesystems/btrfs.nix
index b7ebc37dd5cf9..4e5180f213535 100644
--- a/nixos/modules/tasks/filesystems/btrfs.nix
+++ b/nixos/modules/tasks/filesystems/btrfs.nix
@@ -24,8 +24,8 @@ in
       fileSystems = mkOption {
         type = types.listOf types.path;
         example = [ "/" ];
-        description = ''
-          List of paths to btrfs filesystems to regularily call <command>btrfs scrub</command> on.
+        description = lib.mdDoc ''
+          List of paths to btrfs filesystems to regularily call {command}`btrfs scrub` on.
           Defaults to all mount points with btrfs filesystems.
           If you mount a filesystem multiple times or additionally mount subvolumes,
           you need to manually specify this list to avoid scrubbing multiple times.
diff --git a/nixos/modules/tasks/filesystems/nfs.nix b/nixos/modules/tasks/filesystems/nfs.nix
index 38c3920a78ada..8c631f0772db1 100644
--- a/nixos/modules/tasks/filesystems/nfs.nix
+++ b/nixos/modules/tasks/filesystems/nfs.nix
@@ -30,9 +30,9 @@ in
       idmapd.settings = mkOption {
         type = format.type;
         default = {};
-        description = ''
+        description = lib.mdDoc ''
           libnfsidmap configuration. Refer to
-          <link xlink:href="https://linux.die.net/man/5/idmapd.conf"/>
+          <https://linux.die.net/man/5/idmapd.conf>
           for details.
         '';
         example = literalExpression ''
@@ -49,7 +49,7 @@ in
       extraConfig = mkOption {
         type = types.lines;
         default = "";
-        description = ''
+        description = lib.mdDoc ''
           Extra nfs-utils configuration.
         '';
       };
diff --git a/nixos/modules/tasks/filesystems/zfs.nix b/nixos/modules/tasks/filesystems/zfs.nix
index 05174e03754b6..795879c6764cd 100644
--- a/nixos/modules/tasks/filesystems/zfs.nix
+++ b/nixos/modules/tasks/filesystems/zfs.nix
@@ -202,7 +202,7 @@ in
         type = types.package;
         default = if config.boot.zfs.enableUnstable then pkgs.zfsUnstable else pkgs.zfs;
         defaultText = literalExpression "if config.boot.zfs.enableUnstable then pkgs.zfsUnstable else pkgs.zfs";
-        description = "Configured ZFS userland tools package.";
+        description = lib.mdDoc "Configured ZFS userland tools package.";
       };
 
       enabled = mkOption {
@@ -210,13 +210,13 @@ in
         type = types.bool;
         default = inInitrd || inSystem;
         defaultText = literalDocBook "<literal>true</literal> if ZFS filesystem support is enabled";
-        description = "True if ZFS filesystem support is enabled";
+        description = lib.mdDoc "True if ZFS filesystem support is enabled";
       };
 
       enableUnstable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Use the unstable zfs package. This might be an option, if the latest
           kernel is not yet supported by a published release of ZFS. Enabling
           this option will install a development version of ZFS on Linux. The
@@ -230,12 +230,12 @@ in
         type = types.listOf types.str;
         default = [];
         example = [ "tank" "data" ];
-        description = ''
+        description = lib.mdDoc ''
           Name or GUID of extra ZFS pools that you wish to import during boot.
 
           Usually this is not necessary. Instead, you should set the mountpoint property
-          of ZFS filesystems to <literal>legacy</literal> and add the ZFS filesystems to
-          NixOS's <option>fileSystems</option> option, which makes NixOS automatically
+          of ZFS filesystems to `legacy` and add the ZFS filesystems to
+          NixOS's {option}`fileSystems` option, which makes NixOS automatically
           import the associated pool.
 
           However, in some cases (e.g. if you have many filesystems) it may be preferable
@@ -248,7 +248,7 @@ in
       devNodes = mkOption {
         type = types.path;
         default = "/dev/disk/by-id";
-        description = ''
+        description = lib.mdDoc ''
           Name of directory from which to import ZFS devices.
 
           This should be a path under /dev containing stable names for all devices needed, as
@@ -259,16 +259,16 @@ in
       forceImportRoot = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Forcibly import the ZFS root pool(s) during early boot.
 
           This is enabled by default for backwards compatibility purposes, but it is highly
           recommended to disable this option, as it bypasses some of the safeguards ZFS uses
           to protect your ZFS pools.
 
-          If you set this option to <literal>false</literal> and NixOS subsequently fails to
+          If you set this option to `false` and NixOS subsequently fails to
           boot because it cannot import the root pool, you should boot with the
-          <literal>zfs_force=1</literal> option as a kernel parameter (e.g. by manually
+          `zfs_force=1` option as a kernel parameter (e.g. by manually
           editing the kernel params in grub during boot). You should only need to do this
           once.
         '';
@@ -291,7 +291,7 @@ in
         type = types.either types.bool (types.listOf types.str);
         default = true;
         example = [ "tank" "data" ];
-        description = ''
+        description = lib.mdDoc ''
           If true on import encryption keys or passwords for all encrypted datasets
           are requested. To only decrypt selected datasets supply a list of dataset
           names instead. For root pools the encryption key can be supplied via both
@@ -304,15 +304,15 @@ in
       enable = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Enable the (OpenSolaris-compatible) ZFS auto-snapshotting service.
-          Note that you must set the <literal>com.sun:auto-snapshot</literal>
-          property to <literal>true</literal> on all datasets which you wish
+          Note that you must set the `com.sun:auto-snapshot`
+          property to `true` on all datasets which you wish
           to auto-snapshot.
 
           You can override a child dataset to use, or not use auto-snapshotting
           by setting its flag with the given interval:
-          <literal>zfs set com.sun:auto-snapshot:weekly=false DATASET</literal>
+          `zfs set com.sun:auto-snapshot:weekly=false DATASET`
         '';
       };
 
@@ -320,14 +320,14 @@ in
         default = "-k -p";
         example = "-k -p --utc";
         type = types.str;
-        description = ''
+        description = lib.mdDoc ''
           Flags to pass to the zfs-auto-snapshot command.
 
-          Run <literal>zfs-auto-snapshot</literal> (without any arguments) to
+          Run `zfs-auto-snapshot` (without any arguments) to
           see available flags.
 
           If it's not too inconvenient for snapshots to have timestamps in UTC,
-          it is suggested that you append <literal>--utc</literal> to the list
+          it is suggested that you append `--utc` to the list
           of default options (see example).
 
           Otherwise, snapshot names can cause name conflicts or apparent time
@@ -338,7 +338,7 @@ in
       frequent = mkOption {
         default = 4;
         type = types.int;
-        description = ''
+        description = lib.mdDoc ''
           Number of frequent (15-minute) auto-snapshots that you wish to keep.
         '';
       };
@@ -346,7 +346,7 @@ in
       hourly = mkOption {
         default = 24;
         type = types.int;
-        description = ''
+        description = lib.mdDoc ''
           Number of hourly auto-snapshots that you wish to keep.
         '';
       };
@@ -354,7 +354,7 @@ in
       daily = mkOption {
         default = 7;
         type = types.int;
-        description = ''
+        description = lib.mdDoc ''
           Number of daily auto-snapshots that you wish to keep.
         '';
       };
@@ -362,7 +362,7 @@ in
       weekly = mkOption {
         default = 4;
         type = types.int;
-        description = ''
+        description = lib.mdDoc ''
           Number of weekly auto-snapshots that you wish to keep.
         '';
       };
@@ -370,7 +370,7 @@ in
       monthly = mkOption {
         default = 12;
         type = types.int;
-        description = ''
+        description = lib.mdDoc ''
           Number of monthly auto-snapshots that you wish to keep.
         '';
       };
@@ -378,7 +378,7 @@ in
 
     services.zfs.trim = {
       enable = mkOption {
-        description = "Whether to enable periodic TRIM on all ZFS pools.";
+        description = lib.mdDoc "Whether to enable periodic TRIM on all ZFS pools.";
         default = true;
         example = false;
         type = types.bool;
@@ -417,7 +417,7 @@ in
         default = [];
         type = types.listOf types.str;
         example = [ "tank" ];
-        description = ''
+        description = lib.mdDoc ''
           List of ZFS pools to periodically scrub. If empty, all pools
           will be scrubbed.
         '';
@@ -464,11 +464,11 @@ in
             ZED_SCRUB_AFTER_RESILVER = false;
           }
         '';
-        description = ''
+        description = lib.mdDoc ''
           ZFS Event Daemon /etc/zfs/zed.d/zed.rc content
 
           See
-          <citerefentry><refentrytitle>zed</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+          {manpage}`zed(8)`
           for details on ZED and the scripts in /etc/zfs/zed.d to find the possible variables
         '';
       };
diff --git a/nixos/modules/tasks/network-interfaces.nix b/nixos/modules/tasks/network-interfaces.nix
index 07bccf98f407f..e6cb2daaffca8 100644
--- a/nixos/modules/tasks/network-interfaces.nix
+++ b/nixos/modules/tasks/network-interfaces.nix
@@ -59,7 +59,7 @@ let
     { options = {
         address = mkOption {
           type = types.str;
-          description = ''
+          description = lib.mdDoc ''
             IPv${toString v} address of the interface. Leave empty to configure the
             interface using DHCP.
           '';
@@ -67,9 +67,9 @@ let
 
         prefixLength = mkOption {
           type = types.addCheck types.int (n: n >= 0 && n <= (if v == 4 then 32 else 128));
-          description = ''
+          description = lib.mdDoc ''
             Subnet mask of the interface, specified as the number of
-            bits in the prefix (<literal>${if v == 4 then "24" else "64"}</literal>).
+            bits in the prefix (`${if v == 4 then "24" else "64"}`).
           '';
         };
       };
@@ -79,14 +79,14 @@ let
   { options = {
       address = mkOption {
         type = types.str;
-        description = "IPv${toString v} address of the network.";
+        description = lib.mdDoc "IPv${toString v} address of the network.";
       };
 
       prefixLength = mkOption {
         type = types.addCheck types.int (n: n >= 0 && n <= (if v == 4 then 32 else 128));
-        description = ''
+        description = lib.mdDoc ''
           Subnet mask of the network, specified as the number of
-          bits in the prefix (<literal>${if v == 4 then "24" else "64"}</literal>).
+          bits in the prefix (`${if v == 4 then "24" else "64"}`).
         '';
       };
 
@@ -95,34 +95,34 @@ let
           "unicast" "local" "broadcast" "multicast"
         ]);
         default = null;
-        description = ''
-          Type of the route.  See the <literal>Route types</literal> section
-          in the <literal>ip-route(8)</literal> manual page for the details.
+        description = lib.mdDoc ''
+          Type of the route.  See the `Route types` section
+          in the `ip-route(8)` manual page for the details.
 
-          Note that <literal>prohibit</literal>, <literal>blackhole</literal>,
-          <literal>unreachable</literal>, and <literal>throw</literal> cannot
+          Note that `prohibit`, `blackhole`,
+          `unreachable`, and `throw` cannot
           be configured per device, so they are not available here. Similarly,
-          <literal>nat</literal> hasn't been supported since kernel 2.6.
+          `nat` hasn't been supported since kernel 2.6.
         '';
       };
 
       via = mkOption {
         type = types.nullOr types.str;
         default = null;
-        description = "IPv${toString v} address of the next hop.";
+        description = lib.mdDoc "IPv${toString v} address of the next hop.";
       };
 
       options = mkOption {
         type = types.attrsOf types.str;
         default = { };
         example = { mtu = "1492"; window = "524288"; };
-        description = ''
-          Other route options. See the symbol <literal>OPTIONS</literal>
-          in the <literal>ip-route(8)</literal> manual page for the details.
-          You may also specify <literal>metric</literal>,
-          <literal>src</literal>, <literal>protocol</literal>,
-          <literal>scope</literal>, <literal>from</literal>
-          and <literal>table</literal>, which are technically
+        description = lib.mdDoc ''
+          Other route options. See the symbol `OPTIONS`
+          in the `ip-route(8)` manual page for the details.
+          You may also specify `metric`,
+          `src`, `protocol`,
+          `scope`, `from`
+          and `table`, which are technically
           not route options, in the sense used in the manual.
         '';
       };
@@ -138,21 +138,21 @@ let
 
       address = mkOption {
         type = types.str;
-        description = "The default gateway address.";
+        description = lib.mdDoc "The default gateway address.";
       };
 
       interface = mkOption {
         type = types.nullOr types.str;
         default = null;
         example = "enp0s3";
-        description = "The default gateway interface.";
+        description = lib.mdDoc "The default gateway interface.";
       };
 
       metric = mkOption {
         type = types.nullOr types.int;
         default = null;
         example = 42;
-        description = "The default gateway metric/preference.";
+        description = lib.mdDoc "The default gateway metric/preference.";
       };
 
     };
@@ -165,7 +165,7 @@ let
       name = mkOption {
         example = "eth0";
         type = types.str;
-        description = "Name of the interface.";
+        description = lib.mdDoc "Name of the interface.";
       };
 
       tempAddress = mkOption {
@@ -189,7 +189,7 @@ let
       useDHCP = mkOption {
         type = types.nullOr types.bool;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Whether this interface should be configured with dhcp.
           Null implies the old behavior which depends on whether ip addresses
           are specified or not.
@@ -203,7 +203,7 @@ let
           { address = "192.168.1.1"; prefixLength = 24; }
         ];
         type = with types; listOf (submodule (addrOpts 4));
-        description = ''
+        description = lib.mdDoc ''
           List of IPv4 addresses that will be statically assigned to the interface.
         '';
       };
@@ -215,7 +215,7 @@ let
           { address = "2001:1470:fffd:2098::e006"; prefixLength = 64; }
         ];
         type = with types; listOf (submodule (addrOpts 6));
-        description = ''
+        description = lib.mdDoc ''
           List of IPv6 addresses that will be statically assigned to the interface.
         '';
       };
@@ -247,7 +247,7 @@ let
           { address = "2001:1470:fffd:2098::"; prefixLength = 64; via = "fdfd:b3f0::1"; }
         ];
         type = with types; listOf (submodule (routeOpts 6));
-        description = ''
+        description = lib.mdDoc ''
           List of extra IPv6 static routes that will be assigned to the interface.
         '';
       };
@@ -256,7 +256,7 @@ let
         default = null;
         example = "00:11:22:33:44:55";
         type = types.nullOr (types.str);
-        description = ''
+        description = lib.mdDoc ''
           MAC address of the interface. Leave empty to use the default.
         '';
       };
@@ -265,7 +265,7 @@ let
         default = null;
         example = 9000;
         type = types.nullOr types.int;
-        description = ''
+        description = lib.mdDoc ''
           MTU size for packets leaving the interface. Leave empty to use the default.
         '';
       };
@@ -273,7 +273,7 @@ let
       virtual = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Whether this interface is virtual and should be created by tunctl.
           This is mainly useful for creating bridges between a host and a virtual
           network such as VPN or a virtual machine.
@@ -283,7 +283,7 @@ let
       virtualOwner = mkOption {
         default = "root";
         type = types.str;
-        description = ''
+        description = lib.mdDoc ''
           In case of a virtual device, the user who owns it.
         '';
       };
@@ -292,7 +292,7 @@ let
         default = if hasPrefix "tun" name then "tun" else "tap";
         defaultText = literalExpression ''if hasPrefix "tun" name then "tun" else "tap"'';
         type = with types; enum [ "tun" "tap" ];
-        description = ''
+        description = lib.mdDoc ''
           The type of interface to create.
           The default is TUN for an interface name starting
           with "tun", otherwise TAP.
@@ -302,7 +302,7 @@ let
       proxyARP = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Turn on proxy_arp for this device.
           This is mainly useful for creating pseudo-bridges between a real
           interface and a virtual network such as VPN or a virtual machine for
@@ -321,7 +321,7 @@ let
         enable = mkOption {
           type = types.bool;
           default = false;
-          description = "Whether to enable wol on this interface.";
+          description = lib.mdDoc "Whether to enable wol on this interface.";
         };
       };
     };
@@ -368,20 +368,20 @@ let
     options = {
 
       name = mkOption {
-        description = "Name of the interface";
+        description = lib.mdDoc "Name of the interface";
         example = "eth0";
         type = types.str;
       };
 
       vlan = mkOption {
-        description = "Vlan tag to apply to interface";
+        description = lib.mdDoc "Vlan tag to apply to interface";
         example = 10;
         type = types.nullOr types.int;
         default = null;
       };
 
       type = mkOption {
-        description = "Openvswitch type to assign to interface";
+        description = lib.mdDoc "Openvswitch type to assign to interface";
         example = "internal";
         type = types.nullOr types.str;
         default = null;
@@ -444,7 +444,7 @@ in
       # reasons (as undocumented feature):
       type = types.strMatching
         "^$|^[[:alnum:]]([[:alnum:]_-]{0,61}[[:alnum:]])?$";
-      description = ''
+      description = lib.mdDoc ''
         The name of the machine. Leave it empty if you want to obtain it from a
         DHCP server (if using DHCP). The hostname must be a valid DNS label (see
         RFC 1035 section 2.3.1: "Preferred name syntax", RFC 1123 section 2.1:
@@ -474,7 +474,7 @@ in
           both networking.hostName and networking.domain are set properly.
         '';
       defaultText = literalExpression ''"''${networking.hostName}.''${networking.domain}"'';
-      description = ''
+      description = lib.mdDoc ''
         The fully qualified domain name (FQDN) of this host. It is the result
         of combining networking.hostName and networking.domain. Using this
         option will result in an evaluation error if the hostname is empty or
@@ -486,17 +486,17 @@ in
       default = null;
       example = "4e98920d";
       type = types.nullOr types.str;
-      description = ''
+      description = lib.mdDoc ''
         The 32-bit host ID of the machine, formatted as 8 hexadecimal characters.
 
         You should try to make this ID unique among your machines. You can
         generate a random 32-bit ID using the following commands:
 
-        <literal>head -c 8 /etc/machine-id</literal>
+        `head -c 8 /etc/machine-id`
 
         (this derives it from the machine-id that systemd generates) or
 
-        <literal>head -c4 /dev/urandom | od -A none -t x4</literal>
+        `head -c4 /dev/urandom | od -A none -t x4`
 
         The primary use case is to ensure when using ZFS that a pool isn't imported
         accidentally on a wrong machine.
@@ -506,7 +506,7 @@ in
     networking.enableIPv6 = mkOption {
       default = true;
       type = types.bool;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable support for IPv6.
       '';
     };
@@ -518,7 +518,7 @@ in
         interface = "enp3s0";
       };
       type = types.nullOr (types.coercedTo types.str gatewayCoerce (types.submodule gatewayOpts));
-      description = ''
+      description = lib.mdDoc ''
         The default gateway. It can be left empty if it is auto-detected through DHCP.
         It can be specified as a string or an option set along with a network interface.
       '';
@@ -531,7 +531,7 @@ in
         interface = "enp3s0";
       };
       type = types.nullOr (types.coercedTo types.str gatewayCoerce (types.submodule gatewayOpts));
-      description = ''
+      description = lib.mdDoc ''
         The default ipv6 gateway. It can be left empty if it is auto-detected through DHCP.
         It can be specified as a string or an option set along with a network interface.
       '';
@@ -541,7 +541,7 @@ in
       default = null;
       example = 524288;
       type = types.nullOr types.int;
-      description = ''
+      description = lib.mdDoc ''
         The window size of the default gateway. It limits maximal data bursts that TCP peers
         are allowed to send to us.
       '';
@@ -551,7 +551,7 @@ in
       type = types.listOf types.str;
       default = [];
       example = ["130.161.158.4" "130.161.33.17"];
-      description = ''
+      description = lib.mdDoc ''
         The list of nameservers.  It can be left empty if it is auto-detected through DHCP.
       '';
     };
@@ -560,7 +560,7 @@ in
       default = [];
       example = [ "example.com" "home.arpa" ];
       type = types.listOf types.str;
-      description = ''
+      description = lib.mdDoc ''
         The list of search paths used when resolving domain names.
       '';
     };
@@ -569,7 +569,7 @@ in
       default = null;
       example = "home.arpa";
       type = types.nullOr types.str;
-      description = ''
+      description = lib.mdDoc ''
         The domain.  It can be left empty if it is auto-detected through DHCP.
       '';
     };
@@ -577,9 +577,9 @@ in
     networking.useHostResolvConf = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         In containers, whether to use the
-        <filename>resolv.conf</filename> supplied by the host.
+        {file}`resolv.conf` supplied by the host.
       '';
     };
 
@@ -587,9 +587,9 @@ in
       type = types.lines;
       default = "";
       example = "text=anything; echo You can put $text here.";
-      description = ''
+      description = lib.mdDoc ''
         Shell commands to be executed at the end of the
-        <literal>network-setup</literal> systemd service.  Note that if
+        `network-setup` systemd service.  Note that if
         you are using DHCP to obtain the network configuration,
         interfaces may not be fully configured yet.
       '';
@@ -603,9 +603,9 @@ in
             prefixLength = 25;
           } ];
         };
-      description = ''
+      description = lib.mdDoc ''
         The configuration for each network interface.  If
-        <option>networking.useDHCP</option> is true, then every
+        {option}`networking.useDHCP` is true, then every
         interface not listed here will be configured using DHCP.
       '';
       type = with types; attrsOf (submodule interfaceOpts);
@@ -618,7 +618,7 @@ in
           vs1.interfaces = [ { name = "eth2"; } { name = "lo2"; type="internal"; } ];
         };
       description =
-        ''
+        lib.mdDoc ''
           This option allows you to define Open vSwitches that connect
           physical networks together. The value of this option is an
           attribute set. Each attribute specifies a vswitch, with the
@@ -631,7 +631,7 @@ in
         options = {
 
           interfaces = mkOption {
-            description = "The physical network interfaces connected by the vSwitch.";
+            description = lib.mdDoc "The physical network interfaces connected by the vSwitch.";
             type = with types; attrsOf (submodule vswitchInterfaceOpts);
           };
 
@@ -639,8 +639,8 @@ in
             type = types.listOf types.str;
             default = [];
             example = [ "ptcp:6653:[::1]" ];
-            description = ''
-              Specify the controller targets. For the allowed options see <literal>man 8 ovs-vsctl</literal>.
+            description = lib.mdDoc ''
+              Specify the controller targets. For the allowed options see `man 8 ovs-vsctl`.
             '';
           };
 
@@ -650,9 +650,9 @@ in
             example = ''
               actions=normal
             '';
-            description = ''
-              OpenFlow rules to insert into the Open vSwitch. All <literal>openFlowRules</literal> are
-              loaded with <literal>ovs-ofctl</literal> within one atomic operation.
+            description = lib.mdDoc ''
+              OpenFlow rules to insert into the Open vSwitch. All `openFlowRules` are
+              loaded with `ovs-ofctl` within one atomic operation.
             '';
           };
 
@@ -661,7 +661,7 @@ in
             type = types.listOf types.str;
             example = [ "OpenFlow10" "OpenFlow13" "OpenFlow14" ];
             default = [ "OpenFlow13" ];
-            description = ''
+            description = lib.mdDoc ''
               Supported versions to enable on this switch.
             '';
           };
@@ -670,8 +670,8 @@ in
           openFlowVersion = mkOption {
             type = types.str;
             default = "OpenFlow13";
-            description = ''
-              Version of OpenFlow protocol to use when communicating with the switch internally (e.g. with <literal>openFlowRules</literal>).
+            description = lib.mdDoc ''
+              Version of OpenFlow protocol to use when communicating with the switch internally (e.g. with `openFlowRules`).
             '';
           };
 
@@ -682,8 +682,8 @@ in
               set-fail-mode <switch_name> secure
               set Bridge <switch_name> stp_enable=true
             '';
-            description = ''
-              Commands to manipulate the Open vSwitch database. Every line executed with <literal>ovs-vsctl</literal>.
+            description = lib.mdDoc ''
+              Commands to manipulate the Open vSwitch database. Every line executed with `ovs-vsctl`.
               All commands are bundled together with the operations for adding the interfaces
               into one atomic operation.
             '';
@@ -702,7 +702,7 @@ in
           br1.interfaces = [ "eth2" "wlan0" ];
         };
       description =
-        ''
+        lib.mdDoc ''
           This option allows you to define Ethernet bridge devices
           that connect physical networks together.  The value of this
           option is an attribute set.  Each attribute specifies a
@@ -718,13 +718,13 @@ in
             example = [ "eth0" "eth1" ];
             type = types.listOf types.str;
             description =
-              "The physical network interfaces connected by the bridge.";
+              lib.mdDoc "The physical network interfaces connected by the bridge.";
           };
 
           rstp = mkOption {
             default = false;
             type = types.bool;
-            description = "Whether the bridge interface should enable rstp.";
+            description = lib.mdDoc "Whether the bridge interface should enable rstp.";
           };
 
         };
@@ -752,7 +752,7 @@ in
             anotherBond.interfaces = [ "enp4s0f0" "enp4s0f1" "enp5s0f0" "enp5s0f1" ];
           }
         '';
-        description = ''
+        description = lib.mdDoc ''
           This option allows you to define bond devices that aggregate multiple,
           underlying networking interfaces together. The value of this option is
           an attribute set. Each attribute specifies a bond, with the attribute
@@ -766,17 +766,17 @@ in
             interfaces = mkOption {
               example = [ "enp4s0f0" "enp4s0f1" "wlan0" ];
               type = types.listOf types.str;
-              description = "The interfaces to bond together";
+              description = lib.mdDoc "The interfaces to bond together";
             };
 
             driverOptions = mkOption {
               type = types.attrsOf types.str;
               default = {};
               example = literalExpression driverOptionsExample;
-              description = ''
+              description = lib.mdDoc ''
                 Options for the bonding driver.
                 Documentation can be found in
-                <link xlink:href="https://www.kernel.org/doc/Documentation/networking/bonding.txt" />
+                <https://www.kernel.org/doc/Documentation/networking/bonding.txt>
               '';
 
             };
@@ -844,7 +844,7 @@ in
           };
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         This option allows you to define macvlan interfaces which should
         be automatically created.
       '';
@@ -854,14 +854,14 @@ in
           interface = mkOption {
             example = "enp4s0";
             type = types.str;
-            description = "The interface the macvlan will transmit packets through.";
+            description = lib.mdDoc "The interface the macvlan will transmit packets through.";
           };
 
           mode = mkOption {
             default = null;
             type = types.nullOr types.str;
             example = "vepa";
-            description = "The mode of the macvlan device.";
+            description = lib.mdDoc "The mode of the macvlan device.";
           };
 
         };
@@ -885,7 +885,7 @@ in
         options = {
           port = mkOption {
             type = port;
-            description = ''
+            description = lib.mdDoc ''
               Local port of the encapsulation UDP socket.
             '';
           };
@@ -893,8 +893,8 @@ in
           protocol = mkOption {
             type = nullOr (ints.between 1 255);
             default = null;
-            description = ''
-              Protocol number of the encapsulated packets. Specifying <literal>null</literal>
+            description = lib.mdDoc ''
+              Protocol number of the encapsulated packets. Specifying `null`
               (the default) creates a GUE endpoint, specifying a protocol number will create
               a FOU endpoint.
             '';
@@ -905,11 +905,11 @@ in
               options = {
                 address = mkOption {
                   type = types.str;
-                  description = ''
+                  description = lib.mdDoc ''
                     Local address to bind to. The address must be available when the FOU
                     endpoint is created, using the scripted network setup this can be achieved
-                    either by setting <literal>dev</literal> or adding dependency information to
-                    <literal>systemd.services.&lt;name&gt;-fou-encap</literal>; it isn't supported
+                    either by setting `dev` or adding dependency information to
+                    `systemd.services.<name>-fou-encap`; it isn't supported
                     when using networkd.
                   '';
                 };
@@ -918,7 +918,7 @@ in
                   type = nullOr str;
                   default = null;
                   example = "eth0";
-                  description = ''
+                  description = lib.mdDoc ''
                     Network device to bind to.
                   '';
                 };
@@ -926,7 +926,7 @@ in
             });
             default = null;
             example = { address = "203.0.113.22"; };
-            description = ''
+            description = lib.mdDoc ''
               Local address (and optionally device) to bind to using the given port.
             '';
           };
@@ -950,7 +950,7 @@ in
           };
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         This option allows you to define 6-to-4 interfaces which should be automatically created.
       '';
       type = with types; attrsOf (submodule {
@@ -960,7 +960,7 @@ in
             type = types.nullOr types.str;
             default = null;
             example = "10.0.0.1";
-            description = ''
+            description = lib.mdDoc ''
               The address of the remote endpoint to forward traffic over.
             '';
           };
@@ -969,7 +969,7 @@ in
             type = types.nullOr types.str;
             default = null;
             example = "10.0.0.22";
-            description = ''
+            description = lib.mdDoc ''
               The address of the local endpoint which the remote
               side should send packets to.
             '';
@@ -979,7 +979,7 @@ in
             type = types.nullOr types.int;
             default = null;
             example = 255;
-            description = ''
+            description = lib.mdDoc ''
               The time-to-live of the connection to the remote tunnel endpoint.
             '';
           };
@@ -988,7 +988,7 @@ in
             type = types.nullOr types.str;
             default = null;
             example = "enp4s0f0";
-            description = ''
+            description = lib.mdDoc ''
               The underlying network device on which the tunnel resides.
             '';
           };
@@ -1008,7 +1008,7 @@ in
                 port = mkOption {
                   type = port;
                   example = 9001;
-                  description = ''
+                  description = lib.mdDoc ''
                     Destination port for encapsulated packets.
                   '';
                 };
@@ -1017,7 +1017,7 @@ in
                   type = nullOr types.port;
                   default = null;
                   example = 9002;
-                  description = ''
+                  description = lib.mdDoc ''
                     Source port for encapsulated packets. Will be chosen automatically by
                     the kernel if unset.
                   '';
@@ -1026,7 +1026,7 @@ in
             });
             default = null;
             example = { type = "fou"; port = 9001; };
-            description = ''
+            description = lib.mdDoc ''
               Configures encapsulation in UDP packets.
             '';
           };
@@ -1056,7 +1056,7 @@ in
           };
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         This option allows you to define Generic Routing Encapsulation (GRE) tunnels.
       '';
       type = with types; attrsOf (submodule {
@@ -1066,7 +1066,7 @@ in
             type = types.nullOr types.str;
             default = null;
             example = "10.0.0.1";
-            description = ''
+            description = lib.mdDoc ''
               The address of the remote endpoint to forward traffic over.
             '';
           };
@@ -1075,7 +1075,7 @@ in
             type = types.nullOr types.str;
             default = null;
             example = "10.0.0.22";
-            description = ''
+            description = lib.mdDoc ''
               The address of the local endpoint which the remote
               side should send packets to.
             '';
@@ -1085,7 +1085,7 @@ in
             type = types.nullOr types.str;
             default = null;
             example = "enp4s0f0";
-            description = ''
+            description = lib.mdDoc ''
               The underlying network device on which the tunnel resides.
             '';
           };
@@ -1094,7 +1094,7 @@ in
             type = types.nullOr types.int;
             default = null;
             example = 255;
-            description = ''
+            description = lib.mdDoc ''
               The time-to-live/hoplimit of the connection to the remote tunnel endpoint.
             '';
           };
@@ -1109,7 +1109,7 @@ in
               tun6 = "ip6gre";
               tap6 = "ip6gretap";
             }.${v};
-            description = ''
+            description = lib.mdDoc ''
               Whether the tunnel routes layer 2 (tap) or layer 3 (tun) traffic.
             '';
           };
@@ -1132,7 +1132,7 @@ in
         }
       '';
       description =
-        ''
+        lib.mdDoc ''
           This option allows you to define vlan devices that tag packets
           on top of a physical interface. The value of this option is an
           attribute set. Each attribute specifies a vlan, with the name
@@ -1146,13 +1146,13 @@ in
           id = mkOption {
             example = 1;
             type = types.int;
-            description = "The vlan identifier";
+            description = lib.mdDoc "The vlan identifier";
           };
 
           interface = mkOption {
             example = "enp4s0";
             type = types.str;
-            description = "The interface the vlan will transmit packets through.";
+            description = lib.mdDoc "The interface the vlan will transmit packets through.";
           };
 
         };
@@ -1184,17 +1184,17 @@ in
         }
       '';
       description =
-        ''
+        lib.mdDoc ''
           Creating multiple WLAN interfaces on top of one physical WLAN device (NIC).
 
           The name of the WLAN interface corresponds to the name of the attribute.
           A NIC is referenced by the persistent device name of the WLAN interface that
-          <literal>udev</literal> assigns to a NIC by default.
+          `udev` assigns to a NIC by default.
           If a NIC supports multiple WLAN interfaces, then the one NIC can be used as
-          <literal>device</literal> for multiple WLAN interfaces.
+          `device` for multiple WLAN interfaces.
           If a NIC is used for creating WLAN interfaces, then the default WLAN interface
-          with a persistent device name form <literal>udev</literal> is not created.
-          A WLAN interface with the persistent name assigned from <literal>udev</literal>
+          with a persistent device name form `udev` is not created.
+          A WLAN interface with the persistent name assigned from `udev`
           would have to be created explicitly.
         '';
 
@@ -1205,14 +1205,14 @@ in
           device = mkOption {
             type = types.str;
             example = "wlp6s0";
-            description = "The name of the underlying hardware WLAN device as assigned by <literal>udev</literal>.";
+            description = lib.mdDoc "The name of the underlying hardware WLAN device as assigned by `udev`.";
           };
 
           type = mkOption {
             type = types.enum [ "managed" "ibss" "monitor" "mesh" "wds" ];
             default = "managed";
             example = "ibss";
-            description = ''
+            description = lib.mdDoc ''
               The type of the WLAN interface.
               The type has to be supported by the underlying hardware of the device.
             '';
@@ -1221,22 +1221,22 @@ in
           meshID = mkOption {
             type = types.nullOr types.str;
             default = null;
-            description = "MeshID of interface with type <literal>mesh</literal>.";
+            description = lib.mdDoc "MeshID of interface with type `mesh`.";
           };
 
           flags = mkOption {
             type = with types; nullOr (enum [ "none" "fcsfail" "control" "otherbss" "cook" "active" ]);
             default = null;
             example = "control";
-            description = ''
-              Flags for interface of type <literal>monitor</literal>.
+            description = lib.mdDoc ''
+              Flags for interface of type `monitor`.
             '';
           };
 
           fourAddr = mkOption {
             type = types.nullOr types.bool;
             default = null;
-            description = "Whether to enable <literal>4-address mode</literal> with type <literal>managed</literal>.";
+            description = lib.mdDoc "Whether to enable `4-address mode` with type `managed`.";
           };
 
           mac = mkOption {
@@ -1266,7 +1266,7 @@ in
     networking.useDHCP = mkOption {
       type = types.bool;
       default = true;
-      description = ''
+      description = lib.mdDoc ''
         Whether to use DHCP to obtain an IP address and other
         configuration for all network interfaces that are not manually
         configured.
@@ -1276,7 +1276,7 @@ in
     networking.useNetworkd = mkOption {
       default = false;
       type = types.bool;
-      description = ''
+      description = lib.mdDoc ''
         Whether we should use networkd as the network configuration backend or
         the legacy script based system. Note that this option is experimental,
         enable at your own risk.
diff --git a/nixos/modules/tasks/trackpoint.nix b/nixos/modules/tasks/trackpoint.nix
index 029d8a0029556..d197a0feb337c 100644
--- a/nixos/modules/tasks/trackpoint.nix
+++ b/nixos/modules/tasks/trackpoint.nix
@@ -12,7 +12,7 @@ with lib;
       enable = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Enable sensitivity and speed configuration for trackpoints.
         '';
       };
@@ -21,7 +21,7 @@ with lib;
         default = 128;
         example = 255;
         type = types.int;
-        description = ''
+        description = lib.mdDoc ''
           Configure the trackpoint sensitivity. By default, the kernel
           configures 128.
         '';
@@ -31,7 +31,7 @@ with lib;
         default = 97;
         example = 255;
         type = types.int;
-        description = ''
+        description = lib.mdDoc ''
           Configure the trackpoint speed. By default, the kernel
           configures 97.
         '';
@@ -40,7 +40,7 @@ with lib;
       emulateWheel = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Enable scrolling while holding the middle mouse button.
         '';
       };
@@ -48,7 +48,7 @@ with lib;
       fakeButtons = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Switch to "bare" PS/2 mouse support in case Trackpoint buttons are not recognized
           properly. This can happen for example on models like the L430, T450, T450s, on
           which the Trackpoint buttons are actually a part of the Synaptics touchpad.
@@ -58,7 +58,7 @@ with lib;
       device = mkOption {
         default = "TPPS/2 IBM TrackPoint";
         type = types.str;
-        description = ''
+        description = lib.mdDoc ''
           The device name of the trackpoint. You can check with xinput.
           Some newer devices (example x1c6) use "TPPS/2 Elan TrackPoint".
         '';