diff --git a/nixos/modules/services/monitoring/prometheus/default.nix b/nixos/modules/services/monitoring/prometheus/default.nix
index c15c2273eefe..7c03c188356e 100644
--- a/nixos/modules/services/monitoring/prometheus/default.nix
+++ b/nixos/modules/services/monitoring/prometheus/default.nix
@@ -99,14 +99,14 @@ let
 
   mkDefOpt = type: defaultStr: description: mkOpt type (description + ''
 
-    Defaults to <literal>${defaultStr}</literal> in prometheus
-    when set to <literal>null</literal>.
+    Defaults to ````${defaultStr}```` in prometheus
+    when set to `null`.
   '');
 
   mkOpt = type: description: mkOption {
     type = types.nullOr type;
     default = null;
-    inherit description;
+    description = lib.mdDoc description;
   };
 
   mkSdConfigModule = extraOptions: types.submodule {
@@ -123,16 +123,16 @@ let
             '';
 
             credentials = mkOpt types.str ''
-              Sets the credentials. It is mutually exclusive with <literal>credentials_file</literal>.
+              Sets the credentials. It is mutually exclusive with `credentials_file`.
             '';
 
             credentials_file = mkOpt types.str ''
               Sets the credentials to the credentials read from the configured file.
-              It is mutually exclusive with <literal>credentials</literal>.
+              It is mutually exclusive with `credentials`.
             '';
           };
         }) ''
-        Optional <literal>Authorization</literal> header configuration.
+        Optional `Authorization` header configuration.
       '';
 
       oauth2 = mkOpt promtypes.oauth2 ''
@@ -229,7 +229,7 @@ let
       '';
 
       client_secret_file = mkOpt types.str ''
-        Read the client secret from a file. It is mutually exclusive with <literal>client_secret</literal>.
+        Read the client secret from a file. It is mutually exclusive with `client_secret`.
       '';
 
       scopes = mkOpt (types.listOf types.str) ''
@@ -288,7 +288,7 @@ let
 
         If honor_labels is set to "false", label conflicts are
         resolved by renaming conflicting labels in the scraped data
-        to "exported_&lt;original-label&gt;" (for example
+        to "exported_\<original-label\>" (for example
         "exported_instance", "exported_job") and then attaching
         server-side labels. This is useful for use cases such as
         federation, where all labels specified in the target should
@@ -299,10 +299,10 @@ let
         honor_timestamps controls whether Prometheus respects the timestamps present
         in scraped data.
 
-        If honor_timestamps is set to <literal>true</literal>, the timestamps of the metrics exposed
+        If honor_timestamps is set to `true`, the timestamps of the metrics exposed
         by the target will be used.
 
-        If honor_timestamps is set to <literal>false</literal>, the timestamps of the metrics exposed
+        If honor_timestamps is set to `false`, the timestamps of the metrics exposed
         by the target will be ignored.
       '';
 
@@ -315,21 +315,21 @@ let
       '';
 
       basic_auth = mkOpt promTypes.basic_auth ''
-        Sets the <literal>Authorization</literal> header on every scrape request with the
+        Sets the `Authorization` header on every scrape request with the
         configured username and password.
         password and password_file are mutually exclusive.
       '';
 
       bearer_token = mkOpt types.str ''
-        Sets the <literal>Authorization</literal> header on every scrape request with
+        Sets the `Authorization` header on every scrape request with
         the configured bearer token. It is mutually exclusive with
-        <option>bearer_token_file</option>.
+        {option}`bearer_token_file`.
       '';
 
       bearer_token_file = mkOpt types.str ''
-        Sets the <literal>Authorization</literal> header on every scrape request with
+        Sets the `Authorization` header on every scrape request with
         the bearer token read from the configured file. It is mutually
-        exclusive with <option>bearer_token</option>.
+        exclusive with {option}`bearer_token`.
       '';
 
       tls_config = mkOpt promTypes.tls_config ''
@@ -379,7 +379,7 @@ let
       gce_sd_configs = mkOpt (types.listOf promTypes.gce_sd_config) ''
         List of Google Compute Engine service discovery configurations.
 
-        See <link xlink:href="https://prometheus.io/docs/prometheus/latest/configuration/configuration/#gce_sd_config">the relevant Prometheus configuration docs</link>
+        See [the relevant Prometheus configuration docs](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#gce_sd_config)
         for more detail.
       '';
 
@@ -591,7 +591,7 @@ let
 
     allow_stale = mkOpt types.bool ''
       Allow stale Consul results
-      (see <link xlink:href="https://www.consul.io/api/index.html#consistency-modes"/>).
+      (see <https://www.consul.io/api/index.html#consistency-modes>).
 
       Will reduce load on Consul.
     '';
@@ -623,7 +623,7 @@ let
     };
 
     port = mkDefOpt types.int "80" ''
-      The port to scrape metrics from, when <literal>role</literal> is nodes, and for discovered
+      The port to scrape metrics from, when `role` is nodes, and for discovered
       tasks and services that don't have published ports.
     '';
 
@@ -632,16 +632,16 @@ let
         options = {
           name = mkOption {
             type = types.str;
-            description = ''
+            description = lib.mdDoc ''
               Name of the filter. The available filters are listed in the upstream documentation:
-              Services: <link xlink:href="https://docs.docker.com/engine/api/v1.40/#operation/ServiceList"/>
-              Tasks: <link xlink:href="https://docs.docker.com/engine/api/v1.40/#operation/TaskList"/>
-              Nodes: <link xlink:href="https://docs.docker.com/engine/api/v1.40/#operation/NodeList"/>
+              Services: <https://docs.docker.com/engine/api/v1.40/#operation/ServiceList>
+              Tasks: <https://docs.docker.com/engine/api/v1.40/#operation/TaskList>
+              Nodes: <https://docs.docker.com/engine/api/v1.40/#operation/NodeList>
             '';
           };
           values = mkOption {
             type = types.str;
-            description = ''
+            description = lib.mdDoc ''
               Value for the filter.
             '';
           };
@@ -707,12 +707,12 @@ let
 
       access_key = mkOpt types.str ''
         The AWS API key id. If blank, the environment variable
-        <literal>AWS_ACCESS_KEY_ID</literal> is used.
+        `AWS_ACCESS_KEY_ID` is used.
       '';
 
       secret_key = mkOpt types.str ''
         The AWS API key secret. If blank, the environment variable
-         <literal>AWS_SECRET_ACCESS_KEY</literal> is used.
+         `AWS_SECRET_ACCESS_KEY` is used.
       '';
 
       profile = mkOpt types.str ''
@@ -738,8 +738,8 @@ let
           options = {
             name = mkOption {
               type = types.str;
-              description = ''
-                See <link xlink:href="https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeInstances.html">this list</link>
+              description = lib.mdDoc ''
+                See [this list](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeInstances.html)
                 for the available filters.
               '';
             };
@@ -747,7 +747,7 @@ let
             values = mkOption {
               type = types.listOf types.str;
               default = [ ];
-              description = ''
+              description = lib.mdDoc ''
                 Value of the filter.
               '';
             };
@@ -806,7 +806,7 @@ let
       filter = mkOpt types.str ''
         Filter can be used optionally to filter the instance list by other
         criteria Syntax of this filter string is described here in the filter
-        query parameter section: <link xlink:href="https://cloud.google.com/compute/docs/reference/latest/instances/list"/>.
+        query parameter section: <https://cloud.google.com/compute/docs/reference/latest/instances/list>.
       '';
 
       refresh_interval = mkDefOpt types.str "60s" ''
@@ -822,7 +822,7 @@ let
         The tag separator used to separate concatenated GCE instance network tags.
 
         See the GCP documentation on network tags for more information:
-        <link xlink:href="https://cloud.google.com/vpc/docs/add-remove-network-tags"/>
+        <https://cloud.google.com/vpc/docs/add-remove-network-tags>
       '';
     };
   };
@@ -917,7 +917,7 @@ let
             options = {
               role = mkOption {
                 type = types.str;
-                description = ''
+                description = lib.mdDoc ''
                   Selector role
                 '';
               };
@@ -976,11 +976,11 @@ let
       '';
 
       access_key = mkOpt types.str ''
-        The AWS API keys. If blank, the environment variable <literal>AWS_ACCESS_KEY_ID</literal> is used.
+        The AWS API keys. If blank, the environment variable `AWS_ACCESS_KEY_ID` is used.
       '';
 
       secret_key = mkOpt types.str ''
-        The AWS API keys. If blank, the environment variable <literal>AWS_SECRET_ACCESS_KEY</literal> is used.
+        The AWS API keys. If blank, the environment variable `AWS_SECRET_ACCESS_KEY` is used.
       '';
 
       profile = mkOpt types.str ''
@@ -1030,14 +1030,14 @@ let
 
     auth_token = mkOpt types.str ''
       Optional authentication information for token-based authentication:
-      <link xlink:href="https://docs.mesosphere.com/1.11/security/ent/iam-api/#passing-an-authentication-token"/>
-      It is mutually exclusive with <literal>auth_token_file</literal> and other authentication mechanisms.
+      <https://docs.mesosphere.com/1.11/security/ent/iam-api/#passing-an-authentication-token>
+      It is mutually exclusive with `auth_token_file` and other authentication mechanisms.
     '';
 
     auth_token_file = mkOpt types.str ''
       Optional authentication information for token-based authentication:
-      <link xlink:href="https://docs.mesosphere.com/1.11/security/ent/iam-api/#passing-an-authentication-token"/>
-      It is mutually exclusive with <literal>auth_token</literal> and other authentication mechanisms.
+      <https://docs.mesosphere.com/1.11/security/ent/iam-api/#passing-an-authentication-token>
+      It is mutually exclusive with `auth_token` and other authentication mechanisms.
     '';
   };
 
@@ -1205,12 +1205,12 @@ let
 
       secret_key = mkOpt types.str ''
         Secret key to use when listing targets. https://console.scaleway.com/project/credentials
-        It is mutually exclusive with <literal>secret_key_file</literal>.
+        It is mutually exclusive with `secret_key_file`.
       '';
 
       secret_key_file = mkOpt types.str ''
         Sets the secret key with the credentials read from the configured file.
-        It is mutually exclusive with <literal>secret_key</literal>.
+        It is mutually exclusive with `secret_key`.
       '';
 
       project_id = mkOption {
@@ -1299,7 +1299,7 @@ let
       };
 
       groups = mkOpt (types.listOf types.str) ''
-        A list of groups for which targets are retrieved, only supported when targeting the <literal>container</literal> role.
+        A list of groups for which targets are retrieved, only supported when targeting the `container` role.
         If omitted all containers owned by the requesting account are scraped.
       '';
 
@@ -1440,17 +1440,17 @@ let
         remote write configs.
       '';
       basic_auth = mkOpt promTypes.basic_auth ''
-        Sets the <literal>Authorization</literal> header on every remote write request with the
+        Sets the `Authorization` header on every remote write request with the
         configured username and password.
         password and password_file are mutually exclusive.
       '';
       bearer_token = mkOpt types.str ''
-        Sets the <literal>Authorization</literal> header on every remote write request with
-        the configured bearer token. It is mutually exclusive with <literal>bearer_token_file</literal>.
+        Sets the `Authorization` header on every remote write request with
+        the configured bearer token. It is mutually exclusive with `bearer_token_file`.
       '';
       bearer_token_file = mkOpt types.str ''
-        Sets the <literal>Authorization</literal> header on every remote write request with the bearer token
-        read from the configured file. It is mutually exclusive with <literal>bearer_token</literal>.
+        Sets the `Authorization` header on every remote write request with the bearer token
+        read from the configured file. It is mutually exclusive with `bearer_token`.
       '';
       tls_config = mkOpt promTypes.tls_config ''
         Configures the remote write request's TLS settings.
@@ -1531,17 +1531,17 @@ let
         the local storage should have complete data for.
       '';
       basic_auth = mkOpt promTypes.basic_auth ''
-        Sets the <literal>Authorization</literal> header on every remote read request with the
+        Sets the `Authorization` header on every remote read request with the
         configured username and password.
         password and password_file are mutually exclusive.
       '';
       bearer_token = mkOpt types.str ''
-        Sets the <literal>Authorization</literal> header on every remote read request with
-        the configured bearer token. It is mutually exclusive with <literal>bearer_token_file</literal>.
+        Sets the `Authorization` header on every remote read request with
+        the configured bearer token. It is mutually exclusive with `bearer_token_file`.
       '';
       bearer_token_file = mkOpt types.str ''
-        Sets the <literal>Authorization</literal> header on every remote read request with the bearer token
-        read from the configured file. It is mutually exclusive with <literal>bearer_token</literal>.
+        Sets the `Authorization` header on every remote read request with the bearer token
+        read from the configured file. It is mutually exclusive with `bearer_token`.
       '';
       tls_config = mkOpt promTypes.tls_config ''
         Configures the remote read request's TLS settings.