nixos/*: md-convert options with unordered lists

mostly no rendering changes. some lists (like simplelist) don't have an
exact translation to markdown, so we use a comma-separated list of
literals instead.

19 files changed, 202 insertions, 375 deletions

diff --git a/nixos/modules/config/malloc.nix b/nixos/modules/config/malloc.nix
index a3fed33afa1..4db0480b155 100644
--- a/nixos/modules/config/malloc.nix
+++ b/nixos/modules/config/malloc.nix
@@ -77,24 +77,21 @@ in
     environment.memoryAllocator.provider = mkOption {
       type = types.enum ([ "libc" ] ++ attrNames providers);
       default = "libc";
-      description = ''
+      description = lib.mdDoc ''
         The system-wide memory allocator.
 
         Briefly, the system-wide memory allocator providers are:
-        <itemizedlist>
-        <listitem><para><literal>libc</literal>: the standard allocator provided by libc</para></listitem>
-        ${toString (mapAttrsToList
-            (name: value: "<listitem><para><literal>${name}</literal>: ${value.description}</para></listitem>")
+
+        - `libc`: the standard allocator provided by libc
+        ${concatStringsSep "\n" (mapAttrsToList
+            (name: value: "- `${name}`: ${replaceStrings [ "\n" ] [ " " ] value.description}")
             providers)}
-        </itemizedlist>
 
-        <warning>
-        <para>
+        ::: {.warning}
         Selecting an alternative allocator (i.e., anything other than
-        <literal>libc</literal>) may result in instability, data loss,
+        `libc`) may result in instability, data loss,
         and/or service failure.
-        </para>
-        </warning>
+        :::
       '';
     };
   };
diff --git a/nixos/modules/config/mysql.nix b/nixos/modules/config/mysql.nix
index 8e7ce2a307e..bef6acb5dbb 100644
--- a/nixos/modules/config/mysql.nix
+++ b/nixos/modules/config/mysql.nix
@@ -61,30 +61,20 @@ in
               type = types.nullOr types.str;
               default = null;
               example = "status";
-              description = ''
+              description = lib.mdDoc ''
                 The name of the column or an SQL expression that indicates the status of
                 the user. The status is expressed by the combination of two bitfields
                 shown below:
 
-                <itemizedlist>
-                  <listitem>
-                    <para>
-                      <literal>bit 0 (0x01)</literal>:
-                      if flagged, <literal>pam_mysql</literal> deems the account to be expired and
-                      returns <literal>PAM_ACCT_EXPIRED</literal>. That is, the account is supposed
-                      to no longer be available. Note this doesn't mean that <literal>pam_mysql</literal>
-                      rejects further authentication operations.
-                    </para>
-                  </listitem>
-                  <listitem>
-                    <para>
-                      <literal>bit 1 (0x02)</literal>:
-                      if flagged, <literal>pam_mysql</literal> deems the authentication token
-                      (password) to be expired and returns <literal>PAM_NEW_AUTHTOK_REQD</literal>.
-                      This ends up requiring that the user enter a new password.
-                    </para>
-                  </listitem>
-                </itemizedlist>
+                - `bit 0 (0x01)`:
+                   if flagged, `pam_mysql` deems the account to be expired and
+                   returns `PAM_ACCT_EXPIRED`. That is, the account is supposed
+                   to no longer be available. Note this doesn't mean that `pam_mysql`
+                   rejects further authentication operations.
+                -  `bit 1 (0x02)`:
+                   if flagged, `pam_mysql` deems the authentication token
+                   (password) to be expired and returns `PAM_NEW_AUTHTOK_REQD`.
+                   This ends up requiring that the user enter a new password.
               '';
             };
             passwordCrypt = mkOption {
@@ -101,74 +91,32 @@ in
                 "8" "sha512"
                 "9" "sha256"
               ];
-              description = ''
+              description = lib.mdDoc ''
                 The method to encrypt the user's password:
 
-                <itemizedlist>
-                <listitem>
-                  <para>
-                    <literal>0</literal> (or <literal>"plain"</literal>):
-                    No encryption. Passwords are stored in plaintext. HIGHLY DISCOURAGED.
-                  </para>
-                </listitem>
-                <listitem>
-                  <para>
-                    <literal>1</literal> (or <literal>"Y"</literal>):
-                    Use crypt(3) function.
-                  </para>
-                </listitem>
-                <listitem>
-                  <para>
-                    <literal>2</literal> (or <literal>"mysql"</literal>):
-                    Use the MySQL PASSWORD() function. It is possible that the encryption function used
-                    by <literal>pam_mysql</literal> is different from that of the MySQL server, as
-                    <literal>pam_mysql</literal> uses the function defined in MySQL's C-client API
-                    instead of using PASSWORD() SQL function in the query.
-                  </para>
-                </listitem>
-                <listitem>
-                  <para>
-                    <literal>3</literal> (or <literal>"md5"</literal>):
-                    Use plain hex MD5.
-                  </para>
-                </listitem>
-                <listitem>
-                  <para>
-                    <literal>4</literal> (or <literal>"sha1"</literal>):
-                    Use plain hex SHA1.
-                  </para>
-                </listitem>
-                <listitem>
-                  <para>
-                    <literal>5</literal> (or <literal>"drupal7"</literal>):
-                    Use Drupal7 salted passwords.
-                  </para>
-                </listitem>
-                <listitem>
-                  <para>
-                    <literal>6</literal> (or <literal>"joomla15"</literal>):
-                    Use Joomla15 salted passwords.
-                  </para>
-                </listitem>
-                <listitem>
-                  <para>
-                    <literal>7</literal> (or <literal>"ssha"</literal>):
-                    Use ssha hashed passwords.
-                  </para>
-                </listitem>
-                <listitem>
-                  <para>
-                    <literal>8</literal> (or <literal>"sha512"</literal>):
-                    Use sha512 hashed passwords.
-                  </para>
-                </listitem>
-                <listitem>
-                  <para>
-                    <literal>9</literal> (or <literal>"sha256"</literal>):
-                    Use sha256 hashed passwords.
-                  </para>
-                </listitem>
-                </itemizedlist>
+                - `0` (or `"plain"`):
+                  No encryption. Passwords are stored in plaintext. HIGHLY DISCOURAGED.
+                - `1` (or `"Y"`):
+                  Use crypt(3) function.
+                - `2` (or `"mysql"`):
+                  Use the MySQL PASSWORD() function. It is possible that the encryption function used
+                  by `pam_mysql` is different from that of the MySQL server, as
+                  `pam_mysql` uses the function defined in MySQL's C-client API
+                  instead of using PASSWORD() SQL function in the query.
+                - `3` (or `"md5"`):
+                  Use plain hex MD5.
+                - `4` (or `"sha1"`):
+                  Use plain hex SHA1.
+                - `5` (or `"drupal7"`):
+                  Use Drupal7 salted passwords.
+                - `6` (or `"joomla15"`):
+                  Use Joomla15 salted passwords.
+                - `7` (or `"ssha"`):
+                  Use ssha hashed passwords.
+                - `8` (or `"sha512"`):
+                  Use sha512 hashed passwords.
+                - `9` (or `"sha256"`):
+                  Use sha256 hashed passwords.
               '';
             };
             cryptDefault = mkOption {
diff --git a/nixos/modules/i18n/input-method/default.nix b/nixos/modules/i18n/input-method/default.nix
index bbc5783565a..626bced21f7 100644
--- a/nixos/modules/i18n/input-method/default.nix
+++ b/nixos/modules/i18n/input-method/default.nix
@@ -32,22 +32,20 @@ in
         type    = types.nullOr (types.enum [ "ibus" "fcitx" "fcitx5" "nabi" "uim" "hime" "kime" ]);
         default = null;
         example = "fcitx";
-        description = ''
+        description = lib.mdDoc ''
           Select the enabled input method. Input methods is a software to input symbols that are not available on standard input devices.
 
           Input methods are specially used to input Chinese, Japanese and Korean characters.
 
           Currently the following input methods are available in NixOS:
 
-          <itemizedlist>
-          <listitem><para>ibus: The intelligent input bus, extra input engines can be added using <literal>i18n.inputMethod.ibus.engines</literal>.</para></listitem>
-          <listitem><para>fcitx: A customizable lightweight input method, extra input engines can be added using <literal>i18n.inputMethod.fcitx.engines</literal>.</para></listitem>
-          <listitem><para>fcitx5: The next generation of fcitx, addons (including engines, dictionaries, skins) can be added using <literal>i18n.inputMethod.fcitx5.addons</literal>.</para></listitem>
-          <listitem><para>nabi: A Korean input method based on XIM. Nabi doesn't support Qt 5.</para></listitem>
-          <listitem><para>uim: The universal input method, is a library with a XIM bridge. uim mainly support Chinese, Japanese and Korean.</para></listitem>
-          <listitem><para>hime: An extremely easy-to-use input method framework.</para></listitem>
-          <listitem><para>kime: Koream IME.</para></listitem>
-          </itemizedlist>
+          - ibus: The intelligent input bus, extra input engines can be added using `i18n.inputMethod.ibus.engines`.
+          - fcitx: A customizable lightweight input method, extra input engines can be added using `i18n.inputMethod.fcitx.engines`.
+          - fcitx5: The next generation of fcitx, addons (including engines, dictionaries, skins) can be added using `i18n.inputMethod.fcitx5.addons`.
+          - nabi: A Korean input method based on XIM. Nabi doesn't support Qt 5.
+          - uim: The universal input method, is a library with a XIM bridge. uim mainly support Chinese, Japanese and Korean.
+          - hime: An extremely easy-to-use input method framework.
+          - kime: Koream IME.
         '';
       };
 
diff --git a/nixos/modules/misc/documentation.nix b/nixos/modules/misc/documentation.nix
index 251a361a580..5dcdc8f96c4 100644
--- a/nixos/modules/misc/documentation.nix
+++ b/nixos/modules/misc/documentation.nix
@@ -226,15 +226,14 @@ in
       nixos.enable = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Whether to install NixOS's own documentation.
-          <itemizedlist>
-          <listitem><para>This includes man pages like
-                    <citerefentry><refentrytitle>configuration.nix</refentrytitle><manvolnum>5</manvolnum></citerefentry> if <option>documentation.man.enable</option> is
-                    set.</para></listitem>
-          <listitem><para>This includes the HTML manual and the <command>nixos-help</command> command if
-                    <option>documentation.doc.enable</option> is set.</para></listitem>
-          </itemizedlist>
+
+          - This includes man pages like
+            {manpage}`configuration.nix(5)` if {option}`documentation.man.enable` is
+            set.
+          - This includes the HTML manual and the {command}`nixos-help` command if
+            {option}`documentation.doc.enable` is set.
         '';
       };
 
diff --git a/nixos/modules/security/acme/default.nix b/nixos/modules/security/acme/default.nix
index f85cf2fc121..4e5e3266fe1 100644
--- a/nixos/modules/security/acme/default.nix
+++ b/nixos/modules/security/acme/default.nix
@@ -576,13 +576,12 @@ let
       ocspMustStaple = mkOption {
         type = types.bool;
         inherit (defaultAndText "ocspMustStaple" false) default defaultText;
-        description = ''
+        description = lib.mdDoc ''
           Turns on the OCSP Must-Staple TLS extension.
           Make sure you know what you're doing! See:
-          <itemizedlist>
-            <listitem><para><link xlink:href="https://blog.apnic.net/2019/01/15/is-the-web-ready-for-ocsp-must-staple/"/></para></listitem>
-            <listitem><para><link xlink:href="https://blog.hboeck.de/archives/886-The-Problem-with-OCSP-Stapling-and-Must-Staple-and-why-Certificate-Revocation-is-still-broken.html"/></para></listitem>
-          </itemizedlist>
+
+          - <https://blog.apnic.net/2019/01/15/is-the-web-ready-for-ocsp-must-staple/>
+          - <https://blog.hboeck.de/archives/886-The-Problem-with-OCSP-Stapling-and-Must-Staple-and-why-Certificate-Revocation-is-still-broken.html>
         '';
       };
 
diff --git a/nixos/modules/security/tpm2.nix b/nixos/modules/security/tpm2.nix
index 375f4af1a64..903d35b3173 100644
--- a/nixos/modules/security/tpm2.nix
+++ b/nixos/modules/security/tpm2.nix
@@ -76,21 +76,11 @@ in {
 
     tctiEnvironment = {
       enable = lib.mkOption {
-        description = ''
+        description = lib.mdDoc ''
           Set common TCTI environment variables to the specified value.
           The variables are
-          <itemizedlist>
-            <listitem>
-              <para>
-                <literal>TPM2TOOLS_TCTI</literal>
-              </para>
-            </listitem>
-            <listitem>
-              <para>
-                <literal>TPM2_PKCS11_TCTI</literal>
-              </para>
-            </listitem>
-          </itemizedlist>
+          - `TPM2TOOLS_TCTI`
+          - `TPM2_PKCS11_TCTI`
         '';
         type = lib.types.bool;
         default = false;
diff --git a/nixos/modules/services/admin/meshcentral.nix b/nixos/modules/services/admin/meshcentral.nix
index e1df39716d4..7553f4922c9 100644
--- a/nixos/modules/services/admin/meshcentral.nix
+++ b/nixos/modules/services/admin/meshcentral.nix
@@ -13,15 +13,13 @@ in with lib; {
       defaultText = literalExpression "pkgs.meshcentral";
     };
     settings = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Settings for MeshCentral. Refer to upstream documentation for details:
 
-        <itemizedlist>
-          <listitem><para><link xlink:href="https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json">JSON Schema definition</link></para></listitem>
-          <listitem><para><link xlink:href="https://github.com/Ylianst/MeshCentral/blob/master/sample-config.json">simple sample configuration</link></para></listitem>
-          <listitem><para><link xlink:href="https://github.com/Ylianst/MeshCentral/blob/master/sample-config-advanced.json">complex sample configuration</link></para></listitem>
-          <listitem><para><link xlink:href="https://www.meshcommander.com/meshcentral2">Old homepage) with documentation link</link></para></listitem>
-        </itemizedlist>
+        - [JSON Schema definition](https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json)
+        - [simple sample configuration](https://github.com/Ylianst/MeshCentral/blob/master/sample-config.json)
+        - [complex sample configuration](https://github.com/Ylianst/MeshCentral/blob/master/sample-config-advanced.json)
+        - [Old homepage with documentation link](https://www.meshcommander.com/meshcentral2)
       '';
       type = types.submodule {
         freeformType = configFormat.type;
diff --git a/nixos/modules/services/hardware/upower.nix b/nixos/modules/services/hardware/upower.nix
index 54208158b1a..aacc8a63dbe 100644
--- a/nixos/modules/services/hardware/upower.nix
+++ b/nixos/modules/services/hardware/upower.nix
@@ -39,7 +39,7 @@ in
       enableWattsUpPro = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Enable the Watts Up Pro device.
 
           The Watts Up Pro contains a generic FTDI USB device without a specific
@@ -49,10 +49,8 @@ in
 
           The generic FTDI device is known to also be used on:
 
-          <itemizedlist>
-            <listitem><para>Sparkfun FT232 breakout board</para></listitem>
-            <listitem><para>Parallax Propeller</para></listitem>
-          </itemizedlist>
+          - Sparkfun FT232 breakout board
+          - Parallax Propeller
         '';
       };
 
diff --git a/nixos/modules/services/monitoring/grafana-image-renderer.nix b/nixos/modules/services/monitoring/grafana-image-renderer.nix
index d92ce5e1eef..e312d9128a4 100644
--- a/nixos/modules/services/monitoring/grafana-image-renderer.nix
+++ b/nixos/modules/services/monitoring/grafana-image-renderer.nix
@@ -62,18 +62,16 @@ in {
             mode = mkOption {
               default = "default";
               type = types.enum [ "default" "reusable" "clustered" ];
-              description = ''
-                Rendering mode of <literal>grafana-image-renderer</literal>:
-                <itemizedlist>
-                <listitem><para><literal>default:</literal> Creates on browser-instance
-                  per rendering request.</para></listitem>
-                <listitem><para><literal>reusable:</literal> One browser instance
-                  will be started and reused for each rendering request.</para></listitem>
-                <listitem><para><literal>clustered:</literal> allows to precisely
+              description = lib.mdDoc ''
+                Rendering mode of `grafana-image-renderer`:
+
+                - `default:` Creates on browser-instance
+                  per rendering request.
+                - `reusable:` One browser instance
+                  will be started and reused for each rendering request.
+                - `clustered:` allows to precisely
                   configure how many browser-instances are supposed to be used. The values
-                  for that mode can be declared in <literal>rendering.clustering</literal>.
-                  </para></listitem>
-                </itemizedlist>
+                  for that mode can be declared in `rendering.clustering`.
               '';
             };
             args = mkOption {
diff --git a/nixos/modules/services/networking/3proxy.nix b/nixos/modules/services/networking/3proxy.nix
index fb11f5bc05e..21ed1c2c947 100644
--- a/nixos/modules/services/networking/3proxy.nix
+++ b/nixos/modules/services/networking/3proxy.nix
@@ -55,35 +55,17 @@ in {
               "udppm"
             ];
             example = "proxy";
-            description = ''
+            description = lib.mdDoc ''
               Service type. The following values are valid:
 
-              <itemizedlist>
-                <listitem><para>
-                  <literal>"proxy"</literal>: HTTP/HTTPS proxy (default port 3128).
-                </para></listitem>
-                <listitem><para>
-                  <literal>"socks"</literal>: SOCKS 4/4.5/5 proxy (default port 1080).
-                </para></listitem>
-                <listitem><para>
-                  <literal>"pop3p"</literal>: POP3 proxy (default port 110).
-                </para></listitem>
-                <listitem><para>
-                  <literal>"ftppr"</literal>: FTP proxy (default port 21).
-                </para></listitem>
-                <listitem><para>
-                  <literal>"admin"</literal>: Web interface (default port 80).
-                </para></listitem>
-                <listitem><para>
-                  <literal>"dnspr"</literal>: Caching DNS proxy (default port 53).
-                </para></listitem>
-                <listitem><para>
-                  <literal>"tcppm"</literal>: TCP portmapper.
-                </para></listitem>
-                <listitem><para>
-                  <literal>"udppm"</literal>: UDP portmapper.
-                </para></listitem>
-              </itemizedlist>
+              - `"proxy"`: HTTP/HTTPS proxy (default port 3128).
+              - `"socks"`: SOCKS 4/4.5/5 proxy (default port 1080).
+              - `"pop3p"`: POP3 proxy (default port 110).
+              - `"ftppr"`: FTP proxy (default port 21).
+              - `"admin"`: Web interface (default port 80).
+              - `"dnspr"`: Caching DNS proxy (default port 53).
+              - `"tcppm"`: TCP portmapper.
+              - `"udppm"`: UDP portmapper.
             '';
           };
           bindAddress = mkOption {
@@ -113,24 +95,16 @@ in {
           auth = mkOption {
             type = types.listOf (types.enum [ "none" "iponly" "strong" ]);
             example = [ "iponly" "strong" ];
-            description = ''
+            description = lib.mdDoc ''
               Authentication type. The following values are valid:
 
-              <itemizedlist>
-                <listitem><para>
-                  <literal>"none"</literal>: disables both authentication and authorization. You can not use ACLs.
-                </para></listitem>
-                <listitem><para>
-                  <literal>"iponly"</literal>: specifies no authentication. ACLs authorization is used.
-                </para></listitem>
-                <listitem><para>
-                  <literal>"strong"</literal>: authentication by username/password. If user is not registered their access is denied regardless of ACLs.
-                </para></listitem>
-              </itemizedlist>
+              - `"none"`: disables both authentication and authorization. You can not use ACLs.
+              - `"iponly"`: specifies no authentication. ACLs authorization is used.
+              - `"strong"`: authentication by username/password. If user is not registered their access is denied regardless of ACLs.
 
               Double authentication is possible, e.g.
 
-              <programlisting>
+              ```
                 {
                   auth = [ "iponly" "strong" ];
                   acl = [
@@ -144,7 +118,7 @@ in {
                     }
                   ];
                 }
-              </programlisting>
+              ```
               In this example strong username authentication is not required to access 192.168.0.0/16.
             '';
           };
@@ -154,17 +128,11 @@ in {
                 rule = mkOption {
                   type = types.enum [ "allow" "deny" ];
                   example = "allow";
-                  description = ''
+                  description = lib.mdDoc ''
                     ACL rule. The following values are valid:
 
-                    <itemizedlist>
-                      <listitem><para>
-                        <literal>"allow"</literal>: connections allowed.
-                      </para></listitem>
-                      <listitem><para>
-                        <literal>"deny"</literal>: connections not allowed.
-                      </para></listitem>
-                    </itemizedlist>
+                    - `"allow"`: connections allowed.
+                    - `"deny"`: connections not allowed.
                   '';
                 };
                 users = mkOption {
diff --git a/nixos/modules/services/networking/nsd.nix b/nixos/modules/services/networking/nsd.nix
index 8fc171b2321..8c47ac56db8 100644
--- a/nixos/modules/services/networking/nsd.nix
+++ b/nixos/modules/services/networking/nsd.nix
@@ -213,30 +213,24 @@ let
         example = [ "192.0.2.0/24 NOKEY" "10.0.0.1-10.0.0.5 my_tsig_key_name"
                     "10.0.3.4&255.255.0.0 BLOCKED"
                   ];
-        description = ''
+        description = lib.mdDoc ''
           Listed primary servers are allowed to notify this secondary server.
 
-          Format: <literal>&lt;ip&gt; &lt;key-name | NOKEY | BLOCKED&gt;</literal>
+          Format: `<ip> <key-name | NOKEY | BLOCKED>`
 
-          <literal>&lt;ip&gt;</literal> either a plain IPv4/IPv6 address or range.
+          `<ip>` either a plain IPv4/IPv6 address or range.
           Valid patters for ranges:
-          <itemizedlist>
-            <listitem><para><literal>10.0.0.0/24</literal>: via subnet size</para></listitem>
-            <listitem><para><literal>10.0.0.0&amp;255.255.255.0</literal>: via subnet mask</para></listitem>
-            <listitem><para><literal>10.0.0.1-10.0.0.254</literal>: via range</para></listitem>
-          </itemizedlist>
+          * `10.0.0.0/24`: via subnet size
+          * `10.0.0.0&255.255.255.0`: via subnet mask
+          * `10.0.0.1-10.0.0.254`: via range
 
           A optional port number could be added with a '@':
-          <itemizedlist>
-            <listitem><para><literal>2001:1234::1@1234</literal></para></listitem>
-          </itemizedlist>
-
-          <literal>&lt;key-name | NOKEY | BLOCKED&gt;</literal>
-          <itemizedlist>
-            <listitem><para><literal>&lt;key-name&gt;</literal> will use the specified TSIG key</para></listitem>
-            <listitem><para><literal>NOKEY</literal> no TSIG signature is required</para></listitem>
-            <listitem><para><literal>BLOCKED</literal>notifies from non-listed or blocked IPs will be ignored</para></listitem>
-          </itemizedlist>
+          * `2001:1234::1@1234`
+
+          `<key-name | NOKEY | BLOCKED>`
+          * `<key-name>` will use the specified TSIG key
+          * `NOKEY` no TSIG signature is required
+          * `BLOCKED`notifies from non-listed or blocked IPs will be ignored
         '';
       };
 
@@ -350,19 +344,17 @@ let
         type = types.listOf types.str;
         default = [];
         example = [ "10.0.0.1@3721 my_key" "::5 NOKEY" ];
-        description = ''
+        description = lib.mdDoc ''
           This primary server will notify all given secondary servers about
           zone changes.
 
-          Format: <literal>&lt;ip&gt; &lt;key-name | NOKEY&gt;</literal>
+          Format: `<ip> <key-name | NOKEY>`
 
-          <literal>&lt;ip&gt;</literal> a plain IPv4/IPv6 address with on optional port number (ip@port)
+          `<ip>` a plain IPv4/IPv6 address with on optional port number (ip@port)
 
-          <literal>&lt;key-name | NOKEY&gt;</literal>
-          <itemizedlist>
-            <listitem><para><literal>&lt;key-name&gt;</literal> sign notifies with the specified key</para></listitem>
-            <listitem><para><literal>NOKEY</literal> don't sign notifies</para></listitem>
-          </itemizedlist>
+          `<key-name | NOKEY>`
+          - `<key-name>` sign notifies with the specified key
+          - `NOKEY` don't sign notifies
         '';
       };
 
diff --git a/nixos/modules/services/web-apps/documize.nix b/nixos/modules/services/web-apps/documize.nix
index 4353e3c2445..b1c2225cfa8 100644
--- a/nixos/modules/services/web-apps/documize.nix
+++ b/nixos/modules/services/web-apps/documize.nix
@@ -85,37 +85,24 @@ in {
     dbtype = mkOption {
       type = types.enum [ "mysql" "percona" "mariadb" "postgresql" "sqlserver" ];
       default = "postgresql";
-      description = ''
-        Specify the database provider:
-        <simplelist type='inline'>
-          <member><literal>mysql</literal></member>
-          <member><literal>percona</literal></member>
-          <member><literal>mariadb</literal></member>
-          <member><literal>postgresql</literal></member>
-          <member><literal>sqlserver</literal></member>
-        </simplelist>
+      description = lib.mdDoc ''
+        Specify the database provider: `mysql`, `percona`, `mariadb`, `postgresql`, `sqlserver`
       '';
     };
 
     db = mkOption {
       type = types.str;
-      description = ''
+      description = lib.mdDoc ''
         Database specific connection string for example:
-        <itemizedlist>
-        <listitem><para>MySQL/Percona/MariaDB:
-          <literal>user:password@tcp(host:3306)/documize</literal>
-        </para></listitem>
-        <listitem><para>MySQLv8+:
-          <literal>user:password@tcp(host:3306)/documize?allowNativePasswords=true</literal>
-        </para></listitem>
-        <listitem><para>PostgreSQL:
-          <literal>host=localhost port=5432 dbname=documize user=admin password=secret sslmode=disable</literal>
-        </para></listitem>
-        <listitem><para>MSSQL:
-          <literal>sqlserver://username:password@localhost:1433?database=Documize</literal> or
-          <literal>sqlserver://sa@localhost/SQLExpress?database=Documize</literal>
-        </para></listitem>
-        </itemizedlist>
+        - MySQL/Percona/MariaDB:
+          `user:password@tcp(host:3306)/documize`
+        - MySQLv8+:
+          `user:password@tcp(host:3306)/documize?allowNativePasswords=true`
+        - PostgreSQL:
+          `host=localhost port=5432 dbname=documize user=admin password=secret sslmode=disable`
+        - MSSQL:
+          `sqlserver://username:password@localhost:1433?database=Documize` or
+          `sqlserver://sa@localhost/SQLExpress?database=Documize`
       '';
     };
 
diff --git a/nixos/modules/services/web-apps/nextcloud.nix b/nixos/modules/services/web-apps/nextcloud.nix
index 84c6b077d03..02434bf2f7c 100644
--- a/nixos/modules/services/web-apps/nextcloud.nix
+++ b/nixos/modules/services/web-apps/nextcloud.nix
@@ -533,25 +533,23 @@ in {
         The nextcloud-occ program preconfigured to target this Nextcloud instance.
       '';
     };
-    globalProfiles = mkEnableOption "global profiles" // {
-      description = ''
-        Makes user-profiles globally available under <literal>nextcloud.tld/u/user.name</literal>.
+    globalProfiles = mkEnableOption (lib.mdDoc "global profiles") // {
+      description = lib.mdDoc ''
+        Makes user-profiles globally available under `nextcloud.tld/u/user.name`.
         Even though it's enabled by default in Nextcloud, it must be explicitly enabled
         here because it has the side-effect that personal information is even accessible to
         unauthenticated users by default.
 
         By default, the following properties are set to “Show to everyone”
         if this flag is enabled:
-        <itemizedlist>
-        <listitem><para>About</para></listitem>
-        <listitem><para>Full name</para></listitem>
-        <listitem><para>Headline</para></listitem>
-        <listitem><para>Organisation</para></listitem>
-        <listitem><para>Profile picture</para></listitem>
-        <listitem><para>Role</para></listitem>
-        <listitem><para>Twitter</para></listitem>
-        <listitem><para>Website</para></listitem>
-        </itemizedlist>
+        - About
+        - Full name
+        - Headline
+        - Organisation
+        - Profile picture
+        - Role
+        - Twitter
+        - Website
 
         Only has an effect in Nextcloud 23 and later.
       '';
diff --git a/nixos/modules/services/web-apps/wiki-js.nix b/nixos/modules/services/web-apps/wiki-js.nix
index c648cfff6ce..7807fa4a66a 100644
--- a/nixos/modules/services/web-apps/wiki-js.nix
+++ b/nixos/modules/services/web-apps/wiki-js.nix
@@ -93,17 +93,15 @@ in {
           };
         };
       };
-      description = ''
-        Settings to configure <literal>wiki-js</literal>. This directly
-        corresponds to <link xlink:href="https://docs.requarks.io/install/config">the upstream configuration options</link>.
+      description = lib.mdDoc ''
+        Settings to configure `wiki-js`. This directly
+        corresponds to [the upstream configuration options](https://docs.requarks.io/install/config).
 
         Secrets can be injected via the environment by
-        <itemizedlist>
-          <listitem><para>specifying <xref linkend="opt-services.wiki-js.environmentFile"/>
-          to contain secrets</para></listitem>
-          <listitem><para>and setting sensitive values to <literal>$(ENVIRONMENT_VAR)</literal>
-          with this value defined in the environment-file.</para></listitem>
-        </itemizedlist>
+        - specifying [](#opt-services.wiki-js.environmentFile)
+          to contain secrets
+        - and setting sensitive values to `$(ENVIRONMENT_VAR)`
+          with this value defined in the environment-file.
       '';
     };
   };
diff --git a/nixos/modules/services/web-servers/nginx/default.nix b/nixos/modules/services/web-servers/nginx/default.nix
index 0c4b2246a1b..b3c4c21afc0 100644
--- a/nixos/modules/services/web-servers/nginx/default.nix
+++ b/nixos/modules/services/web-servers/nginx/default.nix
@@ -499,21 +499,16 @@ in
       config = mkOption {
         type = types.str;
         default = "";
-        description = ''
-          Verbatim <filename>nginx.conf</filename> configuration.
+        description = lib.mdDoc ''
+          Verbatim {file}`nginx.conf` configuration.
           This is mutually exclusive to any other config option for
-          <filename>nginx.conf</filename> except for
-          <itemizedlist>
-          <listitem><para><xref linkend="opt-services.nginx.appendConfig"/>
-          </para></listitem>
-          <listitem><para><xref linkend="opt-services.nginx.httpConfig"/>
-          </para></listitem>
-          <listitem><para><xref linkend="opt-services.nginx.logError"/>
-          </para></listitem>
-          </itemizedlist>
+          {file}`nginx.conf` except for
+          - [](#opt-services.nginx.appendConfig)
+          - [](#opt-services.nginx.httpConfig)
+          - [](#opt-services.nginx.logError)
 
           If additional verbatim config in addition to other options is needed,
-          <xref linkend="opt-services.nginx.appendConfig"/> should be used instead.
+          [](#opt-services.nginx.appendConfig) should be used instead.
         '';
       };
 
diff --git a/nixos/modules/system/boot/loader/grub/grub.nix b/nixos/modules/system/boot/loader/grub/grub.nix
index 1ad7cd81094..0af7f9729b0 100644
--- a/nixos/modules/system/boot/loader/grub/grub.nix
+++ b/nixos/modules/system/boot/loader/grub/grub.nix
@@ -622,37 +622,35 @@ in
       efiInstallAsRemovable = mkOption {
         default = false;
         type = types.bool;
-        description = ''
-          Whether to invoke <literal>grub-install</literal> with
-          <literal>--removable</literal>.
+        description = lib.mdDoc ''
+          Whether to invoke `grub-install` with
+          `--removable`.
 
           Unless you turn this on, GRUB will install itself somewhere in
-          <literal>boot.loader.efi.efiSysMountPoint</literal> (exactly where
+          `boot.loader.efi.efiSysMountPoint` (exactly where
           depends on other config variables). If you've set
-          <literal>boot.loader.efi.canTouchEfiVariables</literal> *AND* you
+          `boot.loader.efi.canTouchEfiVariables` *AND* you
           are currently booted in UEFI mode, then GRUB will use
-          <literal>efibootmgr</literal> to modify the boot order in the
+          `efibootmgr` to modify the boot order in the
           EFI variables of your firmware to include this location. If you are
           *not* booted in UEFI mode at the time GRUB is being installed, the
           NVRAM will not be modified, and your system will not find GRUB at
           boot time. However, GRUB will still return success so you may miss
-          the warning that gets printed ("<literal>efibootmgr: EFI variables
-          are not supported on this system.</literal>").
+          the warning that gets printed ("`efibootmgr: EFI variables
+          are not supported on this system.`").
 
           If you turn this feature on, GRUB will install itself in a
-          special location within <literal>efiSysMountPoint</literal> (namely
-          <literal>EFI/boot/boot$arch.efi</literal>) which the firmwares
+          special location within `efiSysMountPoint` (namely
+          `EFI/boot/boot$arch.efi`) which the firmwares
           are hardcoded to try first, regardless of NVRAM EFI variables.
 
           To summarize, turn this on if:
-          <itemizedlist>
-            <listitem><para>You are installing NixOS and want it to boot in UEFI mode,
-            but you are currently booted in legacy mode</para></listitem>
-            <listitem><para>You want to make a drive that will boot regardless of
-            the NVRAM state of the computer (like a USB "removable" drive)</para></listitem>
-            <listitem><para>You simply dislike the idea of depending on NVRAM
-            state to make your drive bootable</para></listitem>
-          </itemizedlist>
+          - You are installing NixOS and want it to boot in UEFI mode,
+            but you are currently booted in legacy mode
+          - You want to make a drive that will boot regardless of
+            the NVRAM state of the computer (like a USB "removable" drive)
+          - You simply dislike the idea of depending on NVRAM
+            state to make your drive bootable
         '';
       };
 
diff --git a/nixos/modules/system/boot/loader/grub/memtest.nix b/nixos/modules/system/boot/loader/grub/memtest.nix
index 150068e0e95..ccb6e8cc3ca 100644
--- a/nixos/modules/system/boot/loader/grub/memtest.nix
+++ b/nixos/modules/system/boot/loader/grub/memtest.nix
@@ -31,45 +31,29 @@ in
         default = [];
         example = [ "console=ttyS0,115200" ];
         type = types.listOf types.str;
-        description = ''
+        description = lib.mdDoc ''
           Parameters added to the Memtest86+ command line. As of memtest86+ 5.01
           the following list of (apparently undocumented) parameters are
           accepted:
 
-          <itemizedlist>
-
-          <listitem>
-            <para><literal>console=...</literal>, set up a serial console.
+          - `console=...`, set up a serial console.
             Examples:
-            <literal>console=ttyS0</literal>,
-            <literal>console=ttyS0,9600</literal> or
-            <literal>console=ttyS0,115200n8</literal>.</para>
-          </listitem>
-
-          <listitem>
-            <para><literal>btrace</literal>, enable boot trace.</para>
-          </listitem>
-
-          <listitem>
-            <para><literal>maxcpus=N</literal>, limit number of CPUs.</para>
-          </listitem>
-
-          <listitem>
-            <para><literal>onepass</literal>, run one pass and exit if there
-            are no errors.</para>
-          </listitem>
-
-          <listitem>
-            <para><literal>tstlist=...</literal>, list of tests to run.
-            Example: <literal>0,1,2</literal>.</para>
-          </listitem>
-
-          <listitem>
-            <para><literal>cpumask=...</literal>, set a CPU mask, to select CPUs
-            to use for testing.</para>
-          </listitem>
-
-          </itemizedlist>
+            `console=ttyS0`,
+            `console=ttyS0,9600` or
+            `console=ttyS0,115200n8`.
+
+          - `btrace`, enable boot trace.
+
+          - `maxcpus=N`, limit number of CPUs.
+
+          - `onepass`, run one pass and exit if there
+            are no errors.
+
+          - `tstlist=...`, list of tests to run.
+            Example: `0,1,2`.
+
+          - `cpumask=...`, set a CPU mask, to select CPUs
+            to use for testing.
 
           This list of command line options was obtained by reading the
           Memtest86+ source code.
diff --git a/nixos/modules/system/boot/loader/systemd-boot/systemd-boot.nix b/nixos/modules/system/boot/loader/systemd-boot/systemd-boot.nix
index baf0a9fe9c4..a9d43d027e0 100644
--- a/nixos/modules/system/boot/loader/systemd-boot/systemd-boot.nix
+++ b/nixos/modules/system/boot/loader/systemd-boot/systemd-boot.nix
@@ -104,29 +104,15 @@ in {
 
       type = types.enum [ "0" "1" "2" "auto" "max" "keep" ];
 
-      description = ''
+      description = lib.mdDoc ''
         The resolution of the console. The following values are valid:
 
-        <itemizedlist>
-          <listitem><para>
-            <literal>"0"</literal>: Standard UEFI 80x25 mode
-          </para></listitem>
-          <listitem><para>
-            <literal>"1"</literal>: 80x50 mode, not supported by all devices
-          </para></listitem>
-          <listitem><para>
-            <literal>"2"</literal>: The first non-standard mode provided by the device firmware, if any
-          </para></listitem>
-          <listitem><para>
-            <literal>"auto"</literal>: Pick a suitable mode automatically using heuristics
-          </para></listitem>
-          <listitem><para>
-            <literal>"max"</literal>: Pick the highest-numbered available mode
-          </para></listitem>
-          <listitem><para>
-            <literal>"keep"</literal>: Keep the mode selected by firmware (the default)
-          </para></listitem>
-        </itemizedlist>
+        - `"0"`: Standard UEFI 80x25 mode
+        - `"1"`: 80x50 mode, not supported by all devices
+        - `"2"`: The first non-standard mode provided by the device firmware, if any
+        - `"auto"`: Pick a suitable mode automatically using heuristics
+        - `"max"`: Pick the highest-numbered available mode
+        - `"keep"`: Keep the mode selected by firmware (the default)
       '';
     };
 
diff --git a/nixos/modules/system/boot/stage-1.nix b/nixos/modules/system/boot/stage-1.nix
index 66b51cd7260..c24e6e27ee7 100644
--- a/nixos/modules/system/boot/stage-1.nix
+++ b/nixos/modules/system/boot/stage-1.nix
@@ -613,14 +613,12 @@ in
       );
       defaultText = literalMD "`zstd` if the kernel supports it (5.9+), `gzip` if not";
       type = types.either types.str (types.functionTo types.str);
-      description = ''
+      description = lib.mdDoc ''
         The compressor to use on the initrd image. May be any of:
 
-        <itemizedlist>
-         <listitem><para>The name of one of the predefined compressors, see <filename>pkgs/build-support/kernel/initrd-compressor-meta.nix</filename> for the definitions.</para></listitem>
-         <listitem><para>A function which, given the nixpkgs package set, returns the path to a compressor tool, e.g. <literal>pkgs: "''${pkgs.pigz}/bin/pigz"</literal></para></listitem>
-         <listitem><para>(not recommended, because it does not work when cross-compiling) the full path to a compressor tool, e.g. <literal>"''${pkgs.pigz}/bin/pigz"</literal></para></listitem>
-        </itemizedlist>
+        - The name of one of the predefined compressors, see {file}`pkgs/build-support/kernel/initrd-compressor-meta.nix` for the definitions.
+        - A function which, given the nixpkgs package set, returns the path to a compressor tool, e.g. `pkgs: "''${pkgs.pigz}/bin/pigz"`
+        - (not recommended, because it does not work when cross-compiling) the full path to a compressor tool, e.g. `"''${pkgs.pigz}/bin/pigz"`
 
         The given program should read data from stdin and write it to stdout compressed.
       '';
@@ -662,16 +660,14 @@ in
       default = true;
       type = types.bool;
       description =
-        ''
+        lib.mdDoc ''
           Verbosity of the initrd. Please note that disabling verbosity removes
           only the mandatory messages generated by the NixOS scripts. For a
           completely silent boot, you might also want to set the two following
           configuration options:
 
-          <itemizedlist>
-            <listitem><para><literal>boot.consoleLogLevel = 0;</literal></para></listitem>
-            <listitem><para><literal>boot.kernelParams = [ "quiet" "udev.log_level=3" ];</literal></para></listitem>
-          </itemizedlist>
+          - `boot.consoleLogLevel = 0;`
+          - `boot.kernelParams = [ "quiet" "udev.log_level=3" ];`
         '';
     };