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

nixos/*: more option docs conversions

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

@@ -99,14 +99,6 @@ let
 
   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;
 
@@ -124,20 +116,17 @@ in rec {
 
   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.
@@ -154,7 +143,7 @@ in rec {
           else ''
             python ${./mergeJSON.py} \
               ${lib.optionalString warningsAreErrors "--warnings-are-errors"} \
-              $baseJSON $options \
+              ${baseOptionsJSON} $options \
               > $dst/options.json
           ''
       }

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

@@ -3,6 +3,11 @@ import json
 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:
@@ -41,137 +46,135 @@ def unpivot(options: Dict[Key, Option]) -> Dict[str, JSON]:
         result[opt.name] = opt.value
     return result
 
+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
+
+    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 finalize(self, data):
+        return "".join(data)
+
+def p_command(md):
+    COMMAND_PATTERN = r'\{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 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 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 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 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:
-    import mistune
-    import re
-    from xml.sax.saxutils import escape, quoteattr
-
-    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):
-            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)
-
-    plugins = []
-
-    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)
-
-    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)
-
-    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)
-
-    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)
-
-    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 convertString(path: str, text: str) -> str:
-        rendered = mistune.markdown(text, renderer=Renderer(path), plugins=plugins)
+        try:
-        # keep trailing spaces so we can diff the generated XML to check for conversion bugs.
+            rendered = md(text)
-        return rendered.rstrip() + text[len(text.rstrip()):]
+            # 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

@@ -71,12 +71,11 @@ with lib;
             ))
         '';
         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
+          can be found at <https://sourceware.org/git/?p=glibc.git;a=blob;f=localedata/SUPPORTED>.
-          xlink:href="https://sourceware.org/git/?p=glibc.git;a=blob;f=localedata/SUPPORTED"/>.
         '';
       };
 

nixos/modules/config/resolvconf.nix

@@ -83,9 +83,9 @@ in
       dnsExtensionMechanism = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
-          Enable the <code>edns0</code> option in <filename>resolv.conf</filename>. With
+          Enable the `edns0` option in {file}`resolv.conf`. With
-          that option set, <code>glibc</code> supports use of the extension mechanisms for
+          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

@@ -109,11 +109,11 @@ in
 
     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

@@ -16,7 +16,7 @@ in
 
     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.
 
@@ -25,12 +25,12 @@ in
         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);
@@ -58,7 +58,7 @@ in
         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

@@ -100,17 +100,17 @@ let
       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
+          automatically sets {option}`group` to
-          <literal>users</literal>, <option>createHome</option> to
+          `users`, {option}`createHome` to
-          <literal>true</literal>, <option>home</option> to
+          `true`, {option}`home` to
-          <filename>/home/<replaceable>username</replaceable></filename>,
+          {file}`/home/«username»`,
-          <option>useDefaultShell</option> to <literal>true</literal>,
+          {option}`useDefaultShell` to `true`,
-          and <option>isSystemUser</option> to
+          and {option}`isSystemUser` to
-          <literal>false</literal>.
+          `false`.
-          Exactly one of <literal>isNormalUser</literal> and
+          Exactly one of `isNormalUser` and
-          <literal>isSystemUser</literal> must be true.
+          `isSystemUser` must be true.
         '';
       };
 
@@ -151,13 +151,12 @@ let
       pamMount = mkOption {
         type = with types; attrsOf str;
         default = {};
-        description = ''
+        description = lib.mdDoc ''
           Attributes for user's entry in
-          <filename>pam_mount.conf.xml</filename>.
+          {file}`pam_mount.conf.xml`.
-          Useful attributes might include <code>path</code>,
+          Useful attributes might include `path`,
-          <code>options</code>, <code>fstype</code>, and <code>server</code>.
+          `options`, `fstype`, and `server`.
-          See <link
+          See <http://pam-mount.sourceforge.net/pam_mount.conf.5.html>
-          xlink:href="http://pam-mount.sourceforge.net/pam_mount.conf.5.html" />
           for more information.
         '';
       };
@@ -167,12 +166,12 @@ let
         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,
+          `programs` if necessary,
-          like <code>programs.zsh.enable = true;</code>.
+          like `programs.zsh.enable = true;`.
         '';
       };
 

nixos/modules/config/xdg/portal.nix

@@ -33,7 +33,7 @@ in
 
   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

@@ -32,10 +32,9 @@ in
       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

@@ -13,7 +13,7 @@ in
 
           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

@@ -34,15 +34,15 @@ in
       packages = mkOption {
         type = types.listOf types.path;
         example = literalExpression "[ pkgs.tiscamera ]";
-        description = ''
+        description = lib.mdDoc ''
-          List of packages containing <command>uvcvideo</command> dynamic controls
+          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>
+          Note that these will serve as input to the {command}`libwebcam`
-          package which through its own <command>udev</command> rule will register
+          package which through its own {command}`udev` rule will register
-          the dynamic controls from specified packages to the <command>uvcvideo</command>
+          the dynamic controls from specified packages to the {command}`uvcvideo`
           driver.
         '';
         apply = map getBin;

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

@@ -618,7 +618,7 @@ in
         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

@@ -119,11 +119,11 @@ in
       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
+        this option, extended with <literal>nixpkgs.overlays</literal>, if
-        that is also set. Either <code>nixpkgs.crossSystem</code> or
+        that is also set. Either <literal>nixpkgs.crossSystem</literal> or
-        <code>nixpkgs.localSystem</code> will be used in an assertion
+        <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
@@ -132,18 +132,18 @@ in
         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
+        so the <literal>nixos</literal> in the default value is in fact a
-        relative path. The <code>config</code>, <code>overlays</code>,
+        relative path. The <literal>config</literal>, <literal>overlays</literal>,
-        <code>localSystem</code>, and <code>crossSystem</code> come
+        <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.
@@ -162,7 +162,7 @@ in
         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.
       '';
     };
 
@@ -188,9 +188,9 @@ in
         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>.
       '';
     };
 
@@ -205,9 +205,9 @@ in
       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.
       '';
     };
 
@@ -230,7 +230,7 @@ in
         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.
       '';
     };
 
@@ -253,7 +253,7 @@ in
         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
@@ -261,7 +261,7 @@ in
         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.
       '';
     };
 
@@ -279,13 +279,13 @@ in
 
         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.
       '';
     };
 
@@ -316,7 +316,7 @@ in
         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 = ..;
@@ -328,9 +328,9 @@ in
           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

@@ -11,10 +11,10 @@ with lib;
       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

@@ -69,13 +69,12 @@ in {
           };
         }
       '';
-      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

@@ -11,11 +11,11 @@ with lib;
       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

@@ -8,7 +8,7 @@ with lib;
       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

@@ -72,9 +72,9 @@ in {
           };
         }
       '';
-      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

@@ -33,24 +33,24 @@ in {
     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
+        [](#opt-programs.nncp.secrets) into the file
-        <literal>${nncpCfgFile}</literal>. Node keypairs go in
+        `${nncpCfgFile}`. Node keypairs go in
-        <literal>secrets</literal>, do not specify them in
+        `secrets`, do not specify them in
-        <literal>settings</literal> as they will be leaked into
+        `settings` as they will be leaked into
-        <literal>/nix/store</literal>!
+        `/nix/store`!
       '';
       default = { };
     };

nixos/modules/programs/ssh.nix

@@ -95,7 +95,7 @@ in
         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

@@ -39,7 +39,7 @@ in {
       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

@@ -15,14 +15,14 @@ in
       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

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

@@ -61,7 +61,7 @@ in {
 
           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

@@ -62,19 +62,19 @@ in
     wheelNeedsPassword = mkOption {
       type = with types; bool;
       default = true;
-      description = ''
+      description = lib.mdDoc ''
-        Whether users of the <code>wheel</code> group must provide a password to
+        Whether users of the `wheel` group must provide a password to
-        run commands as super user via <command>doas</command>.
+        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 ''
@@ -113,8 +113,8 @@ in
             noPass = mkOption {
               type = with types; bool;
               default = false;
-              description = ''
+              description = lib.mdDoc ''
-                If <code>true</code>, the user is not required to enter a
+                If `true`, the user is not required to enter a
                 password.
               '';
             };
@@ -122,18 +122,18 @@ in
             noLog = mkOption {
               type = with types; bool;
               default = false;
-              description = ''
+              description = lib.mdDoc ''
-                If <code>true</code>, successful executions will not be logged
+                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 = ''
+              description = lib.mdDoc ''
-                If <code>true</code>, do not ask for a password again for some
+                If `true`, do not ask for a password again for some
                 time after the user successfully authenticates.
               '';
             };
@@ -141,10 +141,10 @@ in
             keepEnv = mkOption {
               type = with types; bool;
               default = false;
-              description = ''
+              description = lib.mdDoc ''
-                If <code>true</code>, environment variables other than those
+                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.
               '';
             };
@@ -152,18 +152,18 @@ in
             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
+                `variable=value`. If the first character of
-                <code>value</code> is a '$', the value to be set is taken from
+                `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
+                NOTE: All rules have `setenv { SSH_AUTH_SOCK }` by
-                default. To prevent <code>SSH_AUTH_SOCK</code> from being
+                default. To prevent `SSH_AUTH_SOCK` from being
-                inherited, add <code>"-SSH_AUTH_SOCK"</code> anywhere in this
+                inherited, add `"-SSH_AUTH_SOCK"` anywhere in this
                 list.
               '';
             };
@@ -183,23 +183,23 @@ in
             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
+                `"foo"`. It is also possible to only allow running as
-                a specific group with <code>":bar"</code>.
+                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
@@ -210,9 +210,9 @@ in
             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

@@ -52,7 +52,7 @@ with lib;
     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.
@@ -62,7 +62,7 @@ with lib;
         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

@@ -807,14 +807,14 @@ in
         default = config.krb5.enable;
         defaultText = literalExpression "config.krb5.enable";
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
-          Enables Kerberos PAM modules (<literal>pam-krb5</literal>,
+          Enables Kerberos PAM modules (`pam-krb5`,
-          <literal>pam-ccreds</literal>).
+          `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
+          (`config.krb5.enable` should be set to
-          <literal>true</literal>).
+          `true`).
 
           Note that the Kerberos PAM modules are not necessary when using SSS
           to handle Kerberos authentication.
@@ -826,13 +826,12 @@ in
       enable = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
-          Enables P11 PAM (<literal>pam_p11</literal>) module.
+          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
+          More information can be found [here](https://github.com/OpenSC/pam_p11).
-          xlink:href="https://github.com/OpenSC/pam_p11">here</link>.
         '';
       };
 
@@ -859,77 +858,71 @@ in
       enable = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
-          Enables U2F PAM (<literal>pam-u2f</literal>) module.
+          Enables U2F PAM (`pam-u2f`) module.
 
           If set, users listed in
-          <filename>$XDG_CONFIG_HOME/Yubico/u2f_keys</filename> (or
+          {file}`$XDG_CONFIG_HOME/Yubico/u2f_keys` (or
-          <filename>$HOME/.config/Yubico/u2f_keys</filename> if XDG variable is
+          {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>
+          `username:first_keyHandle,first_public_key: second_keyHandle,second_public_key`
-          This file can be generated using <command>pamu2fcfg</command> command.
+          This file can be generated using {command}`pamu2fcfg` command.
 
-          More information can be found <link
+          More information can be found [here](https://developers.yubico.com/pam-u2f/).
-          xlink:href="https://developers.yubico.com/pam-u2f/">here</link>.
         '';
       };
 
       authFile = mkOption {
         default = null;
         type = with types; nullOr path;
-        description = ''
+        description = lib.mdDoc ''
-          By default <literal>pam-u2f</literal> module reads the keys from
+          By default `pam-u2f` module reads the keys from
-          <filename>$XDG_CONFIG_HOME/Yubico/u2f_keys</filename> (or
+          {file}`$XDG_CONFIG_HOME/Yubico/u2f_keys` (or
-          <filename>$HOME/.config/Yubico/u2f_keys</filename> if XDG variable is
+          {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>
+          `username:first_keyHandle,first_public_key: second_keyHandle,second_public_key`
-          This file can be generated using <command>pamu2fcfg</command> command.
+          This file can be generated using {command}`pamu2fcfg` command.
 
-          More information can be found <link
+          More information can be found [here](https://developers.yubico.com/pam-u2f/).
-          xlink:href="https://developers.yubico.com/pam-u2f/">here</link>.
         '';
       };
 
       appId = mkOption {
         default = null;
         type = with types; nullOr str;
-        description = ''
+        description = lib.mdDoc ''
-            By default <literal>pam-u2f</literal> module sets the application
+            By default `pam-u2f` module sets the application
-            ID to <literal>pam://$HOSTNAME</literal>.
+            ID to `pam://$HOSTNAME`.
 
-            When using <command>pamu2fcfg</command>, you can specify your
+            When using {command}`pamu2fcfg`, you can specify your
-            application ID with the <literal>-i</literal> flag.
+            application ID with the `-i` flag.
 
-            More information can be found <link
+            More information can be found [here](https://developers.yubico.com/pam-u2f/Manuals/pam_u2f.8.html)
-            xlink:href="https://developers.yubico.com/pam-u2f/Manuals/pam_u2f.8.html">
-            here</link>
         '';
       };
 
       origin = mkOption {
         default = null;
         type = with types; nullOr str;
-        description = ''
+        description = lib.mdDoc ''
-            By default <literal>pam-u2f</literal> module sets the origin
+            By default `pam-u2f` module sets the origin
-            to <literal>pam://$HOSTNAME</literal>.
+            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
+            When using {command}`pamu2fcfg`, you can specify your
-            application ID with the <literal>-o</literal> flag.
+            application ID with the `-o` flag.
 
-            More information can be found <link
+            More information can be found [here](https://developers.yubico.com/pam-u2f/Manuals/pam_u2f.8.html)
-            xlink:href="https://developers.yubico.com/pam-u2f/Manuals/pam_u2f.8.html">
-            here</link>
         '';
       };
 
@@ -985,18 +978,17 @@ in
       enable = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
-          Enables Uber's USSH PAM (<literal>pam-ussh</literal>) module.
+          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
+          More information can be found [here](https://github.com/uber/pam-ussh).
-          xlink:href="https://github.com/uber/pam-ussh">here</link>.
         '';
       };
 
@@ -1075,17 +1067,16 @@ in
       enable = mkOption {
         default = false;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
-          Enables Yubico PAM (<literal>yubico-pam</literal>) module.
+          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>
+          `username:yubikey_token_id1:yubikey_token_id2`
-          More information can be found <link
+          More information can be found [here](https://developers.yubico.com/yubico-pam/).
-          xlink:href="https://developers.yubico.com/yubico-pam/">here</link>.
         '';
       };
       control = mkOption {
@@ -1120,7 +1111,7 @@ in
       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
@@ -1130,18 +1121,16 @@ in
           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
+          More information can be found [here](https://developers.yubico.com/yubico-pam/Authentication_Using_Challenge-Response.html).
-          xlink:href="https://developers.yubico.com/yubico-pam/Authentication_Using_Challenge-Response.html">here</link>.
         '';
       };
       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
+          More information can be found [here](https://developers.yubico.com/yubico-pam/Authentication_Using_Challenge-Response.html).
-          xlink:href="https://developers.yubico.com/yubico-pam/Authentication_Using_Challenge-Response.html">here</link>.
         '';
       };
     };

nixos/modules/security/pam_mount.nix

@@ -31,10 +31,9 @@ in
       extraVolumes = mkOption {
         type = types.listOf types.str;
         default = [];
-        description = ''
+        description = lib.mdDoc ''
           List of volume definitions for pam_mount.
-          For more information, visit <link
+          For more information, visit <http://pam-mount.sourceforge.net/pam_mount.conf.5.html>.
-          xlink:href="http://pam-mount.sourceforge.net/pam_mount.conf.5.html" />.
         '';
       };
 
@@ -64,22 +63,20 @@ in
         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
+          For more information, visit <http://pam-mount.sourceforge.net/pam_mount.conf.5.html>.
-          xlink:href="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
+          For more information, visit <http://pam-mount.sourceforge.net/pam_mount.conf.5.html>.
-          xlink:href="http://pam-mount.sourceforge.net/pam_mount.conf.5.html" />.
         '';
       };
 

nixos/modules/security/pam_usb.nix

@@ -17,10 +17,9 @@ in
       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
+          more information, visit <https://github.com/aluzzardi/pam_usb/wiki/Getting-Started#setting-up-devices-and-users>.
-          xlink:href="https://github.com/aluzzardi/pam_usb/wiki/Getting-Started#setting-up-devices-and-users" />.
         '';
       };
 

nixos/modules/security/sudo.nix

@@ -55,19 +55,19 @@ in
       type = types.bool;
       default = true;
       description =
-        ''
+        lib.mdDoc ''
-          Whether users of the <code>wheel</code> group must
+          Whether users of the `wheel` group must
-          provide a password to run commands as super user via <command>sudo</command>.
+          provide a password to run commands as super user via {command}`sudo`.
         '';
       };
 
     security.sudo.execWheelOnly = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
-        Only allow members of the <code>wheel</code> group to execute sudo by
+        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.
       '';
     };
@@ -139,12 +139,12 @@ in
           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>.
+              A user can be specified using just the username: `"foo"`.
-              It is also possible to specify a user/group combination using <code>"foo:bar"</code>
+              It is also possible to specify a user/group combination using `"foo:bar"`
-              or to only allow running as a specific group with <code>":bar"</code>.
+              or to only allow running as a specific group with `":bar"`.
             '';
           };
 
@@ -159,7 +159,7 @@ in
                   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

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

nixos/modules/services/backup/restic.nix

@@ -227,7 +227,7 @@ in
           type = types.package;
           default = pkgs.restic;
           defaultText = literalExpression "pkgs.restic";
-          description = ''
+          description = lib.mdDoc ''
             Restic package to use.
           '';
         };

nixos/modules/services/backup/syncoid.nix

@@ -192,10 +192,10 @@ in
           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
+              («pool/dataset») or remote
-              (<replaceable>user@server:pool/dataset</replaceable>).
+              («user@server:pool/dataset»).
             '';
           };
 

nixos/modules/services/backup/zrepl.nix

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

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

@@ -18,12 +18,11 @@ in
     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](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners).
-        >About self-hosted runners</link>.
       '';
       type = lib.types.bool;
     };

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

@@ -113,15 +113,15 @@ in
     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}`configFile` takes precedence over {option}`services`.
-        <option>checkInterval</option> and <option>concurrent</option> will be ignored too.
+        {option}`checkInterval` and {option}`concurrent` will be ignored too.
 
-        This option is deprecated, please use <option>services</option> instead.
+        This option is deprecated, please use {option}`services` instead.
-        You can use <option>registrationConfigFile</option> and
+        You can use {option}`registrationConfigFile` and
-        <option>registrationFlags</option>
+        {option}`registrationFlags`
         for settings not covered by this module.
       '';
     };
@@ -130,16 +130,16 @@ in
         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.
@@ -149,7 +149,7 @@ in
       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.
       '';
     };
@@ -158,17 +158,17 @@ in
       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 ''
         {
@@ -250,17 +250,17 @@ in
         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.
@@ -270,10 +270,10 @@ in
             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>.
+              `gitlab-runner register`.
-              Execute <literal>gitlab-runner register --help</literal>
+              Execute `gitlab-runner register --help`
               for a list of supported flags.
             '';
           };
@@ -281,32 +281,32 @@ in
             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>
+              For secrets you can use {option}`registrationConfigFile`
-              with <literal>RUNNER_ENV</literal> variable set.
+              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).
             '';
@@ -315,14 +315,14 @@ in
             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.
             '';
           };
@@ -330,7 +330,7 @@ in
             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.
             '';
@@ -338,14 +338,14 @@ in
           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.
             '';
           };
@@ -353,7 +353,7 @@ in
             type = types.listOf types.str;
             default = [ ];
             example = [ "other-host:127.0.0.1" ];
-            description = ''
+            description = lib.mdDoc ''
               Add a custom host-to-IP mapping.
             '';
           };
@@ -361,7 +361,7 @@ in
             type = types.listOf types.str;
             default = [ ];
             example = [ "ruby:*" "python:*" "php:*" "my.registry.tld:5000/*:*" ];
-            description = ''
+            description = lib.mdDoc ''
               Whitelist allowed images.
             '';
           };
@@ -369,21 +369,21 @@ in
             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.
             '';
@@ -391,7 +391,7 @@ in
           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.
             '';
@@ -399,22 +399,22 @@ in
           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.
             '';
@@ -422,14 +422,14 @@ in
           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.
             '';
@@ -437,7 +437,7 @@ in
           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.
             '';
@@ -445,9 +445,9 @@ in
           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

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

nixos/modules/services/databases/mysql.nix

@@ -201,7 +201,7 @@ in
             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.
@@ -210,8 +210,8 @@ in
 
                 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>.
+                [GRANT syntax](https://mariadb.com/kb/en/library/grant/).
-                The attributes are used as <code>GRANT ''${attrName} ON ''${attrValue}</code>.
+                The attributes are used as `GRANT ''${attrName} ON ''${attrValue}`.
               '';
               example = literalExpression ''
                 {

nixos/modules/services/databases/neo4j.nix

@@ -139,15 +139,14 @@ in {
     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
+        `LOAD CSV` clause to be that defined by
-        <option>directories.imports</option>. It restricts
+        {option}`directories.imports`. It restricts
         access to only those files within that directory and its
         subdirectories.
-        </para>
+
-        <para>
+        Setting this option to `false` introduces
-        Setting this option to <literal>false</literal> introduces
         possible security problems.
       '';
     };
@@ -155,15 +154,14 @@ in {
     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.
       '';
     };
 
@@ -227,20 +225,18 @@ in {
       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
+          {option}`directories.certificates` and
-          associated files (by default: <filename>neo4j.key</filename> and
+          associated files (by default: {file}`neo4j.key` and
-          <filename>neo4j.cert</filename>). Its use will be deprecated.
+          {file}`neo4j.cert`). Its use will be deprecated.
-          </para>
+
-          <para>
           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`.
         '';
       };
 
@@ -258,21 +254,19 @@ in {
         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>.
+          given to the Neo4j daemon user `neo4j`.
-          </para>
+
-          <para>
           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
+          its {option}`baseDirectory`,{option}`revokedDir` and
-          <option>trustedDir</option> must then be setup manually. The
+          {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.
@@ -283,14 +277,13 @@ in {
         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`.
         '';
       };
 
@@ -309,16 +302,15 @@ in {
         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
+          `LOAD CSV` clause. Only meaningful when
-          <option>constrainLoadCvs</option> is set to
+          {option}`constrainLoadCvs` is set to
-          <literal>true</literal>.
+          `true`.
-          </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`.
         '';
       };
 
@@ -326,15 +318,14 @@ in {
         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`.
         '';
       };
     };
@@ -386,15 +377,14 @@ in {
       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
+          {option}`directories.certificates` and
-          associated files (by default: <filename>neo4j.key</filename> and
+          associated files (by default: {file}`neo4j.key` and
-          <filename>neo4j.cert</filename>). Its use will be deprecated.
+          {file}`neo4j.cert`). Its use will be deprecated.
         '';
       };
     };
@@ -417,18 +407,16 @@ in {
           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.
+              {option}`trustedDir` option.
-              </para>
+
-              <para>
               Keys should in general be generated and distributed offline by a
               trusted certificate authority and not by utilizing this mode.
             '';
@@ -438,17 +426,16 @@ in {
             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>.
+              to the Neo4j daemon user `neo4j`.
-              </para>
+
-              <para>
               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.
             '';
           };
@@ -483,16 +470,15 @@ in {
           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.
             '';
           };
 
@@ -536,19 +522,18 @@ in {
             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
+              either this policy's {option}`baseDirectory` or
-              <option>directories.certificates</option> to something other than
+              {option}`directories.certificates` to something other than
               their default. Ensure read/write permissions are given to the
-              Neo4j daemon user <literal>neo4j</literal>.
+              Neo4j daemon user `neo4j`.
-              </para>
+
-              <para>
               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

@@ -88,7 +88,7 @@ in {
       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 {
@@ -173,9 +173,9 @@ in {
       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";
       };
@@ -183,9 +183,9 @@ in {
       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

@@ -62,12 +62,12 @@ in {
         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"/>
+        <http://www.postgresql.org/docs/current/static/libpq-connect.html>
-        </para><para>
+
         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

@@ -81,8 +81,7 @@ in
         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">
+          <link xlink:href="https://www.postgresql.org/docs/current/auth-pg-hba-conf.html">PostgreSQL documentation for pg_hba.conf</link>
-          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
@@ -150,7 +149,7 @@ in
             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
@@ -158,8 +157,8 @@ in
 
                 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>.
+                [GRANT syntax](https://www.postgresql.org/docs/current/sql-grant.html).
-                The attributes are used as <code>GRANT ''${attrValue} ON ''${attrName}</code>.
+                The attributes are used as `GRANT ''${attrValue} ON ''${attrName}`.
               '';
               example = literalExpression ''
                 {

nixos/modules/services/databases/victoriametrics.nix

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

nixos/modules/services/development/zammad.nix

@@ -139,7 +139,7 @@ in
           '';
           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

@@ -136,7 +136,9 @@ in
           };
           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

@@ -10,7 +10,7 @@ let
       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;
@@ -33,18 +33,18 @@ let
             ;; 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.
         '';
       };
     };
@@ -131,7 +131,7 @@ in
       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.
       '';
@@ -139,7 +139,7 @@ in
     keyboards = mkOption {
       type = types.attrsOf (types.submodule keyboard);
       default = { };
-      description = "Keyboard configurations.";
+      description = lib.mdDoc "Keyboard configurations.";
     };
   };
 

nixos/modules/services/hardware/lcd.nix

@@ -63,8 +63,7 @@ in with lib; {
           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
@@ -72,13 +71,11 @@ in with lib; {
             <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

@@ -209,11 +209,11 @@ in
       packages = mkOption {
         type = types.listOf types.path;
         default = [];
-        description = ''
+        description = lib.mdDoc ''
-          List of packages containing <command>udev</command> rules.
+          List of packages containing {command}`udev` rules.
           All files found in
-          <filename><replaceable>pkg</replaceable>/etc/udev/rules.d</filename> and
+          {file}`«pkg»/etc/udev/rules.d` and
-          <filename><replaceable>pkg</replaceable>/lib/udev/rules.d</filename>
+          {file}`«pkg»/lib/udev/rules.d`
           will be included.
         '';
         apply = map getBin;
@@ -281,16 +281,15 @@ in
     networking.usePredictableInterfaceNames = mkOption {
       default = true;
       type = types.bool;
-      description = ''
+      description = lib.mdDoc ''
-        Whether to assign <link
+        Whether to assign [predictable names to network interfaces](http://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames).
-        xlink:href='http://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames'>predictable
+        If enabled, interfaces
-        names to network interfaces</link>.  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.
       '';
     };
@@ -306,8 +305,8 @@ in
 
           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>«pkg»/etc/udev/rules.d</filename> and
-          <filename><replaceable>pkg</replaceable>/lib/udev/rules.d</filename>
+          <filename>«pkg»/lib/udev/rules.d</filename>
           will be included.
         '';
       };

nixos/modules/services/logging/filebeat.nix

@@ -31,20 +31,20 @@ in
       };
 
       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
+          different `<name>` for each, but setting
-          <xref linkend="opt-services.filebeat.inputs._name_.type"/>
+          [](#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, ... }: {
@@ -77,24 +77,24 @@ in
       };
 
       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
+          different `<name>` for each, but setting
-          <xref linkend="opt-services.filebeat.modules._name_.module"/>
+          [](#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, ... }: {
@@ -161,8 +161,7 @@ in
                 internal = true;
                 description = ''
                   Inputs specify how Filebeat locates and processes
-                  input data. Use <xref
+                  input data. Use <xref linkend="opt-services.filebeat.inputs"/> instead.
-                  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

@@ -276,9 +276,9 @@ in
         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" '''
@@ -346,11 +346,11 @@ in
       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

@@ -112,9 +112,9 @@ in {
         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

@@ -38,11 +38,11 @@ with lib;
       remotesFile = mkOption {
         type = types.nullOr types.str;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
-          Path to the <code>remotes</code> control file. This file contains a
+          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.
         '';
       };
@@ -153,17 +153,17 @@ with lib;
         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

@@ -13,12 +13,12 @@ in
     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>.
+        Further nginx configuration can be done by adapting `services.nginx.virtualHosts.<name>`.
-        See <xref linkend="opt-services.nginx.virtualHosts"/> for further information.
+        See [](#opt-services.nginx.virtualHosts) for further information.
       '';
     };
 

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

@@ -23,10 +23,10 @@ let
     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.
       '';
     };
@@ -239,11 +239,11 @@ in
         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>
+          `locations."/inbox".proxyPass = "http://unix:''${config.services.public-inbox.http.port}:/inbox";`
-          Set to null and use <code>systemd.sockets.public-inbox-httpd.listenStreams</code>
+          Set to null and use `systemd.sockets.public-inbox-httpd.listenStreams`
           if you need a more advanced listening.
         '';
       };

nixos/modules/services/mail/roundcube.nix

@@ -14,12 +14,12 @@ in
     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>.
+        Further nginx configuration can be done by adapting `services.nginx.virtualHosts.<name>`.
-        See <xref linkend="opt-services.nginx.virtualHosts"/> for further information.
+        See [](#opt-services.nginx.virtualHosts) for further information.
       '';
     };
 
@@ -99,11 +99,11 @@ in
     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

@@ -86,9 +86,9 @@ in
       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.
       '';
     };
@@ -136,9 +136,9 @@ in
             example = {
               default_max_list_members = 3;
             };
-            description = ''
+            description = lib.mdDoc ''
-              The <filename>robot.conf</filename> configuration file as key value set.
+              The {file}`robot.conf` configuration file as key value set.
-              See <link xlink:href='https://sympa-community.github.io/gpldoc/man/sympa.conf.5.html' />
+              See <https://sympa-community.github.io/gpldoc/man/sympa.conf.5.html>
               for list of configuration parameters.
             '';
           };
@@ -242,7 +242,7 @@ in
         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>.
         '';
       };
 
@@ -285,9 +285,9 @@ in
           viewlogs_page_size = 50;
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
-        The <filename>sympa.conf</filename> configuration file as key value set.
+        The {file}`sympa.conf` configuration file as key value set.
-        See <link xlink:href='https://sympa-community.github.io/gpldoc/man/sympa.conf.5.html' />
+        See <https://sympa-community.github.io/gpldoc/man/sympa.conf.5.html>
         for list of configuration parameters.
       '';
     };

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

@@ -40,23 +40,16 @@ in {
             };
           }
         '';
-        description = ''
+        description = lib.mdDoc ''
-          <filename>config.yaml</filename> configuration as a Nix attribute set.
+          {file}`config.yaml` configuration as a Nix attribute set.
-          </para>
 
-          <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](https://github.com/Half-Shot/matrix-appservice-discord/blob/master/config/config.sample.yaml).
-          config.sample.yaml</link>.
-          </para>
 
-          <para>
+          {option}`config.bridge.domain` and {option}`config.bridge.homeserverUrl`
-          <option>config.bridge.domain</option> and <option>config.bridge.homeserverUrl</option>
           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`
-          Secret tokens should be specified using <option>environmentFile</option>
           instead of this world-readable attribute set.
         '';
       };

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

@@ -75,15 +75,12 @@ in {
             };
           }
         '';
-        description = ''
+        description = lib.mdDoc ''
-          <filename>config.yaml</filename> configuration as a Nix attribute set.
+          {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](https://github.com/mautrix/facebook/blob/master/mautrix_facebook/example-config.yaml).
-          example-config.yaml</link>.
-          </para>
 
-          <para>
+          Secret tokens should be specified using {option}`environmentFile`
-          Secret tokens should be specified using <option>environmentFile</option>
           instead of this world-readable attribute set.
         '';
       };

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

@@ -78,15 +78,12 @@ in {
             };
           }
         '';
-        description = ''
+        description = lib.mdDoc ''
-          <filename>config.yaml</filename> configuration as a Nix attribute set.
+          {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](https://github.com/tulir/mautrix-telegram/blob/master/example-config.yaml).
-          example-config.yaml</link>.
-          </para>
 
-          <para>
+          Secret tokens should be specified using {option}`environmentFile`
-          Secret tokens should be specified using <option>environmentFile</option>
           instead of this world-readable attribute set.
         '';
       };

nixos/modules/services/misc/autorandr.nix

@@ -27,9 +27,9 @@ let
     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 = { };
       };
@@ -154,7 +154,7 @@ let
         });
         description = ''
           Output scale configuration.
-          </para><para>
+
           Either configure by pixels or a scaling factor. When using pixel method the
           <citerefentry>
             <refentrytitle>xrandr</refentrytitle>
@@ -165,7 +165,7 @@ let
           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

@@ -11,14 +11,13 @@ let
   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
@@ -29,14 +28,12 @@ let
     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

@@ -125,9 +125,9 @@ in {
     };
 
     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

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

nixos/modules/services/misc/geoipupdate.nix

@@ -40,7 +40,7 @@ in
         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
@@ -92,8 +92,7 @@ in
 
                 Always handled as a secret whether the value is
                 wrapped in a <literal>{ _secret = ...; }</literal>
-                attrset or not (refer to <xref
+                attrset or not (refer to <xref linkend="opt-services.geoipupdate.settings"/> for
-                linkend="opt-services.geoipupdate.settings" /> for
                 details).
               '';
               apply = x: if isAttrs x then x else { _secret = x; };

nixos/modules/services/misc/klipper.nix

@@ -71,7 +71,7 @@ in
       };
 
       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

@@ -636,12 +636,10 @@ in
             <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

@@ -22,8 +22,8 @@ in
         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">
+        See the <link xlink:href="https://github.com/aiberia/persistent-evdev#example-usage-with-libvirt">project page</link>
-        project page</link> for example configuration of virtual devices with libvirt
+        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

@@ -180,7 +180,7 @@ in
           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;
@@ -209,7 +209,7 @@ in
           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
@@ -252,8 +252,8 @@ in
 
               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>,
+              You can do this with <literal>gpg --edit-key [key-id]</literal>,
-              then use the <code>passwd</code> command and do not enter a new password.
+              then use the <literal>passwd</literal> command and do not enter a new password.
             '';
           };
           pgp-pubkey = mkOption {
@@ -294,7 +294,7 @@ in
               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

@@ -42,7 +42,7 @@ in {
       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

@@ -68,7 +68,7 @@ in {
     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
@@ -82,8 +82,6 @@ in {
         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

@@ -66,16 +66,16 @@ in {
 
       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
+          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</option>.
+          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)
         '';
       };
 
@@ -88,10 +88,10 @@ in {
       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

@@ -92,7 +92,7 @@ in {
       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

@@ -251,9 +251,9 @@ in {
 
       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

@@ -32,17 +32,17 @@ in
       };
 
       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>
+          A module can be specified multiple times by choosing a different `<name>`
-          for each, but setting <xref linkend="opt-services.metricbeat.modules._name_.module"/> to the same value.
+          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

@@ -138,29 +138,29 @@ in
       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 = ''
+        description = lib.mdDoc ''
-          <filename>munin-node.conf</filename> extra configuration. See
+          {file}`munin-node.conf` extra configuration. See
-          <link xlink:href='http://guide.munin-monitoring.org/en/latest/reference/munin-node.conf.html' />
+          <http://guide.munin-monitoring.org/en/latest/reference/munin-node.conf.html>
         '';
       };
 
       extraPluginConfig = mkOption {
         default = "";
         type = types.lines;
-        description = ''
+        description = lib.mdDoc ''
-          <filename>plugin-conf.d</filename> extra plugin configuration. See
+          {file}`plugin-conf.d` extra plugin configuration. See
-          <link xlink:href='http://guide.munin-monitoring.org/en/latest/plugin/use.html' />
+          <http://guide.munin-monitoring.org/en/latest/plugin/use.html>
         '';
         example = ''
           [fail2ban_*]
@@ -266,11 +266,11 @@ in
       extraGlobalConfig = mkOption {
         default = "";
         type = types.lines;
-        description = ''
+        description = lib.mdDoc ''
-          <filename>munin.conf</filename> extra global configuration.
+          {file}`munin.conf` extra global configuration.
-          See <link xlink:href='http://guide.munin-monitoring.org/en/latest/reference/munin.conf.html' />.
+          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}" someone@example.com
@@ -280,10 +280,10 @@ in
       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

@@ -88,7 +88,7 @@ in
 
   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

@@ -114,14 +114,14 @@ in {
         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/"/>
+          <https://docs.netdata.cloud/collectors/plugins.d/>
-          </para><para>
+
           Cannot be combined with configText.
         '';
       };

nixos/modules/services/monitoring/parsedmarc.nix

@@ -29,11 +29,11 @@ in
         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)
           '';
         };
 
@@ -68,15 +68,13 @@ in
       geoIp = lib.mkOption {
         type = lib.types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
-          Whether to enable and configure the <link
+          Whether to enable and configure the [geoipupdate](#opt-services.geoipupdate.enable)
-          linkend="opt-services.geoipupdate.enable">geoipupdate</link>
           service to automatically fetch GeoIP databases. Not crucial,
           but recommended for full functionality.
 
-          To finish the setup, you need to manually set the <xref
+          To finish the setup, you need to manually set the [](#opt-services.geoipupdate.settings.AccountID) and
-          linkend="opt-services.geoipupdate.settings.AccountID" /> and
+          [](#opt-services.geoipupdate.settings.LicenseKey)
-          <xref linkend="opt-services.geoipupdate.settings.LicenseKey" />
           options.
         '';
       };
@@ -97,11 +95,11 @@ in
             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.
           '';
         };
@@ -208,13 +206,12 @@ in
             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>
+                wrapped in a `{ _secret = ...; }`
-                attrset or not (refer to <xref
+                attrset or not (refer to [](#opt-services.parsedmarc.settings) for
-                linkend="opt-services.parsedmarc.settings" /> for
                 details).
               '';
               apply = x: if isAttrs x || x == null then x else { _secret = x; };
@@ -273,13 +270,12 @@ in
             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>
+                wrapped in a `{ _secret = ...; }`
-                attrset or not (refer to <xref
+                attrset or not (refer to [](#opt-services.parsedmarc.settings) for
-                linkend="opt-services.parsedmarc.settings" /> for
                 details).
               '';
               apply = x: if isAttrs x || x == null then x else { _secret = x; };
@@ -326,14 +322,13 @@ in
             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>
+                wrapped in a `{ _secret = ...; }`
-                attrset or not (refer to <xref
+                attrset or not (refer to [](#opt-services.parsedmarc.settings) for
-                linkend="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

@@ -379,9 +379,8 @@ let
       gce_sd_configs = mkOpt (types.listOf promTypes.gce_sd_config) ''
         List of Google Compute Engine service discovery configurations.
 
-        See <link
+        See <link xlink:href="https://prometheus.io/docs/prometheus/latest/configuration/configuration/#gce_sd_config">the relevant Prometheus configuration docs</link>
-        xlink:href="https://prometheus.io/docs/prometheus/latest/configuration/configuration/#gce_sd_config">the
+        for more detail.
-        relevant Prometheus configuration docs</link> for more detail.
       '';
 
       hetzner_sd_configs = mkOpt (types.listOf promTypes.hetzner_sd_config) ''
@@ -807,9 +806,7 @@ let
       filter = mkOpt types.str ''
         Filter can be used optionally to filter the instance list by other
         criteria Syntax of this filter string is described here in the filter
-        query parameter section: <link
+        query parameter section: <link xlink:href="https://cloud.google.com/compute/docs/reference/latest/instances/list"/>.
-        xlink:href="https://cloud.google.com/compute/docs/reference/latest/instances/list"
-        />.
       '';
 
       refresh_interval = mkDefOpt types.str "60s" ''
@@ -825,7 +822,7 @@ let
         The tag separator used to separate concatenated GCE instance network tags.
 
         See the GCP documentation on network tags for more information:
-        <link xlink:href="https://cloud.google.com/vpc/docs/add-remove-network-tags" />
+        <link xlink:href="https://cloud.google.com/vpc/docs/add-remove-network-tags"/>
       '';
     };
   };
@@ -1033,13 +1030,13 @@ let
 
     auth_token = mkOpt types.str ''
       Optional authentication information for token-based authentication:
-      <link xlink:href="https://docs.mesosphere.com/1.11/security/ent/iam-api/#passing-an-authentication-token" />
+      <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

@@ -33,10 +33,10 @@ in
         work with this exporter:
         <programlisting>
         {
-          <xref linkend="opt-services.prometheus.exporters.dovecot.enable" /> = true;
+          <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.prometheus.exporters.dovecot.socketPath"/> = "/var/run/dovecot2/old-stats";
-          <xref linkend="opt-services.dovecot2.mailPlugins.globally.enable" /> = [ "old_stats" ];
+          <xref linkend="opt-services.dovecot2.mailPlugins.globally.enable"/> = [ "old_stats" ];
-          <xref linkend="opt-services.dovecot2.extraConfig" /> = '''
+          <xref linkend="opt-services.dovecot2.extraConfig"/> = '''
             service old-stats {
               unix_listener old-stats {
                 user = dovecot-exporter

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

@@ -22,7 +22,7 @@ in
         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

@@ -41,7 +41,7 @@ in
         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

@@ -83,13 +83,13 @@ in
           };
           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.
             '';
           };
@@ -155,12 +155,12 @@ in
 
       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

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

nixos/modules/services/networking/bird.nix

@@ -13,18 +13,18 @@ in
       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.
         '';
       };
@@ -34,9 +34,9 @@ in
         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

@@ -17,7 +17,10 @@ in {
         }
       '';
       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

@@ -40,37 +40,37 @@ let
           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 = ''
+          description = lib.mdDoc ''
-            Path to CA bundle file (PEM/X509). Uses system trust store if <code>null</code>.
+            Path to CA bundle file (PEM/X509). Uses system trust store if `null`.
           '';
           type = types.nullOr types.str;
         };
@@ -124,7 +124,7 @@ let
         };
 
         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

@@ -19,12 +19,12 @@ in
     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>
+          `hans-«name»`
-          where <replaceable>name</replaceable> is the name of the
+          where «name» is the name of the
           corresponding attribute name.
         '';
         example = literalExpression ''

nixos/modules/services/networking/iodine.nix

@@ -28,12 +28,12 @@ in
     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>
+          `iodine-«name»`
-          where <replaceable>name</replaceable> is the name of the
+          where «name» is the name of the
           corresponding attribute name.
         '';
         example = literalExpression ''

nixos/modules/services/networking/kea.nix

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

nixos/modules/services/networking/ncdns.nix

@@ -176,10 +176,10 @@ in
             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

@@ -329,8 +329,7 @@ in {
         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
@@ -388,12 +387,12 @@ in {
       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
+          `networkmanager_strongswan` plugin will be added to
-          the <option>networking.networkmanager.plugins</option> option
+          the {option}`networking.networkmanager.plugins` option
           so you don't need to to that yourself.
         '';
       };

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

@@ -167,9 +167,9 @@ in
             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

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

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

@@ -40,21 +40,19 @@ in
       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 `systemd.timesyncd` if enabled.
-          Disables <literal>systemd.timesyncd</literal> 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
@@ -65,10 +63,9 @@ in
 
       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

@@ -38,10 +38,10 @@ let
       # 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
+          is passed to `openconnect` via the
-          <code>--passwd-on-stdin</code> option.
+          `--passwd-on-stdin` option.
         '';
         default = null;
         example = "/var/lib/secrets/openconnect-passwd";
@@ -63,13 +63,13 @@ let
       };
 
       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
+          Non-key-value options like `deflate` can be used by
-          declaring them as booleans, i. e. <code>deflate = true;</code>.
+          declaring them as booleans, i. e. `deflate = true;`.
         '';
         default = { };
         example = {

nixos/modules/services/networking/openvpn.nix

@@ -115,12 +115,12 @@ in
         }
       '';
 
-      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>,
+        `openvpn-«name».service`,
-        where <replaceable>name</replaceable> is the corresponding
+        where «name» is the corresponding
         attribute name.
       '';
 

nixos/modules/services/networking/pleroma.nix

@@ -34,7 +34,7 @@ in {
 
       configs = mkOption {
         type = with types; listOf str;
-        description = ''
+        description = lib.mdDoc ''
           Pleroma public configuration.
 
           This list gets appended from left to
@@ -42,9 +42,9 @@ in {
           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
+          *DO NOT STORE ANY PLEROMA SECRET
-          HERE</emphasis>, use
+          HERE*, use
-          <link linkend="opt-services.pleroma.secretConfigFile">services.pleroma.secretConfigFile</link>
+          [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

@@ -133,7 +133,7 @@ in {
       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

@@ -257,12 +257,12 @@ in
       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"/>
+          keys, you can generally use [](#opt-users.users._name_.openssh.authorizedKeys.keys)
-          or <xref linkend="opt-users.users._name_.openssh.authorizedKeys.keyFiles"/>.
+          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.
@@ -298,14 +298,13 @@ in
           "curve25519-sha256@libssh.org"
           "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>
         '';
       };
 
@@ -319,14 +318,13 @@ in
           "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>
         '';
       };
 
@@ -340,14 +338,13 @@ in
           "hmac-sha2-256"
           "umac-128@openssh.com"
         ];
-        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>
         '';
       };