nixos/*: automatically convert option docs

nixos/modules/config/sysctl.nix

···
         { "net.ipv4.tcp_syncookies" = false; "vm.swappiness" = 60; }
       '';
       type = types.attrsOf sysctlOption;
-      description = ''
+      description = lib.mdDoc ''
         Runtime parameters of the Linux kernel, as set by
-        <citerefentry><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>.  Note that sysctl
+        {manpage}`sysctl(8)`.  Note that sysctl
         parameters names must be enclosed in quotes
-        (e.g. <literal>"vm.swappiness"</literal> instead of
-        <literal>vm.swappiness</literal>).  The value of each
+        (e.g. `"vm.swappiness"` instead of
+        `vm.swappiness`).  The value of each
         parameter may be a string, integer, boolean, or null
         (signifying the option will not appear at all).
       '';

nixos/modules/config/system-environment.nix

···
     environment.profileRelativeSessionVariables = mkOption {
       type = types.attrsOf (types.listOf types.str);
       example = { PATH = [ "/bin" ]; MANPATH = [ "/man" "/share/man" ]; };
-      description = ''
+      description = lib.mdDoc ''
         Attribute set of environment variable used in the global
         environment. These variables will be set by PAM early in the
         login process.
 
         Variable substitution is available as described in
-        <citerefentry><refentrytitle>pam_env.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+        {manpage}`pam_env.conf(5)`.
 
         Each attribute maps to a list of relative paths. Each relative
         path is appended to the each profile of
-        <option>environment.profiles</option> to form the content of
+        {option}`environment.profiles` to form the content of
         the corresponding environment variable.
 
         Also, these variables are merged into
-        <xref linkend="opt-environment.profileRelativeEnvVars"/> and it is
+        [](#opt-environment.profileRelativeEnvVars) and it is
         therefore not possible to use PAM style variables such as
-        <literal>@{HOME}</literal>.
+        `@{HOME}`.
       '';
     };
 

nixos/modules/installer/cd-dvd/iso-image.nix

···
 
     isoImage.isoName = mkOption {
       default = "${config.isoImage.isoBaseName}.iso";
-      description = ''
+      description = lib.mdDoc ''
         Name of the generated ISO image file.
       '';
     };
 
     isoImage.isoBaseName = mkOption {
       default = "nixos";
-      description = ''
+      description = lib.mdDoc ''
         Prefix of the name of the generated ISO image file.
       '';
     };
 
     isoImage.compressImage = mkOption {
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether the ISO image should be compressed using
-        <command>zstd</command>.
+        {command}`zstd`.
       '';
     };
 
···
                 + lib.optionalString isAarch "-Xbcj arm"
                 + lib.optionalString (isPower && is32bit && isBigEndian) "-Xbcj powerpc"
                 + lib.optionalString (isSparc) "-Xbcj sparc";
-      description = ''
+      description = lib.mdDoc ''
         Compression settings to use for the squashfs nix store.
       '';
       example = "zstd -Xcompression-level 6";
···
 
     isoImage.edition = mkOption {
       default = "";
-      description = ''
+      description = lib.mdDoc ''
         Specifies which edition string to use in the volume ID of the generated
         ISO image.
       '';
···
     isoImage.volumeID = mkOption {
       # nixos-$EDITION-$RELEASE-$ARCH
       default = "nixos${optionalString (config.isoImage.edition != "") "-${config.isoImage.edition}"}-${config.system.nixos.release}-${pkgs.stdenv.hostPlatform.uname.processor}";
-      description = ''
+      description = lib.mdDoc ''
         Specifies the label or volume ID of the generated ISO image.
         Note that the label is used by stage 1 of the boot process to
         mount the CD, so it should be reasonably distinctive.
···
           }
         ]
       '';
-      description = ''
+      description = lib.mdDoc ''
         This option lists files to be copied to fixed locations in the
         generated ISO image.
       '';
···
 
     isoImage.storeContents = mkOption {
       example = literalExpression "[ pkgs.stdenv ]";
-      description = ''
+      description = lib.mdDoc ''
         This option lists additional derivations to be included in the
         Nix store in the generated ISO image.
       '';
···
 
     isoImage.includeSystemBuildDependencies = mkOption {
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Set this option to include all the needed sources etc in the
         image. It significantly increases image size. Use that when
         you want to be able to keep all the sources needed to build your
···
 
     isoImage.makeEfiBootable = mkOption {
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether the ISO image should be an efi-bootable volume.
       '';
     };
 
     isoImage.makeUsbBootable = mkOption {
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether the ISO image should be bootable from CD as well as USB.
       '';
     };
···
           url = "https://raw.githubusercontent.com/NixOS/nixos-artwork/a9e05d7deb38a8e005a2b52575a3f59a63a4dba0/bootloader/efi-background.png";
           sha256 = "18lfwmp8yq923322nlb9gxrh5qikj1wsk6g5qvdh31c4h5b1538x";
         };
-      description = ''
+      description = lib.mdDoc ''
         The splash image to use in the EFI bootloader.
       '';
     };
···
           url = "https://raw.githubusercontent.com/NixOS/nixos-artwork/a9e05d7deb38a8e005a2b52575a3f59a63a4dba0/bootloader/isolinux/bios-boot.png";
           sha256 = "1wp822zrhbg4fgfbwkr7cbkr4labx477209agzc0hr6k62fr6rxd";
         };
-      description = ''
+      description = lib.mdDoc ''
         The splash image to use in the legacy-boot bootloader.
       '';
     };
···
     isoImage.grubTheme = mkOption {
       default = pkgs.nixos-grub2-theme;
       type = types.nullOr (types.either types.path types.package);
-      description = ''
+      description = lib.mdDoc ''
         The grub2 theme used for UEFI boot.
       '';
     };
···
         MENU COLOR SEL          7;37;40    #FFFFFFFF    #FF5277C3   std
       '';
       type = types.str;
-      description = ''
+      description = lib.mdDoc ''
         The syslinux theme used for BIOS boot.
       '';
     };
···
     isoImage.appendToMenuLabel = mkOption {
       default = " Installer";
       example = " Live System";
-      description = ''
+      description = lib.mdDoc ''
         The string to append after the menu label for the NixOS system.
         This will be directly appended (without whitespace) to the NixOS version
-        string, like for example if it is set to <literal>XXX</literal>:
+        string, like for example if it is set to `XXX`:
 
-        <literal>NixOS 99.99-pre666XXX</literal>
+        `NixOS 99.99-pre666XXX`
       '';
     };
 

nixos/modules/installer/netboot/netboot.nix

···
 
     netboot.storeContents = mkOption {
       example = literalExpression "[ pkgs.stdenv ]";
-      description = ''
+      description = lib.mdDoc ''
         This option lists additional derivations to be included in the
         Nix store in the generated netboot image.
       '';

nixos/modules/misc/documentation.nix

···
       enable = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Whether to install documentation of packages from
-          <option>environment.systemPackages</option> into the generated system path.
+          {option}`environment.systemPackages` into the generated system path.
 
           See "Multiple-output packages" chapter in the nixpkgs manual for more info.
         '';
···
       man.enable = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Whether to install manual pages.
-          This also includes <literal>man</literal> outputs.
+          This also includes `man` outputs.
         '';
       };
 
···
       info.enable = mkOption {
         type = types.bool;
         default = true;
-        description = ''
-          Whether to install info pages and the <command>info</command> command.
+        description = lib.mdDoc ''
+          Whether to install info pages and the {command}`info` command.
           This also includes "info" outputs.
         '';
       };
···
       doc.enable = mkOption {
         type = types.bool;
         default = true;
-        description = ''
-          Whether to install documentation distributed in packages' <literal>/share/doc</literal>.
+        description = lib.mdDoc ''
+          Whether to install documentation distributed in packages' `/share/doc`.
           Usually plain text and/or HTML.
           This also includes "doc" outputs.
         '';
···
       nixos.options.splitBuild = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Whether to split the option docs build into a cacheable and an uncacheable part.
           Splitting the build can substantially decrease the amount of time needed to build
           the manual, but some user modules may be incompatible with this splitting.
···
       nixos.options.warningsAreErrors = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Treat warning emitted during the option documentation build (eg for missing option
           descriptions) as errors.
         '';
···
       nixos.includeAllModules = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether the generated NixOS's documentation should include documentation for all
           the options from all the NixOS modules included in the current
-          <literal>configuration.nix</literal>. Disabling this will make the manual
-          generator to ignore options defined outside of <literal>baseModules</literal>.
+          `configuration.nix`. Disabling this will make the manual
+          generator to ignore options defined outside of `baseModules`.
         '';
       };
 
       nixos.extraModuleSources = mkOption {
         type = types.listOf (types.either types.path types.str);
         default = [ ];
-        description = ''
+        description = lib.mdDoc ''
           Which extra NixOS module paths the generated NixOS's documentation should strip
           from options.
         '';

nixos/modules/misc/locate.nix

···
       type = str;
       default = "02:15";
       example = "hourly";
-      description = ''
+      description = lib.mdDoc ''
         Update the locate database at this interval. Updates by
         default at 2:15 AM every day.
 
         The format is described in
-        <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+        {manpage}`systemd.time(7)`.
 
-        To disable automatic updates, set to <literal>"never"</literal>
-        and run <command>updatedb</command> manually.
+        To disable automatic updates, set to `"never"`
+        and run {command}`updatedb` manually.
       '';
     };
 

nixos/modules/misc/nixpkgs.nix

···
           { allowBroken = true; allowUnfree = true; }
         '';
       type = configType;
-      description = ''
+      description = lib.mdDoc ''
         The configuration of the Nix Packages collection.  (For
         details, see the Nixpkgs documentation.)  It allows you to set
         package configuration options.
 
-        Ignored when <literal>nixpkgs.pkgs</literal> is set.
+        Ignored when `nixpkgs.pkgs` is set.
       '';
     };
 
···
           ]
         '';
       type = types.listOf overlayType;
-      description = ''
+      description = lib.mdDoc ''
         List of overlays to use with the Nix Packages collection.
         (For details, see the Nixpkgs documentation.)  It allows
         you to override packages globally. Each function in the list
-        takes as an argument the <emphasis>original</emphasis> Nixpkgs.
+        takes as an argument the *original* Nixpkgs.
         The first argument should be used for finding dependencies, and
         the second should be used for overriding recipes.
 
-        If <literal>nixpkgs.pkgs</literal> is set, overlays specified here
+        If `nixpkgs.pkgs` is set, overlays specified here
         will be applied after the overlays that were already present
-        in <literal>nixpkgs.pkgs</literal>.
+        in `nixpkgs.pkgs`.
       '';
     };
 
···
       apply = lib.systems.elaborate;
       defaultText = literalExpression
         ''(import "''${nixos}/../lib").lib.systems.examples.aarch64-multiplatform'';
-      description = ''
+      description = lib.mdDoc ''
         Specifies the platform where the NixOS configuration will run.
 
-        To cross-compile, set also <literal>nixpkgs.buildPlatform</literal>.
+        To cross-compile, set also `nixpkgs.buildPlatform`.
 
-        Ignored when <literal>nixpkgs.pkgs</literal> is set.
+        Ignored when `nixpkgs.pkgs` is set.
       '';
     };
 
···
       apply = lib.systems.elaborate;
       defaultText = literalExpression
         ''config.nixpkgs.hostPlatform'';
-      description = ''
+      description = lib.mdDoc ''
         Specifies the platform on which NixOS should be built.
         By default, NixOS is built on the system where it runs, but you can
         change where it's built. Setting this option will cause NixOS to be
···
         or if you're building machines, you can set this to match your
         development system and/or build farm.
 
-        Ignored when <literal>nixpkgs.pkgs</literal> is set.
+        Ignored when `nixpkgs.pkgs` is set.
       '';
     };
 
···
       apply = lib.systems.elaborate;
       defaultText = literalExpression
         ''(import "''${nixos}/../lib").lib.systems.examples.aarch64-multiplatform'';
-      description = ''
-        Systems with a recently generated <literal>hardware-configuration.nix</literal>
+      description = lib.mdDoc ''
+        Systems with a recently generated `hardware-configuration.nix`
         do not need to specify this option, unless cross-compiling, in which case
-        you should set <emphasis>only</emphasis> <option>nixpkgs.buildPlatform</option>.
+        you should set *only* {option}`nixpkgs.buildPlatform`.
 
         If this is somehow not feasible, you may fall back to removing the
-        <option>nixpkgs.hostPlatform</option> line from the generated config and
+        {option}`nixpkgs.hostPlatform` line from the generated config and
         use the old options.
 
         Specifies the platform on which NixOS should be built. When
-        <literal>nixpkgs.crossSystem</literal> is unset, it also specifies
-        the platform <emphasis>for</emphasis> which NixOS should be
+        `nixpkgs.crossSystem` is unset, it also specifies
+        the platform *for* which NixOS should be
         built.  If this option is unset, it defaults to the platform
         type of the machine where evaluation happens. Specifying this
         option is useful when doing distributed multi-platform
         deployment, or when building virtual machines. See its
         description in the Nixpkgs manual for more details.
 
-        Ignored when <literal>nixpkgs.pkgs</literal> or <literal>hostPlatform</literal> is set.
+        Ignored when `nixpkgs.pkgs` or `hostPlatform` is set.
       '';
     };
 
···
       type = types.nullOr types.attrs; # TODO utilize lib.systems.parsedPlatform
       default = null;
       example = { system = "aarch64-linux"; config = "aarch64-unknown-linux-gnu"; };
-      description = ''
-        Systems with a recently generated <literal>hardware-configuration.nix</literal>
-        may instead specify <emphasis>only</emphasis> <option>nixpkgs.buildPlatform</option>,
-        or fall back to removing the <option>nixpkgs.hostPlatform</option> line from the generated config.
+      description = lib.mdDoc ''
+        Systems with a recently generated `hardware-configuration.nix`
+        may instead specify *only* {option}`nixpkgs.buildPlatform`,
+        or fall back to removing the {option}`nixpkgs.hostPlatform` line from the generated config.
 
         Specifies the platform for which NixOS should be
         built. Specify this only if it is different from
-        <literal>nixpkgs.localSystem</literal>, the platform
-        <emphasis>on</emphasis> which NixOS should be built. In other
+        `nixpkgs.localSystem`, the platform
+        *on* which NixOS should be built. In other
         words, specify this to cross-compile NixOS. Otherwise it
         should be set as null, the default. See its description in the
         Nixpkgs manual for more details.
 
-        Ignored when <literal>nixpkgs.pkgs</literal> or <literal>hostPlatform</literal> is set.
+        Ignored when `nixpkgs.pkgs` or `hostPlatform` is set.
       '';
     };
 

nixos/modules/profiles/clone-config.nix

···
 
     installer.cloneConfig = mkOption {
       default = true;
-      description = ''
+      description = lib.mdDoc ''
         Try to clone the installation-device configuration by re-using it's
         profile from the list of imported modules.
       '';
···
     installer.cloneConfigIncludes = mkOption {
       default = [];
       example = [ "./nixos/modules/hardware/network/rt73.nix" ];
-      description = ''
+      description = lib.mdDoc ''
         List of modules used to re-build this installation device profile.
       '';
     };
 
     installer.cloneConfigExtra = mkOption {
       default = "";
-      description = ''
+      description = lib.mdDoc ''
         Extra text to include in the cloned configuration.nix included in this
         installer.
       '';

nixos/modules/security/acme/default.nix

···
       renewInterval = mkOption {
         type = types.str;
         inherit (defaultAndText "renewInterval" "daily") default defaultText;
-        description = ''
+        description = lib.mdDoc ''
           Systemd calendar expression when to check for renewal. See
-          <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+          {manpage}`systemd.time(7)`.
         '';
       };
 

nixos/modules/security/apparmor.nix

···
         if you want this service to do such killing
         by sending a <literal>SIGTERM</literal> to those running processes'';
       policies = mkOption {
-        description = ''
+        description = lib.mdDoc ''
           AppArmor policies.
         '';
         type = types.attrsOf (types.submodule ({ name, config, ... }: {
···
             enable = mkDisableOption "loading of the profile into the kernel";
             enforce = mkDisableOption "enforcing of the policy or only complain in the logs";
             profile = mkOption {
-              description = "The policy of the profile.";
+              description = lib.mdDoc "The policy of the profile.";
               type = types.lines;
               apply = pkgs.writeText name;
             };
···
       includes = mkOption {
         type = types.attrsOf types.lines;
         default = {};
-        description = ''
+        description = lib.mdDoc ''
           List of paths to be added to AppArmor's searched paths
-          when resolving <literal>include</literal> directives.
+          when resolving `include` directives.
         '';
         apply = mapAttrs pkgs.writeText;
       };
       packages = mkOption {
         type = types.listOf types.package;
         default = [];
-        description = "List of packages to be added to AppArmor's include path";
+        description = lib.mdDoc "List of packages to be added to AppArmor's include path";
       };
       enableCache = mkEnableOption ''
         caching of AppArmor policies

nixos/modules/security/pam.nix

···
       control = mkOption {
         default = "sufficient";
         type = types.enum [ "required" "requisite" "sufficient" "optional" ];
-        description = ''
+        description = lib.mdDoc ''
           This option sets pam "control".
           If you want to have multi factor authentication, use "required".
           If you want to use the PKCS#11 device instead of the regular password,
           use "sufficient".
 
           Read
-          <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+          {manpage}`pam.conf(5)`
           for better understanding of this option.
         '';
       };
···
       control = mkOption {
         default = "sufficient";
         type = types.enum [ "required" "requisite" "sufficient" "optional" ];
-        description = ''
+        description = lib.mdDoc ''
           This option sets pam "control".
           If you want to have multi factor authentication, use "required".
           If you want to use U2F device instead of regular password, use "sufficient".
 
           Read
-          <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+          {manpage}`pam.conf(5)`
           for better understanding of this option.
         '';
       };
···
       control = mkOption {
         default = "sufficient";
         type = types.enum [ "required" "requisite" "sufficient" "optional" ];
-        description = ''
+        description = lib.mdDoc ''
           This option sets pam "control".
           If you want to have multi factor authentication, use "required".
           If you want to use the SSH certificate instead of the regular password,
           use "sufficient".
 
           Read
-          <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+          {manpage}`pam.conf(5)`
           for better understanding of this option.
         '';
       };
···
       control = mkOption {
         default = "sufficient";
         type = types.enum [ "required" "requisite" "sufficient" "optional" ];
-        description = ''
+        description = lib.mdDoc ''
           This option sets pam "control".
           If you want to have multi factor authentication, use "required".
           If you want to use Yubikey instead of regular password, use "sufficient".
 
           Read
-          <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+          {manpage}`pam.conf(5)`
           for better understanding of this option.
         '';
       };

nixos/modules/security/systemd-confinement.nix

···
       options.confinement.enable = lib.mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           If set, all the required runtime store paths for this service are
-          bind-mounted into a <literal>tmpfs</literal>-based
-          <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
+          bind-mounted into a `tmpfs`-based
+          {manpage}`chroot(2)`.
         '';
       };
 
···
         default = toplevelConfig.environment.binsh;
         defaultText = lib.literalExpression "config.environment.binsh";
         example = lib.literalExpression ''"''${pkgs.dash}/bin/dash"'';
-        description = ''
-          The program to make available as <filename>/bin/sh</filename> inside
-          the chroot. If this is set to <literal>null</literal>, no
-          <filename>/bin/sh</filename> is provided at all.
+        description = lib.mdDoc ''
+          The program to make available as {file}`/bin/sh` inside
+          the chroot. If this is set to `null`, no
+          {file}`/bin/sh` is provided at all.
 
           This is useful for some applications, which for example use the
-          <citerefentry><refentrytitle>system</refentrytitle><manvolnum>3</manvolnum></citerefentry> library function to execute commands.
+          {manpage}`system(3)` library function to execute commands.
         '';
       };
 

nixos/modules/services/backup/borgbackup.nix

···
           startAt = mkOption {
             type = with types; either str (listOf str);
             default = "daily";
-            description = ''
+            description = lib.mdDoc ''
               When or how often the backup should run.
               Must be in the format described in
-              <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+              {manpage}`systemd.time(7)`.
               If you do not want the backup to start
-              automatically, use <literal>[ ]</literal>.
+              automatically, use `[ ]`.
               It will generate a systemd service borgbackup-job-NAME.
               You may trigger it manually via systemctl restart borgbackup-job-NAME.
             '';
···
             default = false;
             type = types.bool;
             example = true;
-            description = ''
-              Set the <literal>persistentTimer</literal> option for the
-              <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+            description = lib.mdDoc ''
+              Set the `persistentTimer` option for the
+              {manpage}`systemd.timer(5)`
               which triggers the backup immediately if the last trigger
               was missed (e.g. if the system was powered down).
             '';

nixos/modules/services/backup/duplicity.nix

···
       type = types.listOf types.str;
       default = [ ];
       example = [ "/home" ];
-      description = ''
+      description = lib.mdDoc ''
         List of paths to include into the backups. See the FILE SELECTION
-        section in <citerefentry><refentrytitle>duplicity</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details on the syntax.
+        section in {manpage}`duplicity(1)` for details on the syntax.
       '';
     };
 
     exclude = mkOption {
       type = types.listOf types.str;
       default = [ ];
-      description = ''
+      description = lib.mdDoc ''
         List of paths to exclude from backups. See the FILE SELECTION section in
-        <citerefentry><refentrytitle>duplicity</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details on the syntax.
+        {manpage}`duplicity(1)` for details on the syntax.
       '';
     };
 
     targetUrl = mkOption {
       type = types.str;
       example = "s3://host:port/prefix";
-      description = ''
+      description = lib.mdDoc ''
         Target url to backup to. See the URL FORMAT section in
-        <citerefentry><refentrytitle>duplicity</refentrytitle><manvolnum>1</manvolnum></citerefentry> for supported urls.
+        {manpage}`duplicity(1)` for supported urls.
       '';
     };
 
···
     frequency = mkOption {
       type = types.nullOr types.str;
       default = "daily";
-      description = ''
+      description = lib.mdDoc ''
         Run duplicity with the given frequency (see
-        <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for the format).
+        {manpage}`systemd.time(7)` for the format).
         If null, do not run automatically.
       '';
     };
···
       type = types.listOf types.str;
       default = [ ];
       example = [ "--backend-retry-delay" "100" ];
-      description = ''
+      description = lib.mdDoc ''
         Extra command-line flags passed to duplicity. See
-        <citerefentry><refentrytitle>duplicity</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+        {manpage}`duplicity(1)`.
       '';
     };
 

nixos/modules/services/backup/sanoid.nix

···
       type = types.str;
       default = "hourly";
       example = "daily";
-      description = ''
+      description = lib.mdDoc ''
         Run sanoid at this interval. The default is to run hourly.
 
         The format is described in
-        <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+        {manpage}`systemd.time(7)`.
       '';
     };
 

nixos/modules/services/backup/syncoid.nix

···
       type = types.str;
       default = "hourly";
       example = "*-*-* *:15:00";
-      description = ''
+      description = lib.mdDoc ''
         Run syncoid at this interval. The default is to run hourly.
 
         The format is described in
-        <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+        {manpage}`systemd.time(7)`.
       '';
     };
 

nixos/modules/services/backup/tarsnap.nix

···
                 type = types.str;
                 default = "01:15";
                 example = "hourly";
-                description = ''
+                description = lib.mdDoc ''
                   Create archive at this interval.
 
                   The format is described in
-                  <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+                  {manpage}`systemd.time(7)`.
                 '';
               };
 

nixos/modules/services/cluster/hadoop/default.nix

···
           "fs.defaultFS" = "hdfs://localhost";
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         Hadoop core-site.xml definition
-        <link xlink:href="https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-common/core-default.xml"/>
+        <https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-common/core-default.xml>
       '';
     };
     coreSiteInternal = mkOption {
···
         "dfs.namenode.http-bind-host" = "0.0.0.0";
       };
       type = types.attrsOf types.anything;
-      description = ''
+      description = lib.mdDoc ''
         Default options for hdfs-site.xml
       '';
     };
···
           "dfs.nameservices" = "namenode1";
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         Additional options and overrides for hdfs-site.xml
-        <link xlink:href="https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-hdfs/hdfs-default.xml"/>
+        <https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-hdfs/hdfs-default.xml>
       '';
     };
     hdfsSiteInternal = mkOption {
···
         }
       '';
       type = types.attrsOf types.anything;
-      description = ''
+      description = lib.mdDoc ''
         Default options for mapred-site.xml
       '';
     };
···
           "mapreduce.map.java.opts" = "-Xmx900m -XX:+UseParallelGC";
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         Additional options and overrides for mapred-site.xml
-        <link xlink:href="https://hadoop.apache.org/docs/current/hadoop-mapreduce-client/hadoop-mapreduce-client-core/mapred-default.xml"/>
+        <https://hadoop.apache.org/docs/current/hadoop-mapreduce-client/hadoop-mapreduce-client-core/mapred-default.xml>
       '';
     };
 
···
         "yarn.resourcemanager.scheduler.class" = "org.apache.hadoop.yarn.server.resourcemanager.scheduler.fair.FairScheduler";
       };
       type = types.attrsOf types.anything;
-      description = ''
+      description = lib.mdDoc ''
         Default options for yarn-site.xml
       '';
     };
···
           "yarn.resourcemanager.hostname" = "''${config.networking.hostName}";
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         Additional options and overrides for yarn-site.xml
-        <link xlink:href="https://hadoop.apache.org/docs/current/hadoop-yarn/hadoop-yarn-common/yarn-default.xml"/>
+        <https://hadoop.apache.org/docs/current/hadoop-yarn/hadoop-yarn-common/yarn-default.xml>
       '';
     };
     yarnSiteInternal = mkOption {
···
           "hadoop.http.max.threads" = 500;
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         Hadoop httpfs-site.xml definition
-        <link xlink:href="https://hadoop.apache.org/docs/current/hadoop-hdfs-httpfs/httpfs-default.html"/>
+        <https://hadoop.apache.org/docs/current/hadoop-hdfs-httpfs/httpfs-default.html>
       '';
     };
 
···
       example = literalExpression ''
         "''${pkgs.hadoop}/lib/''${pkgs.hadoop.untarDir}/etc/hadoop/log4j.properties";
       '';
-      description = "log4j.properties file added to HADOOP_CONF_DIR";
+      description = lib.mdDoc "log4j.properties file added to HADOOP_CONF_DIR";
     };
 
     containerExecutorCfg = mkOption {
···
           "feature.terminal.enabled" = 0;
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         Yarn container-executor.cfg definition
-        <link xlink:href="https://hadoop.apache.org/docs/r2.7.2/hadoop-yarn/hadoop-yarn-site/SecureContainer.html"/>
+        <https://hadoop.apache.org/docs/r2.7.2/hadoop-yarn/hadoop-yarn-site/SecureContainer.html>
       '';
     };
 
···
           ./extraYARNConfs
         ]
       '';
-      description = "Directories containing additional config files to be added to HADOOP_CONF_DIR";
+      description = lib.mdDoc "Directories containing additional config files to be added to HADOOP_CONF_DIR";
     };
 
     gatewayRole.enable = mkEnableOption "gateway role for deploying hadoop configs";

nixos/modules/services/computing/slurm/slurm.nix

···
         extraConfig = mkOption {
           type = types.lines;
           default = "";
-          description = ''
-            Extra configuration for <literal>slurmdbd.conf</literal> See also:
-            <citerefentry><refentrytitle>slurmdbd.conf</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+          description = lib.mdDoc ''
+            Extra configuration for `slurmdbd.conf` See also:
+            {manpage}`slurmdbd.conf(8)`.
           '';
         };
       };

nixos/modules/services/databases/rethinkdb.nix

···
 
       user = mkOption {
         default = "rethinkdb";
-        description = "User account under which RethinkDB runs.";
+        description = lib.mdDoc "User account under which RethinkDB runs.";
       };
 
       group = mkOption {
         default = "rethinkdb";
-        description = "Group which rethinkdb user belongs to.";
+        description = lib.mdDoc "Group which rethinkdb user belongs to.";
       };
 
       dbpath = mkOption {
         default = "/var/db/rethinkdb";
-        description = "Location where RethinkDB stores its data, 1 data directory per instance.";
+        description = lib.mdDoc "Location where RethinkDB stores its data, 1 data directory per instance.";
       };
 
       pidpath = mkOption {
         default = "/run/rethinkdb";
-        description = "Location where each instance's pid file is located.";
+        description = lib.mdDoc "Location where each instance's pid file is located.";
       };
 
       #cfgpath = mkOption {

nixos/modules/services/desktops/pipewire/pipewire-media-session.nix

···
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = "Whether to enable the deprecated example Pipewire session manager";
+        description = lib.mdDoc "Whether to enable the deprecated example Pipewire session manager";
       };
 
       package = mkOption {
         type = types.package;
         default = pkgs.pipewire-media-session;
         defaultText = literalExpression "pkgs.pipewire-media-session";
-        description = ''
+        description = lib.mdDoc ''
           The pipewire-media-session derivation to use.
         '';
       };
···
       config = {
         media-session = mkOption {
           type = json.type;
-          description = ''
+          description = lib.mdDoc ''
             Configuration for the media session core. For details see
             https://gitlab.freedesktop.org/pipewire/media-session/-/blob/${cfg.package.version}/src/daemon/media-session.d/media-session.conf
           '';
···
 
         alsa-monitor = mkOption {
           type = json.type;
-          description = ''
+          description = lib.mdDoc ''
             Configuration for the alsa monitor. For details see
             https://gitlab.freedesktop.org/pipewire/media-session/-/blob/${cfg.package.version}/src/daemon/media-session.d/alsa-monitor.conf
           '';
···
 
         bluez-monitor = mkOption {
           type = json.type;
-          description = ''
+          description = lib.mdDoc ''
             Configuration for the bluez5 monitor. For details see
             https://gitlab.freedesktop.org/pipewire/media-session/-/blob/${cfg.package.version}/src/daemon/media-session.d/bluez-monitor.conf
           '';
···
 
         v4l2-monitor = mkOption {
           type = json.type;
-          description = ''
+          description = lib.mdDoc ''
             Configuration for the V4L2 monitor. For details see
             https://gitlab.freedesktop.org/pipewire/media-session/-/blob/${cfg.package.version}/src/daemon/media-session.d/v4l2-monitor.conf
           '';

nixos/modules/services/development/jupyter/default.nix

···
     ip = mkOption {
       type = types.str;
       default = "localhost";
-      description = ''
+      description = lib.mdDoc ''
         IP address Jupyter will be listening on.
       '';
     };
···
       # saving a rebuild.
       default = pkgs.python3.pkgs.notebook;
       defaultText = literalExpression "pkgs.python3.pkgs.notebook";
-      description = ''
+      description = lib.mdDoc ''
         Jupyter package to use.
       '';
     };
···
       type = types.str;
       default = "jupyter-notebook";
       example = "jupyter-lab";
-      description = ''
+      description = lib.mdDoc ''
         Which command the service runs. Note that not all jupyter packages
         have all commands, e.g. jupyter-lab isn't present in the default package.
        '';
···
     port = mkOption {
       type = types.int;
       default = 8888;
-      description = ''
+      description = lib.mdDoc ''
         Port number Jupyter will be listening on.
       '';
     };
···
     notebookDir = mkOption {
       type = types.str;
       default = "~/";
-      description = ''
+      description = lib.mdDoc ''
         Root directory for notebooks.
       '';
     };
···
     user = mkOption {
       type = types.str;
       default = "jupyter";
-      description = ''
+      description = lib.mdDoc ''
         Name of the user used to run the jupyter service.
         For security reason, jupyter should really not be run as root.
         If not set (jupyter), the service will create a jupyter user with appropriate settings.
···
     group = mkOption {
       type = types.str;
       default = "jupyter";
-      description = ''
+      description = lib.mdDoc ''
         Name of the group used to run the jupyter service.
         Use this if you want to create a group of users that are able to view the notebook directory's content.
       '';
···
 
     password = mkOption {
       type = types.str;
-      description = ''
+      description = lib.mdDoc ''
         Password to use with notebook.
         Can be generated using:
           In [1]: from notebook.auth import passwd
···
     notebookConfig = mkOption {
       type = types.lines;
       default = "";
-      description = ''
+      description = lib.mdDoc ''
         Raw jupyter config.
       '';
     };

nixos/modules/services/development/jupyter/kernel-options.nix

···
         "Python 3"
         "Python 3 for Data Science"
       '';
-      description = ''
+      description = lib.mdDoc ''
         Name that will be shown to the user.
       '';
     };
···
         "-f"
         "{connection_file}"
       ];
-      description = ''
+      description = lib.mdDoc ''
         Command and arguments to start the kernel.
       '';
     };
···
     language = mkOption {
       type = types.str;
       example = "python";
-      description = ''
+      description = lib.mdDoc ''
         Language of the environment. Typically the name of the binary.
       '';
     };
···
       type = types.nullOr types.path;
       default = null;
       example = literalExpression ''"''${env.sitePackages}/ipykernel/resources/logo-32x32.png"'';
-      description = ''
+      description = lib.mdDoc ''
         Path to 32x32 logo png.
       '';
     };
···
       type = types.nullOr types.path;
       default = null;
       example = literalExpression ''"''${env.sitePackages}/ipykernel/resources/logo-64x64.png"'';
-      description = ''
+      description = lib.mdDoc ''
         Path to 64x64 logo png.
       '';
     };
···
       type = types.attrsOf types.path;
       default = { };
       example = literalExpression ''"{ examples = ''${env.sitePack}/IRkernel/kernelspec/kernel.js"; }'';
-      description = ''
+      description = lib.mdDoc ''
         Extra paths to link in kernel directory
       '';
     };

nixos/modules/services/development/jupyterhub/default.nix

···
     authentication = mkOption {
       type = types.str;
       default = "jupyterhub.auth.PAMAuthenticator";
-      description = ''
+      description = lib.mdDoc ''
         Jupyterhub authentication to use
 
         There are many authenticators available including: oauth, pam,
···
     spawner = mkOption {
       type = types.str;
       default = "systemdspawner.SystemdSpawner";
-      description = ''
+      description = lib.mdDoc ''
         Jupyterhub spawner to use
 
         There are many spawners available including: local process,
···
     extraConfig = mkOption {
       type = types.lines;
       default = "";
-      description = ''
+      description = lib.mdDoc ''
         Extra contents appended to the jupyterhub configuration
 
         Jupyterhub configuration is a normal python file using
···
           jupyterhub-systemdspawner
         ])
       '';
-      description = ''
+      description = lib.mdDoc ''
         Python environment to run jupyterhub
 
         Customizing will affect the packages available in the hub and
···
           jupyterlab
         ])
       '';
-      description = ''
+      description = lib.mdDoc ''
         Python environment to run jupyterlab
 
         Customizing will affect the packages available in the
···
           };
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         Declarative kernel config
 
         Kernels can be declared in any language that supports and has
···
     port = mkOption {
       type = types.port;
       default = 8000;
-      description = ''
+      description = lib.mdDoc ''
         Port number Jupyterhub will be listening on
       '';
     };
···
     host = mkOption {
       type = types.str;
       default = "0.0.0.0";
-      description = ''
+      description = lib.mdDoc ''
         Bind IP JupyterHub will be listening on
       '';
     };
···
     stateDirectory = mkOption {
       type = types.str;
       default = "jupyterhub";
-      description = ''
+      description = lib.mdDoc ''
         Directory for jupyterhub state (token + database)
       '';
     };

nixos/modules/services/hardware/pcscd.nix

···
         LIBPATH           /path/to/serial_reader.so
         CHANNELID         1
       '';
-      description = ''
+      description = lib.mdDoc ''
         Configuration for devices that aren't hotpluggable.
 
-        See <citerefentry><refentrytitle>reader.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for valid options.
+        See {manpage}`reader.conf(5)` for valid options.
       '';
     };
   };

nixos/modules/services/logging/awstats.nix

···
       type = types.nullOr types.str;
       default = null;
       example = "hourly";
-      description = ''
+      description = lib.mdDoc ''
         Specification of the time at which awstats will get updated.
-        (in the format described by <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
+        (in the format described by {manpage}`systemd.time(7)`)
       '';
     };
   };

nixos/modules/services/mail/mlmmj.nix

···
       maintInterval = mkOption {
         type = types.str;
         default = "20min";
-        description = ''
+        description = lib.mdDoc ''
           Time interval between mlmmj-maintd runs, see
-          <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for format information.
+          {manpage}`systemd.time(7)` for format information.
         '';
       };
 

nixos/modules/services/mail/postfix.nix

···
       canonical = mkOption {
         type = types.lines;
         default = "";
-        description = ''
-          Entries for the <citerefentry><refentrytitle>canonical</refentrytitle><manvolnum>5</manvolnum></citerefentry> table.
+        description = lib.mdDoc ''
+          Entries for the {manpage}`canonical(5)` table.
         '';
       };
 

nixos/modules/services/matrix/mjolnir.nix

···
     homeserverUrl = mkOption {
       type = types.str;
       default = "https://matrix.org";
-      description = ''
+      description = lib.mdDoc ''
         Where the homeserver is located (client-server URL).
 
-        If <literal>pantalaimon.enable</literal> is <literal>true</literal>, this option will become the homeserver to which <literal>pantalaimon</literal> connects.
-        The listen address of <literal>pantalaimon</literal> will then become the <literal>homeserverUrl</literal> of <literal>mjolnir</literal>.
+        If `pantalaimon.enable` is `true`, this option will become the homeserver to which `pantalaimon` connects.
+        The listen address of `pantalaimon` will then become the `homeserverUrl` of `mjolnir`.
       '';
     };
 
     accessTokenFile = mkOption {
       type = with types; nullOr path;
       default = null;
-      description = ''
-        File containing the matrix access token for the <literal>mjolnir</literal> user.
+      description = lib.mdDoc ''
+        File containing the matrix access token for the `mjolnir` user.
       '';
     };
 
     pantalaimon = mkOption {
-      description = ''
-        <literal>pantalaimon</literal> options (enables E2E Encryption support).
+      description = lib.mdDoc ''
+        `pantalaimon` options (enables E2E Encryption support).
 
-        This will create a <literal>pantalaimon</literal> instance with the name "mjolnir".
+        This will create a `pantalaimon` instance with the name "mjolnir".
       '';
       default = { };
       type = types.submodule {
···
 
           username = mkOption {
             type = types.str;
-            description = "The username to login with.";
+            description = lib.mdDoc "The username to login with.";
           };
 
           passwordFile = mkOption {
             type = with types; nullOr path;
             default = null;
-            description = ''
-              File containing the matrix password for the <literal>mjolnir</literal> user.
+            description = lib.mdDoc ''
+              File containing the matrix password for the `mjolnir` user.
             '';
           };
 
           options = mkOption {
             type = types.submodule (import ./pantalaimon-options.nix);
             default = { };
-            description = ''
-              passthrough additional options to the <literal>pantalaimon</literal> service.
+            description = lib.mdDoc ''
+              passthrough additional options to the `pantalaimon` service.
             '';
           };
         };
···
     dataPath = mkOption {
       type = types.path;
       default = "/var/lib/mjolnir";
-      description = ''
+      description = lib.mdDoc ''
         The directory the bot should store various bits of information in.
       '';
     };
···
     managementRoom = mkOption {
       type = types.str;
       default = "#moderators:example.org";
-      description = ''
+      description = lib.mdDoc ''
         The room ID where people can use the bot. The bot has no access controls, so
         anyone in this room can use the bot - secure your room!
         This should be a room alias or room ID - not a matrix.to URL.
-        Note: <literal>mjolnir</literal> is fairly verbose - expect a lot of messages from it.
+        Note: `mjolnir` is fairly verbose - expect a lot of messages from it.
       '';
     };
 
···
           "https://matrix.to/#/#anotherroom:example.org"
         ]
       '';
-      description = ''
+      description = lib.mdDoc ''
         A list of rooms to protect (matrix.to URLs).
       '';
     };
···
           automaticallyRedactForReasons = [ "spam" "advertising" ];
         }
       '';
-      description = ''
-        Additional settings (see <link xlink:href="https://github.com/matrix-org/mjolnir/blob/main/config/default.yaml">mjolnir default config</link> for available settings). These settings will override settings made by the module config.
+      description = lib.mdDoc ''
+        Additional settings (see [mjolnir default config](https://github.com/matrix-org/mjolnir/blob/main/config/default.yaml) for available settings). These settings will override settings made by the module config.
       '';
     };
   };

nixos/modules/services/matrix/pantalaimon-options.nix

···
     dataPath = mkOption {
       type = types.path;
       default = "/var/lib/pantalaimon-${name}";
-      description = ''
-        The directory where <literal>pantalaimon</literal> should store its state such as the database file.
+      description = lib.mdDoc ''
+        The directory where `pantalaimon` should store its state such as the database file.
       '';
     };
 
     logLevel = mkOption {
       type = types.enum [ "info" "warning" "error" "debug" ];
       default = "warning";
-      description = ''
+      description = lib.mdDoc ''
         Set the log level of the daemon.
       '';
     };
···
     homeserver = mkOption {
       type = types.str;
       example = "https://matrix.org";
-      description = ''
-        The URI of the homeserver that the <literal>pantalaimon</literal> proxy should
+      description = lib.mdDoc ''
+        The URI of the homeserver that the `pantalaimon` proxy should
         forward requests to, without the matrix API path but including
         the http(s) schema.
       '';
···
     ssl = mkOption {
       type = types.bool;
       default = true;
-      description = ''
+      description = lib.mdDoc ''
         Whether or not SSL verification should be enabled for outgoing
         connections to the homeserver.
       '';
···
     listenAddress = mkOption {
       type = types.str;
       default = "localhost";
-      description = ''
+      description = lib.mdDoc ''
         The address where the daemon will listen to client connections
         for this homeserver.
       '';
···
     listenPort = mkOption {
       type = types.port;
       default = 8009;
-      description = ''
+      description = lib.mdDoc ''
         The port where the daemon will listen to client connections for
         this homeserver. Note that the listen address/port combination
         needs to be unique between different homeservers.
···
     extraSettings = mkOption {
       type = types.attrs;
       default = { };
-      description = ''
+      description = lib.mdDoc ''
         Extra configuration options. See
-        <link xlink:href="https://github.com/matrix-org/pantalaimon/blob/master/docs/man/pantalaimon.5.md">pantalaimon(5)</link>
+        [pantalaimon(5)](https://github.com/matrix-org/pantalaimon/blob/master/docs/man/pantalaimon.5.md)
         for available options.
       '';
     };

nixos/modules/services/matrix/pantalaimon.nix

···
   options.services.pantalaimon-headless.instances = mkOption {
     default = { };
     type = types.attrsOf (types.submodule (import ./pantalaimon-options.nix));
-    description = ''
+    description = lib.mdDoc ''
       Declarative instance config.
 
       Note: to use pantalaimon interactively, e.g. for a Matrix client which does not
-      support End-to-end encryption (like <literal>fractal</literal>), refer to the home-manager module.
+      support End-to-end encryption (like `fractal`), refer to the home-manager module.
     '';
   };
 

nixos/modules/services/matrix/synapse.nix

···
       configFile = mkOption {
         type = types.path;
         readOnly = true;
-        description = ''
+        description = lib.mdDoc ''
           Path to the configuration file on the target system. Useful to configure e.g. workers
           that also need this.
         '';
···
         type = types.package;
         default = pkgs.matrix-synapse;
         defaultText = literalExpression "pkgs.matrix-synapse";
-        description = ''
+        description = lib.mdDoc ''
           Overridable attribute of the matrix synapse server package to use.
         '';
       };
···
             matrix-synapse-pam
           ];
         '';
-        description = ''
+        description = lib.mdDoc ''
           List of additional Matrix plugins to make available.
         '';
       };
···
       withJemalloc = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to preload jemalloc to reduce memory fragmentation and overall usage.
         '';
       };
···
       dataDir = mkOption {
         type = types.str;
         default = "/var/lib/matrix-synapse";
-        description = ''
+        description = lib.mdDoc ''
           The directory where matrix-synapse stores its stateful data such as
           certificates, media and uploads.
         '';
···
               example = "example.com";
               default = config.networking.hostName;
               defaultText = literalExpression "config.networking.hostName";
-              description = ''
+              description = lib.mdDoc ''
                 The domain name of the server, with optional explicit port.
                 This is used by remote servers to look up the server address.
                 This is also the last part of your UserID.
···
             enable_registration = mkOption {
               type = types.bool;
               default = false;
-              description = ''
+              description = lib.mdDoc ''
                 Enable registration for new users.
               '';
             };
···
             enable_metrics = mkOption {
               type = types.bool;
               default = false;
-              description = ''
+              description = lib.mdDoc ''
                 Enable collection and rendering of performance metrics
               '';
             };
···
             report_stats = mkOption {
               type = types.bool;
               default = false;
-              description = ''
+              description = lib.mdDoc ''
                 Whether or not to report anonymized homeserver usage statistics.
               '';
             };
···
             signing_key_path = mkOption {
               type = types.path;
               default = "${cfg.dataDir}/homeserver.signing.key";
-              description = ''
+              description = lib.mdDoc ''
                 Path to the signing key to sign messages with.
               '';
             };
···
               type = types.path;
               default = "/run/matrix-synapse.pid";
               readOnly = true;
-              description = ''
+              description = lib.mdDoc ''
                 The file to store the PID in.
               '';
             };
···
             log_config = mkOption {
               type = types.path;
               default = ./synapse-log_config.yaml;
-              description = ''
+              description = lib.mdDoc ''
                 The file that holds the logging configuration.
               '';
             };
···
                 then "${cfg.dataDir}/media_store"
                 else "${cfg.dataDir}/media";
               defaultText = "${cfg.dataDir}/media_store for when system.stateVersion is at least 22.05, ${cfg.dataDir}/media when lower than 22.05";
-              description = ''
+              description = lib.mdDoc ''
                 Directory where uploaded images and attachments are stored.
               '';
             };
···
               type = types.nullOr types.str;
               default = null;
               example = "https://example.com:8448/";
-              description = ''
+              description = lib.mdDoc ''
                 The public-facing base URL for the client API (not including _matrix/...)
               '';
             };
···
               type = types.nullOr types.str;
               default = null;
               example = "/var/lib/acme/example.com/fullchain.pem";
-              description = ''
+              description = lib.mdDoc ''
                 PEM encoded X509 certificate for TLS.
                 You can replace the self-signed certificate that synapse
                 autogenerates on launch with your own SSL certificate + key pair
···
               type = types.nullOr types.str;
               default = null;
               example = "/var/lib/acme/example.com/key.pem";
-              description = ''
+              description = lib.mdDoc ''
                 PEM encoded private key for TLS. Specify null if synapse is not
                 speaking TLS directly.
               '';
···
               type = types.bool;
               default = true;
               example = false;
-              description = ''
+              description = lib.mdDoc ''
                 Whether to enable presence tracking.
 
                 Presence tracking allows users to see the state (e.g online/offline)
···
                   port = mkOption {
                     type = types.port;
                     example = 8448;
-                    description = ''
+                    description = lib.mdDoc ''
                       The port to listen for HTTP(S) requests on.
                     '';
                   };
···
                       "0.0.0.0"
                     ]
                     '';
-                    description = ''
+                    description = lib.mdDoc ''
                      IP addresses to bind the listener to.
                     '';
                   };
···
                     ];
                     default = "http";
                     example = "metrics";
-                    description = ''
+                    description = lib.mdDoc ''
                       The type of the listener, usually http.
                     '';
                   };
···
                     type = types.bool;
                     default = true;
                     example = false;
-                    description = ''
+                    description = lib.mdDoc ''
                       Whether to enable TLS on the listener socket.
                     '';
                   };
···
                     type = types.bool;
                     default = false;
                     example = true;
-                    description = ''
+                    description = lib.mdDoc ''
                       Use the X-Forwarded-For (XFF) header as the client IP and not the
                       actual client IP.
                     '';
···
                             "replication"
                             "static"
                           ]);
-                          description = ''
+                          description = lib.mdDoc ''
                             List of resources to host on this listener.
                           '';
                           example = [
···
                         };
                         compress = mkOption {
                           type = types.bool;
-                          description = ''
+                          description = lib.mdDoc ''
                             Should synapse compress HTTP responses to clients that support it?
                             This should be disabled if running synapse behind a load balancer
                             that can do automatic compression.
···
                         };
                       };
                     });
-                    description = ''
+                    description = lib.mdDoc ''
                       List of HTTP resources to serve on this listener.
                     '';
                   };
···
                   compress = false;
                 } ];
               } ];
-              description = ''
+              description = lib.mdDoc ''
                 List of ports that Synapse should listen on, their purpose and their configuration.
               '';
             };
···
                 then "psycopg2"
                 else "sqlite3"
               '';
-              description = ''
+              description = lib.mdDoc ''
                 The database engine name. Can be sqlite3 or psycopg2.
               '';
             };
···
                 psycopg2 = "matrix-synapse";
               }.''${${options.services.matrix-synapse.settings}.database.name};
               '';
-              description = ''
+              description = lib.mdDoc ''
                 Name of the database when using the psycopg2 backend,
                 path to the database location when using sqlite3.
               '';
···
                 sqlite3 = null;
                 psycopg2 = "matrix-synapse";
               }.${cfg.settings.database.name};
-              description = ''
+              description = lib.mdDoc ''
                 Username to connect with psycopg2, set to null
                 when using sqlite3.
               '';
···
                 "fec0::/10"
                 "ff00::/8"
               ];
-              description = ''
+              description = lib.mdDoc ''
                 List of IP address CIDR ranges that the URL preview spider is denied
                 from accessing.
               '';
···
             url_preview_ip_range_whitelist = mkOption {
               type = types.listOf types.str;
               default = [];
-              description = ''
+              description = lib.mdDoc ''
                 List of IP address CIDR ranges that the URL preview spider is allowed
                 to access even if they are specified in url_preview_ip_range_blacklist.
               '';
···
             url_preview_url_blacklist = mkOption {
               type = types.listOf types.str;
               default = [];
-              description = ''
+              description = lib.mdDoc ''
                 Optional list of URL matches that the URL preview spider is
                 denied from accessing.
               '';
···
               type = types.str;
               default = "50M";
               example = "100M";
-              description = ''
+              description = lib.mdDoc ''
                 The largest allowed upload size in bytes
               '';
             };
···
               type = types.str;
               default = "32M";
               example = "64M";
-              description = ''
+              description = lib.mdDoc ''
                 Maximum number of pixels that will be thumbnailed
               '';
             };
···
               type = types.bool;
               default = false;
               example = true;
-              description = ''
+              description = lib.mdDoc ''
                 Whether to generate new thumbnails on the fly to precisely match
                 the resolution requested by the client. If true then whenever
                 a new resolution is requested by the client the server will
···
                 "turns:turn.example.com:5349?transport=udp"
                 "turns:turn.example.com:5349?transport=tcp"
               ];
-              description = ''
+              description = lib.mdDoc ''
                 The public URIs of the TURN server to give to clients
               '';
             };
···
                   server_name = mkOption {
                     type = types.str;
                     example = "matrix.org";
-                    description = ''
+                    description = lib.mdDoc ''
                       Hostname of the trusted server.
                     '';
                   };
···
                         "ed25519:auto" = "Noi6WqcDj0QmPxCNQqgezwTlBKrfqehY1u2FyWP9uYw";
                       }
                     '';
-                    description = ''
+                    description = lib.mdDoc ''
                       Attribute set from key id to base64 encoded public key.
 
                       If specified synapse will check that the response is signed
···
                   "ed25519:auto" = "Noi6WqcDj0QmPxCNQqgezwTlBKrfqehY1u2FyWP9uYw";
                 };
               } ];
-              description = ''
+              description = lib.mdDoc ''
                 The trusted servers to download signing keys from.
               '';
             };
···
             app_service_config_files = mkOption {
               type = types.listOf types.path;
               default = [ ];
-              description = ''
+              description = lib.mdDoc ''
                 A list of application service config file to use
               '';
             };
···
       extraConfigFiles = mkOption {
         type = types.listOf types.path;
         default = [];
-        description = ''
+        description = lib.mdDoc ''
           Extra config files to include.
 
           The configuration files will be included based on the command line

nixos/modules/services/misc/autorandr.nix

···
             [ 0.0 0.0 1.0 ]
           ]
         '';
-        description = ''
+        description = lib.mdDoc ''
           Refer to
-          <citerefentry><refentrytitle>xrandr</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+          {manpage}`xrandr(1)`
           for the documentation of the transform matrix.
         '';
       };

nixos/modules/services/misc/docker-registry.nix

···
     garbageCollectDates = mkOption {
       default = "daily";
       type = types.str;
-      description = ''
+      description = lib.mdDoc ''
         Specification (in the format described by
-        <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>) of the time at
+        {manpage}`systemd.time(7)`) of the time at
         which the garbage collect will occur.
       '';
     };

nixos/modules/services/misc/fstrim.nix

···
       interval = mkOption {
         type = types.str;
         default = "weekly";
-        description = ''
+        description = lib.mdDoc ''
           How often we run fstrim. For most desktop and server systems
           a sufficient trimming frequency is once a week.
 
           The format is described in
-          <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+          {manpage}`systemd.time(7)`.
         '';
       };
     };

nixos/modules/services/misc/geoipupdate.nix

···
       interval = lib.mkOption {
         type = lib.types.str;
         default = "weekly";
-        description = ''
+        description = lib.mdDoc ''
           Update the GeoIP databases at this time / interval.
           The format is described in
-          <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+          {manpage}`systemd.time(7)`.
         '';
       };
 

nixos/modules/services/misc/gitea.nix

···
           type = types.str;
           default = "04:31";
           example = "hourly";
-          description = ''
+          description = lib.mdDoc ''
             Run a gitea dump at this interval. Runs by default at 04:31 every day.
 
             The format is described in
-            <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+            {manpage}`systemd.time(7)`.
           '';
         };
 

nixos/modules/services/misc/gitit.nix

···
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = "Enable the gitit service.";
+        description = lib.mdDoc "Enable the gitit service.";
       };
 
       haskellPackages = mkOption {
         default = pkgs.haskellPackages;
         defaultText = literalExpression "pkgs.haskellPackages";
         example = literalExpression "pkgs.haskell.packages.ghc784";
-        description = "haskellPackages used to build gitit and plugins.";
+        description = lib.mdDoc "haskellPackages used to build gitit and plugins.";
       };
 
       extraPackages = mkOption {
···
       address = mkOption {
         type = types.str;
         default = "0.0.0.0";
-        description = "IP address on which the web server will listen.";
+        description = lib.mdDoc "IP address on which the web server will listen.";
       };
 
       port = mkOption {
         type = types.int;
         default = 5001;
-        description = "Port on which the web server will run.";
+        description = lib.mdDoc "Port on which the web server will run.";
       };
 
       wikiTitle = mkOption {
         type = types.str;
         default = "Gitit!";
-        description = "The wiki title.";
+        description = lib.mdDoc "The wiki title.";
       };
 
       repositoryType = mkOption {
         type = types.enum ["git" "darcs" "mercurial"];
         default = "git";
-        description = "Specifies the type of repository used for wiki content.";
+        description = lib.mdDoc "Specifies the type of repository used for wiki content.";
       };
 
       repositoryPath = mkOption {
         type = types.path;
         default = homeDir + "/wiki";
-        description = ''
+        description = lib.mdDoc ''
           Specifies the path of the repository directory. If it does not
           exist, gitit will create it on startup.
         '';
···
       requireAuthentication = mkOption {
         type = types.enum [ "none" "modify" "read" ];
         default = "modify";
-        description = ''
+        description = lib.mdDoc ''
           If 'none', login is never required, and pages can be edited
           anonymously.  If 'modify', login is required to modify the wiki
           (edit, add, delete pages, upload files).  If 'read', login is
···
       authenticationMethod = mkOption {
         type = types.enum [ "form" "http" "generic" "github" ];
         default = "form";
-        description = ''
+        description = lib.mdDoc ''
           'form' means that users will be logged in and registered using forms
           in the gitit web interface.  'http' means that gitit will assume that
           HTTP authentication is in place and take the logged in username from
···
       userFile = mkOption {
         type = types.path;
         default = homeDir + "/gitit-users";
-        description = ''
+        description = lib.mdDoc ''
           Specifies the path of the file containing user login information.  If
           it does not exist, gitit will create it (with an empty user list).
           This file is not used if 'http' is selected for
···
       sessionTimeout = mkOption {
         type = types.int;
         default = 60;
-        description = ''
+        description = lib.mdDoc ''
           Number of minutes of inactivity before a session expires.
         '';
       };
···
       staticDir = mkOption {
         type = types.path;
         default = gititShared + "/data/static";
-        description = ''
+        description = lib.mdDoc ''
           Specifies the path of the static directory (containing javascript,
           css, and images).  If it does not exist, gitit will create it and
           populate it with required scripts, stylesheets, and images.
···
       defaultPageType = mkOption {
         type = types.enum [ "markdown" "rst" "latex" "html" "markdown+lhs" "rst+lhs" "latex+lhs" ];
         default = "markdown";
-        description = ''
+        description = lib.mdDoc ''
           Specifies the type of markup used to interpret pages in the wiki.
           Possible values are markdown, rst, latex, html, markdown+lhs,
           rst+lhs, and latex+lhs. (the +lhs variants treat the input as
···
       math = mkOption {
         type = types.enum [ "mathml" "raw" "mathjax" "jsmath" "google" ];
         default = "mathml";
-        description = ''
+        description = lib.mdDoc ''
           Specifies how LaTeX math is to be displayed.  Possible values are
           mathml, raw, mathjax, jsmath, and google.  If mathml is selected,
           gitit will convert LaTeX math to MathML and link in a script,
···
       mathJaxScript = mkOption {
         type = types.str;
         default = "https://d3eoax9i5htok0.cloudfront.net/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML";
-        description = ''
+        description = lib.mdDoc ''
           Specifies the path to MathJax rendering script.  You might want to
           use your own MathJax script to render formulas without Internet
           connection or if you want to use some special LaTeX packages.  Note:
···
       showLhsBirdTracks = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Specifies whether to show Haskell code blocks in "bird style", with
           "> " at the beginning of each line.
         '';
···
       logFile = mkOption {
         type = types.path;
         default = homeDir + "/gitit.log";
-        description = ''
+        description = lib.mdDoc ''
           Specifies the path of gitit's log file.  If it does not exist, gitit
           will create it. The log is in Apache combined log format.
         '';
···
       logLevel = mkOption {
         type = types.enum [ "DEBUG" "INFO" "NOTICE" "WARNING" "ERROR" "CRITICAL" "ALERT" "EMERGENCY" ];
         default = "ERROR";
-        description = ''
+        description = lib.mdDoc ''
           Determines how much information is logged.  Possible values (from
           most to least verbose) are DEBUG, INFO, NOTICE, WARNING, ERROR,
           CRITICAL, ALERT, EMERGENCY.
···
       frontPage = mkOption {
         type = types.str;
         default = "Front Page";
-        description = ''
+        description = lib.mdDoc ''
           Specifies which wiki page is to be used as the wiki's front page.
           Gitit creates a default front page on startup, if one does not exist
           already.
···
       noDelete = mkOption {
         type = types.str;
         default = "Front Page, Help";
-        description = ''
+        description = lib.mdDoc ''
           Specifies pages that cannot be deleted through the web interface.
           (They can still be deleted directly using git or darcs.) A
           comma-separated list of page names.  Leave blank to allow every page
···
       noEdit = mkOption {
         type = types.str;
         default = "Help";
-        description = ''
+        description = lib.mdDoc ''
           Specifies pages that cannot be edited through the web interface.
           Leave blank to allow every page to be edited.
         '';
···
       defaultSummary = mkOption {
         type = types.str;
         default = "";
-        description = ''
+        description = lib.mdDoc ''
           Specifies text to be used in the change description if the author
           leaves the "description" field blank.  If default-summary is blank
           (the default), the author will be required to fill in the description
···
       tableOfContents = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Specifies whether to print a tables of contents (with links to
           sections) on each wiki page.
         '';
···
       plugins = mkOption {
         type = with types; listOf str;
         default = [ (gititShared + "/plugins/Dot.hs") ];
-        description = ''
+        description = lib.mdDoc ''
           Specifies a list of plugins to load. Plugins may be specified either
           by their path or by their module name. If the plugin name starts
           with Gitit.Plugin., gitit will assume that the plugin is an installed
···
       useCache = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Specifies whether to cache rendered pages.  Note that if use-feed is
           selected, feeds will be cached regardless of the value of use-cache.
         '';
···
       cacheDir = mkOption {
         type = types.path;
         default = homeDir + "/cache";
-        description = "Path where rendered pages will be cached.";
+        description = lib.mdDoc "Path where rendered pages will be cached.";
       };
 
       maxUploadSize = mkOption {
         type = types.str;
         default = "1000K";
-        description = ''
+        description = lib.mdDoc ''
           Specifies an upper limit on the size (in bytes) of files uploaded
           through the wiki's web interface.  To disable uploads, set this to
           0K.  This will result in the uploads link disappearing and the
···
       maxPageSize = mkOption {
         type = types.str;
         default = "1000K";
-        description = "Specifies an upper limit on the size (in bytes) of pages.";
+        description = lib.mdDoc "Specifies an upper limit on the size (in bytes) of pages.";
       };
 
       debugMode = mkOption {
         type = types.bool;
         default = false;
-        description = "Causes debug information to be logged while gitit is running.";
+        description = lib.mdDoc "Causes debug information to be logged while gitit is running.";
       };
 
       compressResponses = mkOption {
         type = types.bool;
         default = true;
-        description = "Specifies whether HTTP responses should be compressed.";
+        description = lib.mdDoc "Specifies whether HTTP responses should be compressed.";
       };
 
       mimeTypesFile = mkOption {
···
       useReCaptcha = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           If true, causes gitit to use the reCAPTCHA service
           (http://recaptcha.net) to prevent bots from creating accounts.
         '';
···
       reCaptchaPrivateKey = mkOption {
         type = with types; nullOr str;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Specifies the private key for the reCAPTCHA service.  To get
           these, you need to create an account at http://recaptcha.net.
         '';
···
       reCaptchaPublicKey = mkOption {
         type = with types; nullOr str;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Specifies the public key for the reCAPTCHA service.  To get
           these, you need to create an account at http://recaptcha.net.
         '';
···
       accessQuestion = mkOption {
         type = types.str;
         default = "What is the code given to you by Ms. X?";
-        description = ''
+        description = lib.mdDoc ''
           Specifies a question that users must answer when they attempt to
           create an account
         '';
···
       accessQuestionAnswers = mkOption {
         type = types.str;
         default = "RED DOG, red dog";
-        description = ''
+        description = lib.mdDoc ''
           Specifies a question that users must answer when they attempt to
           create an account, along with a comma-separated list of acceptable
           answers.  This can be used to institute a rudimentary password for
···
       rpxDomain = mkOption {
         type = with types; nullOr str;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Specifies the domain and key of your RPX account.  The domain is just
           the prefix of the complete RPX domain, so if your full domain is
           'https://foo.rpxnow.com/', use 'foo' as the value of rpx-domain.
···
       rpxKey = mkOption {
         type = with types; nullOr str;
         default = null;
-        description = "RPX account access key.";
+        description = lib.mdDoc "RPX account access key.";
       };
 
       mailCommand = mkOption {
         type = types.str;
         default = "sendmail %s";
-        description = ''
+        description = lib.mdDoc ''
           Specifies the command to use to send notification emails.  '%s' will
           be replaced by the destination email address.  The body of the
           message will be read from stdin.  If this field is left blank,
···
           >
           > Regards
         '';
-        description = ''
+        description = lib.mdDoc ''
           Gives the text of the message that will be sent to the user should
           she want to reset her password, or change other registration info.
           The lines must be indented, and must begin with '>'.  The initial
···
       useFeed = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Specifies whether an ATOM feed should be enabled (for the site and
           for individual pages).
         '';
···
       baseUrl = mkOption {
         type = with types; nullOr str;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           The base URL of the wiki, to be used in constructing feed IDs and RPX
           token_urls.  Set this if useFeed is false or authentication-method
           is 'rpx'.
···
       feedDays = mkOption {
         type = types.int;
         default = 14;
-        description = "Number of days to be included in feeds.";
+        description = lib.mdDoc "Number of days to be included in feeds.";
       };
 
       feedRefreshTime = mkOption {
         type = types.int;
         default = 60;
-        description = "Number of minutes to cache feeds before refreshing.";
+        description = lib.mdDoc "Number of minutes to cache feeds before refreshing.";
       };
 
       pdfExport = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           If true, PDF will appear in export options. PDF will be created using
           pdflatex, which must be installed and in the path. Note that PDF
           exports create significant additional server load.
···
       pandocUserData = mkOption {
         type = with types; nullOr path;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           If a directory is specified, this will be searched for pandoc
           customizations. These can include a templates/ directory for custom
           templates for various export formats, an S5 directory for custom S5
···
       xssSanitize = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           If true, all HTML (including that produced by pandoc) is filtered
           through xss-sanitize.  Set to no only if you trust all of your users.
         '';
···
       oauthClientId = mkOption {
         type = with types; nullOr str;
         default = null;
-        description = "OAuth client ID";
+        description = lib.mdDoc "OAuth client ID";
       };
 
       oauthClientSecret = mkOption {
         type = with types; nullOr str;
         default = null;
-        description = "OAuth client secret";
+        description = lib.mdDoc "OAuth client secret";
       };
 
       oauthCallback = mkOption {
         type = with types; nullOr str;
         default = null;
-        description = "OAuth callback URL";
+        description = lib.mdDoc "OAuth callback URL";
       };
 
       oauthAuthorizeEndpoint = mkOption {
         type = with types; nullOr str;
         default = null;
-        description = "OAuth authorize endpoint";
+        description = lib.mdDoc "OAuth authorize endpoint";
       };
 
       oauthAccessTokenEndpoint = mkOption {
         type = with types; nullOr str;
         default = null;
-        description = "OAuth access token endpoint";
+        description = lib.mdDoc "OAuth access token endpoint";
       };
 
       githubOrg = mkOption {
         type = with types; nullOr str;
         default = null;
-        description = "Github organization";
+        description = lib.mdDoc "Github organization";
       };
   };
 

nixos/modules/services/misc/gitlab.nix

···
         type = with types; either str (listOf str);
         default = [];
         example = "03:00";
-        description = ''
+        description = lib.mdDoc ''
           The time(s) to run automatic backup of GitLab
           state. Specified in systemd's time format; see
-          <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+          {manpage}`systemd.time(7)`.
         '';
       };
 

nixos/modules/services/misc/nix-daemon.nix

···
         type = types.enum [ "other" "batch" "idle" ];
         default = "other";
         example = "batch";
-        description = ''
+        description = lib.mdDoc ''
           Nix daemon process CPU scheduling policy. This policy propagates to
-          build processes. <literal>other</literal> is the default scheduling
-          policy for regular tasks. The <literal>batch</literal> policy is
-          similar to <literal>other</literal>, but optimised for
-          non-interactive tasks. <literal>idle</literal> is for extremely
+          build processes. `other` is the default scheduling
+          policy for regular tasks. The `batch` policy is
+          similar to `other`, but optimised for
+          non-interactive tasks. `idle` is for extremely
           low-priority tasks that should only be run when no other task
           requires CPU time.
 
-          Please note that while using the <literal>idle</literal> policy may
+          Please note that while using the `idle` policy may
           greatly improve responsiveness of a system performing expensive
           builds, it may also slow down and potentially starve crucial
           configuration updates during load.
 
-          <literal>idle</literal> may therefore be a sensible policy for
+          `idle` may therefore be a sensible policy for
           systems that experience only intermittent phases of high CPU load,
           such as desktop or portable computers used interactively. Other
-          systems should use the <literal>other</literal> or
-          <literal>batch</literal> policy instead.
+          systems should use the `other` or
+          `batch` policy instead.
 
           For more fine-grained resource control, please refer to
-          <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> and adjust
-          <option>systemd.services.nix-daemon</option> directly.
+          {manpage}`systemd.resource-control(5)` and adjust
+          {option}`systemd.services.nix-daemon` directly.
       '';
       };
 

nixos/modules/services/misc/nix-gc.nix

···
         type = types.str;
         default = "03:15";
         example = "weekly";
-        description = ''
+        description = lib.mdDoc ''
           How often or when garbage collection is performed. For most desktop and server systems
           a sufficient garbage collection is once a week.
 
           The format is described in
-          <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+          {manpage}`systemd.time(7)`.
         '';
       };
 
···
         default = "0";
         type = types.str;
         example = "45min";
-        description = ''
+        description = lib.mdDoc ''
           Add a randomized delay before each garbage collection.
           The delay will be chosen between zero and this value.
           This value must be a time span in the format specified by
-          <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+          {manpage}`systemd.time(7)`
         '';
       };
 

nixos/modules/services/misc/nix-optimise.nix

···
       dates = mkOption {
         default = ["03:45"];
         type = types.listOf types.str;
-        description = ''
+        description = lib.mdDoc ''
           Specification (in the format described by
-          <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>) of the time at
+          {manpage}`systemd.time(7)`) of the time at
           which the optimiser will run.
         '';
       };

nixos/modules/services/misc/snapper.nix

···
     snapshotInterval = mkOption {
       type = types.str;
       default = "hourly";
-      description = ''
+      description = lib.mdDoc ''
         Snapshot interval.
 
         The format is described in
-        <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+        {manpage}`systemd.time(7)`.
       '';
     };
 
     cleanupInterval = mkOption {
       type = types.str;
       default = "1d";
-      description = ''
+      description = lib.mdDoc ''
         Cleanup interval.
 
         The format is described in
-        <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+        {manpage}`systemd.time(7)`.
       '';
     };
 

nixos/modules/services/misc/sourcehut/default.nix

···
     })));
   commonServiceSettings = srv: {
     origin = mkOption {
-      description = "URL ${srv}.sr.ht is being served at (protocol://domain)";
+      description = lib.mdDoc "URL ${srv}.sr.ht is being served at (protocol://domain)";
       type = types.str;
       default = "https://${srv}.${domain}";
       defaultText = "https://${srv}.example.com";
     };
     debug-host = mkOption {
-      description = "Address to bind the debug server to.";
+      description = lib.mdDoc "Address to bind the debug server to.";
       type = with types; nullOr str;
       default = null;
     };
     debug-port = mkOption {
-      description = "Port to bind the debug server to.";
+      description = lib.mdDoc "Port to bind the debug server to.";
       type = with types; nullOr str;
       default = null;
     };
     connection-string = mkOption {
-      description = "SQLAlchemy connection string for the database.";
+      description = lib.mdDoc "SQLAlchemy connection string for the database.";
       type = types.str;
       default = "postgresql:///localhost?user=${srv}srht&host=/run/postgresql";
     };
     migrate-on-upgrade = mkEnableOption "automatic migrations on package upgrade" // { default = true; };
     oauth-client-id = mkOption {
-      description = "${srv}.sr.ht's OAuth client id for meta.sr.ht.";
+      description = lib.mdDoc "${srv}.sr.ht's OAuth client id for meta.sr.ht.";
       type = types.str;
     };
     oauth-client-secret = mkOption {
-      description = "${srv}.sr.ht's OAuth client secret for meta.sr.ht.";
+      description = lib.mdDoc "${srv}.sr.ht's OAuth client secret for meta.sr.ht.";
       type = types.path;
       apply = s: "<" + toString s;
     };
···
       type = with types; listOf (enum
         [ "builds" "dispatch" "git" "hg" "hub" "lists" "man" "meta" "pages" "paste" "todo" ]);
       defaultText = "locally enabled services";
-      description = ''
+      description = lib.mdDoc ''
         Services that may be displayed as links in the title bar of the Web interface.
       '';
     };
···
     listenAddress = mkOption {
       type = types.str;
       default = "localhost";
-      description = "Address to bind to.";
+      description = lib.mdDoc "Address to bind to.";
     };
 
     python = mkOption {
···
       virtualHost = mkOption {
         type = types.attrs;
         default = {};
-        description = "Virtual-host configuration merged with all Sourcehut's virtual-hosts.";
+        description = lib.mdDoc "Virtual-host configuration merged with all Sourcehut's virtual-hosts.";
       };
     };
 
···
         freeformType = settingsFormat.type;
         options."sr.ht" = {
           global-domain = mkOption {
-            description = "Global domain name.";
+            description = lib.mdDoc "Global domain name.";
             type = types.str;
             example = "example.com";
           };
           environment = mkOption {
-            description = "Values other than \"production\" adds a banner to each page.";
+            description = lib.mdDoc "Values other than \"production\" adds a banner to each page.";
             type = types.enum [ "development" "production" ];
             default = "development";
           };
           network-key = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               An absolute file path (which should be outside the Nix-store)
-              to a secret key to encrypt internal messages with. Use <literal>srht-keygen network</literal> to
+              to a secret key to encrypt internal messages with. Use `srht-keygen network` to
               generate this key. It must be consistent between all services and nodes.
             '';
             type = types.path;
             apply = s: "<" + toString s;
           };
           owner-email = mkOption {
-            description = "Owner's email.";
+            description = lib.mdDoc "Owner's email.";
             type = types.str;
             default = "[e-mail]";
           };
           owner-name = mkOption {
-            description = "Owner's name.";
+            description = lib.mdDoc "Owner's name.";
             type = types.str;
             default = "John Doe";
           };
           site-blurb = mkOption {
-            description = "Blurb for your site.";
+            description = lib.mdDoc "Blurb for your site.";
             type = types.str;
             default = "the hacker's forge";
           };
           site-info = mkOption {
-            description = "The top-level info page for your site.";
+            description = lib.mdDoc "The top-level info page for your site.";
             type = types.str;
             default = "https://sourcehut.org";
           };
           service-key = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               An absolute file path (which should be outside the Nix-store)
-              to a key used for encrypting session cookies. Use <literal>srht-keygen service</literal> to
+              to a key used for encrypting session cookies. Use `srht-keygen service` to
               generate the service key. This must be shared between each node of the same
               service (e.g. git1.sr.ht and git2.sr.ht), but different services may use
               different keys. If you configure all of your services with the same
···
             apply = s: "<" + toString s;
           };
           site-name = mkOption {
-            description = "The name of your network of sr.ht-based sites.";
+            description = lib.mdDoc "The name of your network of sr.ht-based sites.";
             type = types.str;
             default = "sourcehut";
           };
           source-url = mkOption {
-            description = "The source code for your fork of sr.ht.";
+            description = lib.mdDoc "The source code for your fork of sr.ht.";
             type = types.str;
             default = "https://git.sr.ht/~sircmpwn/srht";
           };
···
         options.mail = {
           smtp-host = mkOptionNullOrStr "Outgoing SMTP host.";
           smtp-port = mkOption {
-            description = "Outgoing SMTP port.";
+            description = lib.mdDoc "Outgoing SMTP port.";
             type = with types; nullOr port;
             default = null;
           };
···
           smtp-password = mkOptionNullOrStr "Outgoing SMTP password.";
           smtp-from = mkOption {
             type = types.str;
-            description = "Outgoing SMTP FROM.";
+            description = lib.mdDoc "Outgoing SMTP FROM.";
           };
           error-to = mkOptionNullOrStr "Address receiving application exceptions";
           error-from = mkOptionNullOrStr "Address sending application exceptions";
           pgp-privkey = mkOption {
             type = types.str;
-            description = ''
+            description = lib.mdDoc ''
               An absolute file path (which should be outside the Nix-store)
               to an OpenPGP private key.
 
               Your PGP key information (DO NOT mix up pub and priv here)
               You must remove the password from your secret key, if present.
-              You can do this with <literal>gpg --edit-key [key-id]</literal>,
-              then use the <literal>passwd</literal> command and do not enter a new password.
+              You can do this with `gpg --edit-key [key-id]`,
+              then use the `passwd` command and do not enter a new password.
             '';
           };
           pgp-pubkey = mkOption {
             type = with types; either path str;
-            description = "OpenPGP public key.";
+            description = lib.mdDoc "OpenPGP public key.";
           };
           pgp-key-id = mkOption {
             type = types.str;
-            description = "OpenPGP key identifier.";
+            description = lib.mdDoc "OpenPGP key identifier.";
           };
         };
         options.objects = {
           s3-upstream = mkOption {
-            description = "Configure the S3-compatible object storage service.";
+            description = lib.mdDoc "Configure the S3-compatible object storage service.";
             type = with types; nullOr str;
             default = null;
           };
           s3-access-key = mkOption {
-            description = "Access key to the S3-compatible object storage service";
+            description = lib.mdDoc "Access key to the S3-compatible object storage service";
             type = with types; nullOr str;
             default = null;
           };
           s3-secret-key = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               An absolute file path (which should be outside the Nix-store)
               to the secret key of the S3-compatible object storage service.
             '';
···
         };
         options.webhooks = {
           private-key = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               An absolute file path (which should be outside the Nix-store)
               to a base64-encoded Ed25519 key for signing webhook payloads.
               This should be consistent for all *.sr.ht sites,
               as this key will be used to verify signatures
               from other sites in your network.
-              Use the <literal>srht-keygen webhook</literal> command to generate a key.
+              Use the `srht-keygen webhook` command to generate a key.
             '';
             type = types.path;
             apply = s: "<" + toString s;
···
           enabled = mkEnableOption "GitLab integration";
           canonical-upstream = mkOption {
             type = types.str;
-            description = "Canonical upstream.";
+            description = lib.mdDoc "Canonical upstream.";
             default = "gitlab.com";
           };
           repo-cache = mkOption {
             type = types.str;
-            description = "Repository cache directory.";
+            description = lib.mdDoc "Repository cache directory.";
             default = "./repo-cache";
           };
           "gitlab.com" = mkOption {
             type = with types; nullOr str;
-            description = "GitLab id and secret.";
+            description = lib.mdDoc "GitLab id and secret.";
             default = null;
             example = "GitLab:application id:secret";
           };
···
         options."builds.sr.ht" = commonServiceSettings "builds" // {
           allow-free = mkEnableOption "nonpaying users to submit builds";
           redis = mkOption {
-            description = "The Redis connection used for the Celery worker.";
+            description = lib.mdDoc "The Redis connection used for the Celery worker.";
             type = types.str;
             default = "redis+socket:///run/redis-sourcehut-buildsrht/redis.sock?virtual_host=2";
           };
           shell = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               Scripts used to launch on SSH connection.
-              <literal>/usr/bin/master-shell</literal> on master,
-              <literal>/usr/bin/runner-shell</literal> on runner.
+              `/usr/bin/master-shell` on master,
+              `/usr/bin/runner-shell` on runner.
               If master and worker are on the same system
-              set to <literal>/usr/bin/runner-shell</literal>.
+              set to `/usr/bin/runner-shell`.
             '';
             type = types.enum ["/usr/bin/master-shell" "/usr/bin/runner-shell"];
             default = "/usr/bin/master-shell";
···
         };
         options."builds.sr.ht::worker" = {
           bind-address = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               HTTP bind address for serving local build information/monitoring.
             '';
             type = types.str;
             default = "localhost:8080";
           };
           buildlogs = mkOption {
-            description = "Path to write build logs.";
+            description = lib.mdDoc "Path to write build logs.";
             type = types.str;
             default = "/var/log/sourcehut/buildsrht-worker";
           };
           name = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               Listening address and listening port
               of the build runner (with HTTP port if not 80).
             '';
···
             default = "localhost:5020";
           };
           timeout = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               Max build duration.
-              See <link xlink:href="https://golang.org/pkg/time/#ParseDuration"/>.
+              See <https://golang.org/pkg/time/#ParseDuration>.
             '';
             type = types.str;
             default = "3m";
···
 
         options."git.sr.ht" = commonServiceSettings "git" // {
           outgoing-domain = mkOption {
-            description = "Outgoing domain.";
+            description = lib.mdDoc "Outgoing domain.";
             type = types.str;
             default = "https://git.localhost.localdomain";
           };
           post-update-script = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               A post-update script which is installed in every git repo.
               This setting is propagated to newer and existing repositories.
             '';
···
             defaultText = "\${pkgs.sourcehut.gitsrht}/bin/gitsrht-update-hook";
           };
           repos = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               Path to git repositories on disk.
               If changing the default, you must ensure that
               the gitsrht's user as read and write access to it.
···
             default = "/var/lib/sourcehut/gitsrht/repos";
           };
           webhooks = mkOption {
-            description = "The Redis connection used for the webhooks worker.";
+            description = lib.mdDoc "The Redis connection used for the webhooks worker.";
             type = types.str;
             default = "redis+socket:///run/redis-sourcehut-gitsrht/redis.sock?virtual_host=1";
           };
         };
         options."git.sr.ht::api" = {
           internal-ipnet = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               Set of IP subnets which are permitted to utilize internal API
               authentication. This should be limited to the subnets
               from which your *.sr.ht services are running.
-              See <xref linkend="opt-services.sourcehut.listenAddress"/>.
+              See [](#opt-services.sourcehut.listenAddress).
             '';
             type = with types; listOf str;
             default = [ "127.0.0.0/8" "::1/128" ];
···
 
         options."hg.sr.ht" = commonServiceSettings "hg" // {
           changegroup-script = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               A changegroup script which is installed in every mercurial repo.
               This setting is propagated to newer and existing repositories.
             '';
···
             defaultText = "\${cfg.python}/bin/hgsrht-hook-changegroup";
           };
           repos = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               Path to mercurial repositories on disk.
               If changing the default, you must ensure that
               the hgsrht's user as read and write access to it.
···
             (defaults to where the hgsrht code is)
           '';
           clone_bundle_threshold = mkOption {
-            description = ".hg/store size (in MB) past which the nightly job generates clone bundles.";
+            description = lib.mdDoc ".hg/store size (in MB) past which the nightly job generates clone bundles.";
             type = types.ints.unsigned;
             default = 50;
           };
           hg_ssh = mkOption {
-            description = "Path to hg-ssh (if not in $PATH).";
+            description = lib.mdDoc "Path to hg-ssh (if not in $PATH).";
             type = types.str;
             default = "${pkgs.mercurial}/bin/hg-ssh";
             defaultText = "\${pkgs.mercurial}/bin/hg-ssh";
           };
           webhooks = mkOption {
-            description = "The Redis connection used for the webhooks worker.";
+            description = lib.mdDoc "The Redis connection used for the webhooks worker.";
             type = types.str;
             default = "redis+socket:///run/redis-sourcehut-hgsrht/redis.sock?virtual_host=1";
           };
···
         options."lists.sr.ht" = commonServiceSettings "lists" // {
           allow-new-lists = mkEnableOption "Allow creation of new lists.";
           notify-from = mkOption {
-            description = "Outgoing email for notifications generated by users.";
+            description = lib.mdDoc "Outgoing email for notifications generated by users.";
             type = types.str;
             default = "[e-mail]";
           };
           posting-domain = mkOption {
-            description = "Posting domain.";
+            description = lib.mdDoc "Posting domain.";
             type = types.str;
             default = "lists.localhost.localdomain";
           };
           redis = mkOption {
-            description = "The Redis connection used for the Celery worker.";
+            description = lib.mdDoc "The Redis connection used for the Celery worker.";
             type = types.str;
             default = "redis+socket:///run/redis-sourcehut-listssrht/redis.sock?virtual_host=2";
           };
           webhooks = mkOption {
-            description = "The Redis connection used for the webhooks worker.";
+            description = lib.mdDoc "The Redis connection used for the webhooks worker.";
             type = types.str;
             default = "redis+socket:///run/redis-sourcehut-listssrht/redis.sock?virtual_host=1";
           };
         };
         options."lists.sr.ht::worker" = {
           reject-mimetypes = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               Comma-delimited list of Content-Types to reject. Messages with Content-Types
               included in this list are rejected. Multipart messages are always supported,
               and each part is checked against this list.
···
             default = ["text/html"];
           };
           reject-url = mkOption {
-            description = "Reject URL.";
+            description = lib.mdDoc "Reject URL.";
             type = types.str;
             default = "https://man.sr.ht/lists.sr.ht/etiquette.md";
           };
           sock = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               Path for the lmtp daemon's unix socket. Direct incoming mail to this socket.
               Alternatively, specify IP:PORT and an SMTP server will be run instead.
             '';
···
             default = "/tmp/lists.sr.ht-lmtp.sock";
           };
           sock-group = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               The lmtp daemon will make the unix socket group-read/write
               for users in this group.
             '';
···
           removeAttrs (commonServiceSettings "meta")
             ["oauth-client-id" "oauth-client-secret"] // {
           api-origin = mkOption {
-            description = "Origin URL for API, 100 more than web.";
+            description = lib.mdDoc "Origin URL for API, 100 more than web.";
             type = types.str;
             default = "http://${cfg.listenAddress}:${toString (cfg.meta.port + 100)}";
             defaultText = ''http://<xref linkend="opt-services.sourcehut.listenAddress"/>:''${toString (<xref linkend="opt-services.sourcehut.meta.port"/> + 100)}'';
           };
           webhooks = mkOption {
-            description = "The Redis connection used for the webhooks worker.";
+            description = lib.mdDoc "The Redis connection used for the webhooks worker.";
             type = types.str;
             default = "redis+socket:///run/redis-sourcehut-metasrht/redis.sock?virtual_host=1";
           };
···
         };
         options."meta.sr.ht::api" = {
           internal-ipnet = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               Set of IP subnets which are permitted to utilize internal API
               authentication. This should be limited to the subnets
               from which your *.sr.ht services are running.
-              See <xref linkend="opt-services.sourcehut.listenAddress"/>.
+              See [](#opt-services.sourcehut.listenAddress).
             '';
             type = with types; listOf str;
             default = [ "127.0.0.0/8" "::1/128" ];
           };
         };
         options."meta.sr.ht::aliases" = mkOption {
-          description = "Aliases for the client IDs of commonly used OAuth clients.";
+          description = lib.mdDoc "Aliases for the client IDs of commonly used OAuth clients.";
           type = with types; attrsOf int;
           default = {};
           example = { "git.sr.ht" = 12345; };
···
         options."meta.sr.ht::settings" = {
           registration = mkEnableOption "public registration";
           onboarding-redirect = mkOption {
-            description = "Where to redirect new users upon registration.";
+            description = lib.mdDoc "Where to redirect new users upon registration.";
             type = types.str;
             default = "https://meta.localhost.localdomain";
           };
           user-invites = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               How many invites each user is issued upon registration
               (only applicable if open registration is disabled).
             '';
···
 
         options."pages.sr.ht" = commonServiceSettings "pages" // {
           gemini-certs = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               An absolute file path (which should be outside the Nix-store)
               to Gemini certificates.
             '';
···
             default = null;
           };
           max-site-size = mkOption {
-            description = "Maximum size of any given site (post-gunzip), in MiB.";
+            description = lib.mdDoc "Maximum size of any given site (post-gunzip), in MiB.";
             type = types.int;
             default = 1024;
           };
···
         };
         options."pages.sr.ht::api" = {
           internal-ipnet = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               Set of IP subnets which are permitted to utilize internal API
               authentication. This should be limited to the subnets
               from which your *.sr.ht services are running.
-              See <xref linkend="opt-services.sourcehut.listenAddress"/>.
+              See [](#opt-services.sourcehut.listenAddress).
             '';
             type = with types; listOf str;
             default = [ "127.0.0.0/8" "::1/128" ];
···
 
         options."todo.sr.ht" = commonServiceSettings "todo" // {
           notify-from = mkOption {
-            description = "Outgoing email for notifications generated by users.";
+            description = lib.mdDoc "Outgoing email for notifications generated by users.";
             type = types.str;
             default = "[e-mail]";
           };
           webhooks = mkOption {
-            description = "The Redis connection used for the webhooks worker.";
+            description = lib.mdDoc "The Redis connection used for the webhooks worker.";
             type = types.str;
             default = "redis+socket:///run/redis-sourcehut-todosrht/redis.sock?virtual_host=1";
           };
         };
         options."todo.sr.ht::mail" = {
           posting-domain = mkOption {
-            description = "Posting domain.";
+            description = lib.mdDoc "Posting domain.";
             type = types.str;
             default = "todo.localhost.localdomain";
           };
           sock = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               Path for the lmtp daemon's unix socket. Direct incoming mail to this socket.
               Alternatively, specify IP:PORT and an SMTP server will be run instead.
             '';
···
             default = "/tmp/todo.sr.ht-lmtp.sock";
           };
           sock-group = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               The lmtp daemon will make the unix socket group-read/write
               for users in this group.
             '';
···
         };
       };
       default = { };
-      description = ''
+      description = lib.mdDoc ''
         The configuration for the sourcehut network.
       '';
     };
···
             nixos.unstable.x86_64 = image_from_nixpkgs;
           }
         )'';
-        description = ''
+        description = lib.mdDoc ''
           Images for builds.sr.ht. Each package should be distro.release.arch and point to a /nix/store/package/root.img.qcow2.
         '';
       };
···
         default = pkgs.git;
         defaultText = literalExpression "pkgs.git";
         example = literalExpression "pkgs.gitFull";
-        description = ''
+        description = lib.mdDoc ''
           Git package for git.sr.ht. This can help silence collisions.
         '';
       };
       fcgiwrap.preforkProcess = mkOption {
-        description = "Number of fcgiwrap processes to prefork.";
+        description = lib.mdDoc "Number of fcgiwrap processes to prefork.";
         type = types.int;
         default = 4;
       };
···
         type = types.package;
         default = pkgs.mercurial;
         defaultText = literalExpression "pkgs.mercurial";
-        description = ''
+        description = lib.mdDoc ''
           Mercurial package for hg.sr.ht. This can help silence collisions.
         '';
       };
       cloneBundles = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Generate clonebundles (which require more disk space but dramatically speed up cloning large repositories).
         '';
       };
···
         extraArgs = mkOption {
           type = with types; listOf str;
           default = [ "--loglevel DEBUG" "--pool eventlet" "--without-heartbeat" ];
-          description = "Extra arguments passed to the Celery responsible for processing mails.";
+          description = lib.mdDoc "Extra arguments passed to the Celery responsible for processing mails.";
         };
         celeryConfig = mkOption {
           type = types.lines;
           default = "";
-          description = "Content of the <literal>celeryconfig.py</literal> used by the Celery of <literal>listssrht-process</literal>.";
+          description = lib.mdDoc "Content of the `celeryconfig.py` used by the Celery of `listssrht-process`.";
         };
       };
     };

nixos/modules/services/misc/sourcehut/service.nix

···
     user = mkOption {
       type = types.str;
       default = srvsrht;
-      description = ''
+      description = lib.mdDoc ''
         User for ${srv}.sr.ht.
       '';
     };
···
     group = mkOption {
       type = types.str;
       default = srvsrht;
-      description = ''
+      description = lib.mdDoc ''
         Group for ${srv}.sr.ht.
         Membership grants access to the Git/Mercurial repositories by default,
         but not to the config.ini file (where secrets are).
···
     port = mkOption {
       type = types.port;
       default = port;
-      description = ''
+      description = lib.mdDoc ''
         Port on which the "${srv}" backend should listen.
       '';
     };
···
         type = types.str;
         default = "unix:///run/redis-sourcehut-${srvsrht}/redis.sock?db=0";
         example = "redis://shared.wireguard:6379/0";
-        description = ''
+        description = lib.mdDoc ''
           The redis host URL. This is used for caching and temporary storage, and must
           be shared between nodes (e.g. git1.sr.ht and git2.sr.ht), but need not be
           shared between services. It may be shared between services, however, with no
···
       database = mkOption {
         type = types.str;
         default = "${srv}.sr.ht";
-        description = ''
+        description = lib.mdDoc ''
           PostgreSQL database name for the ${srv}.sr.ht service,
-          used if <xref linkend="opt-services.sourcehut.postgresql.enable"/> is <literal>true</literal>.
+          used if [](#opt-services.sourcehut.postgresql.enable) is `true`.
         '';
       };
     };
···
       extraArgs = mkOption {
         type = with types; listOf str;
         default = ["--timeout 120" "--workers 1" "--log-level=info"];
-        description = "Extra arguments passed to Gunicorn.";
+        description = lib.mdDoc "Extra arguments passed to Gunicorn.";
       };
     };
   } // optionalAttrs webhooks {
···
       extraArgs = mkOption {
         type = with types; listOf str;
         default = ["--loglevel DEBUG" "--pool eventlet" "--without-heartbeat"];
-        description = "Extra arguments passed to the Celery responsible for webhooks.";
+        description = lib.mdDoc "Extra arguments passed to the Celery responsible for webhooks.";
       };
       celeryConfig = mkOption {
         type = types.lines;
         default = "";
-        description = "Content of the <literal>celeryconfig.py</literal> used by the Celery responsible for webhooks.";
+        description = lib.mdDoc "Content of the `celeryconfig.py` used by the Celery responsible for webhooks.";
       };
     };
   };

nixos/modules/services/misc/taskserver/default.nix

···
       queueSize = mkOption {
         type = types.int;
         default = 10;
-        description = ''
-          Size of the connection backlog, see <citerefentry><refentrytitle>listen</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
+        description = lib.mdDoc ''
+          Size of the connection backlog, see {manpage}`listen(2)`.
         '';
       };
 
···
       config = mkOption {
         type = types.attrs;
         example.client.cert = "/tmp/debugging.cert";
-        description = ''
+        description = lib.mdDoc ''
           Configuration options to pass to Taskserver.
 
           The options here are the same as described in
-          <citerefentry><refentrytitle>taskdrc</refentrytitle><manvolnum>5</manvolnum></citerefentry>, but with one difference:
+          {manpage}`taskdrc(5)`, but with one difference:
 
-          The <literal>server</literal> option is
-          <literal>server.listen</literal> here, because the
-          <literal>server</literal> option would collide with other options
-          like <literal>server.cert</literal> and we would run in a type error
+          The `server` option is
+          `server.listen` here, because the
+          `server` option would collide with other options
+          like `server.cert` and we would run in a type error
           (attribute set versus string).
 
           Nix types like integers or booleans are automatically converted to

nixos/modules/services/monitoring/nagios.nix

···
           debug_file = "/var/log/nagios/debug.log";
         };
         default = {};
-        description = "Configuration to add to /etc/nagios.cfg";
+        description = lib.mdDoc "Configuration to add to /etc/nagios.cfg";
       };
 
       validateConfig = mkOption {
         type = types.bool;
         default = pkgs.stdenv.hostPlatform == pkgs.stdenv.buildPlatform;
         defaultText = literalExpression "pkgs.stdenv.hostPlatform == pkgs.stdenv.buildPlatform";
-        description = "if true, the syntax of the nagios configuration file is checked at build time";
+        description = lib.mdDoc "if true, the syntax of the nagios configuration file is checked at build time";
       };
 
       cgiConfigFile = mkOption {
···
             sslServerKey = "/var/lib/acme/example.org/key.pem";
           }
         '';
-        description = ''
-          Apache configuration can be done by adapting <option>services.httpd.virtualHosts</option>.
-          See <xref linkend="opt-services.httpd.virtualHosts"/> for further information.
+        description = lib.mdDoc ''
+          Apache configuration can be done by adapting {option}`services.httpd.virtualHosts`.
+          See [](#opt-services.httpd.virtualHosts) for further information.
         '';
       };
     };

nixos/modules/services/monitoring/prometheus/exporters.nix

···
     port = mkOption {
       type = types.port;
       default = port;
-      description = ''
+      description = lib.mdDoc ''
         Port to listen on.
       '';
     };
     listenAddress = mkOption {
       type = types.str;
       default = "0.0.0.0";
-      description = ''
+      description = lib.mdDoc ''
         Address to listen on.
       '';
     };
     extraFlags = mkOption {
       type = types.listOf types.str;
       default = [];
-      description = ''
+      description = lib.mdDoc ''
         Extra commandline options to pass to the ${name} exporter.
       '';
     };
     openFirewall = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Open port in firewall for incoming connections.
       '';
     };
···
     user = mkOption {
       type = types.str;
       default = "${name}-exporter";
-      description = ''
+      description = lib.mdDoc ''
         User name under which the ${name} exporter shall be run.
       '';
     };
     group = mkOption {
       type = types.str;
       default = "${name}-exporter";
-      description = ''
+      description = lib.mdDoc ''
         Group under which the ${name} exporter shall be run.
       '';
     };
···
     type = types.submodule {
       options = (mkSubModules);
     };
-    description = "Prometheus exporter configuration";
+    description = lib.mdDoc "Prometheus exporter configuration";
     default = {};
     example = literalExpression ''
       {

nixos/modules/services/monitoring/prometheus/exporters/apcupsd.nix

···
     apcupsdAddress = mkOption {
       type = types.str;
       default = ":3551";
-      description = ''
+      description = lib.mdDoc ''
         Address of the apcupsd Network Information Server (NIS).
       '';
     };
···
     apcupsdNetwork = mkOption {
       type = types.enum ["tcp" "tcp4" "tcp6"];
       default = "tcp";
-      description = ''
+      description = lib.mdDoc ''
         Network of the apcupsd Network Information Server (NIS): one of "tcp", "tcp4", or "tcp6".
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/artifactory.nix

···
     scrapeUri = mkOption {
       type = types.str;
       default = "http://localhost:8081/artifactory";
-      description = ''
+      description = lib.mdDoc ''
         URI on which to scrape JFrog Artifactory.
       '';
     };
 
     artiUsername = mkOption {
       type = types.str;
-      description = ''
+      description = lib.mdDoc ''
         Username for authentication against JFrog Artifactory API.
       '';
     };
···
     artiPassword = mkOption {
       type = types.str;
       default = "";
-      description = ''
+      description = lib.mdDoc ''
         Password for authentication against JFrog Artifactory API.
         One of the password or access token needs to be set.
       '';
···
     artiAccessToken = mkOption {
       type = types.str;
       default = "";
-      description = ''
+      description = lib.mdDoc ''
         Access token for authentication against JFrog Artifactory API.
         One of the password or access token needs to be set.
       '';

nixos/modules/services/monitoring/prometheus/exporters/bind.nix

···
     bindURI = mkOption {
       type = types.str;
       default = "http://localhost:8053/";
-      description = ''
+      description = lib.mdDoc ''
         HTTP XML API address of an Bind server.
       '';
     };
     bindTimeout = mkOption {
       type = types.str;
       default = "10s";
-      description = ''
+      description = lib.mdDoc ''
         Timeout for trying to get stats from Bind.
       '';
     };
     bindVersion = mkOption {
       type = types.enum [ "xml.v2" "xml.v3" "auto" ];
       default = "auto";
-      description = ''
+      description = lib.mdDoc ''
         BIND statistics version. Can be detected automatically.
       '';
     };
     bindGroups = mkOption {
       type = types.listOf (types.enum [ "server" "view" "tasks" ]);
       default = [ "server" "view" ];
-      description = ''
+      description = lib.mdDoc ''
         List of statistics to collect. Available: [server, view, tasks]
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/bird.nix

···
     birdVersion = mkOption {
       type = types.enum [ 1 2 ];
       default = 2;
-      description = ''
+      description = lib.mdDoc ''
         Specifies whether BIRD1 or BIRD2 is in use.
       '';
     };
     birdSocket = mkOption {
       type = types.path;
       default = "/run/bird/bird.ctl";
-      description = ''
+      description = lib.mdDoc ''
         Path to BIRD2 (or BIRD1 v4) socket.
       '';
     };
     newMetricFormat = mkOption {
       type = types.bool;
       default = true;
-      description = ''
+      description = lib.mdDoc ''
         Enable the new more-generic metric format.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/bitcoin.nix

···
     rpcUser = mkOption {
       type = types.str;
       default = "bitcoinrpc";
-      description = ''
+      description = lib.mdDoc ''
         RPC user name.
       '';
     };
 
     rpcPasswordFile = mkOption {
       type = types.path;
-      description = ''
+      description = lib.mdDoc ''
         File containing RPC password.
       '';
     };
···
     rpcScheme = mkOption {
       type = types.enum [ "http" "https" ];
       default = "http";
-      description = ''
+      description = lib.mdDoc ''
         Whether to connect to bitcoind over http or https.
       '';
     };
···
     rpcHost = mkOption {
       type = types.str;
       default = "localhost";
-      description = ''
+      description = lib.mdDoc ''
         RPC host.
       '';
     };
···
     rpcPort = mkOption {
       type = types.port;
       default = 8332;
-      description = ''
+      description = lib.mdDoc ''
         RPC port number.
       '';
     };
···
     refreshSeconds = mkOption {
       type = types.ints.unsigned;
       default = 300;
-      description = ''
+      description = lib.mdDoc ''
         How often to ask bitcoind for metrics.
       '';
     };
···
     extraEnv = mkOption {
       type = types.attrsOf types.str;
       default = {};
-      description = ''
+      description = lib.mdDoc ''
         Extra environment variables for the exporter.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/blackbox.nix

···
   extraOpts = {
     configFile = mkOption {
       type = types.path;
-      description = ''
+      description = lib.mdDoc ''
         Path to configuration file.
       '';
     };
     enableConfigCheck = mkOption {
       type = types.bool;
       default = true;
-      description = ''
+      description = lib.mdDoc ''
         Whether to run a correctness check for the configuration file. This depends
         on the configuration file residing in the nix-store. Paths passed as string will
         be copied to the store.

nixos/modules/services/monitoring/prometheus/exporters/buildkite-agent.nix

···
     tokenPath = mkOption {
       type = types.nullOr types.path;
       apply = final: if final == null then null else toString final;
-      description = ''
+      description = lib.mdDoc ''
         The token from your Buildkite "Agents" page.
 
         A run-time path to the token file, which is supposed to be provisioned
···
       type = types.str;
       default = "30s";
       example = "1min";
-      description = ''
+      description = lib.mdDoc ''
         How often to update metrics.
       '';
     };
     endpoint = mkOption {
       type = types.str;
       default = "https://agent.buildkite.com/v3";
-      description = ''
+      description = lib.mdDoc ''
         The Buildkite Agent API endpoint.
       '';
     };
···
       type = with types; nullOr (listOf str);
       default = null;
       example = literalExpression ''[ "my-queue1" "my-queue2" ]'';
-      description = ''
+      description = lib.mdDoc ''
         Which specific queues to process.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/collectd.nix

···
       authFile = mkOption {
         default = null;
         type = types.nullOr types.path;
-        description = "File mapping user names to pre-shared keys (passwords).";
+        description = lib.mdDoc "File mapping user names to pre-shared keys (passwords).";
       };
 
       port = mkOption {
         type = types.int;
         default = 25826;
-        description = "Network address on which to accept collectd binary network packets.";
+        description = lib.mdDoc "Network address on which to accept collectd binary network packets.";
       };
 
       listenAddress = mkOption {
         type = types.str;
         default = "0.0.0.0";
-        description = ''
+        description = lib.mdDoc ''
           Address to listen on for binary network packets.
           '';
       };
···
       securityLevel = mkOption {
         type = types.enum ["None" "Sign" "Encrypt"];
         default = "None";
-        description = ''
+        description = lib.mdDoc ''
           Minimum required security level for accepted packets.
         '';
       };
···
       type = types.enum [ "logfmt" "json" ];
       default = "logfmt";
       example = "json";
-      description = ''
+      description = lib.mdDoc ''
         Set the log format.
       '';
     };
···
     logLevel = mkOption {
       type = types.enum ["debug" "info" "warn" "error" "fatal"];
       default = "info";
-      description = ''
+      description = lib.mdDoc ''
         Only log messages with the given severity or above.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/dmarc.nix

···
       host = mkOption {
         type = types.str;
         default = "localhost";
-        description = ''
+        description = lib.mdDoc ''
           Hostname of IMAP server to connect to.
         '';
       };
       port = mkOption {
         type = types.port;
         default = 993;
-        description = ''
+        description = lib.mdDoc ''
           Port of the IMAP server to connect to.
         '';
       };
       username = mkOption {
         type = types.str;
         example = "[e-mail]";
-        description = ''
+        description = lib.mdDoc ''
           Login username for the IMAP connection.
         '';
       };
       passwordFile = mkOption {
         type = types.str;
         example = "/run/secrets/dovecot_pw";
-        description = ''
+        description = lib.mdDoc ''
           File containing the login password for the IMAP connection.
         '';
       };
···
       inbox = mkOption {
         type = types.str;
         default = "INBOX";
-        description = ''
+        description = lib.mdDoc ''
           IMAP mailbox that is checked for incoming DMARC aggregate reports
         '';
       };
       done = mkOption {
         type = types.str;
         default = "Archive";
-        description = ''
+        description = lib.mdDoc ''
           IMAP mailbox that successfully processed reports are moved to.
         '';
       };
       error = mkOption {
         type = types.str;
         default = "Invalid";
-        description = ''
+        description = lib.mdDoc ''
           IMAP mailbox that emails are moved to that could not be processed.
         '';
       };
···
     pollIntervalSeconds = mkOption {
       type = types.ints.unsigned;
       default = 60;
-      description = ''
+      description = lib.mdDoc ''
         How often to poll the IMAP server in seconds.
       '';
     };
···
       type = types.ints.unsigned;
       default = 604800;
       defaultText = "7 days (in seconds)";
-      description = ''
+      description = lib.mdDoc ''
         How long individual report IDs will be remembered to avoid
         counting double delivered reports twice.
       '';
···
     debug = mkOption {
       type = types.bool;
       default = false;
-      description = ''
-        Whether to declare enable <literal>--debug</literal>.
+      description = lib.mdDoc ''
+        Whether to declare enable `--debug`.
       '';
     };
   };

nixos/modules/services/monitoring/prometheus/exporters/dnsmasq.nix

···
     dnsmasqListenAddress = mkOption {
       type = types.str;
       default = "localhost:53";
-      description = ''
+      description = lib.mdDoc ''
         Address on which dnsmasq listens.
       '';
     };
···
       type = types.path;
       default = "/var/lib/misc/dnsmasq.leases";
       example = "/var/lib/dnsmasq/dnsmasq.leases";
-      description = ''
-        Path to the <literal>dnsmasq.leases</literal> file.
+      description = lib.mdDoc ''
+        Path to the `dnsmasq.leases` file.
       '';
     };
   };

nixos/modules/services/monitoring/prometheus/exporters/dovecot.nix

···
     telemetryPath = mkOption {
       type = types.str;
       default = "/metrics";
-      description = ''
+      description = lib.mdDoc ''
         Path under which to expose metrics.
       '';
     };
···
       type = types.listOf types.str;
       default = [ "user" ];
       example = [ "user" "global" ];
-      description = ''
+      description = lib.mdDoc ''
         Stats scopes to query.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/fastly.nix

···
     configFile = mkOption {
       type = types.nullOr types.path;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Path to a fastly-exporter configuration file.
-        Example one can be generated with <literal>fastly-exporter --config-file-example</literal>.
+        Example one can be generated with `fastly-exporter --config-file-example`.
       '';
       example = "./fastly-exporter-config.txt";
     };
···
     tokenPath = mkOption {
       type = types.nullOr types.path;
       apply = final: if final == null then null else toString final;
-      description = ''
+      description = lib.mdDoc ''
         A run-time path to the token file, which is supposed to be provisioned
         outside of Nix store.
       '';

nixos/modules/services/monitoring/prometheus/exporters/flow.nix

···
     brokers = mkOption {
       type = types.listOf types.str;
       example = literalExpression ''[ "kafka.example.org:19092" ]'';
-      description = "List of Kafka brokers to connect to.";
+      description = lib.mdDoc "List of Kafka brokers to connect to.";
     };
 
     asn = mkOption {
       type = types.ints.positive;
       example = 65542;
-      description = "The ASN being monitored.";
+      description = lib.mdDoc "The ASN being monitored.";
     };
 
     partitions = mkOption {
       type = types.listOf types.int;
       default = [];
-      description = ''
+      description = lib.mdDoc ''
         The number of the partitions to consume, none means all.
       '';
     };
···
     topic = mkOption {
       type = types.str;
       example = "pmacct.acct";
-      description = "The Kafka topic to consume from.";
+      description = lib.mdDoc "The Kafka topic to consume from.";
     };
   };
 

nixos/modules/services/monitoring/prometheus/exporters/fritzbox.nix

···
     gatewayAddress = mkOption {
       type = types.str;
       default = "fritz.box";
-      description = ''
+      description = lib.mdDoc ''
         The hostname or IP of the FRITZ!Box.
       '';
     };
···
     gatewayPort = mkOption {
       type = types.int;
       default = 49000;
-      description = ''
+      description = lib.mdDoc ''
         The port of the FRITZ!Box UPnP service.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/influxdb.nix

···
       type = types.str;
       default = "5m";
       example = "10m";
-      description = "How long a sample is valid for";
+      description = lib.mdDoc "How long a sample is valid for";
     };
     udpBindAddress = mkOption {
       type = types.str;
       default = ":9122";
       example = "192.0.2.1:9122";
-      description = "Address on which to listen for udp packets";
+      description = lib.mdDoc "Address on which to listen for udp packets";
     };
   };
   serviceOpts = {

nixos/modules/services/monitoring/prometheus/exporters/jitsi.nix

···
     url = mkOption {
       type = types.str;
       default = "http://localhost:8080/colibri/stats";
-      description = ''
+      description = lib.mdDoc ''
         Jitsi Videobridge metrics URL to monitor.
         This is usually /colibri/stats on port 8080 of the jitsi videobridge host.
       '';
···
       type = types.str;
       default = "30s";
       example = "1min";
-      description = ''
+      description = lib.mdDoc ''
         How often to scrape new data
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/json.nix

···
   extraOpts = {
     configFile = mkOption {
       type = types.path;
-      description = ''
+      description = lib.mdDoc ''
         Path to configuration file.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/kea.nix

···
           "/run/kea/kea-dhcp6.socket"
         ]
       '';
-      description = ''
+      description = lib.mdDoc ''
         Paths to kea control sockets
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/knot.nix

···
     knotSocketPath = mkOption {
       type = types.str;
       default = "/run/knot/knot.sock";
-      description = ''
-        Socket path of <citerefentry><refentrytitle>knotd</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+      description = lib.mdDoc ''
+        Socket path of {manpage}`knotd(8)`.
       '';
     };
 
     knotSocketTimeout = mkOption {
       type = types.int;
       default = 2000;
-      description = ''
+      description = lib.mdDoc ''
         Timeout in seconds.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/lnd.nix

···
     lndHost = mkOption {
       type = types.str;
       default = "localhost:10009";
-      description = ''
+      description = lib.mdDoc ''
         lnd instance gRPC address:port.
       '';
     };
 
     lndTlsPath = mkOption {
       type = types.path;
-      description = ''
+      description = lib.mdDoc ''
         Path to lnd TLS certificate.
       '';
     };
 
     lndMacaroonDir = mkOption {
       type = types.path;
-      description = ''
+      description = lib.mdDoc ''
         Path to lnd macaroons.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/mail.nix

···
   serverOptions.options = {
     name = mkOption {
       type = types.str;
-      description = ''
+      description = lib.mdDoc ''
         Value for label 'configname' which will be added to all metrics.
       '';
     };
     server = mkOption {
       type = types.str;
-      description = ''
+      description = lib.mdDoc ''
         Hostname of the server that should be probed.
       '';
     };
     port = mkOption {
       type = types.int;
       example = 587;
-      description = ''
+      description = lib.mdDoc ''
         Port to use for SMTP.
       '';
     };
     from = mkOption {
       type = types.str;
       example = "[e-mail]";
-      description = ''
+      description = lib.mdDoc ''
         Content of 'From' Header for probing mails.
       '';
     };
     to = mkOption {
       type = types.str;
       example = "[e-mail]";
-      description = ''
+      description = lib.mdDoc ''
         Content of 'To' Header for probing mails.
       '';
     };
     detectionDir = mkOption {
       type = types.path;
       example = "/var/spool/mail/exporteruser/new";
-      description = ''
+      description = lib.mdDoc ''
         Directory in which new mails for the exporter user are placed.
         Note that this needs to exist when the exporter starts.
       '';
···
       type = types.nullOr types.str;
       default = null;
       example = "[e-mail]";
-      description = ''
+      description = lib.mdDoc ''
         Username to use for SMTP authentication.
       '';
     };
     passphrase = mkOption {
       type = types.nullOr types.str;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Password to use for SMTP authentication.
       '';
     };
···
     monitoringInterval = mkOption {
       type = types.str;
       example = "10s";
-      description = ''
+      description = lib.mdDoc ''
         Time interval between two probe attempts.
       '';
     };
     mailCheckTimeout = mkOption {
       type = types.str;
-      description = ''
+      description = lib.mdDoc ''
         Timeout until mails are considered "didn't make it".
       '';
     };
     disableFileDeletion = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Disables the exporter's function to delete probing mails.
       '';
     };
···
     environmentFile = mkOption {
       type = types.nullOr types.str;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         File containing env-vars to be substituted into the exporter's config.
       '';
     };
     configFile = mkOption {
       type = types.nullOr types.path;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Specify the mailexporter configuration file to use.
       '';
     };
     configuration = mkOption {
       type = types.nullOr (types.submodule exporterOptions);
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Specify the mailexporter configuration file to use.
       '';
     };
     telemetryPath = mkOption {
       type = types.str;
       default = "/metrics";
-      description = ''
+      description = lib.mdDoc ''
         Path under which to expose metrics.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/mikrotik.nix

···
     configFile = mkOption {
       type = types.nullOr types.path;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Path to a mikrotik exporter configuration file. Mutually exclusive with
-        <option>configuration</option> option.
+        {option}`configuration` option.
       '';
       example = literalExpression "./mikrotik.yml";
     };
···
     configuration = mkOption {
       type = types.nullOr types.attrs;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Mikrotik exporter configuration as nix attribute set. Mutually exclusive with
-        <option>configFile</option> option.
+        {option}`configFile` option.
 
-        See <link xlink:href="https://github.com/nshttpd/mikrotik-exporter/blob/master/README.md"/>
+        See <https://github.com/nshttpd/mikrotik-exporter/blob/master/README.md>
         for the description of the configuration file format.
       '';
       example = literalExpression ''

nixos/modules/services/monitoring/prometheus/exporters/minio.nix

···
     minioAddress = mkOption {
       type = types.str;
       example = "https://10.0.0.1:9000";
-      description = ''
+      description = lib.mdDoc ''
         The URL of the minio server.
         Use HTTPS if Minio accepts secure connections only.
         By default this connects to the local minio server if enabled.
···
     minioAccessKey = mkOption {
       type = types.str;
       example = "yourMinioAccessKey";
-      description = ''
+      description = lib.mdDoc ''
         The value of the Minio access key.
         It is required in order to connect to the server.
         By default this uses the one from the local minio server if enabled
-        and <literal>config.services.minio.accessKey</literal>.
+        and `config.services.minio.accessKey`.
       '';
     };
 
     minioAccessSecret = mkOption {
       type = types.str;
-      description = ''
+      description = lib.mdDoc ''
         The value of the Minio access secret.
         It is required in order to connect to the server.
         By default this uses the one from the local minio server if enabled
-        and <literal>config.services.minio.secretKey</literal>.
+        and `config.services.minio.secretKey`.
       '';
     };
 
     minioBucketStats = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Collect statistics about the buckets and files in buckets.
         It requires more computation, use it carefully in case of large buckets..
       '';

nixos/modules/services/monitoring/prometheus/exporters/modemmanager.nix

···
     refreshRate = mkOption {
       type = types.str;
       default = "5s";
-      description = ''
+      description = lib.mdDoc ''
         How frequently ModemManager will refresh the extended signal quality
         information for each modem. The duration should be specified in seconds
         ("5s"), minutes ("1m"), or hours ("1h").

nixos/modules/services/monitoring/prometheus/exporters/nextcloud.nix

···
     url = mkOption {
       type = types.str;
       example = "https://domain.tld";
-      description = ''
+      description = lib.mdDoc ''
         URL to the Nextcloud serverinfo page.
         Adding the path to the serverinfo API is optional, it defaults
-        to <literal>/ocs/v2.php/apps/serverinfo/api/v1/info</literal>.
+        to `/ocs/v2.php/apps/serverinfo/api/v1/info`.
       '';
     };
     username = mkOption {
       type = types.str;
       default = "nextcloud-exporter";
-      description = ''
+      description = lib.mdDoc ''
         Username for connecting to Nextcloud.
         Note that this account needs to have admin privileges in Nextcloud.
       '';
···
     passwordFile = mkOption {
       type = types.path;
       example = "/path/to/password-file";
-      description = ''
+      description = lib.mdDoc ''
         File containing the password for connecting to Nextcloud.
         Make sure that this file is readable by the exporter user.
       '';
···
     timeout = mkOption {
       type = types.str;
       default = "5s";
-      description = ''
+      description = lib.mdDoc ''
         Timeout for getting server info document.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/nginx.nix

···
     scrapeUri = mkOption {
       type = types.str;
       default = "http://localhost/nginx_status";
-      description = ''
+      description = lib.mdDoc ''
         Address to access the nginx status page.
         Can be enabled with services.nginx.statusPage = true.
       '';
···
     telemetryPath = mkOption {
       type = types.str;
       default = "/metrics";
-      description = ''
+      description = lib.mdDoc ''
         Path under which to expose metrics.
       '';
     };
     sslVerify = mkOption {
       type = types.bool;
       default = true;
-      description = ''
+      description = lib.mdDoc ''
         Whether to perform certificate verification for https.
       '';
     };
···
         "label1=value1"
         "label2=value2"
       ];
-      description = ''
+      description = lib.mdDoc ''
         A list of constant labels that will be used in every metric.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/nginxlog.nix

···
     metricsEndpoint = mkOption {
       type = types.str;
       default = "/metrics";
-      description = ''
+      description = lib.mdDoc ''
         Path under which to expose metrics.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/node.nix

···
       type = types.listOf types.str;
       default = [];
       example = [ "systemd" ];
-      description = ''
+      description = lib.mdDoc ''
         Collectors to enable. The collectors listed here are enabled in addition to the default ones.
       '';
     };
···
       type = types.listOf types.str;
       default = [];
       example = [ "timex" ];
-      description = ''
+      description = lib.mdDoc ''
         Collectors to disable which are enabled by default.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/openldap.nix

···
     metricsPath = mkOption {
       default = "/metrics";
       type = types.str;
-      description = ''
+      description = lib.mdDoc ''
         URL path where metrics should be exposed.
       '';
     };
···
       default = "30s";
       type = types.str;
       example = "1m";
-      description = ''
+      description = lib.mdDoc ''
         Scrape interval of the exporter.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/openvpn.nix

···
   extraOpts = {
     statusPaths = mkOption {
       type = types.listOf types.str;
-      description = ''
+      description = lib.mdDoc ''
         Paths to OpenVPN status files. Please configure the OpenVPN option
-        <literal>status</literal> accordingly.
+        `status` accordingly.
       '';
     };
     telemetryPath = mkOption {
       type = types.str;
       default = "/metrics";
-      description = ''
+      description = lib.mdDoc ''
         Path under which to expose metrics.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/pihole.nix

···
       type = types.str;
       default = "";
       example = "580a770cb40511eb85290242ac130003580a770cb40511eb85290242ac130003";
-      description = ''
+      description = lib.mdDoc ''
         pi-hole API token which can be used instead of a password
       '';
     };
···
       type = types.str;
       default = "10s";
       example = "30s";
-      description = ''
+      description = lib.mdDoc ''
         How often to scrape new data
       '';
     };
···
       type = types.str;
       default = "";
       example = "password";
-      description = ''
+      description = lib.mdDoc ''
         The password to login into pihole. An api token can be used instead.
       '';
     };
···
       type = types.str;
       default = "pihole";
       example = "127.0.0.1";
-      description = ''
+      description = lib.mdDoc ''
         Hostname or address where to find the pihole webinterface
       '';
     };
···
       type = types.port;
       default = 80;
       example = 443;
-      description = ''
+      description = lib.mdDoc ''
         The port pihole webinterface is reachable on
       '';
     };
···
       type = types.enum [ "http" "https" ];
       default = "http";
       example = "https";
-      description = ''
+      description = lib.mdDoc ''
         The protocol which is used to connect to pihole
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/postfix.nix

···
   extraOpts = {
     group = mkOption {
       type = types.str;
-      description = ''
+      description = lib.mdDoc ''
         Group under which the postfix exporter shall be run.
         It should match the group that is allowed to access the
-        <literal>showq</literal> socket in the <literal>queue/public/</literal> directory.
-        Defaults to <literal>services.postfix.setgidGroup</literal> when postfix is enabled.
+        `showq` socket in the `queue/public/` directory.
+        Defaults to `services.postfix.setgidGroup` when postfix is enabled.
       '';
     };
     telemetryPath = mkOption {
       type = types.str;
       default = "/metrics";
-      description = ''
+      description = lib.mdDoc ''
         Path under which to expose metrics.
       '';
     };
···
       type = types.path;
       default = "/var/log/postfix_exporter_input.log";
       example = "/var/log/mail.log";
-      description = ''
+      description = lib.mdDoc ''
         Path where Postfix writes log entries.
         This file will be truncated by this exporter!
       '';
···
       type = types.path;
       default = "/var/lib/postfix/queue/public/showq";
       example = "/var/spool/postfix/public/showq";
-      description = ''
+      description = lib.mdDoc ''
         Path where Postfix places its showq socket.
       '';
     };
···
       enable = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable reading metrics from the systemd journal instead of from a logfile
         '';
       };
       unit = mkOption {
         type = types.str;
         default = "postfix.service";
-        description = ''
+        description = lib.mdDoc ''
           Name of the postfix systemd unit.
         '';
       };
       slice = mkOption {
         type = types.nullOr types.str;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Name of the postfix systemd slice.
-          This overrides the <option>systemd.unit</option>.
+          This overrides the {option}`systemd.unit`.
         '';
       };
       journalPath = mkOption {
         type = types.nullOr types.path;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Path to the systemd journal.
         '';
       };

nixos/modules/services/monitoring/prometheus/exporters/postgres.nix

···
     telemetryPath = mkOption {
       type = types.str;
       default = "/metrics";
-      description = ''
+      description = lib.mdDoc ''
         Path under which to expose metrics.
       '';
     };
···
       type = types.str;
       default = "user=postgres database=postgres host=/run/postgresql sslmode=disable";
       example = "postgresql://username:password@localhost:5432/postgres?sslmode=disable";
-      description = ''
+      description = lib.mdDoc ''
         Accepts PostgreSQL URI form and key=value form arguments.
       '';
     };
     runAsLocalSuperUser = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether to run the exporter as the local 'postgres' super user.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/process.nix

···
           { name = "{{.Matches.Wrapped}} {{ .Matches.Args }}"; cmdline = [ "^/nix/store[^ ]*/(?P<Wrapped>[^ /]*) (?P<Args>.*)" ]; }
         ]
       '';
-      description = ''
+      description = lib.mdDoc ''
         All settings expressed as an Nix attrset.
 
         Check the official documentation for the corresponding YAML
-        settings that can all be used here: <link xlink:href="https://github.com/ncabatoff/process-exporter"/>
+        settings that can all be used here: <https://github.com/ncabatoff/process-exporter>
       '';
     };
   };

nixos/modules/services/monitoring/prometheus/exporters/pve.nix

···
       default = pkgs.prometheus-pve-exporter;
       defaultText = literalExpression "pkgs.prometheus-pve-exporter";
       example = literalExpression "pkgs.prometheus-pve-exporter";
-      description = ''
+      description = lib.mdDoc ''
         The package to use for prometheus-pve-exporter
       '';
     };
···
       type = with types; nullOr path;
       default = null;
       example = "/etc/prometheus-pve-exporter/pve.env";
-      description = ''
+      description = lib.mdDoc ''
         Path to the service's environment file. This path can either be a computed path in /nix/store or a path in the local filesystem.
 
         The environment file should NOT be stored in /nix/store as it contains passwords and/or keys in plain text.
···
       type = with types; nullOr path;
       default = null;
       example = "/etc/prometheus-pve-exporter/pve.yml";
-      description = ''
+      description = lib.mdDoc ''
         Path to the service's config file. This path can either be a computed path in /nix/store or a path in the local filesystem.
 
         The config file should NOT be stored in /nix/store as it will contain passwords and/or keys in plain text.
···
       status = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Collect Node/VM/CT status
         '';
       };
       version = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Collect PVE version info
         '';
       };
       node = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Collect PVE node info
         '';
       };
       cluster = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Collect PVE cluster info
         '';
       };
       resources = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Collect PVE resources info
         '';
       };
       config = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Collect PVE onboot status
         '';
       };

nixos/modules/services/monitoring/prometheus/exporters/py-air-control.nix

···
     deviceHostname = mkOption {
       type = types.str;
       example = "192.168.1.123";
-      description = ''
+      description = lib.mdDoc ''
         The hostname of the air purification device from which to scrape the metrics.
       '';
     };
     protocol = mkOption {
       type = types.str;
       default = "http";
-      description = ''
+      description = lib.mdDoc ''
         The protocol to use when communicating with the air purification device.
         Available: [http, coap, plain_coap]
       '';
···
     stateDir = mkOption {
       type = types.str;
       default = "prometheus-py-air-control-exporter";
-      description = ''
-        Directory below <literal>/var/lib</literal> to store runtime data.
+      description = lib.mdDoc ''
+        Directory below `/var/lib` to store runtime data.
         This directory will be created automatically using systemd's StateDirectory mechanism.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/rspamd.nix

···
           custom_label = "some_value";
         }
       '';
-      description = "Set of labels added to each metric.";
+      description = lib.mdDoc "Set of labels added to each metric.";
     };
   };
   serviceOpts.serviceConfig.ExecStart = ''

nixos/modules/services/monitoring/prometheus/exporters/rtl_433.nix

···
         options = {
           name = lib.mkOption {
             type = str;
-            description = "Name to match.";
+            description = lib.mdDoc "Name to match.";
           };
           "${field}" = lib.mkOption {
             type = int;
···
           };
           location = lib.mkOption {
             type = str;
-            description = "Location to match.";
+            description = lib.mdDoc "Location to match.";
           };
         };
       });
···
       type = lib.types.str;
       default = "-C si";
       example = "-C si -R 19";
-      description = ''
+      description = lib.mdDoc ''
         Flags passed verbatim to rtl_433 binary.
-        Having <literal>-C si</literal> (the default) is recommended since only Celsius temperatures are parsed.
+        Having `-C si` (the default) is recommended since only Celsius temperatures are parsed.
       '';
     };
     channels = lib.mkOption {
···
       example = [
         { name = "Acurite"; channel = 6543; location = "Kitchen"; }
       ];
-      description = ''
+      description = lib.mdDoc ''
         List of channel matchers to export.
       '';
     };
···
       example = [
         { name = "Nexus"; id = 1; location = "Bedroom"; }
       ];
-      description = ''
+      description = lib.mdDoc ''
         List of ID matchers to export.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/script.nix

···
           name = mkOption {
             type = str;
             example = "sleep";
-            description = "Name of the script.";
+            description = lib.mdDoc "Name of the script.";
           };
           script = mkOption {
             type = str;
             example = "sleep 5";
-            description = "Shell script to execute when metrics are requested.";
+            description = lib.mdDoc "Shell script to execute when metrics are requested.";
           };
           timeout = mkOption {
             type = nullOr int;
             default = null;
             example = 60;
-            description = "Optional timeout for the script in seconds.";
+            description = lib.mdDoc "Optional timeout for the script in seconds.";
           };
         };
       });
···
           ];
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         All settings expressed as an Nix attrset.
 
         Check the official documentation for the corresponding YAML
-        settings that can all be used here: <link xlink:href="https://github.com/adhocteam/script_exporter#sample-configuration"/>
+        settings that can all be used here: <https://github.com/adhocteam/script_exporter#sample-configuration>
       '';
     };
   };

nixos/modules/services/monitoring/prometheus/exporters/smartctl.nix

···
       example = literalExpression ''
         [ "/dev/sda", "/dev/nvme0n1" ];
       '';
-      description = ''
+      description = lib.mdDoc ''
         Paths to the disks that will be monitored. Will autodiscover
         all disks if none given.
       '';
···
       type = types.str;
       default = "60s";
       example = "2m";
-      description = ''
+      description = lib.mdDoc ''
         Interval that limits how often a disk can be queried.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/smokeping.nix

···
     telemetryPath = mkOption {
       type = types.str;
       default = "/metrics";
-      description = ''
+      description = lib.mdDoc ''
         Path under which to expose metrics.
       '';
     };
     pingInterval = mkOption {
       type = goDuration;
       default = "1s";
-      description = ''
+      description = lib.mdDoc ''
         Interval between pings.
       '';
     };
     buckets = mkOption {
       type = types.commas;
       default = "5e-05,0.0001,0.0002,0.0004,0.0008,0.0016,0.0032,0.0064,0.0128,0.0256,0.0512,0.1024,0.2048,0.4096,0.8192,1.6384,3.2768,6.5536,13.1072,26.2144";
-      description = ''
+      description = lib.mdDoc ''
         List of buckets to use for the response duration histogram.
       '';
     };
     hosts = mkOption {
       type = with types; listOf str;
-      description = ''
+      description = lib.mdDoc ''
         List of endpoints to probe.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/snmp.nix

···
     configurationPath = mkOption {
       type = types.nullOr types.path;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Path to a snmp exporter configuration file. Mutually exclusive with 'configuration' option.
       '';
       example = literalExpression "./snmp.yml";
···
     configuration = mkOption {
       type = types.nullOr types.attrs;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Snmp exporter configuration as nix attribute set. Mutually exclusive with 'configurationPath' option.
       '';
       example = {
···
     logFormat = mkOption {
       type = types.enum ["logfmt" "json"];
       default = "logfmt";
-      description = ''
+      description = lib.mdDoc ''
         Output format of log messages.
       '';
     };
···
     logLevel = mkOption {
       type = types.enum ["debug" "info" "warn" "error"];
       default = "info";
-      description = ''
+      description = lib.mdDoc ''
         Only log messages with the given severity or above.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/sql.nix

···
       jobs = mkOption {
         type = attrsOf (submodule jobOptions);
         default = { };
-        description = "An attrset of metrics scraping jobs to run.";
+        description = lib.mdDoc "An attrset of metrics scraping jobs to run.";
       };
     };
   };
···
     options = with types; {
       interval = mkOption {
         type = str;
-        description = ''
+        description = lib.mdDoc ''
           How often to run this job, specified in
-          <link xlink:href="https://golang.org/pkg/time/#ParseDuration">Go duration</link> format.
+          [Go duration](https://golang.org/pkg/time/#ParseDuration) format.
         '';
       };
       connections = mkOption {
         type = listOf str;
-        description = "A list of connection strings of the SQL servers to scrape metrics from";
+        description = lib.mdDoc "A list of connection strings of the SQL servers to scrape metrics from";
       };
       startupSql = mkOption {
         type = listOf str;
         default = [];
-        description = "A list of SQL statements to execute once after making a connection.";
+        description = lib.mdDoc "A list of SQL statements to execute once after making a connection.";
       };
       queries = mkOption {
         type = attrsOf (submodule queryOptions);
-        description = "SQL queries to run.";
+        description = lib.mdDoc "SQL queries to run.";
       };
     };
   };
···
       help = mkOption {
         type = nullOr str;
         default = null;
-        description = "A human-readable description of this metric.";
+        description = lib.mdDoc "A human-readable description of this metric.";
       };
       labels = mkOption {
         type = listOf str;
         default = [ ];
-        description = "A set of columns that will be used as Prometheus labels.";
+        description = lib.mdDoc "A set of columns that will be used as Prometheus labels.";
       };
       query = mkOption {
         type = str;
-        description = "The SQL query to run.";
+        description = lib.mdDoc "The SQL query to run.";
       };
       values = mkOption {
         type = listOf str;
-        description = "A set of columns that will be used as values of this metric.";
+        description = lib.mdDoc "A set of columns that will be used as values of this metric.";
       };
     };
   };
···
     configFile = mkOption {
       type = with types; nullOr path;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Path to configuration file.
       '';
     };
     configuration = mkOption {
       type = with types; nullOr (submodule cfgOptions);
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Exporter configuration as nix attribute set. Mutually exclusive with 'configFile' option.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/surfboard.nix

···
     modemAddress = mkOption {
       type = types.str;
       default = "192.168.100.1";
-      description = ''
+      description = lib.mdDoc ''
         The hostname or IP of the cable modem.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/tor.nix

···
     torControlAddress = mkOption {
       type = types.str;
       default = "127.0.0.1";
-      description = ''
+      description = lib.mdDoc ''
         Tor control IP address or hostname.
       '';
     };
···
     torControlPort = mkOption {
       type = types.int;
       default = 9051;
-      description = ''
+      description = lib.mdDoc ''
         Tor control port.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/unbound.nix

···
       # TODO: add shm when upstream implemented it
       type = types.enum [ "tcp" "uds" ];
       default = "uds";
-      description = ''
+      description = lib.mdDoc ''
         Which methods the exporter uses to get the information from unbound.
       '';
     };
···
     telemetryPath = mkOption {
       type = types.str;
       default = "/metrics";
-      description = ''
+      description = lib.mdDoc ''
         Path under which to expose metrics.
       '';
     };
···
       type = types.nullOr types.str;
       default = null;
       example = "/run/unbound/unbound.socket";
-      description = ''
+      description = lib.mdDoc ''
         Path to the unbound socket for uds mode or the control interface port for tcp mode.
 
         Example:

nixos/modules/services/monitoring/prometheus/exporters/unifi.nix

···
     unifiAddress = mkOption {
       type = types.str;
       example = "https://10.0.0.1:8443";
-      description = ''
+      description = lib.mdDoc ''
         URL of the UniFi Controller API.
       '';
     };
···
     unifiInsecure = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         If enabled skip the verification of the TLS certificate of the UniFi Controller API.
         Use with caution.
       '';
···
     unifiUsername = mkOption {
       type = types.str;
       example = "ReadOnlyUser";
-      description = ''
+      description = lib.mdDoc ''
         username for authentication against UniFi Controller API.
       '';
     };
 
     unifiPassword = mkOption {
       type = types.str;
-      description = ''
+      description = lib.mdDoc ''
         Password for authentication against UniFi Controller API.
       '';
     };
···
       type = types.str;
       default = "5s";
       example = "2m";
-      description = ''
+      description = lib.mdDoc ''
         Timeout including unit for UniFi Controller API requests.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/varnish.nix

···
     noExit = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Do not exit server on Varnish scrape errors.
       '';
     };
     withGoMetrics = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Export go runtime and http handler metrics.
       '';
     };
     verbose = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Enable verbose logging.
       '';
     };
     raw = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Enable raw stdout logging without timestamps.
       '';
     };
     varnishStatPath = mkOption {
       type = types.str;
       default = "varnishstat";
-      description = ''
+      description = lib.mdDoc ''
         Path to varnishstat.
       '';
     };
···
       type = types.nullOr types.str;
       default = config.services.varnish.stateDir;
       defaultText = lib.literalExpression "config.services.varnish.stateDir";
-      description = ''
+      description = lib.mdDoc ''
         varnishstat -n value.
       '';
     };
     healthPath = mkOption {
       type = types.nullOr types.str;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Path under which to expose healthcheck. Disabled unless configured.
       '';
     };
     telemetryPath = mkOption {
       type = types.str;
       default = "/metrics";
-      description = ''
+      description = lib.mdDoc ''
         Path under which to expose metrics.
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/wireguard.nix

···
       type = with types; nullOr (either path str);
       default = null;
 
-      description = ''
+      description = lib.mdDoc ''
         Path to the Wireguard Config to
-        <link xlink:href="https://github.com/MindFlavor/prometheus_wireguard_exporter/tree/2.0.0#usage">add the peer's name to the stats of a peer</link>.
+        [add the peer's name to the stats of a peer](https://github.com/MindFlavor/prometheus_wireguard_exporter/tree/2.0.0#usage).
 
-        Please note that <literal>networking.wg-quick</literal> is required for this feature
-        as <literal>networking.wireguard</literal> uses
-        <citerefentry><refentrytitle>wg</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+        Please note that `networking.wg-quick` is required for this feature
+        as `networking.wireguard` uses
+        {manpage}`wg(8)`
         to set the peers up.
       '';
     };
···
     singleSubnetPerField = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         By default, all allowed IPs and subnets are comma-separated in the
-        <literal>allowed_ips</literal> field. With this option enabled,
-        a single IP and subnet will be listed in fields like <literal>allowed_ip_0</literal>,
-        <literal>allowed_ip_1</literal> and so on.
+        `allowed_ips` field. With this option enabled,
+        a single IP and subnet will be listed in fields like `allowed_ip_0`,
+        `allowed_ip_1` and so on.
       '';
     };
 
     withRemoteIp = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether or not the remote IP of a WireGuard peer should be exposed via prometheus.
       '';
     };

nixos/modules/services/network-filesystems/netatalk.nix

···
             "read only" = true;
           };
         };
-        description = ''
+        description = lib.mdDoc ''
           Configuration for Netatalk. See
-          <citerefentry><refentrytitle>afp.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+          {manpage}`afp.conf(5)`.
         '';
       };
 
       extmap = mkOption {
         type = types.lines;
         default = "";
-        description = ''
+        description = lib.mdDoc ''
           File name extension mappings.
-          See <citerefentry><refentrytitle>extmap.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. for more information.
+          See {manpage}`extmap.conf(5)`. for more information.
         '';
       };
 

nixos/modules/services/network-filesystems/nfsd.nix

···
         exports = mkOption {
           type = types.lines;
           default = "";
-          description = ''
+          description = lib.mdDoc ''
             Contents of the /etc/exports file.  See
-            <citerefentry><refentrytitle>exports</refentrytitle><manvolnum>5</manvolnum></citerefentry> for the format.
+            {manpage}`exports(5)` for the format.
           '';
         };
 
         hostName = mkOption {
           type = types.nullOr types.str;
           default = null;
-          description = ''
+          description = lib.mdDoc ''
             Hostname or address on which NFS requests will be accepted.
-            Default is all.  See the <option>-H</option> option in
-            <citerefentry><refentrytitle>nfsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+            Default is all.  See the {option}`-H` option in
+            {manpage}`nfsd(8)`.
           '';
         };
 

nixos/modules/services/network-filesystems/openafs/client.nix

···
       enable = mkOption {
         default = false;
         type = types.bool;
-        description = "Whether to enable the OpenAFS client.";
+        description = lib.mdDoc "Whether to enable the OpenAFS client.";
       };
 
       afsdb = mkOption {
         default = true;
         type = types.bool;
-        description = "Resolve cells via AFSDB DNS records.";
+        description = lib.mdDoc "Resolve cells via AFSDB DNS records.";
       };
 
       cellName = mkOption {
         default = "";
         type = types.str;
-        description = "Cell name.";
+        description = lib.mdDoc "Cell name.";
         example = "grand.central.org";
       };
 
       cellServDB = mkOption {
         default = [];
         type = with types; listOf (submodule { options = cellServDBConfig; });
-        description = ''
+        description = lib.mdDoc ''
           This cell's database server records, added to the global
           CellServDB. See CellServDB(5) man page for syntax. Ignored when
-          <literal>afsdb</literal> is set to <literal>true</literal>.
+          `afsdb` is set to `true`.
         '';
         example = [
           { ip = "1.2.3.4"; dnsname = "first.afsdb.server.dns.fqdn.org"; }
···
         blocks = mkOption {
           default = 100000;
           type = types.int;
-          description = "Cache size in 1KB blocks.";
+          description = lib.mdDoc "Cache size in 1KB blocks.";
         };
 
         chunksize = mkOption {
           default = 0;
           type = types.ints.between 0 30;
-          description = ''
+          description = lib.mdDoc ''
             Size of each cache chunk given in powers of
-            2. <literal>0</literal> resets the chunk size to its default
+            2. `0` resets the chunk size to its default
             values (13 (8 KB) for memcache, 18-20 (256 KB to 1 MB) for
             diskcache). Maximum value is 30. Important performance
             parameter. Set to higher values when dealing with large files.
···
         directory = mkOption {
           default = "/var/cache/openafs";
           type = types.str;
-          description = "Cache directory.";
+          description = lib.mdDoc "Cache directory.";
         };
 
         diskless = mkOption {
           default = false;
           type = types.bool;
-          description = ''
+          description = lib.mdDoc ''
             Use in-memory cache for diskless machines. Has no real
             performance benefit anymore.
           '';
···
       crypt = mkOption {
         default = true;
         type = types.bool;
-        description = "Whether to enable (weak) protocol encryption.";
+        description = lib.mdDoc "Whether to enable (weak) protocol encryption.";
       };
 
       daemons = mkOption {
         default = 2;
         type = types.int;
-        description = ''
+        description = lib.mdDoc ''
           Number of daemons to serve user requests. Numbers higher than 6
           usually do no increase performance. Default is sufficient for up
           to five concurrent users.
···
       fakestat = mkOption {
         default = false;
         type = types.bool;
-        description = ''
-          Return fake data on stat() calls. If <literal>true</literal>,
-          always do so. If <literal>false</literal>, only do so for
+        description = lib.mdDoc ''
+          Return fake data on stat() calls. If `true`,
+          always do so. If `false`, only do so for
           cross-cell mounts (as these are potentially expensive).
         '';
       };
···
       inumcalc = mkOption {
         default = "compat";
         type = types.strMatching "compat|md5";
-        description = ''
-          Inode calculation method. <literal>compat</literal> is
-          computationally less expensive, but <literal>md5</literal> greatly
+        description = lib.mdDoc ''
+          Inode calculation method. `compat` is
+          computationally less expensive, but `md5` greatly
           reduces the likelihood of inode collisions in larger scenarios
           involving multiple cells mounted into one AFS space.
         '';
···
       mountPoint = mkOption {
         default = "/afs";
         type = types.str;
-        description = ''
+        description = lib.mdDoc ''
           Mountpoint of the AFS file tree, conventionally
-          <literal>/afs</literal>. When set to a different value, only
+          `/afs`. When set to a different value, only
           cross-cells that use the same value can be accessed.
         '';
       };
···
           default = config.boot.kernelPackages.openafs;
           defaultText = literalExpression "config.boot.kernelPackages.openafs";
           type = types.package;
-          description = "OpenAFS kernel module package. MUST match the userland package!";
+          description = lib.mdDoc "OpenAFS kernel module package. MUST match the userland package!";
         };
         programs = mkOption {
           default = getBin pkgs.openafs;
           defaultText = literalExpression "getBin pkgs.openafs";
           type = types.package;
-          description = "OpenAFS programs package. MUST match the kernel module package!";
+          description = lib.mdDoc "OpenAFS programs package. MUST match the kernel module package!";
         };
       };
 
       sparse = mkOption {
         default = true;
         type = types.bool;
-        description = "Minimal cell list in /afs.";
+        description = lib.mdDoc "Minimal cell list in /afs.";
       };
 
       startDisconnected = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Start up in disconnected mode.  You need to execute
-          <literal>fs disco online</literal> (as root) to switch to
+          `fs disco online` (as root) to switch to
           connected mode. Useful for roaming devices.
         '';
       };

nixos/modules/services/network-filesystems/openafs/lib.nix

···
       type = types.str;
       default = "";
       example = "1.2.3.4";
-      description = "IP Address of a database server";
+      description = lib.mdDoc "IP Address of a database server";
     };
     dnsname = mkOption {
       type = types.str;
       default = "";
       example = "afs.example.org";
-      description = "DNS full-qualified domain name of a database server";
+      description = lib.mdDoc "DNS full-qualified domain name of a database server";
     };
   };
 

nixos/modules/services/network-filesystems/openafs/server.nix

···
       enable = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable the OpenAFS server. An OpenAFS server needs a
           complex setup. So, be aware that enabling this service and setting
           some options does not give you a turn-key-ready solution. You need
           at least a running Kerberos 5 setup, as OpenAFS relies on it for
           authentication. See the Guide "QuickStartUnix" coming with
-          <literal>pkgs.openafs.doc</literal> for complete setup
+          `pkgs.openafs.doc` for complete setup
           instructions.
         '';
       };
···
       advertisedAddresses = mkOption {
         type = types.listOf types.str;
         default = [];
-        description = "List of IP addresses this server is advertised under. See NetInfo(5)";
+        description = lib.mdDoc "List of IP addresses this server is advertised under. See NetInfo(5)";
       };
 
       cellName = mkOption {
         default = "";
         type = types.str;
-        description = "Cell name, this server will serve.";
+        description = lib.mdDoc "Cell name, this server will serve.";
         example = "grand.central.org";
       };
 
       cellServDB = mkOption {
         default = [];
         type = with types; listOf (submodule [ { options = cellServDBConfig;} ]);
-        description = "Definition of all cell-local database server machines.";
+        description = lib.mdDoc "Definition of all cell-local database server machines.";
       };
 
       package = mkOption {
         default = pkgs.openafs.server or pkgs.openafs;
         defaultText = literalExpression "pkgs.openafs.server or pkgs.openafs";
         type = types.package;
-        description = "OpenAFS package for the server binaries";
+        description = lib.mdDoc "OpenAFS package for the server binaries";
       };
 
       roles = {
···
           enable = mkOption {
             default = true;
             type = types.bool;
-            description = "Fileserver role, serves files and volumes from its local storage.";
+            description = lib.mdDoc "Fileserver role, serves files and volumes from its local storage.";
           };
 
           fileserverArgs = mkOption {
             default = "-vattachpar 128 -vhashsize 11 -L -rxpck 400 -cb 1000000";
             type = types.str;
-            description = "Arguments to the dafileserver process. See its man page.";
+            description = lib.mdDoc "Arguments to the dafileserver process. See its man page.";
           };
 
           volserverArgs = mkOption {
             default = "";
             type = types.str;
-            description = "Arguments to the davolserver process. See its man page.";
+            description = lib.mdDoc "Arguments to the davolserver process. See its man page.";
             example = "-sync never";
           };
 
           salvageserverArgs = mkOption {
             default = "";
             type = types.str;
-            description = "Arguments to the salvageserver process. See its man page.";
+            description = lib.mdDoc "Arguments to the salvageserver process. See its man page.";
             example = "-showlog";
           };
 
           salvagerArgs = mkOption {
             default = "";
             type = types.str;
-            description = "Arguments to the dasalvager process. See its man page.";
+            description = lib.mdDoc "Arguments to the dasalvager process. See its man page.";
             example = "-showlog -showmounts";
           };
         };
···
           enable = mkOption {
             default = true;
             type = types.bool;
-            description = ''
+            description = lib.mdDoc ''
               Database server role, maintains the Volume Location Database,
               Protection Database (and Backup Database, see
-              <literal>backup</literal> role). There can be multiple
+              `backup` role). There can be multiple
               servers in the database role for replication, which then need
               reliable network connection to each other.
 
···
           vlserverArgs = mkOption {
             default = "";
             type = types.str;
-            description = "Arguments to the vlserver process. See its man page.";
+            description = lib.mdDoc "Arguments to the vlserver process. See its man page.";
             example = "-rxbind";
           };
 
           ptserverArgs = mkOption {
             default = "";
             type = types.str;
-            description = "Arguments to the ptserver process. See its man page.";
+            description = lib.mdDoc "Arguments to the ptserver process. See its man page.";
             example = "-restricted -default_access S---- S-M---";
           };
         };
···
           enable = mkOption {
             default = false;
             type = types.bool;
-            description = ''
+            description = lib.mdDoc ''
               Backup server role. Use in conjunction with the
-              <literal>database</literal> role to maintain the Backup
+              `database` role to maintain the Backup
               Database. Normally only used in conjunction with tape storage
               or IBM's Tivoli Storage Manager.
             '';
···
           buserverArgs = mkOption {
             default = "";
             type = types.str;
-            description = "Arguments to the buserver process. See its man page.";
+            description = lib.mdDoc "Arguments to the buserver process. See its man page.";
             example = "-p 8";
           };
 
           cellServDB = mkOption {
             default = [];
             type = with types; listOf (submodule [ { options = cellServDBConfig;} ]);
-            description = ''
+            description = lib.mdDoc ''
               Definition of all cell-local backup database server machines.
               Use this when your cell uses less backup database servers than
               other database server machines.
···
       dottedPrincipals= mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           If enabled, allow principal names containing (.) dots. Enabling
           this has security implications!
         '';
···
       udpPacketSize = mkOption {
         default = 1310720;
         type = types.int;
-        description = ''
+        description = lib.mdDoc ''
           UDP packet size to use in Bytes. Higher values can speed up
           communications. The default of 1 MB is a sufficient in most
           cases. Make sure to increase the kernel's UDP buffer size
-          accordingly via <literal>net.core(w|r|opt)mem_max</literal>
+          accordingly via `net.core(w|r|opt)mem_max`
           sysctl.
         '';
       };

nixos/modules/services/network-filesystems/rsyncd.nix

···
             "secrets file" = "/etc/rsyncd.secrets";
           };
         };
-        description = ''
+        description = lib.mdDoc ''
           Configuration for rsyncd. See
-          <citerefentry><refentrytitle>rsyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+          {manpage}`rsyncd.conf(5)`.
         '';
       };
 

nixos/modules/services/network-filesystems/webdav.nix

···
       environmentFile = mkOption {
         type = types.nullOr types.path;
         default = null;
-        description = ''
-          Environment file as defined in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+        description = lib.mdDoc ''
+          Environment file as defined in {manpage}`systemd.exec(5)`.
         '';
       };
     };

nixos/modules/services/networking/avahi-daemon.nix

···
           ''';
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         Specify custom service definitions which are placed in the avahi service directory.
-        See the <citerefentry><refentrytitle>avahi.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> manpage for detailed information.
+        See the {manpage}`avahi.service(5)` manpage for detailed information.
       '';
     };
 

nixos/modules/services/networking/keepalived/default.nix

···
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable Keepalived.
         '';
       };
···
       enableScriptSecurity = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Don't run scripts configured to be run as root if any part of the path is writable by a non-root user.
         '';
       };
···
         enable = mkOption {
           type = types.bool;
           default = false;
-          description = ''
+          description = lib.mdDoc ''
             Whether to enable the builtin AgentX subagent.
           '';
         };
···
         socket = mkOption {
           type = types.nullOr types.str;
           default = null;
-          description = ''
+          description = lib.mdDoc ''
             Socket to use for connecting to SNMP master agent. If this value is
             set to null, keepalived's default will be used, which is
             unix:/var/agentx/master, unless using a network namespace, when the
···
         enableKeepalived = mkOption {
           type = types.bool;
           default = false;
-          description = ''
+          description = lib.mdDoc ''
             Enable SNMP handling of vrrp element of KEEPALIVED MIB.
           '';
         };
···
         enableChecker = mkOption {
           type = types.bool;
           default = false;
-          description = ''
+          description = lib.mdDoc ''
             Enable SNMP handling of checker element of KEEPALIVED MIB.
           '';
         };
···
         enableRfc = mkOption {
           type = types.bool;
           default = false;
-          description = ''
+          description = lib.mdDoc ''
             Enable SNMP handling of RFC2787 and RFC6527 VRRP MIBs.
           '';
         };
···
         enableRfcV2 = mkOption {
           type = types.bool;
           default = false;
-          description = ''
+          description = lib.mdDoc ''
             Enable SNMP handling of RFC2787 VRRP MIB.
           '';
         };
···
         enableRfcV3 = mkOption {
           type = types.bool;
           default = false;
-          description = ''
+          description = lib.mdDoc ''
             Enable SNMP handling of RFC6527 VRRP MIB.
           '';
         };
···
         enableTraps = mkOption {
           type = types.bool;
           default = false;
-          description = ''
+          description = lib.mdDoc ''
             Enable SNMP traps.
           '';
         };
···
           inherit lib;
         }));
         default = {};
-        description = "Declarative vrrp script config";
+        description = lib.mdDoc "Declarative vrrp script config";
       };
 
       vrrpInstances = mkOption {
···
           inherit lib;
         }));
         default = {};
-        description = "Declarative vhost config";
+        description = lib.mdDoc "Declarative vhost config";
       };
 
       extraGlobalDefs = mkOption {
         type = types.lines;
         default = "";
-        description = ''
+        description = lib.mdDoc ''
           Extra lines to be added verbatim to the 'global_defs' block of the
           configuration file
         '';
···
       extraConfig = mkOption {
         type = types.lines;
         default = "";
-        description = ''
+        description = lib.mdDoc ''
           Extra lines to be added verbatim to the configuration file.
         '';
       };

nixos/modules/services/networking/keepalived/virtual-ip-options.nix

···
 
     addr = mkOption {
       type = types.str;
-      description = ''
+      description = lib.mdDoc ''
         IP address, optionally with a netmask: IPADDR[/MASK]
       '';
     };
···
     brd = mkOption {
       type = types.nullOr types.str;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         The broadcast address on the interface.
       '';
     };
···
     dev = mkOption {
       type = types.nullOr types.str;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         The name of the device to add the address to.
       '';
     };
···
     scope = mkOption {
       type = types.nullOr types.str;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         The scope of the area where this address is valid.
       '';
     };
···
     label = mkOption {
       type = types.nullOr types.str;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Each address may be tagged with a label string. In order to preserve
         compatibility with Linux-2.0 net aliases, this string must coincide with
         the name of the device or must be prefixed with the device name followed

nixos/modules/services/networking/keepalived/vrrp-instance-options.nix

···
 
     interface = mkOption {
       type = types.str;
-      description = ''
+      description = lib.mdDoc ''
         Interface for inside_network, bound by vrrp.
       '';
     };
···
     state = mkOption {
       type = types.enum [ "MASTER" "BACKUP" ];
       default = "BACKUP";
-      description = ''
+      description = lib.mdDoc ''
         Initial state. As soon as the other machine(s) come up, an election will
         be held and the machine with the highest "priority" will become MASTER.
         So the entry here doesn't matter a whole lot.
···
 
     virtualRouterId = mkOption {
       type = types.int;
-      description = ''
+      description = lib.mdDoc ''
         Arbitrary unique number 0..255. Used to differentiate multiple instances
         of vrrpd running on the same NIC (and hence same socket).
       '';
···
     priority = mkOption {
       type = types.int;
       default = 100;
-      description = ''
+      description = lib.mdDoc ''
         For electing MASTER, highest priority wins. To be MASTER, make 50 more
         than other machines.
       '';
···
     noPreempt = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         VRRP will normally preempt a lower priority machine when a higher
         priority machine comes online. "nopreempt" allows the lower priority
         machine to maintain the master role, even when a higher priority machine
···
     useVmac = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Use VRRP Virtual MAC.
       '';
     };
···
     vmacInterface = mkOption {
       type = types.nullOr types.str;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
          Name of the vmac interface to use. keepalived will come up with a name
          if you don't specify one.
       '';
···
     vmacXmitBase = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Send/Recv VRRP messages from base interface instead of VMAC interface.
       '';
     };
···
     unicastSrcIp = mkOption {
       type = types.nullOr types.str;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
          Default IP for binding vrrpd is the primary IP on interface. If you
          want to hide location of vrrpd, use this IP as src_addr for unicast
          vrrp packets.
···
     unicastPeers = mkOption {
       type = types.listOf types.str;
       default = [];
-      description = ''
+      description = lib.mdDoc ''
         Do not send VRRP adverts over VRRP multicast group. Instead it sends
         adverts to the following list of ip addresses using unicast design
         fashion. It can be cool to use VRRP FSM and features in a networking
···
       }));
       default = [];
       # TODO: example
-      description = "Declarative vhost config";
+      description = lib.mdDoc "Declarative vhost config";
     };
 
     trackScripts = mkOption {
       type = types.listOf types.str;
       default = [];
       example = [ "chk_cmd1" "chk_cmd2" ];
-      description = "List of script names to invoke for health tracking.";
+      description = lib.mdDoc "List of script names to invoke for health tracking.";
     };
 
     trackInterfaces = mkOption {
       type = types.listOf types.str;
       default = [];
       example = [ "eth0" "eth1" ];
-      description = "List of network interfaces to monitor for health tracking.";
+      description = lib.mdDoc "List of network interfaces to monitor for health tracking.";
     };
 
     extraConfig = mkOption {
       type = types.lines;
       default = "";
-      description = ''
+      description = lib.mdDoc ''
         Extra lines to be added verbatim to the vrrp_instance section.
       '';
     };

nixos/modules/services/networking/keepalived/vrrp-script-options.nix

···
     script = mkOption {
       type = str;
       example = literalExpression ''"''${pkgs.curl} -f http://localhost:80"'';
-      description = "(Path of) Script command to execute followed by args, i.e. cmd [args]...";
+      description = lib.mdDoc "(Path of) Script command to execute followed by args, i.e. cmd [args]...";
     };
 
     interval = mkOption {
       type = int;
       default = 1;
-      description = "Seconds between script invocations.";
+      description = lib.mdDoc "Seconds between script invocations.";
     };
 
     timeout = mkOption {
       type = int;
       default = 5;
-      description = "Seconds after which script is considered to have failed.";
+      description = lib.mdDoc "Seconds after which script is considered to have failed.";
     };
 
     weight = mkOption {
       type = int;
       default = 0;
-      description = "Following a failure, adjust the priority by this weight.";
+      description = lib.mdDoc "Following a failure, adjust the priority by this weight.";
     };
 
     rise = mkOption {
       type = int;
       default = 5;
-      description = "Required number of successes for OK transition.";
+      description = lib.mdDoc "Required number of successes for OK transition.";
     };
 
     fall = mkOption {
       type = int;
       default = 3;
-      description = "Required number of failures for KO transition.";
+      description = lib.mdDoc "Required number of failures for KO transition.";
     };
 
     user = mkOption {
       type = str;
       default = "keepalived_script";
-      description = "Name of user to run the script under.";
+      description = lib.mdDoc "Name of user to run the script under.";
     };
 
     group = mkOption {
       type = nullOr str;
       default = null;
-      description = "Name of group to run the script under. Defaults to user group.";
+      description = lib.mdDoc "Name of group to run the script under. Defaults to user group.";
     };
 
     extraConfig = mkOption {
       type = lines;
       default = "";
-      description = "Extra lines to be added verbatim to the vrrp_script section.";
+      description = lib.mdDoc "Extra lines to be added verbatim to the vrrp_script section.";
     };
 
   };

nixos/modules/services/networking/nbd.nix

···
           default = {
             allowlist = false;
           };
-          description = ''
+          description = lib.mdDoc ''
             Extra options for the server. See
-            <citerefentry><refentrytitle>nbd-server</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+            {manpage}`nbd-server(5)`.
           '';
         };
 
···
                     flush = true;
                     fua = true;
                   };
-                  description = ''
+                  description = lib.mdDoc ''
                     Extra options for this export. See
-                    <citerefentry><refentrytitle>nbd-server</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+                    {manpage}`nbd-server(5)`.
                   '';
                 };
               };

nixos/modules/services/networking/networkmanager.nix

···
           str
         ]));
         default = {};
-        description = ''
+        description = lib.mdDoc ''
           Configuration for the [connection] section of NetworkManager.conf.
           Refer to
-          <link xlink:href="https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html">
+          [
             https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html#id-1.2.3.11
-          </link>
+          ](https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html)
           or
-          <citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+          {manpage}`NetworkManager.conf(5)`
           for more information.
         '';
       };
···
       extraConfig = mkOption {
         type = types.lines;
         default = "";
-        description = ''
+        description = lib.mdDoc ''
           Configuration appended to the generated NetworkManager.conf.
           Refer to
-          <link xlink:href="https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html">
+          [
             https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html
-          </link>
+          ](https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html)
           or
-          <citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+          {manpage}`NetworkManager.conf(5)`
           for more information.
         '';
       };
···
       unmanaged = mkOption {
         type = types.listOf types.str;
         default = [];
-        description = ''
+        description = lib.mdDoc ''
           List of interfaces that will not be managed by NetworkManager.
           Interface name can be specified here, but if you need more fidelity,
           refer to
-          <link xlink:href="https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html#device-spec">
+          [
             https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html#device-spec
-          </link>
+          ](https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html#device-spec)
           or the "Device List Format" Appendix of
-          <citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+          {manpage}`NetworkManager.conf(5)`.
         '';
       };
 
···
       dns = mkOption {
         type = types.enum [ "default" "dnsmasq" "unbound" "systemd-resolved" "none" ];
         default = "default";
-        description = ''
-          Set the DNS (<literal>resolv.conf</literal>) processing mode.
+        description = lib.mdDoc ''
+          Set the DNS (`resolv.conf`) processing mode.
 
           A description of these modes can be found in the main section of
-          <link xlink:href="https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html">
+          [
             https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html
-          </link>
+          ](https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html)
           or in
-          <citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+          {manpage}`NetworkManager.conf(5)`.
         '';
       };
 

nixos/modules/services/networking/nghttpx/backend-submodule.nix

···
         host = "127.0.0.1";
         port = 80;
       };
-      description = ''
+      description = lib.mdDoc ''
         Backend server location specified as either a host:port pair
         or a unix domain docket.
       '';
···
         "/somepath"
       ];
       default     = [];
-      description = ''
+      description = lib.mdDoc ''
         List of nghttpx backend patterns.
 
         Please see https://nghttp2.org/documentation/nghttpx.1.html#cmdoption-nghttpx-b
···
         tls   = true;
       };
       default     = null;
-      description = ''
+      description = lib.mdDoc ''
         Parameters to configure a backend.
       '';
     };

nixos/modules/services/networking/nghttpx/frontend-submodule.nix

···
         host = "127.0.0.1";
         port = 80;
       };
-      description = ''
+      description = lib.mdDoc ''
         Frontend server interface binding specification as either a
         host:port pair or a unix domain docket.
 
···
         tls   = "tls";
       };
       default     = null;
-      description = ''
+      description = lib.mdDoc ''
         Parameters to configure a backend.
       '';
     };

nixos/modules/services/networking/nghttpx/nghttpx-options.nix

···
 
     frontends = lib.mkOption {
       type        = lib.types.listOf (lib.types.submodule (import ./frontend-submodule.nix));
-      description = ''
+      description = lib.mdDoc ''
         A list of frontend listener specifications.
       '';
       example = [
···
 
     backends  = lib.mkOption {
       type = lib.types.listOf (lib.types.submodule (import ./backend-submodule.nix));
-      description = ''
+      description = lib.mdDoc ''
         A list of backend specifications.
       '';
       example = [
···
     tls = lib.mkOption {
       type        = lib.types.nullOr (lib.types.submodule (import ./tls-submodule.nix));
       default     = null;
-      description = ''
+      description = lib.mdDoc ''
         TLS certificate and key paths. Note that this does not enable
         TLS for a frontend listener, to do so, a frontend
-        specification must set <literal>params.tls</literal> to true.
+        specification must set `params.tls` to true.
       '';
       example = {
         key = "/etc/ssl/keys/server.key";
···
     extraConfig = lib.mkOption {
       type        = lib.types.lines;
       default     = "";
-      description = ''
+      description = lib.mdDoc ''
         Extra configuration options to be appended to the generated
         configuration file.
       '';
···
     single-process = lib.mkOption {
       type        = lib.types.bool;
       default     = false;
-      description = ''
+      description = lib.mdDoc ''
         Run this program in a single process mode for debugging
         purpose. Without this option, nghttpx creates at least 2
         processes: master and worker processes. If this option is
···
     backlog = lib.mkOption {
       type        = lib.types.int;
       default     = 65536;
-      description = ''
+      description = lib.mdDoc ''
         Listen backlog size.
 
         Please see https://nghttp2.org/documentation/nghttpx.1.html#cmdoption-nghttpx--backlog
···
         "IPv6"
       ];
       default = "auto";
-      description = ''
+      description = lib.mdDoc ''
         Specify address family of backend connections. If "auto" is
         given, both IPv4 and IPv6 are considered. If "IPv4" is given,
         only IPv4 address is considered. If "IPv6" is given, only IPv6
···
     workers = lib.mkOption {
       type        = lib.types.int;
       default     = 1;
-      description = ''
+      description = lib.mdDoc ''
         Set the number of worker threads.
 
         Please see https://nghttp2.org/documentation/nghttpx.1.html#cmdoption-nghttpx-n
···
     single-thread = lib.mkOption {
       type        = lib.types.bool;
       default     = false;
-      description = ''
+      description = lib.mdDoc ''
         Run everything in one thread inside the worker process. This
         feature is provided for better debugging experience, or for
         the platforms which lack thread support. If threading is

nixos/modules/services/networking/soju.nix

···
     listen = mkOption {
       type = types.listOf types.str;
       default = [ ":6697" ];
-      description = ''
+      description = lib.mdDoc ''
         Where soju should listen for incoming connections. See the
-        <literal>listen</literal> directive in
-        <citerefentry><refentrytitle>soju</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+        `listen` directive in
+        {manpage}`soju(1)`.
       '';
     };
 
···
     httpOrigins = mkOption {
       type = types.listOf types.str;
       default = [];
-      description = ''
+      description = lib.mdDoc ''
         List of allowed HTTP origins for WebSocket listeners. The parameters are
         interpreted as shell patterns, see
-        <citerefentry><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+        {manpage}`glob(7)`.
       '';
     };
 

nixos/modules/services/networking/ssh/sshd.nix

···
       gatewayPorts = mkOption {
         type = types.str;
         default = "no";
-        description = ''
+        description = lib.mdDoc ''
           Specifies whether remote hosts are allowed to connect to
           ports forwarded for the client.  See
-          <citerefentry><refentrytitle>sshd_config</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+          {manpage}`sshd_config(5)`.
         '';
       };
 
···
           [ { type = "rsa"; bits = 4096; path = "/etc/ssh/ssh_host_rsa_key"; rounds = 100; openSSHFormat = true; }
             { type = "ed25519"; path = "/etc/ssh/ssh_host_ed25519_key"; rounds = 100; comment = "key comment"; }
           ];
-        description = ''
+        description = lib.mdDoc ''
           NixOS can automatically generate SSH host keys.  This option
           specifies the path, type and size of each key.  See
-          <citerefentry><refentrytitle>ssh-keygen</refentrytitle><manvolnum>1</manvolnum></citerefentry> for supported types
+          {manpage}`ssh-keygen(1)` for supported types
           and sizes.
         '';
       };

nixos/modules/services/networking/strongswan-swanctl/module.nix

···
       type = types.package;
       default = pkgs.strongswan;
       defaultText = literalExpression "pkgs.strongswan";
-      description = ''
+      description = lib.mdDoc ''
         The strongswan derivation to use.
       '';
     };
···
     strongswan.extraConfig = mkOption {
       type = types.str;
       default = "";
-      description = ''
-        Contents of the <literal>strongswan.conf</literal> file.
+      description = lib.mdDoc ''
+        Contents of the `strongswan.conf` file.
       '';
     };
 

nixos/modules/services/networking/stunnel.nix

···
 
 
       servers = mkOption {
-        description = ''
+        description = lib.mdDoc ''
           Define the server configuations.
 
-          See "SERVICE-LEVEL OPTIONS" in <citerefentry><refentrytitle>stunnel</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+          See "SERVICE-LEVEL OPTIONS" in {manpage}`stunnel(8)`.
         '';
         type = with types; attrsOf (attrsOf (nullOr (oneOf [bool int str])));
         example = {
···
       };
 
       clients = mkOption {
-        description = ''
+        description = lib.mdDoc ''
           Define the client configurations.
 
           By default, verifyChain and OCSPaia are enabled and a CAFile is provided from pkgs.cacert.
 
-          See "SERVICE-LEVEL OPTIONS" in <citerefentry><refentrytitle>stunnel</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+          See "SERVICE-LEVEL OPTIONS" in {manpage}`stunnel(8)`.
         '';
         type = with types; attrsOf (attrsOf (nullOr (oneOf [bool int str])));
 

nixos/modules/services/networking/unbound.nix

···
             remote-control.control-enable = true;
           };
         '';
-        description = ''
+        description = lib.mdDoc ''
           Declarative Unbound configuration
-          See the <citerefentry><refentrytitle>unbound.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> manpage for a list of
+          See the {manpage}`unbound.conf(5)` manpage for a list of
           available options.
         '';
       };

nixos/modules/services/networking/wpa_supplicant.nix

···
               example = ''
                 bssid_blacklist=02:11:22:33:44:55 02:22:aa:44:55:66
               '';
-              description = ''
+              description = lib.mdDoc ''
                 Extra configuration lines appended to the network block.
                 See
-                <citerefentry><refentrytitle>wpa_supplicant.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                {manpage}`wpa_supplicant.conf(5)`
                 for available options.
               '';
             };
···
         example = ''
           p2p_disabled=1
         '';
-        description = ''
+        description = lib.mdDoc ''
           Extra lines appended to the configuration file.
           See
-          <citerefentry><refentrytitle>wpa_supplicant.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+          {manpage}`wpa_supplicant.conf(5)`
           for available options.
         '';
       };

nixos/modules/services/networking/znc/default.nix

···
         default = "znc";
         example = "john";
         type = types.str;
-        description = ''
+        description = lib.mdDoc ''
           The name of an existing user account to use to own the ZNC server
           process. If not specified, a default user will be created.
         '';
···
         default = defaultUser;
         example = "users";
         type = types.str;
-        description = ''
+        description = lib.mdDoc ''
           Group to own the ZNC process.
         '';
       };
···
         default = "/var/lib/znc";
         example = "/home/john/.znc";
         type = types.path;
-        description = ''
+        description = lib.mdDoc ''
           The state directory for ZNC. The config and the modules will be linked
           to from this directory as well.
         '';
···
       openFirewall = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to open ports in the firewall for ZNC. Does work with
           ports for listeners specified in
-          <option>services.znc.config.Listener</option>.
+          {option}`services.znc.config.Listener`.
         '';
       };
 
···
       configFile = mkOption {
         type = types.path;
         example = literalExpression "~/.znc/configs/znc.conf";
-        description = ''
+        description = lib.mdDoc ''
           Configuration file for ZNC. It is recommended to use the
-          <option>config</option> option instead.
+          {option}`config` option instead.
 
           Setting this option will override any auto-generated config file
-          through the <option>confOptions</option> or <option>config</option>
+          through the {option}`confOptions` or {option}`config`
           options.
         '';
       };
···
         type = types.listOf types.package;
         default = [ ];
         example = literalExpression "[ pkgs.zncModules.fish pkgs.zncModules.push ]";
-        description = ''
+        description = lib.mdDoc ''
           A list of global znc module packages to add to znc.
         '';
       };
···
       mutable = mkOption {
         default = true; # TODO: Default to true when config is set, make sure to not delete the old config if present
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Indicates whether to allow the contents of the
-          <literal>dataDir</literal> directory to be changed by the user at
+          `dataDir` directory to be changed by the user at
           run-time.
 
           If enabled, modifications to the ZNC configuration after its initial
···
         default = [ ];
         example = [ "--debug" ];
         type = types.listOf types.str;
-        description = ''
+        description = lib.mdDoc ''
           Extra arguments to use for executing znc.
         '';
       };

nixos/modules/services/security/usbguard.nix

···
         example = ''
           allow with-interface equals { 08:*:* }
         '';
-        description = ''
+        description = lib.mdDoc ''
           The USBGuard daemon will load this as the policy rule set.
           As these rules are NixOS managed they are immutable and can't
           be changed by the IPC interface.
 
           If you do not set this option, the USBGuard daemon will load
-          it's policy rule set from <literal>${defaultRuleFile}</literal>.
+          it's policy rule set from `${defaultRuleFile}`.
           This file can be changed manually or via the IPC interface.
 
-          Running <literal>usbguard generate-policy</literal> as root will
+          Running `usbguard generate-policy` as root will
           generate a config for your currently plugged in devices.
 
-          For more details see <citerefentry><refentrytitle>usbguard-rules.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+          For more details see {manpage}`usbguard-rules.conf(5)`.
         '';
       };
 

nixos/modules/services/system/kerberos/default.nix

···
     options = {
       principal = mkOption {
         type = types.str;
-        description = "Which principal the rule applies to";
+        description = lib.mdDoc "Which principal the rule applies to";
       };
       access = mkOption {
         type = types.either
           (types.listOf (types.enum ["add" "cpw" "delete" "get" "list" "modify"]))
           (types.enum ["all"]);
         default = "all";
-        description = "The changes the principal is allowed to make.";
+        description = lib.mdDoc "The changes the principal is allowed to make.";
       };
       target = mkOption {
         type = types.str;
         default = "*";
-        description = "The principals that 'access' applies to.";
+        description = lib.mdDoc "The principals that 'access' applies to.";
       };
     };
   };
···
           { principal = "*/admin"; access = "all"; }
           { principal = "admin"; access = "all"; }
         ];
-        description = ''
+        description = lib.mdDoc ''
           The privileges granted to a user.
         '';
       };
···
 
       realms = mkOption {
         type = types.attrsOf (types.submodule realm);
-        description = ''
+        description = lib.mdDoc ''
           The realm(s) to serve keys for.
         '';
       };

nixos/modules/services/system/nscd.nix

···
       enable = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable the Name Service Cache Daemon.
           Disabling this is strongly discouraged, as this effectively disables NSS Lookups
           from all non-glibc NSS modules, including the ones provided by systemd.
···
       config = mkOption {
         type = types.lines;
         default = builtins.readFile ./nscd.conf;
-        description = "Configuration to use for Name Service Cache Daemon.";
+        description = lib.mdDoc "Configuration to use for Name Service Cache Daemon.";
       };
 
       package = mkOption {
···
             then pkgs.stdenv.cc.libc.bin
             else pkgs.glibc.bin;
         '';
-        description = "package containing the nscd binary to be used by the service";
+        description = lib.mdDoc "package containing the nscd binary to be used by the service";
       };
 
     };

nixos/modules/services/ttys/getty.nix

···
       loginOptions = mkOption {
         type = types.nullOr types.str;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Template for arguments to be passed to
-          <citerefentry><refentrytitle>login</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+          {manpage}`login(1)`.
 
-          See <citerefentry><refentrytitle>agetty</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details,
+          See {manpage}`agetty(1)` for details,
           including security considerations.  If unspecified, agetty
-          will not be invoked with a <option>--login-options</option>
+          will not be invoked with a {option}`--login-options`
           option.
         '';
         example = "-h darkstar -- \\u";

nixos/modules/services/web-apps/bookstack.nix

···
 
     user = mkOption {
       default = "bookstack";
-      description = "User bookstack runs as.";
+      description = lib.mdDoc "User bookstack runs as.";
       type = types.str;
     };
 
     group = mkOption {
       default = "bookstack";
-      description = "Group bookstack runs as.";
+      description = lib.mdDoc "Group bookstack runs as.";
       type = types.str;
     };
 
     appKeyFile = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         A file containing the Laravel APP_KEY - a 32 character long,
         base64 encoded key used for encryption where needed. Can be
-        generated with <literal>head -c 32 /dev/urandom | base64</literal>.
+        generated with `head -c 32 /dev/urandom | base64`.
       '';
       example = "/run/keys/bookstack-appkey";
       type = types.path;
···
                   config.networking.hostName;
       defaultText = lib.literalExpression "config.networking.fqdn";
       example = "bookstack.example.com";
-      description = ''
+      description = lib.mdDoc ''
         The hostname to serve BookStack on.
       '';
     };
 
     appURL = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         The root URL that you want to host BookStack on. All URLs in BookStack will be generated using this value.
-        If you change this in the future you may need to run a command to update stored URLs in the database. Command example: <literal>php artisan bookstack:update-url https://old.example.com https://new.example.com</literal>
+        If you change this in the future you may need to run a command to update stored URLs in the database. Command example: `php artisan bookstack:update-url https://old.example.com https://new.example.com`
       '';
       default = "http${lib.optionalString tlsEnabled "s"}://${cfg.hostname}";
       defaultText = ''http''${lib.optionalString tlsEnabled "s"}://''${cfg.hostname}'';
···
     };
 
     dataDir = mkOption {
-      description = "BookStack data directory";
+      description = lib.mdDoc "BookStack data directory";
       default = "/var/lib/bookstack";
       type = types.path;
     };
···
       host = mkOption {
         type = types.str;
         default = "localhost";
-        description = "Database host address.";
+        description = lib.mdDoc "Database host address.";
       };
       port = mkOption {
         type = types.port;
         default = 3306;
-        description = "Database host port.";
+        description = lib.mdDoc "Database host port.";
       };
       name = mkOption {
         type = types.str;
         default = "bookstack";
-        description = "Database name.";
+        description = lib.mdDoc "Database name.";
       };
       user = mkOption {
         type = types.str;
         default = user;
         defaultText = literalExpression "user";
-        description = "Database username.";
+        description = lib.mdDoc "Database username.";
       };
       passwordFile = mkOption {
         type = with types; nullOr path;
         default = null;
         example = "/run/keys/bookstack-dbpassword";
-        description = ''
+        description = lib.mdDoc ''
           A file containing the password corresponding to
-          <option>database.user</option>.
+          {option}`database.user`.
         '';
       };
       createLocally = mkOption {
         type = types.bool;
         default = false;
-        description = "Create the database and database user locally.";
+        description = lib.mdDoc "Create the database and database user locally.";
       };
     };
 
···
       driver = mkOption {
         type = types.enum [ "smtp" "sendmail" ];
         default = "smtp";
-        description = "Mail driver to use.";
+        description = lib.mdDoc "Mail driver to use.";
       };
       host = mkOption {
         type = types.str;
         default = "localhost";
-        description = "Mail host address.";
+        description = lib.mdDoc "Mail host address.";
       };
       port = mkOption {
         type = types.port;
         default = 1025;
-        description = "Mail host port.";
+        description = lib.mdDoc "Mail host port.";
       };
       fromName = mkOption {
         type = types.str;
         default = "BookStack";
-        description = "Mail \"from\" name.";
+        description = lib.mdDoc "Mail \"from\" name.";
       };
       from = mkOption {
         type = types.str;
         default = "[e-mail]";
-        description = "Mail \"from\" email.";
+        description = lib.mdDoc "Mail \"from\" email.";
       };
       user = mkOption {
         type = with types; nullOr str;
         default = null;
         example = "bookstack";
-        description = "Mail username.";
+        description = lib.mdDoc "Mail username.";
       };
       passwordFile = mkOption {
         type = with types; nullOr path;
         default = null;
         example = "/run/keys/bookstack-mailpassword";
-        description = ''
+        description = lib.mdDoc ''
           A file containing the password corresponding to
-          <option>mail.user</option>.
+          {option}`mail.user`.
         '';
       };
       encryption = mkOption {
         type = with types; nullOr (enum [ "tls" ]);
         default = null;
-        description = "SMTP encryption mechanism to use.";
+        description = lib.mdDoc "SMTP encryption mechanism to use.";
       };
     };
 
···
       type = types.str;
       default = "18M";
       example = "1G";
-      description = "The maximum size for uploads (e.g. images).";
+      description = lib.mdDoc "The maximum size for uploads (e.g. images).";
     };
 
     poolConfig = mkOption {
···
         "pm.max_spare_servers" = 4;
         "pm.max_requests" = 500;
       };
-      description = ''
-        Options for the bookstack PHP pool. See the documentation on <literal>php-fpm.conf</literal>
+      description = lib.mdDoc ''
+        Options for the bookstack PHP pool. See the documentation on `php-fpm.conf`
         for details on configuration directives.
       '';
     };
···
           enableACME = true;
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         With this option, you can customize the nginx virtualHost settings.
       '';
     };
···
           OIDC_ISSUER_DISCOVER = true;
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         BookStack configuration options to set in the
-        <filename>.env</filename> file.
+        {file}`.env` file.
 
-        Refer to <link xlink:href="https://www.bookstackapp.com/docs/"/>
+        Refer to <https://www.bookstackapp.com/docs/>
         for details on supported values.
 
         Settings containing secret data should be set to an attribute
-        set containing the attribute <literal>_secret</literal> - a
+        set containing the attribute `_secret` - a
         string pointing to a file containing the value the option
         should be set to. See the example to get a better picture of
-        this: in the resulting <filename>.env</filename> file, the
-        <literal>OIDC_CLIENT_SECRET</literal> key will be set to the
-        contents of the <filename>/run/keys/oidc_secret</filename>
+        this: in the resulting {file}`.env` file, the
+        `OIDC_CLIENT_SECRET` key will be set to the
+        contents of the {file}`/run/keys/oidc_secret`
         file.
       '';
     };

nixos/modules/services/web-apps/fluidd.nix

···
 
     package = mkOption {
       type = types.package;
-      description = "Fluidd package to be used in the module";
+      description = lib.mdDoc "Fluidd package to be used in the module";
       default = pkgs.fluidd;
       defaultText = literalExpression "pkgs.fluidd";
     };
···
     hostName = mkOption {
       type = types.str;
       default = "localhost";
-      description = "Hostname to serve fluidd on";
+      description = lib.mdDoc "Hostname to serve fluidd on";
     };
 
     nginx = mkOption {
···
           serverAliases = [ "fluidd.''${config.networking.domain}" ];
         }
       '';
-      description = "Extra configuration for the nginx virtual host of fluidd.";
+      description = lib.mdDoc "Extra configuration for the nginx virtual host of fluidd.";
     };
   };
 

nixos/modules/services/web-apps/jirafeau.nix

···
     adminPasswordSha256 = mkOption {
       type = types.str;
       default = "";
-      description = ''
+      description = lib.mdDoc ''
         SHA-256 of the desired administration password. Leave blank/unset for no password.
       '';
     };
···
     dataDir = mkOption {
       type = types.path;
       default = "/var/lib/jirafeau/data/";
-      description = "Location of Jirafeau storage directory.";
+      description = lib.mdDoc "Location of Jirafeau storage directory.";
     };
 
     enable = mkEnableOption "Jirafeau file upload application.";
···
     hostName = mkOption {
       type = types.str;
       default = "localhost";
-      description = "URL of instance. Must have trailing slash.";
+      description = lib.mdDoc "URL of instance. Must have trailing slash.";
     };
 
     maxUploadSizeMegabytes = mkOption {
       type = types.int;
       default = 0;
-      description = "Maximum upload size of accepted files.";
+      description = lib.mdDoc "Maximum upload size of accepted files.";
     };
 
     maxUploadTimeout = mkOption {
···
           serverAliases = [ "wiki.''${config.networking.domain}" ];
         }
       '';
-      description = "Extra configuration for the nginx virtual host of Jirafeau.";
+      description = lib.mdDoc "Extra configuration for the nginx virtual host of Jirafeau.";
     };
 
     package = mkOption {
       type = types.package;
       default = pkgs.jirafeau;
       defaultText = literalExpression "pkgs.jirafeau";
-      description = "Jirafeau package to use";
+      description = lib.mdDoc "Jirafeau package to use";
     };
 
     poolConfig = mkOption {
···
         "pm.max_spare_servers" = 4;
         "pm.max_requests" = 500;
       };
-      description = ''
-        Options for Jirafeau PHP pool. See documentation on <literal>php-fpm.conf</literal> for
+      description = lib.mdDoc ''
+        Options for Jirafeau PHP pool. See documentation on `php-fpm.conf` for
         details on configuration directives.
       '';
     };

nixos/modules/services/web-apps/limesurvey.nix

···
         type = types.enum [ "mysql" "pgsql" "odbc" "mssql" ];
         example = "pgsql";
         default = "mysql";
-        description = "Database engine to use.";
+        description = lib.mdDoc "Database engine to use.";
       };
 
       host = mkOption {
         type = types.str;
         default = "localhost";
-        description = "Database host address.";
+        description = lib.mdDoc "Database host address.";
       };
 
       port = mkOption {
         type = types.int;
         default = if cfg.database.type == "pgsql" then 5442 else 3306;
         defaultText = literalExpression "3306";
-        description = "Database host port.";
+        description = lib.mdDoc "Database host port.";
       };
 
       name = mkOption {
         type = types.str;
         default = "limesurvey";
-        description = "Database name.";
+        description = lib.mdDoc "Database name.";
       };
 
       user = mkOption {
         type = types.str;
         default = "limesurvey";
-        description = "Database user.";
+        description = lib.mdDoc "Database user.";
       };
 
       passwordFile = mkOption {
         type = types.nullOr types.path;
         default = null;
         example = "/run/keys/limesurvey-dbpassword";
-        description = ''
+        description = lib.mdDoc ''
           A file containing the password corresponding to
-          <option>database.user</option>.
+          {option}`database.user`.
         '';
       };
 
···
           else null
         ;
         defaultText = literalExpression "/run/mysqld/mysqld.sock";
-        description = "Path to the unix socket file to use for authentication.";
+        description = lib.mdDoc "Path to the unix socket file to use for authentication.";
       };
 
       createLocally = mkOption {
         type = types.bool;
         default = cfg.database.type == "mysql";
         defaultText = literalExpression "true";
-        description = ''
+        description = lib.mdDoc ''
           Create the database and database user locally.
           This currently only applies if database type "mysql" is selected.
         '';
···
           enableACME = true;
         }
       '';
-      description = ''
-        Apache configuration can be done by adapting <literal>services.httpd.virtualHosts.&lt;name&gt;</literal>.
-        See <xref linkend="opt-services.httpd.virtualHosts"/> for further information.
+      description = lib.mdDoc ''
+        Apache configuration can be done by adapting `services.httpd.virtualHosts.<name>`.
+        See [](#opt-services.httpd.virtualHosts) for further information.
       '';
     };
 
···
         "pm.max_spare_servers" = 4;
         "pm.max_requests" = 500;
       };
-      description = ''
-        Options for the LimeSurvey PHP pool. See the documentation on <literal>php-fpm.conf</literal>
+      description = lib.mdDoc ''
+        Options for the LimeSurvey PHP pool. See the documentation on `php-fpm.conf`
         for details on configuration directives.
       '';
     };
···
     config = mkOption {
       type = configType;
       default = {};
-      description = ''
+      description = lib.mdDoc ''
         LimeSurvey configuration. Refer to
-        <link xlink:href="https://manual.limesurvey.org/Optional_settings"/>
+        <https://manual.limesurvey.org/Optional_settings>
         for details on supported values.
       '';
     };

nixos/modules/services/web-apps/matomo.nix

···
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Enable Matomo web analytics with php-fpm backend.
           Either the nginx option or the webServerUser option is mandatory.
         '';
···
 
       package = mkOption {
         type = types.package;
-        description = ''
+        description = lib.mdDoc ''
           Matomo package for the service to use.
           This can be used to point to newer releases from nixos-unstable,
           as they don't get backported if they are not security-relevant.
···
       periodicArchiveProcessing = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Enable periodic archive processing, which generates aggregated reports from the visits.
 
           This means that you can safely disable browser triggers for Matomo archiving,
           and safely enable to delete old visitor logs.
           Before deleting visitor logs,
-          make sure though that you run <literal>systemctl start matomo-archive-processing.service</literal>
+          make sure though that you run `systemctl start matomo-archive-processing.service`
           at least once without errors if you have already collected data before.
         '';
       };
···
           else "${user}.''${config.${options.networking.hostName}}"
         '';
         example = "matomo.yourdomain.org";
-        description = ''
+        description = lib.mdDoc ''
           URL of the host, without https prefix. You may want to change it if you
           run Matomo on a different URL than matomo.yourdomain.
         '';
···
             enableACME = false;
           }
         '';
-        description = ''
+        description = lib.mdDoc ''
             With this option, you can customize an nginx virtualHost which already has sensible defaults for Matomo.
             Either this option or the webServerUser option is mandatory.
             Set this to {} to just enable the virtualHost if you don't need any customization.
-            If enabled, then by default, the <option>serverName</option> is
-            <literal>''${user}.''${config.networking.hostName}.''${config.networking.domain}</literal>,
+            If enabled, then by default, the {option}`serverName` is
+            `''${user}.''${config.networking.hostName}.''${config.networking.domain}`,
             SSL is active, and certificates are acquired via ACME.
             If this is set to null (the default), no nginx virtualHost will be configured.
         '';

nixos/modules/services/web-apps/mediawiki.nix

···
         type = types.package;
         default = pkgs.mediawiki;
         defaultText = literalExpression "pkgs.mediawiki";
-        description = "Which MediaWiki package to use.";
+        description = lib.mdDoc "Which MediaWiki package to use.";
       };
 
       name = mkOption {
         type = types.str;
         default = "MediaWiki";
         example = "Foobar Wiki";
-        description = "Name of the wiki.";
+        description = lib.mdDoc "Name of the wiki.";
       };
 
       uploadsDir = mkOption {
         type = types.nullOr types.path;
         default = "${stateDir}/uploads";
-        description = ''
+        description = lib.mdDoc ''
           This directory is used for uploads of pictures. The directory passed here is automatically
           created and permissions adjusted as required.
         '';
···
 
       passwordFile = mkOption {
         type = types.path;
-        description = "A file containing the initial password for the admin user.";
+        description = lib.mdDoc "A file containing the initial password for the admin user.";
         example = "/run/keys/mediawiki-password";
       };
 
       skins = mkOption {
         default = {};
         type = types.attrsOf types.path;
-        description = ''
-          Attribute set of paths whose content is copied to the <filename>skins</filename>
+        description = lib.mdDoc ''
+          Attribute set of paths whose content is copied to the {file}`skins`
           subdirectory of the MediaWiki installation in addition to the default skins.
         '';
       };
···
       extensions = mkOption {
         default = {};
         type = types.attrsOf (types.nullOr types.path);
-        description = ''
-          Attribute set of paths whose content is copied to the <filename>extensions</filename>
+        description = lib.mdDoc ''
+          Attribute set of paths whose content is copied to the {file}`extensions`
           subdirectory of the MediaWiki installation and enabled in configuration.
 
-          Use <literal>null</literal> instead of path to enable extensions that are part of MediaWiki.
+          Use `null` instead of path to enable extensions that are part of MediaWiki.
         '';
         example = literalExpression ''
           {
···
         type = mkOption {
           type = types.enum [ "mysql" "postgres" "sqlite" "mssql" "oracle" ];
           default = "mysql";
-          description = "Database engine to use. MySQL/MariaDB is the database of choice by MediaWiki developers.";
+          description = lib.mdDoc "Database engine to use. MySQL/MariaDB is the database of choice by MediaWiki developers.";
         };
 
         host = mkOption {
           type = types.str;
           default = "localhost";
-          description = "Database host address.";
+          description = lib.mdDoc "Database host address.";
         };
 
         port = mkOption {
           type = types.port;
           default = 3306;
-          description = "Database host port.";
+          description = lib.mdDoc "Database host port.";
         };
 
         name = mkOption {
           type = types.str;
           default = "mediawiki";
-          description = "Database name.";
+          description = lib.mdDoc "Database name.";
         };
 
         user = mkOption {
           type = types.str;
           default = "mediawiki";
-          description = "Database user.";
+          description = lib.mdDoc "Database user.";
         };
 
         passwordFile = mkOption {
           type = types.nullOr types.path;
           default = null;
           example = "/run/keys/mediawiki-dbpassword";
-          description = ''
+          description = lib.mdDoc ''
             A file containing the password corresponding to
-            <option>database.user</option>.
+            {option}`database.user`.
           '';
         };
 
         tablePrefix = mkOption {
           type = types.nullOr types.str;
           default = null;
-          description = ''
+          description = lib.mdDoc ''
             If you only have access to a single database and wish to install more than
             one version of MediaWiki, or have other applications that also use the
             database, you can give the table names a unique prefix to stop any naming
             conflicts or confusion.
-            See <link xlink:href="https://www.mediawiki.org/wiki/Manual:$wgDBprefix"/>.
+            See <https://www.mediawiki.org/wiki/Manual:$wgDBprefix>.
           '';
         };
 
···
           type = types.nullOr types.path;
           default = if cfg.database.createLocally then "/run/mysqld/mysqld.sock" else null;
           defaultText = literalExpression "/run/mysqld/mysqld.sock";
-          description = "Path to the unix socket file to use for authentication.";
+          description = lib.mdDoc "Path to the unix socket file to use for authentication.";
         };
 
         createLocally = mkOption {
           type = types.bool;
           default = cfg.database.type == "mysql";
           defaultText = literalExpression "true";
-          description = ''
+          description = lib.mdDoc ''
             Create the database and database user locally.
             This currently only applies if database type "mysql" is selected.
           '';
···
             enableACME = true;
           }
         '';
-        description = ''
-          Apache configuration can be done by adapting <option>services.httpd.virtualHosts</option>.
-          See <xref linkend="opt-services.httpd.virtualHosts"/> for further information.
+        description = lib.mdDoc ''
+          Apache configuration can be done by adapting {option}`services.httpd.virtualHosts`.
+          See [](#opt-services.httpd.virtualHosts) for further information.
         '';
       };
 
···
           "pm.max_spare_servers" = 4;
           "pm.max_requests" = 500;
         };
-        description = ''
-          Options for the MediaWiki PHP pool. See the documentation on <literal>php-fpm.conf</literal>
+        description = lib.mdDoc ''
+          Options for the MediaWiki PHP pool. See the documentation on `php-fpm.conf`
           for details on configuration directives.
         '';
       };
 
       extraConfig = mkOption {
         type = types.lines;
-        description = ''
+        description = lib.mdDoc ''
           Any additional text to be appended to MediaWiki's
           LocalSettings.php configuration file. For configuration
-          settings, see <link xlink:href="https://www.mediawiki.org/wiki/Manual:Configuration_settings"/>.
+          settings, see <https://www.mediawiki.org/wiki/Manual:Configuration_settings>.
         '';
         default = "";
         example = ''

nixos/modules/services/web-apps/moodle.nix

···
       type = types.package;
       default = pkgs.moodle;
       defaultText = literalExpression "pkgs.moodle";
-      description = "The Moodle package to use.";
+      description = lib.mdDoc "The Moodle package to use.";
     };
 
     initialPassword = mkOption {
       type = types.str;
       example = "correcthorsebatterystaple";
-      description = ''
+      description = lib.mdDoc ''
         Specifies the initial password for the admin, i.e. the password assigned if the user does not already exist.
         The password specified here is world-readable in the Nix store, so it should be changed promptly.
       '';
···
       type = mkOption {
         type = types.enum [ "mysql" "pgsql" ];
         default = "mysql";
-        description = "Database engine to use.";
+        description = lib.mdDoc "Database engine to use.";
       };
 
       host = mkOption {
         type = types.str;
         default = "localhost";
-        description = "Database host address.";
+        description = lib.mdDoc "Database host address.";
       };
 
       port = mkOption {
         type = types.int;
-        description = "Database host port.";
+        description = lib.mdDoc "Database host port.";
         default = {
           mysql = 3306;
           pgsql = 5432;
···
       name = mkOption {
         type = types.str;
         default = "moodle";
-        description = "Database name.";
+        description = lib.mdDoc "Database name.";
       };
 
       user = mkOption {
         type = types.str;
         default = "moodle";
-        description = "Database user.";
+        description = lib.mdDoc "Database user.";
       };
 
       passwordFile = mkOption {
         type = types.nullOr types.path;
         default = null;
         example = "/run/keys/moodle-dbpassword";
-        description = ''
+        description = lib.mdDoc ''
           A file containing the password corresponding to
-          <option>database.user</option>.
+          {option}`database.user`.
         '';
       };
 
···
           else if pgsqlLocal then "/run/postgresql"
           else null;
         defaultText = literalExpression "/run/mysqld/mysqld.sock";
-        description = "Path to the unix socket file to use for authentication.";
+        description = lib.mdDoc "Path to the unix socket file to use for authentication.";
       };
 
       createLocally = mkOption {
···
           enableACME = true;
         }
       '';
-      description = ''
-        Apache configuration can be done by adapting <option>services.httpd.virtualHosts</option>.
-        See <xref linkend="opt-services.httpd.virtualHosts"/> for further information.
+      description = lib.mdDoc ''
+        Apache configuration can be done by adapting {option}`services.httpd.virtualHosts`.
+        See [](#opt-services.httpd.virtualHosts) for further information.
       '';
     };
 
···
         "pm.max_spare_servers" = 4;
         "pm.max_requests" = 500;
       };
-      description = ''
-        Options for the Moodle PHP pool. See the documentation on <literal>php-fpm.conf</literal>
+      description = lib.mdDoc ''
+        Options for the Moodle PHP pool. See the documentation on `php-fpm.conf`
         for details on configuration directives.
       '';
     };
···
     extraConfig = mkOption {
       type = types.lines;
       default = "";
-      description = ''
+      description = lib.mdDoc ''
         Any additional text to be appended to the config.php
         configuration file. This is a PHP script. For configuration
-        details, see <link xlink:href="https://docs.moodle.org/37/en/Configuration_file"/>.
+        details, see <https://docs.moodle.org/37/en/Configuration_file>.
       '';
       example = ''
         $CFG->disableupdatenotifications = true;

nixos/modules/services/web-apps/snipe-it.nix

···
 
     user = mkOption {
       default = "snipeit";
-      description = "User snipe-it runs as.";
+      description = lib.mdDoc "User snipe-it runs as.";
       type = types.str;
     };
 
     group = mkOption {
       default = "snipeit";
-      description = "Group snipe-it runs as.";
+      description = lib.mdDoc "Group snipe-it runs as.";
       type = types.str;
     };
 
     appKeyFile = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         A file containing the Laravel APP_KEY - a 32 character long,
         base64 encoded key used for encryption where needed. Can be
-        generated with <literal>head -c 32 /dev/urandom | base64</literal>.
+        generated with `head -c 32 /dev/urandom | base64`.
       '';
       example = "/run/keys/snipe-it/appkey";
       type = types.path;
···
                   config.networking.hostName;
       defaultText = lib.literalExpression "config.networking.fqdn";
       example = "snipe-it.example.com";
-      description = ''
+      description = lib.mdDoc ''
         The hostname to serve Snipe-IT on.
       '';
     };
 
     appURL = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         The root URL that you want to host Snipe-IT on. All URLs in Snipe-IT will be generated using this value.
         If you change this in the future you may need to run a command to update stored URLs in the database.
-        Command example: <literal>snipe-it snipe-it:update-url https://old.example.com https://new.example.com</literal>
+        Command example: `snipe-it snipe-it:update-url https://old.example.com https://new.example.com`
       '';
       default = "http${lib.optionalString tlsEnabled "s"}://${cfg.hostName}";
       defaultText = ''
···
     };
 
     dataDir = mkOption {
-      description = "snipe-it data directory";
+      description = lib.mdDoc "snipe-it data directory";
       default = "/var/lib/snipe-it";
       type = types.path;
     };
···
       host = mkOption {
         type = types.str;
         default = "localhost";
-        description = "Database host address.";
+        description = lib.mdDoc "Database host address.";
       };
       port = mkOption {
         type = types.port;
         default = 3306;
-        description = "Database host port.";
+        description = lib.mdDoc "Database host port.";
       };
       name = mkOption {
         type = types.str;
         default = "snipeit";
-        description = "Database name.";
+        description = lib.mdDoc "Database name.";
       };
       user = mkOption {
         type = types.str;
         default = user;
         defaultText = literalExpression "user";
-        description = "Database username.";
+        description = lib.mdDoc "Database username.";
       };
       passwordFile = mkOption {
         type = with types; nullOr path;
         default = null;
         example = "/run/keys/snipe-it/dbpassword";
-        description = ''
+        description = lib.mdDoc ''
           A file containing the password corresponding to
-          <option>database.user</option>.
+          {option}`database.user`.
         '';
       };
       createLocally = mkOption {
         type = types.bool;
         default = false;
-        description = "Create the database and database user locally.";
+        description = lib.mdDoc "Create the database and database user locally.";
       };
     };
 
···
       driver = mkOption {
         type = types.enum [ "smtp" "sendmail" ];
         default = "smtp";
-        description = "Mail driver to use.";
+        description = lib.mdDoc "Mail driver to use.";
       };
       host = mkOption {
         type = types.str;
         default = "localhost";
-        description = "Mail host address.";
+        description = lib.mdDoc "Mail host address.";
       };
       port = mkOption {
         type = types.port;
         default = 1025;
-        description = "Mail host port.";
+        description = lib.mdDoc "Mail host port.";
       };
       encryption = mkOption {
         type = with types; nullOr (enum [ "tls" "ssl" ]);
         default = null;
-        description = "SMTP encryption mechanism to use.";
+        description = lib.mdDoc "SMTP encryption mechanism to use.";
       };
       user = mkOption {
         type = with types; nullOr str;
         default = null;
         example = "snipeit";
-        description = "Mail username.";
+        description = lib.mdDoc "Mail username.";
       };
       passwordFile = mkOption {
         type = with types; nullOr path;
         default = null;
         example = "/run/keys/snipe-it/mailpassword";
-        description = ''
+        description = lib.mdDoc ''
           A file containing the password corresponding to
-          <option>mail.user</option>.
+          {option}`mail.user`.
         '';
       };
       backupNotificationAddress = mkOption {
         type = types.str;
         default = "[e-mail]";
-        description = "Email Address to send Backup Notifications to.";
+        description = lib.mdDoc "Email Address to send Backup Notifications to.";
       };
       from = {
         name = mkOption {
           type = types.str;
           default = "Snipe-IT Asset Management";
-          description = "Mail \"from\" name.";
+          description = lib.mdDoc "Mail \"from\" name.";
         };
         address = mkOption {
           type = types.str;
           default = "[e-mail]";
-          description = "Mail \"from\" address.";
+          description = lib.mdDoc "Mail \"from\" address.";
         };
       };
       replyTo = {
         name = mkOption {
           type = types.str;
           default = "Snipe-IT Asset Management";
-          description = "Mail \"reply-to\" name.";
+          description = lib.mdDoc "Mail \"reply-to\" name.";
         };
         address = mkOption {
           type = types.str;
           default = "[e-mail]";
-          description = "Mail \"reply-to\" address.";
+          description = lib.mdDoc "Mail \"reply-to\" address.";
         };
       };
     };
···
       type = types.str;
       default = "18M";
       example = "1G";
-      description = "The maximum size for uploads (e.g. images).";
+      description = lib.mdDoc "The maximum size for uploads (e.g. images).";
     };
 
     poolConfig = mkOption {
···
         "pm.max_spare_servers" = 4;
         "pm.max_requests" = 500;
       };
-      description = ''
-        Options for the snipe-it PHP pool. See the documentation on <literal>php-fpm.conf</literal>
+      description = lib.mdDoc ''
+        Options for the snipe-it PHP pool. See the documentation on `php-fpm.conf`
         for details on configuration directives.
       '';
     };
···
           enableACME = true;
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         With this option, you can customize the nginx virtualHost settings.
       '';
     };
···
           OIDC_ISSUER_DISCOVER = true;
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         Snipe-IT configuration options to set in the
-        <filename>.env</filename> file.
-        Refer to <link xlink:href="https://snipe-it.readme.io/docs/configuration"/>
+        {file}`.env` file.
+        Refer to <https://snipe-it.readme.io/docs/configuration>
         for details on supported values.
 
         Settings containing secret data should be set to an attribute
-        set containing the attribute <literal>_secret</literal> - a
+        set containing the attribute `_secret` - a
         string pointing to a file containing the value the option
         should be set to. See the example to get a better picture of
-        this: in the resulting <filename>.env</filename> file, the
-        <literal>OIDC_CLIENT_SECRET</literal> key will be set to the
-        contents of the <filename>/run/keys/oidc_secret</filename>
+        this: in the resulting {file}`.env` file, the
+        `OIDC_CLIENT_SECRET` key will be set to the
+        contents of the {file}`/run/keys/oidc_secret`
         file.
       '';
     };

nixos/modules/services/web-apps/wordpress.nix

···
           type = types.package;
           default = pkgs.wordpress;
           defaultText = literalExpression "pkgs.wordpress";
-          description = "Which WordPress package to use.";
+          description = lib.mdDoc "Which WordPress package to use.";
         };
 
         uploadsDir = mkOption {
           type = types.path;
           default = "/var/lib/wordpress/${name}/uploads";
-          description = ''
+          description = lib.mdDoc ''
             This directory is used for uploads of pictures. The directory passed here is automatically
             created and permissions adjusted as required.
           '';
···
           host = mkOption {
             type = types.str;
             default = "localhost";
-            description = "Database host address.";
+            description = lib.mdDoc "Database host address.";
           };
 
           port = mkOption {
             type = types.port;
             default = 3306;
-            description = "Database host port.";
+            description = lib.mdDoc "Database host port.";
           };
 
           name = mkOption {
             type = types.str;
             default = "wordpress";
-            description = "Database name.";
+            description = lib.mdDoc "Database name.";
           };
 
           user = mkOption {
             type = types.str;
             default = "wordpress";
-            description = "Database user.";
+            description = lib.mdDoc "Database user.";
           };
 
           passwordFile = mkOption {
             type = types.nullOr types.path;
             default = null;
             example = "/run/keys/wordpress-dbpassword";
-            description = ''
+            description = lib.mdDoc ''
               A file containing the password corresponding to
-              <option>database.user</option>.
+              {option}`database.user`.
             '';
           };
 
           tablePrefix = mkOption {
             type = types.str;
             default = "wp_";
-            description = ''
+            description = lib.mdDoc ''
               The $table_prefix is the value placed in the front of your database tables.
               Change the value if you want to use something other than wp_ for your database
               prefix. Typically this is changed if you are installing multiple WordPress blogs
               in the same database.
 
-              See <link xlink:href="https://codex.wordpress.org/Editing_wp-config.php#table_prefix"/>.
+              See <https://codex.wordpress.org/Editing_wp-config.php#table_prefix>.
             '';
           };
 
···
             type = types.nullOr types.path;
             default = null;
             defaultText = literalExpression "/run/mysqld/mysqld.sock";
-            description = "Path to the unix socket file to use for authentication.";
+            description = lib.mdDoc "Path to the unix socket file to use for authentication.";
           };
 
           createLocally = mkOption {
             type = types.bool;
             default = true;
-            description = "Create the database and database user locally.";
+            description = lib.mdDoc "Create the database and database user locally.";
           };
         };
 
···
               enableACME = true;
             }
           '';
-          description = ''
-            Apache configuration can be done by adapting <option>services.httpd.virtualHosts</option>.
+          description = lib.mdDoc ''
+            Apache configuration can be done by adapting {option}`services.httpd.virtualHosts`.
           '';
         };
 
···
             "pm.max_spare_servers" = 4;
             "pm.max_requests" = 500;
           };
-          description = ''
-            Options for the WordPress PHP pool. See the documentation on <literal>php-fpm.conf</literal>
+          description = lib.mdDoc ''
+            Options for the WordPress PHP pool. See the documentation on `php-fpm.conf`
             for details on configuration directives.
           '';
         };
···
         extraConfig = mkOption {
           type = types.lines;
           default = "";
-          description = ''
+          description = lib.mdDoc ''
             Any additional text to be appended to the wp-config.php
             configuration file. This is a PHP script. For configuration
-            settings, see <link xlink:href="https://codex.wordpress.org/Editing_wp-config.php"/>.
+            settings, see <https://codex.wordpress.org/Editing_wp-config.php>.
           '';
           example = ''
             define( 'AUTOSAVE_INTERVAL', 60 ); // Seconds
···
       sites = mkOption {
         type = types.attrsOf (types.submodule siteOpts);
         default = {};
-        description = "Specification of one or more WordPress sites to serve";
+        description = lib.mdDoc "Specification of one or more WordPress sites to serve";
       };
 
       webserver = mkOption {
         type = types.enum [ "httpd" "nginx" "caddy" ];
         default = "httpd";
-        description = ''
+        description = lib.mdDoc ''
           Whether to use apache2 or nginx for virtual host management.
 
-          Further nginx configuration can be done by adapting <literal>services.nginx.virtualHosts.&lt;name&gt;</literal>.
-          See <xref linkend="opt-services.nginx.virtualHosts"/> for further information.
+          Further nginx configuration can be done by adapting `services.nginx.virtualHosts.<name>`.
+          See [](#opt-services.nginx.virtualHosts) for further information.
 
-          Further apache2 configuration can be done by adapting <literal>services.httpd.virtualHosts.&lt;name&gt;</literal>.
-          See <xref linkend="opt-services.httpd.virtualHosts"/> for further information.
+          Further apache2 configuration can be done by adapting `services.httpd.virtualHosts.<name>`.
+          See [](#opt-services.httpd.virtualHosts) for further information.
         '';
       };
 

nixos/modules/services/web-apps/zabbix.nix

···
         type = types.package;
         default = pkgs.zabbix.web;
         defaultText = literalExpression "zabbix.web";
-        description = "Which Zabbix package to use.";
+        description = lib.mdDoc "Which Zabbix package to use.";
       };
 
       server = {
         port = mkOption {
           type = types.int;
-          description = "The port of the Zabbix server to connect to.";
+          description = lib.mdDoc "The port of the Zabbix server to connect to.";
           default = 10051;
         };
 
         address = mkOption {
           type = types.str;
-          description = "The IP address or hostname of the Zabbix server to connect to.";
+          description = lib.mdDoc "The IP address or hostname of the Zabbix server to connect to.";
           default = "localhost";
         };
       };
···
           type = types.enum [ "mysql" "pgsql" "oracle" ];
           example = "mysql";
           default = "pgsql";
-          description = "Database engine to use.";
+          description = lib.mdDoc "Database engine to use.";
         };
 
         host = mkOption {
           type = types.str;
           default = "";
-          description = "Database host address.";
+          description = lib.mdDoc "Database host address.";
         };
 
         port = mkOption {
···
             else if config.${opt.database.type} == "pgsql" then config.${options.services.postgresql.port}
             else 1521
           '';
-          description = "Database host port.";
+          description = lib.mdDoc "Database host port.";
         };
 
         name = mkOption {
           type = types.str;
           default = "zabbix";
-          description = "Database name.";
+          description = lib.mdDoc "Database name.";
         };
 
         user = mkOption {
           type = types.str;
           default = "zabbix";
-          description = "Database user.";
+          description = lib.mdDoc "Database user.";
         };
 
         passwordFile = mkOption {
           type = types.nullOr types.path;
           default = null;
           example = "/run/keys/zabbix-dbpassword";
-          description = ''
+          description = lib.mdDoc ''
             A file containing the password corresponding to
-            <option>database.user</option>.
+            {option}`database.user`.
           '';
         };
 
···
           type = types.nullOr types.path;
           default = null;
           example = "/run/postgresql";
-          description = "Path to the unix socket file to use for authentication.";
+          description = lib.mdDoc "Path to the unix socket file to use for authentication.";
         };
       };
 
···
             enableACME = true;
           }
         '';
-        description = ''
-          Apache configuration can be done by adapting <literal>services.httpd.virtualHosts.&lt;name&gt;</literal>.
-          See <xref linkend="opt-services.httpd.virtualHosts"/> for further information.
+        description = lib.mdDoc ''
+          Apache configuration can be done by adapting `services.httpd.virtualHosts.<name>`.
+          See [](#opt-services.httpd.virtualHosts) for further information.
         '';
       };
 
···
           "pm.max_spare_servers" = 4;
           "pm.max_requests" = 500;
         };
-        description = ''
-          Options for the Zabbix PHP pool. See the documentation on <literal>php-fpm.conf</literal> for details on configuration directives.
+        description = lib.mdDoc ''
+          Options for the Zabbix PHP pool. See the documentation on `php-fpm.conf` for details on configuration directives.
         '';
       };
 
       extraConfig = mkOption {
         type = types.lines;
         default = "";
-        description = ''
-          Additional configuration to be copied verbatim into <filename>zabbix.conf.php</filename>.
+        description = lib.mdDoc ''
+          Additional configuration to be copied verbatim into {file}`zabbix.conf.php`.
         '';
       };
 

nixos/modules/services/web-servers/apache-httpd/default.nix

···
         type = types.package;
         default = pkgs.apacheHttpd;
         defaultText = literalExpression "pkgs.apacheHttpd";
-        description = ''
+        description = lib.mdDoc ''
           Overridable attribute of the Apache HTTP Server package to use.
         '';
       };
···
         default = confFile;
         defaultText = literalExpression "confFile";
         example = literalExpression ''pkgs.writeText "httpd.conf" "# my custom config file ..."'';
-        description = ''
+        description = lib.mdDoc ''
           Override the configuration file used by Apache. By default,
           NixOS generates one automatically.
         '';
···
       extraConfig = mkOption {
         type = types.lines;
         default = "";
-        description = ''
+        description = lib.mdDoc ''
           Configuration lines appended to the generated Apache
           configuration file. Note that this mechanism will not work
-          when <option>configFile</option> is overridden.
+          when {option}`configFile` is overridden.
         '';
       };
 
···
       adminAddr = mkOption {
         type = types.str;
         example = "[e-mail]";
-        description = "E-mail address of the server administrator.";
+        description = lib.mdDoc "E-mail address of the server administrator.";
       };
 
       logFormat = mkOption {
         type = types.str;
         default = "common";
         example = "combined";
-        description = ''
+        description = lib.mdDoc ''
           Log format for log files. Possible values are: combined, common, referer, agent, none.
-          See <link xlink:href="https://httpd.apache.org/docs/2.4/logs.html"/> for more details.
+          See <https://httpd.apache.org/docs/2.4/logs.html> for more details.
         '';
       };
 
       logPerVirtualHost = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           If enabled, each virtual host gets its own
-          <filename>access.log</filename> and
-          <filename>error.log</filename>, namely suffixed by the
-          <option>hostName</option> of the virtual host.
+          {file}`access.log` and
+          {file}`error.log`, namely suffixed by the
+          {option}`hostName` of the virtual host.
         '';
       };
 
···
       group = mkOption {
         type = types.str;
         default = "wwwrun";
-        description = ''
+        description = lib.mdDoc ''
           Group under which httpd children processes run.
         '';
       };
···
       logDir = mkOption {
         type = types.path;
         default = "/var/log/httpd";
-        description = ''
+        description = lib.mdDoc ''
           Directory for Apache's log files. It is created automatically.
         '';
       };
···
             };
           }
         '';
-        description = ''
+        description = lib.mdDoc ''
           Specification of the virtual hosts served by Apache. Each
           element should be an attribute set specifying the
           configuration of the virtual host.
···
       enableMellon = mkOption {
         type = types.bool;
         default = false;
-        description = "Whether to enable the mod_auth_mellon module.";
+        description = lib.mdDoc "Whether to enable the mod_auth_mellon module.";
       };
 
       enablePHP = mkOption {
         type = types.bool;
         default = false;
-        description = "Whether to enable the PHP module.";
+        description = lib.mdDoc "Whether to enable the PHP module.";
       };
 
       phpPackage = mkOption {
         type = types.package;
         default = pkgs.php;
         defaultText = literalExpression "pkgs.php";
-        description = ''
+        description = lib.mdDoc ''
           Overridable attribute of the PHP package to use.
         '';
       };
···
       enablePerl = mkOption {
         type = types.bool;
         default = false;
-        description = "Whether to enable the Perl module (mod_perl).";
+        description = lib.mdDoc "Whether to enable the Perl module (mod_perl).";
       };
 
       phpOptions = mkOption {
···
           ''
             date.timezone = "CET"
           '';
-        description = ''
-          Options appended to the PHP configuration file <filename>php.ini</filename>.
+        description = lib.mdDoc ''
+          Options appended to the PHP configuration file {file}`php.ini`.
         '';
       };
 
···
         default = "event";
         example = "worker";
         description =
-          ''
+          lib.mdDoc ''
             Multi-processing module to be used by Apache. Available
-            modules are <literal>prefork</literal> (handles each
-            request in a separate child process), <literal>worker</literal>
+            modules are `prefork` (handles each
+            request in a separate child process), `worker`
             (hybrid approach that starts a number of child processes
-            each running a number of threads) and <literal>event</literal>
-            (the default; a recent variant of <literal>worker</literal>
+            each running a number of threads) and `event`
+            (the default; a recent variant of `worker`
             that handles persistent connections more efficiently).
           '';
       };
···
         type = types.int;
         default = 150;
         example = 8;
-        description = "Maximum number of httpd processes (prefork)";
+        description = lib.mdDoc "Maximum number of httpd processes (prefork)";
       };
 
       maxRequestsPerChild = mkOption {
         type = types.int;
         default = 0;
         example = 500;
-        description = ''
+        description = lib.mdDoc ''
           Maximum number of httpd requests answered per httpd child (prefork), 0 means unlimited.
         '';
       };
···
       sslCiphers = mkOption {
         type = types.str;
         default = "HIGH:!aNULL:!MD5:!EXP";
-        description = "Cipher Suite available for negotiation in SSL proxy handshake.";
+        description = lib.mdDoc "Cipher Suite available for negotiation in SSL proxy handshake.";
       };
 
       sslProtocols = mkOption {
         type = types.str;
         default = "All -SSLv2 -SSLv3 -TLSv1 -TLSv1.1";
         example = "All -SSLv2 -SSLv3";
-        description = "Allowed SSL/TLS protocol versions.";
+        description = lib.mdDoc "Allowed SSL/TLS protocol versions.";
       };
     };
 

nixos/modules/services/web-servers/apache-httpd/vhost-options.nix

···
     hostName = mkOption {
       type = types.str;
       default = name;
-      description = "Canonical hostname for the server.";
+      description = lib.mdDoc "Canonical hostname for the server.";
     };
 
     serverAliases = mkOption {
       type = types.listOf types.str;
       default = [];
       example = ["www.example.org" "www.example.org:8080" "example.org"];
-      description = ''
+      description = lib.mdDoc ''
         Additional names of virtual hosts served by this virtual host configuration.
       '';
     };
···
         options = {
           port = mkOption {
             type = types.port;
-            description = "Port to listen on";
+            description = lib.mdDoc "Port to listen on";
           };
           ip = mkOption {
             type = types.str;
             default = "*";
-            description = "IP to listen on. 0.0.0.0 for IPv4 only, * for all.";
+            description = lib.mdDoc "IP to listen on. 0.0.0.0 for IPv4 only, * for all.";
           };
           ssl = mkOption {
             type = types.bool;
             default = false;
-            description = "Whether to enable SSL (https) support.";
+            description = lib.mdDoc "Whether to enable SSL (https) support.";
           };
         };
       }));
···
     listenAddresses = mkOption {
       type = with types; nonEmptyListOf str;
 
-      description = ''
+      description = lib.mdDoc ''
         Listen addresses for this virtual host.
-        Compared to <literal>listen</literal> this only sets the addreses
+        Compared to `listen` this only sets the addreses
         and the ports are chosen automatically.
       '';
       default = [ "*" ];
···
     addSSL = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable HTTPS in addition to plain HTTP. This will set defaults for
-        <literal>listen</literal> to listen on all interfaces on the respective default
+        `listen` to listen on all interfaces on the respective default
         ports (80, 443).
       '';
     };
···
     onlySSL = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable HTTPS and reject plain HTTP connections. This will set
-        defaults for <literal>listen</literal> to listen on all interfaces on port 443.
+        defaults for `listen` to listen on all interfaces on port 443.
       '';
     };
 
     forceSSL = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether to add a separate nginx server block that permanently redirects (301)
         all plain HTTP traffic to HTTPS. This will set defaults for
-        <literal>listen</literal> to listen on all interfaces on the respective default
+        `listen` to listen on all interfaces on the respective default
         ports (80, 443), where the non-SSL listens are used for the redirect vhosts.
       '';
     };
···
     enableACME = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether to ask Let's Encrypt to sign a certificate for this vhost.
-        Alternately, you can use an existing certificate through <option>useACMEHost</option>.
+        Alternately, you can use an existing certificate through {option}`useACMEHost`.
       '';
     };
 
···
     acmeRoot = mkOption {
       type = types.nullOr types.str;
       default = "/var/lib/acme/acme-challenge";
-      description = ''
+      description = lib.mdDoc ''
         Directory for the acme challenge which is PUBLIC, don't put certs or keys in here.
         Set to null to inherit from config.security.acme.
       '';
···
     sslServerCert = mkOption {
       type = types.path;
       example = "/var/host.cert";
-      description = "Path to server SSL certificate.";
+      description = lib.mdDoc "Path to server SSL certificate.";
     };
 
     sslServerKey = mkOption {
       type = types.path;
       example = "/var/host.key";
-      description = "Path to server SSL certificate key.";
+      description = lib.mdDoc "Path to server SSL certificate key.";
     };
 
     sslServerChain = mkOption {
       type = types.nullOr types.path;
       default = null;
       example = "/var/ca.pem";
-      description = "Path to server SSL chain file.";
+      description = lib.mdDoc "Path to server SSL chain file.";
     };
 
     http2 = mkOption {
       type = types.bool;
       default = true;
-      description = ''
-        Whether to enable HTTP 2. HTTP/2 is supported in all multi-processing modules that come with httpd. <emphasis>However, if you use the prefork mpm, there will
-        be severe restrictions.</emphasis> Refer to <link xlink:href="https://httpd.apache.org/docs/2.4/howto/http2.html#mpm-config"/> for details.
+      description = lib.mdDoc ''
+        Whether to enable HTTP 2. HTTP/2 is supported in all multi-processing modules that come with httpd. *However, if you use the prefork mpm, there will
+        be severe restrictions.* Refer to <https://httpd.apache.org/docs/2.4/howto/http2.html#mpm-config> for details.
       '';
     };
 
···
       type = types.nullOr types.str;
       default = null;
       example = "[e-mail]";
-      description = "E-mail address of the server administrator.";
+      description = lib.mdDoc "E-mail address of the server administrator.";
     };
 
     documentRoot = mkOption {
       type = types.nullOr types.path;
       default = null;
       example = "/data/webserver/docs";
-      description = ''
+      description = lib.mdDoc ''
         The path of Apache's document root directory.  If left undefined,
         an empty directory in the Nix store will be used as root.
       '';
···
           dir = "/home/eelco/Dev/nix-homepage";
         }
       ];
-      description = ''
+      description = lib.mdDoc ''
         This option provides a simple way to serve static directories.
       '';
     };
···
           AllowOverride All
         </Directory>
       '';
-      description = ''
+      description = lib.mdDoc ''
         These lines go to httpd.conf verbatim. They will go after
         directories and directory aliases defined by default.
       '';
···
     enableUserDir = mkOption {
       type = types.bool;
       default = false;
-      description = ''
-        Whether to enable serving <filename>~/public_html</filename> as
-        <literal>/~«username»</literal>.
+      description = lib.mdDoc ''
+        Whether to enable serving {file}`~/public_html` as
+        `/~«username»`.
       '';
     };
 
···
       type = types.nullOr types.str;
       default = null;
       example = "http://newserver.example.org/";
-      description = ''
+      description = lib.mdDoc ''
         If set, all requests for this host are redirected permanently to
         the given URL.
       '';
···
       type = types.str;
       default = "common";
       example = "combined";
-      description = ''
+      description = lib.mdDoc ''
         Log format for Apache's log files. Possible values are: combined, common, referer, agent.
       '';
     };
···
       type = types.lines;
       default = "";
       example = "Disallow: /foo/";
-      description = ''
-        Specification of pages to be ignored by web crawlers. See <link xlink:href="http://www.robotstxt.org/"/> for details.
+      description = lib.mdDoc ''
+        Specification of pages to be ignored by web crawlers. See <http://www.robotstxt.org/> for details.
       '';
     };
 
···
           };
         };
       '';
-      description = ''
-        Declarative location config. See <link xlink:href="https://httpd.apache.org/docs/2.4/mod/core.html#location"/> for details.
+      description = lib.mdDoc ''
+        Declarative location config. See <https://httpd.apache.org/docs/2.4/mod/core.html#location> for details.
       '';
     };
 

nixos/modules/services/web-servers/caddy/default.nix

···
       default = pkgs.caddy;
       defaultText = literalExpression "pkgs.caddy";
       type = types.package;
-      description = ''
+      description = lib.mdDoc ''
         Caddy package to use.
       '';
     };
···
       example = literalExpression ''
         mkForce "level INFO";
       '';
-      description = ''
+      description = lib.mdDoc ''
         Configuration for the default logger. See
-        <link xlink:href="https://caddyserver.com/docs/caddyfile/options#log"/>
+        <https://caddyserver.com/docs/caddyfile/options#log>
         for details.
       '';
     };
···
           file_server
         ''';
       '';
-      description = ''
+      description = lib.mdDoc ''
         Override the configuration file used by Caddy. By default,
         NixOS generates one automatically.
       '';
···
     resume = mkOption {
       default = false;
       type = types.bool;
-      description = ''
-        Use saved config, if any (and prefer over any specified configuration passed with <literal>--config</literal>).
+      description = lib.mdDoc ''
+        Use saved config, if any (and prefer over any specified configuration passed with `--config`).
       '';
     };
 
···
           }
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         Additional lines of configuration appended to the global config section
-        of the <literal>Caddyfile</literal>.
+        of the `Caddyfile`.
 
-        Refer to <link xlink:href="https://caddyserver.com/docs/caddyfile/options#global-options"/>
+        Refer to <https://caddyserver.com/docs/caddyfile/options#global-options>
         for details on supported values.
       '';
     };
···
           root /srv/http
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         Additional lines of configuration appended to the automatically
-        generated <literal>Caddyfile</literal>.
+        generated `Caddyfile`.
       '';
     };
 
···
           };
         };
       '';
-      description = ''
+      description = lib.mdDoc ''
         Declarative specification of virtual hosts served by Caddy.
       '';
     };
···
       default = "https://acme-v02.api.letsencrypt.org/directory";
       example = "https://acme-staging-v02.api.letsencrypt.org/directory";
       type = with types; nullOr str;
-      description = ''
+      description = lib.mdDoc ''
         The URL to the ACME CA's directory. It is strongly recommended to set
         this to Let's Encrypt's staging endpoint for testing or development.
 
-        Set it to <literal>null</literal> if you want to write a more
+        Set it to `null` if you want to write a more
         fine-grained configuration manually.
       '';
     };
···
     email = mkOption {
       default = null;
       type = with types; nullOr str;
-      description = ''
+      description = lib.mdDoc ''
         Your email address. Mainly used when creating an ACME account with your
         CA, and is highly recommended in case there are problems with your
         certificates.

nixos/modules/services/web-servers/caddy/vhost-options.nix

···
     hostName = mkOption {
       type = types.str;
       default = name;
-      description = "Canonical hostname for the server.";
+      description = lib.mdDoc "Canonical hostname for the server.";
     };
 
     serverAliases = mkOption {
       type = with types; listOf str;
       default = [ ];
       example = [ "www.example.org" "example.org" ];
-      description = ''
+      description = lib.mdDoc ''
         Additional names of virtual hosts served by this virtual host configuration.
       '';
     };
 
     listenAddresses = mkOption {
       type = with types; listOf str;
-      description = ''
+      description = lib.mdDoc ''
         A list of host interfaces to bind to for this virtual host.
       '';
       default = [ ];
···
           output discard
         ''';
       '';
-      description = ''
+      description = lib.mdDoc ''
         Configuration for HTTP request logging (also known as access logs). See
-        <link xlink:href="https://caddyserver.com/docs/caddyfile/directives/log#log"/>
+        <https://caddyserver.com/docs/caddyfile/directives/log#log>
         for details.
       '';
     };
···
     extraConfig = mkOption {
       type = types.lines;
       default = "";
-      description = ''
+      description = lib.mdDoc ''
         Additional lines of configuration appended to this virtual host in the
-        automatically generated <literal>Caddyfile</literal>.
+        automatically generated `Caddyfile`.
       '';
     };
 

nixos/modules/services/web-servers/hydron.nix

···
       type = types.str;
       default = "weekly";
       example = "06:00";
-      description = ''
+      description = lib.mdDoc ''
         How often we run hydron import and possibly fetch tags. Runs by default every week.
 
         The format is described in
-        <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+        {manpage}`systemd.time(7)`.
       '';
     };
 

nixos/modules/services/web-servers/nginx/default.nix

···
         default = [];
         type = types.listOf (types.attrsOf types.anything);
         example = literalExpression "[ pkgs.nginxModules.brotli ]";
-        description = ''
-          Additional <link xlink:href="https://www.nginx.com/resources/wiki/modules/">third-party nginx modules</link>
+        description = lib.mdDoc ''
+          Additional [third-party nginx modules](https://www.nginx.com/resources/wiki/modules/)
           to install. Packaged modules are available in
-          <literal>pkgs.nginxModules</literal>.
+          `pkgs.nginxModules`.
         '';
       };
 
···
       appendConfig = mkOption {
         type = types.lines;
         default = "";
-        description = ''
+        description = lib.mdDoc ''
           Configuration lines appended to the generated Nginx
           configuration file. Commonly used by different modules
-          providing http snippets. <option>appendConfig</option>
+          providing http snippets. {option}`appendConfig`
           can be specified more than once and it's value will be
-          concatenated (contrary to <option>config</option> which
+          concatenated (contrary to {option}`config` which
           can be set only once).
         '';
       };
···
                               '"$request" $status $body_bytes_sent '
                               '"$http_referer" "$http_user_agent"';
         '';
-        description = ''
+        description = lib.mdDoc ''
           With nginx you must provide common http context definitions before
           they are used, e.g. log_format, resolver, etc. inside of server
           or location contexts. Use this attribute to set these definitions
···
       eventsConfig = mkOption {
         type = types.lines;
         default = "";
-        description = ''
+        description = lib.mdDoc ''
           Configuration lines to be set inside the events block.
         '';
       };
···
       user = mkOption {
         type = types.str;
         default = "nginx";
-        description = "User account under which nginx runs.";
+        description = lib.mdDoc "User account under which nginx runs.";
       };
 
       group = mkOption {
         type = types.str;
         default = "nginx";
-        description = "Group account under which nginx runs.";
+        description = lib.mdDoc "Group account under which nginx runs.";
       };
 
       serverTokens = mkOption {
         type = types.bool;
         default = false;
-        description = "Show nginx version in headers and error pages.";
+        description = lib.mdDoc "Show nginx version in headers and error pages.";
       };
 
       clientMaxBodySize = mkOption {
         type = types.str;
         default = "10m";
-        description = "Set nginx global client_max_body_size.";
+        description = lib.mdDoc "Set nginx global client_max_body_size.";
       };
 
       sslCiphers = mkOption {
         type = types.nullOr types.str;
         # Keep in sync with https://ssl-config.mozilla.org/#server=nginx&config=intermediate
         default = "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384";
-        description = "Ciphers to choose from when negotiating TLS handshakes.";
+        description = lib.mdDoc "Ciphers to choose from when negotiating TLS handshakes.";
       };
 
       sslProtocols = mkOption {
         type = types.str;
         default = "TLSv1.2 TLSv1.3";
         example = "TLSv1 TLSv1.1 TLSv1.2 TLSv1.3";
-        description = "Allowed TLS protocol versions.";
+        description = lib.mdDoc "Allowed TLS protocol versions.";
       };
 
       sslDhparam = mkOption {
         type = types.nullOr types.path;
         default = null;
         example = "/path/to/dhparams.pem";
-        description = "Path to DH parameters file.";
+        description = lib.mdDoc "Path to DH parameters file.";
       };
 
       proxyResolveWhileRunning = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Resolves domains of proxyPass targets at runtime
           and not only at start, you have to set
           services.nginx.resolver, too.
···
       mapHashBucketSize = mkOption {
         type = types.nullOr (types.enum [ 32 64 128 ]);
         default = null;
-        description = ''
+        description = lib.mdDoc ''
             Sets the bucket size for the map variables hash tables. Default
             value depends on the processor’s cache line size.
           '';
···
       mapHashMaxSize = mkOption {
         type = types.nullOr types.ints.positive;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
             Sets the maximum size of the map variables hash tables.
           '';
       };
···
       serverNamesHashBucketSize = mkOption {
         type = types.nullOr types.ints.positive;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
             Sets the bucket size for the server names hash tables. Default
             value depends on the processor’s cache line size.
           '';
···
       serverNamesHashMaxSize = mkOption {
         type = types.nullOr types.ints.positive;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
             Sets the maximum size of the server names hash tables.
           '';
       };
···
               type = types.listOf types.str;
               default = [];
               example = literalExpression ''[ "[::1]" "127.0.0.1:5353" ]'';
-              description = "List of resolvers to use";
+              description = lib.mdDoc "List of resolvers to use";
             };
             valid = mkOption {
               type = types.str;
               default = "";
               example = "30s";
-              description = ''
+              description = lib.mdDoc ''
                 By default, nginx caches answers using the TTL value of a response.
                 An optional valid parameter allows overriding it
               '';
···
             ipv6 = mkOption {
               type = types.bool;
               default = true;
-              description = ''
+              description = lib.mdDoc ''
                 By default, nginx will look up both IPv4 and IPv6 addresses while resolving.
                 If looking up of IPv6 addresses is not desired, the ipv6=off parameter can be
                 specified.
···
             };
           };
         };
-        description = ''
+        description = lib.mdDoc ''
           Configures name servers used to resolve names of upstream servers into addresses
         '';
         default = {};
···
                   backup = mkOption {
                     type = types.bool;
                     default = false;
-                    description = ''
+                    description = lib.mdDoc ''
                       Marks the server as a backup server. It will be passed
                       requests when the primary servers are unavailable.
                     '';
                   };
                 };
               });
-              description = ''
+              description = lib.mdDoc ''
                 Defines the address and other parameters of the upstream servers.
               '';
               default = {};
···
             extraConfig = mkOption {
               type = types.lines;
               default = "";
-              description = ''
+              description = lib.mdDoc ''
                 These lines go to the end of the upstream verbatim.
               '';
             };
           };
         });
-        description = ''
+        description = lib.mdDoc ''
           Defines a group of servers to use as proxy target.
         '';
         default = {};
···
             };
           };
         '';
-        description = "Declarative vhost config";
+        description = lib.mdDoc "Declarative vhost config";
       };
     };
   };

nixos/modules/services/web-servers/nginx/location-options.nix

···
           user = "password";
         };
       '';
-      description = ''
+      description = lib.mdDoc ''
         Basic Auth protection for a vhost.
 
         WARNING: This is implemented to store the password in plain text in the
···
     basicAuthFile = mkOption {
       type = types.nullOr types.path;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Basic Auth password file for a vhost.
-        Can be created via: <command>htpasswd -c &lt;filename&gt; &lt;username&gt;</command>.
+        Can be created via: {command}`htpasswd -c <filename> <username>`.
 
         WARNING: The generate file contains the users' passwords in a
         non-cryptographically-securely hashed way.
···
       type = types.nullOr types.str;
       default = null;
       example = "http://www.example.org/";
-      description = ''
+      description = lib.mdDoc ''
         Adds proxy_pass directive and sets recommended proxy headers if
         recommendedProxySettings is enabled.
       '';
···
       type = types.bool;
       default = false;
       example = true;
-      description = ''
+      description = lib.mdDoc ''
         Whether to support proxying websocket connections with HTTP/1.1.
       '';
     };
···
       type = types.nullOr types.str;
       default = null;
       example = "index.php index.html";
-      description = ''
+      description = lib.mdDoc ''
         Adds index directive.
       '';
     };
···
       type = types.nullOr types.str;
       default = null;
       example = "$uri =404";
-      description = ''
+      description = lib.mdDoc ''
         Adds try_files directive.
       '';
     };
···
       type = types.nullOr types.path;
       default = null;
       example = "/your/root/directory";
-      description = ''
+      description = lib.mdDoc ''
         Root directory for requests.
       '';
     };
···
       type = types.nullOr types.path;
       default = null;
       example = "/your/alias/directory";
-      description = ''
+      description = lib.mdDoc ''
         Alias directory for requests.
       '';
     };
···
       type = types.nullOr types.str;
       default = null;
       example = "301 http://example.com$request_uri";
-      description = ''
+      description = lib.mdDoc ''
         Adds a return directive, for e.g. redirections.
       '';
     };
···
     fastcgiParams = mkOption {
       type = types.attrsOf (types.either types.str types.path);
       default = {};
-      description = ''
+      description = lib.mdDoc ''
         FastCGI parameters to override.  Unlike in the Nginx
         configuration file, overriding only some default parameters
         won't unset the default values for other parameters.
···
     extraConfig = mkOption {
       type = types.lines;
       default = "";
-      description = ''
+      description = lib.mdDoc ''
         These lines go to the end of the location verbatim.
       '';
     };
···
       type = types.bool;
       default = config.services.nginx.recommendedProxySettings;
       defaultText = literalExpression "config.services.nginx.recommendedProxySettings";
-      description = ''
+      description = lib.mdDoc ''
         Enable recommended proxy settings.
       '';
     };

nixos/modules/services/web-servers/nginx/vhost-options.nix

···
     serverName = mkOption {
       type = types.nullOr types.str;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Name of this virtual host. Defaults to attribute name in virtualHosts.
       '';
       example = "example.org";
···
       type = types.listOf types.str;
       default = [];
       example = [ "www.example.org" "example.org" ];
-      description = ''
+      description = lib.mdDoc ''
         Additional names of virtual hosts served by this virtual host configuration.
       '';
     };
 
     listen = mkOption {
       type = with types; listOf (submodule { options = {
-        addr = mkOption { type = str;  description = "IP address.";  };
-        port = mkOption { type = int;  description = "Port number."; default = 80; };
-        ssl  = mkOption { type = bool; description = "Enable SSL.";  default = false; };
-        extraParameters = mkOption { type = listOf str; description = "Extra parameters of this listen directive."; default = []; example = [ "backlog=1024" "deferred" ]; };
+        addr = mkOption { type = str;  description = lib.mdDoc "IP address.";  };
+        port = mkOption { type = int;  description = lib.mdDoc "Port number."; default = 80; };
+        ssl  = mkOption { type = bool; description = lib.mdDoc "Enable SSL.";  default = false; };
+        extraParameters = mkOption { type = listOf str; description = lib.mdDoc "Extra parameters of this listen directive."; default = []; example = [ "backlog=1024" "deferred" ]; };
       }; });
       default = [];
       example = [
         { addr = "195.154.1.1"; port = 443; ssl = true; }
         { addr = "192.154.1.1"; port = 80; }
       ];
-      description = ''
+      description = lib.mdDoc ''
         Listen addresses and ports for this virtual host.
         IPv6 addresses must be enclosed in square brackets.
-        Note: this option overrides <literal>addSSL</literal>
-        and <literal>onlySSL</literal>.
+        Note: this option overrides `addSSL`
+        and `onlySSL`.
 
         If you only want to set the addresses manually and not
-        the ports, take a look at <literal>listenAddresses</literal>
+        the ports, take a look at `listenAddresses`
       '';
     };
 
     listenAddresses = mkOption {
       type = with types; listOf str;
 
-      description = ''
+      description = lib.mdDoc ''
         Listen addresses for this virtual host.
-        Compared to <literal>listen</literal> this only sets the addreses
+        Compared to `listen` this only sets the addreses
         and the ports are choosen automatically.
 
-        Note: This option overrides <literal>enableIPv6</literal>
+        Note: This option overrides `enableIPv6`
       '';
       default = [];
       example = [ "127.0.0.1" "[::1]" ];
···
     enableACME = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether to ask Let's Encrypt to sign a certificate for this vhost.
-        Alternately, you can use an existing certificate through <option>useACMEHost</option>.
+        Alternately, you can use an existing certificate through {option}`useACMEHost`.
       '';
     };
 
···
     acmeRoot = mkOption {
       type = types.nullOr types.str;
       default = "/var/lib/acme/acme-challenge";
-      description = ''
+      description = lib.mdDoc ''
         Directory for the acme challenge which is PUBLIC, don't put certs or keys in here.
         Set to null to inherit from config.security.acme.
       '';
···
     acmeFallbackHost = mkOption {
       type = types.nullOr types.str;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Host which to proxy requests to if acme challenge is not found. Useful
         if you want multiple hosts to be able to verify the same domain name.
       '';
···
     addSSL = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable HTTPS in addition to plain HTTP. This will set defaults for
-        <literal>listen</literal> to listen on all interfaces on the respective default
+        `listen` to listen on all interfaces on the respective default
         ports (80, 443).
       '';
     };
···
     onlySSL = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable HTTPS and reject plain HTTP connections. This will set
-        defaults for <literal>listen</literal> to listen on all interfaces on port 443.
+        defaults for `listen` to listen on all interfaces on port 443.
       '';
     };
 
···
     forceSSL = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether to add a separate nginx server block that permanently redirects (301)
         all plain HTTP traffic to HTTPS. This will set defaults for
-        <literal>listen</literal> to listen on all interfaces on the respective default
+        `listen` to listen on all interfaces on the respective default
         ports (80, 443), where the non-SSL listens are used for the redirect vhosts.
       '';
     };
···
     rejectSSL = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether to listen for and reject all HTTPS connections to this vhost. Useful in
-        <link linkend="opt-services.nginx.virtualHosts._name_.default">default</link>
+        [default](#opt-services.nginx.virtualHosts._name_.default)
         server blocks to avoid serving the certificate for another vhost. Uses the
-        <literal>ssl_reject_handshake</literal> directive available in nginx versions
+        `ssl_reject_handshake` directive available in nginx versions
         1.19.4 and above.
       '';
     };
···
     kTLS = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable kTLS support.
         Implementing TLS in the kernel (kTLS) improves performance by significantly
         reducing the need for copying operations between user space and the kernel.
···
     sslCertificate = mkOption {
       type = types.path;
       example = "/var/host.cert";
-      description = "Path to server SSL certificate.";
+      description = lib.mdDoc "Path to server SSL certificate.";
     };
 
     sslCertificateKey = mkOption {
       type = types.path;
       example = "/var/host.key";
-      description = "Path to server SSL certificate key.";
+      description = lib.mdDoc "Path to server SSL certificate key.";
     };
 
     sslTrustedCertificate = mkOption {
       type = types.nullOr types.path;
       default = null;
       example = literalExpression ''"''${pkgs.cacert}/etc/ssl/certs/ca-bundle.crt"'';
-      description = "Path to root SSL certificate for stapling and client certificates.";
+      description = lib.mdDoc "Path to root SSL certificate for stapling and client certificates.";
     };
 
     http2 = mkOption {
       type = types.bool;
       default = true;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable HTTP 2.
         Note that (as of writing) due to nginx's implementation, to disable
         HTTP 2 you have to disable it on all vhosts that use a given
···
     reuseport = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Create an individual listening socket .
         It is required to specify only once on one of the hosts.
       '';
···
       type = types.nullOr types.path;
       default = null;
       example = "/data/webserver/docs";
-      description = ''
+      description = lib.mdDoc ''
         The path of the web root directory.
       '';
     };
···
     default = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Makes this vhost the default.
       '';
     };
···
     extraConfig = mkOption {
       type = types.lines;
       default = "";
-      description = ''
+      description = lib.mdDoc ''
         These lines go to the end of the vhost verbatim.
       '';
     };
···
       type = types.nullOr types.str;
       default = null;
       example = "newserver.example.org";
-      description = ''
+      description = lib.mdDoc ''
         If set, all requests for this host are redirected permanently to
         the given hostname.
       '';
···
           user = "password";
         };
       '';
-      description = ''
+      description = lib.mdDoc ''
         Basic Auth protection for a vhost.
 
         WARNING: This is implemented to store the password in plain text in the
···
     basicAuthFile = mkOption {
       type = types.nullOr types.path;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Basic Auth password file for a vhost.
-        Can be created via: <command>htpasswd -c &lt;filename&gt; &lt;username&gt;</command>.
+        Can be created via: {command}`htpasswd -c <filename> <username>`.
 
         WARNING: The generate file contains the users' passwords in a
         non-cryptographically-securely hashed way.
···
           };
         };
       '';
-      description = "Declarative location config";
+      description = lib.mdDoc "Declarative location config";
     };
   };
 }

nixos/modules/services/x11/desktop-managers/default.nix

···
           type = types.enum [ "center" "fill" "max" "scale" "tile" ];
           default = "scale";
           example = "fill";
-          description = ''
-            The file <filename>~/.background-image</filename> is used as a background image.
+          description = lib.mdDoc ''
+            The file {file}`~/.background-image` is used as a background image.
             This option specifies the placement of this image onto your desktop.
 
             Possible values:
-            <literal>center</literal>: Center the image on the background. If it is too small, it will be surrounded by a black border.
-            <literal>fill</literal>: Like <literal>scale</literal>, but preserves aspect ratio by zooming the image until it fits. Either a horizontal or a vertical part of the image will be cut off.
-            <literal>max</literal>: Like <literal>fill</literal>, but scale the image to the maximum size that fits the screen with black borders on one side.
-            <literal>scale</literal>: Fit the file into the background without repeating it, cutting off stuff or using borders. But the aspect ratio is not preserved either.
-            <literal>tile</literal>: Tile (repeat) the image in case it is too small for the screen.
+            `center`: Center the image on the background. If it is too small, it will be surrounded by a black border.
+            `fill`: Like `scale`, but preserves aspect ratio by zooming the image until it fits. Either a horizontal or a vertical part of the image will be cut off.
+            `max`: Like `fill`, but scale the image to the maximum size that fits the screen with black borders on one side.
+            `scale`: Fit the file into the background without repeating it, cutting off stuff or using borders. But the aspect ratio is not preserved either.
+            `tile`: Tile (repeat) the image in case it is too small for the screen.
           '';
         };
 
         combineScreens = mkOption {
           type = types.bool;
           default = false;
-          description = ''
-            When set to <literal>true</literal> the wallpaper will stretch across all screens.
-            When set to <literal>false</literal> the wallpaper is duplicated to all screens.
+          description = lib.mdDoc ''
+            When set to `true` the wallpaper will stretch across all screens.
+            When set to `false` the wallpaper is duplicated to all screens.
           '';
         };
       };

nixos/modules/services/x11/display-managers/lightdm.nix

···
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable lightdm as the display manager.
         '';
       };
···
         enable = mkOption {
           type = types.bool;
           default = true;
-          description = ''
+          description = lib.mdDoc ''
             If set to false, run lightdm in greeterless mode. This only works if autologin
             is enabled and autoLogin.timeout is zero.
           '';
         };
         package = mkOption {
           type = types.package;
-          description = ''
+          description = lib.mdDoc ''
             The LightDM greeter to login via. The package should be a directory
             containing a .desktop file matching the name in the 'name' option.
           '';
···
         };
         name = mkOption {
           type = types.str;
-          description = ''
+          description = lib.mdDoc ''
             The name of a .desktop file in the directory specified
             in the 'package' option.
           '';
···
         example = ''
           user-authority-in-system-dir = true
         '';
-        description = "Extra lines to append to LightDM section.";
+        description = lib.mdDoc "Extra lines to append to LightDM section.";
       };
 
       background = mkOption {
         type = types.either types.path (types.strMatching "^#[0-9]\{6\}$");
         # Manual cannot depend on packages, we are actually setting the default in config below.
         defaultText = literalExpression "pkgs.nixos-artwork.wallpapers.simple-dark-gray-bottom.gnomeFilePath";
-        description = ''
+        description = lib.mdDoc ''
           The background image or color to use.
         '';
       };
···
         example = ''
           greeter-show-manual-login=true
         '';
-        description = "Extra lines to append to SeatDefaults section.";
+        description = lib.mdDoc "Extra lines to append to SeatDefaults section.";
       };
 
       # Configuration for automatic login specific to LightDM
       autoLogin.timeout = mkOption {
         type = types.int;
         default = 0;
-        description = ''
+        description = lib.mdDoc ''
           Show the greeter for this many seconds before automatic login occurs.
         '';
       };

nixos/modules/services/x11/xserver.nix

···
     output = mkOption {
       type = types.str;
       example = "DVI-0";
-      description = ''
+      description = lib.mdDoc ''
         The output name of the monitor, as shown by
-        <citerefentry><refentrytitle>xrandr</refentrytitle><manvolnum>1</manvolnum></citerefentry> invoked without arguments.
+        {manpage}`xrandr(1)` invoked without arguments.
       '';
     };
 
     primary = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether this head is treated as the primary monitor,
       '';
     };
···
         DisplaySize 408 306
         Option "DPMS" "false"
       '';
-      description = ''
-        Extra lines to append to the <literal>Monitor</literal> section
+      description = lib.mdDoc ''
+        Extra lines to append to the `Monitor` section
         verbatim. Available options are documented in the MONITOR section in
-        <citerefentry><refentrytitle>xorg.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+        {manpage}`xorg.conf(5)`.
       '';
     };
   };
···
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable the X server.
         '';
       };
···
       autorun = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Whether to start the X server automatically.
         '';
       };
···
         default = [];
         example = literalExpression "[ pkgs.xterm ]";
         type = types.listOf types.package;
-        description = "Which X11 packages to exclude from the default environment";
+        description = lib.mdDoc "Which X11 packages to exclude from the default environment";
       };
 
       exportConfiguration = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to symlink the X server configuration under
-          <filename>/etc/X11/xorg.conf</filename>.
+          {file}`/etc/X11/xorg.conf`.
         '';
       };
 
       enableTCP = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to allow the X server to accept TCP connections.
         '';
       };
···
       autoRepeatDelay = mkOption {
         type = types.nullOr types.int;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Sets the autorepeat delay (length of time in milliseconds that a key must be depressed before autorepeat starts).
         '';
       };
···
       autoRepeatInterval = mkOption {
         type = types.nullOr types.int;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Sets the autorepeat interval (length of time in milliseconds that should elapse between autorepeat-generated keystrokes).
         '';
       };
···
             '''
           ]
         '';
-        description = "Content of additional InputClass sections of the X server configuration file.";
+        description = lib.mdDoc "Content of additional InputClass sections of the X server configuration file.";
       };
 
       modules = mkOption {
         type = types.listOf types.path;
         default = [];
         example = literalExpression "[ pkgs.xf86_input_wacom ]";
-        description = "Packages to be added to the module search path of the X server.";
+        description = lib.mdDoc "Packages to be added to the module search path of the X server.";
       };
 
       resolutions = mkOption {
         type = types.listOf types.attrs;
         default = [];
         example = [ { x = 1600; y = 1200; } { x = 1024; y = 786; } ];
-        description = ''
+        description = lib.mdDoc ''
           The screen resolutions for the X server.  The first element
           is the default resolution.  If this list is empty, the X
           server will automatically configure the resolution.
···
               path  = [ "xorg" n ];
               title = removePrefix "xf86video" n;
             }) pkgs.xorg);
-        description = ''
+        description = lib.mdDoc ''
           The names of the video drivers the configuration
           supports. They will be tried in order until one that
           supports your card is found.
···
         type = types.nullOr types.str;
         default = null;
         example = "i810";
-        description = ''
+        description = lib.mdDoc ''
           The name of the video driver for your graphics card.  This
           option is obsolete; please set the
-          <option>services.xserver.videoDrivers</option> instead.
+          {option}`services.xserver.videoDrivers` instead.
         '';
       };
 
···
       dpi = mkOption {
         type = types.nullOr types.int;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Force global DPI resolution to use for X server. It's recommended to
           use this only when DPI is detected incorrectly; also consider using
-          <literal>Monitor</literal> section in configuration file instead.
+          `Monitor` section in configuration file instead.
         '';
       };
 
       updateDbusEnvironment = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to update the DBus activation environment after launching the
           desktop manager.
         '';
···
       layout = mkOption {
         type = types.str;
         default = "us";
-        description = ''
+        description = lib.mdDoc ''
           Keyboard layout, or multiple keyboard layouts separated by commas.
         '';
       };
···
         type = types.str;
         default = "pc104";
         example = "presario";
-        description = ''
+        description = lib.mdDoc ''
           Keyboard model.
         '';
       };
···
         type = types.commas;
         default = "terminate:ctrl_alt_bksp";
         example = "grp:caps_toggle,grp_led:scroll";
-        description = ''
+        description = lib.mdDoc ''
           X keyboard options; layout switching goes here.
         '';
       };
···
         type = types.str;
         default = "";
         example = "colemak";
-        description = ''
+        description = lib.mdDoc ''
           X keyboard variant.
         '';
       };
···
         type = types.path;
         default = "${pkgs.xkeyboard_config}/etc/X11/xkb";
         defaultText = literalExpression ''"''${pkgs.xkeyboard_config}/etc/X11/xkb"'';
-        description = ''
+        description = lib.mdDoc ''
           Path used for -xkbdir xserver parameter.
         '';
       };
 
       config = mkOption {
         type = types.lines;
-        description = ''
+        description = lib.mdDoc ''
           The contents of the configuration file of the X server
-          (<filename>xorg.conf</filename>).
+          ({file}`xorg.conf`).
 
           This option is set by multiple modules, and the configs are
           concatenated together.
 
           In Xorg configs the last config entries take precedence,
-          so you may want to use <literal>lib.mkAfter</literal> on this option
+          so you may want to use `lib.mkAfter` on this option
           to override NixOS's defaults.
         '';
       };
···
         type = types.lines;
         default = "";
         example = ''FontPath "/path/to/my/fonts"'';
-        description = "Contents of the first <literal>Files</literal> section of the X server configuration file.";
+        description = lib.mdDoc "Contents of the first `Files` section of the X server configuration file.";
       };
 
       deviceSection = mkOption {
         type = types.lines;
         default = "";
         example = "VideoRAM 131072";
-        description = "Contents of the first Device section of the X server configuration file.";
+        description = lib.mdDoc "Contents of the first Device section of the X server configuration file.";
       };
 
       screenSection = mkOption {
···
         example = ''
           Option "RandRRotation" "on"
         '';
-        description = "Contents of the first Screen section of the X server configuration file.";
+        description = lib.mdDoc "Contents of the first Screen section of the X server configuration file.";
       };
 
       monitorSection = mkOption {
         type = types.lines;
         default = "";
         example = "HorizSync 28-49";
-        description = "Contents of the first Monitor section of the X server configuration file.";
+        description = lib.mdDoc "Contents of the first Monitor section of the X server configuration file.";
       };
 
       extraConfig = mkOption {
         type = types.lines;
         default = "";
-        description = "Additional contents (sections) included in the X server configuration file";
+        description = lib.mdDoc "Additional contents (sections) included in the X server configuration file";
       };
 
       xrandrHeads = mkOption {
···
           Option "SuspendTime" "0"
           Option "OffTime" "0"
           '';
-        description = "Contents of the ServerFlags section of the X server configuration file.";
+        description = lib.mdDoc "Contents of the ServerFlags section of the X server configuration file.";
       };
 
       moduleSection = mkOption {
···
             SubSection "extmod"
             EndSubsection
           '';
-        description = "Contents of the Module section of the X server configuration file.";
+        description = lib.mdDoc "Contents of the Module section of the X server configuration file.";
       };
 
       serverLayoutSection = mkOption {
···
           ''
             Option "AIGLX" "true"
           '';
-        description = "Contents of the ServerLayout section of the X server configuration file.";
+        description = lib.mdDoc "Contents of the ServerLayout section of the X server configuration file.";
       };
 
       extraDisplaySettings = mkOption {
         type = types.lines;
         default = "";
         example = "Virtual 2048 2048";
-        description = "Lines to be added to every Display subsection of the Screen section.";
+        description = lib.mdDoc "Lines to be added to every Display subsection of the Screen section.";
       };
 
       defaultDepth = mkOption {
         type = types.int;
         default = 0;
         example = 8;
-        description = "Default colour depth.";
+        description = lib.mdDoc "Default colour depth.";
       };
 
       fontPath = mkOption {
         type = types.nullOr types.str;
         default = null;
         example = "unix/:7100";
-        description = ''
+        description = lib.mdDoc ''
           Set the X server FontPath. Defaults to null, which
           means the compiled in defaults will be used. See
           man xorg.conf for details.
···
       tty = mkOption {
         type = types.nullOr types.int;
         default = 7;
-        description = "Virtual console for the X server.";
+        description = lib.mdDoc "Virtual console for the X server.";
       };
 
       display = mkOption {
         type = types.nullOr types.int;
         default = 0;
-        description = "Display number for the X server.";
+        description = lib.mdDoc "Display number for the X server.";
       };
 
       virtualScreen = mkOption {
         type = types.nullOr types.attrs;
         default = null;
         example = { x = 2048; y = 2048; };
-        description = ''
+        description = lib.mdDoc ''
           Virtual screen size for Xrandr.
         '';
       };
···
         type = types.nullOr types.str;
         default = "/dev/null";
         example = "/var/log/Xorg.0.log";
-        description = ''
+        description = lib.mdDoc ''
           Controls the file Xorg logs to.
 
-          The default of <literal>/dev/null</literal> is set so that systemd services (like <literal>displayManagers</literal>) only log to the journal and don't create their own log files.
+          The default of `/dev/null` is set so that systemd services (like `displayManagers`) only log to the journal and don't create their own log files.
 
-          Setting this to <literal>null</literal> will not pass the <literal>-logfile</literal> argument to Xorg which allows it to log to its default logfile locations instead (see <literal>man Xorg</literal>). You probably only want this behaviour when running Xorg manually (e.g. via <literal>startx</literal>).
+          Setting this to `null` will not pass the `-logfile` argument to Xorg which allows it to log to its default logfile locations instead (see `man Xorg`). You probably only want this behaviour when running Xorg manually (e.g. via `startx`).
         '';
       };
 
···
         type = types.nullOr types.int;
         default = 3;
         example = 7;
-        description = ''
+        description = lib.mdDoc ''
           Controls verbosity of X logging.
         '';
       };
···
       useGlamor = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to use the Glamor module for 2D acceleration,
           if possible.
         '';
···
       enableCtrlAltBackspace = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable the DontZap option, which binds Ctrl+Alt+Backspace
           to forcefully kill X. This can lead to data loss and is disabled
           by default.
···
       terminateOnReset = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Whether to terminate X upon server reset.
         '';
       };

nixos/modules/system/activation/top-level.nix

···
           options.inheritParentConfig = mkOption {
             type = types.bool;
             default = true;
-            description = "Include the entire system's configuration. Set to false to make a completely differently configured system.";
+            description = lib.mdDoc "Include the entire system's configuration. Set to false to make a completely differently configured system.";
           };
 
           options.configuration = mkOption {
             default = {};
-            description = ''
+            description = lib.mdDoc ''
               Arbitrary NixOS configuration.
 
               Anything you can add to a normal NixOS configuration, you can add
···
       toplevel = mkOption {
         type = types.package;
         readOnly = true;
-        description = ''
+        description = lib.mdDoc ''
           This option contains the store path that typically represents a NixOS system.
 
           You can read this path in a custom deployment tool for example.
···
     system.copySystemConfiguration = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         If enabled, copies the NixOS configuration file
-        (usually <filename>/etc/nixos/configuration.nix</filename>)
+        (usually {file}`/etc/nixos/configuration.nix`)
         and links it from the resulting system
-        (getting to <filename>/run/current-system/configuration.nix</filename>).
+        (getting to {file}`/run/current-system/configuration.nix`).
         Note that only this single file is copied, even if it imports others.
       '';
     };
···
     system.extraDependencies = mkOption {
       type = types.listOf types.package;
       default = [];
-      description = ''
+      description = lib.mdDoc ''
         A list of packages that should be included in the system
         closure but not otherwise made available to users. This is
         primarily used by the installation tests.
···
         { ... }: {
           options.original = mkOption {
             type = types.package;
-            description = "The original package to override.";
+            description = lib.mdDoc "The original package to override.";
           };
 
           options.replacement = mkOption {
             type = types.package;
-            description = "The replacement package.";
+            description = lib.mdDoc "The replacement package.";
           };
         })
       );
···
         oldDependency = original;
         newDependency = replacement;
       });
-      description = ''
+      description = lib.mdDoc ''
         List of packages to override without doing a full rebuild.
         The original derivation and replacement derivation must have the same
         name length, and ideally should have close-to-identical directory layout.
···
         then "unnamed"
         else config.networking.hostName;
       '';
-      description = ''
-        The name of the system used in the <option>system.build.toplevel</option> derivation.
+      description = lib.mdDoc ''
+        The name of the system used in the {option}`system.build.toplevel` derivation.
 
         That derivation has the following name:
-        <literal>"nixos-system-''${config.system.name}-''${config.system.nixos.label}"</literal>
+        `"nixos-system-''${config.system.name}-''${config.system.nixos.label}"`
       '';
     };
 

nixos/modules/system/boot/loader/generic-extlinux-compatible/default.nix

···
       enable = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Whether to generate an extlinux-compatible configuration file
-          under <literal>/boot/extlinux.conf</literal>.  For instance,
+          under `/boot/extlinux.conf`.  For instance,
           U-Boot's generic distro boot support uses this file format.
 
-          See <link xlink:href="http://git.denx.de/?p=u-boot.git;a=blob;f=doc/README.distro;hb=refs/heads/master">U-boot's documentation</link>
+          See [U-boot's documentation](http://git.denx.de/?p=u-boot.git;a=blob;f=doc/README.distro;hb=refs/heads/master)
           for more information.
         '';
       };
···
       useGenerationDeviceTree = mkOption {
         default = true;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Whether to generate Device Tree-related directives in the
           extlinux configuration.
 
···
         default = 20;
         example = 10;
         type = types.int;
-        description = ''
+        description = lib.mdDoc ''
           Maximum number of configurations in the boot menu.
         '';
       };
···
       populateCmd = mkOption {
         type = types.str;
         readOnly = true;
-        description = ''
+        description = lib.mdDoc ''
           Contains the builder command used to populate an image,
-          honoring all options except the <literal>-c &lt;path-to-default-configuration&gt;</literal>
+          honoring all options except the `-c <path-to-default-configuration>`
           argument.
           Useful to have for sdImage.populateRootCommands
         '';

nixos/modules/system/boot/modprobe.nix

···
         ''
           options parport_pc io=0x378 irq=7 dma=1
         '';
-      description = ''
+      description = lib.mdDoc ''
         Any additional configuration to be appended to the generated
-        <filename>modprobe.conf</filename>.  This is typically used to
+        {file}`modprobe.conf`.  This is typically used to
         specify module options.  See
-        <citerefentry><refentrytitle>modprobe.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        {manpage}`modprobe.d(5)` for details.
       '';
       type = types.lines;
     };

nixos/modules/system/boot/networkd.nix

···
       default = {};
       example = { SpeedMeter = true; ManageForeignRoutingPolicyRules = false; };
       type = types.addCheck (types.attrsOf unitOption) check.global.sectionNetwork;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[Network]</literal> section of the networkd config.
-        See <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[Network]` section of the networkd config.
+        See {manpage}`networkd.conf(5)` for details.
       '';
     };
 
···
       default = {};
       example = { DUIDType = "vendor"; };
       type = types.addCheck (types.attrsOf unitOption) check.global.sectionDHCPv4;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[DHCPv4]</literal> section of the networkd config.
-        See <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[DHCPv4]` section of the networkd config.
+        See {manpage}`networkd.conf(5)` for details.
       '';
     };
 
···
       default = {};
       example = { DUIDType = "vendor"; };
       type = types.addCheck (types.attrsOf unitOption) check.global.sectionDHCPv6;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[DHCPv6]</literal> section of the networkd config.
-        See <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[DHCPv6]` section of the networkd config.
+        See {manpage}`networkd.conf(5)` for details.
       '';
     };
   };
···
       default = {};
       example = { MACAddress = "00:ff:ee:aa:cc:dd"; };
       type = types.addCheck (types.attrsOf unitOption) check.link.sectionLink;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[Link]</literal> section of the unit.  See
-        <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[Link]` section of the unit.  See
+        {manpage}`systemd.link(5)` for details.
       '';
     };
 
···
       wireguardPeerConfig = mkOption {
         default = {};
         type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionWireGuardPeer;
-        description = ''
+        description = lib.mdDoc ''
           Each attribute in this set specifies an option in the
-          <literal>[WireGuardPeer]</literal> section of the unit.  See
-          <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+          `[WireGuardPeer]` section of the unit.  See
+          {manpage}`systemd.network(5)` for details.
         '';
       };
     };
···
     netdevConfig = mkOption {
       example = { Name = "mybridge"; Kind = "bridge"; };
       type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionNetdev;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[Netdev]</literal> section of the unit.  See
-        <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[Netdev]` section of the unit.  See
+        {manpage}`systemd.netdev(5)` for details.
       '';
     };
 
···
       default = {};
       example = { Id = 4; };
       type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionVLAN;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[VLAN]</literal> section of the unit.  See
-        <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[VLAN]` section of the unit.  See
+        {manpage}`systemd.netdev(5)` for details.
       '';
     };
 
···
       default = {};
       example = { Mode = "private"; };
       type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionMACVLAN;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[MACVLAN]</literal> section of the unit.  See
-        <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[MACVLAN]` section of the unit.  See
+        {manpage}`systemd.netdev(5)` for details.
       '';
     };
 
     vxlanConfig = mkOption {
       default = {};
       type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionVXLAN;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[VXLAN]</literal> section of the unit.  See
-        <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[VXLAN]` section of the unit.  See
+        {manpage}`systemd.netdev(5)` for details.
       '';
     };
 
···
       default = {};
       example = { Remote = "192.168.1.1"; };
       type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionTunnel;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[Tunnel]</literal> section of the unit.  See
-        <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[Tunnel]` section of the unit.  See
+        {manpage}`systemd.netdev(5)` for details.
       '';
     };
 
···
       default = { };
       example = { Port = 9001; };
       type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionFooOverUDP;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[FooOverUDP]</literal> section of the unit.  See
-        <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[FooOverUDP]` section of the unit.  See
+        {manpage}`systemd.netdev(5)` for details.
       '';
     };
 
···
       default = {};
       example = { Name = "veth2"; };
       type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionPeer;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[Peer]</literal> section of the unit.  See
-        <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[Peer]` section of the unit.  See
+        {manpage}`systemd.netdev(5)` for details.
       '';
     };
 
···
       default = {};
       example = { User = "openvpn"; };
       type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionTun;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[Tun]</literal> section of the unit.  See
-        <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[Tun]` section of the unit.  See
+        {manpage}`systemd.netdev(5)` for details.
       '';
     };
 
···
       default = {};
       example = { User = "openvpn"; };
       type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionTap;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[Tap]</literal> section of the unit.  See
-        <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[Tap]` section of the unit.  See
+        {manpage}`systemd.netdev(5)` for details.
       '';
     };
 
···
         FirewallMark = 42;
       };
       type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionWireGuard;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[WireGuard]</literal> section of the unit. See
-        <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
-        Use <literal>PrivateKeyFile</literal> instead of
-        <literal>PrivateKey</literal>: the nix store is
+        `[WireGuard]` section of the unit. See
+        {manpage}`systemd.netdev(5)` for details.
+        Use `PrivateKeyFile` instead of
+        `PrivateKey`: the nix store is
         world-readable.
       '';
     };
···
         PersistentKeepalive = 15;
       };}];
       type = with types; listOf (submodule wireguardPeerOptions);
-      description = ''
+      description = lib.mdDoc ''
         Each item in this array specifies an option in the
-        <literal>[WireGuardPeer]</literal> section of the unit. See
-        <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
-        Use <literal>PresharedKeyFile</literal> instead of
-        <literal>PresharedKey</literal>: the nix store is
+        `[WireGuardPeer]` section of the unit. See
+        {manpage}`systemd.netdev(5)` for details.
+        Use `PresharedKeyFile` instead of
+        `PresharedKey`: the nix store is
         world-readable.
       '';
     };
···
       default = {};
       example = { Mode = "802.3ad"; };
       type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionBond;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[Bond]</literal> section of the unit.  See
-        <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[Bond]` section of the unit.  See
+        {manpage}`systemd.netdev(5)` for details.
       '';
     };
 
···
       default = {};
       example = { InterfaceId = 1; };
       type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionXfrm;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[Xfrm]</literal> section of the unit.  See
-        <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[Xfrm]` section of the unit.  See
+        {manpage}`systemd.netdev(5)` for details.
       '';
     };
 
···
       default = {};
       example = { Table = 2342; };
       type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionVRF;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[VRF]</literal> section of the unit. See
-        <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[VRF]` section of the unit. See
+        {manpage}`systemd.netdev(5)` for details.
         A detailed explanation about how VRFs work can be found in the
-        <link xlink:href="https://www.kernel.org/doc/Documentation/networking/vrf.txt">kernel docs</link>.
+        [kernel docs](https://www.kernel.org/doc/Documentation/networking/vrf.txt).
       '';
     };
 
···
         RoutingAlgorithm = "batman-v";
       };
       type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionBatmanAdvanced;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[BatmanAdvanced]</literal> section of the unit. See
-        <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[BatmanAdvanced]` section of the unit. See
+        {manpage}`systemd.netdev(5)` for details.
       '';
     };
 
···
       addressConfig = mkOption {
         example = { Address = "192.168.0.100/24"; };
         type = types.addCheck (types.attrsOf unitOption) check.network.sectionAddress;
-        description = ''
+        description = lib.mdDoc ''
           Each attribute in this set specifies an option in the
-          <literal>[Address]</literal> section of the unit.  See
-          <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+          `[Address]` section of the unit.  See
+          {manpage}`systemd.network(5)` for details.
         '';
       };
     };
···
         default = { };
         example = { Table = 10; IncomingInterface = "eth1"; Family = "both"; };
         type = types.addCheck (types.attrsOf unitOption) check.network.sectionRoutingPolicyRule;
-        description = ''
+        description = lib.mdDoc ''
           Each attribute in this set specifies an option in the
-          <literal>[RoutingPolicyRule]</literal> section of the unit.  See
-          <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+          `[RoutingPolicyRule]` section of the unit.  See
+          {manpage}`systemd.network(5)` for details.
         '';
       };
     };
···
         default = {};
         example = { Gateway = "192.168.0.1"; };
         type = types.addCheck (types.attrsOf unitOption) check.network.sectionRoute;
-        description = ''
+        description = lib.mdDoc ''
           Each attribute in this set specifies an option in the
-          <literal>[Route]</literal> section of the unit.  See
-          <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+          `[Route]` section of the unit.  See
+          {manpage}`systemd.network(5)` for details.
         '';
       };
     };
···
         default = {};
         example = { Prefix = "fd00::/64"; };
         type = types.addCheck (types.attrsOf unitOption) check.network.sectionIPv6Prefix;
-        description = ''
+        description = lib.mdDoc ''
           Each attribute in this set specifies an option in the
-          <literal>[IPv6Prefix]</literal> section of the unit.  See
-          <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+          `[IPv6Prefix]` section of the unit.  See
+          {manpage}`systemd.network(5)` for details.
         '';
       };
     };
···
         default = {};
         example = { MACAddress = "65:43:4a:5b:d8:5f"; Address = "192.168.1.42"; };
         type = types.addCheck (types.attrsOf unitOption) check.network.sectionDHCPServerStaticLease;
-        description = ''
+        description = lib.mdDoc ''
           Each attribute in this set specifies an option in the
-          <literal>[DHCPServerStaticLease]</literal> section of the unit.  See
-          <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+          `[DHCPServerStaticLease]` section of the unit.  See
+          {manpage}`systemd.network(5)` for details.
 
           Make sure to configure the corresponding client interface to use
-          <literal>ClientIdentifier=mac</literal>.
+          `ClientIdentifier=mac`.
         '';
       };
     };
···
       default = {};
       example = { Unmanaged = true; };
       type = types.addCheck (types.attrsOf unitOption) check.network.sectionLink;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[Link]</literal> section of the unit.  See
-        <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[Link]` section of the unit.  See
+        {manpage}`systemd.network(5)` for details.
       '';
     };
 
···
       default = {};
       example = { Description = "My Network"; };
       type = types.addCheck (types.attrsOf unitOption) check.network.sectionNetwork;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[Network]</literal> section of the unit.  See
-        <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[Network]` section of the unit.  See
+        {manpage}`systemd.network(5)` for details.
       '';
     };
 
···
       default = {};
       example = { UseDNS = true; UseRoutes = true; };
       type = types.addCheck (types.attrsOf unitOption) check.network.sectionDHCPv4;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[DHCPv4]</literal> section of the unit.  See
-        <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[DHCPv4]` section of the unit.  See
+        {manpage}`systemd.network(5)` for details.
       '';
     };
 
···
       default = {};
       example = { UseDNS = true; };
       type = types.addCheck (types.attrsOf unitOption) check.network.sectionDHCPv6;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[DHCPv6]</literal> section of the unit.  See
-        <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[DHCPv6]` section of the unit.  See
+        {manpage}`systemd.network(5)` for details.
       '';
     };
 
···
       default = {};
       example = { SubnetId = "auto"; Announce = true; };
       type = types.addCheck (types.attrsOf unitOption) check.network.sectionDHCPv6PrefixDelegation;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[DHCPv6PrefixDelegation]</literal> section of the unit. See
-        <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[DHCPv6PrefixDelegation]` section of the unit. See
+        {manpage}`systemd.network(5)` for details.
       '';
     };
 
···
       default = {};
       example = { UseDNS = true; DHCPv6Client = "always"; };
       type = types.addCheck (types.attrsOf unitOption) check.network.sectionIPv6AcceptRA;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[IPv6AcceptRA]</literal> section of the unit. See
-        <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[IPv6AcceptRA]` section of the unit. See
+        {manpage}`systemd.network(5)` for details.
       '';
     };
 
···
       default = {};
       example = { PoolOffset = 50; EmitDNS = false; };
       type = types.addCheck (types.attrsOf unitOption) check.network.sectionDHCPServer;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[DHCPServer]</literal> section of the unit.  See
-        <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[DHCPServer]` section of the unit.  See
+        {manpage}`systemd.network(5)` for details.
       '';
     };
 
···
       default = {};
       example = { EmitDNS = true; Managed = true; OtherInformation = true; };
       type = types.addCheck (types.attrsOf unitOption) check.network.sectionIPv6SendRA;
-      description = ''
+      description = lib.mdDoc ''
         Each attribute in this set specifies an option in the
-        <literal>[IPv6SendRA]</literal> section of the unit.  See
-        <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        `[IPv6SendRA]` section of the unit.  See
+        {manpage}`systemd.network(5)` for details.
       '';
     };
 
···
       default = [];
       example = [ { dhcpServerStaticLeaseConfig = { MACAddress = "65:43:4a:5b:d8:5f"; Address = "192.168.1.42"; }; } ];
       type = with types; listOf (submodule dhcpServerStaticLeaseOptions);
-      description = ''
+      description = lib.mdDoc ''
         A list of DHCPServerStaticLease sections to be added to the unit.  See
-        <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        {manpage}`systemd.network(5)` for details.
       '';
     };
 
···
       default = [];
       example = [ { ipv6PrefixConfig = { AddressAutoconfiguration = true; OnLink = true; }; } ];
       type = with types; listOf (submodule ipv6PrefixOptions);
-      description = ''
+      description = lib.mdDoc ''
         A list of ipv6Prefix sections to be added to the unit.  See
-        <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        {manpage}`systemd.network(5)` for details.
       '';
     };
 
···
     address = mkOption {
       default = [ ];
       type = types.listOf types.str;
-      description = ''
+      description = lib.mdDoc ''
         A list of addresses to be added to the network section of the
-        unit.  See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        unit.  See {manpage}`systemd.network(5)` for details.
       '';
     };
 
     gateway = mkOption {
       default = [ ];
       type = types.listOf types.str;
-      description = ''
+      description = lib.mdDoc ''
         A list of gateways to be added to the network section of the
-        unit.  See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        unit.  See {manpage}`systemd.network(5)` for details.
       '';
     };
 
     dns = mkOption {
       default = [ ];
       type = types.listOf types.str;
-      description = ''
+      description = lib.mdDoc ''
         A list of dns servers to be added to the network section of the
-        unit.  See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        unit.  See {manpage}`systemd.network(5)` for details.
       '';
     };
 
     ntp = mkOption {
       default = [ ];
       type = types.listOf types.str;
-      description = ''
+      description = lib.mdDoc ''
         A list of ntp servers to be added to the network section of the
-        unit.  See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        unit.  See {manpage}`systemd.network(5)` for details.
       '';
     };
 
     bridge = mkOption {
       default = [ ];
       type = types.listOf types.str;
-      description = ''
+      description = lib.mdDoc ''
         A list of bridge interfaces to be added to the network section of the
-        unit.  See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        unit.  See {manpage}`systemd.network(5)` for details.
       '';
     };
 
     bond = mkOption {
       default = [ ];
       type = types.listOf types.str;
-      description = ''
+      description = lib.mdDoc ''
         A list of bond interfaces to be added to the network section of the
-        unit.  See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        unit.  See {manpage}`systemd.network(5)` for details.
       '';
     };
 
     vrf = mkOption {
       default = [ ];
       type = types.listOf types.str;
-      description = ''
+      description = lib.mdDoc ''
         A list of vrf interfaces to be added to the network section of the
-        unit.  See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        unit.  See {manpage}`systemd.network(5)` for details.
       '';
     };
 
     vlan = mkOption {
       default = [ ];
       type = types.listOf types.str;
-      description = ''
+      description = lib.mdDoc ''
         A list of vlan interfaces to be added to the network section of the
-        unit.  See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        unit.  See {manpage}`systemd.network(5)` for details.
       '';
     };
 
     macvlan = mkOption {
       default = [ ];
       type = types.listOf types.str;
-      description = ''
+      description = lib.mdDoc ''
         A list of macvlan interfaces to be added to the network section of the
-        unit.  See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        unit.  See {manpage}`systemd.network(5)` for details.
       '';
     };
 
     vxlan = mkOption {
       default = [ ];
       type = types.listOf types.str;
-      description = ''
+      description = lib.mdDoc ''
         A list of vxlan interfaces to be added to the network section of the
-        unit.  See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        unit.  See {manpage}`systemd.network(5)` for details.
       '';
     };
 
     tunnel = mkOption {
       default = [ ];
       type = types.listOf types.str;
-      description = ''
+      description = lib.mdDoc ''
         A list of tunnel interfaces to be added to the network section of the
-        unit.  See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        unit.  See {manpage}`systemd.network(5)` for details.
       '';
     };
 
     xfrm = mkOption {
       default = [ ];
       type = types.listOf types.str;
-      description = ''
+      description = lib.mdDoc ''
         A list of xfrm interfaces to be added to the network section of the
-        unit.  See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        unit.  See {manpage}`systemd.network(5)` for details.
       '';
     };
 
     addresses = mkOption {
       default = [ ];
       type = with types; listOf (submodule addressOptions);
-      description = ''
+      description = lib.mdDoc ''
         A list of address sections to be added to the unit.  See
-        <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        {manpage}`systemd.network(5)` for details.
       '';
     };
 
     routingPolicyRules = mkOption {
       default = [ ];
       type = with types; listOf (submodule routingPolicyRulesOptions);
-      description = ''
+      description = lib.mdDoc ''
         A list of routing policy rules sections to be added to the unit.  See
-        <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        {manpage}`systemd.network(5)` for details.
       '';
     };
 
     routes = mkOption {
       default = [ ];
       type = with types; listOf (submodule routeOptions);
-      description = ''
+      description = lib.mdDoc ''
         A list of route sections to be added to the unit.  See
-        <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+        {manpage}`systemd.network(5)` for details.
       '';
     };
 
···
         default = {};
         example = { foo = 27; };
         type = with types; attrsOf int;
-        description = ''
+        description = lib.mdDoc ''
           Defines route table names as an attrset of name to number.
-          See <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+          See {manpage}`networkd.conf(5)` for details.
         '';
       };
 

nixos/modules/system/boot/systemd/nspawn.nix

···
         default = {};
         example = { Parameters = "/bin/sh"; };
         type = types.addCheck (types.attrsOf unitOption) checkExec;
-        description = ''
+        description = lib.mdDoc ''
           Each attribute in this set specifies an option in the
-          <literal>[Exec]</literal> section of this unit. See
-          <citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+          `[Exec]` section of this unit. See
+          {manpage}`systemd.nspawn(5)` for details.
         '';
       };
 
···
         default = {};
         example = { Bind = [ "/home/alice" ]; };
         type = types.addCheck (types.attrsOf unitOption) checkFiles;
-        description = ''
+        description = lib.mdDoc ''
           Each attribute in this set specifies an option in the
-          <literal>[Files]</literal> section of this unit. See
-          <citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+          `[Files]` section of this unit. See
+          {manpage}`systemd.nspawn(5)` for details.
         '';
       };
 
···
         default = {};
         example = { Private = false; };
         type = types.addCheck (types.attrsOf unitOption) checkNetwork;
-        description = ''
+        description = lib.mdDoc ''
           Each attribute in this set specifies an option in the
-          <literal>[Network]</literal> section of this unit. See
-          <citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
+          `[Network]` section of this unit. See
+          {manpage}`systemd.nspawn(5)` for details.
         '';
       };
     };

nixos/modules/tasks/auto-upgrade.nix

···
         type = types.str;
         default = "04:40";
         example = "daily";
-        description = ''
+        description = lib.mdDoc ''
           How often or when upgrade occurs. For most desktop and server systems
           a sufficient upgrade frequency is once a day.
 
           The format is described in
-          <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+          {manpage}`systemd.time(7)`.
         '';
       };
 
···
         default = "0";
         type = types.str;
         example = "45min";
-        description = ''
+        description = lib.mdDoc ''
           Add a randomized delay before each automatic upgrade.
           The delay will be chosen between zero and this value.
           This value must be a time span in the format specified by
-          <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+          {manpage}`systemd.time(7)`
         '';
       };
 

nixos/modules/tasks/filesystems/btrfs.nix

···
         default = "monthly";
         type = types.str;
         example = "weekly";
-        description = ''
+        description = lib.mdDoc ''
           Systemd calendar expression for when to scrub btrfs filesystems.
           The recommended period is a month but could be less
-          (<citerefentry><refentrytitle>btrfs-scrub</refentrytitle><manvolnum>8</manvolnum></citerefentry>).
+          ({manpage}`btrfs-scrub(8)`).
           See
-          <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+          {manpage}`systemd.time(7)`
           for more information on the syntax.
         '';
       };

nixos/modules/tasks/filesystems/zfs.nix

···
         default = "weekly";
         type = types.str;
         example = "daily";
-        description = ''
+        description = lib.mdDoc ''
           How often we run trim. For most desktop and server systems
           a sufficient trimming frequency is once a week.
 
           The format is described in
-          <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+          {manpage}`systemd.time(7)`.
         '';
       };
     };
···
         default = "Sun, 02:00";
         type = types.str;
         example = "daily";
-        description = ''
+        description = lib.mdDoc ''
           Systemd calendar expression when to scrub ZFS pools. See
-          <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+          {manpage}`systemd.time(7)`.
         '';
       };
 

nixos/modules/tasks/network-interfaces.nix

···
           primary = { port = 9001; local = { address = "192.0.2.1"; dev = "eth0"; }; };
           backup =  { port = 9002; };
         };
-      description = ''
+      description = lib.mdDoc ''
         This option allows you to configure Foo Over UDP and Generic UDP Encapsulation
-        endpoints. See <citerefentry><refentrytitle>ip-fou</refentrytitle><manvolnum>8</manvolnum></citerefentry> for details.
+        endpoints. See {manpage}`ip-fou(8)` for details.
       '';
       type = with types; attrsOf (submodule {
         options = {
···
               options = {
                 type = mkOption {
                   type = enum [ "fou" "gue" ];
-                  description = ''
+                  description = lib.mdDoc ''
                     Selects encapsulation type. See
-                    <citerefentry><refentrytitle>ip-link</refentrytitle><manvolnum>8</manvolnum></citerefentry> for details.
+                    {manpage}`ip-link(8)` for details.
                   '';
                 };
 

nixos/modules/virtualisation/azure-agent.nix

···
   options.virtualisation.azure.agent = {
     enable = mkOption {
       default = false;
-      description = "Whether to enable the Windows Azure Linux Agent.";
+      description = lib.mdDoc "Whether to enable the Windows Azure Linux Agent.";
     };
     verboseLogging = mkOption {
       default = false;
-      description = "Whether to enable verbose logging.";
+      description = lib.mdDoc "Whether to enable verbose logging.";
     };
     mountResourceDisk = mkOption {
       default = true;
-      description = "Whether the agent should format (ext4) and mount the resource disk to /mnt/resource.";
+      description = lib.mdDoc "Whether the agent should format (ext4) and mount the resource disk to /mnt/resource.";
     };
   };
 

nixos/modules/virtualisation/docker.nix

···
       dates = mkOption {
         default = "weekly";
         type = types.str;
-        description = ''
+        description = lib.mdDoc ''
           Specification (in the format described by
-          <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>) of the time at
+          {manpage}`systemd.time(7)`) of the time at
           which the prune will occur.
         '';
       };

nixos/modules/virtualisation/lxc.nix

···
         type = types.lines;
         default = "";
         description =
-          ''
+          lib.mdDoc ''
             This is the system-wide LXC config. See
-            <citerefentry><refentrytitle>lxc.system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+            {manpage}`lxc.system.conf(5)`.
           '';
       };
 
···
         type = types.lines;
         default = "";
         description =
-          ''
+          lib.mdDoc ''
             Default config (default.conf) for new containers, i.e. for
-            network config. See <citerefentry><refentrytitle>lxc.container.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+            network config. See {manpage}`lxc.container.conf(5)`.
           '';
       };
 

nixos/modules/virtualisation/nixos-containers.nix

···
             timeoutStartSec = mkOption {
               type = types.str;
               default = "1min";
-              description = ''
+              description = lib.mdDoc ''
                 Time for the container to start. In case of a timeout,
                 the container processes get killed.
-                See <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+                See {manpage}`systemd.time(7)`
                 for more information about the format.
                '';
             };

nixos/modules/virtualisation/podman/default.nix

···
       mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           This option enables Podman, a daemonless container engine for
           developing, managing, and running OCI Containers on your Linux System.
 
-          It is a drop-in replacement for the <command>docker</command> command.
+          It is a drop-in replacement for the {command}`docker` command.
         '';
       };
 
     dockerSocket.enable = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Make the Podman socket available in place of the Docker socket, so
         Docker tools can find the Podman socket.
 
         Podman implements the Docker API.
 
-        Users must be in the <literal>podman</literal> group in order to connect. As
+        Users must be in the `podman` group in order to connect. As
         with Docker, members of this group can gain root access.
       '';
     };
···
     dockerCompat = mkOption {
       type = types.bool;
       default = false;
-      description = ''
-        Create an alias mapping <command>docker</command> to <command>podman</command>.
+      description = lib.mdDoc ''
+        Create an alias mapping {command}`docker` to {command}`podman`.
       '';
     };
 
     enableNvidia = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Enable use of NVidia GPUs from within podman containers.
       '';
     };
···
           pkgs.gvisor
         ]
       '';
-      description = ''
+      description = lib.mdDoc ''
         Extra packages to be installed in the Podman wrapper.
       '';
     };
···
     defaultNetwork.extraPlugins = lib.mkOption {
       type = types.listOf json.type;
       default = [];
-      description = ''
+      description = lib.mdDoc ''
         Extra CNI plugin configurations to add to podman's default network.
       '';
     };

nixos/modules/virtualisation/podman/network-socket.nix

···
 
     server = mkOption {
       type = types.enum [];
-      description = ''
+      description = lib.mdDoc ''
         Choice of TLS proxy server.
       '';
       example = "ghostunnel";
···
     openFirewall = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether to open the port in the firewall.
       '';
     };
 
     tls.cacert = mkOption {
       type = types.path;
-      description = ''
+      description = lib.mdDoc ''
         Path to CA certificate to use for client authentication.
       '';
     };
 
     tls.cert = mkOption {
       type = types.path;
-      description = ''
+      description = lib.mdDoc ''
         Path to certificate describing the server.
       '';
     };
 
     tls.key = mkOption {
       type = types.path;
-      description = ''
+      description = lib.mdDoc ''
         Path to the private key corresponding to the server certificate.
 
         Use a string for this setting. Otherwise it will be copied to the Nix
···
     port = mkOption {
       type = types.port;
       default = 2376;
-      description = ''
+      description = lib.mdDoc ''
         TCP port number for receiving TLS connections.
       '';
     };
     listenAddress = mkOption {
       type = types.str;
       default = "0.0.0.0";
-      description = ''
+      description = lib.mdDoc ''
         Interface address for receiving TLS connections.
       '';
     };

nixos/modules/virtualisation/qemu-vm.nix

···
 
       file = mkOption {
         type = types.str;
-        description = "The file image used for this drive.";
+        description = lib.mdDoc "The file image used for this drive.";
       };
 
       driveExtraOpts = mkOption {
         type = types.attrsOf types.str;
         default = {};
-        description = "Extra options passed to drive flag.";
+        description = lib.mdDoc "Extra options passed to drive flag.";
       };
 
       deviceExtraOpts = mkOption {
         type = types.attrsOf types.str;
         default = {};
-        description = "Extra options passed to device flag.";
+        description = lib.mdDoc "Extra options passed to device flag.";
       };
 
       name = mkOption {
         type = types.nullOr types.str;
         default = null;
         description =
-          "A name for the drive. Must be unique in the drives list. Not passed to qemu.";
+          lib.mdDoc "A name for the drive. Must be unique in the drives list. Not passed to qemu.";
       };
 
     };
···
         type = types.ints.positive;
         default = 1024;
         description =
-          ''
+          lib.mdDoc ''
             The memory size in megabytes of the virtual machine.
           '';
       };
···
         type = types.ints.positive;
         default = 16384;
         description =
-          ''
+          lib.mdDoc ''
             The msize (maximum packet size) option passed to 9p file systems, in
             bytes. Increasing this should increase performance significantly,
             at the cost of higher RAM usage.
···
         type = types.nullOr types.ints.positive;
         default = 1024;
         description =
-          ''
+          lib.mdDoc ''
             The disk size in megabytes of the virtual machine.
           '';
       };
···
         default = "./${config.system.name}.qcow2";
         defaultText = literalExpression ''"./''${config.system.name}.qcow2"'';
         description =
-          ''
+          lib.mdDoc ''
             Path to the disk image containing the root filesystem.
             The image will be created on startup if it does not
             exist.
···
         type = types.path;
         example = "/dev/vda";
         description =
-          ''
+          lib.mdDoc ''
             The disk to be used for the root filesystem.
           '';
       };
···
         type = types.listOf types.ints.positive;
         default = [];
         description =
-          ''
+          lib.mdDoc ''
             Additional disk images to provide to the VM. The value is
             a list of size in megabytes of each disk. These disks are
             writeable by the VM.
···
         type = types.bool;
         default = true;
         description =
-          ''
+          lib.mdDoc ''
             Whether to run QEMU with a graphics window, or in nographic mode.
             Serial console will be enabled on both settings, but this will
             change the preferred console.
···
         type = options.services.xserver.resolutions.type.nestedTypes.elemType;
         default = { x = 1024; y = 768; };
         description =
-          ''
+          lib.mdDoc ''
             The resolution of the virtual machine display.
           '';
       };
···
         type = types.ints.positive;
         default = 1;
         description =
-          ''
+          lib.mdDoc ''
             Specify the number of cores the guest is permitted to use.
             The number can be higher than the available cores on the
             host system.
···
           (types.submodule {
             options.source = mkOption {
               type = types.str;
-              description = "The path of the directory to share, can be a shell variable";
+              description = lib.mdDoc "The path of the directory to share, can be a shell variable";
             };
             options.target = mkOption {
               type = types.path;
-              description = "The mount point of the directory inside the virtual machine";
+              description = lib.mdDoc "The mount point of the directory inside the virtual machine";
             };
           });
         default = { };
···
           my-share = { source = "/path/to/be/shared"; target = "/mnt/shared"; };
         };
         description =
-          ''
+          lib.mdDoc ''
             An attributes set of directories that will be shared with the
             virtual machine using VirtFS (9P filesystem over VirtIO).
             The attribute name will be used as the 9P mount tag.
···
         type = types.listOf types.path;
         default = [];
         description =
-          ''
+          lib.mdDoc ''
             A list of paths whose closure should be made available to
             the VM.
 
···
             garbage (because they are not registered in the Nix
             database of the guest).
 
-            When <option>virtualisation.useNixStoreImage</option> is
+            When {option}`virtualisation.useNixStoreImage` is
             set, the closure is copied to the Nix store image.
           '';
       };
···
           options.proto = mkOption {
             type = types.enum [ "tcp" "udp" ];
             default = "tcp";
-            description = "The protocol to forward.";
+            description = lib.mdDoc "The protocol to forward.";
           };
           options.host.address = mkOption {
             type = types.str;
             default = "";
-            description = "The IPv4 address of the host.";
+            description = lib.mdDoc "The IPv4 address of the host.";
           };
           options.host.port = mkOption {
             type = types.port;
-            description = "The host port to be mapped.";
+            description = lib.mdDoc "The host port to be mapped.";
           };
           options.guest.address = mkOption {
             type = types.str;
             default = "";
-            description = "The IPv4 address on the guest VLAN.";
+            description = lib.mdDoc "The IPv4 address on the guest VLAN.";
           };
           options.guest.port = mkOption {
             type = types.port;
-            description = "The guest port to be mapped.";
+            description = lib.mdDoc "The guest port to be mapped.";
           };
         });
       default = [];
···
         default = [ 1 ];
         example = [ 1 2 ];
         description =
-          ''
+          lib.mdDoc ''
             Virtual networks to which the VM is connected.  Each
             number «N» in this list causes
             the VM to have a virtual Ethernet interface attached to a
             separate virtual network on which it will be assigned IP
             address
-            <literal>192.168.«N».«M»</literal>,
+            `192.168.«N».«M»`,
             where «M» is the index of this VM
             in the list of VMs.
           '';
···
         type = types.bool;
         default = true; # FIXME
         description =
-          ''
+          lib.mdDoc ''
             If enabled, the Nix store in the VM is made writable by
             layering an overlay filesystem on top of the host's Nix
             store.
···
         type = types.bool;
         default = true;
         description =
-          ''
+          lib.mdDoc ''
             Use a tmpfs for the writable store instead of writing to the VM's
             own filesystem.
           '';
···
           type = types.package;
           default = pkgs.qemu_kvm;
           example = "pkgs.qemu_test";
-          description = "QEMU package to use.";
+          description = lib.mdDoc "QEMU package to use.";
         };
 
       options =
···
           type = types.listOf types.str;
           default = [];
           example = [ "-vga std" ];
-          description = "Options passed to QEMU.";
+          description = lib.mdDoc "Options passed to QEMU.";
         };
 
       consoles = mkOption {
···
           consoles = [ "${qemu-common.qemuSerialDevice},115200n8" "tty0" ];
         in if cfg.graphics then consoles else reverseList consoles;
         example = [ "console=tty1" ];
-        description = ''
+        description = lib.mdDoc ''
           The output console devices to pass to the kernel command line via the
-          <literal>console</literal> parameter, the primary console is the last
+          `console` parameter, the primary console is the last
           item of this list.
 
           By default it enables both serial console and
-          <literal>tty0</literal>. The preferred console (last one) is based on
-          the value of <option>virtualisation.graphics</option>.
+          `tty0`. The preferred console (last one) is based on
+          the value of {option}`virtualisation.graphics`.
         '';
       };
 
···
             "-net nic,netdev=user.0,model=virtio"
             "-netdev user,id=user.0,\${QEMU_NET_OPTS:+,$QEMU_NET_OPTS}"
           ];
-          description = ''
+          description = lib.mdDoc ''
             Networking-related command-line options that should be passed to qemu.
             The default is to use userspace networking (SLiRP).
 
···
       drives =
         mkOption {
           type = types.listOf (types.submodule driveOpts);
-          description = "Drives passed to qemu.";
+          description = lib.mdDoc "Drives passed to qemu.";
           apply = addDeviceNames;
         };
 
···
           type = types.enum [ "virtio" "scsi" "ide" ];
           default = "virtio";
           example = "scsi";
-          description = "The interface used for the virtual hard disks.";
+          description = lib.mdDoc "The interface used for the virtual hard disks.";
         };
 
       guestAgent.enable =
         mkOption {
           type = types.bool;
           default = true;
-          description = ''
+          description = lib.mdDoc ''
             Enable the Qemu guest agent.
           '';
         };
···
         mkOption {
           type = types.bool;
           default = true;
-          description = ''
+          description = lib.mdDoc ''
             Enable the virtio-keyboard device.
           '';
         };
···
       mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Build and use a disk image for the Nix store, instead of
           accessing the host's one through 9p.
 
···
         type = types.bool;
         default = false;
         description =
-          ''
+          lib.mdDoc ''
             If enabled, the virtual machine will be booted using the
             regular boot loader (i.e., GRUB 1 or 2).  This allows
             testing of the boot loader.  If
···
         type = types.bool;
         default = false;
         description =
-          ''
+          lib.mdDoc ''
             If enabled, the virtual machine will provide a EFI boot
             manager.
             useEFIBoot is ignored if useBootLoader == false.
···
         type = types.bool;
         default = true;
         description =
-          ''
+          lib.mdDoc ''
             If enabled, the boot disk of the virtual machine will be
             formatted and mounted with the default filesystems for
             testing. Swap devices and LUKS will be disabled.
···
         default = "./${config.system.name}-efi-vars.fd";
         defaultText = literalExpression ''"./''${config.system.name}-efi-vars.fd"'';
         description =
-          ''
+          lib.mdDoc ''
             Path to nvram image containing UEFI variables.  The will be created
             on startup if it does not exist.
           '';