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

treewide: automatically md-convert option descriptions

16 files changed, 247 insertions, 247 deletions

diff --git a/nixos/modules/security/acme/default.nix b/nixos/modules/security/acme/default.nix
index d827c448055b7..54b44dcab62be 100644
--- a/nixos/modules/security/acme/default.nix
+++ b/nixos/modules/security/acme/default.nix
@@ -445,7 +445,7 @@ let
       validMinDays = mkOption {
         type = types.int;
         inherit (defaultAndText "validMinDays" 30) default defaultText;
-        description = "Minimum remaining validity before renewal in days.";
+        description = lib.mdDoc "Minimum remaining validity before renewal in days.";
       };
 
       renewInterval = mkOption {
@@ -466,11 +466,11 @@ let
         type = types.nullOr types.str;
         inherit (defaultAndText "webroot" null) default defaultText;
         example = "/var/lib/acme/acme-challenge";
-        description = ''
+        description = lib.mdDoc ''
           Where the webroot of the HTTP vhost is located.
-          <filename>.well-known/acme-challenge/</filename> directory
+          {file}`.well-known/acme-challenge/` directory
           will be created below the webroot if it doesn't exist.
-          <literal>http://example.org/.well-known/acme-challenge/</literal> must also
+          `http://example.org/.well-known/acme-challenge/` must also
           be available (notice unencrypted HTTP).
         '';
       };
@@ -478,17 +478,17 @@ let
       server = mkOption {
         type = types.nullOr types.str;
         inherit (defaultAndText "server" null) default defaultText;
-        description = ''
+        description = lib.mdDoc ''
           ACME Directory Resource URI. Defaults to Let's Encrypt's
           production endpoint,
-          <link xlink:href="https://acme-v02.api.letsencrypt.org/directory"/>, if unset.
+          <https://acme-v02.api.letsencrypt.org/directory>, if unset.
         '';
       };
 
       email = mkOption {
         type = types.str;
         inherit (defaultAndText "email" null) default defaultText;
-        description = ''
+        description = lib.mdDoc ''
           Email address for account creation and correspondence from the CA.
           It is recommended to use the same email for all certs to avoid account
           creation limits.
@@ -498,7 +498,7 @@ let
       group = mkOption {
         type = types.str;
         inherit (defaultAndText "group" "acme") default defaultText;
-        description = "Group running the ACME client.";
+        description = lib.mdDoc "Group running the ACME client.";
       };
 
       reloadServices = mkOption {
@@ -514,7 +514,7 @@ let
         type = types.lines;
         inherit (defaultAndText "postRun" "") default defaultText;
         example = "cp full.pem backup.pem";
-        description = ''
+        description = lib.mdDoc ''
           Commands to run after new certificates go live. Note that
           these commands run as the root user.
 
@@ -525,10 +525,10 @@ let
       keyType = mkOption {
         type = types.str;
         inherit (defaultAndText "keyType" "ec256") default defaultText;
-        description = ''
+        description = lib.mdDoc ''
           Key type to use for private keys.
           For an up to date list of supported values check the --key-type option
-          at <link xlink:href="https://go-acme.github.io/lego/usage/cli/#usage"/>.
+          at <https://go-acme.github.io/lego/usage/cli/#usage>.
         '';
       };
 
@@ -536,9 +536,9 @@ let
         type = types.nullOr types.str;
         inherit (defaultAndText "dnsProvider" null) default defaultText;
         example = "route53";
-        description = ''
+        description = lib.mdDoc ''
           DNS Challenge provider. For a list of supported providers, see the "code"
-          field of the DNS providers listed at <link xlink:href="https://go-acme.github.io/lego/dns/"/>.
+          field of the DNS providers listed at <https://go-acme.github.io/lego/dns/>.
         '';
       };
 
@@ -546,7 +546,7 @@ let
         type = types.nullOr types.str;
         inherit (defaultAndText "dnsResolver" null) default defaultText;
         example = "1.1.1.1:53";
-        description = ''
+        description = lib.mdDoc ''
           Set the resolver to use for performing recursive DNS queries. Supported:
           host:port. The default is to use the system resolvers, or Google's DNS
           resolvers if the system's cannot be determined.
@@ -556,11 +556,11 @@ let
       credentialsFile = mkOption {
         type = types.path;
         inherit (defaultAndText "credentialsFile" null) default defaultText;
-        description = ''
+        description = lib.mdDoc ''
           Path to an EnvironmentFile for the cert's service containing any required and
           optional environment variables for your selected dnsProvider.
           To find out what values you need to set, consult the documentation at
-          <link xlink:href="https://go-acme.github.io/lego/dns/"/> for the corresponding dnsProvider.
+          <https://go-acme.github.io/lego/dns/> for the corresponding dnsProvider.
         '';
         example = "/var/src/secrets/example.org-route53-api-token";
       };
@@ -568,7 +568,7 @@ let
       dnsPropagationCheck = mkOption {
         type = types.bool;
         inherit (defaultAndText "dnsPropagationCheck" true) default defaultText;
-        description = ''
+        description = lib.mdDoc ''
           Toggles lego DNS propagation check, which is used alongside DNS-01
           challenge to ensure the DNS entries required are available.
         '';
@@ -590,7 +590,7 @@ let
       extraLegoFlags = mkOption {
         type = types.listOf types.str;
         inherit (defaultAndText "extraLegoFlags" []) default defaultText;
-        description = ''
+        description = lib.mdDoc ''
           Additional global flags to pass to all lego commands.
         '';
       };
@@ -598,7 +598,7 @@ let
       extraLegoRenewFlags = mkOption {
         type = types.listOf types.str;
         inherit (defaultAndText "extraLegoRenewFlags" []) default defaultText;
-        description = ''
+        description = lib.mdDoc ''
           Additional flags to pass to lego renew.
         '';
       };
@@ -606,7 +606,7 @@ let
       extraLegoRunFlags = mkOption {
         type = types.listOf types.str;
         inherit (defaultAndText "extraLegoRunFlags" []) default defaultText;
-        description = ''
+        description = lib.mdDoc ''
           Additional flags to pass to lego run.
         '';
       };
@@ -637,13 +637,13 @@ let
         type = types.str;
         readOnly = true;
         default = "/var/lib/acme/${name}";
-        description = "Directory where certificate and other state is stored.";
+        description = lib.mdDoc "Directory where certificate and other state is stored.";
       };
 
       domain = mkOption {
         type = types.str;
         default = name;
-        description = "Domain to fetch certificate for (defaults to the entry name).";
+        description = lib.mdDoc "Domain to fetch certificate for (defaults to the entry name).";
       };
 
       extraDomainNames = mkOption {
@@ -655,7 +655,7 @@ let
             "mydomain.org"
           ]
         '';
-        description = ''
+        description = lib.mdDoc ''
           A list of extra domain names, which are included in the one certificate to be issued.
         '';
       };
@@ -667,7 +667,7 @@ let
         type = types.nullOr types.str;
         default = null;
         example = ":1360";
-        description = ''
+        description = lib.mdDoc ''
           Interface and port to listen on to solve HTTP challenges
           in the form [INTERFACE]:PORT.
           If you use a port other than 80, you must proxy port 80 to this port.
@@ -690,7 +690,7 @@ in {
       preliminarySelfsigned = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Whether a preliminary self-signed certificate should be generated before
           doing ACME requests. This can be useful when certificates are required in
           a webserver, but ACME needs the webserver to make its requests.
@@ -703,16 +703,16 @@ in {
       acceptTerms = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Accept the CA's terms of service. The default provider is Let's Encrypt,
-          you can find their ToS at <link xlink:href="https://letsencrypt.org/repository/"/>.
+          you can find their ToS at <https://letsencrypt.org/repository/>.
         '';
       };
 
       useRoot = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to use the root user when generating certs. This is not recommended
           for security + compatiblity reasons. If a service requires root owned certificates
           consider following the guide on "Using ACME with services demanding root
@@ -723,7 +723,7 @@ in {
 
       defaults = mkOption {
         type = types.submodule (inheritableModule true);
-        description = ''
+        description = lib.mdDoc ''
           Default values inheritable by all configured certs. You can
           use this to define options shared by all your certs. These defaults
           can also be ignored on a per-cert basis using the
@@ -734,9 +734,9 @@ in {
       certs = mkOption {
         default = { };
         type = with types; attrsOf (submodule [ (inheritableModule false) certOpts ]);
-        description = ''
+        description = lib.mdDoc ''
           Attribute set of certificates to get signed and renewed. Creates
-          <literal>acme-''${cert}.{service,timer}</literal> systemd units for
+          `acme-''${cert}.{service,timer}` systemd units for
           each certificate defined here. Other services can add dependencies
           to those units if they rely on the certificates being present,
           or trigger restarts of the service if certificates get renewed.
diff --git a/nixos/modules/security/audit.nix b/nixos/modules/security/audit.nix
index 2b22bdd9f0ae6..06b4766c8f5a9 100644
--- a/nixos/modules/security/audit.nix
+++ b/nixos/modules/security/audit.nix
@@ -56,7 +56,7 @@ in {
       enable = mkOption {
         type        = types.enum [ false true "lock" ];
         default     = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable the Linux audit system. The special `lock' value can be used to
           enable auditing and prevent disabling it until a restart. Be careful about locking
           this, as it will prevent you from changing your audit configuration until you
@@ -67,13 +67,13 @@ in {
       failureMode = mkOption {
         type        = types.enum [ "silent" "printk" "panic" ];
         default     = "printk";
-        description = "How to handle critical errors in the auditing system";
+        description = lib.mdDoc "How to handle critical errors in the auditing system";
       };
 
       backlogLimit = mkOption {
         type        = types.int;
         default     = 64; # Apparently the kernel default
-        description = ''
+        description = lib.mdDoc ''
           The maximum number of outstanding audit buffers allowed; exceeding this is
           considered a failure and handled in a manner specified by failureMode.
         '';
@@ -82,7 +82,7 @@ in {
       rateLimit = mkOption {
         type        = types.int;
         default     = 0;
-        description = ''
+        description = lib.mdDoc ''
           The maximum messages per second permitted before triggering a failure as
           specified by failureMode. Setting it to zero disables the limit.
         '';
@@ -92,7 +92,7 @@ in {
         type        = types.listOf types.str; # (types.either types.str (types.submodule rule));
         default     = [];
         example     = [ "-a exit,always -F arch=b64 -S execve" ];
-        description = ''
+        description = lib.mdDoc ''
           The ordered audit rules, with each string appearing as one line of the audit.rules file.
         '';
       };
diff --git a/nixos/modules/security/ca.nix b/nixos/modules/security/ca.nix
index f71d9d90ec5b8..c704e2c1f51c3 100644
--- a/nixos/modules/security/ca.nix
+++ b/nixos/modules/security/ca.nix
@@ -23,12 +23,12 @@ in
       type = types.listOf types.path;
       default = [];
       example = literalExpression ''[ "''${pkgs.cacert}/etc/ssl/certs/ca-bundle.crt" ]'';
-      description = ''
+      description = lib.mdDoc ''
         A list of files containing trusted root certificates in PEM
         format. These are concatenated to form
-        <filename>/etc/ssl/certs/ca-certificates.crt</filename>, which is
+        {file}`/etc/ssl/certs/ca-certificates.crt`, which is
         used by many programs that use OpenSSL, such as
-        <command>curl</command> and <command>git</command>.
+        {command}`curl` and {command}`git`.
       '';
     };
 
@@ -47,7 +47,7 @@ in
           '''
         ]
       '';
-      description = ''
+      description = lib.mdDoc ''
         A list of trusted root certificates in PEM format.
       '';
     };
@@ -60,10 +60,10 @@ in
         "CA WoSign ECC Root"
         "Certification Authority of WoSign G2"
       ];
-      description = ''
+      description = lib.mdDoc ''
         A list of blacklisted CA certificate names that won't be imported from
         the Mozilla Trust Store into
-        <filename>/etc/ssl/certs/ca-certificates.crt</filename>. Use the
+        {file}`/etc/ssl/certs/ca-certificates.crt`. Use the
         names from that file.
       '';
     };
diff --git a/nixos/modules/security/chromium-suid-sandbox.nix b/nixos/modules/security/chromium-suid-sandbox.nix
index bb99c053f7185..cab4b9f8d3abf 100644
--- a/nixos/modules/security/chromium-suid-sandbox.nix
+++ b/nixos/modules/security/chromium-suid-sandbox.nix
@@ -14,7 +14,7 @@ in
   options.security.chromiumSuidSandbox.enable = mkOption {
     type = types.bool;
     default = false;
-    description = ''
+    description = lib.mdDoc ''
       Whether to install the Chromium SUID sandbox which is an executable that
       Chromium may use in order to achieve sandboxing.
 
diff --git a/nixos/modules/security/dhparams.nix b/nixos/modules/security/dhparams.nix
index cfa9003f12fb6..720936e68d72a 100644
--- a/nixos/modules/security/dhparams.nix
+++ b/nixos/modules/security/dhparams.nix
@@ -15,7 +15,7 @@ let
       type = bitType;
       default = cfg.defaultBitSize;
       defaultText = literalExpression "config.${opt.defaultBitSize}";
-      description = ''
+      description = lib.mdDoc ''
         The bit size for the prime that is used during a Diffie-Hellman
         key exchange.
       '';
@@ -24,11 +24,11 @@ let
     options.path = mkOption {
       type = types.path;
       readOnly = true;
-      description = ''
+      description = lib.mdDoc ''
         The resulting path of the generated Diffie-Hellman parameters
         file for other services to reference. This could be either a
         store path or a file inside the directory specified by
-        <option>security.dhparams.path</option>.
+        {option}`security.dhparams.path`.
       '';
     };
 
@@ -45,7 +45,7 @@ in {
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to generate new DH params and clean up old DH params.
         '';
       };
@@ -101,21 +101,21 @@ in {
       defaultBitSize = mkOption {
         type = bitType;
         default = 2048;
-        description = ''
+        description = lib.mdDoc ''
           This allows to override the default bit size for all of the
           Diffie-Hellman parameters set in
-          <option>security.dhparams.params</option>.
+          {option}`security.dhparams.params`.
         '';
       };
 
       path = mkOption {
         type = types.str;
         default = "/var/lib/dhparams";
-        description = ''
+        description = lib.mdDoc ''
           Path to the directory in which Diffie-Hellman parameters will be
           stored. This only is relevant if
-          <option>security.dhparams.stateful</option> is
-          <literal>true</literal>.
+          {option}`security.dhparams.stateful` is
+          `true`.
         '';
       };
     };
diff --git a/nixos/modules/security/doas.nix b/nixos/modules/security/doas.nix
index 2a814f17e454f..d4b51b406e288 100644
--- a/nixos/modules/security/doas.nix
+++ b/nixos/modules/security/doas.nix
@@ -53,8 +53,8 @@ in
     enable = mkOption {
       type = with types; bool;
       default = false;
-      description = ''
-        Whether to enable the <command>doas</command> command, which allows
+      description = lib.mdDoc ''
+        Whether to enable the {command}`doas` command, which allows
         non-root users to execute commands as root.
       '';
     };
@@ -171,13 +171,13 @@ in
             users = mkOption {
               type = with types; listOf (either str int);
               default = [];
-              description = "The usernames / UIDs this rule should apply for.";
+              description = lib.mdDoc "The usernames / UIDs this rule should apply for.";
             };
 
             groups = mkOption {
               type = with types; listOf (either str int);
               default = [];
-              description = "The groups / GIDs this rule should apply for.";
+              description = lib.mdDoc "The groups / GIDs this rule should apply for.";
             };
 
             runAs = mkOption {
@@ -223,8 +223,8 @@ in
     extraConfig = mkOption {
       type = with types; lines;
       default = "";
-      description = ''
-        Extra configuration text appended to <filename>doas.conf</filename>.
+      description = lib.mdDoc ''
+        Extra configuration text appended to {file}`doas.conf`.
       '';
     };
   };
diff --git a/nixos/modules/security/duosec.nix b/nixos/modules/security/duosec.nix
index bbe246fe229ec..02b11766b3c09 100644
--- a/nixos/modules/security/duosec.nix
+++ b/nixos/modules/security/duosec.nix
@@ -36,24 +36,24 @@ in
       ssh.enable = mkOption {
         type = types.bool;
         default = false;
-        description = "If enabled, protect SSH logins with Duo Security.";
+        description = lib.mdDoc "If enabled, protect SSH logins with Duo Security.";
       };
 
       pam.enable = mkOption {
         type = types.bool;
         default = false;
-        description = "If enabled, protect logins with Duo Security using PAM support.";
+        description = lib.mdDoc "If enabled, protect logins with Duo Security using PAM support.";
       };
 
       integrationKey = mkOption {
         type = types.str;
-        description = "Integration key.";
+        description = lib.mdDoc "Integration key.";
       };
 
       secretKeyFile = mkOption {
         type = types.nullOr types.path;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           A file containing your secret key. The security of your Duo application is tied to the security of your secret key.
         '';
         example = "/run/keys/duo-skey";
@@ -61,25 +61,25 @@ in
 
       host = mkOption {
         type = types.str;
-        description = "Duo API hostname.";
+        description = lib.mdDoc "Duo API hostname.";
       };
 
       groups = mkOption {
         type = types.str;
         default = "";
         example = "users,!wheel,!*admin guests";
-        description = ''
+        description = lib.mdDoc ''
           If specified, Duo authentication is required only for users
           whose primary group or supplementary group list matches one
           of the space-separated pattern lists. Refer to
-          <link xlink:href="https://duo.com/docs/duounix"/> for details.
+          <https://duo.com/docs/duounix> for details.
         '';
       };
 
       failmode = mkOption {
         type = types.enum [ "safe" "secure" ];
         default = "safe";
-        description = ''
+        description = lib.mdDoc ''
           On service or configuration errors that prevent Duo
           authentication, fail "safe" (allow access) or "secure" (deny
           access). The default is "safe".
@@ -89,7 +89,7 @@ in
       pushinfo = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Include information such as the command to be executed in
           the Duo Push message.
         '';
@@ -98,22 +98,22 @@ in
       autopush = mkOption {
         type = types.bool;
         default = false;
-        description = ''
-          If <literal>true</literal>, Duo Unix will automatically send
+        description = lib.mdDoc ''
+          If `true`, Duo Unix will automatically send
           a push login request to the user’s phone, falling back on a
           phone call if push is unavailable. If
-          <literal>false</literal>, the user will be prompted to
+          `false`, the user will be prompted to
           choose an authentication method. When configured with
-          <literal>autopush = yes</literal>, we recommend setting
-          <literal>prompts = 1</literal>.
+          `autopush = yes`, we recommend setting
+          `prompts = 1`.
         '';
       };
 
       motd = mkOption {
         type = types.bool;
         default = false;
-        description = ''
-          Print the contents of <literal>/etc/motd</literal> to screen
+        description = lib.mdDoc ''
+          Print the contents of `/etc/motd` to screen
           after a successful login.
         '';
       };
@@ -121,30 +121,30 @@ in
       prompts = mkOption {
         type = types.enum [ 1 2 3 ];
         default = 3;
-        description = ''
+        description = lib.mdDoc ''
           If a user fails to authenticate with a second factor, Duo
           Unix will prompt the user to authenticate again. This option
           sets the maximum number of prompts that Duo Unix will
           display before denying access. Must be 1, 2, or 3. Default
           is 3.
 
-          For example, when <literal>prompts = 1</literal>, the user
+          For example, when `prompts = 1`, the user
           will have to successfully authenticate on the first prompt,
-          whereas if <literal>prompts = 2</literal>, if the user
+          whereas if `prompts = 2`, if the user
           enters incorrect information at the initial prompt, he/she
           will be prompted to authenticate again.
 
-          When configured with <literal>autopush = true</literal>, we
-          recommend setting <literal>prompts = 1</literal>.
+          When configured with `autopush = true`, we
+          recommend setting `prompts = 1`.
         '';
       };
 
       acceptEnvFactor = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Look for factor selection or passcode in the
-          <literal>$DUO_PASSCODE</literal> environment variable before
+          `$DUO_PASSCODE` environment variable before
           prompting the user for input.
 
           When $DUO_PASSCODE is non-empty, it will override
@@ -157,11 +157,11 @@ in
       fallbackLocalIP = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Duo Unix reports the IP address of the authorizing user, for
           the purposes of authorization and whitelisting. If Duo Unix
           cannot detect the IP address of the client, setting
-          <literal>fallbackLocalIP = yes</literal> will cause Duo Unix
+          `fallbackLocalIP = yes` will cause Duo Unix
           to send the IP address of the server it is running on.
 
           If you are using IP whitelisting, enabling this option could
@@ -173,7 +173,7 @@ in
       allowTcpForwarding = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           By default, when SSH forwarding, enabling Duo Security will
           disable TCP forwarding. By enabling this, you potentially
           undermine some of the SSH based login security. Note this is
diff --git a/nixos/modules/security/google_oslogin.nix b/nixos/modules/security/google_oslogin.nix
index cf416035ef60c..f75b4df1851a5 100644
--- a/nixos/modules/security/google_oslogin.nix
+++ b/nixos/modules/security/google_oslogin.nix
@@ -16,7 +16,7 @@ in
     security.googleOsLogin.enable = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable Google OS Login.
 
         The OS Login package enables the following components:
diff --git a/nixos/modules/security/misc.nix b/nixos/modules/security/misc.nix
index c20e067b8cc78..3c83ff8d77397 100644
--- a/nixos/modules/security/misc.nix
+++ b/nixos/modules/security/misc.nix
@@ -15,7 +15,7 @@ with lib;
     security.allowUserNamespaces = mkOption {
       type = types.bool;
       default = true;
-      description = ''
+      description = lib.mdDoc ''
         Whether to allow creation of user namespaces.
 
         The motivation for disabling user namespaces is the potential
@@ -34,7 +34,7 @@ with lib;
     security.unprivilegedUsernsClone = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         When disabled, unprivileged users will not be able to create new namespaces.
         By default unprivileged user namespaces are disabled.
         This option only works in a hardened profile.
@@ -44,7 +44,7 @@ with lib;
     security.protectKernelImage = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether to prevent replacing the running kernel image.
       '';
     };
@@ -71,7 +71,7 @@ with lib;
     security.forcePageTableIsolation = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether to force-enable the Page Table Isolation (PTI) Linux kernel
         feature even on CPU models that claim to be safe from Meltdown.
 
diff --git a/nixos/modules/security/oath.nix b/nixos/modules/security/oath.nix
index 93bdc851117ae..3342866538464 100644
--- a/nixos/modules/security/oath.nix
+++ b/nixos/modules/security/oath.nix
@@ -11,7 +11,7 @@ with lib;
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Enable the OATH (one-time password) PAM module.
         '';
       };
@@ -19,7 +19,7 @@ with lib;
       digits = mkOption {
         type = types.enum [ 6 7 8 ];
         default = 6;
-        description = ''
+        description = lib.mdDoc ''
           Specify the length of the one-time password in number of
           digits.
         '';
@@ -28,7 +28,7 @@ with lib;
       window = mkOption {
         type = types.int;
         default = 5;
-        description = ''
+        description = lib.mdDoc ''
           Specify the number of one-time passwords to check in order
           to accommodate for situations where the system and the
           client are slightly out of sync (iteration for HOTP or time
@@ -39,7 +39,7 @@ with lib;
       usersFile = mkOption {
         type = types.path;
         default = "/etc/users.oath";
-        description = ''
+        description = lib.mdDoc ''
           Set the path to file where the user's credentials are
           stored. This file must not be world readable!
         '';
diff --git a/nixos/modules/security/pam.nix b/nixos/modules/security/pam.nix
index 16f4193d3bcec..7903d333411bd 100644
--- a/nixos/modules/security/pam.nix
+++ b/nixos/modules/security/pam.nix
@@ -15,24 +15,24 @@ let
       name = mkOption {
         example = "sshd";
         type = types.str;
-        description = "Name of the PAM service.";
+        description = lib.mdDoc "Name of the PAM service.";
       };
 
       unixAuth = mkOption {
         default = true;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Whether users can log in with passwords defined in
-          <filename>/etc/shadow</filename>.
+          {file}`/etc/shadow`.
         '';
       };
 
       rootOK = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           If set, root doesn't need to authenticate (e.g. for the
-          <command>useradd</command> service).
+          {command}`useradd` service).
         '';
       };
 
@@ -40,10 +40,10 @@ let
         default = config.security.pam.p11.enable;
         defaultText = literalExpression "config.security.pam.p11.enable";
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           If set, keys listed in
-          <filename>~/.ssh/authorized_keys</filename> and
-          <filename>~/.eid/authorized_certificates</filename>
+          {file}`~/.ssh/authorized_keys` and
+          {file}`~/.eid/authorized_certificates`
           can be used to log in with the associated PKCS#11 tokens.
         '';
       };
@@ -52,24 +52,24 @@ let
         default = config.security.pam.u2f.enable;
         defaultText = literalExpression "config.security.pam.u2f.enable";
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           If set, users listed in
-          <filename>$XDG_CONFIG_HOME/Yubico/u2f_keys</filename> (or
-          <filename>$HOME/.config/Yubico/u2f_keys</filename> if XDG variable is
+          {file}`$XDG_CONFIG_HOME/Yubico/u2f_keys` (or
+          {file}`$HOME/.config/Yubico/u2f_keys` if XDG variable is
           not set) are able to log in with the associated U2F key. Path can be
-          changed using <option>security.pam.u2f.authFile</option> option.
+          changed using {option}`security.pam.u2f.authFile` option.
         '';
       };
 
       usshAuth = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           If set, users with an SSH certificate containing an authorized principal
           in their SSH agent are able to log in. Specific options are controlled
-          using the <option>security.pam.ussh</option> options.
+          using the {option}`security.pam.ussh` options.
 
-          Note that the  <option>security.pam.ussh.enable</option> must also be
+          Note that the  {option}`security.pam.ussh.enable` must also be
           set for this option to take effect.
         '';
       };
@@ -78,9 +78,9 @@ let
         default = config.security.pam.yubico.enable;
         defaultText = literalExpression "config.security.pam.yubico.enable";
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           If set, users listed in
-          <filename>~/.yubico/authorized_yubikeys</filename>
+          {file}`~/.yubico/authorized_yubikeys`
           are able to log in with the associated Yubikey tokens.
         '';
       };
@@ -89,9 +89,9 @@ let
         enable = mkOption {
           default = false;
           type = types.bool;
-          description = ''
+          description = lib.mdDoc ''
             If set, users with enabled Google Authenticator (created
-            <filename>~/.google_authenticator</filename>) will be required
+            {file}`~/.google_authenticator`) will be required
             to provide Google Authenticator token to log in.
           '';
         };
@@ -101,9 +101,9 @@ let
         default = config.security.pam.usb.enable;
         defaultText = literalExpression "config.security.pam.usb.enable";
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           If set, users listed in
-          <filename>/etc/pamusb.conf</filename> are able to log in
+          {file}`/etc/pamusb.conf` are able to log in
           with the associated USB key.
         '';
       };
@@ -112,21 +112,21 @@ let
         default = config.security.pam.enableOTPW;
         defaultText = literalExpression "config.security.pam.enableOTPW";
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           If set, the OTPW system will be used (if
-          <filename>~/.otpw</filename> exists).
+          {file}`~/.otpw` exists).
         '';
       };
 
       googleOsLoginAccountVerification = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           If set, will use the Google OS Login PAM modules
-          (<literal>pam_oslogin_login</literal>,
-          <literal>pam_oslogin_admin</literal>) to verify possible OS Login
+          (`pam_oslogin_login`,
+          `pam_oslogin_admin`) to verify possible OS Login
           users and set sudoers configuration accordingly.
-          This only makes sense to enable for the <literal>sshd</literal> PAM
+          This only makes sense to enable for the `sshd` PAM
           service.
         '';
       };
@@ -134,10 +134,10 @@ let
       googleOsLoginAuthentication = mkOption {
         default = false;
         type = types.bool;
-        description = ''
-          If set, will use the <literal>pam_oslogin_login</literal>'s user
+        description = lib.mdDoc ''
+          If set, will use the `pam_oslogin_login`'s user
           authentication methods to authenticate users using 2FA.
-          This only makes sense to enable for the <literal>sshd</literal> PAM
+          This only makes sense to enable for the `sshd` PAM
           service.
         '';
       };
@@ -146,7 +146,7 @@ let
         default = config.services.fprintd.enable;
         defaultText = literalExpression "config.services.fprintd.enable";
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           If set, fingerprint reader will be used (if exists and
           your fingerprints are enrolled).
         '';
@@ -156,7 +156,7 @@ let
         default = config.security.pam.oath.enable;
         defaultText = literalExpression "config.security.pam.oath.enable";
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           If set, the OATH Toolkit will be used.
         '';
       };
@@ -164,11 +164,11 @@ let
       sshAgentAuth = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           If set, the calling user's SSH agent is used to authenticate
           against the keys in the calling user's
-          <filename>~/.ssh/authorized_keys</filename>.  This is useful
-          for <command>sudo</command> on password-less remote systems.
+          {file}`~/.ssh/authorized_keys`.  This is useful
+          for {command}`sudo` on password-less remote systems.
         '';
       };
 
@@ -176,10 +176,10 @@ let
         enable = mkOption {
           default = false;
           type = types.bool;
-          description = ''
+          description = lib.mdDoc ''
             If set, use the Duo Security pam module
-            <literal>pam_duo</literal> for authentication.  Requires
-            configuration of <option>security.duosec</option> options.
+            `pam_duo` for authentication.  Requires
+            configuration of {option}`security.duosec` options.
           '';
         };
       };
@@ -187,7 +187,7 @@ let
       startSession = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           If set, the service will register a new session with
           systemd's login manager.  For local sessions, this will give
           the user access to audio devices, CD-ROM drives.  In the
@@ -199,21 +199,21 @@ let
       setEnvironment = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Whether the service should set the environment variables
-          listed in <option>environment.sessionVariables</option>
-          using <literal>pam_env.so</literal>.
+          listed in {option}`environment.sessionVariables`
+          using `pam_env.so`.
         '';
       };
 
       setLoginUid = mkOption {
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Set the login uid of the process
-          (<filename>/proc/self/loginuid</filename>) for auditing
+          ({file}`/proc/self/loginuid`) for auditing
           purposes.  The login uid is only set by ‘entry points’ like
-          <command>login</command> and <command>sshd</command>, not by
-          commands like <command>sudo</command>.
+          {command}`login` and {command}`sshd`, not by
+          commands like {command}`sudo`.
         '';
       };
 
@@ -221,7 +221,7 @@ let
         enable = mkOption {
           type = types.bool;
           default = false;
-          description = ''
+          description = lib.mdDoc ''
             Enable or disable TTY auditing for specified users
           '';
         };
@@ -229,7 +229,7 @@ let
         enablePattern = mkOption {
           type = types.nullOr types.str;
           default = null;
-          description = ''
+          description = lib.mdDoc ''
             For each user matching one of comma-separated
             glob patterns, enable TTY auditing
           '';
@@ -238,7 +238,7 @@ let
         disablePattern = mkOption {
           type = types.nullOr types.str;
           default = null;
-          description = ''
+          description = lib.mdDoc ''
             For each user matching one of comma-separated
             glob patterns, disable TTY auditing
           '';
@@ -247,7 +247,7 @@ let
         openOnly = mkOption {
           type = types.bool;
           default = false;
-          description = ''
+          description = lib.mdDoc ''
             Set the TTY audit flag when opening the session,
             but do not restore it when closing the session.
             Using this option is necessary for some services
@@ -260,10 +260,10 @@ let
       forwardXAuth = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Whether X authentication keys should be passed from the
           calling user to the target user (e.g. for
-          <command>su</command>)
+          {command}`su`)
         '';
       };
 
@@ -271,7 +271,7 @@ let
         default = config.security.pam.mount.enable;
         defaultText = literalExpression "config.security.pam.mount.enable";
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Enable PAM mount (pam_mount) system to mount fileystems on user login.
         '';
       };
@@ -279,13 +279,13 @@ let
       allowNullPassword = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Whether to allow logging into accounts that have no password
           set (i.e., have an empty password field in
-          <filename>/etc/passwd</filename> or
-          <filename>/etc/group</filename>).  This does not enable
+          {file}`/etc/passwd` or
+          {file}`/etc/group`).  This does not enable
           logging into disabled accounts (i.e., that have the password
-          field set to <literal>!</literal>).  Note that regardless of
+          field set to `!`).  Note that regardless of
           what the pam_unix documentation says, accounts with hashed
           empty passwords are always allowed to log in.
         '';
@@ -294,7 +294,7 @@ let
       nodelay = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Wheather the delay after typing a wrong password should be disabled.
         '';
       };
@@ -302,7 +302,7 @@ let
       requireWheel = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Whether to permit root access only to members of group wheel.
         '';
       };
@@ -322,15 +322,15 @@ let
       showMotd = mkOption {
         default = false;
         type = types.bool;
-        description = "Whether to show the message of the day.";
+        description = lib.mdDoc "Whether to show the message of the day.";
       };
 
       makeHomeDir = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Whether to try to create home directories for users
-          with <literal>$HOME</literal>s pointing to nonexistent
+          with `$HOME`s pointing to nonexistent
           locations on session login.
         '';
       };
@@ -338,19 +338,19 @@ let
       updateWtmp = mkOption {
         default = false;
         type = types.bool;
-        description = "Whether to update <filename>/var/log/wtmp</filename>.";
+        description = lib.mdDoc "Whether to update {file}`/var/log/wtmp`.";
       };
 
       logFailures = mkOption {
         default = false;
         type = types.bool;
-        description = "Whether to log authentication failures in <filename>/var/log/faillog</filename>.";
+        description = lib.mdDoc "Whether to log authentication failures in {file}`/var/log/faillog`.";
       };
 
       enableAppArmor = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Enable support for attaching AppArmor profiles at the
           user/group level, e.g., as part of a role based access
           control scheme.
@@ -360,7 +360,7 @@ let
       enableKwallet = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           If enabled, pam_wallet will attempt to automatically unlock the
           user's default KDE wallet upon login. If the user has no wallet named
           "kdewallet", or the login password does not match their wallet
@@ -370,13 +370,13 @@ let
       sssdStrictAccess = mkOption {
         default = false;
         type = types.bool;
-        description = "enforce sssd access control";
+        description = lib.mdDoc "enforce sssd access control";
       };
 
       enableGnomeKeyring = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           If enabled, pam_gnome_keyring will attempt to automatically unlock the
           user's default Gnome keyring upon login. If the user login password does
           not match their keyring password, Gnome Keyring will prompt separately
@@ -388,24 +388,24 @@ let
         enable = mkOption {
           type = types.bool;
           default = false;
-          description = ''
+          description = lib.mdDoc ''
             If enabled, pam_gnupg will attempt to automatically unlock the
             user's GPG keys with the login password via
-            <command>gpg-agent</command>. The keygrips of all keys to be
-            unlocked should be written to <filename>~/.pam-gnupg</filename>,
-            and can be queried with <command>gpg -K --with-keygrip</command>.
+            {command}`gpg-agent`. The keygrips of all keys to be
+            unlocked should be written to {file}`~/.pam-gnupg`,
+            and can be queried with {command}`gpg -K --with-keygrip`.
             Presetting passphrases must be enabled by adding
-            <literal>allow-preset-passphrase</literal> in
-            <filename>~/.gnupg/gpg-agent.conf</filename>.
+            `allow-preset-passphrase` in
+            {file}`~/.gnupg/gpg-agent.conf`.
           '';
         };
 
         noAutostart = mkOption {
           type = types.bool;
           default = false;
-          description = ''
-            Don't start <command>gpg-agent</command> if it is not running.
-            Useful in conjunction with starting <command>gpg-agent</command> as
+          description = lib.mdDoc ''
+            Don't start {command}`gpg-agent` if it is not running.
+            Useful in conjunction with starting {command}`gpg-agent` as
             a systemd user service.
           '';
         };
@@ -413,16 +413,16 @@ let
         storeOnly = mkOption {
           type = types.bool;
           default = false;
-          description = ''
+          description = lib.mdDoc ''
             Don't send the password immediately after login, but store for PAM
-            <literal>session</literal>.
+            `session`.
           '';
         };
       };
 
       text = mkOption {
         type = types.nullOr types.lines;
-        description = "Contents of the PAM service file.";
+        description = lib.mdDoc "Contents of the PAM service file.";
       };
 
     };
@@ -673,19 +673,19 @@ let
   limitsType = with lib.types; listOf (submodule ({ ... }: {
     options = {
       domain = mkOption {
-        description = "Username, groupname, or wildcard this limit applies to";
+        description = lib.mdDoc "Username, groupname, or wildcard this limit applies to";
         example = "@wheel";
         type = str;
       };
 
       type = mkOption {
-        description = "Type of this limit";
+        description = lib.mdDoc "Type of this limit";
         type = enum [ "-" "hard" "soft" ];
         default = "-";
       };
 
       item = mkOption {
-        description = "Item this limit applies to";
+        description = lib.mdDoc "Item this limit applies to";
         type = enum [
           "core"
           "data"
@@ -709,7 +709,7 @@ let
       };
 
       value = mkOption {
-        description = "Value of this limit";
+        description = lib.mdDoc "Value of this limit";
         type = oneOf [ str int ];
       };
     };
@@ -769,10 +769,10 @@ in
       default = {};
       type = with types; attrsOf (submodule pamOpts);
       description =
-        ''
+        lib.mdDoc ''
           This option defines the PAM services.  A service typically
           corresponds to a program that uses PAM,
-          e.g. <command>login</command> or <command>passwd</command>.
+          e.g. {command}`login` or {command}`passwd`.
           Each attribute of this set defines a PAM service, with the attribute name
           defining the name of the service.
         '';
@@ -782,9 +782,9 @@ in
       type = types.str;
       default = "/var/empty";
       example =  "/etc/skel";
-      description = ''
+      description = lib.mdDoc ''
         Path to skeleton directory whose contents are copied to home
-        directories newly created by <literal>pam_mkhomedir</literal>.
+        directories newly created by `pam_mkhomedir`.
       '';
     };
 
@@ -792,9 +792,9 @@ in
       type = types.bool;
       default = false;
       description =
-        ''
+        lib.mdDoc ''
           Enable sudo logins if the user's SSH agent provides a key
-          present in <filename>~/.ssh/authorized_keys</filename>.
+          present in {file}`~/.ssh/authorized_keys`.
           This allows machines to exclusively use SSH keys instead of
           passwords.
         '';
@@ -953,7 +953,7 @@ in
       debug = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Debug output to stderr.
         '';
       };
@@ -961,7 +961,7 @@ in
       interactive = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Set to prompt a message and wait before testing the presence of a U2F device.
           Recommended if your device doesn’t have a tactile trigger.
         '';
@@ -970,12 +970,12 @@ in
       cue = mkOption {
         default = false;
         type = types.bool;
-        description = ''
-          By default <literal>pam-u2f</literal> module does not inform user
+        description = lib.mdDoc ''
+          By default `pam-u2f` module does not inform user
           that he needs to use the u2f device, it just waits without a prompt.
 
-          If you set this option to <literal>true</literal>,
-          <literal>cue</literal> option is added to <literal>pam-u2f</literal>
+          If you set this option to `true`,
+          `cue` option is added to `pam-u2f`
           module and reminder message will be displayed.
         '';
       };
@@ -1003,11 +1003,11 @@ in
       caFile = mkOption {
         default = null;
         type = with types; nullOr path;
-        description = ''
-          By default <literal>pam-ussh</literal> reads the trusted user CA keys
-          from <filename>/etc/ssh/trusted_user_ca</filename>.
+        description = lib.mdDoc ''
+          By default `pam-ussh` reads the trusted user CA keys
+          from {file}`/etc/ssh/trusted_user_ca`.
 
-          This should be set the same as your <literal>TrustedUserCAKeys</literal>
+          This should be set the same as your `TrustedUserCAKeys`
           option for sshd.
         '';
       };
@@ -1015,38 +1015,38 @@ in
       authorizedPrincipals = mkOption {
         default = null;
         type = with types; nullOr commas;
-        description = ''
+        description = lib.mdDoc ''
           Comma-separated list of authorized principals to permit; if the user
           presents a certificate with one of these principals, then they will be
           authorized.
 
-          Note that <literal>pam-ussh</literal> also requires that the certificate
+          Note that `pam-ussh` also requires that the certificate
           contain a principal matching the user's username. The principals from
           this list are in addition to those principals.
 
-          Mutually exclusive with <literal>authorizedPrincipalsFile</literal>.
+          Mutually exclusive with `authorizedPrincipalsFile`.
         '';
       };
 
       authorizedPrincipalsFile = mkOption {
         default = null;
         type = with types; nullOr path;
-        description = ''
+        description = lib.mdDoc ''
           Path to a list of principals; if the user presents a certificate with
           one of these principals, then they will be authorized.
 
-          Note that <literal>pam-ussh</literal> also requires that the certificate
+          Note that `pam-ussh` also requires that the certificate
           contain a principal matching the user's username. The principals from
           this file are in addition to those principals.
 
-          Mutually exclusive with <literal>authorizedPrincipals</literal>.
+          Mutually exclusive with `authorizedPrincipals`.
         '';
       };
 
       group = mkOption {
         default = null;
         type = with types; nullOr str;
-        description = ''
+        description = lib.mdDoc ''
           If set, then the authenticating user must be a member of this group
           to use this module.
         '';
@@ -1107,13 +1107,13 @@ in
       id = mkOption {
         example = "42";
         type = types.str;
-        description = "client id";
+        description = lib.mdDoc "client id";
       };
 
       debug = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Debug output to stderr.
         '';
       };
@@ -1152,7 +1152,7 @@ in
       default = null;
       example = "Today is Sweetmorn, the 4th day of The Aftermath in the YOLD 3178.";
       type = types.nullOr types.lines;
-      description = "Message of the day shown to users when they log in.";
+      description = lib.mdDoc "Message of the day shown to users when they log in.";
     };
 
   };
diff --git a/nixos/modules/security/pam_mount.nix b/nixos/modules/security/pam_mount.nix
index 1d0efee8ca8ee..e159a73b66a46 100644
--- a/nixos/modules/security/pam_mount.nix
+++ b/nixos/modules/security/pam_mount.nix
@@ -23,7 +23,7 @@ in
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Enable PAM mount system to mount fileystems on user login.
         '';
       };
@@ -42,7 +42,7 @@ in
         type = types.listOf types.package;
         default = [];
         example = literalExpression "[ pkgs.bindfs ]";
-        description = ''
+        description = lib.mdDoc ''
           Additional programs to include in the search path of pam_mount.
           Useful for example if you want to use some FUSE filesystems like bindfs.
         '';
@@ -54,7 +54,7 @@ in
         example = literalExpression ''
           [ "nodev" "nosuid" "force-user=%(USER)" "gid=%(USERGID)" "perms=0700" "chmod-deny" "chown-deny" "chgrp-deny" ]
         '';
-        description = ''
+        description = lib.mdDoc ''
           Global mount options that apply to every FUSE volume.
           You can define volume-specific options in the volume definitions.
         '';
@@ -86,7 +86,7 @@ in
       logoutHup = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Kill remaining processes after logout by sending a SIGHUP.
         '';
       };
@@ -94,7 +94,7 @@ in
       logoutTerm = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Kill remaining processes after logout by sending a SIGTERM.
         '';
       };
@@ -102,7 +102,7 @@ in
       logoutKill = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Kill remaining processes after logout by sending a SIGKILL.
         '';
       };
@@ -110,7 +110,7 @@ in
       createMountPoints = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Create mountpoints for volumes if they do not exist.
         '';
       };
@@ -118,7 +118,7 @@ in
       removeCreatedMountPoints = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Remove mountpoints created by pam_mount after logout. This
           only affects mountpoints that have been created by pam_mount
           in the same session.
diff --git a/nixos/modules/security/rtkit.nix b/nixos/modules/security/rtkit.nix
index ad8746808e85e..0f58b4dce84a2 100644
--- a/nixos/modules/security/rtkit.nix
+++ b/nixos/modules/security/rtkit.nix
@@ -12,7 +12,7 @@ with lib;
     security.rtkit.enable = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable the RealtimeKit system service, which hands
         out realtime scheduling priority to user processes on
         demand. For example, the PulseAudio server uses this to
diff --git a/nixos/modules/security/sudo.nix b/nixos/modules/security/sudo.nix
index 4bf239fca8f90..2e30a8915d865 100644
--- a/nixos/modules/security/sudo.nix
+++ b/nixos/modules/security/sudo.nix
@@ -36,8 +36,8 @@ in
       type = types.bool;
       default = true;
       description =
-        ''
-          Whether to enable the <command>sudo</command> command, which
+        lib.mdDoc ''
+          Whether to enable the {command}`sudo` command, which
           allows non-root users to execute commands as root.
         '';
     };
@@ -77,15 +77,15 @@ in
       # Note: if syntax errors are detected in this file, the NixOS
       # configuration will fail to build.
       description =
-        ''
+        lib.mdDoc ''
           This string contains the contents of the
-          <filename>sudoers</filename> file.
+          {file}`sudoers` file.
         '';
     };
 
     security.sudo.extraRules = mkOption {
-      description = ''
-        Define specific rules to be in the <filename>sudoers</filename> file.
+      description = lib.mdDoc ''
+        Define specific rules to be in the {file}`sudoers` file.
         More specific rules should come after more general ones in order to
         yield the expected behavior. You can use mkBefore/mkAfter to ensure
         this is the case when configuration options are merged.
@@ -114,7 +114,7 @@ in
         options = {
           users = mkOption {
             type = with types; listOf (either str int);
-            description = ''
+            description = lib.mdDoc ''
               The usernames / UIDs this rule should apply for.
             '';
             default = [];
@@ -122,7 +122,7 @@ in
 
           groups = mkOption {
             type = with types; listOf (either str int);
-            description = ''
+            description = lib.mdDoc ''
               The groups / GIDs this rule should apply for.
             '';
             default = [];
@@ -131,7 +131,7 @@ in
           host = mkOption {
             type = types.str;
             default = "ALL";
-            description = ''
+            description = lib.mdDoc ''
               For what host this rule should apply.
             '';
           };
@@ -149,7 +149,7 @@ in
           };
 
           commands = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               The commands for which the rule should apply.
             '';
             type = with types; listOf (either str (submodule {
@@ -182,8 +182,8 @@ in
     security.sudo.extraConfig = mkOption {
       type = types.lines;
       default = "";
-      description = ''
-        Extra configuration text appended to <filename>sudoers</filename>.
+      description = lib.mdDoc ''
+        Extra configuration text appended to {file}`sudoers`.
       '';
     };
   };
diff --git a/nixos/modules/security/tpm2.nix b/nixos/modules/security/tpm2.nix
index be85fd246e3cc..375f4af1a64f2 100644
--- a/nixos/modules/security/tpm2.nix
+++ b/nixos/modules/security/tpm2.nix
@@ -20,7 +20,7 @@ in {
     enable = lib.mkEnableOption "Trusted Platform Module 2 support";
 
     tssUser = lib.mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Name of the tpm device-owner and service user, set if applyUdevRules is
         set.
       '';
@@ -30,7 +30,7 @@ in {
     };
 
     tssGroup = lib.mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Group of the tpm kernel resource manager (tpmrm) device-group, set if
         applyUdevRules is set.
       '';
@@ -39,7 +39,7 @@ in {
     };
 
     applyUdevRules = lib.mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Whether to make the /dev/tpm[0-9] devices accessible by the tssUser, or
         the /dev/tpmrm[0-9] by tssGroup respectively
       '';
@@ -53,7 +53,7 @@ in {
       '';
 
       package = lib.mkOption {
-        description = "tpm2-abrmd package to use";
+        description = lib.mdDoc "tpm2-abrmd package to use";
         type = lib.types.package;
         default = pkgs.tpm2-abrmd;
         defaultText = lib.literalExpression "pkgs.tpm2-abrmd";
@@ -67,7 +67,7 @@ in {
       '';
 
       package = lib.mkOption {
-        description = "tpm2-pkcs11 package to use";
+        description = lib.mdDoc "tpm2-pkcs11 package to use";
         type = lib.types.package;
         default = pkgs.tpm2-pkcs11;
         defaultText = lib.literalExpression "pkgs.tpm2-pkcs11";
@@ -97,7 +97,7 @@ in {
       };
 
       interface = lib.mkOption {
-        description = ''
+        description = lib.mdDoc ''
           The name of the TPM command transmission interface (TCTI) library to
           use.
         '';
@@ -106,24 +106,24 @@ in {
       };
 
       deviceConf = lib.mkOption {
-        description = ''
+        description = lib.mdDoc ''
           Configuration part of the device TCTI, e.g. the path to the TPM device.
           Applies if interface is set to "device".
           The format is specified in the
-          <link xlink:href="https://github.com/tpm2-software/tpm2-tools/blob/master/man/common/tcti.md#tcti-options">
-          tpm2-tools repository</link>.
+          [
+          tpm2-tools repository](https://github.com/tpm2-software/tpm2-tools/blob/master/man/common/tcti.md#tcti-options).
         '';
         type = lib.types.str;
         default = "/dev/tpmrm0";
       };
 
       tabrmdConf = lib.mkOption {
-        description = ''
+        description = lib.mdDoc ''
           Configuration part of the tabrmd TCTI, like the D-Bus bus name.
           Applies if interface is set to "tabrmd".
           The format is specified in the
-          <link xlink:href="https://github.com/tpm2-software/tpm2-tools/blob/master/man/common/tcti.md#tcti-options">
-          tpm2-tools repository</link>.
+          [
+          tpm2-tools repository](https://github.com/tpm2-software/tpm2-tools/blob/master/man/common/tcti.md#tcti-options).
         '';
         type = lib.types.str;
         default = "bus_name=com.intel.tss2.Tabrmd";
diff --git a/nixos/modules/security/wrappers/default.nix b/nixos/modules/security/wrappers/default.nix
index 169ef7442626e..cdf99e697f6f2 100644
--- a/nixos/modules/security/wrappers/default.nix
+++ b/nixos/modules/security/wrappers/default.nix
@@ -22,30 +22,30 @@ let
   wrapperType = lib.types.submodule ({ name, config, ... }: {
     options.source = lib.mkOption
       { type = lib.types.path;
-        description = "The absolute path to the program to be wrapped.";
+        description = lib.mdDoc "The absolute path to the program to be wrapped.";
       };
     options.program = lib.mkOption
       { type = with lib.types; nullOr str;
         default = name;
-        description = ''
+        description = lib.mdDoc ''
           The name of the wrapper program. Defaults to the attribute name.
         '';
       };
     options.owner = lib.mkOption
       { type = lib.types.str;
-        description = "The owner of the wrapper program.";
+        description = lib.mdDoc "The owner of the wrapper program.";
       };
     options.group = lib.mkOption
       { type = lib.types.str;
-        description = "The group of the wrapper program.";
+        description = lib.mdDoc "The group of the wrapper program.";
       };
     options.permissions = lib.mkOption
       { type = fileModeType;
         default  = "u+rx,g+x,o+x";
         example = "a+rx";
-        description = ''
+        description = lib.mdDoc ''
           The permissions of the wrapper program. The format is that of a
-          symbolic or numeric file mode understood by <command>chmod</command>.
+          symbolic or numeric file mode understood by {command}`chmod`.
         '';
       };
     options.capabilities = lib.mkOption
@@ -73,12 +73,12 @@ let
     options.setuid = lib.mkOption
       { type = lib.types.bool;
         default = false;
-        description = "Whether to add the setuid bit the wrapper program.";
+        description = lib.mdDoc "Whether to add the setuid bit the wrapper program.";
       };
     options.setgid = lib.mkOption
       { type = lib.types.bool;
         default = false;
-        description = "Whether to add the setgid bit the wrapper program.";
+        description = lib.mdDoc "Whether to add the setgid bit the wrapper program.";
       };
   });
 
@@ -179,12 +179,12 @@ in
               };
           }
         '';
-      description = ''
+      description = lib.mdDoc ''
         This option effectively allows adding setuid/setgid bits, capabilities,
         changing file ownership and permissions of a program without directly
         modifying it. This works by creating a wrapper program under the
-        <option>security.wrapperDir</option> directory, which is then added to
-        the shell <literal>PATH</literal>.
+        {option}`security.wrapperDir` directory, which is then added to
+        the shell `PATH`.
       '';
     };