nixos/manual: generate module chapters with md-to-db.sh

nixos/doc/manual/md-to-db.sh

···
 done
 
 popd
+
+# now handle module chapters. we'll need extra checks to ensure that we don't process
+# markdown files we're not interested in, so we'll require an x.nix file for ever x.md
+# that we'll convert to xml.
+pushd "$DIR/../../modules"
+
+mapfile -t MD_FILES < <(find . -type f -regex '.*\.md$')
+
+for mf in ${MD_FILES[*]}; do
+  [ -f "${mf%.md}.nix" ] || continue
+
+  pandoc --top-level-division=chapter "$mf" "${pandoc_flags[@]}" -o "${mf%.md}.xml"
+done
+
+popd

nixos/modules/i18n/input-method/default.nix

···
 
   meta = {
     maintainers = with lib.maintainers; [ ericsagnes ];
-    # Don't edit the docbook xml directly, edit the md and generate it:
-    # `pandoc default.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > default.xml`
+    # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
     doc = ./default.xml;
   };
 

nixos/modules/i18n/input-method/default.xml

···
 };
 </programlisting>
     <para>
-      Note: The <xref linkend="opt-i18n.inputMethod.uim.toolbar"></xref>
+      Note: The <xref linkend="opt-i18n.inputMethod.uim.toolbar" />
       option can be used to choose uim toolbar.
     </para>
   </section>

nixos/modules/programs/digitalbitbox/default.nix

···
   };
 
   meta = {
-    # Don't edit the docbook xml directly, edit the md and generate it:
-    # `pandoc doc.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart > doc.xml`
-    doc = ./doc.xml;
+    # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
+    doc = ./default.xml;
     maintainers = with lib.maintainers; [ vidbina ];
   };
 }

nixos/modules/programs/digitalbitbox/doc.xml nixos/modules/programs/digitalbitbox/default.xml

···
 </programlisting>
   <para>
     and bundles the <literal>digitalbitbox</literal> package (see
-    <xref linkend="sec-digitalbitbox-package"></xref>), which contains
-    the <literal>dbb-app</literal> and <literal>dbb-cli</literal>
-    binaries, along with the hardware module (see
-    <xref linkend="sec-digitalbitbox-hardware-module"></xref>) which
-    sets up the necessary udev rules to access the device.
+    <xref linkend="sec-digitalbitbox-package" />), which contains the
+    <literal>dbb-app</literal> and <literal>dbb-cli</literal> binaries,
+    along with the hardware module (see
+    <xref linkend="sec-digitalbitbox-hardware-module" />) which sets up
+    the necessary udev rules to access the device.
   </para>
   <para>
     Enabling the digitalbitbox module is pretty much the easiest way to
···
   </para>
   <para>
     For more information, see
-    <link xlink:href="https://digitalbitbox.com/start_linux" role="uri">https://digitalbitbox.com/start_linux</link>.
+    <link xlink:href="https://digitalbitbox.com/start_linux">https://digitalbitbox.com/start_linux</link>.
   </para>
   <section xml:id="sec-digitalbitbox-package">
     <title>Package</title>

nixos/modules/programs/plotinus.nix

···
 {
   meta = {
     maintainers = pkgs.plotinus.meta.maintainers;
-    # Don't edit the docbook xml directly, edit the md and generate it:
-    # `pandoc plotinus.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > plotinus.xml`
+    # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
     doc = ./plotinus.xml;
   };
 

nixos/modules/programs/plotinus.xml

···
   </para>
   <para>
     <emphasis>Upstream documentation:</emphasis>
-    <link xlink:href="https://github.com/p-e-w/plotinus" role="uri">https://github.com/p-e-w/plotinus</link>
+    <link xlink:href="https://github.com/p-e-w/plotinus">https://github.com/p-e-w/plotinus</link>
   </para>
   <para>
     Plotinus is a searchable command palette in every modern GTK

nixos/modules/programs/zsh/oh-my-zsh.nix

···
 
     };
 
-    # Don't edit the docbook xml directly, edit the md and generate it:
-    # `pandoc oh-my-zsh.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > oh-my-zsh.xml`
+    # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
     meta.doc = ./oh-my-zsh.xml;
   }

nixos/modules/programs/zsh/oh-my-zsh.xml

···
   <section xml:id="module-programs-oh-my-zsh-packaging-customizations">
     <title>Package your own customizations</title>
     <para>
-      If third-party customizations (e.g. new themes) are supposed to be
+      If third-party customizations (e.g. new themes) are supposed to be
       added to <literal>oh-my-zsh</literal> there are several pitfalls
       to keep in mind:
     </para>

nixos/modules/security/acme/default.nix

···
 
   meta = {
     maintainers = lib.teams.acme.members;
-    # Don't edit the docbook xml directly, edit the md and generate it:
-    # `pandoc doc.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > doc.xml`
-    doc = ./doc.xml;
+    # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
+    doc = ./default.xml;
   };
 }

nixos/modules/security/acme/doc.xml nixos/modules/security/acme/default.xml

···
     <para>
       To use the ACME module, you must accept the provider’s terms of
       service by setting
-      <xref linkend="opt-security.acme.acceptTerms"></xref> to
+      <xref linkend="opt-security.acme.acceptTerms" /> to
       <literal>true</literal>. The Let’s Encrypt ToS can be found
       <link xlink:href="https://letsencrypt.org/repository/">here</link>.
     </para>
     <para>
       You must also set an email address to be used when creating
       accounts with Let’s Encrypt. You can set this for all certs with
-      <xref linkend="opt-security.acme.defaults.email"></xref> and/or on
-      a per-cert basis with
-      <xref linkend="opt-security.acme.certs._name_.email"></xref>. This
+      <xref linkend="opt-security.acme.defaults.email" /> and/or on a
+      per-cert basis with
+      <xref linkend="opt-security.acme.certs._name_.email" />. This
       address is only used for registration and renewal reminders, and
       cannot be used to administer the certificates in any way.
     </para>
     <para>
       Alternatively, you can use a different ACME server by changing the
-      <xref linkend="opt-security.acme.defaults.server"></xref> option
-      to a provider of your choosing, or just change the server for one
-      cert with
-      <xref linkend="opt-security.acme.certs._name_.server"></xref>.
+      <xref linkend="opt-security.acme.defaults.server" /> option to a
+      provider of your choosing, or just change the server for one cert
+      with <xref linkend="opt-security.acme.certs._name_.server" />.
     </para>
     <para>
       You will need an HTTP server or DNS server for verification. For
···
       <filename>/var/lib/acme/foo.example.com</filename>.
     </para>
     <para>
-      Refer to <xref linkend="ch-options"></xref> for all available
+      Refer to <xref linkend="ch-options" /> for all available
       configuration options for the
       <link linkend="opt-security.acme.certs">security.acme</link>
       module.
···
     <para>
       You must follow the guide above on configuring DNS-01 validation
       first, however instead of setting the options for one certificate
-      (e.g. <xref linkend="opt-security.acme.certs._name_.dnsProvider"></xref>)
-      you will set them as defaults
-      (e.g. <xref linkend="opt-security.acme.defaults.dnsProvider"></xref>).
+      (e.g.
+      <xref linkend="opt-security.acme.certs._name_.dnsProvider" />) you
+      will set them as defaults (e.g.
+      <xref linkend="opt-security.acme.defaults.dnsProvider" />).
     </para>
     <programlisting>
 # Configure ACME appropriately

nixos/modules/services/backup/borgbackup.nix

···
 
 in {
   meta.maintainers = with maintainers; [ dotlambda ];
-  # Don't edit the docbook xml directly, edit the md and generate it:
-  # `pandoc borgbackup.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > borgbackup.xml`
+  # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
   meta.doc = ./borgbackup.xml;
 
   ###### interface

nixos/modules/services/backup/borgbackup.xml

···
   </para>
   <para>
     <emphasis>Upstream documentation:</emphasis>
-    <link xlink:href="https://borgbackup.readthedocs.io/" role="uri">https://borgbackup.readthedocs.io/</link>
+    <link xlink:href="https://borgbackup.readthedocs.io/">https://borgbackup.readthedocs.io/</link>
   </para>
   <para>
     <link xlink:href="https://www.borgbackup.org/">BorgBackup</link>
···
       protect your data from disk failure, ransomware and theft.
     </para>
     <para>
-      It can be installed in NixOS e.g. by adding
+      It can be installed in NixOS e.g. by adding
       <literal>pkgs.vorta</literal> to
-      <xref linkend="opt-environment.systemPackages"></xref>.
+      <xref linkend="opt-environment.systemPackages" />.
     </para>
     <para>
       Details about using Vorta can be found under

nixos/modules/services/databases/foundationdb.nix

···
     };
   };
 
-  # Don't edit the docbook xml directly, edit the md and generate it:
-  # `pandoc foundationdb.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > foundationdb.xml`
+  # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
   meta.doc         = ./foundationdb.xml;
   meta.maintainers = with lib.maintainers; [ thoughtpolice ];
 }

nixos/modules/services/databases/foundationdb.xml

···
   </para>
   <para>
     <emphasis>Upstream documentation:</emphasis>
-    <link xlink:href="https://apple.github.io/foundationdb/" role="uri">https://apple.github.io/foundationdb/</link>
+    <link xlink:href="https://apple.github.io/foundationdb/">https://apple.github.io/foundationdb/</link>
   </para>
   <para>
     <emphasis>Maintainer:</emphasis> Austin Seipp
···
       FoundationDB is a complex piece of software, and requires careful
       administration to properly use. Full documentation for
       administration can be found here:
-      <link xlink:href="https://apple.github.io/foundationdb/" role="uri">https://apple.github.io/foundationdb/</link>.
+      <link xlink:href="https://apple.github.io/foundationdb/">https://apple.github.io/foundationdb/</link>.
     </para>
   </section>
 </chapter>

nixos/modules/services/databases/postgresql.nix

···
 
   };
 
-  # Don't edit the docbook xml directly, edit the md and generate it:
-  # `pandoc postgresql.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > postgresql.xml`
+  # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
   meta.doc = ./postgresql.xml;
   meta.maintainers = with lib.maintainers; [ thoughtpolice danbst ];
 }

nixos/modules/services/databases/postgresql.xml

···
   </para>
   <para>
     <emphasis>Upstream documentation:</emphasis>
-    <link xlink:href="http://www.postgresql.org/docs/" role="uri">http://www.postgresql.org/docs/</link>
+    <link xlink:href="http://www.postgresql.org/docs/">http://www.postgresql.org/docs/</link>
   </para>
   <para>
-    PostgreSQL is an advanced, free relational database. <!-- MORE -->
+    PostgreSQL is an advanced, free relational database.
   </para>
   <section xml:id="module-services-postgres-configuring">
     <title>Configuring</title>
···
 </programlisting>
     <para>
       Note that you are required to specify the desired version of
-      PostgreSQL (e.g. <literal>pkgs.postgresql_11</literal>). Since
+      PostgreSQL (e.g. <literal>pkgs.postgresql_11</literal>). Since
       upgrading your PostgreSQL version requires a database dump and
       reload (see below), NixOS cannot provide a default value for
-      <xref linkend="opt-services.postgresql.package"></xref> such as
-      the most recent release of PostgreSQL.
+      <xref linkend="opt-services.postgresql.package" /> such as the
+      most recent release of PostgreSQL.
     </para>
     <para>
       By default, PostgreSQL stores its databases in
       <filename>/var/lib/postgresql/$psqlSchema</filename>. You can
       override this using
-      <xref linkend="opt-services.postgresql.dataDir"></xref>, e.g.
+      <xref linkend="opt-services.postgresql.dataDir" />, e.g.
     </para>
     <programlisting>
 services.postgresql.dataDir = &quot;/data/postgresql&quot;;
···
           the new one. You may supply arguments like
           <literal>--jobs 4</literal> and <literal>--link</literal> to
           speedup migration process. See
-          <link xlink:href="https://www.postgresql.org/docs/current/pgupgrade.html" role="uri">https://www.postgresql.org/docs/current/pgupgrade.html</link>
+          <link xlink:href="https://www.postgresql.org/docs/current/pgupgrade.html">https://www.postgresql.org/docs/current/pgupgrade.html</link>
           for details.
         </para>
       </listitem>
···
         <para>
           Change postgresql package in NixOS configuration to the one
           you were upgrading to via
-          <xref linkend="opt-services.postgresql.package"></xref>.
-          Rebuild NixOS. This should start new postgres using upgraded
-          data directory and all services you stopped during the
-          upgrade.
+          <xref linkend="opt-services.postgresql.package" />. Rebuild
+          NixOS. This should start new postgres using upgraded data
+          directory and all services you stopped during the upgrade.
         </para>
       </listitem>
       <listitem>
···
             <para>
               For PostgreSQL &lt; 14, run (as
               <literal>su -l postgres</literal> in the
-              <xref linkend="opt-services.postgresql.dataDir"></xref>,
-              in this example
-              <filename>/var/lib/postgresql/13</filename>):
+              <xref linkend="opt-services.postgresql.dataDir" />, in
+              this example <filename>/var/lib/postgresql/13</filename>):
             </para>
             <programlisting>
 $ ./analyze_new_cluster.sh

nixos/modules/services/desktops/flatpak.nix

···
   cfg = config.services.flatpak;
 in {
   meta = {
-    # Don't edit the docbook xml directly, edit the md and generate it:
-    # `pandoc flatpak.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > flatpak.xml`
+    # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
     doc = ./flatpak.xml;
     maintainers = pkgs.flatpak.meta.maintainers;
   };

nixos/modules/services/desktops/flatpak.xml

···
   </para>
   <para>
     <emphasis>Upstream documentation:</emphasis>
-    <link xlink:href="https://github.com/flatpak/flatpak/wiki" role="uri">https://github.com/flatpak/flatpak/wiki</link>
+    <link xlink:href="https://github.com/flatpak/flatpak/wiki">https://github.com/flatpak/flatpak/wiki</link>
   </para>
   <para>
     Flatpak is a system for building, distributing, and running

nixos/modules/services/development/blackfire.nix

···
 in {
   meta = {
     maintainers = pkgs.blackfire.meta.maintainers;
-    # Don't edit the docbook xml directly, edit the md and generate it:
-    # `pandoc blackfire.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > blackfire.xml`
+    # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
     doc = ./blackfire.xml;
   };
 

nixos/modules/services/development/blackfire.xml

···
   </para>
   <para>
     <emphasis>Upstream documentation:</emphasis>
-    <link xlink:href="https://blackfire.io/docs/introduction" role="uri">https://blackfire.io/docs/introduction</link>
+    <link xlink:href="https://blackfire.io/docs/introduction">https://blackfire.io/docs/introduction</link>
   </para>
   <para>
     <link xlink:href="https://blackfire.io">Blackfire</link> is a

nixos/modules/services/editors/emacs.nix

···
     environment.variables.EDITOR = mkIf cfg.defaultEditor (mkOverride 900 "${editorScript}/bin/emacseditor");
   };
 
-  # Don't edit the docbook xml directly, edit the md and generate it:
-  # `pandoc emacs.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > emacs.xml`
+  # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
   meta.doc = ./emacs.xml;
 }

nixos/modules/services/editors/emacs.xml

···
   <para>
     Emacs runs within a graphical desktop environment using the X Window
     System, but works equally well on a text terminal. Under macOS, a
-    &quot;Mac port&quot; edition is available, which uses Apple's native
-    GUI frameworks.
+    <quote>Mac port</quote> edition is available, which uses Apple’s
+    native GUI frameworks.
   </para>
   <para>
-    Nixpkgs provides a superior environment for running Emacs. It's
+    Nixpkgs provides a superior environment for running Emacs. It’s
     simple to create custom builds by overriding the default packages.
     Chaotic collections of Emacs Lisp code and extensions can be brought
     under control using declarative package management. NixOS even
···
     <title>Installing Emacs</title>
     <para>
       Emacs can be installed in the normal way for Nix (see
-      <xref linkend="sec-package-management"></xref>). In addition, a
-      NixOS <emphasis>service</emphasis> can be enabled.
+      <xref linkend="sec-package-management" />). In addition, a NixOS
+      <emphasis>service</emphasis> can be enabled.
     </para>
     <section xml:id="module-services-emacs-releases">
       <title>The Different Releases of Emacs</title>
···
           </term>
           <listitem>
             <para>
-              Emacs with the &quot;Mac port&quot; patches, providing a
-              more native look and feel under macOS.
+              Emacs with the <quote>Mac port</quote> patches, providing
+              a more native look and feel under macOS.
             </para>
           </listitem>
         </varlistentry>
       </variablelist>
       <para>
-        If those aren't suitable, then the following imitation Emacs
+        If those aren’t suitable, then the following imitation Emacs
         editors are also available in Nixpkgs:
         <link xlink:href="https://www.gnu.org/software/zile/">Zile</link>,
         <link xlink:href="http://homepage.boetes.org/software/mg/">mg</link>,
···
       <para>
         If you are on NixOS, you can install this particular Emacs for
         all users by adding it to the list of system packages (see
-        <xref linkend="sec-declarative-package-mgmt"></xref>). Simply
-        modify your file <filename>configuration.nix</filename> to make
-        it contain:
+        <xref linkend="sec-declarative-package-mgmt" />). Simply modify
+        your file <filename>configuration.nix</filename> to make it
+        contain:
         <anchor xml:id="module-services-emacs-configuration-nix" />
       </para>
       <programlisting>
···
         In this case, the next <command>nixos-rebuild switch</command>
         will take care of adding your <command>emacs</command> to the
         <varname>PATH</varname> environment variable (see
-        <xref linkend="sec-changing-config"></xref>).
+        <xref linkend="sec-changing-config" />).
       </para>
       <para>
         If you are not on NixOS or want to install this particular Emacs
···
       NixOS provides an optional <command>systemd</command> service
       which launches
       <link xlink:href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html">Emacs
-      daemon</link> with the user's login session.
+      daemon</link> with the user’s login session.
     </para>
     <para>
       <emphasis>Source:</emphasis>
···
         <literal>emacsWithPackages</literal>.
       </para>
       <para>
-        Ensure that the Emacs server is enabled for your user's Emacs
+        Ensure that the Emacs server is enabled for your user’s Emacs
         configuration, either by customizing the
         <varname>server-mode</varname> variable, or by adding
         <literal>(server-start)</literal> to
···
     <section xml:id="module-services-emacs-editor-variable">
       <title>Configuring the <varname>EDITOR</varname> variable</title>
       <para>
-        If <xref linkend="opt-services.emacs.defaultEditor"></xref> is
+        If <xref linkend="opt-services.emacs.defaultEditor" /> is
         <literal>true</literal>, the <varname>EDITOR</varname> variable
         will be set to a wrapper script which launches
         <command>emacsclient</command>.
···
       <para>
         To install the DocBook 5.0 schemas, either add
         <varname>pkgs.docbook5</varname> to
-        <xref linkend="opt-environment.systemPackages"></xref>
+        <xref linkend="opt-environment.systemPackages" />
         (<link linkend="sec-declarative-package-mgmt">NixOS</link>), or
         run <literal>nix-env -f '&lt;nixpkgs&gt;' -iA docbook5</literal>
         (<link linkend="sec-ad-hoc-packages">Nix</link>).

nixos/modules/services/hardware/trezord.nix

···
   ### docs
 
   meta = {
-    # Don't edit the docbook xml directly, edit the md and generate it:
-    # `pandoc trezord.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > trezord.xml`
+    # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
     doc = ./trezord.xml;
   };
 

nixos/modules/services/hardware/trezord.xml

···
     <link xlink:href="https://wiki.trezor.io/GPG">GPG</link> and a
     <link xlink:href="https://wiki.trezor.io/Trezor_Password_Manager">password
     manager</link>. For more information, guides and documentation, see
-    <link xlink:href="https://wiki.trezor.io" role="uri">https://wiki.trezor.io</link>.
+    <link xlink:href="https://wiki.trezor.io">https://wiki.trezor.io</link>.
   </para>
   <para>
     To enable Trezor support, add the following to your

nixos/modules/services/mail/mailman.nix

···
 
   meta = {
     maintainers = with lib.maintainers; [ lheckemann qyliss ma27 ];
-    # Don't edit the docbook xml directly, edit the md and generate it:
-    # `pandoc mailman.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > mailman.xml`
+    # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
     doc = ./mailman.xml;
   };
 

nixos/modules/services/matrix/mjolnir.nix

···
   };
 
   meta = {
-    # Don't edit the docbook xml directly, edit the md and generate it:
-    # `pandoc mjolnir.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > mjolnir.xml`
+    # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
     doc = ./mjolnir.xml;
     maintainers = with maintainers; [ jojosch ];
   };

nixos/modules/services/matrix/synapse.nix

···
 
   meta = {
     buildDocsInSandbox = false;
-    # Don't edit the docbook xml directly, edit the md and generate it:
-    # `pandoc synapse.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > synapse.xml`
+    # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
     doc = ./synapse.xml;
     maintainers = teams.matrix.members;
   };

nixos/modules/services/matrix/synapse.xml

···
       <literal>services.matrix-synapse.settings.enable_registration = true;</literal>.
       Otherwise, or you can generate a registration secret with
       <command>pwgen -s 64 1</command> and set it with
-      <xref linkend="opt-services.matrix-synapse.settings.registration_shared_secret"></xref>.
+      <xref linkend="opt-services.matrix-synapse.settings.registration_shared_secret" />.
       To create a new user or admin, run the following after you have
       set the secret and have rebuilt NixOS:
     </para>
···
     <warning>
       <para>
         When using
-        <xref linkend="opt-services.matrix-synapse.settings.registration_shared_secret"></xref>,
+        <xref linkend="opt-services.matrix-synapse.settings.registration_shared_secret" />,
         the secret will end up in the world-readable store. Instead it’s
         recommended to deploy the secret in an additional file like
         this:
···
             <citerefentry><refentrytitle>nixops</refentrytitle><manvolnum>1</manvolnum></citerefentry>
             or
             <link xlink:href="https://github.com/Mic92/sops-nix/">sops-nix</link>
-            to
-            e.g. <filename>/run/secrets/matrix-shared-secret</filename>
-            and ensure that it’s readable by
+            to e.g.
+            <filename>/run/secrets/matrix-shared-secret</filename> and
+            ensure that it’s readable by
             <literal>matrix-synapse</literal>.
           </para>
         </listitem>
···
       <literal>https://element.myhostname.example.org</literal> and
       <literal>https://element.example.org</literal>. Alternatively, you
       can use the hosted copy at
-      <link xlink:href="https://app.element.io/" role="uri">https://app.element.io/</link>,
+      <link xlink:href="https://app.element.io/">https://app.element.io/</link>,
       or use other web clients or native client applications. Due to the
       <literal>/.well-known</literal> urls set up done above, many
       clients should fill in the required connection details

nixos/modules/services/misc/gitlab.nix

···
 
   };
 
-  # Don't edit the docbook xml directly, edit the md and generate it:
-  # `pandoc gitlab.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > gitlab.xml`
+  # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
   meta.doc = ./gitlab.xml;
 
 }

nixos/modules/services/misc/gitlab.xml

···
       enabled for fetching incoming mail.
     </para>
     <para>
-      Refer to <xref linkend="ch-options"></xref> for all available
+      Refer to <xref linkend="ch-options" /> for all available
       configuration options for the
       <link linkend="opt-services.gitlab.enable">services.gitlab</link>
       module.

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

···
     '')
   ];
 
-  # Don't edit the docbook xml directly, edit the md and generate it:
-  # `pandoc sourcehut.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > sourcehut.xml`
-  meta.doc = ./sourcehut.xml;
+  # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
+  meta.doc = ./default.xml;
   meta.maintainers = with maintainers; [ tomberek ];
 }

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

···
     </para>
   </section>
   <section xml:id="module-services-sourcehut-httpd">
-    <title>Using an alternative webserver as reverse-proxy
-    (e.g. <literal>httpd</literal>)</title>
+    <title>Using an alternative webserver as reverse-proxy (e.g.
+    <literal>httpd</literal>)</title>
     <para>
       By default, <literal>nginx</literal> is used as reverse-proxy for
-      <literal>sourcehut</literal>. However, it’s possible to use
-      e.g. <literal>httpd</literal> by explicitly disabling
+      <literal>sourcehut</literal>. However, it’s possible to use e.g.
+      <literal>httpd</literal> by explicitly disabling
       <literal>nginx</literal> using
-      <xref linkend="opt-services.nginx.enable"></xref> and fixing the
+      <xref linkend="opt-services.nginx.enable" /> and fixing the
       <literal>settings</literal>.
     </para>
   </section>

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

···
     })
   ];
 
-  # Don't edit the docbook xml directly, edit the md and generate it:
-  # `pandoc doc.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > doc.xml`
-  meta.doc = ./doc.xml;
+  # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
+  meta.doc = ./default.xml;
 }

nixos/modules/services/misc/taskserver/doc.xml nixos/modules/services/misc/taskserver/default.xml

···
   </para>
   <para>
     <emphasis>Upstream documentation:</emphasis>
-    <link xlink:href="https://taskwarrior.org/docs/#taskd" role="uri">https://taskwarrior.org/docs/#taskd</link>
+    <link xlink:href="https://taskwarrior.org/docs/#taskd">https://taskwarrior.org/docs/#taskd</link>
   </para>
   <section xml:id="module-services-taskserver-configuration">
     <title>Configuration</title>
···
       imperatively, the <command>nixos-taskserver</command> tool is used
       for addition and deletion of organisations along with users and
       groups defined by
-      <xref linkend="opt-services.taskserver.organisations"></xref> and
-      as well for imperative set up.
+      <xref linkend="opt-services.taskserver.organisations" /> and as
+      well for imperative set up.
     </para>
     <para>
       The tool is designed to not interfere if the command is used to

nixos/modules/services/misc/weechat.nix

···
       };
   };
 
-  # Don't edit the docbook xml directly, edit the md and generate it:
-  # `pandoc weechat.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > weechat.xml`
+  # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
   meta.doc = ./weechat.xml;
 }

nixos/modules/services/monitoring/parsedmarc.md

···
 Note that GeoIP provisioning is disabled in the example for
 simplicity, but should be turned on for fully functional reports.
 
-## Local mail
+## Local mail {#module-services-parsedmarc-local-mail}
 Instead of watching an external inbox, a local inbox can be
 automatically provisioned. The recipient's name is by default set to
 `dmarc`, but can be configured in
···
 };
 ```
 
-## Grafana and GeoIP
+## Grafana and GeoIP {#module-services-parsedmarc-grafana-geoip}
 The reports can be visualized and summarized with parsedmarc's
 official Grafana dashboard. For all views to work, and for the data to
 be complete, GeoIP databases are also required. The following example

nixos/modules/services/monitoring/parsedmarc.nix

···
     };
   };
 
-  # Don't edit the docbook xml directly, edit the md and generate it:
-  # `pandoc parsedmarc.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart > parsedmarc.xml`
+  # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
   meta.doc = ./parsedmarc.xml;
   meta.maintainers = [ lib.maintainers.talyz ];
 }

nixos/modules/services/monitoring/parsedmarc.xml

···
       simplicity, but should be turned on for fully functional reports.
     </para>
   </section>
-  <section xml:id="local-mail">
+  <section xml:id="module-services-parsedmarc-local-mail">
     <title>Local mail</title>
     <para>
       Instead of watching an external inbox, a local inbox can be
···
 };
 </programlisting>
   </section>
-  <section xml:id="grafana-and-geoip">
+  <section xml:id="module-services-parsedmarc-grafana-geoip">
     <title>Grafana and GeoIP</title>
     <para>
       The reports can be visualized and summarized with parsedmarc’s

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

···
   );
 
   meta = {
-    # Don't edit the docbook xml directly, edit the md and generate it:
-    # `pandoc exporters.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > exporters.xml`
+    # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
     doc = ./exporters.xml;
     maintainers = [ maintainers.willibutz ];
   };

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

···
     users.groups.litestream = {};
   };
 
-  # Don't edit the docbook xml directly, edit the md and generate it:
-  # `pandoc litestream.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > litestream.xml`
-  meta.doc = ./litestream.xml;
+  # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
+  meta.doc = ./default.xml;
 }

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

···
 
   meta = {
     maintainers = with lib.maintainers; [ pennae ];
-    # Don't edit the docbook xml directly, edit the md and generate it:
-    # `pandoc firefox-syncserver.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart > firefox-syncserver.xml`
+    # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
     doc = ./firefox-syncserver.xml;
   };
 }

nixos/modules/services/networking/mosquitto.nix

···
 
   meta = {
     maintainers = with lib.maintainers; [ pennae ];
-    # Don't edit the docbook xml directly, edit the md and generate it:
-    # `pandoc mosquitto.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart > mosquitto.xml`
+    # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
     doc = ./mosquitto.xml;
   };
 }

nixos/modules/services/networking/pleroma.nix

···
 
   };
   meta.maintainers = with lib.maintainers; [ ninjatrappeur ];
-  # Don't edit the docbook xml directly, edit the md and generate it:
-  # `pandoc pleroma.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > pleroma.xml`
+  # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
   meta.doc = ./pleroma.xml;
 }

nixos/modules/services/networking/pleroma.xml

···
     </para>
     <para>
       This is an example of configuration, where
-      <xref linkend="opt-services.pleroma.configs"></xref> option
-      contains the content of the file <literal>config.exs</literal>,
-      generated
+      <xref linkend="opt-services.pleroma.configs" /> option contains
+      the content of the file <literal>config.exs</literal>, generated
       <link linkend="module-services-pleroma-generate-config">in the
       first section</link>, but with the secrets (database password,
       endpoint secret key, salts, etc.) removed. Removing secrets is
···
 </programlisting>
     <para>
       Secrets must be moved into a file pointed by
-      <xref linkend="opt-services.pleroma.secretConfigFile"></xref>, in
-      our case <literal>/var/lib/pleroma/secrets.exs</literal>. This
-      file can be created copying the previously generated
+      <xref linkend="opt-services.pleroma.secretConfigFile" />, in our
+      case <literal>/var/lib/pleroma/secrets.exs</literal>. This file
+      can be created copying the previously generated
       <literal>config.exs</literal> file and then removing all the
       settings, except the secrets. This is an example
     </para>
···
 </programlisting>
     <para>
       Note that the lines of the same configuration group are comma
-      separated (i.e. all the lines end with a comma, except the last
+      separated (i.e. all the lines end with a comma, except the last
       one), so when the lines with passwords are added or removed,
       commas must be adjusted accordingly.
     </para>
···
 </programlisting>
     <para>
       and then accessing
-      <link xlink:href="http://localhost:4000" role="uri">http://localhost:4000</link>
+      <link xlink:href="http://localhost:4000">http://localhost:4000</link>
       from a web browser.
     </para>
   </section>

nixos/modules/services/networking/prosody.nix

···
 
   };
 
-  # Don't edit the docbook xml directly, edit the md and generate it:
-  # `pandoc prosody.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > prosody.xml`
+  # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
   meta.doc = ./prosody.xml;
 }

nixos/modules/services/networking/yggdrasil.nix

···
     environment.systemPackages = [ cfg.package ];
   });
   meta = {
-    # Don't edit the docbook xml directly, edit the md and generate it:
-    # `pandoc yggdrasil.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > yggdrasil.xml`
+    # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
     doc = ./yggdrasil.xml;
     maintainers = with lib.maintainers; [ gazally ehmry ];
   };

nixos/modules/services/networking/yggdrasil.xml

···
   </para>
   <para>
     <emphasis>Upstream documentation:</emphasis>
-    <link xlink:href="https://yggdrasil-network.github.io/" role="uri">https://yggdrasil-network.github.io/</link>
+    <link xlink:href="https://yggdrasil-network.github.io/">https://yggdrasil-network.github.io/</link>
   </para>
   <para>
     Yggdrasil is an early-stage implementation of a fully end-to-end

nixos/modules/services/search/meilisearch.nix

···
 {
 
   meta.maintainers = with maintainers; [ Br1ght0ne happysalada ];
-  # Don't edit the docbook xml directly, edit the md and generate it:
-  # `pandoc meilisearch.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart > meilisearch.xml`
+  # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
   meta.doc = ./meilisearch.xml;
 
   ###### interface

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

···
     ];
   };
 
-  # Don't edit the docbook xml directly, edit the md and generate it:
-  # `pandoc discourse.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > discourse.xml`
+  # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
   meta.doc = ./discourse.xml;
   meta.maintainers = [ lib.maintainers.talyz ];
 }

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

···
     <title>Using a regular TLS certificate</title>
     <para>
       To set up TLS using a regular certificate and key on file, use the
-      <xref linkend="opt-services.discourse.sslCertificate"></xref> and
-      <xref linkend="opt-services.discourse.sslCertificateKey"></xref>
+      <xref linkend="opt-services.discourse.sslCertificate" /> and
+      <xref linkend="opt-services.discourse.sslCertificateKey" />
       options:
     </para>
     <programlisting>
···
     <para>
       Discourse uses PostgreSQL to store most of its data. A database
       will automatically be enabled and a database and role created
-      unless
-      <xref linkend="opt-services.discourse.database.host"></xref> is
+      unless <xref linkend="opt-services.discourse.database.host" /> is
       changed from its default of <literal>null</literal> or
-      <xref linkend="opt-services.discourse.database.createLocally"></xref>
+      <xref linkend="opt-services.discourse.database.createLocally" />
       is set to <literal>false</literal>.
     </para>
     <para>
       External database access can also be configured by setting
-      <xref linkend="opt-services.discourse.database.host"></xref>,
-      <xref linkend="opt-services.discourse.database.username"></xref>
-      and
-      <xref linkend="opt-services.discourse.database.passwordFile"></xref>
-      as appropriate. Note that you need to manually create a database
+      <xref linkend="opt-services.discourse.database.host" />,
+      <xref linkend="opt-services.discourse.database.username" /> and
+      <xref linkend="opt-services.discourse.database.passwordFile" /> as
+      appropriate. Note that you need to manually create a database
       called <literal>discourse</literal> (or the name you chose in
-      <xref linkend="opt-services.discourse.database.name"></xref>) and
-      allow the configured database user full access to it.
+      <xref linkend="opt-services.discourse.database.name" />) and allow
+      the configured database user full access to it.
     </para>
   </section>
   <section xml:id="module-services-discourse-mail">
···
       If you want to use a different domain for your outgoing email (for
       example <literal>example.com</literal> instead of
       <literal>discourse.example.com</literal>) you should set
-      <xref linkend="opt-services.discourse.mail.notificationEmailAddress"></xref>
+      <xref linkend="opt-services.discourse.mail.notificationEmailAddress" />
       and
-      <xref linkend="opt-services.discourse.mail.contactEmailAddress"></xref>
+      <xref linkend="opt-services.discourse.mail.contactEmailAddress" />
       manually.
     </para>
     <note>
       <para>
         Setup of TLS for incoming email is currently only configured
-        automatically when a regular TLS certificate is used, i.e. when
-        <xref linkend="opt-services.discourse.sslCertificate"></xref>
-        and
-        <xref linkend="opt-services.discourse.sslCertificateKey"></xref>
-        are set.
+        automatically when a regular TLS certificate is used, i.e. when
+        <xref linkend="opt-services.discourse.sslCertificate" /> and
+        <xref linkend="opt-services.discourse.sslCertificateKey" /> are
+        set.
       </para>
     </note>
   </section>
···
     <para>
       Additional site settings and backend settings, for which no
       explicit NixOS options are provided, can be set in
-      <xref linkend="opt-services.discourse.siteSettings"></xref> and
-      <xref linkend="opt-services.discourse.backendSettings"></xref>
+      <xref linkend="opt-services.discourse.siteSettings" /> and
+      <xref linkend="opt-services.discourse.backendSettings" />
       respectively.
     </para>
     <section xml:id="module-services-discourse-site-settings">
···
         <quote>Site settings</quote> are the settings that can be
         changed through the Discourse UI. Their
         <emphasis>default</emphasis> values can be set using
-        <xref linkend="opt-services.discourse.siteSettings"></xref>.
+        <xref linkend="opt-services.discourse.siteSettings" />.
       </para>
       <para>
         Settings are expressed as a Nix attribute set which matches the
         structure of the configuration in
         <link xlink:href="https://github.com/discourse/discourse/blob/master/config/site_settings.yml">config/site_settings.yml</link>.
         To find a setting’s path, you only need to care about the first
-        two levels; i.e. its category (e.g. <literal>login</literal>)
-        and name (e.g. <literal>invite_only</literal>).
+        two levels; i.e. its category (e.g. <literal>login</literal>)
+        and name (e.g. <literal>invite_only</literal>).
       </para>
       <para>
         Settings containing secret data should be set to an attribute
···
     <title>Plugins</title>
     <para>
       You can install Discourse plugins using the
-      <xref linkend="opt-services.discourse.plugins"></xref> option.
+      <xref linkend="opt-services.discourse.plugins" /> option.
       Pre-packaged plugins are provided in
       <literal>&lt;your_discourse_package_here&gt;.plugins</literal>. If
       you want the full suite of plugins provided through
       <literal>nixpkgs</literal>, you can also set the
-      <xref linkend="opt-services.discourse.package"></xref> option to
+      <xref linkend="opt-services.discourse.package" /> option to
       <literal>pkgs.discourseAllPlugins</literal>.
     </para>
     <para>
···
       Some plugins provide
       <link linkend="module-services-discourse-site-settings">site
       settings</link>. Their defaults can be configured using
-      <xref linkend="opt-services.discourse.siteSettings"></xref>, just
-      like regular site settings. To find the names of these settings,
-      look in the <literal>config/settings.yml</literal> file of the
-      plugin repo.
+      <xref linkend="opt-services.discourse.siteSettings" />, just like
+      regular site settings. To find the names of these settings, look
+      in the <literal>config/settings.yml</literal> file of the plugin
+      repo.
     </para>
     <para>
       For example, to add the

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

···
 
   meta = {
     maintainers = with maintainers; [ ma27 ];
-    # Don't edit the docbook xml directly, edit the md and generate it:
-    # `pandoc grocy.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > grocy.xml`
+    # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
     doc = ./grocy.xml;
   };
 }

nixos/modules/services/web-apps/jitsi-meet.nix

···
     };
   };
 
-  # Don't edit the docbook xml directly, edit the md and generate it:
-  # `pandoc jitsi-meet.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > jitsi-meet.xml`
+  # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
   meta.doc = ./jitsi-meet.xml;
   meta.maintainers = lib.teams.jitsi.members;
 }

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

···
           mkIf createLocalMySQL (mkDefault dbPkg);
       };
 
-  # Don't edit the docbook xml directly, edit the md and generate it:
-  # `pandoc keycloak.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > keycloak.xml`
+  # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
   meta.doc = ./keycloak.xml;
   meta.maintainers = [ maintainers.talyz ];
 }

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

···
       An administrative user with the username <literal>admin</literal>
       is automatically created in the <literal>master</literal> realm.
       Its initial password can be configured by setting
-      <xref linkend="opt-services.keycloak.initialAdminPassword"></xref>
-      and defaults to <literal>changeme</literal>. The password is not
+      <xref linkend="opt-services.keycloak.initialAdminPassword" /> and
+      defaults to <literal>changeme</literal>. The password is not
       stored safely and should be changed immediately in the admin
       panel.
     </para>
···
     <para>
       Keycloak can be used with either PostgreSQL, MariaDB or MySQL.
       Which one is used can be configured in
-      <xref linkend="opt-services.keycloak.database.type"></xref>. The
+      <xref linkend="opt-services.keycloak.database.type" />. The
       selected database will automatically be enabled and a database and
       role created unless
-      <xref linkend="opt-services.keycloak.database.host"></xref> is
-      changed from its default of <literal>localhost</literal> or
-      <xref linkend="opt-services.keycloak.database.createLocally"></xref>
-      is set to <literal>false</literal>.
+      <xref linkend="opt-services.keycloak.database.host" /> is changed
+      from its default of <literal>localhost</literal> or
+      <xref linkend="opt-services.keycloak.database.createLocally" /> is
+      set to <literal>false</literal>.
     </para>
     <para>
       External database access can also be configured by setting
-      <xref linkend="opt-services.keycloak.database.host"></xref>,
-      <xref linkend="opt-services.keycloak.database.name"></xref>,
-      <xref linkend="opt-services.keycloak.database.username"></xref>,
-      <xref linkend="opt-services.keycloak.database.useSSL"></xref> and
-      <xref linkend="opt-services.keycloak.database.caCert"></xref> as
+      <xref linkend="opt-services.keycloak.database.host" />,
+      <xref linkend="opt-services.keycloak.database.name" />,
+      <xref linkend="opt-services.keycloak.database.username" />,
+      <xref linkend="opt-services.keycloak.database.useSSL" /> and
+      <xref linkend="opt-services.keycloak.database.caCert" /> as
       appropriate. Note that you need to manually create the database
       and allow the configured database user full access to it.
     </para>
     <para>
-      <xref linkend="opt-services.keycloak.database.passwordFile"></xref>
+      <xref linkend="opt-services.keycloak.database.passwordFile" />
       must be set to the path to a file containing the password used to
       log in to the database. If
-      <xref linkend="opt-services.keycloak.database.host"></xref> and
-      <xref linkend="opt-services.keycloak.database.createLocally"></xref>
+      <xref linkend="opt-services.keycloak.database.host" /> and
+      <xref linkend="opt-services.keycloak.database.createLocally" />
       are kept at their defaults, the database role
       <literal>keycloak</literal> with that password is provisioned on
       the local database instance.
···
     <para>
       The hostname is used to build the public URL used as base for all
       frontend requests and must be configured through
-      <xref linkend="opt-services.keycloak.settings.hostname"></xref>.
+      <xref linkend="opt-services.keycloak.settings.hostname" />.
     </para>
     <note>
       <para>
         If you’re migrating an old Wildfly based Keycloak instance and
         want to keep compatibility with your current clients, you’ll
         likely want to set
-        <xref linkend="opt-services.keycloak.settings.http-relative-path"></xref>
+        <xref linkend="opt-services.keycloak.settings.http-relative-path" />
         to <literal>/auth</literal>. See the option description for more
         details.
       </para>
     </note>
     <para>
-      <xref linkend="opt-services.keycloak.settings.hostname-strict-backchannel"></xref>
+      <xref linkend="opt-services.keycloak.settings.hostname-strict-backchannel" />
       determines whether Keycloak should force all requests to go
       through the frontend URL. By default, Keycloak allows backend
       requests to instead use its local hostname or IP address and may
···
       both
       <link xlink:href="https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail">PEM
       formatted</link>. Their paths should be set through
-      <xref linkend="opt-services.keycloak.sslCertificate"></xref> and
-      <xref linkend="opt-services.keycloak.sslCertificateKey"></xref>.
+      <xref linkend="opt-services.keycloak.sslCertificate" /> and
+      <xref linkend="opt-services.keycloak.sslCertificateKey" />.
     </para>
     <warning>
       <para>
···
     <title>Themes</title>
     <para>
       You can package custom themes and make them visible to Keycloak
-      through <xref linkend="opt-services.keycloak.themes"></xref>. See
-      the
+      through <xref linkend="opt-services.keycloak.themes" />. See the
       <link xlink:href="https://www.keycloak.org/docs/latest/server_development/#_themes">Themes
       section of the Keycloak Server Development Guide</link> and the
       description of the aforementioned NixOS option for more
···
     <title>Configuration file settings</title>
     <para>
       Keycloak server configuration parameters can be set in
-      <xref linkend="opt-services.keycloak.settings"></xref>. These
+      <xref linkend="opt-services.keycloak.settings" />. These
       correspond directly to options in
       <filename>conf/keycloak.conf</filename>. Some of the most
       important parameters are documented as suboptions, the rest can be
···
       containing the attribute <literal>_secret</literal> - a string
       pointing to a file containing the value the option should be set
       to. See the description of
-      <xref linkend="opt-services.keycloak.settings"></xref> for an
-      example.
+      <xref linkend="opt-services.keycloak.settings" /> for an example.
     </para>
   </section>
   <section xml:id="module-services-keycloak-example-config">

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

···
 in
 {
   meta.maintainers = with maintainers; [ happysalada ];
-  # Don't edit the docbook xml directly, edit the md and generate it:
-  # `pandoc lemmy.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart > lemmy.xml`
+  # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
   meta.doc = ./lemmy.xml;
 
   imports = [

nixos/modules/services/web-apps/matomo-doc.xml nixos/modules/services/web-apps/matomo.xml

···
       <literal>matomo</literal> database user (without needing a
       password), but no other users. For more information on
       passwordless login, see
-      <link xlink:href="https://mariadb.com/kb/en/mariadb/unix_socket-authentication-plugin/" role="uri">https://mariadb.com/kb/en/mariadb/unix_socket-authentication-plugin/</link>.
+      <link xlink:href="https://mariadb.com/kb/en/mariadb/unix_socket-authentication-plugin/">https://mariadb.com/kb/en/mariadb/unix_socket-authentication-plugin/</link>.
     </para>
     <para>
-      Of course, you can use password based authentication as well,
-      e.g. when the database is not on the same host.
+      Of course, you can use password based authentication as well, e.g.
+      when the database is not on the same host.
     </para>
   </section>
   <section xml:id="module-services-matomo-archive-processing">
···
       <filename>/var/lib/matomo/config/config.ini.php</filename> file.
       Use a user in the <literal>matomo</literal> group or root to
       access the file. For more information, see
-      <link xlink:href="https://matomo.org/faq/how-to-install/faq_138/" role="uri">https://matomo.org/faq/how-to-install/faq_138/</link>.
+      <link xlink:href="https://matomo.org/faq/how-to-install/faq_138/">https://matomo.org/faq/how-to-install/faq_138/</link>.
     </para>
   </section>
   <section xml:id="module-services-matomo-issues">

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

···
   };
 
   meta = {
-    # Don't edit the docbook xml directly, edit the md and generate it:
-    # `pandoc matomo-doc.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > matomo-doc.xml`
-    doc = ./matomo-doc.xml;
+    # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
+    doc = ./matomo.xml;
     maintainers = with lib.maintainers; [ florianjacob ];
   };
 }

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

···
     }
   ]);
 
-  # Don't edit the docbook xml directly, edit the md and generate it:
-  # `pandoc nextcloud.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > nextcloud.xml`
+  # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
   meta.doc = ./nextcloud.xml;
 }

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

···
           external storage such as S3. Please note that this won’t work
           anymore when using OpenSSL 3 for PHP’s openssl extension
           because this is implemented using the legacy cipher RC4. If
-          <xref linkend="opt-system.stateVersion"></xref> is
+          <xref linkend="opt-system.stateVersion" /> is
           <emphasis>above</emphasis> <literal>22.05</literal>, this is
           disabled by default. To turn it on again and for further
           information please refer to
-          <xref linkend="opt-services.nextcloud.enableBrokenCiphersForSSE"></xref>.
+          <xref linkend="opt-services.nextcloud.enableBrokenCiphersForSSE" />.
         </para>
       </listitem>
     </itemizedlist>
   </section>
   <section xml:id="module-services-nextcloud-httpd">
-    <title>Using an alternative webserver as reverse-proxy
-    (e.g. <literal>httpd</literal>)</title>
+    <title>Using an alternative webserver as reverse-proxy (e.g.
+    <literal>httpd</literal>)</title>
     <para>
       By default, <literal>nginx</literal> is used as reverse-proxy for
-      <literal>nextcloud</literal>. However, it’s possible to use
-      e.g. <literal>httpd</literal> by explicitly disabling
+      <literal>nextcloud</literal>. However, it’s possible to use e.g.
+      <literal>httpd</literal> by explicitly disabling
       <literal>nginx</literal> using
-      <xref linkend="opt-services.nginx.enable"></xref> and fixing the
+      <xref linkend="opt-services.nginx.enable" /> and fixing the
       settings <literal>listen.owner</literal> &amp;
       <literal>listen.group</literal> in the
       <link linkend="opt-services.phpfpm.pools">corresponding
···
       Nextcloud apps are installed statefully through the web interface.
       Some apps may require extra PHP extensions to be installed. This
       can be configured with the
-      <xref linkend="opt-services.nextcloud.phpExtraExtensions"></xref>
+      <xref linkend="opt-services.nextcloud.phpExtraExtensions" />
       setting.
     </para>
     <para>
       Alternatively, extra apps can also be declared with the
-      <xref linkend="opt-services.nextcloud.extraApps"></xref> setting.
-      When using this setting, apps can no longer be managed statefully
+      <xref linkend="opt-services.nextcloud.extraApps" /> setting. When
+      using this setting, apps can no longer be managed statefully
       because this can lead to Nextcloud updating apps that are managed
       by Nix. If you want automatic updates it is recommended that you
       use web interface to install apps.
···
       While minor and patch-level updates are no problem and can be done
       directly in the package-expression (and should be backported to
       supported stable branches after that), major-releases should be
-      added in a new attribute (e.g. Nextcloud
+      added in a new attribute (e.g. Nextcloud
       <literal>v19.0.0</literal> should be available in
       <literal>nixpkgs</literal> as
       <literal>pkgs.nextcloud19</literal>). To provide simple upgrade
···
 </programlisting>
     <para>
       Ideally we should make sure that it’s possible to jump two NixOS
-      versions forward: i.e. the warnings and the logic in the module
-      should guard a user to upgrade from a Nextcloud on e.g. 19.09 to a
+      versions forward: i.e. the warnings and the logic in the module
+      should guard a user to upgrade from a Nextcloud on e.g. 19.09 to a
       Nextcloud on 20.09.
     </para>
   </section>

nixos/modules/services/web-apps/pict-rs.nix

···
 in
 {
   meta.maintainers = with maintainers; [ happysalada ];
-  # Don't edit the docbook xml directly, edit the md and generate it:
-  # `pandoc pict-rs.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart > pict-rs.xml`
+  # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
   meta.doc = ./pict-rs.xml;
 
   options.services.pict-rs = {

nixos/modules/services/web-apps/pict-rs.xml

···
         <para>
           This endpoint returns the following JSON structure on success
           with a 201 Created status
-          <literal>json   {       &quot;files&quot;: [           {               &quot;delete_token&quot;: &quot;JFvFhqJA98&quot;,               &quot;file&quot;: &quot;lkWZDRvugm.jpg&quot;           },           {               &quot;delete_token&quot;: &quot;kAYy9nk2WK&quot;,               &quot;file&quot;: &quot;8qFS0QooAn.jpg&quot;           },           {               &quot;delete_token&quot;: &quot;OxRpM3sf0Y&quot;,               &quot;file&quot;: &quot;1hJaYfGE01.jpg&quot;           }       ],       &quot;msg&quot;: &quot;ok&quot;   }</literal>
         </para>
+        <programlisting language="json">
+{
+    &quot;files&quot;: [
+        {
+            &quot;delete_token&quot;: &quot;JFvFhqJA98&quot;,
+            &quot;file&quot;: &quot;lkWZDRvugm.jpg&quot;
+        },
+        {
+            &quot;delete_token&quot;: &quot;kAYy9nk2WK&quot;,
+            &quot;file&quot;: &quot;8qFS0QooAn.jpg&quot;
+        },
+        {
+            &quot;delete_token&quot;: &quot;OxRpM3sf0Y&quot;,
+            &quot;file&quot;: &quot;1hJaYfGE01.jpg&quot;
+        }
+    ],
+    &quot;msg&quot;: &quot;ok&quot;
+}
+</programlisting>
       </listitem>
       <listitem>
         <para>
···
           <literal>GET /image/details/original/{file}</literal> for
           getting the details of a full-resolution image. The returned
           JSON is structured like so:
-          <literal>json     {         &quot;width&quot;: 800,         &quot;height&quot;: 537,         &quot;content_type&quot;: &quot;image/webp&quot;,         &quot;created_at&quot;: [             2020,             345,             67376,             394363487         ]     }</literal>
         </para>
+        <programlisting language="json">
+{
+    &quot;width&quot;: 800,
+    &quot;height&quot;: 537,
+    &quot;content_type&quot;: &quot;image/webp&quot;,
+    &quot;created_at&quot;: [
+        2020,
+        345,
+        67376,
+        394363487
+    ]
+}
+</programlisting>
       </listitem>
       <listitem>
         <para>
···
         </para>
         <para>
           An example of usage could be
-          <literal>GET /image/process.jpg?src=asdf.png&amp;thumbnail=256&amp;blur=3.0</literal>
+        </para>
+        <programlisting>
+GET /image/process.jpg?src=asdf.png&amp;thumbnail=256&amp;blur=3.0
+</programlisting>
+        <para>
           which would create a 256x256px JPEG thumbnail and blur it
         </para>
       </listitem>

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

···
   };
 
   meta.maintainers = with maintainers; [ ma27 ];
-  # Don't edit the docbook xml directly, edit the md and generate it:
-  # `pandoc plausible.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > plausible.xml`
+  # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
   meta.doc = ./plausible.xml;
 }

nixos/modules/services/web-servers/garage-doc.xml nixos/modules/services/web-servers/garage.xml

···
     <title>General considerations on upgrades</title>
     <para>
       Garage provides a cookbook documentation on how to upgrade:
-      <link xlink:href="https://garagehq.deuxfleurs.fr/documentation/cookbook/upgrading/" role="uri">https://garagehq.deuxfleurs.fr/documentation/cookbook/upgrading/</link>
+      <link xlink:href="https://garagehq.deuxfleurs.fr/documentation/cookbook/upgrading/">https://garagehq.deuxfleurs.fr/documentation/cookbook/upgrading/</link>
     </para>
     <warning>
       <para>
···
       <para>
         Until 1.0 is released, patch-level upgrades are considered as
         minor version upgrades. Minor version upgrades are considered as
-        major version upgrades. i.e. 0.6 to 0.7 is a major version
+        major version upgrades. i.e. 0.6 to 0.7 is a major version
         upgrade.
       </para>
     </warning>
···
         <para>
           <emphasis role="strong">Straightforward upgrades (patch-level
           upgrades).</emphasis> Upgrades must be performed one by one,
-          i.e. for each node, stop it, upgrade it : change
+          i.e. for each node, stop it, upgrade it : change
           <link linkend="opt-system.stateVersion">stateVersion</link> or
           <link linkend="opt-services.garage.package">services.garage.package</link>,
           restart it if it was not already by switching.
···
       </listitem>
       <listitem>
         <para>
-          Backup the metadata folder of ALL your nodes, e.g. for a
+          Backup the metadata folder of ALL your nodes, e.g. for a
           metadata directory (the default one) in
           <literal>/var/lib/garage/meta</literal>, you can run
           <literal>pushd /var/lib/garage; tar -acf meta-v0.7.tar.zst meta/; popd</literal>.
···
       While patch-level updates are no problem and can be done directly
       in the package-expression (and should be backported to supported
       stable branches after that), major-releases should be added in a
-      new attribute (e.g. Garage <literal>v0.8.0</literal> should be
+      new attribute (e.g. Garage <literal>v0.8.0</literal> should be
       available in <literal>nixpkgs</literal> as
       <literal>pkgs.garage_0_8_0</literal>). To provide simple upgrade
       paths it’s generally useful to backport those as well to stable
···
 </programlisting>
     <para>
       Ideally we should make sure that it’s possible to jump two NixOS
-      versions forward: i.e. the warnings and the logic in the module
-      should guard a user to upgrade from a Garage on e.g. 22.11 to a
+      versions forward: i.e. the warnings and the logic in the module
+      should guard a user to upgrade from a Garage on e.g. 22.11 to a
       Garage on 23.11.
     </para>
   </section>

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

···
 in
 {
   meta = {
-    # Don't edit the docbook xml directly, edit the md and generate it:
-    # `pandoc garage-doc.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > garage-doc.xml`
-    doc = ./garage-doc.xml;
+    # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
+    doc = ./garage.xml;
     maintainers = with pkgs.lib.maintainers; [ raitobezarius ];
   };
 

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

···
 {
 
   meta = {
-    # Don't edit the docbook xml directly, edit the md and generate it:
-    # `pandoc gnome.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > gnome.xml`
+    # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
     doc = ./gnome.xml;
     maintainers = teams.gnome.members;
   };

nixos/modules/services/x11/desktop-managers/gnome.xml

···
       <para>
         If you’d only like to omit a subset of the core utilities, you
         can use
-        <xref linkend="opt-environment.gnome.excludePackages"></xref>.
-        Note that this mechanism can only exclude core utilities, games
-        and core developer tools.
+        <xref linkend="opt-environment.gnome.excludePackages" />. Note
+        that this mechanism can only exclude core utilities, games and
+        core developer tools.
       </para>
     </section>
     <section xml:id="sec-gnome-disabling-services">
···
     <para>
       It is also possible to create custom sessions that replace
       Metacity with a different window manager using
-      <xref linkend="opt-services.xserver.desktopManager.gnome.flashback.customSessions"></xref>.
+      <xref linkend="opt-services.xserver.desktopManager.gnome.flashback.customSessions" />.
     </para>
     <para>
       The following example uses <literal>xmonad</literal> window
···
     </para>
     <para>
       You can add them to
-      <xref linkend="opt-environment.systemPackages"></xref> and switch
-      to them with GNOME Tweaks. If you’d like to do this manually in
+      <xref linkend="opt-environment.systemPackages" /> and switch to
+      them with GNOME Tweaks. If you’d like to do this manually in
       dconf, change the values of the following keys:
     </para>
     <programlisting>
···
     </warning>
     <para>
       You can override the default GSettings values using the
-      <xref linkend="opt-services.xserver.desktopManager.gnome.extraGSettingsOverrides"></xref>
+      <xref linkend="opt-services.xserver.desktopManager.gnome.extraGSettingsOverrides" />
       option.
     </para>
     <para>
       Take note that whatever packages you want to override GSettings
       for, you need to add them to
-      <xref linkend="opt-services.xserver.desktopManager.gnome.extraGSettingsOverridePackages"></xref>.
+      <xref linkend="opt-services.xserver.desktopManager.gnome.extraGSettingsOverridePackages" />.
     </para>
     <para>
       You can use <literal>dconf-editor</literal> tool to explore which

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

···
 {
 
   meta = {
-    # Don't edit the docbook xml directly, edit the md and generate it:
-    # `pandoc pantheon.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > pantheon.xml`
+    # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
     doc = ./pantheon.xml;
     maintainers = teams.pantheon.members;
   };

nixos/modules/services/x11/desktop-managers/pantheon.xml

···
 </programlisting>
     <para>
       You can also use
-      <xref linkend="opt-environment.pantheon.excludePackages"></xref>
-      to remove any other app (like <literal>elementary-mail</literal>).
+      <xref linkend="opt-environment.pantheon.excludePackages" /> to
+      remove any other app (like <literal>elementary-mail</literal>).
     </para>
   </section>
   <section xml:id="sec-pantheon-wingpanel-switchboard">
···
     <itemizedlist spacing="compact">
       <listitem>
         <para>
-          <xref linkend="opt-services.xserver.desktopManager.pantheon.extraWingpanelIndicators"></xref>
+          <xref linkend="opt-services.xserver.desktopManager.pantheon.extraWingpanelIndicators" />
         </para>
       </listitem>
       <listitem>
         <para>
-          <xref linkend="opt-services.xserver.desktopManager.pantheon.extraSwitchboardPlugs"></xref>
+          <xref linkend="opt-services.xserver.desktopManager.pantheon.extraSwitchboardPlugs" />
         </para>
       </listitem>
     </itemizedlist>
···
   </section>
   <section xml:id="sec-pantheon-faq">
     <title>FAQ</title>
-    <variablelist>
+    <variablelist spacing="compact">
       <varlistentry>
         <term>
           <anchor xml:id="sec-pantheon-faq-messed-up-theme" />I have

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

···
 {
   meta = {
     maintainers = with maintainers; [ cole-h grahamc raitobezarius ];
-    # Don't edit the docbook xml directly, edit the md and generate it:
-    # `pandoc external.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart > external.xml`
+    # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh
     doc = ./external.xml;
   };