treewide: automatically md-convert option descriptions

the conversion procedure is simple:

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

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

15 files changed, 184 insertions, 184 deletions

diff --git a/nixos/modules/services/cluster/corosync/default.nix b/nixos/modules/services/cluster/corosync/default.nix
index b4144917fee..97308944541 100644
--- a/nixos/modules/services/cluster/corosync/default.nix
+++ b/nixos/modules/services/cluster/corosync/default.nix
@@ -13,37 +13,37 @@ in
       type = types.package;
       default = pkgs.corosync;
       defaultText = literalExpression "pkgs.corosync";
-      description = "Package that should be used for corosync.";
+      description = lib.mdDoc "Package that should be used for corosync.";
     };
 
     clusterName = mkOption {
       type = types.str;
       default = "nixcluster";
-      description = "Name of the corosync cluster.";
+      description = lib.mdDoc "Name of the corosync cluster.";
     };
 
     extraOptions = mkOption {
       type = with types; listOf str;
       default = [];
-      description = "Additional options with which to start corosync.";
+      description = lib.mdDoc "Additional options with which to start corosync.";
     };
 
     nodelist = mkOption {
-      description = "Corosync nodelist: all cluster members.";
+      description = lib.mdDoc "Corosync nodelist: all cluster members.";
       default = [];
       type = with types; listOf (submodule {
         options = {
           nodeid = mkOption {
             type = int;
-            description = "Node ID number";
+            description = lib.mdDoc "Node ID number";
           };
           name = mkOption {
             type = str;
-            description = "Node name";
+            description = lib.mdDoc "Node name";
           };
           ring_addrs = mkOption {
             type = listOf str;
-            description = "List of addresses, one for each ring.";
+            description = lib.mdDoc "List of addresses, one for each ring.";
           };
         };
       });
diff --git a/nixos/modules/services/cluster/hadoop/hdfs.nix b/nixos/modules/services/cluster/hadoop/hdfs.nix
index 325a002ad32..6c185b9cd24 100644
--- a/nixos/modules/services/cluster/hadoop/hdfs.nix
+++ b/nixos/modules/services/cluster/hadoop/hdfs.nix
@@ -11,7 +11,7 @@ let
     enable = mkEnableOption serviceName;
     restartIfChanged = mkOption {
       type = types.bool;
-      description = ''
+      description = lib.mdDoc ''
         Automatically restart the service on config change.
         This can be set to false to defer restarts on clusters running critical applications.
         Please consider the security implications of inadvertently running an older version,
@@ -22,7 +22,7 @@ let
     extraFlags = mkOption{
       type = with types; listOf str;
       default = [];
-      description = "Extra command line flags to pass to ${serviceName}";
+      description = lib.mdDoc "Extra command line flags to pass to ${serviceName}";
       example = [
         "-Dcom.sun.management.jmxremote"
         "-Dcom.sun.management.jmxremote.port=8010"
@@ -31,13 +31,13 @@ let
     extraEnv = mkOption{
       type = with types; attrsOf str;
       default = {};
-      description = "Extra environment variables for ${serviceName}";
+      description = lib.mdDoc "Extra environment variables for ${serviceName}";
     };
   } // (optionalAttrs firewallOption {
     openFirewall = mkOption {
       type = types.bool;
       default = false;
-      description = "Open firewall ports for ${serviceName}.";
+      description = lib.mdDoc "Open firewall ports for ${serviceName}.";
     };
   }) // (optionalAttrs (extraOpts != null) extraOpts);
 
@@ -83,12 +83,12 @@ in
       formatOnInit = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Format HDFS namenode on first start. This is useful for quickly spinning up
           ephemeral HDFS clusters with a single namenode.
           For HA clusters, initialization involves multiple steps across multiple nodes.
           Follow this guide to initialize an HA cluster manually:
-          <link xlink:href="https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-hdfs/HDFSHighAvailabilityWithQJM.html"/>
+          <https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-hdfs/HDFSHighAvailabilityWithQJM.html>
         '';
       };
     };
@@ -96,19 +96,19 @@ in
     datanode = hadoopServiceOption { serviceName = "HDFS DataNode"; } // {
       dataDirs = mkOption {
         default = null;
-        description = "Tier and path definitions for datanode storage.";
+        description = lib.mdDoc "Tier and path definitions for datanode storage.";
         type = with types; nullOr (listOf (submodule {
           options = {
             type = mkOption {
               type = enum [ "SSD" "DISK" "ARCHIVE" "RAM_DISK" ];
-              description = ''
+              description = lib.mdDoc ''
                 Storage types ([SSD]/[DISK]/[ARCHIVE]/[RAM_DISK]) for HDFS storage policies.
               '';
             };
             path = mkOption {
               type = path;
               example = [ "/var/lib/hadoop/hdfs/dn" ];
-              description = "Determines where on the local filesystem a data node should store its blocks.";
+              description = lib.mdDoc "Determines where on the local filesystem a data node should store its blocks.";
             };
           };
         }));
@@ -126,7 +126,7 @@ in
       tempPath = mkOption {
         type = types.path;
         default = "/tmp/hadoop/httpfs";
-        description = "HTTPFS_TEMP path used by HTTPFS";
+        description = lib.mdDoc "HTTPFS_TEMP path used by HTTPFS";
       };
     };
 
diff --git a/nixos/modules/services/cluster/hadoop/yarn.nix b/nixos/modules/services/cluster/hadoop/yarn.nix
index 74e16bdec68..0a03fe6dab6 100644
--- a/nixos/modules/services/cluster/hadoop/yarn.nix
+++ b/nixos/modules/services/cluster/hadoop/yarn.nix
@@ -5,7 +5,7 @@ let
   hadoopConf = "${import ./conf.nix { inherit cfg pkgs lib; }}/";
   restartIfChanged  = mkOption {
     type = types.bool;
-    description = ''
+    description = lib.mdDoc ''
       Automatically restart the service on config change.
       This can be set to false to defer restarts on clusters running critical applications.
       Please consider the security implications of inadvertently running an older version,
@@ -16,7 +16,7 @@ let
   extraFlags = mkOption{
     type = with types; listOf str;
     default = [];
-    description = "Extra command line flags to pass to the service";
+    description = lib.mdDoc "Extra command line flags to pass to the service";
     example = [
       "-Dcom.sun.management.jmxremote"
       "-Dcom.sun.management.jmxremote.port=8010"
@@ -25,7 +25,7 @@ let
   extraEnv = mkOption{
     type = with types; attrsOf str;
     default = {};
-    description = "Extra environment variables";
+    description = lib.mdDoc "Extra environment variables";
   };
 in
 {
@@ -37,7 +37,7 @@ in
       openFirewall = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Open firewall ports for resourcemanager
         '';
       };
@@ -48,22 +48,22 @@ in
 
       resource = {
         cpuVCores = mkOption {
-          description = "Number of vcores that can be allocated for containers.";
+          description = lib.mdDoc "Number of vcores that can be allocated for containers.";
           type = with types; nullOr ints.positive;
           default = null;
         };
         maximumAllocationVCores = mkOption {
-          description = "The maximum virtual CPU cores any container can be allocated.";
+          description = lib.mdDoc "The maximum virtual CPU cores any container can be allocated.";
           type = with types; nullOr ints.positive;
           default = null;
         };
         memoryMB = mkOption {
-          description = "Amount of physical memory, in MB, that can be allocated for containers.";
+          description = lib.mdDoc "Amount of physical memory, in MB, that can be allocated for containers.";
           type = with types; nullOr ints.positive;
           default = null;
         };
         maximumAllocationMB = mkOption {
-          description = "The maximum physical memory any container can be allocated.";
+          description = lib.mdDoc "The maximum physical memory any container can be allocated.";
           type = with types; nullOr ints.positive;
           default = null;
         };
@@ -72,13 +72,13 @@ in
       useCGroups = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Use cgroups to enforce resource limits on containers
         '';
       };
 
       localDir = mkOption {
-        description = "List of directories to store localized files in.";
+        description = lib.mdDoc "List of directories to store localized files in.";
         type = with types; nullOr (listOf path);
         example = [ "/var/lib/hadoop/yarn/nm" ];
         default = null;
@@ -87,14 +87,14 @@ in
       addBinBash = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Add /bin/bash. This is needed by the linux container executor's launch script.
         '';
       };
       openFirewall = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Open firewall ports for nodemanager.
           Because containers can listen on any ephemeral port, TCP ports 1024–65535 will be opened.
         '';
diff --git a/nixos/modules/services/cluster/k3s/default.nix b/nixos/modules/services/cluster/k3s/default.nix
index bc5e8c66e2a..a1f6d4ecdfa 100644
--- a/nixos/modules/services/cluster/k3s/default.nix
+++ b/nixos/modules/services/cluster/k3s/default.nix
@@ -19,11 +19,11 @@ in
       type = types.package;
       default = pkgs.k3s;
       defaultText = literalExpression "pkgs.k3s";
-      description = "Package that should be used for k3s";
+      description = lib.mdDoc "Package that should be used for k3s";
     };
 
     role = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Whether k3s should run as a server or agent.
         Note that the server, by default, also runs as an agent.
       '';
@@ -33,14 +33,14 @@ in
 
     serverAddr = mkOption {
       type = types.str;
-      description = "The k3s server to connect to. This option only makes sense for an agent.";
+      description = lib.mdDoc "The k3s server to connect to. This option only makes sense for an agent.";
       example = "https://10.0.0.10:6443";
       default = "";
     };
 
     token = mkOption {
       type = types.str;
-      description = ''
+      description = lib.mdDoc ''
         The k3s token to use when connecting to the server. This option only makes sense for an agent.
         WARNING: This option will expose store your token unencrypted world-readable in the nix store.
         If this is undesired use the tokenFile option instead.
@@ -50,12 +50,12 @@ in
 
     tokenFile = mkOption {
       type = types.nullOr types.path;
-      description = "File path containing k3s token to use when connecting to the server. This option only makes sense for an agent.";
+      description = lib.mdDoc "File path containing k3s token to use when connecting to the server. This option only makes sense for an agent.";
       default = null;
     };
 
     extraFlags = mkOption {
-      description = "Extra flags to pass to the k3s command.";
+      description = lib.mdDoc "Extra flags to pass to the k3s command.";
       type = types.str;
       default = "";
       example = "--no-deploy traefik --cluster-cidr 10.24.0.0/16";
@@ -64,13 +64,13 @@ in
     disableAgent = mkOption {
       type = types.bool;
       default = false;
-      description = "Only run the server. This option only makes sense for a server.";
+      description = lib.mdDoc "Only run the server. This option only makes sense for a server.";
     };
 
     configPath = mkOption {
       type = types.nullOr types.path;
       default = null;
-      description = "File path containing the k3s YAML config. This is useful when the config is generated (for example on boot).";
+      description = lib.mdDoc "File path containing the k3s YAML config. This is useful when the config is generated (for example on boot).";
     };
   };
 
diff --git a/nixos/modules/services/cluster/kubernetes/addon-manager.nix b/nixos/modules/services/cluster/kubernetes/addon-manager.nix
index b677d900ff5..99fd1e6f049 100644
--- a/nixos/modules/services/cluster/kubernetes/addon-manager.nix
+++ b/nixos/modules/services/cluster/kubernetes/addon-manager.nix
@@ -21,7 +21,7 @@ in
   options.services.kubernetes.addonManager = with lib.types; {
 
     bootstrapAddons = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Bootstrap addons are like regular addons, but they are applied with cluster-admin rigths.
         They are applied at addon-manager startup only.
       '';
@@ -43,7 +43,7 @@ in
     };
 
     addons = mkOption {
-      description = "Kubernetes addons (any kind of Kubernetes resource can be an addon).";
+      description = lib.mdDoc "Kubernetes addons (any kind of Kubernetes resource can be an addon).";
       default = { };
       type = attrsOf (either attrs (listOf attrs));
       example = literalExpression ''
diff --git a/nixos/modules/services/cluster/kubernetes/addons/dns.nix b/nixos/modules/services/cluster/kubernetes/addons/dns.nix
index 7bd4991f43f..5b1e9a68768 100644
--- a/nixos/modules/services/cluster/kubernetes/addons/dns.nix
+++ b/nixos/modules/services/cluster/kubernetes/addons/dns.nix
@@ -15,7 +15,7 @@ in {
     enable = mkEnableOption "kubernetes dns addon";
 
     clusterIp = mkOption {
-      description = "Dns addon clusterIP";
+      description = lib.mdDoc "Dns addon clusterIP";
 
       # this default is also what kubernetes users
       default = (
@@ -31,31 +31,31 @@ in {
     };
 
     clusterDomain = mkOption {
-      description = "Dns cluster domain";
+      description = lib.mdDoc "Dns cluster domain";
       default = "cluster.local";
       type = types.str;
     };
 
     replicas = mkOption {
-      description = "Number of DNS pod replicas to deploy in the cluster.";
+      description = lib.mdDoc "Number of DNS pod replicas to deploy in the cluster.";
       default = 2;
       type = types.int;
     };
 
     reconcileMode = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Controls the addon manager reconciliation mode for the DNS addon.
 
         Setting reconcile mode to EnsureExists makes it possible to tailor DNS behavior by editing the coredns ConfigMap.
 
-        See: <link xlink:href="https://github.com/kubernetes/kubernetes/blob/master/cluster/addons/addon-manager/README.md"/>.
+        See: <https://github.com/kubernetes/kubernetes/blob/master/cluster/addons/addon-manager/README.md>.
       '';
       default = "Reconcile";
       type = types.enum [ "Reconcile" "EnsureExists" ];
     };
 
     coredns = mkOption {
-      description = "Docker image to seed for the CoreDNS container.";
+      description = lib.mdDoc "Docker image to seed for the CoreDNS container.";
       type = types.attrs;
       default = {
         imageName = "coredns/coredns";
@@ -66,10 +66,10 @@ in {
     };
 
     corefile = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Custom coredns corefile configuration.
 
-        See: <link xlink:href="https://coredns.io/manual/toc/#configuration"/>.
+        See: <https://coredns.io/manual/toc/#configuration>.
       '';
       type = types.str;
       default = ''
diff --git a/nixos/modules/services/cluster/kubernetes/apiserver.nix b/nixos/modules/services/cluster/kubernetes/apiserver.nix
index a192e93badc..c9ae2c14bbf 100644
--- a/nixos/modules/services/cluster/kubernetes/apiserver.nix
+++ b/nixos/modules/services/cluster/kubernetes/apiserver.nix
@@ -30,7 +30,7 @@ in
   options.services.kubernetes.apiserver = with lib.types; {
 
     advertiseAddress = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Kubernetes apiserver IP address on which to advertise the apiserver
         to members of the cluster. This address must be reachable by the rest
         of the cluster.
@@ -40,40 +40,40 @@ in
     };
 
     allowPrivileged = mkOption {
-      description = "Whether to allow privileged containers on Kubernetes.";
+      description = lib.mdDoc "Whether to allow privileged containers on Kubernetes.";
       default = false;
       type = bool;
     };
 
     authorizationMode = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Kubernetes apiserver authorization mode (AlwaysAllow/AlwaysDeny/ABAC/Webhook/RBAC/Node). See
-        <link xlink:href="https://kubernetes.io/docs/reference/access-authn-authz/authorization/"/>
+        <https://kubernetes.io/docs/reference/access-authn-authz/authorization/>
       '';
       default = ["RBAC" "Node"]; # Enabling RBAC by default, although kubernetes default is AllowAllow
       type = listOf (enum ["AlwaysAllow" "AlwaysDeny" "ABAC" "Webhook" "RBAC" "Node"]);
     };
 
     authorizationPolicy = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Kubernetes apiserver authorization policy file. See
-        <link xlink:href="https://kubernetes.io/docs/reference/access-authn-authz/authorization/"/>
+        <https://kubernetes.io/docs/reference/access-authn-authz/authorization/>
       '';
       default = [];
       type = listOf attrs;
     };
 
     basicAuthFile = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Kubernetes apiserver basic authentication file. See
-        <link xlink:href="https://kubernetes.io/docs/reference/access-authn-authz/authentication"/>
+        <https://kubernetes.io/docs/reference/access-authn-authz/authentication>
       '';
       default = null;
       type = nullOr path;
     };
 
     bindAddress = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         The IP address on which to listen for the --secure-port port.
         The associated interface(s) must be reachable by the rest
         of the cluster, and by CLI/web clients.
@@ -83,16 +83,16 @@ in
     };
 
     clientCaFile = mkOption {
-      description = "Kubernetes apiserver CA file for client auth.";
+      description = lib.mdDoc "Kubernetes apiserver CA file for client auth.";
       default = top.caFile;
       defaultText = literalExpression "config.${otop.caFile}";
       type = nullOr path;
     };
 
     disableAdmissionPlugins = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Kubernetes admission control plugins to disable. See
-        <link xlink:href="https://kubernetes.io/docs/admin/admission-controllers/"/>
+        <https://kubernetes.io/docs/admin/admission-controllers/>
       '';
       default = [];
       type = listOf str;
@@ -101,9 +101,9 @@ in
     enable = mkEnableOption "Kubernetes apiserver";
 
     enableAdmissionPlugins = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Kubernetes admission control plugins to enable. See
-        <link xlink:href="https://kubernetes.io/docs/admin/admission-controllers/"/>
+        <https://kubernetes.io/docs/admin/admission-controllers/>
       '';
       default = [
         "NamespaceLifecycle" "LimitRanger" "ServiceAccount"
@@ -120,25 +120,25 @@ in
 
     etcd = {
       servers = mkOption {
-        description = "List of etcd servers.";
+        description = lib.mdDoc "List of etcd servers.";
         default = ["http://127.0.0.1:2379"];
         type = types.listOf types.str;
       };
 
       keyFile = mkOption {
-        description = "Etcd key file.";
+        description = lib.mdDoc "Etcd key file.";
         default = null;
         type = types.nullOr types.path;
       };
 
       certFile = mkOption {
-        description = "Etcd cert file.";
+        description = lib.mdDoc "Etcd cert file.";
         default = null;
         type = types.nullOr types.path;
       };
 
       caFile = mkOption {
-        description = "Etcd ca file.";
+        description = lib.mdDoc "Etcd ca file.";
         default = top.caFile;
         defaultText = literalExpression "config.${otop.caFile}";
         type = types.nullOr types.path;
@@ -146,77 +146,77 @@ in
     };
 
     extraOpts = mkOption {
-      description = "Kubernetes apiserver extra command line options.";
+      description = lib.mdDoc "Kubernetes apiserver extra command line options.";
       default = "";
       type = separatedString " ";
     };
 
     extraSANs = mkOption {
-      description = "Extra x509 Subject Alternative Names to be added to the kubernetes apiserver tls cert.";
+      description = lib.mdDoc "Extra x509 Subject Alternative Names to be added to the kubernetes apiserver tls cert.";
       default = [];
       type = listOf str;
     };
 
     featureGates = mkOption {
-      description = "List set of feature gates";
+      description = lib.mdDoc "List set of feature gates";
       default = top.featureGates;
       defaultText = literalExpression "config.${otop.featureGates}";
       type = listOf str;
     };
 
     insecureBindAddress = mkOption {
-      description = "The IP address on which to serve the --insecure-port.";
+      description = lib.mdDoc "The IP address on which to serve the --insecure-port.";
       default = "127.0.0.1";
       type = str;
     };
 
     insecurePort = mkOption {
-      description = "Kubernetes apiserver insecure listening port. (0 = disabled)";
+      description = lib.mdDoc "Kubernetes apiserver insecure listening port. (0 = disabled)";
       default = 0;
       type = int;
     };
 
     kubeletClientCaFile = mkOption {
-      description = "Path to a cert file for connecting to kubelet.";
+      description = lib.mdDoc "Path to a cert file for connecting to kubelet.";
       default = top.caFile;
       defaultText = literalExpression "config.${otop.caFile}";
       type = nullOr path;
     };
 
     kubeletClientCertFile = mkOption {
-      description = "Client certificate to use for connections to kubelet.";
+      description = lib.mdDoc "Client certificate to use for connections to kubelet.";
       default = null;
       type = nullOr path;
     };
 
     kubeletClientKeyFile = mkOption {
-      description = "Key to use for connections to kubelet.";
+      description = lib.mdDoc "Key to use for connections to kubelet.";
       default = null;
       type = nullOr path;
     };
 
     preferredAddressTypes = mkOption {
-      description = "List of the preferred NodeAddressTypes to use for kubelet connections.";
+      description = lib.mdDoc "List of the preferred NodeAddressTypes to use for kubelet connections.";
       type = nullOr str;
       default = null;
     };
 
     proxyClientCertFile = mkOption {
-      description = "Client certificate to use for connections to proxy.";
+      description = lib.mdDoc "Client certificate to use for connections to proxy.";
       default = null;
       type = nullOr path;
     };
 
     proxyClientKeyFile = mkOption {
-      description = "Key to use for connections to proxy.";
+      description = lib.mdDoc "Key to use for connections to proxy.";
       default = null;
       type = nullOr path;
     };
 
     runtimeConfig = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Api runtime configuration. See
-        <link xlink:href="https://kubernetes.io/docs/tasks/administer-cluster/cluster-management/"/>
+        <https://kubernetes.io/docs/tasks/administer-cluster/cluster-management/>
       '';
       default = "authentication.k8s.io/v1beta1=true";
       example = "api/all=false,api/v1=true";
@@ -224,7 +224,7 @@ in
     };
 
     storageBackend = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Kubernetes apiserver storage backend.
       '';
       default = "etcd3";
@@ -232,13 +232,13 @@ in
     };
 
     securePort = mkOption {
-      description = "Kubernetes apiserver secure port.";
+      description = lib.mdDoc "Kubernetes apiserver secure port.";
       default = 6443;
       type = int;
     };
 
     apiAudiences = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Kubernetes apiserver ServiceAccount issuer.
       '';
       default = "api,https://kubernetes.default.svc";
@@ -246,7 +246,7 @@ in
     };
 
     serviceAccountIssuer = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Kubernetes apiserver ServiceAccount issuer.
       '';
       default = "https://kubernetes.default.svc";
@@ -254,7 +254,7 @@ in
     };
 
     serviceAccountSigningKeyFile = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Path to the file that contains the current private key of the service
         account token issuer. The issuer will sign issued ID tokens with this
         private key.
@@ -263,7 +263,7 @@ in
     };
 
     serviceAccountKeyFile = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         File containing PEM-encoded x509 RSA or ECDSA private or public keys,
         used to verify ServiceAccount tokens. The specified file can contain
         multiple keys, and the flag can be specified multiple times with
@@ -274,7 +274,7 @@ in
     };
 
     serviceClusterIpRange = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         A CIDR notation IP range from which to assign service cluster IPs.
         This must not overlap with any IP ranges assigned to nodes for pods.
       '';
@@ -283,39 +283,39 @@ in
     };
 
     tlsCertFile = mkOption {
-      description = "Kubernetes apiserver certificate file.";
+      description = lib.mdDoc "Kubernetes apiserver certificate file.";
       default = null;
       type = nullOr path;
     };
 
     tlsKeyFile = mkOption {
-      description = "Kubernetes apiserver private key file.";
+      description = lib.mdDoc "Kubernetes apiserver private key file.";
       default = null;
       type = nullOr path;
     };
 
     tokenAuthFile = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Kubernetes apiserver token authentication file. See
-        <link xlink:href="https://kubernetes.io/docs/reference/access-authn-authz/authentication"/>
+        <https://kubernetes.io/docs/reference/access-authn-authz/authentication>
       '';
       default = null;
       type = nullOr path;
     };
 
     verbosity = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Optional glog verbosity level for logging statements. See
-        <link xlink:href="https://github.com/kubernetes/community/blob/master/contributors/devel/logging.md"/>
+        <https://github.com/kubernetes/community/blob/master/contributors/devel/logging.md>
       '';
       default = null;
       type = nullOr int;
     };
 
     webhookConfig = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Kubernetes apiserver Webhook config file. It uses the kubeconfig file format.
-        See <link xlink:href="https://kubernetes.io/docs/reference/access-authn-authz/webhook/"/>
+        See <https://kubernetes.io/docs/reference/access-authn-authz/webhook/>
       '';
       default = null;
       type = nullOr path;
diff --git a/nixos/modules/services/cluster/kubernetes/controller-manager.nix b/nixos/modules/services/cluster/kubernetes/controller-manager.nix
index 7c317e94dee..6080e6f9915 100644
--- a/nixos/modules/services/cluster/kubernetes/controller-manager.nix
+++ b/nixos/modules/services/cluster/kubernetes/controller-manager.nix
@@ -17,19 +17,19 @@ in
   options.services.kubernetes.controllerManager = with lib.types; {
 
     allocateNodeCIDRs = mkOption {
-      description = "Whether to automatically allocate CIDR ranges for cluster nodes.";
+      description = lib.mdDoc "Whether to automatically allocate CIDR ranges for cluster nodes.";
       default = true;
       type = bool;
     };
 
     bindAddress = mkOption {
-      description = "Kubernetes controller manager listening address.";
+      description = lib.mdDoc "Kubernetes controller manager listening address.";
       default = "127.0.0.1";
       type = str;
     };
 
     clusterCidr = mkOption {
-      description = "Kubernetes CIDR Range for Pods in cluster.";
+      description = lib.mdDoc "Kubernetes CIDR Range for Pods in cluster.";
       default = top.clusterCidr;
       defaultText = literalExpression "config.${otop.clusterCidr}";
       type = str;
@@ -38,20 +38,20 @@ in
     enable = mkEnableOption "Kubernetes controller manager";
 
     extraOpts = mkOption {
-      description = "Kubernetes controller manager extra command line options.";
+      description = lib.mdDoc "Kubernetes controller manager extra command line options.";
       default = "";
       type = separatedString " ";
     };
 
     featureGates = mkOption {
-      description = "List set of feature gates";
+      description = lib.mdDoc "List set of feature gates";
       default = top.featureGates;
       defaultText = literalExpression "config.${otop.featureGates}";
       type = listOf str;
     };
 
     insecurePort = mkOption {
-      description = "Kubernetes controller manager insecure listening port.";
+      description = lib.mdDoc "Kubernetes controller manager insecure listening port.";
       default = 0;
       type = int;
     };
@@ -59,13 +59,13 @@ in
     kubeconfig = top.lib.mkKubeConfigOptions "Kubernetes controller manager";
 
     leaderElect = mkOption {
-      description = "Whether to start leader election before executing main loop.";
+      description = lib.mdDoc "Whether to start leader election before executing main loop.";
       type = bool;
       default = true;
     };
 
     rootCaFile = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Kubernetes controller manager certificate authority file included in
         service account's token secret.
       '';
@@ -75,13 +75,13 @@ in
     };
 
     securePort = mkOption {
-      description = "Kubernetes controller manager secure listening port.";
+      description = lib.mdDoc "Kubernetes controller manager secure listening port.";
       default = 10252;
       type = int;
     };
 
     serviceAccountKeyFile = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Kubernetes controller manager PEM-encoded private RSA key file used to
         sign service account tokens
       '';
@@ -90,21 +90,21 @@ in
     };
 
     tlsCertFile = mkOption {
-      description = "Kubernetes controller-manager certificate file.";
+      description = lib.mdDoc "Kubernetes controller-manager certificate file.";
       default = null;
       type = nullOr path;
     };
 
     tlsKeyFile = mkOption {
-      description = "Kubernetes controller-manager private key file.";
+      description = lib.mdDoc "Kubernetes controller-manager private key file.";
       default = null;
       type = nullOr path;
     };
 
     verbosity = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Optional glog verbosity level for logging statements. See
-        <link xlink:href="https://github.com/kubernetes/community/blob/master/contributors/devel/logging.md"/>
+        <https://github.com/kubernetes/community/blob/master/contributors/devel/logging.md>
       '';
       default = null;
       type = nullOr int;
diff --git a/nixos/modules/services/cluster/kubernetes/default.nix b/nixos/modules/services/cluster/kubernetes/default.nix
index 35ec99d83c8..f5374fc7194 100644
--- a/nixos/modules/services/cluster/kubernetes/default.nix
+++ b/nixos/modules/services/cluster/kubernetes/default.nix
@@ -77,25 +77,25 @@ let
 
   mkKubeConfigOptions = prefix: {
     server = mkOption {
-      description = "${prefix} kube-apiserver server address.";
+      description = lib.mdDoc "${prefix} kube-apiserver server address.";
       type = types.str;
     };
 
     caFile = mkOption {
-      description = "${prefix} certificate authority file used to connect to kube-apiserver.";
+      description = lib.mdDoc "${prefix} certificate authority file used to connect to kube-apiserver.";
       type = types.nullOr types.path;
       default = cfg.caFile;
       defaultText = literalExpression "config.${opt.caFile}";
     };
 
     certFile = mkOption {
-      description = "${prefix} client certificate file used to connect to kube-apiserver.";
+      description = lib.mdDoc "${prefix} client certificate file used to connect to kube-apiserver.";
       type = types.nullOr types.path;
       default = null;
     };
 
     keyFile = mkOption {
-      description = "${prefix} client key file used to connect to kube-apiserver.";
+      description = lib.mdDoc "${prefix} client key file used to connect to kube-apiserver.";
       type = types.nullOr types.path;
       default = null;
     };
@@ -111,7 +111,7 @@ in {
 
   options.services.kubernetes = {
     roles = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Kubernetes role that this machine should take.
 
         Master role will enable etcd, apiserver, scheduler, controller manager
@@ -123,7 +123,7 @@ in {
     };
 
     package = mkOption {
-      description = "Kubernetes package to use.";
+      description = lib.mdDoc "Kubernetes package to use.";
       type = types.package;
       default = pkgs.kubernetes;
       defaultText = literalExpression "pkgs.kubernetes";
@@ -132,7 +132,7 @@ in {
     kubeconfig = mkKubeConfigOptions "Default kubeconfig";
 
     apiserverAddress = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Clusterwide accessible address for the kubernetes apiserver,
         including protocol and optional port.
       '';
@@ -141,49 +141,49 @@ in {
     };
 
     caFile = mkOption {
-      description = "Default kubernetes certificate authority";
+      description = lib.mdDoc "Default kubernetes certificate authority";
       type = types.nullOr types.path;
       default = null;
     };
 
     dataDir = mkOption {
-      description = "Kubernetes root directory for managing kubelet files.";
+      description = lib.mdDoc "Kubernetes root directory for managing kubelet files.";
       default = "/var/lib/kubernetes";
       type = types.path;
     };
 
     easyCerts = mkOption {
-      description = "Automatically setup x509 certificates and keys for the entire cluster.";
+      description = lib.mdDoc "Automatically setup x509 certificates and keys for the entire cluster.";
       default = false;
       type = types.bool;
     };
 
     featureGates = mkOption {
-      description = "List set of feature gates.";
+      description = lib.mdDoc "List set of feature gates.";
       default = [];
       type = types.listOf types.str;
     };
 
     masterAddress = mkOption {
-      description = "Clusterwide available network address or hostname for the kubernetes master server.";
+      description = lib.mdDoc "Clusterwide available network address or hostname for the kubernetes master server.";
       example = "master.example.com";
       type = types.str;
     };
 
     path = mkOption {
-      description = "Packages added to the services' PATH environment variable. Both the bin and sbin subdirectories of each package are added.";
+      description = lib.mdDoc "Packages added to the services' PATH environment variable. Both the bin and sbin subdirectories of each package are added.";
       type = types.listOf types.package;
       default = [];
     };
 
     clusterCidr = mkOption {
-      description = "Kubernetes controller manager and proxy CIDR Range for Pods in cluster.";
+      description = lib.mdDoc "Kubernetes controller manager and proxy CIDR Range for Pods in cluster.";
       default = "10.1.0.0/16";
       type = types.nullOr types.str;
     };
 
     lib = mkOption {
-      description = "Common functions for the kubernetes modules.";
+      description = lib.mdDoc "Common functions for the kubernetes modules.";
       default = {
         inherit mkCert;
         inherit mkKubeConfig;
@@ -193,7 +193,7 @@ in {
     };
 
     secretsPath = mkOption {
-      description = "Default location for kubernetes secrets. Not a store location.";
+      description = lib.mdDoc "Default location for kubernetes secrets. Not a store location.";
       type = types.path;
       default = cfg.dataDir + "/secrets";
       defaultText = literalExpression ''
diff --git a/nixos/modules/services/cluster/kubernetes/kubelet.nix b/nixos/modules/services/cluster/kubernetes/kubelet.nix
index 4363ed35d34..cbb1cffc169 100644
--- a/nixos/modules/services/cluster/kubernetes/kubelet.nix
+++ b/nixos/modules/services/cluster/kubernetes/kubelet.nix
@@ -38,17 +38,17 @@ let
   taintOptions = with lib.types; { name, ... }: {
     options = {
       key = mkOption {
-        description = "Key of taint.";
+        description = lib.mdDoc "Key of taint.";
         default = name;
         defaultText = literalDocBook "Name of this submodule.";
         type = str;
       };
       value = mkOption {
-        description = "Value of taint.";
+        description = lib.mdDoc "Value of taint.";
         type = str;
       };
       effect = mkOption {
-        description = "Effect of taint.";
+        description = lib.mdDoc "Effect of taint.";
         example = "NoSchedule";
         type = enum ["NoSchedule" "PreferNoSchedule" "NoExecute"];
       };
@@ -68,26 +68,26 @@ in
   options.services.kubernetes.kubelet = with lib.types; {
 
     address = mkOption {
-      description = "Kubernetes kubelet info server listening address.";
+      description = lib.mdDoc "Kubernetes kubelet info server listening address.";
       default = "0.0.0.0";
       type = str;
     };
 
     clusterDns = mkOption {
-      description = "Use alternative DNS.";
+      description = lib.mdDoc "Use alternative DNS.";
       default = "10.1.0.1";
       type = str;
     };
 
     clusterDomain = mkOption {
-      description = "Use alternative domain.";
+      description = lib.mdDoc "Use alternative domain.";
       default = config.services.kubernetes.addons.dns.clusterDomain;
       defaultText = literalExpression "config.${options.services.kubernetes.addons.dns.clusterDomain}";
       type = str;
     };
 
     clientCaFile = mkOption {
-      description = "Kubernetes apiserver CA file for client authentication.";
+      description = lib.mdDoc "Kubernetes apiserver CA file for client authentication.";
       default = top.caFile;
       defaultText = literalExpression "config.${otop.caFile}";
       type = nullOr path;
@@ -95,13 +95,13 @@ in
 
     cni = {
       packages = mkOption {
-        description = "List of network plugin packages to install.";
+        description = lib.mdDoc "List of network plugin packages to install.";
         type = listOf package;
         default = [];
       };
 
       config = mkOption {
-        description = "Kubernetes CNI configuration.";
+        description = lib.mdDoc "Kubernetes CNI configuration.";
         type = listOf attrs;
         default = [];
         example = literalExpression ''
@@ -127,20 +127,20 @@ in
       };
 
       configDir = mkOption {
-        description = "Path to Kubernetes CNI configuration directory.";
+        description = lib.mdDoc "Path to Kubernetes CNI configuration directory.";
         type = nullOr path;
         default = null;
       };
     };
 
     containerRuntime = mkOption {
-      description = "Which container runtime type to use";
+      description = lib.mdDoc "Which container runtime type to use";
       type = enum ["docker" "remote"];
       default = "remote";
     };
 
     containerRuntimeEndpoint = mkOption {
-      description = "Endpoint at which to find the container runtime api interface/socket";
+      description = lib.mdDoc "Endpoint at which to find the container runtime api interface/socket";
       type = str;
       default = "unix:///run/containerd/containerd.sock";
     };
@@ -148,13 +148,13 @@ in
     enable = mkEnableOption "Kubernetes kubelet.";
 
     extraOpts = mkOption {
-      description = "Kubernetes kubelet extra command line options.";
+      description = lib.mdDoc "Kubernetes kubelet extra command line options.";
       default = "";
       type = separatedString " ";
     };
 
     featureGates = mkOption {
-      description = "List set of feature gates";
+      description = lib.mdDoc "List set of feature gates";
       default = top.featureGates;
       defaultText = literalExpression "config.${otop.featureGates}";
       type = listOf str;
@@ -162,20 +162,20 @@ in
 
     healthz = {
       bind = mkOption {
-        description = "Kubernetes kubelet healthz listening address.";
+        description = lib.mdDoc "Kubernetes kubelet healthz listening address.";
         default = "127.0.0.1";
         type = str;
       };
 
       port = mkOption {
-        description = "Kubernetes kubelet healthz port.";
+        description = lib.mdDoc "Kubernetes kubelet healthz port.";
         default = 10248;
         type = int;
       };
     };
 
     hostname = mkOption {
-      description = "Kubernetes kubelet hostname override.";
+      description = lib.mdDoc "Kubernetes kubelet hostname override.";
       default = config.networking.hostName;
       defaultText = literalExpression "config.networking.hostName";
       type = str;
@@ -184,69 +184,69 @@ in
     kubeconfig = top.lib.mkKubeConfigOptions "Kubelet";
 
     manifests = mkOption {
-      description = "List of manifests to bootstrap with kubelet (only pods can be created as manifest entry)";
+      description = lib.mdDoc "List of manifests to bootstrap with kubelet (only pods can be created as manifest entry)";
       type = attrsOf attrs;
       default = {};
     };
 
     networkPlugin = mkOption {
-      description = "Network plugin to use by Kubernetes.";
+      description = lib.mdDoc "Network plugin to use by Kubernetes.";
       type = nullOr (enum ["cni" "kubenet"]);
       default = "kubenet";
     };
 
     nodeIp = mkOption {
-      description = "IP address of the node. If set, kubelet will use this IP address for the node.";
+      description = lib.mdDoc "IP address of the node. If set, kubelet will use this IP address for the node.";
       default = null;
       type = nullOr str;
     };
 
     registerNode = mkOption {
-      description = "Whether to auto register kubelet with API server.";
+      description = lib.mdDoc "Whether to auto register kubelet with API server.";
       default = true;
       type = bool;
     };
 
     port = mkOption {
-      description = "Kubernetes kubelet info server listening port.";
+      description = lib.mdDoc "Kubernetes kubelet info server listening port.";
       default = 10250;
       type = int;
     };
 
     seedDockerImages = mkOption {
-      description = "List of docker images to preload on system";
+      description = lib.mdDoc "List of docker images to preload on system";
       default = [];
       type = listOf package;
     };
 
     taints = mkOption {
-      description = "Node taints (https://kubernetes.io/docs/concepts/configuration/assign-pod-node/).";
+      description = lib.mdDoc "Node taints (https://kubernetes.io/docs/concepts/configuration/assign-pod-node/).";
       default = {};
       type = attrsOf (submodule [ taintOptions ]);
     };
 
     tlsCertFile = mkOption {
-      description = "File containing x509 Certificate for HTTPS.";
+      description = lib.mdDoc "File containing x509 Certificate for HTTPS.";
       default = null;
       type = nullOr path;
     };
 
     tlsKeyFile = mkOption {
-      description = "File containing x509 private key matching tlsCertFile.";
+      description = lib.mdDoc "File containing x509 private key matching tlsCertFile.";
       default = null;
       type = nullOr path;
     };
 
     unschedulable = mkOption {
-      description = "Whether to set node taint to unschedulable=true as it is the case of node that has only master role.";
+      description = lib.mdDoc "Whether to set node taint to unschedulable=true as it is the case of node that has only master role.";
       default = false;
       type = bool;
     };
 
     verbosity = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Optional glog verbosity level for logging statements. See
-        <link xlink:href="https://github.com/kubernetes/community/blob/master/contributors/devel/logging.md"/>
+        <https://github.com/kubernetes/community/blob/master/contributors/devel/logging.md>
       '';
       default = null;
       type = nullOr int;
diff --git a/nixos/modules/services/cluster/kubernetes/pki.nix b/nixos/modules/services/cluster/kubernetes/pki.nix
index 7d9198d20e8..7c46ac85584 100644
--- a/nixos/modules/services/cluster/kubernetes/pki.nix
+++ b/nixos/modules/services/cluster/kubernetes/pki.nix
@@ -44,13 +44,13 @@ in
     enable = mkEnableOption "easyCert issuer service";
 
     certs = mkOption {
-      description = "List of certificate specs to feed to cert generator.";
+      description = lib.mdDoc "List of certificate specs to feed to cert generator.";
       default = {};
       type = attrs;
     };
 
     genCfsslCACert = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Whether to automatically generate cfssl CA certificate and key,
         if they don't exist.
       '';
@@ -59,7 +59,7 @@ in
     };
 
     genCfsslAPICerts = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Whether to automatically generate cfssl API webserver TLS cert and key,
         if they don't exist.
       '';
@@ -68,7 +68,7 @@ in
     };
 
     cfsslAPIExtraSANs = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Extra x509 Subject Alternative Names to be added to the cfssl API webserver TLS cert.
       '';
       default = [];
@@ -77,7 +77,7 @@ in
     };
 
     genCfsslAPIToken = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Whether to automatically generate cfssl API-token secret,
         if they doesn't exist.
       '';
@@ -86,13 +86,13 @@ in
     };
 
     pkiTrustOnBootstrap = mkOption {
-      description = "Whether to always trust remote cfssl server upon initial PKI bootstrap.";
+      description = lib.mdDoc "Whether to always trust remote cfssl server upon initial PKI bootstrap.";
       default = true;
       type = bool;
     };
 
     caCertPathPrefix = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Path-prefrix for the CA-certificate to be used for cfssl signing.
         Suffixes ".pem" and "-key.pem" will be automatically appended for
         the public and private keys respectively.
@@ -103,7 +103,7 @@ in
     };
 
     caSpec = mkOption {
-      description = "Certificate specification for the auto-generated CAcert.";
+      description = lib.mdDoc "Certificate specification for the auto-generated CAcert.";
       default = {
         CN = "kubernetes-cluster-ca";
         O = "NixOS";
diff --git a/nixos/modules/services/cluster/kubernetes/proxy.nix b/nixos/modules/services/cluster/kubernetes/proxy.nix
index 0fd98d1c157..51114c32499 100644
--- a/nixos/modules/services/cluster/kubernetes/proxy.nix
+++ b/nixos/modules/services/cluster/kubernetes/proxy.nix
@@ -16,7 +16,7 @@ in
   options.services.kubernetes.proxy = with lib.types; {
 
     bindAddress = mkOption {
-      description = "Kubernetes proxy listening address.";
+      description = lib.mdDoc "Kubernetes proxy listening address.";
       default = "0.0.0.0";
       type = str;
     };
@@ -24,20 +24,20 @@ in
     enable = mkEnableOption "Kubernetes proxy";
 
     extraOpts = mkOption {
-      description = "Kubernetes proxy extra command line options.";
+      description = lib.mdDoc "Kubernetes proxy extra command line options.";
       default = "";
       type = separatedString " ";
     };
 
     featureGates = mkOption {
-      description = "List set of feature gates";
+      description = lib.mdDoc "List set of feature gates";
       default = top.featureGates;
       defaultText = literalExpression "config.${otop.featureGates}";
       type = listOf str;
     };
 
     hostname = mkOption {
-      description = "Kubernetes proxy hostname override.";
+      description = lib.mdDoc "Kubernetes proxy hostname override.";
       default = config.networking.hostName;
       defaultText = literalExpression "config.networking.hostName";
       type = str;
@@ -46,9 +46,9 @@ in
     kubeconfig = top.lib.mkKubeConfigOptions "Kubernetes proxy";
 
     verbosity = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Optional glog verbosity level for logging statements. See
-        <link xlink:href="https://github.com/kubernetes/community/blob/master/contributors/devel/logging.md"/>
+        <https://github.com/kubernetes/community/blob/master/contributors/devel/logging.md>
       '';
       default = null;
       type = nullOr int;
diff --git a/nixos/modules/services/cluster/kubernetes/scheduler.nix b/nixos/modules/services/cluster/kubernetes/scheduler.nix
index 2d95528a6ea..ddc67889a37 100644
--- a/nixos/modules/services/cluster/kubernetes/scheduler.nix
+++ b/nixos/modules/services/cluster/kubernetes/scheduler.nix
@@ -12,7 +12,7 @@ in
   options.services.kubernetes.scheduler = with lib.types; {
 
     address = mkOption {
-      description = "Kubernetes scheduler listening address.";
+      description = lib.mdDoc "Kubernetes scheduler listening address.";
       default = "127.0.0.1";
       type = str;
     };
@@ -20,13 +20,13 @@ in
     enable = mkEnableOption "Kubernetes scheduler";
 
     extraOpts = mkOption {
-      description = "Kubernetes scheduler extra command line options.";
+      description = lib.mdDoc "Kubernetes scheduler extra command line options.";
       default = "";
       type = separatedString " ";
     };
 
     featureGates = mkOption {
-      description = "List set of feature gates";
+      description = lib.mdDoc "List set of feature gates";
       default = top.featureGates;
       defaultText = literalExpression "config.${otop.featureGates}";
       type = listOf str;
@@ -35,21 +35,21 @@ in
     kubeconfig = top.lib.mkKubeConfigOptions "Kubernetes scheduler";
 
     leaderElect = mkOption {
-      description = "Whether to start leader election before executing main loop.";
+      description = lib.mdDoc "Whether to start leader election before executing main loop.";
       type = bool;
       default = true;
     };
 
     port = mkOption {
-      description = "Kubernetes scheduler listening port.";
+      description = lib.mdDoc "Kubernetes scheduler listening port.";
       default = 10251;
       type = int;
     };
 
     verbosity = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Optional glog verbosity level for logging statements. See
-        <link xlink:href="https://github.com/kubernetes/community/blob/master/contributors/devel/logging.md"/>
+        <https://github.com/kubernetes/community/blob/master/contributors/devel/logging.md>
       '';
       default = null;
       type = nullOr int;
diff --git a/nixos/modules/services/cluster/pacemaker/default.nix b/nixos/modules/services/cluster/pacemaker/default.nix
index 7eeadffcc58..41d98a460f5 100644
--- a/nixos/modules/services/cluster/pacemaker/default.nix
+++ b/nixos/modules/services/cluster/pacemaker/default.nix
@@ -13,7 +13,7 @@ in
       type = types.package;
       default = pkgs.pacemaker;
       defaultText = literalExpression "pkgs.pacemaker";
-      description = "Package that should be used for pacemaker.";
+      description = lib.mdDoc "Package that should be used for pacemaker.";
     };
   };
 
diff --git a/nixos/modules/services/cluster/spark/default.nix b/nixos/modules/services/cluster/spark/default.nix
index e6b44e130a3..30d8fa0fc41 100644
--- a/nixos/modules/services/cluster/spark/default.nix
+++ b/nixos/modules/services/cluster/spark/default.nix
@@ -10,13 +10,13 @@ with lib;
         enable = mkEnableOption "Spark master service";
         bind = mkOption {
           type = types.str;
-          description = "Address the spark master binds to.";
+          description = lib.mdDoc "Address the spark master binds to.";
           default = "127.0.0.1";
           example = "0.0.0.0";
         };
         restartIfChanged  = mkOption {
           type = types.bool;
-          description = ''
+          description = lib.mdDoc ''
             Automatically restart master service on config change.
             This can be set to false to defer restarts on clusters running critical applications.
             Please consider the security implications of inadvertently running an older version,
@@ -26,7 +26,7 @@ with lib;
         };
         extraEnvironment = mkOption {
           type = types.attrsOf types.str;
-          description = "Extra environment variables to pass to spark master. See spark-standalone documentation.";
+          description = lib.mdDoc "Extra environment variables to pass to spark master. See spark-standalone documentation.";
           default = {};
           example = {
             SPARK_MASTER_WEBUI_PORT = 8181;
@@ -38,17 +38,17 @@ with lib;
         enable = mkEnableOption "Spark worker service";
         workDir = mkOption {
           type = types.path;
-          description = "Spark worker work dir.";
+          description = lib.mdDoc "Spark worker work dir.";
           default = "/var/lib/spark";
         };
         master = mkOption {
           type = types.str;
-          description = "Address of the spark master.";
+          description = lib.mdDoc "Address of the spark master.";
           default = "127.0.0.1:7077";
         };
         restartIfChanged  = mkOption {
           type = types.bool;
-          description = ''
+          description = lib.mdDoc ''
             Automatically restart worker service on config change.
             This can be set to false to defer restarts on clusters running critical applications.
             Please consider the security implications of inadvertently running an older version,
@@ -58,7 +58,7 @@ with lib;
         };
         extraEnvironment = mkOption {
           type = types.attrsOf types.str;
-          description = "Extra environment variables to pass to spark worker.";
+          description = lib.mdDoc "Extra environment variables to pass to spark worker.";
           default = {};
           example = {
             SPARK_WORKER_CORES = 5;
@@ -68,18 +68,18 @@ with lib;
       };
       confDir = mkOption {
         type = types.path;
-        description = "Spark configuration directory. Spark will use the configuration files (spark-defaults.conf, spark-env.sh, log4j.properties, etc) from this directory.";
+        description = lib.mdDoc "Spark configuration directory. Spark will use the configuration files (spark-defaults.conf, spark-env.sh, log4j.properties, etc) from this directory.";
         default = "${cfg.package}/lib/${cfg.package.untarDir}/conf";
         defaultText = literalExpression ''"''${package}/lib/''${package.untarDir}/conf"'';
       };
       logDir = mkOption {
         type = types.path;
-        description = "Spark log directory.";
+        description = lib.mdDoc "Spark log directory.";
         default = "/var/log/spark";
       };
       package = mkOption {
         type = types.package;
-        description = "Spark package.";
+        description = lib.mdDoc "Spark package.";
         default = pkgs.spark;
         defaultText = literalExpression "pkgs.spark";
         example = literalExpression ''pkgs.spark.overrideAttrs (super: rec {