Merge pull request #185056 from pennae/option-docs-md

nixos/*: more option docs conversions

nixos/lib/make-options-doc/default.nix

···
 
   optionsNix = builtins.listToAttrs (map (o: { name = o.name; value = removeAttrs o ["name" "visible" "internal"]; }) optionsList);
 
-  pythonMD =
-    let
-      self = (pkgs.python3Minimal.override {
-        inherit self;
-        includeSiteCustomize = true;
-        });
-      in self.withPackages (p: [ p.mistune_2_0 ]);
-
 in rec {
   inherit optionsNix;
 
···
 
   optionsJSON = pkgs.runCommand "options.json"
     { meta.description = "List of NixOS options in JSON format";
-      buildInputs = [ pkgs.brotli pythonMD ];
+      buildInputs = [
+        pkgs.brotli
+        (let
+          self = (pkgs.python3Minimal.override {
+            inherit self;
+            includeSiteCustomize = true;
+           });
+         in self.withPackages (p: [ p.mistune_2_0 ]))
+      ];
       options = builtins.toFile "options.json"
         (builtins.unsafeDiscardStringContext (builtins.toJSON optionsNix));
-      # convert markdown to docbook in its own derivation to cache the
-      # conversion results. the conversion is surprisingly expensive.
-      baseJSON =
-        if baseOptionsJSON != null
-        then
-          pkgs.runCommand "base-json-md-converted" {
-            buildInputs = [ pythonMD ];
-          } ''
-            python ${./mergeJSON.py} ${baseOptionsJSON} <(echo '{}') > $out
-          ''
-        else null;
     }
     ''
       # Export list of options in different format.
···
           else ''
             python ${./mergeJSON.py} \
               ${lib.optionalString warningsAreErrors "--warnings-are-errors"} \
-              $baseJSON $options \
+              ${baseOptionsJSON} $options \
               > $dst/options.json
           ''
       }

nixos/lib/make-options-doc/mergeJSON.py

···
 import sys
 from typing import Any, Dict, List
 
+# for MD conversion
+import mistune
+import re
+from xml.sax.saxutils import escape, quoteattr
+
 JSON = Dict[str, Any]
 
 class Key:
···
         result[opt.name] = opt.value
     return result
 
-# converts in-place!
-def convertMD(options: Dict[str, Any]) -> str:
-    import mistune
-    import re
-    from xml.sax.saxutils import escape, quoteattr
+admonitions = {
+    '.warning': 'warning',
+    '.important': 'important',
+    '.note': 'note'
+}
+class Renderer(mistune.renderers.BaseRenderer):
+    def _get_method(self, name):
+        try:
+            return super(Renderer, self)._get_method(name)
+        except AttributeError:
+            def not_supported(*args, **kwargs):
+                raise NotImplementedError("md node not supported yet", name, args, **kwargs)
+            return not_supported
 
-    admonitions = {
-        '.warning': 'warning',
-        '.important': 'important',
-        '.note': 'note'
-    }
-    class Renderer(mistune.renderers.BaseRenderer):
-        def __init__(self, path):
-            self.path = path
-        def _get_method(self, name):
-            try:
-                return super(Renderer, self)._get_method(name)
-            except AttributeError:
-                def not_supported(*args, **kwargs):
-                    raise NotImplementedError("md node not supported yet", self.path, name, args, **kwargs)
-                return not_supported
+    def text(self, text):
+        return escape(text)
+    def paragraph(self, text):
+        return text + "\n\n"
+    def newline(self):
+        return "<literallayout>\n</literallayout>"
+    def codespan(self, text):
+        return f"<literal>{escape(text)}</literal>"
+    def block_code(self, text, info=None):
+        info = f" language={quoteattr(info)}" if info is not None else ""
+        return f"<programlisting{info}>\n{escape(text)}</programlisting>"
+    def link(self, link, text=None, title=None):
+        tag = "link"
+        if link[0:1] == '#':
+            if text == "":
+                tag = "xref"
+            attr = "linkend"
+            link = quoteattr(link[1:])
+        else:
+            # try to faithfully reproduce links that were of the form <link href="..."/>
+            # in docbook format
+            if text == link:
+                text = ""
+            attr = "xlink:href"
+            link = quoteattr(link)
+        return f"<{tag} {attr}={link}>{text}</{tag}>"
+    def list(self, text, ordered, level, start=None):
+        if ordered:
+            raise NotImplementedError("ordered lists not supported yet")
+        return f"<itemizedlist>\n{text}\n</itemizedlist>"
+    def list_item(self, text, level):
+        return f"<listitem><para>{text}</para></listitem>\n"
+    def block_text(self, text):
+        return text
+    def emphasis(self, text):
+        return f"<emphasis>{text}</emphasis>"
+    def strong(self, text):
+        return f"<emphasis role=\"strong\">{text}</emphasis>"
+    def admonition(self, text, kind):
+        if kind not in admonitions:
+            raise NotImplementedError(f"admonition {kind} not supported yet")
+        tag = admonitions[kind]
+        # we don't keep whitespace here because usually we'll contain only
+        # a single paragraph and the original docbook string is no longer
+        # available to restore the trailer.
+        return f"<{tag}><para>{text.rstrip()}</para></{tag}>"
+    def block_quote(self, text):
+        return f"<blockquote><para>{text}</para></blockquote>"
+    def command(self, text):
+        return f"<command>{escape(text)}</command>"
+    def option(self, text):
+        return f"<option>{escape(text)}</option>"
+    def file(self, text):
+        return f"<filename>{escape(text)}</filename>"
+    def manpage(self, page, section):
+        title = f"<refentrytitle>{escape(page)}</refentrytitle>"
+        vol = f"<manvolnum>{escape(section)}</manvolnum>"
+        return f"<citerefentry>{title}{vol}</citerefentry>"
 
-        def text(self, text):
-            return escape(text)
-        def paragraph(self, text):
-            return text + "\n\n"
-        def newline(self):
-            return "<literallayout>\n</literallayout>"
-        def codespan(self, text):
-            return f"<literal>{escape(text)}</literal>"
-        def block_code(self, text, info=None):
-            info = f" language={quoteattr(info)}" if info is not None else ""
-            return f"<programlisting{info}>\n{escape(text)}</programlisting>"
-        def link(self, link, text=None, title=None):
-            if link[0:1] == '#':
-                attr = "linkend"
-                link = quoteattr(link[1:])
-            else:
-                # try to faithfully reproduce links that were of the form <link href="..."/>
-                # in docbook format
-                if text == link:
-                    text = ""
-                attr = "xlink:href"
-                link = quoteattr(link)
-            return f"<link {attr}={link}>{text}</link>"
-        def list(self, text, ordered, level, start=None):
-            if ordered:
-                raise NotImplementedError("ordered lists not supported yet")
-            return f"<itemizedlist>\n{text}\n</itemizedlist>"
-        def list_item(self, text, level):
-            return f"<listitem><para>{text}</para></listitem>\n"
-        def block_text(self, text):
-            return text
-        def emphasis(self, text):
-            return f"<emphasis>{text}</emphasis>"
-        def strong(self, text):
-            return f"<emphasis role=\"strong\">{text}</emphasis>"
-        def admonition(self, text, kind):
-            if kind not in admonitions:
-                raise NotImplementedError(f"admonition {kind} not supported yet")
-            tag = admonitions[kind]
-            # we don't keep whitespace here because usually we'll contain only
-            # a single paragraph and the original docbook string is no longer
-            # available to restore the trailer.
-            return f"<{tag}><para>{text.rstrip()}</para></{tag}>"
-        def block_quote(self, text):
-            return f"<blockquote><para>{text}</para></blockquote>"
-        def command(self, text):
-            return f"<command>{escape(text)}</command>"
-        def option(self, text):
-            return f"<option>{escape(text)}</option>"
-        def file(self, text):
-            return f"<filename>{escape(text)}</filename>"
-        def manpage(self, page, section):
-            title = f"<refentrytitle>{escape(page)}</refentrytitle>"
-            vol = f"<manvolnum>{escape(section)}</manvolnum>"
-            return f"<citerefentry>{title}{vol}</citerefentry>"
+    def finalize(self, data):
+        return "".join(data)
 
-        def finalize(self, data):
-            return "".join(data)
-
-    plugins = []
-
+def p_command(md):
     COMMAND_PATTERN = r'\{command\}`(.*?)`'
-    def command(md):
-        def parse(self, m, state):
-            return ('command', m.group(1))
-        md.inline.register_rule('command', COMMAND_PATTERN, parse)
-        md.inline.rules.append('command')
-    plugins.append(command)
+    def parse(self, m, state):
+        return ('command', m.group(1))
+    md.inline.register_rule('command', COMMAND_PATTERN, parse)
+    md.inline.rules.append('command')
 
+def p_file(md):
     FILE_PATTERN = r'\{file\}`(.*?)`'
-    def file(md):
-        def parse(self, m, state):
-            return ('file', m.group(1))
-        md.inline.register_rule('file', FILE_PATTERN, parse)
-        md.inline.rules.append('file')
-    plugins.append(file)
+    def parse(self, m, state):
+        return ('file', m.group(1))
+    md.inline.register_rule('file', FILE_PATTERN, parse)
+    md.inline.rules.append('file')
 
+def p_option(md):
     OPTION_PATTERN = r'\{option\}`(.*?)`'
-    def option(md):
-        def parse(self, m, state):
-            return ('option', m.group(1))
-        md.inline.register_rule('option', OPTION_PATTERN, parse)
-        md.inline.rules.append('option')
-    plugins.append(option)
+    def parse(self, m, state):
+        return ('option', m.group(1))
+    md.inline.register_rule('option', OPTION_PATTERN, parse)
+    md.inline.rules.append('option')
 
+def p_manpage(md):
     MANPAGE_PATTERN = r'\{manpage\}`(.*?)\((.+?)\)`'
-    def manpage(md):
-        def parse(self, m, state):
-            return ('manpage', m.group(1), m.group(2))
-        md.inline.register_rule('manpage', MANPAGE_PATTERN, parse)
-        md.inline.rules.append('manpage')
-    plugins.append(manpage)
+    def parse(self, m, state):
+        return ('manpage', m.group(1), m.group(2))
+    md.inline.register_rule('manpage', MANPAGE_PATTERN, parse)
+    md.inline.rules.append('manpage')
 
+def p_admonition(md):
     ADMONITION_PATTERN = re.compile(r'^::: \{([^\n]*?)\}\n(.*?)^:::\n', flags=re.MULTILINE|re.DOTALL)
-    def admonition(md):
-        def parse(self, m, state):
-            return {
-                'type': 'admonition',
-                'children': self.parse(m.group(2), state),
-                'params': [ m.group(1) ],
-            }
-        md.block.register_rule('admonition', ADMONITION_PATTERN, parse)
-        md.block.rules.append('admonition')
-    plugins.append(admonition)
+    def parse(self, m, state):
+        return {
+            'type': 'admonition',
+            'children': self.parse(m.group(2), state),
+            'params': [ m.group(1) ],
+        }
+    md.block.register_rule('admonition', ADMONITION_PATTERN, parse)
+    md.block.rules.append('admonition')
+
+md = mistune.create_markdown(renderer=Renderer(), plugins=[
+    p_command, p_file, p_option, p_manpage, p_admonition
+])
 
+# converts in-place!
+def convertMD(options: Dict[str, Any]) -> str:
     def convertString(path: str, text: str) -> str:
-        rendered = mistune.markdown(text, renderer=Renderer(path), plugins=plugins)
-        # keep trailing spaces so we can diff the generated XML to check for conversion bugs.
-        return rendered.rstrip() + text[len(text.rstrip()):]
+        try:
+            rendered = md(text)
+            # keep trailing spaces so we can diff the generated XML to check for conversion bugs.
+            return rendered.rstrip() + text[len(text.rstrip()):]
+        except:
+            print(f"error in {path}")
+            raise
 
     def optionIs(option: Dict[str, Any], key: str, typ: str) -> bool:
         if key not in option: return False

nixos/modules/config/i18n.nix

···
             ))
         '';
         example = ["en_US.UTF-8/UTF-8" "nl_NL.UTF-8/UTF-8" "nl_NL/ISO-8859-1"];
-        description = ''
+        description = lib.mdDoc ''
           List of locales that the system should support.  The value
-          <literal>"all"</literal> means that all locales supported by
+          `"all"` means that all locales supported by
           Glibc will be installed.  A full list of supported locales
-          can be found at <link
-          xlink:href="https://sourceware.org/git/?p=glibc.git;a=blob;f=localedata/SUPPORTED"/>.
+          can be found at <https://sourceware.org/git/?p=glibc.git;a=blob;f=localedata/SUPPORTED>.
         '';
       };
 

nixos/modules/config/resolvconf.nix

···
       dnsExtensionMechanism = mkOption {
         type = types.bool;
         default = true;
-        description = ''
-          Enable the <code>edns0</code> option in <filename>resolv.conf</filename>. With
-          that option set, <code>glibc</code> supports use of the extension mechanisms for
+        description = lib.mdDoc ''
+          Enable the `edns0` option in {file}`resolv.conf`. With
+          that option set, `glibc` supports use of the extension mechanisms for
           DNS (EDNS) specified in RFC 2671. The most popular user of that feature is DNSSEC,
           which does not work without it.
         '';

nixos/modules/config/shells-environment.nix

···
 
     environment.shellAliases = mkOption {
       example = { l = null; ll = "ls -l"; };
-      description = ''
+      description = lib.mdDoc ''
         An attribute set that maps aliases (the top level attribute names in
         this option) to command strings or directly to build outputs. The
         aliases are added to all users' shells.
-        Aliases mapped to <code>null</code> are ignored.
+        Aliases mapped to `null` are ignored.
       '';
       type = with types; attrsOf (nullOr (either str path));
     };

nixos/modules/config/system-environment.nix

···
 
     environment.sessionVariables = mkOption {
       default = {};
-      description = ''
+      description = lib.mdDoc ''
         A set of environment variables used in the global environment.
         These variables will be set by PAM early in the login process.
 
···
         colon characters.
 
         Note, due to limitations in the PAM format values may not
-        contain the <literal>"</literal> character.
+        contain the `"` character.
 
         Also, these variables are merged into
-        <xref linkend="opt-environment.variables"/> and it is
+        [](#opt-environment.variables) and it is
         therefore not possible to use PAM style variables such as
-        <code>@{HOME}</code>.
+        `@{HOME}`.
       '';
       type = with types; attrsOf (either str (listOf str));
       apply = mapAttrs (n: v: if isList v then concatStringsSep ":" v else v);
···
         Also, these variables are merged into
         <xref linkend="opt-environment.profileRelativeEnvVars"/> and it is
         therefore not possible to use PAM style variables such as
-        <code>@{HOME}</code>.
+        <literal>@{HOME}</literal>.
       '';
     };
 

nixos/modules/config/users-groups.nix

···
       isNormalUser = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Indicates whether this is an account for a “real” user. This
-          automatically sets <option>group</option> to
-          <literal>users</literal>, <option>createHome</option> to
-          <literal>true</literal>, <option>home</option> to
-          <filename>/home/<replaceable>username</replaceable></filename>,
-          <option>useDefaultShell</option> to <literal>true</literal>,
-          and <option>isSystemUser</option> to
-          <literal>false</literal>.
-          Exactly one of <literal>isNormalUser</literal> and
-          <literal>isSystemUser</literal> must be true.
+          automatically sets {option}`group` to
+          `users`, {option}`createHome` to
+          `true`, {option}`home` to
+          {file}`/home/«username»`,
+          {option}`useDefaultShell` to `true`,
+          and {option}`isSystemUser` to
+          `false`.
+          Exactly one of `isNormalUser` and
+          `isSystemUser` must be true.
         '';
       };
 
···
       pamMount = mkOption {
         type = with types; attrsOf str;
         default = {};
-        description = ''
+        description = lib.mdDoc ''
           Attributes for user's entry in
-          <filename>pam_mount.conf.xml</filename>.
-          Useful attributes might include <code>path</code>,
-          <code>options</code>, <code>fstype</code>, and <code>server</code>.
-          See <link
-          xlink:href="http://pam-mount.sourceforge.net/pam_mount.conf.5.html" />
+          {file}`pam_mount.conf.xml`.
+          Useful attributes might include `path`,
+          `options`, `fstype`, and `server`.
+          See <http://pam-mount.sourceforge.net/pam_mount.conf.5.html>
           for more information.
         '';
       };
···
         default = pkgs.shadow;
         defaultText = literalExpression "pkgs.shadow";
         example = literalExpression "pkgs.bashInteractive";
-        description = ''
+        description = lib.mdDoc ''
           The path to the user's shell. Can use shell derivations,
-          like <literal>pkgs.bashInteractive</literal>. Don’t
+          like `pkgs.bashInteractive`. Don’t
           forget to enable your shell in
-          <literal>programs</literal> if necessary,
-          like <code>programs.zsh.enable = true;</code>.
+          `programs` if necessary,
+          like `programs.zsh.enable = true;`.
         '';
       };
 

nixos/modules/config/xdg/portal.nix

···
 
   options.xdg.portal = {
     enable =
-      mkEnableOption "<link xlink:href='https://github.com/flatpak/xdg-desktop-portal'>xdg desktop integration</link>" // {
+      mkEnableOption ''<link xlink:href="https://github.com/flatpak/xdg-desktop-portal">xdg desktop integration</link>'' // {
         default = false;
       };
 

nixos/modules/hardware/logitech.nix

···
       devices = mkOption {
         type = types.listOf types.str;
         default = [ "0a07" "c222" "c225" "c227" "c251" ];
-        description = ''
+        description = lib.mdDoc ''
           List of USB device ids supported by g15daemon.
-          </para>
-          <para>
+
           You most likely do not need to change this.
         '';
       };

nixos/modules/hardware/tuxedo-keyboard.nix

···
 
           To configure the driver, pass the options to the <option>boot.kernelParams</option> 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: <link xlink:href="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:
 

nixos/modules/hardware/video/uvcvideo/default.nix

···
       packages = mkOption {
         type = types.listOf types.path;
         example = literalExpression "[ pkgs.tiscamera ]";
-        description = ''
-          List of packages containing <command>uvcvideo</command> dynamic controls
+        description = lib.mdDoc ''
+          List of packages containing {command}`uvcvideo` dynamic controls
           rules. All files found in
-          <filename><replaceable>pkg</replaceable>/share/uvcdynctrl/data</filename>
+          {file}`«pkg»/share/uvcdynctrl/data`
           will be included.
 
-          Note that these will serve as input to the <command>libwebcam</command>
-          package which through its own <command>udev</command> rule will register
-          the dynamic controls from specified packages to the <command>uvcvideo</command>
+          Note that these will serve as input to the {command}`libwebcam`
+          package which through its own {command}`udev` rule will register
+          the dynamic controls from specified packages to the {command}`uvcvideo`
           driver.
         '';
         apply = map getBin;

nixos/modules/installer/cd-dvd/iso-image.nix

···
         This will be directly appended (without whitespace) to the NixOS version
         string, like for example if it is set to <literal>XXX</literal>:
 
-        <para><literal>NixOS 99.99-pre666XXX</literal></para>
+        <literal>NixOS 99.99-pre666XXX</literal>
       '';
     };
 

nixos/modules/misc/nixpkgs.nix

···
       example = literalExpression "import <nixpkgs> {}";
       description = ''
         If set, the pkgs argument to all NixOS modules is the value of
-        this option, extended with <code>nixpkgs.overlays</code>, if
-        that is also set. Either <code>nixpkgs.crossSystem</code> or
-        <code>nixpkgs.localSystem</code> will be used in an assertion
+        this option, extended with <literal>nixpkgs.overlays</literal>, if
+        that is also set. Either <literal>nixpkgs.crossSystem</literal> or
+        <literal>nixpkgs.localSystem</literal> will be used in an assertion
         to check that the NixOS and Nixpkgs architectures match. Any
-        other options in <code>nixpkgs.*</code>, notably <code>config</code>,
+        other options in <literal>nixpkgs.*</literal>, notably <literal>config</literal>,
         will be ignored.
 
         If unset, the pkgs argument to all NixOS modules is determined
···
         The default value imports the Nixpkgs source files
         relative to the location of this NixOS module, because
         NixOS and Nixpkgs are distributed together for consistency,
-        so the <code>nixos</code> in the default value is in fact a
-        relative path. The <code>config</code>, <code>overlays</code>,
-        <code>localSystem</code>, and <code>crossSystem</code> come
+        so the <literal>nixos</literal> in the default value is in fact a
+        relative path. The <literal>config</literal>, <literal>overlays</literal>,
+        <literal>localSystem</literal>, and <literal>crossSystem</literal> come
         from this option's siblings.
 
         This option can be used by applications like NixOps to increase
         the performance of evaluation, or to create packages that depend
         on a container that should be built with the exact same evaluation
         of Nixpkgs, for example. Applications like this should set
-        their default value using <code>lib.mkDefault</code>, so
+        their default value using <literal>lib.mkDefault</literal>, so
         user-provided configuration can override it without using
-        <code>lib</code>.
+        <literal>lib</literal>.
 
         Note that using a distinct version of Nixpkgs with NixOS may
         be an unexpected source of problems. Use this option with care.
···
         details, see the Nixpkgs documentation.)  It allows you to set
         package configuration options.
 
-        Ignored when <code>nixpkgs.pkgs</code> is set.
+        Ignored when <literal>nixpkgs.pkgs</literal> is set.
       '';
     };
 
···
         The first argument should be used for finding dependencies, and
         the second should be used for overriding recipes.
 
-        If <code>nixpkgs.pkgs</code> is set, overlays specified here
+        If <literal>nixpkgs.pkgs</literal> is set, overlays specified here
         will be applied after the overlays that were already present
-        in <code>nixpkgs.pkgs</code>.
+        in <literal>nixpkgs.pkgs</literal>.
       '';
     };
 
···
       description = ''
         Specifies the platform where the NixOS configuration will run.
 
-        To cross-compile, set also <code>nixpkgs.buildPlatform</code>.
+        To cross-compile, set also <literal>nixpkgs.buildPlatform</literal>.
 
-        Ignored when <code>nixpkgs.pkgs</code> is set.
+        Ignored when <literal>nixpkgs.pkgs</literal> is set.
       '';
     };
 
···
         or if you're building machines, you can set this to match your
         development system and/or build farm.
 
-        Ignored when <code>nixpkgs.pkgs</code> is set.
+        Ignored when <literal>nixpkgs.pkgs</literal> is set.
       '';
     };
 
···
         use the old options.
 
         Specifies the platform on which NixOS should be built. When
-        <code>nixpkgs.crossSystem</code> is unset, it also specifies
+        <literal>nixpkgs.crossSystem</literal> is unset, it also specifies
         the platform <emphasis>for</emphasis> which NixOS should be
         built.  If this option is unset, it defaults to the platform
         type of the machine where evaluation happens. Specifying this
···
         deployment, or when building virtual machines. See its
         description in the Nixpkgs manual for more details.
 
-        Ignored when <code>nixpkgs.pkgs</code> or <code>hostPlatform</code> is set.
+        Ignored when <literal>nixpkgs.pkgs</literal> or <literal>hostPlatform</literal> is set.
       '';
     };
 
···
 
         Specifies the platform for which NixOS should be
         built. Specify this only if it is different from
-        <code>nixpkgs.localSystem</code>, the platform
+        <literal>nixpkgs.localSystem</literal>, the platform
         <emphasis>on</emphasis> which NixOS should be built. In other
         words, specify this to cross-compile NixOS. Otherwise it
         should be set as null, the default. See its description in the
         Nixpkgs manual for more details.
 
-        Ignored when <code>nixpkgs.pkgs</code> or <code>hostPlatform</code> is set.
+        Ignored when <literal>nixpkgs.pkgs</literal> or <literal>hostPlatform</literal> is set.
       '';
     };
 
···
         with a recently generated <literal>hardware-configuration.nix</literal>.
 
         Specifies the Nix platform type on which NixOS should be built.
-        It is better to specify <code>nixpkgs.localSystem</code> instead.
+        It is better to specify <literal>nixpkgs.localSystem</literal> instead.
         <programlisting>
         {
           nixpkgs.system = ..;
···
           nixpkgs.localSystem.system = ..;
         }
         </programlisting>
-        See <code>nixpkgs.localSystem</code> for more information.
+        See <literal>nixpkgs.localSystem</literal> for more information.
 
-        Ignored when <code>nixpkgs.pkgs</code>, <code>nixpkgs.localSystem</code> or <code>nixpkgs.hostPlatform</code> is set.
+        Ignored when <literal>nixpkgs.pkgs</literal>, <literal>nixpkgs.localSystem</literal> or <literal>nixpkgs.hostPlatform</literal> is set.
       '';
     };
   };

nixos/modules/programs/adb.nix

···
       enable = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Whether to configure system to use Android Debug Bridge (adb).
           To grant access to a user, it must be part of adbusers group:
-          <code>users.users.alice.extraGroups = ["adbusers"];</code>
+          `users.users.alice.extraGroups = ["adbusers"];`
         '';
       };
     };

nixos/modules/programs/firejail.nix

···
           };
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         Wrap the binaries in firejail and place them in the global path.
-        </para>
-        <para>
+
         You will get file collisions if you put the actual application binary in
         the global environment (such as by adding the application package to
-        <code>environment.systemPackages</code>), and applications started via
+        `environment.systemPackages`), and applications started via
         .desktop files are not wrapped if they specify the absolute path to the
         binary.
       '';

nixos/modules/programs/gphoto2.nix

···
       enable = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Whether to configure system to use gphoto2.
           To grant digital camera access to a user, the user must
           be part of the camera group:
-          <code>users.users.alice.extraGroups = ["camera"];</code>
+          `users.users.alice.extraGroups = ["camera"];`
         '';
       };
     };

nixos/modules/programs/kdeconnect.nix

···
       Note that it will open the TCP and UDP port from
       1714 to 1764 as they are needed for it to function properly.
       You can use the <option>package</option> to use
-      <code>gnomeExtensions.gsconnect</code> as an alternative
+      <literal>gnomeExtensions.gsconnect</literal> as an alternative
       implementation if you use Gnome.
     '';
     package = mkOption {

nixos/modules/programs/neovim.nix

···
           };
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         Generate your init file from your list of plugins and custom commands.
-        Neovim will then be wrapped to load <command>nvim -u /nix/store/<replaceable>hash</replaceable>-vimrc</command>
+        Neovim will then be wrapped to load {command}`nvim -u /nix/store/«hash»-vimrc`
       '';
     };
 

nixos/modules/programs/nncp.nix

···
     secrets = mkOption {
       type = with types; listOf str;
       example = [ "/run/keys/nncp.hjson" ];
-      description = ''
+      description = lib.mdDoc ''
         A list of paths to NNCP configuration files that should not be
         in the Nix store. These files are layered on top of the values at
-        <xref linkend="opt-programs.nncp.settings"/>.
+        [](#opt-programs.nncp.settings).
       '';
     };
 
     settings = mkOption {
       type = settingsFormat.type;
-      description = ''
+      description = lib.mdDoc ''
         NNCP configuration, see
-        <link xlink:href="http://www.nncpgo.org/Configuration.html"/>.
+        <http://www.nncpgo.org/Configuration.html>.
         At runtime these settings will be overlayed by the contents of
-        <xref linkend="opt-programs.nncp.secrets"/> into the file
-        <literal>${nncpCfgFile}</literal>. Node keypairs go in
-        <literal>secrets</literal>, do not specify them in
-        <literal>settings</literal> as they will be leaked into
-        <literal>/nix/store</literal>!
+        [](#opt-programs.nncp.secrets) into the file
+        `${nncpCfgFile}`. Node keypairs go in
+        `secrets`, do not specify them in
+        `settings` as they will be leaked into
+        `/nix/store`!
       '';
       default = { };
     };

nixos/modules/programs/ssh.nix

···
         default = "";
         description = ''
           Extra configuration text prepended to <filename>ssh_config</filename>. Other generated
-          options will be added after a <code>Host *</code> pattern.
+          options will be added after a <literal>Host *</literal> pattern.
           See <citerefentry><refentrytitle>ssh_config</refentrytitle><manvolnum>5</manvolnum></citerefentry>
           for help.
         '';

nixos/modules/programs/sway.nix

···
       Sway, the i3-compatible tiling Wayland compositor. You can manually launch
       Sway by executing "exec sway" on a TTY. Copy /etc/sway/config to
       ~/.config/sway/config to modify the default configuration. See
-      <link xlink:href="https://github.com/swaywm/sway/wiki" /> and
+      <link xlink:href="https://github.com/swaywm/sway/wiki"/> and
       "man 5 sway" for more information'';
 
     wrapperFeatures = mkOption {

nixos/modules/programs/turbovnc.nix

···
       ensureHeadlessSoftwareOpenGL = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to set up NixOS such that TurboVNC's built-in software OpenGL
           implementation works.
 
-          This will enable <option>hardware.opengl.enable</option> so that OpenGL
+          This will enable {option}`hardware.opengl.enable` so that OpenGL
           programs can find Mesa's llvmpipe drivers.
 
-          Setting this option to <code>false</code> does not mean that software
+          Setting this option to `false` does not mean that software
           OpenGL won't work; it may still work depending on your system
           configuration.
 

nixos/modules/security/acme/default.nix

···
       reloadServices = mkOption {
         type = types.listOf types.str;
         inherit (defaultAndText "reloadServices" []) default defaultText;
-        description = ''
-          The list of systemd services to call <code>systemctl try-reload-or-restart</code>
+        description = lib.mdDoc ''
+          The list of systemd services to call `systemctl try-reload-or-restart`
           on.
         '';
       };
···
           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>
+            <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>
         '';
       };

nixos/modules/security/dhparams.nix

···
 
           The value is the size (in bits) of the DH params to generate. The
           generated DH params path can be found in
-          <literal>config.security.dhparams.params.<replaceable>name</replaceable>.path</literal>.
+          <literal>config.security.dhparams.params.«name».path</literal>.
 
           <note><para>The name of the DH params is taken as being the name of
           the service it serves and the params will be generated before the

nixos/modules/security/doas.nix

···
     wheelNeedsPassword = mkOption {
       type = with types; bool;
       default = true;
-      description = ''
-        Whether users of the <code>wheel</code> group must provide a password to
-        run commands as super user via <command>doas</command>.
+      description = lib.mdDoc ''
+        Whether users of the `wheel` group must provide a password to
+        run commands as super user via {command}`doas`.
       '';
     };
 
     extraRules = mkOption {
       default = [];
-      description = ''
+      description = lib.mdDoc ''
         Define specific rules to be set in the
-        <filename>/etc/doas.conf</filename> file. More specific rules should
+        {file}`/etc/doas.conf` file. More specific rules should
         come after more general ones in order to yield the expected behavior.
-        You can use <code>mkBefore</code> and/or <code>mkAfter</code> to ensure
+        You can use `mkBefore` and/or `mkAfter` to ensure
         this is the case when configuration options are merged.
       '';
       example = literalExpression ''
···
             noPass = mkOption {
               type = with types; bool;
               default = false;
-              description = ''
-                If <code>true</code>, the user is not required to enter a
+              description = lib.mdDoc ''
+                If `true`, the user is not required to enter a
                 password.
               '';
             };
···
             noLog = mkOption {
               type = with types; bool;
               default = false;
-              description = ''
-                If <code>true</code>, successful executions will not be logged
+              description = lib.mdDoc ''
+                If `true`, successful executions will not be logged
                 to
-                <citerefentry><refentrytitle>syslogd</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+                {manpage}`syslogd(8)`.
               '';
             };
 
             persist = mkOption {
               type = with types; bool;
               default = false;
-              description = ''
-                If <code>true</code>, do not ask for a password again for some
+              description = lib.mdDoc ''
+                If `true`, do not ask for a password again for some
                 time after the user successfully authenticates.
               '';
             };
···
             keepEnv = mkOption {
               type = with types; bool;
               default = false;
-              description = ''
-                If <code>true</code>, environment variables other than those
+              description = lib.mdDoc ''
+                If `true`, environment variables other than those
                 listed in
-                <citerefentry><refentrytitle>doas</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+                {manpage}`doas(1)`
                 are kept when creating the environment for the new process.
               '';
             };
···
             setEnv = mkOption {
               type = with types; listOf str;
               default = [];
-              description = ''
+              description = lib.mdDoc ''
                 Keep or set the specified variables. Variables may also be
                 removed with a leading '-' or set using
-                <code>variable=value</code>. If the first character of
-                <code>value</code> is a '$', the value to be set is taken from
+                `variable=value`. If the first character of
+                `value` is a '$', the value to be set is taken from
                 the existing environment variable of the indicated name. This
                 option is processed after the default environment has been
                 created.
 
-                NOTE: All rules have <code>setenv { SSH_AUTH_SOCK }</code> by
-                default. To prevent <code>SSH_AUTH_SOCK</code> from being
-                inherited, add <code>"-SSH_AUTH_SOCK"</code> anywhere in this
+                NOTE: All rules have `setenv { SSH_AUTH_SOCK }` by
+                default. To prevent `SSH_AUTH_SOCK` from being
+                inherited, add `"-SSH_AUTH_SOCK"` anywhere in this
                 list.
               '';
             };
···
             runAs = mkOption {
               type = with types; nullOr str;
               default = null;
-              description = ''
+              description = lib.mdDoc ''
                 Which user or group the specified command is allowed to run as.
-                When set to <code>null</code> (the default), all users are
+                When set to `null` (the default), all users are
                 allowed.
 
                 A user can be specified using just the username:
-                <code>"foo"</code>. It is also possible to only allow running as
-                a specific group with <code>":bar"</code>.
+                `"foo"`. It is also possible to only allow running as
+                a specific group with `":bar"`.
               '';
             };
 
             cmd = mkOption {
               type = with types; nullOr str;
               default = null;
-              description = ''
+              description = lib.mdDoc ''
                 The command the user is allowed to run. When set to
-                <code>null</code> (the default), all commands are allowed.
+                `null` (the default), all commands are allowed.
 
                 NOTE: It is best practice to specify absolute paths. If a
                 relative path is specified, only a restricted PATH will be
···
             args = mkOption {
               type = with types; nullOr (listOf str);
               default = null;
-              description = ''
+              description = lib.mdDoc ''
                 Arguments that must be provided to the command. When set to
-                <code>[]</code>, the command must be run without any arguments.
+                `[]`, the command must be run without any arguments.
               '';
             };
           };

nixos/modules/security/misc.nix

···
     security.allowSimultaneousMultithreading = mkOption {
       type = types.bool;
       default = true;
-      description = ''
+      description = lib.mdDoc ''
         Whether to allow SMT/hyperthreading.  Disabling SMT means that only
         physical CPU cores will be usable at runtime, potentially at
         significant performance cost.
···
         e.g., shared caches).  This attack vector is unproven.
 
         Disabling SMT is a supplement to the L1 data cache flushing mitigation
-        (see <xref linkend="opt-security.virtualisation.flushL1DataCache"/>)
+        (see [](#opt-security.virtualisation.flushL1DataCache))
         versus malicious VM guests (SMT could "bring back" previously flushed
         data).
       '';

nixos/modules/security/pam.nix

···
         default = config.krb5.enable;
         defaultText = literalExpression "config.krb5.enable";
         type = types.bool;
-        description = ''
-          Enables Kerberos PAM modules (<literal>pam-krb5</literal>,
-          <literal>pam-ccreds</literal>).
+        description = lib.mdDoc ''
+          Enables Kerberos PAM modules (`pam-krb5`,
+          `pam-ccreds`).
 
           If set, users can authenticate with their Kerberos password.
           This requires a valid Kerberos configuration
-          (<literal>config.krb5.enable</literal> should be set to
-          <literal>true</literal>).
+          (`config.krb5.enable` should be set to
+          `true`).
 
           Note that the Kerberos PAM modules are not necessary when using SSS
           to handle Kerberos authentication.
···
       enable = mkOption {
         default = false;
         type = types.bool;
-        description = ''
-          Enables P11 PAM (<literal>pam_p11</literal>) module.
+        description = lib.mdDoc ''
+          Enables P11 PAM (`pam_p11`) module.
 
           If set, users can log in with SSH keys and PKCS#11 tokens.
 
-          More information can be found <link
-          xlink:href="https://github.com/OpenSC/pam_p11">here</link>.
+          More information can be found [here](https://github.com/OpenSC/pam_p11).
         '';
       };
 
···
       enable = mkOption {
         default = false;
         type = types.bool;
-        description = ''
-          Enables U2F PAM (<literal>pam-u2f</literal>) module.
+        description = lib.mdDoc ''
+          Enables U2F PAM (`pam-u2f`) module.
 
           If set, users listed in
-          <filename>$XDG_CONFIG_HOME/Yubico/u2f_keys</filename> (or
-          <filename>$HOME/.config/Yubico/u2f_keys</filename> if XDG variable is
+          {file}`$XDG_CONFIG_HOME/Yubico/u2f_keys` (or
+          {file}`$HOME/.config/Yubico/u2f_keys` if XDG variable is
           not set) are able to log in with the associated U2F key. The path can
-          be changed using <option>security.pam.u2f.authFile</option> option.
+          be changed using {option}`security.pam.u2f.authFile` option.
 
           File format is:
-          <literal>username:first_keyHandle,first_public_key: second_keyHandle,second_public_key</literal>
-          This file can be generated using <command>pamu2fcfg</command> command.
+          `username:first_keyHandle,first_public_key: second_keyHandle,second_public_key`
+          This file can be generated using {command}`pamu2fcfg` command.
 
-          More information can be found <link
-          xlink:href="https://developers.yubico.com/pam-u2f/">here</link>.
+          More information can be found [here](https://developers.yubico.com/pam-u2f/).
         '';
       };
 
       authFile = mkOption {
         default = null;
         type = with types; nullOr path;
-        description = ''
-          By default <literal>pam-u2f</literal> module reads the keys from
-          <filename>$XDG_CONFIG_HOME/Yubico/u2f_keys</filename> (or
-          <filename>$HOME/.config/Yubico/u2f_keys</filename> if XDG variable is
+        description = lib.mdDoc ''
+          By default `pam-u2f` module reads the keys from
+          {file}`$XDG_CONFIG_HOME/Yubico/u2f_keys` (or
+          {file}`$HOME/.config/Yubico/u2f_keys` if XDG variable is
           not set).
 
           If you want to change auth file locations or centralize database (for
-          example use <filename>/etc/u2f-mappings</filename>) you can set this
+          example use {file}`/etc/u2f-mappings`) you can set this
           option.
 
           File format is:
-          <literal>username:first_keyHandle,first_public_key: second_keyHandle,second_public_key</literal>
-          This file can be generated using <command>pamu2fcfg</command> command.
+          `username:first_keyHandle,first_public_key: second_keyHandle,second_public_key`
+          This file can be generated using {command}`pamu2fcfg` command.
 
-          More information can be found <link
-          xlink:href="https://developers.yubico.com/pam-u2f/">here</link>.
+          More information can be found [here](https://developers.yubico.com/pam-u2f/).
         '';
       };
 
       appId = mkOption {
         default = null;
         type = with types; nullOr str;
-        description = ''
-            By default <literal>pam-u2f</literal> module sets the application
-            ID to <literal>pam://$HOSTNAME</literal>.
+        description = lib.mdDoc ''
+            By default `pam-u2f` module sets the application
+            ID to `pam://$HOSTNAME`.
 
-            When using <command>pamu2fcfg</command>, you can specify your
-            application ID with the <literal>-i</literal> flag.
+            When using {command}`pamu2fcfg`, you can specify your
+            application ID with the `-i` flag.
 
-            More information can be found <link
-            xlink:href="https://developers.yubico.com/pam-u2f/Manuals/pam_u2f.8.html">
-            here</link>
+            More information can be found [here](https://developers.yubico.com/pam-u2f/Manuals/pam_u2f.8.html)
         '';
       };
 
       origin = mkOption {
         default = null;
         type = with types; nullOr str;
-        description = ''
-            By default <literal>pam-u2f</literal> module sets the origin
-            to <literal>pam://$HOSTNAME</literal>.
+        description = lib.mdDoc ''
+            By default `pam-u2f` module sets the origin
+            to `pam://$HOSTNAME`.
             Setting origin to an host independent value will allow you to
             reuse credentials across machines
 
-            When using <command>pamu2fcfg</command>, you can specify your
-            application ID with the <literal>-o</literal> flag.
+            When using {command}`pamu2fcfg`, you can specify your
+            application ID with the `-o` flag.
 
-            More information can be found <link
-            xlink:href="https://developers.yubico.com/pam-u2f/Manuals/pam_u2f.8.html">
-            here</link>
+            More information can be found [here](https://developers.yubico.com/pam-u2f/Manuals/pam_u2f.8.html)
         '';
       };
 
···
       enable = mkOption {
         default = false;
         type = types.bool;
-        description = ''
-          Enables Uber's USSH PAM (<literal>pam-ussh</literal>) module.
+        description = lib.mdDoc ''
+          Enables Uber's USSH PAM (`pam-ussh`) module.
 
-          This is similar to <literal>pam-ssh-agent</literal>, except that
+          This is similar to `pam-ssh-agent`, except that
           the presence of a CA-signed SSH key with a valid principal is checked
           instead.
 
           Note that this module must both be enabled using this option and on a
-          per-PAM-service level as well (using <literal>usshAuth</literal>).
+          per-PAM-service level as well (using `usshAuth`).
 
-          More information can be found <link
-          xlink:href="https://github.com/uber/pam-ussh">here</link>.
+          More information can be found [here](https://github.com/uber/pam-ussh).
         '';
       };
 
···
       enable = mkOption {
         default = false;
         type = types.bool;
-        description = ''
-          Enables Yubico PAM (<literal>yubico-pam</literal>) module.
+        description = lib.mdDoc ''
+          Enables Yubico PAM (`yubico-pam`) module.
 
           If set, users listed in
-          <filename>~/.yubico/authorized_yubikeys</filename>
+          {file}`~/.yubico/authorized_yubikeys`
           are able to log in with the associated Yubikey tokens.
 
           The file must have only one line:
-          <literal>username:yubikey_token_id1:yubikey_token_id2</literal>
-          More information can be found <link
-          xlink:href="https://developers.yubico.com/yubico-pam/">here</link>.
+          `username:yubikey_token_id1:yubikey_token_id2`
+          More information can be found [here](https://developers.yubico.com/yubico-pam/).
         '';
       };
       control = mkOption {
···
       mode = mkOption {
         default = "client";
         type = types.enum [ "client" "challenge-response" ];
-        description = ''
+        description = lib.mdDoc ''
           Mode of operation.
 
           Use "client" for online validation with a YubiKey validation service such as
···
           Challenge-Response configurations. See the man-page ykpamcfg(1) for further
           details on how to configure offline Challenge-Response validation.
 
-          More information can be found <link
-          xlink:href="https://developers.yubico.com/yubico-pam/Authentication_Using_Challenge-Response.html">here</link>.
+          More information can be found [here](https://developers.yubico.com/yubico-pam/Authentication_Using_Challenge-Response.html).
         '';
       };
       challengeResponsePath = mkOption {
         default = null;
         type = types.nullOr types.path;
-        description = ''
+        description = lib.mdDoc ''
           If not null, set the path used by yubico pam module where the challenge expected response is stored.
 
-          More information can be found <link
-          xlink:href="https://developers.yubico.com/yubico-pam/Authentication_Using_Challenge-Response.html">here</link>.
+          More information can be found [here](https://developers.yubico.com/yubico-pam/Authentication_Using_Challenge-Response.html).
         '';
       };
     };

nixos/modules/security/pam_mount.nix

···
       extraVolumes = mkOption {
         type = types.listOf types.str;
         default = [];
-        description = ''
+        description = lib.mdDoc ''
           List of volume definitions for pam_mount.
-          For more information, visit <link
-          xlink:href="http://pam-mount.sourceforge.net/pam_mount.conf.5.html" />.
+          For more information, visit <http://pam-mount.sourceforge.net/pam_mount.conf.5.html>.
         '';
       };
 
···
         type = types.int;
         default = 0;
         example = 1;
-        description = ''
+        description = lib.mdDoc ''
           Sets the Debug-Level. 0 disables debugging, 1 enables pam_mount tracing,
           and 2 additionally enables tracing in mount.crypt. The default is 0.
-          For more information, visit <link
-          xlink:href="http://pam-mount.sourceforge.net/pam_mount.conf.5.html" />.
+          For more information, visit <http://pam-mount.sourceforge.net/pam_mount.conf.5.html>.
         '';
       };
 
       logoutWait = mkOption {
         type = types.int;
         default = 0;
-        description = ''
+        description = lib.mdDoc ''
           Amount of microseconds to wait until killing remaining processes after
           final logout.
-          For more information, visit <link
-          xlink:href="http://pam-mount.sourceforge.net/pam_mount.conf.5.html" />.
+          For more information, visit <http://pam-mount.sourceforge.net/pam_mount.conf.5.html>.
         '';
       };
 

nixos/modules/security/pam_usb.nix

···
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Enable USB login for all login systems that support it.  For
-          more information, visit <link
-          xlink:href="https://github.com/aluzzardi/pam_usb/wiki/Getting-Started#setting-up-devices-and-users" />.
+          more information, visit <https://github.com/aluzzardi/pam_usb/wiki/Getting-Started#setting-up-devices-and-users>.
         '';
       };
 

nixos/modules/security/sudo.nix

···
       type = types.bool;
       default = true;
       description =
-        ''
-          Whether users of the <code>wheel</code> group must
-          provide a password to run commands as super user via <command>sudo</command>.
+        lib.mdDoc ''
+          Whether users of the `wheel` group must
+          provide a password to run commands as super user via {command}`sudo`.
         '';
       };
 
     security.sudo.execWheelOnly = mkOption {
       type = types.bool;
       default = false;
-      description = ''
-        Only allow members of the <code>wheel</code> group to execute sudo by
+      description = lib.mdDoc ''
+        Only allow members of the `wheel` group to execute sudo by
         setting the executable's permissions accordingly.
-        This prevents users that are not members of <code>wheel</code> from
+        This prevents users that are not members of `wheel` from
         exploiting vulnerabilities in sudo such as CVE-2021-3156.
       '';
     };
···
           runAs = mkOption {
             type = with types; str;
             default = "ALL:ALL";
-            description = ''
+            description = lib.mdDoc ''
               Under which user/group the specified command is allowed to run.
 
-              A user can be specified using just the username: <code>"foo"</code>.
-              It is also possible to specify a user/group combination using <code>"foo:bar"</code>
-              or to only allow running as a specific group with <code>":bar"</code>.
+              A user can be specified using just the username: `"foo"`.
+              It is also possible to specify a user/group combination using `"foo:bar"`
+              or to only allow running as a specific group with `":bar"`.
             '';
           };
 
···
                   type = with types; str;
                   description = ''
                     A command being either just a path to a binary to allow any arguments,
-                    the full command with arguments pre-set or with <code>""</code> used as the argument,
+                    the full command with arguments pre-set or with <literal>""</literal> used as the argument,
                     not allowing arguments to the command at all.
                   '';
                 };

nixos/modules/services/backup/duplicity.nix

···
         <citerefentry><refentrytitle>systemd.exec</refentrytitle>
         <manvolnum>5</manvolnum></citerefentry>. For example:
         <programlisting>
-        PASSPHRASE=<replaceable>...</replaceable>
-        AWS_ACCESS_KEY_ID=<replaceable>...</replaceable>
-        AWS_SECRET_ACCESS_KEY=<replaceable>...</replaceable>
+        PASSPHRASE=«...»
+        AWS_ACCESS_KEY_ID=«...»
+        AWS_SECRET_ACCESS_KEY=«...»
         </programlisting>
       '';
     };

nixos/modules/services/backup/restic.nix

···
           type = types.package;
           default = pkgs.restic;
           defaultText = literalExpression "pkgs.restic";
-          description = ''
+          description = lib.mdDoc ''
             Restic package to use.
           '';
         };

nixos/modules/services/backup/syncoid.nix

···
           target = mkOption {
             type = types.str;
             example = "user@server:pool/dataset";
-            description = ''
+            description = lib.mdDoc ''
               Target ZFS dataset. Can be either local
-              (<replaceable>pool/dataset</replaceable>) or remote
-              (<replaceable>user@server:pool/dataset</replaceable>).
+              («pool/dataset») or remote
+              («user@server:pool/dataset»).
             '';
           };
 

nixos/modules/services/backup/zrepl.nix

···
 
       settings = mkOption {
         default = { };
-        description = ''
-          Configuration for zrepl. See <link
-          xlink:href="https://zrepl.github.io/configuration.html"/>
+        description = lib.mdDoc ''
+          Configuration for zrepl. See <https://zrepl.github.io/configuration.html>
           for more information.
         '';
         type = types.submodule {

nixos/modules/services/continuous-integration/github-runner.nix

···
     enable = mkOption {
       default = false;
       example = true;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable GitHub Actions runner.
 
         Note: GitHub recommends using self-hosted runners with private repositories only. Learn more here:
-        <link xlink:href="https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners"
-        >About self-hosted runners</link>.
+        [About self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners).
       '';
       type = lib.types.bool;
     };

nixos/modules/services/continuous-integration/gitlab-runner.nix

···
     configFile = mkOption {
       type = types.nullOr types.path;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Configuration file for gitlab-runner.
 
-        <option>configFile</option> takes precedence over <option>services</option>.
-        <option>checkInterval</option> and <option>concurrent</option> will be ignored too.
+        {option}`configFile` takes precedence over {option}`services`.
+        {option}`checkInterval` and {option}`concurrent` will be ignored too.
 
-        This option is deprecated, please use <option>services</option> instead.
-        You can use <option>registrationConfigFile</option> and
-        <option>registrationFlags</option>
+        This option is deprecated, please use {option}`services` instead.
+        You can use {option}`registrationConfigFile` and
+        {option}`registrationFlags`
         for settings not covered by this module.
       '';
     };
···
         freeformType = (pkgs.formats.json { }).type;
       };
       default = { };
-      description = ''
+      description = lib.mdDoc ''
         Global gitlab-runner configuration. See
-        <link xlink:href="https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section"/>
+        <https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section>
         for supported values.
       '';
     };
     gracefulTermination = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Finish all remaining jobs before stopping.
         If not set gitlab-runner will stop immediatly without waiting
         for jobs to finish, which will lead to failed builds.
···
       type = types.str;
       default = "infinity";
       example = "5min 20s";
-      description = ''
+      description = lib.mdDoc ''
         Time to wait until a graceful shutdown is turned into a forceful one.
       '';
     };
···
       default = pkgs.gitlab-runner;
       defaultText = literalExpression "pkgs.gitlab-runner";
       example = literalExpression "pkgs.gitlab-runner_1_11";
-      description = "Gitlab Runner package to use.";
+      description = lib.mdDoc "Gitlab Runner package to use.";
     };
     extraPackages = mkOption {
       type = types.listOf types.package;
       default = [ ];
-      description = ''
+      description = lib.mdDoc ''
         Extra packages to add to PATH for the gitlab-runner process.
       '';
     };
     services = mkOption {
-      description = "GitLab Runner services.";
+      description = lib.mdDoc "GitLab Runner services.";
       default = { };
       example = literalExpression ''
         {
···
         options = {
           registrationConfigFile = mkOption {
             type = types.path;
-            description = ''
+            description = lib.mdDoc ''
               Absolute path to a file with environment variables
               used for gitlab-runner registration.
               A list of all supported environment variables can be found in
-              <literal>gitlab-runner register --help</literal>.
+              `gitlab-runner register --help`.
 
               Ones that you probably want to set is
 
-              <literal>CI_SERVER_URL=&lt;CI server URL&gt;</literal>
+              `CI_SERVER_URL=<CI server URL>`
 
-              <literal>REGISTRATION_TOKEN=&lt;registration secret&gt;</literal>
+              `REGISTRATION_TOKEN=<registration secret>`
 
               WARNING: make sure to use quoted absolute path,
               or it is going to be copied to Nix Store.
···
             type = types.listOf types.str;
             default = [ ];
             example = [ "--docker-helper-image my/gitlab-runner-helper" ];
-            description = ''
+            description = lib.mdDoc ''
               Extra command-line flags passed to
-              <literal>gitlab-runner register</literal>.
-              Execute <literal>gitlab-runner register --help</literal>
+              `gitlab-runner register`.
+              Execute `gitlab-runner register --help`
               for a list of supported flags.
             '';
           };
···
             type = types.attrsOf types.str;
             default = { };
             example = { NAME = "value"; };
-            description = ''
+            description = lib.mdDoc ''
               Custom environment variables injected to build environment.
-              For secrets you can use <option>registrationConfigFile</option>
-              with <literal>RUNNER_ENV</literal> variable set.
+              For secrets you can use {option}`registrationConfigFile`
+              with `RUNNER_ENV` variable set.
             '';
           };
           description = mkOption {
             type = types.nullOr types.str;
             default = null;
-            description = ''
+            description = lib.mdDoc ''
               Name/description of the runner.
             '';
           };
           executor = mkOption {
             type = types.str;
             default = "docker";
-            description = ''
+            description = lib.mdDoc ''
               Select executor, eg. shell, docker, etc.
-              See <link xlink:href="https://docs.gitlab.com/runner/executors/README.html">runner documentation</link> for more information.
+              See [runner documentation](https://docs.gitlab.com/runner/executors/README.html) for more information.
             '';
           };
           buildsDir = mkOption {
             type = types.nullOr types.path;
             default = null;
             example = "/var/lib/gitlab-runner/builds";
-            description = ''
+            description = lib.mdDoc ''
               Absolute path to a directory where builds will be stored
               in context of selected executor (Locally, Docker, SSH).
             '';
···
             type = types.nullOr types.str;
             default = null;
             example = "http://gitlab.example.local";
-            description = ''
+            description = lib.mdDoc ''
               Overwrite the URL for the GitLab instance. Used if the Runner can’t connect to GitLab on the URL GitLab exposes itself.
             '';
           };
           dockerImage = mkOption {
             type = types.nullOr types.str;
             default = null;
-            description = ''
+            description = lib.mdDoc ''
               Docker image to be used.
             '';
           };
···
             type = types.listOf types.str;
             default = [ ];
             example = [ "/var/run/docker.sock:/var/run/docker.sock" ];
-            description = ''
+            description = lib.mdDoc ''
               Bind-mount a volume and create it
               if it doesn't exist prior to mounting.
             '';
···
           dockerDisableCache = mkOption {
             type = types.bool;
             default = false;
-            description = ''
+            description = lib.mdDoc ''
               Disable all container caching.
             '';
           };
           dockerPrivileged = mkOption {
             type = types.bool;
             default = false;
-            description = ''
+            description = lib.mdDoc ''
               Give extended privileges to container.
             '';
           };
···
             type = types.listOf types.str;
             default = [ ];
             example = [ "other-host:127.0.0.1" ];
-            description = ''
+            description = lib.mdDoc ''
               Add a custom host-to-IP mapping.
             '';
           };
···
             type = types.listOf types.str;
             default = [ ];
             example = [ "ruby:*" "python:*" "php:*" "my.registry.tld:5000/*:*" ];
-            description = ''
+            description = lib.mdDoc ''
               Whitelist allowed images.
             '';
           };
···
             type = types.listOf types.str;
             default = [ ];
             example = [ "postgres:9" "redis:*" "mysql:*" ];
-            description = ''
+            description = lib.mdDoc ''
               Whitelist allowed services.
             '';
           };
           preCloneScript = mkOption {
             type = types.nullOr types.path;
             default = null;
-            description = ''
+            description = lib.mdDoc ''
               Runner-specific command script executed before code is pulled.
             '';
           };
           preBuildScript = mkOption {
             type = types.nullOr types.path;
             default = null;
-            description = ''
+            description = lib.mdDoc ''
               Runner-specific command script executed after code is pulled,
               just before build executes.
             '';
···
           postBuildScript = mkOption {
             type = types.nullOr types.path;
             default = null;
-            description = ''
+            description = lib.mdDoc ''
               Runner-specific command script executed after code is pulled
               and just after build executes.
             '';
···
           tagList = mkOption {
             type = types.listOf types.str;
             default = [ ];
-            description = ''
+            description = lib.mdDoc ''
               Tag list.
             '';
           };
           runUntagged = mkOption {
             type = types.bool;
             default = false;
-            description = ''
+            description = lib.mdDoc ''
               Register to run untagged builds; defaults to
-              <literal>true</literal> when <option>tagList</option> is empty.
+              `true` when {option}`tagList` is empty.
             '';
           };
           limit = mkOption {
             type = types.int;
             default = 0;
-            description = ''
+            description = lib.mdDoc ''
               Limit how many jobs can be handled concurrently by this service.
               0 (default) simply means don't limit.
             '';
···
           requestConcurrency = mkOption {
             type = types.int;
             default = 0;
-            description = ''
+            description = lib.mdDoc ''
               Limit number of concurrent requests for new jobs from GitLab.
             '';
           };
           maximumTimeout = mkOption {
             type = types.int;
             default = 0;
-            description = ''
+            description = lib.mdDoc ''
               What is the maximum timeout (in seconds) that will be set for
               job when using this Runner. 0 (default) simply means don't limit.
             '';
···
           protected = mkOption {
             type = types.bool;
             default = false;
-            description = ''
+            description = lib.mdDoc ''
               When set to true Runner will only run on pipelines
               triggered on protected branches.
             '';
···
           debugTraceDisabled = mkOption {
             type = types.bool;
             default = false;
-            description = ''
+            description = lib.mdDoc ''
               When set to true Runner will disable the possibility of
-              using the <literal>CI_DEBUG_TRACE</literal> feature.
+              using the `CI_DEBUG_TRACE` feature.
             '';
           };
         };

nixos/modules/services/databases/firebird.nix

···
         defaultText = literalExpression "pkgs.firebird";
         type = types.package;
         example = literalExpression "pkgs.firebird_3";
-        description = ''
-          Which Firebird package to be installed: <code>pkgs.firebird_3</code>
-          For SuperServer use override: <code>pkgs.firebird_3.override { superServer = true; };</code>
+        description = lib.mdDoc ''
+          Which Firebird package to be installed: `pkgs.firebird_3`
+          For SuperServer use override: `pkgs.firebird_3.override { superServer = true; };`
         '';
       };
 

nixos/modules/services/databases/mysql.nix

···
             ensurePermissions = mkOption {
               type = types.attrsOf types.str;
               default = {};
-              description = ''
+              description = lib.mdDoc ''
                 Permissions to ensure for the user, specified as attribute set.
                 The attribute names specify the database and tables to grant the permissions for,
                 separated by a dot. You may use wildcards here.
···
 
                 For more information on how to specify the target
                 and on which privileges exist, see the
-                <link xlink:href="https://mariadb.com/kb/en/library/grant/">GRANT syntax</link>.
-                The attributes are used as <code>GRANT ''${attrName} ON ''${attrValue}</code>.
+                [GRANT syntax](https://mariadb.com/kb/en/library/grant/).
+                The attributes are used as `GRANT ''${attrName} ON ''${attrValue}`.
               '';
               example = literalExpression ''
                 {

nixos/modules/services/databases/neo4j.nix

···
     constrainLoadCsv = mkOption {
       type = types.bool;
       default = true;
-      description = ''
+      description = lib.mdDoc ''
         Sets the root directory for file URLs used with the Cypher
-        <literal>LOAD CSV</literal> clause to be that defined by
-        <option>directories.imports</option>. It restricts
+        `LOAD CSV` clause to be that defined by
+        {option}`directories.imports`. It restricts
         access to only those files within that directory and its
         subdirectories.
-        </para>
-        <para>
-        Setting this option to <literal>false</literal> introduces
+
+        Setting this option to `false` introduces
         possible security problems.
       '';
     };
···
     defaultListenAddress = mkOption {
       type = types.str;
       default = "127.0.0.1";
-      description = ''
+      description = lib.mdDoc ''
         Default network interface to listen for incoming connections. To
         listen for connections on all interfaces, use "0.0.0.0".
-        </para>
-        <para>
+
         Specifies the default IP address and address part of connector
-        specific <option>listenAddress</option> options. To bind specific
+        specific {option}`listenAddress` options. To bind specific
         connectors to a specific network interfaces, specify the entire
-        <option>listenAddress</option> option for that connector.
+        {option}`listenAddress` option for that connector.
       '';
     };
 
···
       sslPolicy = mkOption {
         type = types.str;
         default = "legacy";
-        description = ''
+        description = lib.mdDoc ''
           Neo4j SSL policy for BOLT traffic.
-          </para>
-          <para>
+
           The legacy policy is a special policy which is not defined in
           the policy configuration section, but rather derives from
-          <option>directories.certificates</option> and
-          associated files (by default: <filename>neo4j.key</filename> and
-          <filename>neo4j.cert</filename>). Its use will be deprecated.
-          </para>
-          <para>
+          {option}`directories.certificates` and
+          associated files (by default: {file}`neo4j.key` and
+          {file}`neo4j.cert`). Its use will be deprecated.
+
           Note: This connector must be configured to support/require
           SSL/TLS for the legacy policy to actually be utilized. See
-          <option>bolt.tlsLevel</option>.
+          {option}`bolt.tlsLevel`.
         '';
       };
 
···
         type = types.path;
         default = "${cfg.directories.home}/certificates";
         defaultText = literalExpression ''"''${config.${opt.directories.home}}/certificates"'';
-        description = ''
+        description = lib.mdDoc ''
           Directory for storing certificates to be used by Neo4j for
           TLS connections.
-          </para>
-          <para>
+
           When setting this directory to something other than its default,
           ensure the directory's existence, and that read/write permissions are
-          given to the Neo4j daemon user <literal>neo4j</literal>.
-          </para>
-          <para>
+          given to the Neo4j daemon user `neo4j`.
+
           Note that changing this directory from its default will prevent
           the directory structure required for each SSL policy from being
           automatically generated. A policy's directory structure as defined by
-          its <option>baseDirectory</option>,<option>revokedDir</option> and
-          <option>trustedDir</option> must then be setup manually. The
+          its {option}`baseDirectory`,{option}`revokedDir` and
+          {option}`trustedDir` must then be setup manually. The
           existence of these directories is mandatory, as well as the presence
           of the certificate file and the private key. Ensure the correct
           permissions are set on these directories and files.
···
         type = types.path;
         default = "${cfg.directories.home}/data";
         defaultText = literalExpression ''"''${config.${opt.directories.home}}/data"'';
-        description = ''
+        description = lib.mdDoc ''
           Path of the data directory. You must not configure more than one
           Neo4j installation to use the same data directory.
-          </para>
-          <para>
+
           When setting this directory to something other than its default,
           ensure the directory's existence, and that read/write permissions are
-          given to the Neo4j daemon user <literal>neo4j</literal>.
+          given to the Neo4j daemon user `neo4j`.
         '';
       };
 
···
         type = types.path;
         default = "${cfg.directories.home}/import";
         defaultText = literalExpression ''"''${config.${opt.directories.home}}/import"'';
-        description = ''
+        description = lib.mdDoc ''
           The root directory for file URLs used with the Cypher
-          <literal>LOAD CSV</literal> clause. Only meaningful when
-          <option>constrainLoadCvs</option> is set to
-          <literal>true</literal>.
-          </para>
-          <para>
+          `LOAD CSV` clause. Only meaningful when
+          {option}`constrainLoadCvs` is set to
+          `true`.
+
           When setting this directory to something other than its default,
           ensure the directory's existence, and that read permission is
-          given to the Neo4j daemon user <literal>neo4j</literal>.
+          given to the Neo4j daemon user `neo4j`.
         '';
       };
 
···
         type = types.path;
         default = "${cfg.directories.home}/plugins";
         defaultText = literalExpression ''"''${config.${opt.directories.home}}/plugins"'';
-        description = ''
+        description = lib.mdDoc ''
           Path of the database plugin directory. Compiled Java JAR files that
           contain database procedures will be loaded if they are placed in
           this directory.
-          </para>
-          <para>
+
           When setting this directory to something other than its default,
           ensure the directory's existence, and that read permission is
-          given to the Neo4j daemon user <literal>neo4j</literal>.
+          given to the Neo4j daemon user `neo4j`.
         '';
       };
     };
···
       sslPolicy = mkOption {
         type = types.str;
         default = "legacy";
-        description = ''
+        description = lib.mdDoc ''
           Neo4j SSL policy for HTTPS traffic.
-          </para>
-          <para>
+
           The legacy policy is a special policy which is not defined in the
           policy configuration section, but rather derives from
-          <option>directories.certificates</option> and
-          associated files (by default: <filename>neo4j.key</filename> and
-          <filename>neo4j.cert</filename>). Its use will be deprecated.
+          {option}`directories.certificates` and
+          associated files (by default: {file}`neo4j.key` and
+          {file}`neo4j.cert`). Its use will be deprecated.
         '';
       };
     };
···
           allowKeyGeneration = mkOption {
             type = types.bool;
             default = false;
-            description = ''
+            description = lib.mdDoc ''
               Allows the generation of a private key and associated self-signed
               certificate. Only performed when both objects cannot be found for
               this policy. It is recommended to turn this off again after keys
               have been generated.
-              </para>
-              <para>
+
               The public certificate is required to be duplicated to the
               directory holding trusted certificates as defined by the
-              <option>trustedDir</option> option.
-              </para>
-              <para>
+              {option}`trustedDir` option.
+
               Keys should in general be generated and distributed offline by a
               trusted certificate authority and not by utilizing this mode.
             '';
···
             type = types.path;
             default = "${cfg.directories.certificates}/${name}";
             defaultText = literalExpression ''"''${config.${opt.directories.certificates}}/''${name}"'';
-            description = ''
+            description = lib.mdDoc ''
               The mandatory base directory for cryptographic objects of this
               policy. This path is only automatically generated when this
-              option as well as <option>directories.certificates</option> are
+              option as well as {option}`directories.certificates` are
               left at their default. Ensure read/write permissions are given
-              to the Neo4j daemon user <literal>neo4j</literal>.
-              </para>
-              <para>
+              to the Neo4j daemon user `neo4j`.
+
               It is also possible to override each individual
               configuration with absolute paths. See the
-              <option>privateKey</option> and <option>publicCertificate</option>
+              {option}`privateKey` and {option}`publicCertificate`
               policy options.
             '';
           };
···
           publicCertificate = mkOption {
             type = types.str;
             default = "public.crt";
-            description = ''
+            description = lib.mdDoc ''
               The name of public X.509 certificate (chain) file in PEM format
-              for this policy to be found in the <option>baseDirectory</option>,
+              for this policy to be found in the {option}`baseDirectory`,
               or the absolute path to the certificate file. It is mandatory
               that a certificate can be found or generated.
-              </para>
-              <para>
+
               The public certificate is required to be duplicated to the
               directory holding trusted certificates as defined by the
-              <option>trustedDir</option> option.
+              {option}`trustedDir` option.
             '';
           };
 
···
             type = types.path;
             default = "${config.baseDirectory}/trusted";
             defaultText = literalExpression ''"''${config.${options.baseDirectory}}/trusted"'';
-            description = ''
+            description = lib.mdDoc ''
               Path to directory of X.509 certificates in PEM format for
               trusted parties. Must be an absolute path. The existence of this
               directory is mandatory and will need to be created manually when:
               setting this option to something other than its default; setting
-              either this policy's <option>baseDirectory</option> or
-              <option>directories.certificates</option> to something other than
+              either this policy's {option}`baseDirectory` or
+              {option}`directories.certificates` to something other than
               their default. Ensure read/write permissions are given to the
-              Neo4j daemon user <literal>neo4j</literal>.
-              </para>
-              <para>
+              Neo4j daemon user `neo4j`.
+
               The public certificate as defined by
-              <option>publicCertificate</option> is required to be duplicated
+              {option}`publicCertificate` is required to be duplicated
               to this directory.
             '';
           };

nixos/modules/services/databases/openldap.nix

···
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = "Whether to enable the ldap server.";
+        description = lib.mdDoc "Whether to enable the ldap server.";
       };
 
       package = mkOption {
···
       configDir = mkOption {
         type = types.nullOr types.path;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Use this config directory instead of generating one from the
-          <literal>settings</literal> option. Overrides all NixOS settings.
+          `settings` option. Overrides all NixOS settings.
         '';
         example = "/var/lib/openldap/slapd.d";
       };
···
       mutableConfig = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to allow writable on-line configuration. If
-          <literal>true</literal>, the NixOS settings will only be used to
+          `true`, the NixOS settings will only be used to
           initialize the OpenLDAP configuration if it does not exist, and are
           subsequently ignored.
         '';

nixos/modules/services/databases/pgmanage.nix

···
         nuc-server  = "hostaddr=192.168.0.100 port=5432 dbname=postgres";
         mini-server = "hostaddr=127.0.0.1 port=5432 dbname=postgres sslmode=require";
       };
-      description = ''
+      description = lib.mdDoc ''
         pgmanage requires at least one PostgreSQL server be defined.
-        </para><para>
+
         Detailed information about PostgreSQL connection strings is available at:
-        <link xlink:href="http://www.postgresql.org/docs/current/static/libpq-connect.html"/>
-        </para><para>
+        <http://www.postgresql.org/docs/current/static/libpq-connect.html>
+
         Note that you should not specify your user name or password. That
         information will be entered on the login screen. If you specify a
         username or password, it will be removed by pgmanage before attempting to

nixos/modules/services/databases/postgresql.nix

···
         default = "";
         description = ''
           Defines how users authenticate themselves to the server. See the
-          <link xlink:href="https://www.postgresql.org/docs/current/auth-pg-hba-conf.html">
-          PostgreSQL documentation for pg_hba.conf</link>
+          <link xlink:href="https://www.postgresql.org/docs/current/auth-pg-hba-conf.html">PostgreSQL documentation for pg_hba.conf</link>
           for details on the expected format of this option. By default,
           peer based authentication will be used for users connecting
           via the Unix socket, and md5 password authentication will be
···
             ensurePermissions = mkOption {
               type = types.attrsOf types.str;
               default = {};
-              description = ''
+              description = lib.mdDoc ''
                 Permissions to ensure for the user, specified as an attribute set.
                 The attribute names specify the database and tables to grant the permissions for.
                 The attribute values specify the permissions to grant. You may specify one or
···
 
                 For more information on how to specify the target
                 and on which privileges exist, see the
-                <link xlink:href="https://www.postgresql.org/docs/current/sql-grant.html">GRANT syntax</link>.
-                The attributes are used as <code>GRANT ''${attrValue} ON ''${attrName}</code>.
+                [GRANT syntax](https://www.postgresql.org/docs/current/sql-grant.html).
+                The attributes are used as `GRANT ''${attrValue} ON ''${attrName}`.
               '';
               example = literalExpression ''
                 {

nixos/modules/services/databases/victoriametrics.nix

···
     extraOptions = mkOption {
       type = types.listOf types.str;
       default = [];
-      description = ''
-        Extra options to pass to VictoriaMetrics. See the README: <link
-        xlink:href="https://github.com/VictoriaMetrics/VictoriaMetrics/blob/master/README.md" />
-        or <command>victoriametrics -help</command> for more
+      description = lib.mdDoc ''
+        Extra options to pass to VictoriaMetrics. See the README:
+        <https://github.com/VictoriaMetrics/VictoriaMetrics/blob/master/README.md>
+        or {command}`victoriametrics -help` for more
         information.
       '';
     };

nixos/modules/services/development/zammad.nix

···
           '';
           description = ''
             The <filename>database.yml</filename> configuration file as key value set.
-            See <link xlink:href='TODO' />
+            See <link xlink:href="TODO"/>
             for list of configuration parameters.
           '';
         };

nixos/modules/services/games/asf.nix

···
           };
           settings = mkOption {
             type = types.attrs;
-            description = "Additional settings that are documented <link xlink:href=\"https://github.com/JustArchiNET/ArchiSteamFarm/wiki/Configuration#bot-config\">here</link>.";
+            description = lib.mdDoc ''
+              Additional settings that are documented [here](https://github.com/JustArchiNET/ArchiSteamFarm/wiki/Configuration#bot-config).
+            '';
             default = { };
           };
         };

nixos/modules/services/hardware/kanata.nix

···
       device = mkOption {
         type = types.str;
         example = "/dev/input/by-id/usb-0000_0000-event-kbd";
-        description = "Path to the keyboard device.";
+        description = lib.mdDoc "Path to the keyboard device.";
       };
       config = mkOption {
         type = types.lines;
···
             ;; tap within 100ms for capslk, hold more than 100ms for lctl
             cap (tap-hold 100 100 caps lctl))
         '';
-        description = ''
+        description = lib.mdDoc ''
           Configuration other than defcfg.
-          See <link xlink:href="https://github.com/jtroo/kanata"/> for more information.
+          See <https://github.com/jtroo/kanata> for more information.
         '';
       };
       extraDefCfg = mkOption {
         type = types.lines;
         default = "";
         example = "danger-enable-cmd yes";
-        description = ''
+        description = lib.mdDoc ''
           Configuration of defcfg other than linux-dev.
-          See <link xlink:href="https://github.com/jtroo/kanata"/> for more information.
+          See <https://github.com/jtroo/kanata> for more information.
         '';
       };
     };
···
       default = pkgs.kanata;
       defaultText = lib.literalExpression "pkgs.kanata";
       example = lib.literalExpression "pkgs.kanata-with-cmd";
-      description = ''
+      description = lib.mdDoc ''
         kanata package to use.
         If you enable danger-enable-cmd, pkgs.kanata-with-cmd should be used.
       '';
···
     keyboards = mkOption {
       type = types.attrsOf (types.submodule keyboard);
       default = { };
-      description = "Keyboard configurations.";
+      description = lib.mdDoc "Keyboard configurations.";
     };
   };
 

nixos/modules/services/hardware/lcd.nix

···
           default = false;
           description = ''
             Set group-write permissions on a USB device.
-            </para>
-            <para>
+
             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.usbPid</option>. In order to find the
             values, you can run the <command>lsusb</command> command. Example
             output:
-            </para>
-            <para>
+
             <literal>
             Bus 005 Device 002: ID 0403:c630 Future Technology Devices International, Ltd lcd2usb interface
             </literal>
-            </para>
-            <para>
+
             In this case the vendor id is 0403 and the product id is c630.
           '';
         };

nixos/modules/services/hardware/udev.nix

···
       packages = mkOption {
         type = types.listOf types.path;
         default = [];
-        description = ''
-          List of packages containing <command>udev</command> rules.
+        description = lib.mdDoc ''
+          List of packages containing {command}`udev` rules.
           All files found in
-          <filename><replaceable>pkg</replaceable>/etc/udev/rules.d</filename> and
-          <filename><replaceable>pkg</replaceable>/lib/udev/rules.d</filename>
+          {file}`«pkg»/etc/udev/rules.d` and
+          {file}`«pkg»/lib/udev/rules.d`
           will be included.
         '';
         apply = map getBin;
···
     networking.usePredictableInterfaceNames = mkOption {
       default = true;
       type = types.bool;
-      description = ''
-        Whether to assign <link
-        xlink:href='http://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames'>predictable
-        names to network interfaces</link>.  If enabled, interfaces
+      description = lib.mdDoc ''
+        Whether to assign [predictable names to network interfaces](http://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames).
+        If enabled, interfaces
         are assigned names that contain topology information
-        (e.g. <literal>wlp3s0</literal>) and thus should be stable
+        (e.g. `wlp3s0`) and thus should be stable
         across reboots.  If disabled, names depend on the order in
         which interfaces are discovered by the kernel, which may
         change randomly across reboots; for instance, you may find
-        <literal>eth0</literal> and <literal>eth1</literal> flipping
+        `eth0` and `eth1` flipping
         unpredictably.
       '';
     };
···
 
           List of packages containing <command>udev</command> rules that will be copied to stage 1.
           All files found in
-          <filename><replaceable>pkg</replaceable>/etc/udev/rules.d</filename> and
-          <filename><replaceable>pkg</replaceable>/lib/udev/rules.d</filename>
+          <filename>«pkg»/etc/udev/rules.d</filename> and
+          <filename>«pkg»/lib/udev/rules.d</filename>
           will be included.
         '';
       };

nixos/modules/services/logging/filebeat.nix

···
       };
 
       inputs = mkOption {
-        description = ''
+        description = lib.mdDoc ''
           Inputs specify how Filebeat locates and processes input data.
 
-          This is like <literal>services.filebeat.settings.filebeat.inputs</literal>,
+          This is like `services.filebeat.settings.filebeat.inputs`,
           but structured as an attribute set. This has the benefit
           that multiple NixOS modules can contribute settings to a
           single filebeat input.
 
           An input type can be specified multiple times by choosing a
-          different <literal>&lt;name></literal> for each, but setting
-          <xref linkend="opt-services.filebeat.inputs._name_.type"/>
+          different `<name>` for each, but setting
+          [](#opt-services.filebeat.inputs._name_.type)
           to the same value.
 
-          See <link xlink:href="https://www.elastic.co/guide/en/beats/filebeat/current/configuration-filebeat-options.html"/>.
+          See <https://www.elastic.co/guide/en/beats/filebeat/current/configuration-filebeat-options.html>.
         '';
         default = {};
         type = types.attrsOf (types.submodule ({ name, ... }: {
···
       };
 
       modules = mkOption {
-        description = ''
+        description = lib.mdDoc ''
           Filebeat modules provide a quick way to get started
           processing common log formats. They contain default
           configurations, Elasticsearch ingest pipeline definitions,
           and Kibana dashboards to help you implement and deploy a log
           monitoring solution.
 
-          This is like <literal>services.filebeat.settings.filebeat.modules</literal>,
+          This is like `services.filebeat.settings.filebeat.modules`,
           but structured as an attribute set. This has the benefit
           that multiple NixOS modules can contribute settings to a
           single filebeat module.
 
           A module can be specified multiple times by choosing a
-          different <literal>&lt;name></literal> for each, but setting
-          <xref linkend="opt-services.filebeat.modules._name_.module"/>
+          different `<name>` for each, but setting
+          [](#opt-services.filebeat.modules._name_.module)
           to the same value.
 
-          See <link xlink:href="https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-modules.html"/>.
+          See <https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-modules.html>.
         '';
         default = {};
         type = types.attrsOf (types.submodule ({ name, ... }: {
···
                 internal = true;
                 description = ''
                   Inputs specify how Filebeat locates and processes
-                  input data. Use <xref
-                  linkend="opt-services.filebeat.inputs"/> instead.
+                  input data. Use <xref linkend="opt-services.filebeat.inputs"/> instead.
 
                   See <link xlink:href="https://www.elastic.co/guide/en/beats/filebeat/current/configuration-filebeat-options.html"/>.
                 '';

nixos/modules/services/logging/logrotate.nix

···
         defaultText = ''
           A configuration file automatically generated by NixOS.
         '';
-        description = ''
+        description = lib.mdDoc ''
           Override the configuration file used by MySQL. By default,
-          NixOS generates one automatically from <xref linkend="opt-services.logrotate.settings"/>.
+          NixOS generates one automatically from [](#opt-services.logrotate.settings).
         '';
         example = literalExpression ''
           pkgs.writeText "logrotate.conf" '''
···
       extraConfig = mkOption {
         default = "";
         type = types.lines;
-        description = ''
+        description = lib.mdDoc ''
           Extra contents to append to the logrotate configuration file. Refer to
-          <link xlink:href="https://linux.die.net/man/8/logrotate"/> for details.
+          <https://linux.die.net/man/8/logrotate> for details.
           This setting has been deprecated in favor of
-          <link linkend="opt-services.logrotate.settings">logrotate settings</link>.
+          [logrotate settings](#opt-services.logrotate.settings).
         '';
       };
     };

nixos/modules/services/mail/mailman.nix

···
         bindPasswordFile = mkOption {
           type = types.str;
           example = "/run/secrets/ldap-bind";
-          description = ''
+          description = lib.mdDoc ''
             Path to the file containing the bind password of the servie account
-            defined by <xref linkend="opt-services.mailman.ldap.bindDn" />.
+            defined by [](#opt-services.mailman.ldap.bindDn).
           '';
         };
         superUserGroup = mkOption {

nixos/modules/services/mail/nullmailer.nix

···
       remotesFile = mkOption {
         type = types.nullOr types.str;
         default = null;
-        description = ''
-          Path to the <code>remotes</code> control file. This file contains a
+        description = lib.mdDoc ''
+          Path to the `remotes` control file. This file contains a
           list of remote servers to which to send each message.
 
-          See <code>man 8 nullmailer-send</code> for syntax and available
+          See `man 8 nullmailer-send` for syntax and available
           options.
         '';
       };
···
         remotes = mkOption {
           type = types.nullOr types.str;
           default = null;
-          description = ''
+          description = lib.mdDoc ''
             A list of remote servers to which to send each message. Each line
             contains a remote host name or address followed by an optional
             protocol string, separated by white space.
 
-            See <code>man 8 nullmailer-send</code> for syntax and available
+            See `man 8 nullmailer-send` for syntax and available
             options.
 
             WARNING: This is stored world-readable in the nix store. If you need
             to specify any secret credentials here, consider using the
-            <code>remotesFile</code> option instead.
+            `remotesFile` option instead.
           '';
         };
 

nixos/modules/services/mail/postfixadmin.nix

···
     enable = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable postfixadmin.
 
         Also enables nginx virtual host management.
-        Further nginx configuration can be done by adapting <literal>services.nginx.virtualHosts.&lt;name&gt;</literal>.
-        See <xref linkend="opt-services.nginx.virtualHosts"/> for further information.
+        Further nginx configuration can be done by adapting `services.nginx.virtualHosts.<name>`.
+        See [](#opt-services.nginx.virtualHosts) for further information.
       '';
     };
 

nixos/modules/services/mail/public-inbox.nix

···
     port = mkOption {
       type = with types; nullOr (either str port);
       default = defaultPort;
-      description = ''
+      description = lib.mdDoc ''
         Listening port.
         Beware that public-inbox uses well-known ports number to decide whether to enable TLS or not.
-        Set to null and use <code>systemd.sockets.public-inbox-${proto}d.listenStreams</code>
+        Set to null and use `systemd.sockets.public-inbox-${proto}d.listenStreams`
         if you need a more advanced listening.
       '';
     };
···
         type = with types; nullOr (either str port);
         default = 80;
         example = "/run/public-inbox-httpd.sock";
-        description = ''
+        description = lib.mdDoc ''
           Listening port or systemd's ListenStream= entry
           to be used as a reverse proxy, eg. in nginx:
-          <code>locations."/inbox".proxyPass = "http://unix:''${config.services.public-inbox.http.port}:/inbox";</code>
-          Set to null and use <code>systemd.sockets.public-inbox-httpd.listenStreams</code>
+          `locations."/inbox".proxyPass = "http://unix:''${config.services.public-inbox.http.port}:/inbox";`
+          Set to null and use `systemd.sockets.public-inbox-httpd.listenStreams`
           if you need a more advanced listening.
         '';
       };

nixos/modules/services/mail/roundcube.nix

···
     enable = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable roundcube.
 
         Also enables nginx virtual host management.
-        Further nginx configuration can be done by adapting <literal>services.nginx.virtualHosts.&lt;name&gt;</literal>.
-        See <xref linkend="opt-services.nginx.virtualHosts"/> for further information.
+        Further nginx configuration can be done by adapting `services.nginx.virtualHosts.<name>`.
+        See [](#opt-services.nginx.virtualHosts) for further information.
       '';
     };
 
···
     maxAttachmentSize = mkOption {
       type = types.int;
       default = 18;
-      description = ''
+      description = lib.mdDoc ''
         The maximum attachment size in MB.
 
         Note: Since roundcube only uses 70% of max upload values configured in php
-        30% is added automatically to <xref linkend="opt-services.roundcube.maxAttachmentSize"/>.
+        30% is added automatically to [](#opt-services.roundcube.maxAttachmentSize).
       '';
       apply = configuredMaxAttachmentSize: "${toString (configuredMaxAttachmentSize * 1.3)}M";
     };

nixos/modules/services/mail/sympa.nix

···
       type = str;
       default = "en_US";
       example = "cs";
-      description = ''
+      description = lib.mdDoc ''
         Default Sympa language.
-        See <link xlink:href='https://github.com/sympa-community/sympa/tree/sympa-6.2/po/sympa' />
+        See <https://github.com/sympa-community/sympa/tree/sympa-6.2/po/sympa>
         for available options.
       '';
     };
···
             example = {
               default_max_list_members = 3;
             };
-            description = ''
-              The <filename>robot.conf</filename> configuration file as key value set.
-              See <link xlink:href='https://sympa-community.github.io/gpldoc/man/sympa.conf.5.html' />
+            description = lib.mdDoc ''
+              The {file}`robot.conf` configuration file as key value set.
+              See <https://sympa-community.github.io/gpldoc/man/sympa.conf.5.html>
               for list of configuration parameters.
             '';
           };
···
         description = ''
           The webserver used for the Sympa web interface. Set it to `none` if you want to configure it yourself.
           Further nginx configuration can be done by adapting
-          <option>services.nginx.virtualHosts.<replaceable>name</replaceable></option>.
+          <option>services.nginx.virtualHosts.«name»</option>.
         '';
       };
 
···
           viewlogs_page_size = 50;
         }
       '';
-      description = ''
-        The <filename>sympa.conf</filename> configuration file as key value set.
-        See <link xlink:href='https://sympa-community.github.io/gpldoc/man/sympa.conf.5.html' />
+      description = lib.mdDoc ''
+        The {file}`sympa.conf` configuration file as key value set.
+        See <https://sympa-community.github.io/gpldoc/man/sympa.conf.5.html>
         for list of configuration parameters.
       '';
     };

nixos/modules/services/matrix/appservice-discord.nix

···
             };
           }
         '';
-        description = ''
-          <filename>config.yaml</filename> configuration as a Nix attribute set.
-          </para>
+        description = lib.mdDoc ''
+          {file}`config.yaml` configuration as a Nix attribute set.
 
-          <para>
           Configuration options should match those described in
-          <link xlink:href="https://github.com/Half-Shot/matrix-appservice-discord/blob/master/config/config.sample.yaml">
-          config.sample.yaml</link>.
-          </para>
+          [config.sample.yaml](https://github.com/Half-Shot/matrix-appservice-discord/blob/master/config/config.sample.yaml).
 
-          <para>
-          <option>config.bridge.domain</option> and <option>config.bridge.homeserverUrl</option>
+          {option}`config.bridge.domain` and {option}`config.bridge.homeserverUrl`
           should be set to match the public host name of the Matrix homeserver for webhooks and avatars to work.
-          </para>
 
-          <para>
-          Secret tokens should be specified using <option>environmentFile</option>
+          Secret tokens should be specified using {option}`environmentFile`
           instead of this world-readable attribute set.
         '';
       };

nixos/modules/services/matrix/mautrix-facebook.nix

···
             };
           }
         '';
-        description = ''
-          <filename>config.yaml</filename> configuration as a Nix attribute set.
+        description = lib.mdDoc ''
+          {file}`config.yaml` configuration as a Nix attribute set.
           Configuration options should match those described in
-          <link xlink:href="https://github.com/mautrix/facebook/blob/master/mautrix_facebook/example-config.yaml">
-          example-config.yaml</link>.
-          </para>
+          [example-config.yaml](https://github.com/mautrix/facebook/blob/master/mautrix_facebook/example-config.yaml).
 
-          <para>
-          Secret tokens should be specified using <option>environmentFile</option>
+          Secret tokens should be specified using {option}`environmentFile`
           instead of this world-readable attribute set.
         '';
       };

nixos/modules/services/matrix/mautrix-telegram.nix

···
             };
           }
         '';
-        description = ''
-          <filename>config.yaml</filename> configuration as a Nix attribute set.
+        description = lib.mdDoc ''
+          {file}`config.yaml` configuration as a Nix attribute set.
           Configuration options should match those described in
-          <link xlink:href="https://github.com/tulir/mautrix-telegram/blob/master/example-config.yaml">
-          example-config.yaml</link>.
-          </para>
+          [example-config.yaml](https://github.com/tulir/mautrix-telegram/blob/master/example-config.yaml).
 
-          <para>
-          Secret tokens should be specified using <option>environmentFile</option>
+          Secret tokens should be specified using {option}`environmentFile`
           instead of this world-readable attribute set.
         '';
       };

nixos/modules/services/misc/autorandr.nix

···
     options = {
       fingerprint = mkOption {
         type = types.attrsOf types.str;
-        description = ''
+        description = lib.mdDoc ''
           Output name to EDID mapping.
-          Use <code>autorandr --fingerprint</code> to get current setup values.
+          Use `autorandr --fingerprint` to get current setup values.
         '';
         default = { };
       };
···
         });
         description = ''
           Output scale configuration.
-          </para><para>
+
           Either configure by pixels or a scaling factor. When using pixel method the
           <citerefentry>
             <refentrytitle>xrandr</refentrytitle>
···
           will be used; when using factor method the option
           <parameter class="command">--scale</parameter>
           will be used.
-          </para><para>
+
           This option is a shortcut version of the transform option and they are mutually
           exclusive.
         '';

nixos/modules/services/misc/bees.nix

···
   fsOptions = with types; {
     options.spec = mkOption {
       type = str;
-      description = ''
+      description = lib.mdDoc ''
         Description of how to identify the filesystem to be duplicated by this
         instance of bees. Note that deduplication crosses subvolumes; one must
         not configure multiple instances for subvolumes of the same filesystem
         (or block devices which are part of the same filesystem), but only for
         completely independent btrfs filesystems.
-        </para>
-        <para>
+
         This must be in a format usable by findmnt; that could be a key=value
         pair, or a bare path to a mount point.
         Using bare paths will allow systemd to start the beesd service only
···
     options.hashTableSizeMB = mkOption {
       type = types.addCheck types.int (n: mod n 16 == 0);
       default = 1024; # 1GB; default from upstream beesd script
-      description = ''
+      description = lib.mdDoc ''
         Hash table size in MB; must be a multiple of 16.
-        </para>
-        <para>
+
         A larger ratio of index size to storage size means smaller blocks of
         duplicate content are recognized.
-        </para>
-        <para>
+
         If you have 1TB of data, a 4GB hash table (which is to say, a value of
         4096) will permit 4KB extents (the smallest possible size) to be
         recognized, whereas a value of 1024 -- creating a 1GB hash table --

nixos/modules/services/misc/etcd.nix

···
     };
 
     extraConf = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Etcd extra configuration. See
-        <link xlink:href='https://github.com/coreos/etcd/blob/master/Documentation/op-guide/configuration.md#configuration-flags' />
+        <https://github.com/coreos/etcd/blob/master/Documentation/op-guide/configuration.md#configuration-flags>
       '';
       type = types.attrsOf types.str;
       default = {};

nixos/modules/services/misc/etebase-server.nix

···
         default = {};
         description = ''
           Configuration for <package>etebase-server</package>. Refer to
-          <link xlink:href="https://github.com/etesync/server/blob/master/etebase-server.ini.example" />
-          and <link xlink:href="https://github.com/etesync/server/wiki" />
+          <link xlink:href="https://github.com/etesync/server/blob/master/etebase-server.ini.example"/>
+          and <link xlink:href="https://github.com/etesync/server/wiki"/>
           for details on supported values.
         '';
         example = {

nixos/modules/services/misc/geoipupdate.nix

···
         description = ''
           <productname>geoipupdate</productname> configuration
           options. See
-          <link xlink:href="https://github.com/maxmind/geoipupdate/blob/main/doc/GeoIP.conf.md" />
+          <link xlink:href="https://github.com/maxmind/geoipupdate/blob/main/doc/GeoIP.conf.md"/>
           for a full list of available options.
 
           Settings containing secret data should be set to an
···
 
                 Always handled as a secret whether the value is
                 wrapped in a <literal>{ _secret = ...; }</literal>
-                attrset or not (refer to <xref
-                linkend="opt-services.geoipupdate.settings" /> for
+                attrset or not (refer to <xref linkend="opt-services.geoipupdate.settings"/> for
                 details).
               '';
               apply = x: if isAttrs x then x else { _secret = x; };

nixos/modules/services/misc/klipper.nix

···
       };
 
       firmwares = mkOption {
-        description = "Firmwares klipper should manage";
+        description = lib.mdDoc "Firmwares klipper should manage";
         default = { };
         type = with types; attrsOf
           (submodule {

nixos/modules/services/misc/nix-daemon.nix

···
             <manvolnum>5</manvolnum>
           </citerefentry> for avalaible options.
           The value declared here will be translated directly to the key-value pairs Nix expects.
-          </para>
-          <para>
+
           You can use <command>nix-instantiate --eval --strict '&lt;nixpkgs/nixos&gt;' -A config.nix.settings</command>
           to view the current value. By default it is empty.
-          </para>
-          <para>
+
           Nix configurations defined under <option>nix.*</option> will be translated and applied to this
           option. In addition, configuration specified in <option>nix.extraOptions</option> which will be appended
           verbatim to the resulting config file.

nixos/modules/services/misc/persistent-evdev.nix

···
         Physical devices should already exist in <filename class="devicefile">/dev/input/by-id/</filename>.
         Proxy devices will be automatically given a <literal>uinput-</literal> prefix.
 
-        See the <link xlink:href="https://github.com/aiberia/persistent-evdev#example-usage-with-libvirt">
-        project page</link> for example configuration of virtual devices with libvirt
+        See the <link xlink:href="https://github.com/aiberia/persistent-evdev#example-usage-with-libvirt">project page</link>
+        for example configuration of virtual devices with libvirt
         and remember to add <literal>uinput-*</literal> devices to the qemu
         <literal>cgroup_device_acl</literal> list (see <xref linkend="opt-virtualisation.libvirtd.qemu.verbatimConfig"/>).
       '';

nixos/modules/services/misc/sourcehut/default.nix

···
           network-key = mkOption {
             description = ''
               An absolute file path (which should be outside the Nix-store)
-              to a secret key to encrypt internal messages with. Use <code>srht-keygen network</code> to
+              to a secret key to encrypt internal messages with. Use <literal>srht-keygen network</literal> to
               generate this key. It must be consistent between all services and nodes.
             '';
             type = types.path;
···
           service-key = mkOption {
             description = ''
               An absolute file path (which should be outside the Nix-store)
-              to a key used for encrypting session cookies. Use <code>srht-keygen service</code> to
+              to a key used for encrypting session cookies. Use <literal>srht-keygen service</literal> to
               generate the service key. This must be shared between each node of the same
               service (e.g. git1.sr.ht and git2.sr.ht), but different services may use
               different keys. If you configure all of your services with the same
···
 
               Your PGP key information (DO NOT mix up pub and priv here)
               You must remove the password from your secret key, if present.
-              You can do this with <code>gpg --edit-key [key-id]</code>,
-              then use the <code>passwd</code> command and do not enter a new password.
+              You can do this with <literal>gpg --edit-key [key-id]</literal>,
+              then use the <literal>passwd</literal> command and do not enter a new password.
             '';
           };
           pgp-pubkey = mkOption {
···
               This should be consistent for all *.sr.ht sites,
               as this key will be used to verify signatures
               from other sites in your network.
-              Use the <code>srht-keygen webhook</code> command to generate a key.
+              Use the <literal>srht-keygen webhook</literal> command to generate a key.
             '';
             type = types.path;
             apply = s: "<" + toString s;

nixos/modules/services/misc/sssd.nix

···
       kcm = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to use SSS as a Kerberos Cache Manager (KCM).
           Kerberos will be configured to cache credentials in SSS.
         '';

nixos/modules/services/misc/zoneminder.nix

···
     services.zoneminder = with lib; {
       enable = lib.mkEnableOption ''
         ZoneMinder
-        </para><para>
+
         If you intend to run the database locally, you should set
         `config.services.zoneminder.database.createLocally` to true. Otherwise,
         when set to `false` (the default), you will have to create the database
···
         default = "nginx";
         description = ''
           The webserver to configure for the PHP frontend.
-          </para>
-          <para>
 
           Set it to `none` if you want to configure it yourself. PRs are welcome
           for support for other web servers.

nixos/modules/services/monitoring/cadvisor.nix

···
 
       storageDriverPasswordFile = mkOption {
         type = types.str;
-        description = ''
+        description = lib.mdDoc ''
           File that contains the cadvisor storage driver password.
 
-          <option>storageDriverPasswordFile</option> takes precedence over <option>storageDriverPassword</option>
+          {option}`storageDriverPasswordFile` takes precedence over {option}`storageDriverPassword`
 
-          Warning: when <option>storageDriverPassword</option> is non-empty this defaults to a file in the
-          world-readable Nix store that contains the value of <option>storageDriverPassword</option>.
+          Warning: when {option}`storageDriverPassword` is non-empty this defaults to a file in the
+          world-readable Nix store that contains the value of {option}`storageDriverPassword`.
 
           It's recommended to override this with a path not in the Nix store.
-          Tip: use <link xlink:href='https://nixos.org/nixops/manual/#idm140737318306400'>nixops key management</link>
+          Tip: use [nixops key management](https://nixos.org/nixops/manual/#idm140737318306400)
         '';
       };
 
···
       extraOptions = mkOption {
         type = types.listOf types.str;
         default = [];
-        description = ''
+        description = lib.mdDoc ''
           Additional cadvisor options.
 
-          See <link xlink:href='https://github.com/google/cadvisor/blob/master/docs/runtime_options.md'/> for available options.
+          See <https://github.com/google/cadvisor/blob/master/docs/runtime_options.md> for available options.
         '';
       };
     };

nixos/modules/services/monitoring/grafana-image-renderer.nix

···
       description = ''
         Configuration attributes for <package>grafana-image-renderer</package>.
 
-        See <link xlink:href="https://github.com/grafana/grafana-image-renderer/blob/ce1f81438e5f69c7fd7c73ce08bab624c4c92e25/default.json" />
+        See <link xlink:href="https://github.com/grafana/grafana-image-renderer/blob/ce1f81438e5f69c7fd7c73ce08bab624c4c92e25/default.json"/>
         for supported values.
       '';
     };

nixos/modules/services/monitoring/graphite.nix

···
 
       extraConfig = mkOption {
         default = {};
-        description = ''
+        description = lib.mdDoc ''
           Extra seyren configuration. See
-          <link xlink:href='https://github.com/scobal/seyren#config' />
+          <https://github.com/scobal/seyren#config>
         '';
         type = types.attrsOf types.str;
         example = literalExpression ''

nixos/modules/services/monitoring/metricbeat.nix

···
       };
 
       modules = mkOption {
-        description = ''
+        description = lib.mdDoc ''
           Metricbeat modules are responsible for reading metrics from the various sources.
 
-          This is like <literal>services.metricbeat.settings.metricbeat.modules</literal>,
+          This is like `services.metricbeat.settings.metricbeat.modules`,
           but structured as an attribute set. This has the benefit that multiple
           NixOS modules can contribute settings to a single metricbeat module.
 
-          A module can be specified multiple times by choosing a different <literal>&lt;name></literal>
-          for each, but setting <xref linkend="opt-services.metricbeat.modules._name_.module"/> to the same value.
+          A module can be specified multiple times by choosing a different `<name>`
+          for each, but setting [](#opt-services.metricbeat.modules._name_.module) to the same value.
 
-          See <link xlink:href="https://www.elastic.co/guide/en/beats/metricbeat/current/metricbeat-modules.html"/>.
+          See <https://www.elastic.co/guide/en/beats/metricbeat/current/metricbeat-modules.html>.
         '';
         default = {};
         type = types.attrsOf (types.submodule ({ name, ... }: {

nixos/modules/services/monitoring/munin.nix

···
       enable = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Enable Munin Node agent. Munin node listens on 0.0.0.0 and
           by default accepts connections only from 127.0.0.1 for security reasons.
 
-          See <link xlink:href='http://guide.munin-monitoring.org/en/latest/architecture/index.html' />.
+          See <http://guide.munin-monitoring.org/en/latest/architecture/index.html>.
         '';
       };
 
       extraConfig = mkOption {
         default = "";
         type = types.lines;
-        description = ''
-          <filename>munin-node.conf</filename> extra configuration. See
-          <link xlink:href='http://guide.munin-monitoring.org/en/latest/reference/munin-node.conf.html' />
+        description = lib.mdDoc ''
+          {file}`munin-node.conf` extra configuration. See
+          <http://guide.munin-monitoring.org/en/latest/reference/munin-node.conf.html>
         '';
       };
 
       extraPluginConfig = mkOption {
         default = "";
         type = types.lines;
-        description = ''
-          <filename>plugin-conf.d</filename> extra plugin configuration. See
-          <link xlink:href='http://guide.munin-monitoring.org/en/latest/plugin/use.html' />
+        description = lib.mdDoc ''
+          {file}`plugin-conf.d` extra plugin configuration. See
+          <http://guide.munin-monitoring.org/en/latest/plugin/use.html>
         '';
         example = ''
           [fail2ban_*]
···
       extraGlobalConfig = mkOption {
         default = "";
         type = types.lines;
-        description = ''
-          <filename>munin.conf</filename> extra global configuration.
-          See <link xlink:href='http://guide.munin-monitoring.org/en/latest/reference/munin.conf.html' />.
+        description = lib.mdDoc ''
+          {file}`munin.conf` extra global configuration.
+          See <http://guide.munin-monitoring.org/en/latest/reference/munin.conf.html>.
           Useful to setup notifications, see
-          <link xlink:href='http://guide.munin-monitoring.org/en/latest/tutorial/alert.html' />
+          <http://guide.munin-monitoring.org/en/latest/tutorial/alert.html>
         '';
         example = ''
           contact.email.command mail -s "Munin notification for ''${var:host}" [e-mail]
···
       hosts = mkOption {
         default = "";
         type = types.lines;
-        description = ''
+        description = lib.mdDoc ''
           Definitions of hosts of nodes to collect data from. Needs at least one
           host for cron to succeed. See
-          <link xlink:href='http://guide.munin-monitoring.org/en/latest/reference/munin.conf.html' />
+          <http://guide.munin-monitoring.org/en/latest/reference/munin.conf.html>
         '';
         example = literalExpression ''
           '''

nixos/modules/services/monitoring/nagios.nix

···
 
   options = {
     services.nagios = {
-      enable = mkEnableOption "<link xlink:href='http://www.nagios.org/'>Nagios</link> to monitor your system or network.";
+      enable = mkEnableOption ''<link xlink:href="http://www.nagios.org/">Nagios</link> to monitor your system or network.'';
 
       objectDefs = mkOption {
         description = "

nixos/modules/services/monitoring/netdata.nix

···
         example = literalExpression ''
           [ "/path/to/plugins.d" ]
         '';
-        description = ''
+        description = lib.mdDoc ''
           Extra paths to add to the netdata global "plugins directory"
           option.  Useful for when you want to include your own
           collection scripts.
-          </para><para>
+
           Details about writing a custom netdata plugin are available at:
-          <link xlink:href="https://docs.netdata.cloud/collectors/plugins.d/"/>
-          </para><para>
+          <https://docs.netdata.cloud/collectors/plugins.d/>
+
           Cannot be combined with configText.
         '';
       };

nixos/modules/services/monitoring/parsedmarc.nix

···
         enable = lib.mkOption {
           type = lib.types.bool;
           default = false;
-          description = ''
+          description = lib.mdDoc ''
             Whether Postfix and Dovecot should be set up to receive
             mail locally. parsedmarc will be configured to watch the
             local inbox as the automatically created user specified in
-            <xref linkend="opt-services.parsedmarc.provision.localMail.recipientName" />
+            [](#opt-services.parsedmarc.provision.localMail.recipientName)
           '';
         };
 
···
       geoIp = lib.mkOption {
         type = lib.types.bool;
         default = true;
-        description = ''
-          Whether to enable and configure the <link
-          linkend="opt-services.geoipupdate.enable">geoipupdate</link>
+        description = lib.mdDoc ''
+          Whether to enable and configure the [geoipupdate](#opt-services.geoipupdate.enable)
           service to automatically fetch GeoIP databases. Not crucial,
           but recommended for full functionality.
 
-          To finish the setup, you need to manually set the <xref
-          linkend="opt-services.geoipupdate.settings.AccountID" /> and
-          <xref linkend="opt-services.geoipupdate.settings.LicenseKey" />
+          To finish the setup, you need to manually set the [](#opt-services.geoipupdate.settings.AccountID) and
+          [](#opt-services.geoipupdate.settings.LicenseKey)
           options.
         '';
       };
···
             config.${opt.provision.elasticsearch} && config.${options.services.grafana.enable}
           '';
           apply = x: x && cfg.provision.elasticsearch;
-          description = ''
+          description = lib.mdDoc ''
             Whether the automatically provisioned Elasticsearch
             instance should be added as a grafana datasource. Has no
             effect unless
-            <xref linkend="opt-services.parsedmarc.provision.elasticsearch" />
+            [](#opt-services.parsedmarc.provision.elasticsearch)
             is also enabled.
           '';
         };
···
             password = lib.mkOption {
               type = with lib.types; nullOr (either path (attrsOf path));
               default = null;
-              description = ''
+              description = lib.mdDoc ''
                 The IMAP server password.
 
                 Always handled as a secret whether the value is
-                wrapped in a <literal>{ _secret = ...; }</literal>
-                attrset or not (refer to <xref
-                linkend="opt-services.parsedmarc.settings" /> for
+                wrapped in a `{ _secret = ...; }`
+                attrset or not (refer to [](#opt-services.parsedmarc.settings) for
                 details).
               '';
               apply = x: if isAttrs x || x == null then x else { _secret = x; };
···
             password = lib.mkOption {
               type = with lib.types; nullOr (either path (attrsOf path));
               default = null;
-              description = ''
+              description = lib.mdDoc ''
                 The SMTP server password.
 
                 Always handled as a secret whether the value is
-                wrapped in a <literal>{ _secret = ...; }</literal>
-                attrset or not (refer to <xref
-                linkend="opt-services.parsedmarc.settings" /> for
+                wrapped in a `{ _secret = ...; }`
+                attrset or not (refer to [](#opt-services.parsedmarc.settings) for
                 details).
               '';
               apply = x: if isAttrs x || x == null then x else { _secret = x; };
···
             password = lib.mkOption {
               type = with lib.types; nullOr (either path (attrsOf path));
               default = null;
-              description = ''
+              description = lib.mdDoc ''
                 The password to use when connecting to Elasticsearch,
                 if required.
 
                 Always handled as a secret whether the value is
-                wrapped in a <literal>{ _secret = ...; }</literal>
-                attrset or not (refer to <xref
-                linkend="opt-services.parsedmarc.settings" /> for
+                wrapped in a `{ _secret = ...; }`
+                attrset or not (refer to [](#opt-services.parsedmarc.settings) for
                 details).
               '';
               apply = x: if isAttrs x || x == null then x else { _secret = x; };

nixos/modules/services/monitoring/prometheus/default.nix

···
       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> for more detail.
+        See <link xlink:href="https://prometheus.io/docs/prometheus/latest/configuration/configuration/#gce_sd_config">the relevant Prometheus configuration docs</link>
+        for more detail.
       '';
 
       hetzner_sd_configs = mkOpt (types.listOf promTypes.hetzner_sd_config) ''
···
       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: <link xlink:href="https://cloud.google.com/compute/docs/reference/latest/instances/list"/>.
       '';
 
       refresh_interval = mkDefOpt types.str "60s" ''
···
         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" />
+        <link xlink:href="https://cloud.google.com/vpc/docs/add-remove-network-tags"/>
       '';
     };
   };
···
 
     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" />
+      <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.
     '';
 
     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" />
+      <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.
     '';
   };

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

···
         work with this exporter:
         <programlisting>
         {
-          <xref linkend="opt-services.prometheus.exporters.dovecot.enable" /> = true;
-          <xref linkend="opt-services.prometheus.exporters.dovecot.socketPath" /> = "/var/run/dovecot2/old-stats";
-          <xref linkend="opt-services.dovecot2.mailPlugins.globally.enable" /> = [ "old_stats" ];
-          <xref linkend="opt-services.dovecot2.extraConfig" /> = '''
+          <xref linkend="opt-services.prometheus.exporters.dovecot.enable"/> = true;
+          <xref linkend="opt-services.prometheus.exporters.dovecot.socketPath"/> = "/var/run/dovecot2/old-stats";
+          <xref linkend="opt-services.dovecot2.mailPlugins.globally.enable"/> = [ "old_stats" ];
+          <xref linkend="opt-services.dovecot2.extraConfig"/> = '''
             service old-stats {
               unix_listener old-stats {
                 user = dovecot-exporter

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

···
         All settings expressed as an Nix attrset.
 
         Check the official documentation for the corresponding YAML
-        settings that can all be used here: <link xlink:href="https://github.com/ncabatoff/process-exporter" />
+        settings that can all be used here: <link xlink:href="https://github.com/ncabatoff/process-exporter"/>
       '';
     };
   };

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

···
         All settings expressed as an Nix attrset.
 
         Check the official documentation for the corresponding YAML
-        settings that can all be used here: <link xlink:href="https://github.com/adhocteam/script_exporter#sample-configuration" />
+        settings that can all be used here: <link xlink:href="https://github.com/adhocteam/script_exporter#sample-configuration"/>
       '';
     };
   };

nixos/modules/services/networking/biboumi.nix

···
           };
           options.password = mkOption {
             type = with types; nullOr str;
-            description = ''
+            description = lib.mdDoc ''
               The password used to authenticate the XMPP component to your XMPP server.
               This password must be configured in the XMPP server,
               associated with the external component on
-              <link linkend="opt-services.biboumi.settings.hostname">hostname</link>.
+              [hostname](#opt-services.biboumi.settings.hostname).
 
-              Set it to null and use <link linkend="opt-services.biboumi.credentialsFile">credentialsFile</link>
+              Set it to null and use [credentialsFile](#opt-services.biboumi.credentialsFile)
               if you do not want this password to go into the Nix store.
             '';
           };
···
 
       credentialsFile = mkOption {
         type = types.path;
-        description = ''
+        description = lib.mdDoc ''
           Path to a configuration file to be merged with the settings.
           Beware not to surround "=" with spaces when setting biboumi's options in this file.
           Useful to merge a file which is better kept out of the Nix store
           because it contains sensible data like
-          <link linkend="opt-services.biboumi.settings.password">password</link>.
+          [password](#opt-services.biboumi.settings.password).
         '';
         default = "/dev/null";
         example = "/run/keys/biboumi.cfg";

nixos/modules/services/networking/bird-lg.nix

···
         extraArgs = mkOption {
           type = types.lines;
           default = "";
-          description = "
-            Extra parameters documented <link xlink:href=\"https://github.com/xddxdd/bird-lg-go#frontend\">here</link>.
-          ";
+          description = lib.mdDoc ''
+            Extra parameters documented [here](https://github.com/xddxdd/bird-lg-go#frontend).
+          '';
         };
       };
 
···
         extraArgs = mkOption {
           type = types.lines;
           default = "";
-          description = "
-            Extra parameters documented <link xlink:href=\"https://github.com/xddxdd/bird-lg-go#proxy\">here</link>.
-          ";
+          description = lib.mdDoc ''
+            Extra parameters documented [here](https://github.com/xddxdd/bird-lg-go#proxy).
+          '';
         };
       };
     };

nixos/modules/services/networking/bird.nix

···
       enable = mkEnableOption "BIRD Internet Routing Daemon";
       config = mkOption {
         type = types.lines;
-        description = ''
+        description = lib.mdDoc ''
           BIRD Internet Routing Daemon configuration file.
-          <link xlink:href='http://bird.network.cz/'/>
+          <http://bird.network.cz/>
         '';
       };
       checkConfig = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Whether the config should be checked at build time.
           When the config can't be checked during build time, for example when it includes
-          other files, either disable this option or use <code>preCheckConfig</code> to create
+          other files, either disable this option or use `preCheckConfig` to create
           the included files before checking.
         '';
       };
···
         example = ''
           echo "cost 100;" > include.conf
         '';
-        description = ''
+        description = lib.mdDoc ''
           Commands to execute before the config file check. The file to be checked will be
-          available as <code>bird2.conf</code> in the current directory.
+          available as `bird2.conf` in the current directory.
 
           Files created with this option will not be available at service runtime, only during
           build time checking.

nixos/modules/services/networking/coredns.nix

···
         }
       '';
       type = types.lines;
-      description = "Verbatim Corefile to use. See <link xlink:href=\"https://coredns.io/manual/toc/#configuration\"/> for details.";
+      description = lib.mdDoc ''
+        Verbatim Corefile to use.
+        See <https://coredns.io/manual/toc/#configuration> for details.
+      '';
     };
 
     package = mkOption {

nixos/modules/services/networking/ghostunnel.nix

···
           description = ''
             Path to keystore (combined PEM with cert/key, or PKCS12 keystore).
 
-            NB: storepass is not supported because it would expose credentials via <code>/proc/*/cmdline</code>.
+            NB: storepass is not supported because it would expose credentials via <literal>/proc/*/cmdline</literal>.
 
-            Specify this or <code>cert</code> and <code>key</code>.
+            Specify this or <literal>cert</literal> and <literal>key</literal>.
           '';
           type = types.nullOr types.str;
           default = null;
         };
 
         cert = mkOption {
-          description = ''
+          description = lib.mdDoc ''
             Path to certificate (PEM with certificate chain).
 
-            Not required if <code>keystore</code> is set.
+            Not required if `keystore` is set.
           '';
           type = types.nullOr types.str;
           default = null;
         };
 
         key = mkOption {
-          description = ''
+          description = lib.mdDoc ''
             Path to certificate private key (PEM with private key).
 
-            Not required if <code>keystore</code> is set.
+            Not required if `keystore` is set.
           '';
           type = types.nullOr types.str;
           default = null;
         };
 
         cacert = mkOption {
-          description = ''
-            Path to CA bundle file (PEM/X509). Uses system trust store if <code>null</code>.
+          description = lib.mdDoc ''
+            Path to CA bundle file (PEM/X509). Uses system trust store if `null`.
           '';
           type = types.nullOr types.str;
         };
···
         };
 
         extraArguments = mkOption {
-          description = "Extra arguments to pass to <code>ghostunnel server</code>";
+          description = lib.mdDoc "Extra arguments to pass to `ghostunnel server`";
           type = types.separatedString " ";
           default = "";
         };

nixos/modules/services/networking/hans.nix

···
     services.hans = {
       clients = mkOption {
         default = {};
-        description = ''
+        description = lib.mdDoc ''
           Each attribute of this option defines a systemd service that
           runs hans. Many or none may be defined.
           The name of each service is
-          <literal>hans-<replaceable>name</replaceable></literal>
-          where <replaceable>name</replaceable> is the name of the
+          `hans-«name»`
+          where «name» is the name of the
           corresponding attribute name.
         '';
         example = literalExpression ''

nixos/modules/services/networking/iodine.nix

···
     services.iodine = {
       clients = mkOption {
         default = {};
-        description = ''
+        description = lib.mdDoc ''
           Each attribute of this option defines a systemd service that
           runs iodine. Many or none may be defined.
           The name of each service is
-          <literal>iodine-<replaceable>name</replaceable></literal>
-          where <replaceable>name</replaceable> is the name of the
+          `iodine-«name»`
+          where «name» is the name of the
           corresponding attribute name.
         '';
         example = literalExpression ''

nixos/modules/services/networking/kea.nix

···
           configFile = mkOption {
             type = nullOr path;
             default = null;
-            description = ''
-              Kea Control Agent configuration as a path, see <link xlink:href="https://kea.readthedocs.io/en/kea-${package.version}/arm/agent.html"/>.
+            description = lib.mdDoc ''
+              Kea Control Agent configuration as a path, see <https://kea.readthedocs.io/en/kea-${package.version}/arm/agent.html>.
 
-              Takes preference over <link linkend="opt-services.kea.ctrl-agent.settings">settings</link>.
-              Most users should prefer using <link linkend="opt-services.kea.ctrl-agent.settings">settings</link> instead.
+              Takes preference over [settings](#opt-services.kea.ctrl-agent.settings).
+              Most users should prefer using [settings](#opt-services.kea.ctrl-agent.settings) instead.
             '';
           };
 
···
           configFile = mkOption {
             type = nullOr path;
             default = null;
-            description = ''
-              Kea DHCP4 configuration as a path, see <link xlink:href="https://kea.readthedocs.io/en/kea-${package.version}/arm/dhcp4-srv.html"/>.
+            description = lib.mdDoc ''
+              Kea DHCP4 configuration as a path, see <https://kea.readthedocs.io/en/kea-${package.version}/arm/dhcp4-srv.html>.
 
-              Takes preference over <link linkend="opt-services.kea.dhcp4.settings">settings</link>.
-              Most users should prefer using <link linkend="opt-services.kea.dhcp4.settings">settings</link> instead.
+              Takes preference over [settings](#opt-services.kea.dhcp4.settings).
+              Most users should prefer using [settings](#opt-services.kea.dhcp4.settings) instead.
             '';
           };
 
···
           configFile = mkOption {
             type = nullOr path;
             default = null;
-            description = ''
-              Kea DHCP6 configuration as a path, see <link xlink:href="https://kea.readthedocs.io/en/kea-${package.version}/arm/dhcp6-srv.html"/>.
+            description = lib.mdDoc ''
+              Kea DHCP6 configuration as a path, see <https://kea.readthedocs.io/en/kea-${package.version}/arm/dhcp6-srv.html>.
 
-              Takes preference over <link linkend="opt-services.kea.dhcp6.settings">settings</link>.
-              Most users should prefer using <link linkend="opt-services.kea.dhcp6.settings">settings</link> instead.
+              Takes preference over [settings](#opt-services.kea.dhcp6.settings).
+              Most users should prefer using [settings](#opt-services.kea.dhcp6.settings) instead.
             '';
           };
 
···
           configFile = mkOption {
             type = nullOr path;
             default = null;
-            description = ''
-              Kea DHCP-DDNS configuration as a path, see <link xlink:href="https://kea.readthedocs.io/en/kea-${package.version}/arm/ddns.html"/>.
+            description = lib.mdDoc ''
+              Kea DHCP-DDNS configuration as a path, see <https://kea.readthedocs.io/en/kea-${package.version}/arm/ddns.html>.
 
-              Takes preference over <link linkend="opt-services.kea.dhcp-ddns.settings">settings</link>.
-              Most users should prefer using <link linkend="opt-services.kea.dhcp-ddns.settings">settings</link> instead.
+              Takes preference over [settings](#opt-services.kea.dhcp-ddns.settings).
+              Most users should prefer using [settings](#opt-services.kea.dhcp-ddns.settings) instead.
             '';
           };
 

nixos/modules/services/networking/ncdns.nix

···
             certstore.nssdbdir = "../../home/alice/.pki/nssdb";
           }
         '';
-        description = ''
+        description = lib.mdDoc ''
           ncdns settings. Use this option to configure ncds
           settings not exposed in a NixOS option or to bypass one.
-          See the example ncdns.conf file at <link xlink:href="https://github.com/namecoin/ncdns/blob/master/_doc/ncdns.conf.example"/>
+          See the example ncdns.conf file at <https://github.com/namecoin/ncdns/blob/master/_doc/ncdns.conf.example>
           for the available options.
         '';
       };

nixos/modules/services/networking/networkmanager.nix

···
         default = "default";
         description = ''
           Set the DNS (<literal>resolv.conf</literal>) processing mode.
-          </para>
-          <para>
+
           A description of these modes can be found in the main section of
           <link xlink:href="https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html">
             https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html
···
       enableStrongSwan = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Enable the StrongSwan plugin.
-          </para><para>
+
           If you enable this option the
-          <literal>networkmanager_strongswan</literal> plugin will be added to
-          the <option>networking.networkmanager.plugins</option> option
+          `networkmanager_strongswan` plugin will be added to
+          the {option}`networking.networkmanager.plugins` option
           so you don't need to to that yourself.
         '';
       };

nixos/modules/services/networking/nntp-proxy.nix

···
             passwordHash = mkOption {
               type = types.str;
               example = "$6$GtzE7FrpE$wwuVgFYU.TZH4Rz.Snjxk9XGua89IeVwPQ/fEUD8eujr40q5Y021yhn0aNcsQ2Ifw.BLclyzvzgegopgKcneL0";
-              description = ''
+              description = lib.mdDoc ''
                 SHA-512 password hash (can be generated by
-                <code>mkpasswd -m sha-512 &lt;password&gt;</code>)
+                `mkpasswd -m sha-512 <password>`)
               '';
             };
 

nixos/modules/services/networking/nsd.nix

···
       requestXFR = mkOption {
         type = types.listOf types.str;
         default = [];
-        description = ''
-          Format: <code>[AXFR|UDP] &lt;ip-address&gt; &lt;key-name | NOKEY&gt;</code>
+        description = lib.mdDoc ''
+          Format: `[AXFR|UDP] <ip-address> <key-name | NOKEY>`
         '';
       };
 

nixos/modules/services/networking/ntp/ntpd.nix

···
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to synchronise your machine's time using ntpd, as a peer in
           the NTP network.
-          </para>
-          <para>
-          Disables <literal>systemd.timesyncd</literal> if enabled.
+
+          Disables `systemd.timesyncd` if enabled.
         '';
       };
 
       restrictDefault = mkOption {
         type = types.listOf types.str;
-        description = ''
+        description = lib.mdDoc ''
           The restriction flags to be set by default.
-          </para>
-          <para>
+
           The default flags prevent external hosts from using ntpd as a DDoS
           reflector, setting system time, and querying OS/ntpd version. As
           recommended in section 6.5.1.1.3, answer "No" of
···
 
       restrictSource = mkOption {
         type = types.listOf types.str;
-        description = ''
+        description = lib.mdDoc ''
           The restriction flags to be set on source.
-          </para>
-          <para>
+
           The default flags allow peers to be added by ntpd from configured
           pool(s), but not by other means.
         '';

nixos/modules/services/networking/openconnect.nix

···
       # set an authentication cookie, because they have to be requested
       # for every new connection and would only work once.
       passwordFile = mkOption {
-        description = ''
+        description = lib.mdDoc ''
           File containing the password to authenticate with. This
-          is passed to <code>openconnect</code> via the
-          <code>--passwd-on-stdin</code> option.
+          is passed to `openconnect` via the
+          `--passwd-on-stdin` option.
         '';
         default = null;
         example = "/var/lib/secrets/openconnect-passwd";
···
       };
 
       extraOptions = mkOption {
-        description = ''
+        description = lib.mdDoc ''
           Extra config to be appended to the interface config. It should
           contain long-format options as would be accepted on the command
-          line by <code>openconnect</code>
+          line by `openconnect`
           (see https://www.infradead.org/openconnect/manual.html).
-          Non-key-value options like <code>deflate</code> can be used by
-          declaring them as booleans, i. e. <code>deflate = true;</code>.
+          Non-key-value options like `deflate` can be used by
+          declaring them as booleans, i. e. `deflate = true;`.
         '';
         default = { };
         example = {

nixos/modules/services/networking/openvpn.nix

···
         }
       '';
 
-      description = ''
+      description = lib.mdDoc ''
         Each attribute of this option defines a systemd service that
         runs an OpenVPN instance.  These can be OpenVPN servers or
         clients.  The name of each systemd service is
-        <literal>openvpn-<replaceable>name</replaceable>.service</literal>,
-        where <replaceable>name</replaceable> is the corresponding
+        `openvpn-«name».service`,
+        where «name» is the corresponding
         attribute name.
       '';
 

nixos/modules/services/networking/pleroma.nix

···
 
       configs = mkOption {
         type = with types; listOf str;
-        description = ''
+        description = lib.mdDoc ''
           Pleroma public configuration.
 
           This list gets appended from left to
···
           configuration imperatively, meaning you can override a
           setting by appending a new str to this NixOS option list.
 
-          <emphasis>DO NOT STORE ANY PLEROMA SECRET
-          HERE</emphasis>, use
-          <link linkend="opt-services.pleroma.secretConfigFile">services.pleroma.secretConfigFile</link>
+          *DO NOT STORE ANY PLEROMA SECRET
+          HERE*, use
+          [services.pleroma.secretConfigFile](#opt-services.pleroma.secretConfigFile)
           instead.
 
           This setting is going to be stored in a file part of

nixos/modules/services/networking/seafile.nix

···
       type = types.lines;
       description = ''
         Extra config to append to `seahub_settings.py` file.
-        Refer to <link xlink:href="https://manual.seafile.com/config/seahub_settings_py/" />
+        Refer to <link xlink:href="https://manual.seafile.com/config/seahub_settings_py/"/>
         for all available options.
       '';
     };

nixos/modules/services/networking/ssh/sshd.nix

···
       authorizedKeysFiles = mkOption {
         type = types.listOf types.str;
         default = [];
-        description = ''
+        description = lib.mdDoc ''
           Specify the rules for which files to read on the host.
 
           This is an advanced option. If you're looking to configure user
-          keys, you can generally use <xref linkend="opt-users.users._name_.openssh.authorizedKeys.keys"/>
-          or <xref linkend="opt-users.users._name_.openssh.authorizedKeys.keyFiles"/>.
+          keys, you can generally use [](#opt-users.users._name_.openssh.authorizedKeys.keys)
+          or [](#opt-users.users._name_.openssh.authorizedKeys.keyFiles).
 
           These are paths relative to the host root file system or home
           directories and they are subject to certain token expansion rules.
···
           "[e-mail]"
           "diffie-hellman-group-exchange-sha256"
         ];
-        description = ''
+        description = lib.mdDoc ''
           Allowed key exchange algorithms
-          </para>
-          <para>
+
           Uses the lower bound recommended in both
-          <link xlink:href="https://stribika.github.io/2015/01/04/secure-secure-shell.html" />
+          <https://stribika.github.io/2015/01/04/secure-secure-shell.html>
           and
-          <link xlink:href="https://infosec.mozilla.org/guidelines/openssh#modern-openssh-67" />
+          <https://infosec.mozilla.org/guidelines/openssh#modern-openssh-67>
         '';
       };
 
···
           "aes192-ctr"
           "aes128-ctr"
         ];
-        description = ''
+        description = lib.mdDoc ''
           Allowed ciphers
-          </para>
-          <para>
+
           Defaults to recommended settings from both
-          <link xlink:href="https://stribika.github.io/2015/01/04/secure-secure-shell.html" />
+          <https://stribika.github.io/2015/01/04/secure-secure-shell.html>
           and
-          <link xlink:href="https://infosec.mozilla.org/guidelines/openssh#modern-openssh-67" />
+          <https://infosec.mozilla.org/guidelines/openssh#modern-openssh-67>
         '';
       };
 
···
           "hmac-sha2-256"
           "[e-mail]"
         ];
-        description = ''
+        description = lib.mdDoc ''
           Allowed MACs
-          </para>
-          <para>
+
           Defaults to recommended settings from both
-          <link xlink:href="https://stribika.github.io/2015/01/04/secure-secure-shell.html" />
+          <https://stribika.github.io/2015/01/04/secure-secure-shell.html>
           and
-          <link xlink:href="https://infosec.mozilla.org/guidelines/openssh#modern-openssh-67" />
+          <https://infosec.mozilla.org/guidelines/openssh#modern-openssh-67>
         '';
       };
 

nixos/modules/services/networking/strongswan-swanctl/param-constructors.nix

···
     if strongswanDefault == null
     then description
     else description + ''
-      </para><para>
+
+
       StrongSwan default: <literal><![CDATA[${builtins.toJSON strongswanDefault}]]></literal>
     '';
 

nixos/modules/services/networking/strongswan-swanctl/swanctl-params.nix

···
     file = mkOptionalStrParam ''
       Absolute path to the certificate to load. Passed as-is to the daemon, so
       it must be readable by it.
-      </para><para>
+
       Configure either this or <option>handle</option>, but not both, in one section.
     '';
 
     handle = mkOptionalHexParam ''
       Hex-encoded CKA_ID or handle of the certificate on a token or TPM,
       respectively.
-      </para><para>
+
       Configure either this or <option>file</option>, but not both, in one section.
     '';
 
···
     cacert = mkOptionalStrParam ''
       The certificates may use a relative path from the swanctl
       <literal>x509ca</literal> directory or an absolute path.
-      </para><para>
+
       Configure one of <option>cacert</option>,
       <option>file</option>, or
       <option>handle</option> per section.
···
     local_addrs	= mkCommaSepListParam [] ''
       Local address(es) to use for IKE communication. Takes
       single IPv4/IPv6 addresses, DNS names, CIDR subnets or IP address ranges.
-      </para><para>
+
       As initiator, the first non-range/non-subnet is used to initiate the
       connection from. As responder, the local destination address must match at
       least to one of the specified addresses, subnets or ranges.
-      </para><para>
+
       If FQDNs are assigned they are resolved every time a configuration lookup
       is done. If DNS resolution times out, the lookup is delayed for that time.
     '';
···
     remote_addrs = mkCommaSepListParam [] ''
       Remote address(es) to use for IKE communication. Takes
       single IPv4/IPv6 addresses, DNS names, CIDR subnets or IP address ranges.
-      </para><para>
+
       As initiator, the first non-range/non-subnet is used to initiate the
       connection to. As responder, the initiator source address must match at
       least to one of the specified addresses, subnets or ranges.
-      </para><para>
+
       If FQDNs are assigned they are resolved every time a configuration lookup
       is done. If DNS resolution times out, the lookup is delayed for that time.
       To initiate a connection, at least one specific address or DNS name must
···
       backend is used, which is usually <literal>500</literal>. If port
       <literal>500</literal> is used, automatic IKE port floating to port
       <literal>4500</literal> is used to work around NAT issues.
-      </para><para>
+
       Using a non-default local IKE port requires support from the socket
       backend in use (socket-dynamic).
     '';
···
       for IKE an encryption algorithm, an integrity algorithm, a pseudo random
       function and a Diffie-Hellman group. For AEAD algorithms, instead of
       encryption and integrity algorithms, a combined algorithm is used.
-      </para><para>
+
       In IKEv2, multiple algorithms of the same kind can be specified in a
       single proposal, from which one gets selected. In IKEv1, only one
       algorithm per kind is allowed per proposal, more algorithms get implicitly
       stripped. Use multiple proposals to offer different algorithms
       combinations in IKEv1.
-      </para><para>
+
       Algorithm keywords get separated using dashes. Multiple proposals may be
       specified in a list. The special value <literal>default</literal> forms a
       default proposal of supported algorithms considered safe, and is usually a
···
       If the default of yes is used, Mode Config works in pull mode, where the
       initiator actively requests a virtual IP. With no, push mode is used,
       where the responder pushes down a virtual IP to the initiating peer.
-      </para><para>
+
       Push mode is currently supported for IKEv1, but not in IKEv2. It is used
       by a few implementations only, pull mode is recommended.
     '';
···
       To enforce UDP encapsulation of ESP packets, the IKE daemon can fake the
       NAT detection payloads. This makes the peer believe that NAT takes place
       on the path, forcing it to encapsulate ESP packets in UDP.
-      </para><para>
+
       Usually this is not required, but it can help to work around connectivity
       issues with too restrictive intermediary firewalls.
     '';
···
       Enables MOBIKE on IKEv2 connections. MOBIKE is enabled by default on IKEv2
       connections, and allows mobility of clients and multi-homing on servers by
       migrating active IPsec tunnels.
-      </para><para>
+
       Usually keeping MOBIKE enabled is unproblematic, as it is not used if the
       peer does not indicate support for it. However, due to the design of
       MOBIKE, IKEv2 always floats to port 4500 starting from the second
···
       <listitem><para>Finally, setting the option to <literal>no</literal> will disable announcing
       support for this feature.</para></listitem>
       </itemizedlist>
-      </para><para>
+
       Note that fragmented IKE messages sent by a peer are always processed
       irrespective of the value of this option (even when set to no).
     '';
···
     unique = mkEnumParam ["no" "never" "keep" "replace"] "no" ''
       Connection uniqueness policy to enforce. To avoid multiple connections
       from the same user, a uniqueness policy can be enforced.
-      </para><para>
+
       <itemizedlist>
       <listitem><para>
       The value <literal>never</literal> does never enforce such a policy, even
···
       To compare connections for uniqueness, the remote IKE identity is used. If
       EAP or XAuth authentication is involved, the EAP-Identity or XAuth
       username is used to enforce the uniqueness policy instead.
-      </para><para>
+
       On initiators this setting specifies whether an INITIAL_CONTACT notify is
       sent during IKE_AUTH if no existing connection is found with the remote
       peer (determined by the identities of the first authentication
···
       possible to actively reauthenticate as responder. The IKEv2
       reauthentication lifetime negotiation can instruct the client to perform
       reauthentication.
-      </para><para>
+
       Reauthentication is disabled by default. Enabling it usually may lead to
       small connection interruptions, as strongSwan uses a break-before-make
       policy with IKEv2 to avoid any conflicts with associated tunnel resources.
···
       IKE rekeying refreshes key material using a Diffie-Hellman exchange, but
       does not re-check associated credentials. It is supported in IKEv2 only,
       IKEv1 performs a reauthentication procedure instead.
-      </para><para>
+
       With the default value IKE rekeying is scheduled every 4 hours, minus the
       configured rand_time. If a reauth_time is configured, rekey_time defaults
       to zero, disabling rekeying; explicitly set both to enforce rekeying and
···
       perpetually, a maximum hard lifetime may be specified. If the IKE_SA fails
       to rekey or reauthenticate within the specified time, the IKE_SA gets
       closed.
-      </para><para>
+
       In contrast to CHILD_SA rekeying, over_time is relative in time to the
       rekey_time and reauth_time values, as it applies to both.
-      </para><para>
+
       The default is 10% of the longer of <option>rekey_time</option> and
       <option>reauth_time</option>.
     '';
···
       rekey/reauth times. To avoid having both peers initiating the rekey/reauth
       procedure simultaneously, a random time gets subtracted from the
       rekey/reauth times.
-      </para><para>
+
       The default is equal to the configured <option>over_time</option>.
     '';
 
···
         List of certificate candidates to use for
         authentication. The certificates may use a relative path from the
         swanctl <literal>x509</literal> directory or an absolute path.
-        </para><para>
+
         The certificate used for authentication is selected based on the
         received certificate request payloads. If no appropriate CA can be
         located, the first certificate is used.
···
         List of raw public key candidates to use for
         authentication. The public keys may use a relative path from the swanctl
         <literal>pubkey</literal> directory or an absolute path.
-        </para><para>
+
         Even though multiple local public keys could be defined in principle,
         only the first public key in the list is used for authentication.
       '';
···
         authentication. This identity may differ from the IKE identity,
         especially when EAP authentication is delegated from the IKE responder
         to an AAA backend.
-        </para><para>
+
         For EAP-(T)TLS, this defines the identity for which the server must
         provide a certificate in the TLS exchange.
       '';
···
       defines the rules how authentication is performed for the local
       peer. Multiple rounds may be defined to use IKEv2 RFC 4739 Multiple
       Authentication or IKEv1 XAuth.
-      </para><para>
+
       Each round is defined in a section having <literal>local</literal> as
       prefix, and an optional unique suffix. To define a single authentication
       round, the suffix may be omitted.
···
         Authentication to expect from remote. See the <option>local</option>
         section's <option>auth</option> keyword description about the details of
         supported mechanisms.
-        </para><para>
+
         Since 5.4.0, to require a trustchain public key strength for the remote
         side, specify the key type followed by the minimum strength in bits (for
         example <literal>ecdsa-384</literal> or
···
         <literal>pubkey</literal> or <literal>rsa</literal> constraints are
         configured RSASSA-PSS signatures will only be accepted if enabled in
         <literal>strongswan.conf</literal>(5).
-        </para><para>
+
         To specify trust chain constraints for EAP-(T)TLS, append a colon to the
         EAP method, followed by the key type/size and hash algorithm as
         discussed above (e.g. <literal>eap-tls:ecdsa-384-sha384</literal>).
···
       defines the constraints how the peers must authenticate to use this
       connection. Multiple rounds may be defined to use IKEv2 RFC 4739 Multiple
       Authentication or IKEv1 XAuth.
-      </para><para>
+
       Each round is defined in a section having <literal>remote</literal> as
       prefix, and an optional unique suffix. To define a single authentication
       round, the suffix may be omitted.
···
         Diffie-Hellman group. If a DH group is specified, CHILD_SA/Quick Mode
         rekeying and initial negotiation uses a separate Diffie-Hellman exchange
         using the specified group (refer to esp_proposals for details).
-        </para><para>
+
         In IKEv2, multiple algorithms of the same kind can be specified in a
         single proposal, from which one gets selected. In IKEv1, only one
         algorithm per kind is allowed per proposal, more algorithms get
         implicitly stripped. Use multiple proposals to offer different algorithms
         combinations in IKEv1.
-        </para><para>
+
         Algorithm keywords get separated using dashes. Multiple proposals may be
         specified in a list. The special value <literal>default</literal> forms
         a default proposal of supported algorithms considered safe, and is
···
         an optional Extended Sequence Number Mode indicator. For AEAD proposals,
         a combined mode algorithm is used instead of the separate
         encryption/integrity algorithms.
-        </para><para>
+
         If a DH group is specified, CHILD_SA/Quick Mode rekeying and initial
         negotiation use a separate Diffie-Hellman exchange using the specified
         group. However, for IKEv2, the keys of the CHILD_SA created implicitly
···
         rekeyed or is created with a separate CREATE_CHILD_SA exchange. A
         proposal mismatch might, therefore, not immediately be noticed when the
         SA is established, but may later cause rekeying to fail.
-        </para><para>
+
         Extended Sequence Number support may be indicated with the
         <literal>esn</literal> and <literal>noesn</literal> values, both may be
         included to indicate support for both modes. If omitted,
         <literal>noesn</literal> is assumed.
-        </para><para>
+
         In IKEv2, multiple algorithms of the same kind can be specified in a
         single proposal, from which one gets selected. In IKEv1, only one
         algorithm per kind is allowed per proposal, more algorithms get
         implicitly stripped. Use multiple proposals to offer different algorithms
         combinations in IKEv1.
-        </para><para>
+
         Algorithm keywords get separated using dashes. Multiple proposals may be
         specified as a list. The special value <literal>default</literal> forms
         a default proposal of supported algorithms considered safe, and is
···
         selector. The special value <literal>dynamic</literal> may be used
         instead of a subnet definition, which gets replaced by the tunnel outer
         address or the virtual IP, if negotiated. This is the default.
-        </para><para>
+
         A protocol/port selector is surrounded by opening and closing square
         brackets. Between these brackets, a numeric or getservent(3) protocol
         name may be specified. After the optional protocol restriction, an
···
         special value <literal>opaque</literal> for RFC 4301 OPAQUE
         selectors. Port ranges may be specified as well, none of the kernel
         backends currently support port ranges, though.
-        </para><para>
+
         When IKEv1 is used only the first selector is interpreted, except if the
         Cisco Unity extension plugin is used. This is due to a limitation of the
         IKEv1 protocol, which only allows a single pair of selectors per
···
         specified in the proposal.  To avoid rekey collisions initiated by both
         ends simultaneously, a value in the range of <option>rand_time</option>
         gets subtracted to form the effective soft lifetime.
-        </para><para>
+
         By default CHILD_SA rekeying is scheduled every hour, minus
         <option>rand_time</option>.
       '';
···
         Number of bytes processed before initiating CHILD_SA rekeying. CHILD_SA
         rekeying refreshes key material, optionally using a Diffie-Hellman
         exchange if a group is specified in the proposal.
-        </para><para>
+
         To avoid rekey collisions initiated by both ends simultaneously, a value
         in the range of <option>rand_bytes</option> gets subtracted to form the
         effective soft volume limit.
-        </para><para>
+
         Volume based CHILD_SA rekeying is disabled by default.
       '';
 
···
         Number of packets processed before initiating CHILD_SA rekeying. CHILD_SA
         rekeying refreshes key material, optionally using a Diffie-Hellman
         exchange if a group is specified in the proposal.
-        </para><para>
+
         To avoid rekey collisions initiated by both ends simultaneously, a value
         in the range of <option>rand_packets</option> gets subtracted to form
         the effective soft packet count limit.
-        </para><para>
+
         Packet count based CHILD_SA rekeying is disabled by default.
       '';
 
···
         this hard packets limit is never reached, because the CHILD_SA gets
         rekeyed before. If that fails for whatever reason, this limit closes the
         CHILD_SA.
-        </para><para>
+
         The default is 10% more than <option>rekey_bytes</option>.
       '';
 
···
         <literal>%unique</literal> sets a unique mark on each CHILD_SA instance,
         beyond that the value <literal>%unique-dir</literal> assigns a different
         unique mark for each
-        </para><para>
+
         An additional mask may be appended to the mark, separated by
         <literal>/</literal>. The default mask if omitted is
         <literal>0xffffffff</literal>.
···
         value <literal>%unique</literal> sets a unique mark on each CHILD_SA
         instance, beyond that the value <literal>%unique-dir</literal> assigns a
         different unique mark for each CHILD_SA direction (in/out).
-        </para><para>
+
         An additional mask may be appended to the mark, separated by
         <literal>/</literal>. The default mask if omitted is
         <literal>0xffffffff</literal>.
···
         <literal>start</literal> tries to re-create the CHILD_SA.
         </para></listitem>
         </itemizedlist>
-        </para><para>
+
         <option>close_action</option> does not provide any guarantee that the
         CHILD_SA is kept alive. It acts on explicit close messages only, but not
         on negotiation failures. Use trap policies to reliably re-create failed

nixos/modules/services/networking/wireguard.nix

···
         default = null;
         type = with types; nullOr str;
         example = "container";
-        description = ''The pre-existing network namespace in which the
+        description = lib.mdDoc ''The pre-existing network namespace in which the
         WireGuard interface is created, and which retains the socket even if the
-        interface is moved via <option>interfaceNamespace</option>. When
-        <literal>null</literal>, the interface is created in the init namespace.
-        See <link
-        xlink:href="https://www.wireguard.com/netns/">documentation</link>.
+        interface is moved via {option}`interfaceNamespace`. When
+        `null`, the interface is created in the init namespace.
+        See [documentation](https://www.wireguard.com/netns/).
         '';
       };
 
···
         default = null;
         type = with types; nullOr str;
         example = "init";
-        description = ''The pre-existing network namespace the WireGuard
-        interface is moved to. The special value <literal>init</literal> means
-        the init namespace. When <literal>null</literal>, the interface is not
+        description = lib.mdDoc ''The pre-existing network namespace the WireGuard
+        interface is moved to. The special value `init` means
+        the init namespace. When `null`, the interface is not
         moved.
-        See <link
-        xlink:href="https://www.wireguard.com/netns/">documentation</link>.
+        See [documentation](https://www.wireguard.com/netns/).
         '';
       };
     };

nixos/modules/services/networking/wpa_supplicant.nix

···
         description = ''
           Whether to allow configuring networks "imperatively" (e.g. via
           <package>wpa_supplicant_gui</package>) and declaratively via
-          <xref linkend="opt-networking.wireless.networks" />.
+          <xref linkend="opt-networking.wireless.networks"/>.
 
           Please note that this adds a custom patch to <package>wpa_supplicant</package>.
         '';

nixos/modules/services/networking/yggdrasil.nix

···
           are supplied, they will be combined, with values from
           <option>configFile</option> taking precedence.
 
-          You can use the command <code>nix-shell -p yggdrasil --run
-          "yggdrasil -genconf"</code> to generate default
+          You can use the command <literal>nix-shell -p yggdrasil --run
+          "yggdrasil -genconf"</literal> to generate default
           configuration values with documentation.
         '';
       };
···
         type = types.nullOr types.str;
         default = null;
         example = "wheel";
-        description = "Group to grant access to the Yggdrasil control socket. If <code>null</code>, only root can access the socket.";
+        description = lib.mdDoc "Group to grant access to the Yggdrasil control socket. If `null`, only root can access the socket.";
       };
 
       openMulticastPort = mkOption {
         type = bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to open the UDP port used for multicast peer
           discovery. The NixOS firewall blocks link-local
           communication, so in order to make local peering work you
-          will also need to set <code>LinkLocalTCPPort</code> in your
-          yggdrasil configuration (<option>config</option> or
-          <option>configFile</option>) to a port number other than 0,
+          will also need to set `LinkLocalTCPPort` in your
+          yggdrasil configuration ({option}`config` or
+          {option}`configFile`) to a port number other than 0,
           and then add that port to
-          <option>networking.firewall.allowedTCPPorts</option>.
+          {option}`networking.firewall.allowedTCPPorts`.
         '';
       };
 

nixos/modules/services/networking/znc/default.nix

···
           format ZNC expects. This is much more flexible than the legacy options
           under <option>services.znc.confOptions.*</option>, but also can't do
           any type checking.
-          </para>
-          <para>
+
           You can use <command>nix-instantiate --eval --strict '&lt;nixpkgs/nixos&gt;' -A config.services.znc.config</command>
           to view the current value. By default it contains a listener for port
           5000 with SSL enabled.
-          </para>
-          <para>
+
           Nix attributes called <literal>extraConfig</literal> will be inserted
           verbatim into the resulting config file.
-          </para>
-          <para>
+
           If <option>services.znc.useLegacyConfig</option> is turned on, the
           option values in <option>services.znc.confOptions.*</option> will be
           gracefully be applied to this option.
-          </para>
-          <para>
+
           If you intend to update the configuration through this option, be sure
           to enable <option>services.znc.mutable</option>, otherwise none of the
           changes here will be applied after the initial deploy.
···
         description = ''
           Configuration file for ZNC. It is recommended to use the
           <option>config</option> option instead.
-          </para>
-          <para>
+
           Setting this option will override any auto-generated config file
           through the <option>confOptions</option> or <option>config</option>
           options.
···
           Indicates whether to allow the contents of the
           <literal>dataDir</literal> directory to be changed by the user at
           run-time.
-          </para>
-          <para>
+
           If enabled, modifications to the ZNC configuration after its initial
           creation are not overwritten by a NixOS rebuild. If disabled, the
           ZNC configuration is rebuilt on every NixOS rebuild.
-          </para>
-          <para>
+
           If the user wants to manage the ZNC service using the web admin
           interface, this option should be enabled.
         '';

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

···
           <option>services.znc.confOptions.*</option> options.
           You can use <command>nix-instantiate --eval --strict '&lt;nixpkgs/nixos&gt;' -A config.services.znc.config</command>
           to view the current value of the config.
-          </para>
-          <para>
+
           In any case, if you need more flexibility,
           <option>services.znc.config</option> can be used to override/add to
           all of the legacy options.

nixos/modules/services/security/privacyidea.nix

···
           using <package>envsubst</package> which is helpful for specifying
           secrets:
           <programlisting>
-          { <xref linkend="opt-services.privacyidea.secretKey" /> = "$SECRET"; }
+          { <xref linkend="opt-services.privacyidea.secretKey"/> = "$SECRET"; }
           </programlisting>
 
           The environment-file can now specify the actual secret key:
···
           description = ''
             Attribute-set containing the settings for <package>privacyidea-ldap-proxy</package>.
             It's possible to pass secrets using env-vars as substitutes and
-            use the option <xref linkend="opt-services.privacyidea.ldap-proxy.environmentFile" />
+            use the option <xref linkend="opt-services.privacyidea.ldap-proxy.environmentFile"/>
             to inject them via <package>envsubst</package>.
           '';
         };
···
         environmentFile = mkOption {
           default = null;
           type = types.nullOr types.str;
-          description = ''
+          description = lib.mdDoc ''
             Environment file containing secrets to be substituted into
-            <xref linkend="opt-services.privacyidea.ldap-proxy.settings" />.
+            [](#opt-services.privacyidea.ldap-proxy.settings).
           '';
         };
       };

nixos/modules/services/security/step-ca.nix

···
         type = with lib.types; attrsOf anything;
         description = ''
           Settings that go into <filename>ca.json</filename>. See
-          <link xlink:href="https://smallstep.com/docs/step-ca/configuration">
-          the step-ca manual</link> for more information. The easiest way to
+          <link xlink:href="https://smallstep.com/docs/step-ca/configuration">the step-ca manual</link>
+          for more information. The easiest way to
           configure this module would be to run <literal>step ca init</literal>
           to generate <filename>ca.json</filename> and then import it using
           <literal>builtins.fromJSON</literal>.

nixos/modules/services/security/tor.nix

···
       relay = {
         enable = mkEnableOption ''relaying of Tor traffic for others.
 
-          See <link xlink:href="https://www.torproject.org/docs/tor-doc-relay" />
+          See <link xlink:href="https://www.torproject.org/docs/tor-doc-relay"/>
           for details.
 
           Setting this to true requires setting
···
 
                 <para>
                   See
-                  <link xlink:href="https://www.torproject.org/docs/tor-doc-relay.html.en" />
+                  <link xlink:href="https://www.torproject.org/docs/tor-doc-relay.html.en"/>
                   for more info.
                 </para>
               </listitem>
···
                 <para>
                   Using this option will make Tor advertise your bridge
                   to users through various mechanisms like
-                  <link xlink:href="https://bridges.torproject.org/" />, though.
+                  <link xlink:href="https://bridges.torproject.org/"/>, though.
                 </para>
 
                 <important>
···
                 </important>
 
                 <para>
-                  See <link xlink:href="https://www.torproject.org/docs/bridges.html.en" />
+                  See <link xlink:href="https://www.torproject.org/docs/bridges.html.en"/>
                   for more info.
                 </para>
               </listitem>
···
                 </para>
 
                 <para>
-                  See <link xlink:href="https://www.torproject.org/docs/bridges.html.en" />
+                  See <link xlink:href="https://www.torproject.org/docs/bridges.html.en"/>
                   for more info.
                 </para>
               </listitem>
···
                   };
                   clientNames = mkOption {
                     type = with types; nonEmptyListOf (strMatching "[A-Za-z0-9+-_]+");
-                    description = ''
+                    description = lib.mdDoc ''
                       Only clients that are listed here are authorized to access the hidden service.
-                      Generated authorization data can be found in <filename>${stateDir}/onion/$name/hostname</filename>.
+                      Generated authorization data can be found in {file}`${stateDir}/onion/$name/hostname`.
                       Clients need to put this authorization data in their configuration file using
-                      <xref linkend="opt-services.tor.settings.HidServAuth"/>.
+                      [](#opt-services.tor.settings.HidServAuth).
                     '';
                   };
                 };

nixos/modules/services/security/vault.nix

···
       storageConfig = mkOption {
         type = types.nullOr types.lines;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           HCL configuration to insert in the storageBackend section.
 
           Confidential values should not be specified here because this option's
           value is written to the Nix store, which is publicly readable.
           Provide credentials and such in a separate file using
-          <xref linkend="opt-services.vault.extraSettingsPaths"/>.
+          [](#opt-services.vault.extraSettingsPaths).
         '';
       };
 

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

···
         The available configuration options can be found in
         <link xlink:href="https://github.com/dani-garcia/vaultwarden/blob/${vaultwarden.version}/.env.template">the environment template file</link>.
 
-        See <xref linkend="opt-services.vaultwarden.environmentFile" /> for how
+        See <xref linkend="opt-services.vaultwarden.environmentFile"/> for how
         to set up access to the Admin UI to invite initial users.
       '';
     };

nixos/modules/services/system/dbus.nix

···
       packages = mkOption {
         type = types.listOf types.path;
         default = [ ];
-        description = ''
+        description = lib.mdDoc ''
           Packages whose D-Bus configuration files should be included in
           the configuration of the D-Bus system-wide or session-wide
           message bus.  Specifically, files in the following directories
           will be included into their respective DBus configuration paths:
-          <filename><replaceable>pkg</replaceable>/etc/dbus-1/system.d</filename>
-          <filename><replaceable>pkg</replaceable>/share/dbus-1/system.d</filename>
-          <filename><replaceable>pkg</replaceable>/share/dbus-1/system-services</filename>
-          <filename><replaceable>pkg</replaceable>/etc/dbus-1/session.d</filename>
-          <filename><replaceable>pkg</replaceable>/share/dbus-1/session.d</filename>
-          <filename><replaceable>pkg</replaceable>/share/dbus-1/services</filename>
+          {file}`«pkg»/etc/dbus-1/system.d`
+          {file}`«pkg»/share/dbus-1/system.d`
+          {file}`«pkg»/share/dbus-1/system-services`
+          {file}`«pkg»/etc/dbus-1/session.d`
+          {file}`«pkg»/share/dbus-1/session.d`
+          {file}`«pkg»/share/dbus-1/services`
         '';
       };
 

nixos/modules/services/system/earlyoom.nix

···
     freeMemKillThreshold = mkOption {
       type = types.nullOr (types.ints.between 1 100);
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Minimum available memory (in percent) before sending SIGKILL.
-        If unset, this defaults to half of <option>freeMemThreshold</option>.
+        If unset, this defaults to half of {option}`freeMemThreshold`.
 
-        See the description of <xref linkend="opt-services.earlyoom.freeMemThreshold"/>.
+        See the description of [](#opt-services.earlyoom.freeMemThreshold).
       '';
     };
 
     freeSwapThreshold = mkOption {
       type = types.ints.between 1 100;
       default = 10;
-      description = ''
+      description = lib.mdDoc ''
         Minimum free swap space (in percent) before sending SIGTERM.
 
-        See the description of <xref linkend="opt-services.earlyoom.freeMemThreshold"/>.
+        See the description of [](#opt-services.earlyoom.freeMemThreshold).
       '';
     };
 
     freeSwapKillThreshold = mkOption {
       type = types.nullOr (types.ints.between 1 100);
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Minimum free swap space (in percent) before sending SIGKILL.
-        If unset, this defaults to half of <option>freeSwapThreshold</option>.
+        If unset, this defaults to half of {option}`freeSwapThreshold`.
 
-        See the description of <xref linkend="opt-services.earlyoom.freeMemThreshold"/>.
+        See the description of [](#opt-services.earlyoom.freeMemThreshold).
       '';
     };
 

nixos/modules/services/torrent/transmission.nix

···
             type = types.path;
             default = "${cfg.home}/${incompleteDir}";
             defaultText = literalExpression ''"''${config.${opt.home}}/${incompleteDir}"'';
-            description = ''
+            description = lib.mdDoc ''
               When enabled with
               services.transmission.home
-              <xref linkend="opt-services.transmission.settings.incomplete-dir-enabled"/>,
+              [](#opt-services.transmission.settings.incomplete-dir-enabled),
               new torrents will download the files to this directory.
               When complete, the files will be moved to download-dir
-              <xref linkend="opt-services.transmission.settings.download-dir"/>.
+              [](#opt-services.transmission.settings.download-dir).
             '';
           };
           options.incomplete-dir-enabled = mkOption {
···
           options.peer-port-random-high = mkOption {
             type = types.port;
             default = 65535;
-            description = ''
+            description = lib.mdDoc ''
               The maximum peer port to listen to for incoming connections
-              when <xref linkend="opt-services.transmission.settings.peer-port-random-on-start"/> is enabled.
+              when [](#opt-services.transmission.settings.peer-port-random-on-start) is enabled.
             '';
           };
           options.peer-port-random-low = mkOption {
             type = types.port;
             default = 65535;
-            description = ''
+            description = lib.mdDoc ''
               The minimal peer port to listen to for incoming connections
-              when <xref linkend="opt-services.transmission.settings.peer-port-random-on-start"/> is enabled.
+              when [](#opt-services.transmission.settings.peer-port-random-on-start) is enabled.
             '';
           };
           options.peer-port-random-on-start = mkOption {
···
           options.script-torrent-done-enabled = mkOption {
             type = types.bool;
             default = false;
-            description = ''
+            description = lib.mdDoc ''
               Whether to run
-              <xref linkend="opt-services.transmission.settings.script-torrent-done-filename"/>
+              [](#opt-services.transmission.settings.script-torrent-done-filename)
               at torrent completion.
             '';
           };
···
           options.watch-dir-enabled = mkOption {
             type = types.bool;
             default = false;
-            description = ''Whether to enable the
-              <xref linkend="opt-services.transmission.settings.watch-dir"/>.
+            description = lib.mdDoc ''Whether to enable the
+              [](#opt-services.transmission.settings.watch-dir).
             '';
           };
           options.trash-original-torrent-files = mkOption {
             type = types.bool;
             default = false;
-            description = ''Whether to delete torrents added from the
-              <xref linkend="opt-services.transmission.settings.watch-dir"/>.
+            description = lib.mdDoc ''Whether to delete torrents added from the
+              [](#opt-services.transmission.settings.watch-dir).
             '';
           };
         };
···
         type = with types; nullOr str;
         default = null;
         example = "770";
-        description = ''
-          If not <code>null</code>, is used as the permissions
-          set by <literal>systemd.activationScripts.transmission-daemon</literal>
-          on the directories <xref linkend="opt-services.transmission.settings.download-dir"/>,
-          <xref linkend="opt-services.transmission.settings.incomplete-dir"/>.
-          and <xref linkend="opt-services.transmission.settings.watch-dir"/>.
+        description = lib.mdDoc ''
+          If not `null`, is used as the permissions
+          set by `systemd.activationScripts.transmission-daemon`
+          on the directories [](#opt-services.transmission.settings.download-dir),
+          [](#opt-services.transmission.settings.incomplete-dir).
+          and [](#opt-services.transmission.settings.watch-dir).
           Note that you may also want to change
-          <xref linkend="opt-services.transmission.settings.umask"/>.
+          [](#opt-services.transmission.settings.umask).
         '';
       };
 
       home = mkOption {
         type = types.path;
         default = "/var/lib/transmission";
-        description = ''
-          The directory where Transmission will create <literal>${settingsDir}</literal>.
-          as well as <literal>${downloadsDir}/</literal> unless
-          <xref linkend="opt-services.transmission.settings.download-dir"/> is changed,
-          and <literal>${incompleteDir}/</literal> unless
-          <xref linkend="opt-services.transmission.settings.incomplete-dir"/> is changed.
+        description = lib.mdDoc ''
+          The directory where Transmission will create `${settingsDir}`.
+          as well as `${downloadsDir}/` unless
+          [](#opt-services.transmission.settings.download-dir) is changed,
+          and `${incompleteDir}/` unless
+          [](#opt-services.transmission.settings.incomplete-dir) is changed.
         '';
       };
 
···
 
       credentialsFile = mkOption {
         type = types.path;
-        description = ''
+        description = lib.mdDoc ''
           Path to a JSON file to be merged with the settings.
           Useful to merge a file which is better kept out of the Nix store
-          to set secret config parameters like <code>rpc-password</code>.
+          to set secret config parameters like `rpc-password`.
         '';
         default = "/dev/null";
         example = "/var/lib/secrets/transmission/settings.json";
···
         to open many more connections at the same time.
 
         Note that you may also want to increase
-        <code>peer-limit-global"</code>.
+        <literal>peer-limit-global"</literal>.
         And be aware that these settings are quite aggressive
         and might not suite your regular desktop use.
         For instance, SSH sessions may time out more easily'';

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

···
       description = ''
         A file containing the Laravel APP_KEY - a 32 character long,
         base64 encoded key used for encryption where needed. Can be
-        generated with <code>head -c 32 /dev/urandom | base64</code>.
+        generated with <literal>head -c 32 /dev/urandom | base64</literal>.
       '';
       example = "/run/keys/bookstack-appkey";
       type = types.path;
···
     appURL = mkOption {
       description = ''
         The root URL that you want to host BookStack on. All URLs in BookStack will be generated using this value.
-        If you change this in the future you may need to run a command to update stored URLs in the database. Command example: <code>php artisan bookstack:update-url https://old.example.com https://new.example.com</code>
+        If you change this in the future you may need to run a command to update stored URLs in the database. Command example: <literal>php artisan bookstack:update-url https://old.example.com https://new.example.com</literal>
       '';
       default = "http${lib.optionalString tlsEnabled "s"}://${cfg.hostname}";
       defaultText = ''http''${lib.optionalString tlsEnabled "s"}://''${cfg.hostname}'';

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

···
       webserver = mkOption {
         type = types.enum [ "nginx" "caddy" ];
         default = "nginx";
-        description = ''
+        description = lib.mdDoc ''
           Whether to use nginx or caddy for virtual host management.
 
-          Further nginx configuration can be done by adapting <literal>services.nginx.virtualHosts.&lt;name&gt;</literal>.
-          See <xref linkend="opt-services.nginx.virtualHosts"/> for further information.
+          Further nginx configuration can be done by adapting `services.nginx.virtualHosts.<name>`.
+          See [](#opt-services.nginx.virtualHosts) for further information.
 
-          Further apache2 configuration can be done by adapting <literal>services.httpd.virtualHosts.&lt;name&gt;</literal>.
-          See <xref linkend="opt-services.httpd.virtualHosts"/> for further information.
+          Further apache2 configuration can be done by adapting `services.httpd.virtualHosts.<name>`.
+          See [](#opt-services.httpd.virtualHosts) for further information.
         '';
       };
 

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

···
             addDefaults = true;
           }
         '';
-        description = ''
+        description = lib.mdDoc ''
           Specify the Content Security Policy which is passed to Helmet.
-          For configuration details see <link xlink:href="https://helmetjs.github.io/docs/csp/"
-          >https://helmetjs.github.io/docs/csp/</link>.
+          For configuration details see <https://helmetjs.github.io/docs/csp/>.
         '';
       };
       protocolUseSSL = mkOption {

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

···
         name = mkOption {
           type = str;
           default = "keycloak";
-          description = ''
+          description = lib.mdDoc ''
             Database name to use when connecting to an external or
             manually provisioned database; has no effect when a local
             database is automatically provisioned.
 
-            To use this with a local database, set <xref
-            linkend="opt-services.keycloak.database.createLocally" /> to
-            <literal>false</literal> and create the database and user
+            To use this with a local database, set [](#opt-services.keycloak.database.createLocally) to
+            `false` and create the database and user
             manually.
           '';
         };
···
         username = mkOption {
           type = str;
           default = "keycloak";
-          description = ''
+          description = lib.mdDoc ''
             Username to use when connecting to an external or manually
             provisioned database; has no effect when a local database is
             automatically provisioned.
 
-            To use this with a local database, set <xref
-            linkend="opt-services.keycloak.database.createLocally" /> to
-            <literal>false</literal> and create the database and user
+            To use this with a local database, set [](#opt-services.keycloak.database.createLocally) to
+            `false` and create the database and user
             manually.
           '';
         };
···
                     want to set this to <literal>/auth</literal> to
                     keep compatibility with your clients.
 
-                    See <link
-                    xlink:href="https://www.keycloak.org/migration/migrating-to-quarkus"
-                    /> for more information on migrating from Wildfly
-                    to Quarkus.
+                    See <link xlink:href="https://www.keycloak.org/migration/migrating-to-quarkus"/>
+                    for more information on migrating from Wildfly to Quarkus.
                   </para>
                 </note>
               '';
···
                   </varlistentry>
                 </variablelist>
 
-                See <link
-                xlink:href="https://www.keycloak.org/server/reverseproxy"
-                /> for more information.
+                See <link xlink:href="https://www.keycloak.org/server/reverseproxy"/> for more information.
               '';
             };
           };
···
           }
         '';
 
-        description = ''
+        description = lib.mdDoc ''
           Configuration options corresponding to parameters set in
-          <filename>conf/keycloak.conf</filename>.
+          {file}`conf/keycloak.conf`.
 
-          Most available options are documented at <link
-          xlink:href="https://www.keycloak.org/server/all-config" />.
+          Most available options are documented at <https://www.keycloak.org/server/all-config>.
 
           Options containing secret data should be set to an attribute
-          set containing the attribute <literal>_secret</literal> - a
+          set containing the attribute `_secret` - a
           string pointing to a file containing the value the option
           should be set to. See the example to get a better picture of
           this: in the resulting
-          <filename>conf/keycloak.conf</filename> file, the
-          <literal>https-key-store-password</literal> key will be set
+          {file}`conf/keycloak.conf` file, the
+          `https-key-store-password` key will be set
           to the contents of the
-          <filename>/run/keys/store_password</filename> file.
+          {file}`/run/keys/store_password` file.
         '';
       };
     };

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

···
           affect other virtualHosts running on your nginx instance, if any.
           Alternatively you can configure a reverse-proxy of your choice to serve these paths:
 
-          <code>/ -> $(nix-instantiate --eval '&lt;nixpkgs&gt;' -A mastodon.outPath)/public</code>
+          <literal>/ -> $(nix-instantiate --eval '&lt;nixpkgs&gt;' -A mastodon.outPath)/public</literal>
 
-          <code>/ -> 127.0.0.1:{{ webPort }} </code>(If there was no file in the directory above.)
+          <literal>/ -> 127.0.0.1:{{ webPort }} </literal>(If there was no file in the directory above.)
 
-          <code>/system/ -> /var/lib/mastodon/public-system/</code>
+          <literal>/system/ -> /var/lib/mastodon/public-system/</literal>
 
-          <code>/api/v1/streaming/ -> 127.0.0.1:{{ streamingPort }}</code>
+          <literal>/api/v1/streaming/ -> 127.0.0.1:{{ streamingPort }}</literal>
 
           Make sure that websockets are forwarded properly. You might want to set up caching
           of some requests. Take a look at mastodon's provided nginx configuration at
-          <code>https://github.com/mastodon/mastodon/blob/master/dist/nginx.conf</code>.
+          <literal>https://github.com/mastodon/mastodon/blob/master/dist/nginx.conf</literal>.
         '';
         type = lib.types.bool;
         default = false;
···
           that user will be created, otherwise it should be set to the
           name of a user created elsewhere.  In both cases,
           <package>mastodon</package> and a package containing only
-          the shell script <code>mastodon-env</code> will be added to
+          the shell script <literal>mastodon-env</literal> will be added to
           the user's package set. To run a command from
-          <package>mastodon</package> such as <code>tootctl</code>
+          <package>mastodon</package> such as <literal>tootctl</literal>
           with the environment configured by this module use
-          <code>mastodon-env</code>, as in:
+          <literal>mastodon-env</literal>, as in:
 
-          <code>mastodon-env tootctl accounts create newuser --email [e-mail]</code>
+          <literal>mastodon-env tootctl accounts create newuser --email [e-mail]</literal>
         '';
         type = lib.types.str;
         default = "mastodon";
···
       };
 
       vapidPublicKeyFile = lib.mkOption {
-        description = ''
+        description = lib.mdDoc ''
           Path to file containing the public key used for Web Push
           Voluntary Application Server Identification.  A new keypair can
           be generated by running:
 
-          <code>nix build -f '&lt;nixpkgs&gt;' mastodon; cd result; bin/rake webpush:generate_keys</code>
+          `nix build -f '<nixpkgs>' mastodon; cd result; bin/rake webpush:generate_keys`
 
-          If <option>mastodon.vapidPrivateKeyFile</option>does not
+          If {option}`mastodon.vapidPrivateKeyFile`does not
           exist, it and this file will be created with a new keypair.
         '';
         default = "/var/lib/mastodon/secrets/vapid-public-key";
···
       };
 
       secretKeyBaseFile = lib.mkOption {
-        description = ''
+        description = lib.mdDoc ''
           Path to file containing the secret key base.
           A new secret key base can be generated by running:
 
-          <code>nix build -f '&lt;nixpkgs&gt;' mastodon; cd result; bin/rake secret</code>
+          `nix build -f '<nixpkgs>' mastodon; cd result; bin/rake secret`
 
           If this file does not exist, it will be created with a new secret key base.
         '';
···
       };
 
       otpSecretFile = lib.mkOption {
-        description = ''
+        description = lib.mdDoc ''
           Path to file containing the OTP secret.
           A new OTP secret can be generated by running:
 
-          <code>nix build -f '&lt;nixpkgs&gt;' mastodon; cd result; bin/rake secret</code>
+          `nix build -f '<nixpkgs>' mastodon; cd result; bin/rake secret`
 
           If this file does not exist, it will be created with a new OTP secret.
         '';
···
       };
 
       vapidPrivateKeyFile = lib.mkOption {
-        description = ''
+        description = lib.mdDoc ''
           Path to file containing the private key used for Web Push
           Voluntary Application Server Identification.  A new keypair can
           be generated by running:
 
-          <code>nix build -f '&lt;nixpkgs&gt;' mastodon; cd result; bin/rake webpush:generate_keys</code>
+          `nix build -f '<nixpkgs>' mastodon; cd result; bin/rake webpush:generate_keys`
 
           If this file does not exist, it will be created with a new
           private key.

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

···
             one version of MediaWiki, or have other applications that also use the
             database, you can give the table names a unique prefix to stop any naming
             conflicts or confusion.
-            See <link xlink:href='https://www.mediawiki.org/wiki/Manual:$wgDBprefix'/>.
+            See <link xlink:href="https://www.mediawiki.org/wiki/Manual:$wgDBprefix"/>.
           '';
         };
 

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

···
       type = types.str;
       default = config.services.nextcloud.home;
       defaultText = literalExpression "config.services.nextcloud.home";
-      description = ''
-        Data storage path of nextcloud.  Will be <xref linkend="opt-services.nextcloud.home" /> by default.
+      description = lib.mdDoc ''
+        Data storage path of nextcloud.  Will be [](#opt-services.nextcloud.home) by default.
         This folder will be populated with a config.php and data folder which contains the state of the instance (excl the database).";
       '';
       example = "/mnt/nextcloud-file";
···
     extraApps = mkOption {
       type = types.attrsOf types.package;
       default = { };
-      description = ''
+      description = lib.mdDoc ''
         Extra apps to install. Should be an attrSet of appid to packages generated by fetchNextcloudApp.
         The appid must be identical to the "id" value in the apps appinfo/info.xml.
-        Using this will disable the appstore to prevent Nextcloud from updating these apps (see <xref linkend="opt-services.nextcloud.appstoreEnable" />).
+        Using this will disable the appstore to prevent Nextcloud from updating these apps (see [](#opt-services.nextcloud.appstoreEnable)).
       '';
       example = literalExpression ''
         {
···
     extraAppsEnable = mkOption {
       type = types.bool;
       default = true;
-      description = ''
-        Automatically enable the apps in <xref linkend="opt-services.nextcloud.extraApps" /> every time nextcloud starts.
+      description = lib.mdDoc ''
+        Automatically enable the apps in [](#opt-services.nextcloud.extraApps) every time nextcloud starts.
         If set to false, apps need to be enabled in the Nextcloud user interface or with nextcloud-occ app:enable.
       '';
     };
···
       type = types.nullOr types.bool;
       default = null;
       example = true;
-      description = ''
+      description = lib.mdDoc ''
         Allow the installation of apps and app updates from the store.
-        Enabled by default unless there are packages in <xref linkend="opt-services.nextcloud.extraApps" />.
-        Set to true to force enable the store even if <xref linkend="opt-services.nextcloud.extraApps" /> is used.
+        Enabled by default unless there are packages in [](#opt-services.nextcloud.extraApps).
+        Set to true to force enable the store even if [](#opt-services.nextcloud.extraApps) is used.
         Set to false to disable the installation of apps from the global appstore. App management is always enabled regardless of this setting.
       '';
     };
···
         This is used by the theming app and for generating previews of certain images (e.g. SVG and HEIF).
         You may want to disable it for increased security. In that case, previews will still be available
         for some images (e.g. JPEG and PNG).
-        See <link xlink:href="https://github.com/nextcloud/server/issues/13099" />.
+        See <link xlink:href="https://github.com/nextcloud/server/issues/13099"/>.
     '' // {
       default = true;
     };
···
       hstsMaxAge = mkOption {
         type = types.ints.positive;
         default = 15552000;
-        description = ''
-          Value for the <code>max-age</code> directive of the HTTP
-          <code>Strict-Transport-Security</code> header.
+        description = lib.mdDoc ''
+          Value for the `max-age` directive of the HTTP
+          `Strict-Transport-Security` header.
 
           See section 6.1.1 of IETF RFC 6797 for detailed information on this
           directive and header.

nixos/modules/services/web-apps/node-red.nix

···
       type = types.path;
       default = "${cfg.package}/lib/node_modules/node-red/settings.js";
       defaultText = literalExpression ''"''${package}/lib/node_modules/node-red/settings.js"'';
-      description = ''
+      description = lib.mdDoc ''
         Path to the JavaScript configuration file.
-        See <link
-        xlink:href="https://github.com/node-red/node-red/blob/master/packages/node_modules/node-red/settings.js"/>
+        See <https://github.com/node-red/node-red/blob/master/packages/node_modules/node-red/settings.js>
         for a configuration example.
       '';
     };

nixos/modules/services/web-apps/snipe-it.nix

···
       description = ''
         A file containing the Laravel APP_KEY - a 32 character long,
         base64 encoded key used for encryption where needed. Can be
-        generated with <code>head -c 32 /dev/urandom | base64</code>.
+        generated with <literal>head -c 32 /dev/urandom | base64</literal>.
       '';
       example = "/run/keys/snipe-it/appkey";
       type = types.path;
···
       description = ''
         The root URL that you want to host Snipe-IT on. All URLs in Snipe-IT will be generated using this value.
         If you change this in the future you may need to run a command to update stored URLs in the database.
-        Command example: <code>snipe-it snipe-it:update-url https://old.example.com https://new.example.com</code>
+        Command example: <literal>snipe-it snipe-it:update-url https://old.example.com https://new.example.com</literal>
       '';
       default = "http${lib.optionalString tlsEnabled "s"}://${cfg.hostName}";
       defaultText = ''

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

···
     noAuthentication = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         If set to true, no password is required to access the web frontend.
       '';
     };

nixos/modules/services/web-apps/wiki-js.nix

···
       };
       description = ''
         Settings to configure <package>wiki-js</package>. This directly
-        corresponds to <link xlink:href="https://docs.requarks.io/install/config">the upstream
-        configuration options</link>.
+        corresponds to <link xlink:href="https://docs.requarks.io/install/config">the upstream configuration options</link>.
 
         Secrets can be injected via the environment by
         <itemizedlist>
-          <listitem><para>specifying <xref linkend="opt-services.wiki-js.environmentFile" />
+          <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>

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

···
               prefix. Typically this is changed if you are installing multiple WordPress blogs
               in the same database.
 
-              See <link xlink:href='https://codex.wordpress.org/Editing_wp-config.php#table_prefix'/>.
+              See <link xlink:href="https://codex.wordpress.org/Editing_wp-config.php#table_prefix"/>.
             '';
           };
 
···
           description = ''
             Any additional text to be appended to the wp-config.php
             configuration file. This is a PHP script. For configuration
-            settings, see <link xlink:href='https://codex.wordpress.org/Editing_wp-config.php'/>.
+            settings, see <link xlink:href="https://codex.wordpress.org/Editing_wp-config.php"/>.
           '';
           example = ''
             define( 'AUTOSAVE_INTERVAL', 60 ); // Seconds

nixos/modules/services/web-servers/apache-httpd/vhost-options.nix

···
       default = false;
       description = ''
         Whether to enable serving <filename>~/public_html</filename> as
-        <literal>/~<replaceable>username</replaceable></literal>.
+        <literal>/~«username»</literal>.
       '';
     };
 
···
       default = "";
       example = "Disallow: /foo/";
       description = ''
-        Specification of pages to be ignored by web crawlers. See <link
-        xlink:href='http://www.robotstxt.org/'/> for details.
+        Specification of pages to be ignored by web crawlers. See <link xlink:href="http://www.robotstxt.org/"/> for details.
       '';
     };
 
···
         };
       '';
       description = ''
-        Declarative location config. See <link
-        xlink:href="https://httpd.apache.org/docs/2.4/mod/core.html#location"/> for details.
+        Declarative location config. See <link xlink:href="https://httpd.apache.org/docs/2.4/mod/core.html#location"/> for details.
       '';
     };
 

nixos/modules/services/web-servers/nginx/default.nix

···
           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" />
+          <listitem><para><xref linkend="opt-services.nginx.appendConfig"/>
           </para></listitem>
-          <listitem><para><xref linkend="opt-services.nginx.httpConfig" />
+          <listitem><para><xref linkend="opt-services.nginx.httpConfig"/>
           </para></listitem>
-          <listitem><para><xref linkend="opt-services.nginx.logError" />
+          <listitem><para><xref linkend="opt-services.nginx.logError"/>
           </para></listitem>
           </itemizedlist>
 
           If additional verbatim config in addition to other options is needed,
-          <xref linkend="opt-services.nginx.appendConfig" /> should be used instead.
+          <xref linkend="opt-services.nginx.appendConfig"/> should be used instead.
         '';
       };
 

nixos/modules/services/web-servers/uwsgi.nix

···
             <para>
               When in Emperor mode, any capability to be inherited by a vassal must
               be specified again in the vassal configuration using <literal>cap</literal>.
-              See the uWSGI <link
-              xlink:href="https://uwsgi-docs.readthedocs.io/en/latest/Capabilities.html">docs</link>
+              See the uWSGI <link xlink:href="https://uwsgi-docs.readthedocs.io/en/latest/Capabilities.html">docs</link>
               for more information.
             </para>
           </note>

nixos/modules/services/x11/desktop-managers/plasma5.nix

···
     supportDDC = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Support setting monitor brightness via DDC.
-        </para>
-        <para>
+
         This is not needed for controlling brightness of the internal monitor
         of a laptop and as it is considered experimental by upstream, it is
         disabled by default.

nixos/modules/services/x11/display-managers/lightdm-greeters/mini.nix

···
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable lightdm-mini-greeter as the lightdm greeter.
 
           Note that this greeter starts only the default X session.
           You can configure the default X session using
-          <xref linkend="opt-services.xserver.displayManager.defaultSession"/>.
+          [](#opt-services.xserver.displayManager.defaultSession).
         '';
       };
 

nixos/modules/services/x11/display-managers/lightdm-greeters/tiny.nix

···
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable lightdm-tiny-greeter as the lightdm greeter.
 
           Note that this greeter starts only the default X session.
           You can configure the default X session using
-          <xref linkend="opt-services.xserver.displayManager.defaultSession"/>.
+          [](#opt-services.xserver.displayManager.defaultSession).
         '';
       };
 

nixos/modules/services/x11/window-managers/fvwm2.nix

···
       gestures = mkOption {
         default = false;
         type = types.bool;
-        description = "Whether or not to enable libstroke for gesture support";
+        description = lib.mdDoc "Whether or not to enable libstroke for gesture support";
       };
     };
   };

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

···
       '';
       description = ''
         The name of the system used in the <option>system.build.toplevel</option> derivation.
-        </para><para>
+
         That derivation has the following name:
         <literal>"nixos-system-''${config.system.name}-''${config.system.nixos.label}"</literal>
       '';

nixos/modules/system/boot/initrd-network.nix

···
     boot.initrd.network.enable = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Add network connectivity support to initrd. The network may be
-        configured using the <literal>ip</literal> kernel parameter,
-        as described in <link
-        xlink:href="https://www.kernel.org/doc/Documentation/filesystems/nfs/nfsroot.txt">the
-        kernel documentation</link>.  Otherwise, if
-        <option>networking.useDHCP</option> is enabled, an IP address
+        configured using the `ip` kernel parameter,
+        as described in [the kernel documentation](https://www.kernel.org/doc/Documentation/filesystems/nfs/nfsroot.txt).
+        Otherwise, if
+        {option}`networking.useDHCP` is enabled, an IP address
         is acquired using DHCP.
 
         You should add the module(s) required for your network card to
         boot.initrd.availableKernelModules.
-        <literal>lspci -v | grep -iA8 'network\|ethernet'</literal>
+        `lspci -v | grep -iA8 'network\|ethernet'`
         will tell you which.
       '';
     };

nixos/modules/system/boot/loader/grub/grub.nix

···
         type = types.bool;
         description = ''
           Whether to invoke <literal>grub-install</literal> with
-          <literal>--removable</literal>.</para>
+          <literal>--removable</literal>.
 
-          <para>Unless you turn this on, GRUB will install itself somewhere in
+          Unless you turn this on, GRUB will install itself somewhere in
           <literal>boot.loader.efi.efiSysMountPoint</literal> (exactly where
           depends on other config variables). If you've set
           <literal>boot.loader.efi.canTouchEfiVariables</literal> *AND* you
···
           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>").</para>
+          are not supported on this system.</literal>").
 
-          <para>If you turn this feature on, GRUB will install itself in a
+          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
-          are hardcoded to try first, regardless of NVRAM EFI variables.</para>
+          are hardcoded to try first, regardless of NVRAM EFI variables.
 
-          <para>To summarize, turn this on if:
+          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>

nixos/modules/system/boot/luksroot.nix

···
     boot.initrd.luks.devices = mkOption {
       default = { };
       example = { luksroot.device = "/dev/disk/by-uuid/430e9eff-d852-4f68-aa3b-2fa3599ebe08"; };
-      description = ''
+      description = lib.mdDoc ''
         The encrypted disk that should be opened before the root
         filesystem is mounted. Both LVM-over-LUKS and LUKS-over-LVM
         setups are supported. The unencrypted devices can be accessed as
-        <filename>/dev/mapper/<replaceable>name</replaceable></filename>.
+        {file}`/dev/mapper/«name»`.
       '';
 
       type = with types; attrsOf (submodule (

nixos/modules/system/boot/networkd.nix

···
         <citerefentry><refentrytitle>systemd.netdev</refentrytitle>
         <manvolnum>5</manvolnum></citerefentry> for details.
         A detailed explanation about how VRFs work can be found in the
-        <link xlink:href="https://www.kernel.org/doc/Documentation/networking/vrf.txt">kernel
-        docs</link>.
+        <link xlink:href="https://www.kernel.org/doc/Documentation/networking/vrf.txt">kernel docs</link>.
       '';
     };
 
···
       };
 
       extraArgs = mkOption {
-        description = ''
+        description = lib.mdDoc ''
           Extra command-line arguments to pass to systemd-networkd-wait-online.
-          These also affect per-interface <literal>systemd-network-wait-online@</literal> services.
+          These also affect per-interface `systemd-network-wait-online@` services.
 
-          See <link xlink:href="https://www.freedesktop.org/software/systemd/man/systemd-networkd-wait-online.service.html">
-          <citerefentry><refentrytitle>systemd-networkd-wait-online.service</refentrytitle><manvolnum>8</manvolnum>
-          </citerefentry></link> for all available options.
+          See [{manpage}`systemd-networkd-wait-online.service(8)`](https://www.freedesktop.org/software/systemd/man/systemd-networkd-wait-online.service.html) for all available options.
         '';
         type = with types; listOf str;
         default = [];

nixos/modules/system/boot/stage-1.nix

···
         if you want to resume from file. If left empty, the swap partitions are used.
         Specify here the device where the file resides.
         You should also use <varname>boot.kernelParams</varname> to specify
-        <literal><replaceable>resume_offset</replaceable></literal>.
+        <literal>«resume_offset»</literal>.
       '';
     };
 

nixos/modules/system/boot/systemd/logind.nix

···
     services.logind.killUserProcesses = mkOption {
       default = false;
       type = types.bool;
-      description = ''
+      description = lib.mdDoc ''
         Specifies whether the processes of a user should be killed
         when the user logs out.  If true, the scope unit corresponding
         to the session and all processes inside that scope will be
         terminated.  If false, the scope is "abandoned" (see
-        <link xlink:href="https://www.freedesktop.org/software/systemd/man/systemd.scope.html#">
-        systemd.scope(5)</link>), and processes are not killed.
-        </para>
+        [systemd.scope(5)](https://www.freedesktop.org/software/systemd/man/systemd.scope.html#)), and processes are not killed.
 
-        <para>
-        See <link xlink:href="https://www.freedesktop.org/software/systemd/man/logind.conf.html#KillUserProcesses=">logind.conf(5)</link>
+        See [logind.conf(5)](https://www.freedesktop.org/software/systemd/man/logind.conf.html#KillUserProcesses=)
         for more details.
       '';
     };

nixos/modules/system/boot/systemd/tmpfiles.nix

···
       default = [];
       example = literalExpression "[ pkgs.lvm2 ]";
       apply = map getLib;
-      description = ''
-        List of packages containing <command>systemd-tmpfiles</command> rules.
+      description = lib.mdDoc ''
+        List of packages containing {command}`systemd-tmpfiles` rules.
 
         All files ending in .conf found in
-        <filename><replaceable>pkg</replaceable>/lib/tmpfiles.d</filename>
+        {file}`«pkg»/lib/tmpfiles.d`
         will be included.
         If this folder does not exist or does not contain any files an error will be returned instead.
 
-        If a <filename>lib</filename> output is available, rules are searched there and only there.
-        If there is no <filename>lib</filename> output it will fall back to <filename>out</filename>
+        If a {file}`lib` output is available, rules are searched there and only there.
+        If there is no {file}`lib` output it will fall back to {file}`out`
         and if that does not exist either, the default output will be used.
       '';
     };

nixos/modules/tasks/auto-upgrade.nix

···
         type = types.enum ["switch" "boot"];
         default = "switch";
         example = "boot";
-        description = ''
+        description = lib.mdDoc ''
           Whether to run
-          <literal>nixos-rebuild switch --upgrade</literal> or run
-          <literal>nixos-rebuild boot --upgrade</literal>
+          `nixos-rebuild switch --upgrade` or run
+          `nixos-rebuild boot --upgrade`
         '';
       };
 

nixos/modules/tasks/network-interfaces.nix

···
       description = ''
         Whether to enable IPv6 Privacy Extensions for interfaces not
         configured explicitly in
-        <xref linkend="opt-networking.interfaces._name_.tempAddress" />.
+        <xref linkend="opt-networking.interfaces._name_.tempAddress"/>.
 
         This sets the ipv6.conf.*.use_tempaddr sysctl for all
         interfaces. Possible values are:

nixos/modules/tasks/scsi-link-power-management.nix

···
     powerManagement.scsiLinkPolicy = mkOption {
       default = null;
       type = types.nullOr (types.enum allowedValues);
-      description = ''
+      description = lib.mdDoc ''
         SCSI link power management policy. The kernel default is
         "max_performance".
-        </para><para>
+
         "med_power_with_dipm" is supported by kernel versions
         4.15 and newer.
       '';

nixos/modules/virtualisation/nixos-containers.nix

···
             privateNetwork = mkOption {
               type = types.bool;
               default = false;
-              description = ''
+              description = lib.mdDoc ''
                 Whether to give the container its own private virtual
                 Ethernet interface.  The interface is called
-                <literal>eth0</literal>, and is hooked up to the interface
-                <literal>ve-<replaceable>container-name</replaceable></literal>
+                `eth0`, and is hooked up to the interface
+                `ve-«container-name»`
                 on the host.  If this option is not set, then the
                 container shares the network interfaces of the host,
                 and can bind to any port on any interface.
···
               };
           }
         '';
-      description = ''
+      description = lib.mdDoc ''
         A set of NixOS system configurations to be run as lightweight
         containers.  Each container appears as a service
-        <literal>container-<replaceable>name</replaceable></literal>
+        `container-«name»`
         on the host system, allowing it to be started and stopped via
-        <command>systemctl</command>.
+        {command}`systemctl`.
       '';
     };
 

nixos/modules/virtualisation/podman/default.nix

···
 
         Podman implements the Docker API.
 
-        Users must be in the <code>podman</code> group in order to connect. As
+        Users must be in the <literal>podman</literal> group in order to connect. As
         with Docker, members of this group can gain root access.
       '';
     };

nixos/modules/virtualisation/podman/network-socket.nix

···
         with TLS client certificate authentication.
 
         This allows Docker clients to connect with the equivalents of the Docker
-        CLI <code>-H</code> and <code>--tls*</code> family of options.
+        CLI <literal>-H</literal> and <literal>--tls*</literal> family of options.
 
         For certificate setup, see https://docs.docker.com/engine/security/protect-access/
 

nixos/modules/virtualisation/qemu-vm.nix

···
         description =
           ''
             Virtual networks to which the VM is connected.  Each
-            number <replaceable>N</replaceable> in this list causes
+            number «N» in this list causes
             the VM to have a virtual Ethernet interface attached to a
             separate virtual network on which it will be assigned IP
             address
-            <literal>192.168.<replaceable>N</replaceable>.<replaceable>M</replaceable></literal>,
-            where <replaceable>M</replaceable> is the index of this VM
+            <literal>192.168.«N».«M»</literal>,
+            where «M» is the index of this VM
             in the list of VMs.
           '';
       };