nixos/*: convert options with listings

minor rendering changes.

nixos/modules/hardware/tuxedo-keyboard.nix

···
 in
   {
     options.hardware.tuxedo-keyboard = {
-      enable = mkEnableOption ''
+      enable = mkEnableOption (lib.mdDoc ''
           Enables the tuxedo-keyboard driver.
 
-          To configure the driver, pass the options to the <option>boot.kernelParams</option> configuration.
+          To configure the driver, pass the options to the {option}`boot.kernelParams` configuration.
           There are several parameters you can change. It's best to check at the source code description which options are supported.
-          You can find all the supported parameters at: <link xlink:href="https://github.com/tuxedocomputers/tuxedo-keyboard#kernelparam"/>
+          You can find all the supported parameters at: <https://github.com/tuxedocomputers/tuxedo-keyboard#kernelparam>
 
-          In order to use the <literal>custom</literal> lighting with the maximumg brightness and a color of <literal>0xff0a0a</literal> one would put pass <option>boot.kernelParams</option> like this:
+          In order to use the `custom` lighting with the maximumg brightness and a color of `0xff0a0a` one would put pass {option}`boot.kernelParams` like this:
 
-          <programlisting>
+          ```
           boot.kernelParams = [
            "tuxedo_keyboard.mode=0"
            "tuxedo_keyboard.brightness=255"
            "tuxedo_keyboard.color_left=0xff0a0a"
           ];
-          </programlisting>
-      '';
+          ```
+      '');
     };
 
     config = mkIf cfg.enable

nixos/modules/misc/label.nix

···
 
     nixos.label = mkOption {
       type = types.strMatching "[a-zA-Z0-9:_\\.-]*";
-      description = ''
+      description = lib.mdDoc ''
         NixOS version name to be used in the names of generated
         outputs and boot labels.
 
···
         this is the option for you.
 
         It can only contain letters, numbers and the following symbols:
-        <literal>:</literal>, <literal>_</literal>, <literal>.</literal> and <literal>-</literal>.
+        `:`, `_`, `.` and `-`.
 
-        The default is <option>system.nixos.tags</option> separated by
-        "-" + "-" + <envar>NIXOS_LABEL_VERSION</envar> environment
+        The default is {option}`system.nixos.tags` separated by
+        "-" + "-" + {env}`NIXOS_LABEL_VERSION` environment
         variable (defaults to the value of
-        <option>system.nixos.version</option>).
+        {option}`system.nixos.version`).
 
-        Can be overriden by setting <envar>NIXOS_LABEL</envar>.
+        Can be overriden by setting {env}`NIXOS_LABEL`.
 
         Useful for not loosing track of configurations built from different
         nixos branches/revisions, e.g.:
 
-        <programlisting>
+        ```
         #!/bin/sh
         today=`date +%Y%m%d`
         branch=`(cd nixpkgs ; git branch 2>/dev/null | sed -n '/^\* / { s|^\* ||; p; }')`
         revision=`(cd nixpkgs ; git rev-parse HEAD)`
         export NIXOS_LABEL_VERSION="$today.$branch-''${revision:0:7}"
         nixos-rebuild switch
-        </programlisting>
+        ```
       '';
     };
 
···
       type = types.listOf types.str;
       default = [];
       example = [ "with-xen" ];
-      description = ''
+      description = lib.mdDoc ''
         Strings to prefix to the default
-        <option>system.nixos.label</option>.
+        {option}`system.nixos.label`.
 
         Useful for not loosing track of configurations built with
         different options, e.g.:
 
-        <programlisting>
+        ```
         {
           system.nixos.tags = [ "with-xen" ];
           virtualisation.xen.enable = true;
         }
-        </programlisting>
+        ```
       '';
     };
 

nixos/modules/misc/nixpkgs.nix

···
       defaultText = lib.literalMD ''
         Traditionally `builtins.currentSystem`, but unset when invoking NixOS through `lib.nixosSystem`.
       '';
-      description = ''
+      description = lib.mdDoc ''
         This option does not need to be specified for NixOS configurations
-        with a recently generated <literal>hardware-configuration.nix</literal>.
+        with a recently generated `hardware-configuration.nix`.
 
         Specifies the Nix platform type on which NixOS should be built.
-        It is better to specify <literal>nixpkgs.localSystem</literal> instead.
-        <programlisting>
+        It is better to specify `nixpkgs.localSystem` instead.
+        ```
         {
           nixpkgs.system = ..;
         }
-        </programlisting>
+        ```
         is the same as
-        <programlisting>
+        ```
         {
           nixpkgs.localSystem.system = ..;
         }
-        </programlisting>
-        See <literal>nixpkgs.localSystem</literal> for more information.
+        ```
+        See `nixpkgs.localSystem` for more information.
 
-        Ignored when <literal>nixpkgs.pkgs</literal>, <literal>nixpkgs.localSystem</literal> or <literal>nixpkgs.hostPlatform</literal> is set.
+        Ignored when `nixpkgs.pkgs`, `nixpkgs.localSystem` or `nixpkgs.hostPlatform` is set.
       '';
     };
   };

nixos/modules/services/backup/duplicity.nix

···
     secretFile = mkOption {
       type = types.nullOr types.path;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Path of a file containing secrets (gpg passphrase, access key...) in
         the format of EnvironmentFile as described by
-        <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. For example:
-        <programlisting>
+        {manpage}`systemd.exec(5)`. For example:
+        ```
         PASSPHRASE=«...»
         AWS_ACCESS_KEY_ID=«...»
         AWS_SECRET_ACCESS_KEY=«...»
-        </programlisting>
+        ```
       '';
     };
 

nixos/modules/services/databases/cockroachdb.nix

···
       locality = mkOption {
         type = types.nullOr types.str;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           An ordered, comma-separated list of key-value pairs that describe the
           topography of the machine. Topography might include country,
           datacenter or rack designations. Data is automatically replicated to
···
           like datacenter.  The tiers and order must be the same on all nodes.
           Including more tiers is better than including fewer. For example:
 
-          <programlisting>
+          ```
               country=us,region=us-west,datacenter=us-west-1b,rack=12
               country=ca,region=ca-east,datacenter=ca-east-2,rack=4
 
               planet=earth,province=manitoba,colo=secondary,power=3
-          </programlisting>
+          ```
         '';
       };
 

nixos/modules/services/development/zammad.nix

···
         type = types.nullOr types.path;
         default = null;
         example = "/run/keys/secret_key_base";
-        description = ''
+        description = lib.mdDoc ''
           The path to a file containing the
-          <literal>secret_key_base</literal> secret.
+          `secret_key_base` secret.
 
-          Zammad uses <literal>secret_key_base</literal> to encrypt
+          Zammad uses `secret_key_base` to encrypt
           the cookie store, which contains session data, and to digest
           user auth tokens.
 
           Needs to be a 64 byte long string of hexadecimal
           characters. You can generate one by running
 
-          <programlisting>
+          ```
           openssl rand -hex 64 >/path/to/secret_key_base_file
-          </programlisting>
+          ```
 
           This should be a string, not a nix path, since nix paths are
           copied into the world-readable nix store.

nixos/modules/services/hardware/lcd.nix

···
         usbPermissions = mkOption {
           type = bool;
           default = false;
-          description = ''
+          description = lib.mdDoc ''
             Set group-write permissions on a USB device.
 
             A USB connected LCD panel will most likely require having its
             permissions modified for lcdd to write to it. Enabling this option
             sets group-write permissions on the device identified by
-            <option>services.hardware.lcd.usbVid</option> and
-            <option>services.hardware.lcd.usbPid</option>. In order to find the
-            values, you can run the <command>lsusb</command> command. Example
+            {option}`services.hardware.lcd.usbVid` and
+            {option}`services.hardware.lcd.usbPid`. In order to find the
+            values, you can run the {command}`lsusb` command. Example
             output:
 
-            <programlisting>
+            ```
             Bus 005 Device 002: ID 0403:c630 Future Technology Devices International, Ltd lcd2usb interface
-            </programlisting>
+            ```
 
             In this case the vendor id is 0403 and the product id is c630.
           '';

nixos/modules/services/logging/awstats.nix

···
       logFile = mkOption {
         type = types.str;
         example = "/var/log/nginx/access.log";
-        description = ''
+        description = lib.mdDoc ''
           The log file to be scanned.
 
           For mail, set this to
-          <programlisting>
+          ```
           journalctl $OLD_CURSOR -u postfix.service | ''${pkgs.perl}/bin/perl ''${pkgs.awstats.out}/share/awstats/tools/maillogconvert.pl standard |
-          </programlisting>
+          ```
         '';
       };
 
       logFormat = mkOption {
         type = types.str;
         default = "1";
-        description = ''
+        description = lib.mdDoc ''
           The log format being used.
 
           For mail, set this to
-          <programlisting>
+          ```
           %time2 %email %email_r %host %host_r %method %url %code %bytesd
-          </programlisting>
+          ```
         '';
       };
 

nixos/modules/services/matrix/dendrite.nix

···
       type = lib.types.nullOr lib.types.path;
       example = "/var/lib/dendrite/registration_secret";
       default = null;
-      description = ''
-        Environment file as defined in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+      description = lib.mdDoc ''
+        Environment file as defined in {manpage}`systemd.exec(5)`.
         Secrets may be passed to the service without adding them to the world-readable
         Nix store, by specifying placeholder variables as the option value in Nix and
         setting these variables accordingly in the environment file. Currently only used
         for the registration secret to allow secure registration when
         client_api.registration_disabled is true.
 
-        <programlisting>
+        ```
           # snippet of dendrite-related config
           services.dendrite.settings.client_api.registration_shared_secret = "$REGISTRATION_SHARED_SECRET";
-        </programlisting>
+        ```
 
-        <programlisting>
+        ```
           # content of the environment file
           REGISTRATION_SHARED_SECRET=verysecretpassword
-        </programlisting>
+        ```
 
         Note that this file needs to be available on the host on which
-        <literal>dendrite</literal> is running.
+        `dendrite` is running.
       '';
     };
     loadCredential = lib.mkOption {

nixos/modules/services/misc/gitit.nix

···
       mimeTypesFile = mkOption {
         type = types.path;
         default = "/etc/mime/types.info";
-        description = ''
+        description = lib.mdDoc ''
           Specifies the path of a file containing mime type mappings.  Each
           line of the file should contain two fields, separated by whitespace.
           The first field is the mime type, the second is a file extension.
           For example:
-<programlisting>
-video/x-ms-wmx  wmx
-</programlisting>
+          ```
+          video/x-ms-wmx  wmx
+          ```
           If the file is not found, some simple defaults will be used.
         '';
       };

nixos/modules/services/misc/sssd.nix

···
       environmentFile = mkOption {
         type = types.nullOr types.path;
         default = null;
-        description = ''
-          Environment file as defined in <citerefentry>
-          <refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum>
-          </citerefentry>.
+        description = lib.mdDoc ''
+          Environment file as defined in {manpage}`systemd.exec(5)`.
 
           Secrets may be passed to the service without adding them to the world-readable
           Nix store, by specifying placeholder variables as the option value in Nix and
           setting these variables accordingly in the environment file.
 
-          <programlisting>
+          ```
             # snippet of sssd-related config
             [domain/LDAP]
             ldap_default_authtok = $SSSD_LDAP_DEFAULT_AUTHTOK
-          </programlisting>
+          ```
 
-          <programlisting>
+          ```
             # contents of the environment file
             SSSD_LDAP_DEFAULT_AUTHTOK=verysecretpassword
-          </programlisting>
+          ```
         '';
       };
     };

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

···
       type = types.path;
       default = "/var/run/dovecot/stats";
       example = "/var/run/dovecot2/old-stats";
-      description = ''
+      description = lib.mdDoc ''
         Path under which the stats socket is placed.
         The user/group under which the exporter runs,
         should be able to access the socket in order
         to scrape the metrics successfully.
 
         Please keep in mind that the stats module has changed in
-        <link xlink:href="https://wiki2.dovecot.org/Upgrading/2.3">Dovecot 2.3+</link> which
-        is not <link xlink:href="https://github.com/kumina/dovecot_exporter/issues/8">compatible with this exporter</link>.
+        [Dovecot 2.3+](https://wiki2.dovecot.org/Upgrading/2.3) which
+        is not [compatible with this exporter](https://github.com/kumina/dovecot_exporter/issues/8).
 
         The following extra config has to be passed to Dovecot to ensure that recent versions
         work with this exporter:
-        <programlisting>
+        ```
         {
           services.prometheus.exporters.dovecot.enable = true;
           services.prometheus.exporters.dovecot.socketPath = "/var/run/dovecot2/old-stats";
···
             }
           ''';
         }
-        </programlisting>
+        ```
       '';
     };
     scopes = mkOption {

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

···
           detectionDir = "/path/to/Maildir/new";
         } ]
       '';
-      description = ''
+      description = lib.mdDoc ''
         List of servers that should be probed.
 
-        <emphasis>Note:</emphasis> if your mailserver has <citerefentry><refentrytitle>rspamd</refentrytitle><manvolnum>8</manvolnum></citerefentry> configured,
+        *Note:* if your mailserver has {manpage}`rspamd(8)` configured,
         it can happen that emails from this exporter are marked as spam.
 
         It's possible to work around the issue with a config like this:
-        <programlisting>
+        ```
         {
           services.rspamd.locals."multimap.conf".text = '''
             ALLOWLIST_PROMETHEUS {
···
             }
           ''';
         }
-        </programlisting>
+        ```
       '';
     };
   };

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

···
     ldapCredentialFile = mkOption {
       type = types.path;
       example = "/run/keys/ldap_pass";
-      description = ''
+      description = lib.mdDoc ''
         Environment file to contain the credentials to authenticate against
-        <literal>openldap</literal>.
+        `openldap`.
 
         The file should look like this:
-        <programlisting>
+        ```
         ---
         ldapUser: "cn=monitoring,cn=Monitor"
         ldapPass: "secret"
-        </programlisting>
+        ```
       '';
     };
     protocol = mkOption {

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

···
       type = types.nullOr types.path;
       default = null;
       example = "/root/prometheus-postgres-exporter.env";
-      description = ''
-        Environment file as defined in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+      description = lib.mdDoc ''
+        Environment file as defined in {manpage}`systemd.exec(5)`.
 
         Secrets may be passed to the service without adding them to the
         world-readable Nix store, by specifying placeholder variables as
···
 
         Environment variables from this file will be interpolated into the
         config file using envsubst with this syntax:
-        <literal>$ENVIRONMENT ''${VARIABLE}</literal>
+        `$ENVIRONMENT ''${VARIABLE}`
 
         The main use is to set the DATA_SOURCE_NAME that contains the
         postgres password
···
         note that contents from this file will override dataSourceName
         if you have set it from nix.
 
-        <programlisting>
+        ```
           # Content of the environment file
           DATA_SOURCE_NAME=postgresql://username:password@localhost:5432/postgres?sslmode=disable
-        </programlisting>
+        ```
 
         Note that this file needs to be available on the host on which
         this exporter is running.

nixos/modules/services/network-filesystems/litestream/default.nix

···
       type = types.nullOr types.path;
       default = null;
       example = "/run/secrets/litestream";
-      description = ''
-        Environment file as defined in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+      description = lib.mdDoc ''
+        Environment file as defined in {manpage}`systemd.exec(5)`.
 
         Secrets may be passed to the service without adding them to the
         world-readable Nix store, by specifying placeholder variables as
···
         variable values. If no value is set then it will be replaced with an
         empty string.
 
-        <programlisting>
+        ```
           # Content of the environment file
           LITESTREAM_ACCESS_KEY_ID=AKIAxxxxxxxxxxxxxxxx
           LITESTREAM_SECRET_ACCESS_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/xxxxxxxxx
-        </programlisting>
+        ```
 
         Note that this file needs to be available on the host on which
         this exporter is running.

nixos/modules/services/networking/3proxy.nix

···
       type = types.nullOr types.path;
       default = null;
       example = "/var/lib/3proxy/3proxy.passwd";
-      description = ''
+      description = lib.mdDoc ''
         Load users and passwords from this file.
 
         Example users file with plain-text passwords:
 
-        <programlisting>
+        ```
           test1:CL:password1
           test2:CL:password2
-        </programlisting>
+        ```
 
         Example users file with md5-crypted passwords:
 
-        <programlisting>
+        ```
           test1:CR:$1$tFkisVd2$1GA8JXkRmTXdLDytM/i3a1
           test2:CR:$1$rkpibm5J$Aq1.9VtYAn0JrqZ8M.1ME.
-        </programlisting>
+        ```
 
         You can generate md5-crypted passwords via https://unix4lyfe.org/crypt/
         Note that htpasswd tool generates incompatible md5-crypted passwords.
-        Consult <link xlink:href="https://github.com/z3APA3A/3proxy/wiki/How-To-(incomplete)#USERS">documentation</link> for more information.
+        Consult [documentation](https://github.com/z3APA3A/3proxy/wiki/How-To-%28incomplete%29#USERS) for more information.
       '';
     };
     services = mkOption {

nixos/modules/services/networking/firefox-syncserver.nix

···
 {
   options = {
     services.firefox-syncserver = {
-      enable = lib.mkEnableOption ''
+      enable = lib.mkEnableOption (lib.mdDoc ''
         the Firefox Sync storage service.
 
         Out of the box this will not be very useful unless you also configure at least
         one service and one nodes by inserting them into the mysql database manually, e.g.
         by running
 
-        <programlisting>
+        ```
           INSERT INTO `services` (`id`, `service`, `pattern`) VALUES ('1', 'sync-1.5', '{node}/1.5/{uid}');
           INSERT INTO `nodes` (`id`, `service`, `node`, `available`, `current_load`,
               `capacity`, `downed`, `backoff`)
             VALUES ('1', '1', 'https://mydomain.tld', '1', '0', '10', '0', '0');
-        </programlisting>
+        ```
 
-        <option>${opt.singleNode.enable}</option> does this automatically when enabled
-      '';
+        {option}`${opt.singleNode.enable}` does this automatically when enabled
+      '');
 
       package = lib.mkOption {
         type = lib.types.package;

nixos/modules/services/networking/hylafax/options.nix

···
     userAccessFile = mkOption {
       type = path;
       default = "/etc/hosts.hfaxd";
-      description = ''
-        The <filename>hosts.hfaxd</filename>
+      description = lib.mdDoc ''
+        The {file}`hosts.hfaxd`
         file entry in the spooling area
         will be symlinked to the location given here.
         This file must exist and be
-        readable only by the <literal>uucp</literal> user.
+        readable only by the `uucp` user.
         See hosts.hfaxd(5) for details.
         This configuration permits access for all users:
-        <programlisting>
+        ```
           environment.etc."hosts.hfaxd" = {
             mode = "0600";
             user = "uucp";
             text = ".*";
           };
-        </programlisting>
+        ```
         Note that host-based access can be controlled with
-        <option>config.systemd.sockets.hylafax-hfaxd.listenStreams</option>;
+        {option}`config.systemd.sockets.hylafax-hfaxd.listenStreams`;
         by default, only 127.0.0.1 is permitted to connect.
       '';
     };

nixos/modules/services/networking/murmur.nix

···
         type = types.nullOr types.path;
         default = null;
         example = "/var/lib/murmur/murmurd.env";
-        description = ''
-          Environment file as defined in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+        description = lib.mdDoc ''
+          Environment file as defined in {manpage}`systemd.exec(5)`.
 
           Secrets may be passed to the service without adding them to the world-readable
           Nix store, by specifying placeholder variables as the option value in Nix and
           setting these variables accordingly in the environment file.
 
-          <programlisting>
+          ```
             # snippet of murmur-related config
             services.murmur.password = "$MURMURD_PASSWORD";
-          </programlisting>
+          ```
 
-          <programlisting>
+          ```
             # content of the environment file
             MURMURD_PASSWORD=verysecretpassword
-          </programlisting>
+          ```
 
           Note that this file needs to be available on the host on which
-          <literal>murmur</literal> is running.
+          `murmur` is running.
         '';
       };
     };

nixos/modules/services/networking/ncdns.nix

···
         default = config.networking.hostName;
         defaultText = literalExpression "config.networking.hostName";
         example = "example.com";
-        description = ''
+        description = lib.mdDoc ''
           The hostname of this ncdns instance, which defaults to the machine
           hostname. If specified, ncdns lists the hostname as an NS record at
           the zone apex:
-          <programlisting>
+          ```
           bit. IN NS ns1.example.com.
-          </programlisting>
+          ```
           If unset ncdns will generate an internal psuedo-hostname under the
           zone, which will resolve to the value of
-          <option>services.ncdns.identity.address</option>.
+          {option}`services.ncdns.identity.address`.
           If you are only using ncdns locally you can ignore this.
         '';
       };
···
       dnssec.keys.public = mkOption {
         type = types.path;
         default = defaultFiles.public;
-        description = ''
+        description = lib.mdDoc ''
           Path to the file containing the KSK public key.
-          The key can be generated using the <literal>dnssec-keygen</literal>
-          command, provided by the package <literal>bind</literal> as follows:
-          <programlisting>
+          The key can be generated using the `dnssec-keygen`
+          command, provided by the package `bind` as follows:
+          ```
           $ dnssec-keygen -a RSASHA256 -3 -b 2048 -f KSK bit
-          </programlisting>
+          ```
         '';
       };
 
···
       dnssec.keys.zonePublic = mkOption {
         type = types.path;
         default = defaultFiles.zonePublic;
-        description = ''
+        description = lib.mdDoc ''
           Path to the file containing the ZSK public key.
-          The key can be generated using the <literal>dnssec-keygen</literal>
-          command, provided by the package <literal>bind</literal> as follows:
-          <programlisting>
+          The key can be generated using the `dnssec-keygen`
+          command, provided by the package `bind` as follows:
+          ```
           $ dnssec-keygen -a RSASHA256 -3 -b 2048 bit
-          </programlisting>
+          ```
         '';
       };
 

nixos/modules/services/networking/nix-serve.nix

···
       secretKeyFile = mkOption {
         type = types.nullOr types.str;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           The path to the file used for signing derivation data.
           Generate with:
 
-          <programlisting>
+          ```
           nix-store --generate-binary-cache-key key-name secret-key-file public-key-file
-          </programlisting>
+          ```
 
-          For more details see <citerefentry><refentrytitle>nix-store</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+          For more details see {manpage}`nix-store(1)`.
         '';
       };
 

nixos/modules/services/security/hockeypuck.nix

···
           };
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         Configuration file for hockeypuck, here you can override
-        certain settings (<literal>loglevel</literal> and
-        <literal>openpgp.db.dsn</literal>) by just setting those values.
+        certain settings (`loglevel` and
+        `openpgp.db.dsn`) by just setting those values.
 
         For other settings you need to use lib.mkForce to override them.
 
···
         the database yourself.
 
         Example:
-        <programlisting>
+        ```
           services.postgresql = {
             enable = true;
             ensureDatabases = [ "hockeypuck" ];
···
               ensurePermissions."DATABASE hockeypuck" = "ALL PRIVILEGES";
             }];
           };
-        </programlisting>
+        ```
       '';
     };
   };

nixos/modules/services/security/privacyidea.nix

···
         type = types.nullOr types.path;
         default = null;
         example = "/root/privacyidea.env";
-        description = ''
+        description = lib.mdDoc ''
           File to load as environment file. Environment variables
           from this file will be interpolated into the config file
-          using <literal>envsubst</literal> which is helpful for specifying
+          using `envsubst` which is helpful for specifying
           secrets:
-          <programlisting>
-          { <xref linkend="opt-services.privacyidea.secretKey"/> = "$SECRET"; }
-          </programlisting>
+          ```
+          { services.privacyidea.secretKey = "$SECRET"; }
+          ```
 
           The environment-file can now specify the actual secret key:
-          <programlisting>
+          ```
           SECRET=veryverytopsecret
-          </programlisting>
+          ```
         '';
       };
 

nixos/modules/services/security/vault.nix

···
       extraSettingsPaths = mkOption {
         type = types.listOf types.path;
         default = [];
-        description = ''
+        description = lib.mdDoc ''
           Configuration files to load besides the immutable one defined by the NixOS module.
           This can be used to avoid putting credentials in the Nix store, which can be read by any user.
 
           Each path can point to a JSON- or HCL-formatted file, or a directory
-          to be scanned for files with <literal>.hcl</literal> or
-          <literal>.json</literal> extensions.
+          to be scanned for files with `.hcl` or
+          `.json` extensions.
 
           To upload the confidential file with NixOps, use for example:
 
-          <programlisting><![CDATA[
+          ```
           # https://releases.nixos.org/nixops/latest/manual/manual.html#opt-deployment.keys
           deployment.keys."vault.hcl" = let db = import ./db-credentials.nix; in {
             text = ${"''"}
···
           services.vault.extraSettingsPaths = ["/run/keys/vault.hcl"];
           services.vault.storageBackend = "postgresql";
           users.users.vault.extraGroups = ["keys"];
-          ]]></programlisting>
+          ```
         '';
       };
     };

nixos/modules/services/security/vaultwarden/default.nix

···
       type = with types; nullOr path;
       default = null;
       example = "/var/lib/vaultwarden.env";
-      description = ''
-        Additional environment file as defined in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+      description = lib.mdDoc ''
+        Additional environment file as defined in {manpage}`systemd.exec(5)`.
 
-        Secrets like <envar>ADMIN_TOKEN</envar> and <envar>SMTP_PASSWORD</envar>
+        Secrets like {env}`ADMIN_TOKEN` and {env}`SMTP_PASSWORD`
         may be passed to the service without adding them to the world-readable Nix store.
 
         Note that this file needs to be available on the host on which
-        <literal>vaultwarden</literal> is running.
+        `vaultwarden` is running.
 
         As a concrete example, to make the Admin UI available
         (from which new users can be invited initially),
-        the secret <envar>ADMIN_TOKEN</envar> needs to be defined as described
-        <link xlink:href="https://github.com/dani-garcia/vaultwarden/wiki/Enabling-admin-page">here</link>.
-        Setting <literal>environmentFile</literal> to <literal>/var/lib/vaultwarden.env</literal>
+        the secret {env}`ADMIN_TOKEN` needs to be defined as described
+        [here](https://github.com/dani-garcia/vaultwarden/wiki/Enabling-admin-page).
+        Setting `environmentFile` to `/var/lib/vaultwarden.env`
         and ensuring permissions with e.g.
-        <literal>chown vaultwarden:vaultwarden /var/lib/vaultwarden.env</literal>
-        (the <literal>vaultwarden</literal> user will only exist after activating with
-        <literal>enable = true;</literal> before this), we can set the contents of the file to have
+        `chown vaultwarden:vaultwarden /var/lib/vaultwarden.env`
+        (the `vaultwarden` user will only exist after activating with
+        `enable = true;` before this), we can set the contents of the file to have
         contents such as:
 
-<programlisting>
-# Admin secret token, see
-# https://github.com/dani-garcia/vaultwarden/wiki/Enabling-admin-page
-ADMIN_TOKEN=...copy-paste a unique generated secret token here...
-</programlisting>
+        ```
+        # Admin secret token, see
+        # https://github.com/dani-garcia/vaultwarden/wiki/Enabling-admin-page
+        ADMIN_TOKEN=...copy-paste a unique generated secret token here...
+        ```
       '';
     };
 

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

···
         type = with lib.types; nullOr path;
         default = null;
         example = "/run/keys/secret_key_base";
-        description = ''
+        description = lib.mdDoc ''
           The path to a file containing the
-          <literal>secret_key_base</literal> secret.
+          `secret_key_base` secret.
 
-          Discourse uses <literal>secret_key_base</literal> to encrypt
+          Discourse uses `secret_key_base` to encrypt
           the cookie store, which contains session data, and to digest
           user auth tokens.
 
           Needs to be a 64 byte long string of hexadecimal
           characters. You can generate one by running
 
-          <programlisting>
+          ```
           openssl rand -hex 64 >/path/to/secret_key_base_file
-          </programlisting>
+          ```
 
           This should be a string, not a nix path, since nix paths are
           copied into the world-readable nix store.

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

···
       type = with types; nullOr path;
       default = null;
       example = "/var/lib/hedgedoc/hedgedoc.env";
-      description = ''
-        Environment file as defined in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+      description = lib.mdDoc ''
+        Environment file as defined in {manpage}`systemd.exec(5)`.
 
         Secrets may be passed to the service without adding them to the world-readable
         Nix store, by specifying placeholder variables as the option value in Nix and
         setting these variables accordingly in the environment file.
 
-        <programlisting>
+        ```
           # snippet of HedgeDoc-related config
           services.hedgedoc.configuration.dbURL = "postgres://hedgedoc:\''${DB_PASSWORD}@db-host:5432/hedgedocdb";
           services.hedgedoc.configuration.minio.secretKey = "$MINIO_SECRET_KEY";
-        </programlisting>
+        ```
 
-        <programlisting>
+        ```
           # content of the environment file
           DB_PASSWORD=verysecretdbpassword
           MINIO_SECRET_KEY=verysecretminiokey
-        </programlisting>
+        ```
 
         Note that this file needs to be available on the host on which
-        <literal>HedgeDoc</literal> is running.
+        `HedgeDoc` is running.
       '';
     };
 

nixos/modules/services/web-servers/molly-brown.nix

···
     certPath = mkOption {
       type = types.path;
       example = "/var/lib/acme/example.com/cert.pem";
-      description = ''
+      description = lib.mdDoc ''
         Path to TLS certificate. An ACME certificate and key may be
         shared with an HTTP server, but only if molly-brown has
         permissions allowing it to read such keys.
 
         As an example:
-        <programlisting>
+        ```
         systemd.services.molly-brown.serviceConfig.SupplementaryGroups =
           [ config.security.acme.certs."example.com".group ];
-        </programlisting>
+        ```
       '';
     };
 

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

···
     specialisation = mkOption {
       default = {};
       example = lib.literalExpression "{ fewJobsManyCores.configuration = { nix.settings = { core = 0; max-jobs = 1; }; }; }";
-      description = ''
+      description = lib.mdDoc ''
         Additional configurations to build. If
-        <literal>inheritParentConfig</literal> is true, the system
+        `inheritParentConfig` is true, the system
         will be based on the overall system configuration.
 
         To switch to a specialised configuration
-        (e.g. <literal>fewJobsManyCores</literal>) at runtime, run:
+        (e.g. `fewJobsManyCores`) at runtime, run:
 
-        <programlisting>
+        ```
         sudo /run/current-system/specialisation/fewJobsManyCores/bin/switch-to-configuration test
-        </programlisting>
+        ```
       '';
       type = types.attrsOf (types.submodule (
         local@{ ... }: let

nixos/modules/virtualisation/lxcfs.nix

···
       mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           This enables LXCFS, a FUSE filesystem for LXC.
           To use lxcfs in include the following configuration in your
           container configuration:
-          <programlisting>
+          ```
           virtualisation.lxc.defaultConfig = "lxc.include = ''${pkgs.lxcfs}/share/lxc/config/common.conf.d/00-lxcfs.conf";
-          </programlisting>
+          ```
         '';
       };
   };

nixos/modules/virtualisation/lxd.nix

···
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           This option enables lxd, a daemon that manages
           containers. Users in the "lxd" group can interact with
           the daemon (e.g. to start or stop containers) using the
-          <command>lxc</command> command line tool, among others.
+          {command}`lxc` command line tool, among others.
 
           Most of the time, you'll also want to start lxcfs, so
           that containers can "see" the limits:
-          <programlisting>
+          ```
           virtualisation.lxc.lxcfs.enable = true;
-          </programlisting>
+          ```
         '';
       };