nixos-render-docs: add structural includes, use for manual

this adds support for structural includes to nixos-render-docs.
structural includes provide a way to denote the (sub)structure of the
nixos manual in the markdown source files, very similar to how we used
literal docbook blocks before, and are processed by nixos-render-docs
without involvement of xml tooling. this will ultimately allow us to
emit the nixos manual in other formats as well, e.g. html, without going
through docbook at all.

alternatives to this source layout were also considered:

a parallel structure using e.g. toml files that describe the document
tree and links to each part is possible, but much more complicated to
implement than the solution chosen here and makes it harder to follow
which files have what substructure. it also makes it much harder to
include a substructure in the middle of a file.

much the same goes for command-line arguments to the converter, only
that command-lined arguments are even harder to specify correctly and
cannot be reasonably pulled together from many places without involving
another layer of tooling. cli arguments would also mean that the manual
structure would be fixed in default.nix, which is also not ideal.

30 files changed, 255 insertions, 285 deletions

diff --git a/nixos/doc/manual/administration/containers.chapter.md b/nixos/doc/manual/administration/containers.chapter.md
index ea51f91f698fb..50493b562b542 100644
--- a/nixos/doc/manual/administration/containers.chapter.md
+++ b/nixos/doc/manual/administration/containers.chapter.md
@@ -21,8 +21,8 @@ which is often not what you want. By contrast, in the imperative
 approach, containers are configured and updated independently from the
 host system.
 
-```{=docbook}
-<xi:include href="imperative-containers.section.xml" />
-<xi:include href="declarative-containers.section.xml" />
-<xi:include href="container-networking.section.xml" />
+```{=include=} sections
+imperative-containers.section.md
+declarative-containers.section.md
+container-networking.section.md
 ```
diff --git a/nixos/doc/manual/administration/running.md b/nixos/doc/manual/administration/running.md
new file mode 100644
index 0000000000000..48e8c7c6668b7
--- /dev/null
+++ b/nixos/doc/manual/administration/running.md
@@ -0,0 +1,14 @@
+# Administration {#ch-running}
+
+This chapter describes various aspects of managing a running NixOS system, such as how to use the {command}`systemd` service manager.
+
+```{=include=} chapters
+service-mgmt.chapter.md
+rebooting.chapter.md
+user-sessions.chapter.md
+control-groups.chapter.md
+logging.chapter.md
+cleaning-store.chapter.md
+containers.chapter.md
+troubleshooting.chapter.md
+```
diff --git a/nixos/doc/manual/administration/running.xml b/nixos/doc/manual/administration/running.xml
deleted file mode 100644
index d9fcc1aee263f..0000000000000
--- a/nixos/doc/manual/administration/running.xml
+++ /dev/null
@@ -1,21 +0,0 @@
-<part xmlns="http://docbook.org/ns/docbook"
-      xmlns:xlink="http://www.w3.org/1999/xlink"
-      xmlns:xi="http://www.w3.org/2001/XInclude"
-      version="5.0"
-      xml:id="ch-running">
- <title>Administration</title>
- <partintro xml:id="ch-running-intro">
-  <para>
-   This chapter describes various aspects of managing a running NixOS system,
-   such as how to use the <command>systemd</command> service manager.
-  </para>
- </partintro>
- <xi:include href="../from_md/administration/service-mgmt.chapter.xml" />
- <xi:include href="../from_md/administration/rebooting.chapter.xml" />
- <xi:include href="../from_md/administration/user-sessions.chapter.xml" />
- <xi:include href="../from_md/administration/control-groups.chapter.xml" />
- <xi:include href="../from_md/administration/logging.chapter.xml" />
- <xi:include href="../from_md/administration/cleaning-store.chapter.xml" />
- <xi:include href="../from_md/administration/containers.chapter.xml" />
- <xi:include href="../from_md/administration/troubleshooting.chapter.xml" />
-</part>
diff --git a/nixos/doc/manual/administration/troubleshooting.chapter.md b/nixos/doc/manual/administration/troubleshooting.chapter.md
index 548456eaf6d67..1253607f8efc2 100644
--- a/nixos/doc/manual/administration/troubleshooting.chapter.md
+++ b/nixos/doc/manual/administration/troubleshooting.chapter.md
@@ -3,10 +3,10 @@
 This chapter describes solutions to common problems you might encounter
 when you manage your NixOS system.
 
-```{=docbook}
-<xi:include href="boot-problems.section.xml" />
-<xi:include href="maintenance-mode.section.xml" />
-<xi:include href="rollback.section.xml" />
-<xi:include href="store-corruption.section.xml" />
-<xi:include href="network-problems.section.xml" />
+```{=include=} sections
+boot-problems.section.md
+maintenance-mode.section.md
+rollback.section.md
+store-corruption.section.md
+network-problems.section.md
 ```
diff --git a/nixos/doc/manual/configuration/config-syntax.chapter.md b/nixos/doc/manual/configuration/config-syntax.chapter.md
index 9f8d45d588997..9e606b2b82af3 100644
--- a/nixos/doc/manual/configuration/config-syntax.chapter.md
+++ b/nixos/doc/manual/configuration/config-syntax.chapter.md
@@ -11,8 +11,8 @@ manual](https://nixos.org/nix/manual/#chap-writing-nix-expressions), but
 here we give a short overview of the most important constructs useful in
 NixOS configuration files.
 
-```{=docbook}
-<xi:include href="config-file.section.xml" />
-<xi:include href="abstractions.section.xml" />
-<xi:include href="modularity.section.xml" />
+```{=include=} sections
+config-file.section.md
+abstractions.section.md
+modularity.section.md
 ```
diff --git a/nixos/doc/manual/configuration/configuration.md b/nixos/doc/manual/configuration/configuration.md
new file mode 100644
index 0000000000000..4c966f3325b99
--- /dev/null
+++ b/nixos/doc/manual/configuration/configuration.md
@@ -0,0 +1,27 @@
+# Configuration {#ch-configuration}
+
+This chapter describes how to configure various aspects of a NixOS machine through the configuration file {file}`/etc/nixos/configuration.nix`. As described in [](#sec-changing-config), changes to this file only take effect after you run {command}`nixos-rebuild`.
+
+```{=include=} chapters
+config-syntax.chapter.md
+package-mgmt.chapter.md
+user-mgmt.chapter.md
+file-systems.chapter.md
+x-windows.chapter.md
+wayland.chapter.md
+gpu-accel.chapter.md
+xfce.chapter.md
+networking.chapter.md
+linux-kernel.chapter.md
+subversion.chapter.md
+```
+
+```{=include=} chapters
+@MODULE_CHAPTERS@
+```
+
+```{=include=} chapters
+profiles.chapter.md
+kubernetes.chapter.md
+```
+<!-- Apache; libvirtd virtualisation -->
diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml
deleted file mode 100644
index b04316cfa48e2..0000000000000
--- a/nixos/doc/manual/configuration/configuration.xml
+++ /dev/null
@@ -1,31 +0,0 @@
-<part xmlns="http://docbook.org/ns/docbook"
-      xmlns:xlink="http://www.w3.org/1999/xlink"
-      xmlns:xi="http://www.w3.org/2001/XInclude"
-      version="5.0"
-      xml:id="ch-configuration">
- <title>Configuration</title>
- <partintro xml:id="ch-configuration-intro">
-  <para>
-   This chapter describes how to configure various aspects of a NixOS machine
-   through the configuration file
-   <filename>/etc/nixos/configuration.nix</filename>. As described in
-   <xref linkend="sec-changing-config" />, changes to this file only take
-   effect after you run <command>nixos-rebuild</command>.
-  </para>
- </partintro>
- <xi:include href="../from_md/configuration/config-syntax.chapter.xml" />
- <xi:include href="../from_md/configuration/package-mgmt.chapter.xml" />
- <xi:include href="../from_md/configuration/user-mgmt.chapter.xml" />
- <xi:include href="../from_md/configuration/file-systems.chapter.xml" />
- <xi:include href="../from_md/configuration/x-windows.chapter.xml" />
- <xi:include href="../from_md/configuration/wayland.chapter.xml" />
- <xi:include href="../from_md/configuration/gpu-accel.chapter.xml" />
- <xi:include href="../from_md/configuration/xfce.chapter.xml" />
- <xi:include href="../from_md/configuration/networking.chapter.xml" />
- <xi:include href="../from_md/configuration/linux-kernel.chapter.xml" />
- <xi:include href="../from_md/configuration/subversion.chapter.xml" />
- <xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
- <xi:include href="../from_md/configuration/profiles.chapter.xml" />
- <xi:include href="../from_md/configuration/kubernetes.chapter.xml" />
-<!-- Apache; libvirtd virtualisation -->
-</part>
diff --git a/nixos/doc/manual/configuration/declarative-packages.section.md b/nixos/doc/manual/configuration/declarative-packages.section.md
index 337cdf8472e40..02eaa56192e46 100644
--- a/nixos/doc/manual/configuration/declarative-packages.section.md
+++ b/nixos/doc/manual/configuration/declarative-packages.section.md
@@ -40,7 +40,7 @@ configuration use `pkgs` prefix (variable).
 To "uninstall" a package, simply remove it from
 [](#opt-environment.systemPackages) and run `nixos-rebuild switch`.
 
-```{=docbook}
-<xi:include href="customizing-packages.section.xml" />
-<xi:include href="adding-custom-packages.section.xml" />
+```{=include=} sections
+customizing-packages.section.md
+adding-custom-packages.section.md
 ```
diff --git a/nixos/doc/manual/configuration/file-systems.chapter.md b/nixos/doc/manual/configuration/file-systems.chapter.md
index 901e2e4f181b3..aca978be064d3 100644
--- a/nixos/doc/manual/configuration/file-systems.chapter.md
+++ b/nixos/doc/manual/configuration/file-systems.chapter.md
@@ -36,7 +36,7 @@ dropping you to the emergency shell. You can make a mount asynchronous
 and non-critical by adding `options = [ "nofail" ];`.
 :::
 
-```{=docbook}
-<xi:include href="luks-file-systems.section.xml" />
-<xi:include href="sshfs-file-systems.section.xml" />
+```{=include=} sections
+luks-file-systems.section.md
+sshfs-file-systems.section.md
 ```
diff --git a/nixos/doc/manual/configuration/networking.chapter.md b/nixos/doc/manual/configuration/networking.chapter.md
index 529dc0610bdaf..abbd9766f173b 100644
--- a/nixos/doc/manual/configuration/networking.chapter.md
+++ b/nixos/doc/manual/configuration/networking.chapter.md
@@ -3,14 +3,14 @@
 This section describes how to configure networking components
 on your NixOS machine.
 
-```{=docbook}
-<xi:include href="network-manager.section.xml" />
-<xi:include href="ssh.section.xml" />
-<xi:include href="ipv4-config.section.xml" />
-<xi:include href="ipv6-config.section.xml" />
-<xi:include href="firewall.section.xml" />
-<xi:include href="wireless.section.xml" />
-<xi:include href="ad-hoc-network-config.section.xml" />
-<xi:include href="renaming-interfaces.section.xml" />
+```{=include=} sections
+network-manager.section.md
+ssh.section.md
+ipv4-config.section.md
+ipv6-config.section.md
+firewall.section.md
+wireless.section.md
+ad-hoc-network-config.section.md
+renaming-interfaces.section.md
 ```
 <!-- TODO: OpenVPN, NAT -->
diff --git a/nixos/doc/manual/configuration/package-mgmt.chapter.md b/nixos/doc/manual/configuration/package-mgmt.chapter.md
index a6c414be59a97..1148bbe84740c 100644
--- a/nixos/doc/manual/configuration/package-mgmt.chapter.md
+++ b/nixos/doc/manual/configuration/package-mgmt.chapter.md
@@ -12,7 +12,7 @@ NixOS has two distinct styles of package management:
     `nix-env` command. This style allows mixing packages from different
     Nixpkgs versions. It's the only choice for non-root users.
 
-```{=docbook}
-<xi:include href="declarative-packages.section.xml" />
-<xi:include href="ad-hoc-packages.section.xml" />
+```{=include=} sections
+declarative-packages.section.md
+ad-hoc-packages.section.md
 ```
diff --git a/nixos/doc/manual/configuration/profiles.chapter.md b/nixos/doc/manual/configuration/profiles.chapter.md
index 2c3dea27c1818..9f1f48f742ac5 100644
--- a/nixos/doc/manual/configuration/profiles.chapter.md
+++ b/nixos/doc/manual/configuration/profiles.chapter.md
@@ -19,16 +19,16 @@ install media, many are actually intended to be used in real installs.
 What follows is a brief explanation on the purpose and use-case for each
 profile. Detailing each option configured by each one is out of scope.
 
-```{=docbook}
-<xi:include href="profiles/all-hardware.section.xml" />
-<xi:include href="profiles/base.section.xml" />
-<xi:include href="profiles/clone-config.section.xml" />
-<xi:include href="profiles/demo.section.xml" />
-<xi:include href="profiles/docker-container.section.xml" />
-<xi:include href="profiles/graphical.section.xml" />
-<xi:include href="profiles/hardened.section.xml" />
-<xi:include href="profiles/headless.section.xml" />
-<xi:include href="profiles/installation-device.section.xml" />
-<xi:include href="profiles/minimal.section.xml" />
-<xi:include href="profiles/qemu-guest.section.xml" />
+```{=include=} sections
+profiles/all-hardware.section.md
+profiles/base.section.md
+profiles/clone-config.section.md
+profiles/demo.section.md
+profiles/docker-container.section.md
+profiles/graphical.section.md
+profiles/hardened.section.md
+profiles/headless.section.md
+profiles/installation-device.section.md
+profiles/minimal.section.md
+profiles/qemu-guest.section.md
 ```
diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix
index 3da6e88c70b7a..8c71e5108799c 100644
--- a/nixos/doc/manual/default.nix
+++ b/nixos/doc/manual/default.nix
@@ -143,35 +143,26 @@ let
     ''
       cp -r --no-preserve=all $inputs/* .
 
-      declare -a convert_args
-      while read -r mf; do
-        if [[ "$mf" = *.chapter.md ]]; then
-          convert_args+=("--chapter")
-        else
-          convert_args+=("--section")
-        fi
-
-        convert_args+=("from_md/''${mf%.md}.xml" "$mf")
-      done < <(find . -type f -name '*.md')
-
-      nixos-render-docs manual docbook-fragment \
+      substituteInPlace ./manual.md \
+        --replace '@NIXOS_VERSION@' "${version}"
+      substituteInPlace ./configuration/configuration.md \
+        --replace \
+            '@MODULE_CHAPTERS@' \
+            ${lib.escapeShellArg (lib.concatMapStringsSep "\n" (p: "${p.value}") config.meta.doc)}
+      substituteInPlace ./nixos-options.md \
+        --replace \
+          '@NIXOS_OPTIONS_JSON@' \
+          ${optionsDoc.optionsJSON}/share/doc/nixos/options.json
+      substituteInPlace ./development/writing-nixos-tests.section.md \
+        --replace \
+          '@NIXOS_TEST_OPTIONS_JSON@' \
+          ${testOptionsDoc.optionsJSON}/share/doc/nixos/options.json
+
+      nixos-render-docs manual docbook \
         --manpage-urls ${manpageUrls} \
-        "''${convert_args[@]}"
-
-      mkdir ./generated
-      ln -s ${optionsDoc.optionsDocBook} ./generated/options-db.xml
-      ln -s ${testOptionsDoc.optionsDocBook} ./generated/test-options-db.xml
-      printf "%s" "${version}" > ./generated/version
-      chmod -R u+w .
-
-      nixos-render-docs manual docbook-section \
-        --manpage-urls ${manpageUrls} \
-        ./generated/modules.xml \
-        --section \
-          --section-id modules \
-          --chapters ${lib.concatMapStrings (p: "${p.value} ") config.meta.doc}
-
-      xmllint --xinclude --output ./manual-combined.xml ./manual.xml
+        --revision ${lib.escapeShellArg revision} \
+        ./manual.md \
+        ./manual-combined.xml
 
       ${linterFunctions}
 
diff --git a/nixos/doc/manual/development/development.md b/nixos/doc/manual/development/development.md
new file mode 100644
index 0000000000000..6a0dd091b1292
--- /dev/null
+++ b/nixos/doc/manual/development/development.md
@@ -0,0 +1,14 @@
+# Development {#ch-development}
+
+This chapter describes how you can modify and extend NixOS.
+
+```{=include=} chapters
+sources.chapter.md
+writing-modules.chapter.md
+building-parts.chapter.md
+bootspec.chapter.md
+what-happens-during-a-system-switch.chapter.md
+writing-documentation.chapter.md
+nixos-tests.chapter.md
+testing-installer.chapter.md
+```
diff --git a/nixos/doc/manual/development/development.xml b/nixos/doc/manual/development/development.xml
deleted file mode 100644
index 949468c9021df..0000000000000
--- a/nixos/doc/manual/development/development.xml
+++ /dev/null
@@ -1,20 +0,0 @@
-<part   xmlns="http://docbook.org/ns/docbook"
-        xmlns:xlink="http://www.w3.org/1999/xlink"
-        xmlns:xi="http://www.w3.org/2001/XInclude"
-        version="5.0"
-        xml:id="ch-development">
- <title>Development</title>
- <partintro xml:id="ch-development-intro">
-  <para>
-   This chapter describes how you can modify and extend NixOS.
-  </para>
- </partintro>
- <xi:include href="../from_md/development/sources.chapter.xml" />
- <xi:include href="../from_md/development/writing-modules.chapter.xml" />
- <xi:include href="../from_md/development/building-parts.chapter.xml" />
- <xi:include href="../from_md/development/bootspec.chapter.xml" />
- <xi:include href="../from_md/development/what-happens-during-a-system-switch.chapter.xml" />
- <xi:include href="../from_md/development/writing-documentation.chapter.xml" />
- <xi:include href="../from_md/development/nixos-tests.chapter.xml" />
- <xi:include href="../from_md/development/testing-installer.chapter.xml" />
-</part>
diff --git a/nixos/doc/manual/development/nixos-tests.chapter.md b/nixos/doc/manual/development/nixos-tests.chapter.md
index 2a4fdddeaa666..ec0e4b9f076af 100644
--- a/nixos/doc/manual/development/nixos-tests.chapter.md
+++ b/nixos/doc/manual/development/nixos-tests.chapter.md
@@ -5,9 +5,9 @@ NixOS tests are kept in the directory `nixos/tests`, and are executed
 (using Nix) by a testing framework that automatically starts one or more
 virtual machines containing the NixOS system(s) required for the test.
 
-```{=docbook}
-<xi:include href="writing-nixos-tests.section.xml" />
-<xi:include href="running-nixos-tests.section.xml" />
-<xi:include href="running-nixos-tests-interactively.section.xml" />
-<xi:include href="linking-nixos-tests-to-packages.section.xml" />
+```{=include=} sections
+writing-nixos-tests.section.md
+running-nixos-tests.section.md
+running-nixos-tests-interactively.section.md
+linking-nixos-tests-to-packages.section.md
 ```
diff --git a/nixos/doc/manual/development/what-happens-during-a-system-switch.chapter.md b/nixos/doc/manual/development/what-happens-during-a-system-switch.chapter.md
index aad82831a3c24..9cbec729803ac 100644
--- a/nixos/doc/manual/development/what-happens-during-a-system-switch.chapter.md
+++ b/nixos/doc/manual/development/what-happens-during-a-system-switch.chapter.md
@@ -47,7 +47,7 @@ Most of these actions are either self-explaining but some of them have to do
 with our units or the activation script. For this reason, these topics are
 explained in the next sections.
 
-```{=docbook}
-<xi:include href="unit-handling.section.xml" />
-<xi:include href="activation-script.section.xml" />
+```{=include=} sections
+unit-handling.section.md
+activation-script.section.md
 ```
diff --git a/nixos/doc/manual/development/writing-documentation.chapter.md b/nixos/doc/manual/development/writing-documentation.chapter.md
index 4986c9f0a81b6..8d504dfb0b0a0 100644
--- a/nixos/doc/manual/development/writing-documentation.chapter.md
+++ b/nixos/doc/manual/development/writing-documentation.chapter.md
@@ -83,7 +83,7 @@ Keep the following guidelines in mind when you create and add a topic:
 
 ## Adding a Topic to the Book {#sec-writing-docs-adding-a-topic}
 
-Open the parent XML file and add an `xi:include` element to the list of
+Open the parent CommonMark file and add a line to the list of
 chapters with the file name of the topic that you created. If you
 created a `section`, you add the file to the `chapter` file. If you created
 a `chapter`, you add the file to the `part` file.
diff --git a/nixos/doc/manual/development/writing-modules.chapter.md b/nixos/doc/manual/development/writing-modules.chapter.md
index a0ec4a5df96e9..ae657458d7680 100644
--- a/nixos/doc/manual/development/writing-modules.chapter.md
+++ b/nixos/doc/manual/development/writing-modules.chapter.md
@@ -189,14 +189,14 @@ in {
 ```
 :::
 
-```{=docbook}
-<xi:include href="option-declarations.section.xml" />
-<xi:include href="option-types.section.xml" />
-<xi:include href="option-def.section.xml" />
-<xi:include href="assertions.section.xml" />
-<xi:include href="meta-attributes.section.xml" />
-<xi:include href="importing-modules.section.xml" />
-<xi:include href="replace-modules.section.xml" />
-<xi:include href="freeform-modules.section.xml" />
-<xi:include href="settings-options.section.xml" />
+```{=include=} sections
+option-declarations.section.md
+option-types.section.md
+option-def.section.md
+assertions.section.md
+meta-attributes.section.md
+importing-modules.section.md
+replace-modules.section.md
+freeform-modules.section.md
+settings-options.section.md
 ```
diff --git a/nixos/doc/manual/development/writing-nixos-tests.section.md b/nixos/doc/manual/development/writing-nixos-tests.section.md
index d80e314e6251b..3de46fda3df67 100644
--- a/nixos/doc/manual/development/writing-nixos-tests.section.md
+++ b/nixos/doc/manual/development/writing-nixos-tests.section.md
@@ -470,6 +470,8 @@ In that case, `numpy` is chosen from the generic `python3Packages`.
 
 The following options can be used when writing tests.
 
-```{=docbook}
-<xi:include href="../../generated/test-options-db.xml" xpointer="test-options-list"/>
+```{=include=} options
+id-prefix: test-opt-
+list-id: test-options-list
+source: @NIXOS_TEST_OPTIONS_JSON@
 ```
diff --git a/nixos/doc/manual/installation/installation.md b/nixos/doc/manual/installation/installation.md
new file mode 100644
index 0000000000000..140594256609f
--- /dev/null
+++ b/nixos/doc/manual/installation/installation.md
@@ -0,0 +1,11 @@
+# Installation {#ch-installation}
+
+This section describes how to obtain, install, and configure NixOS for first-time use.
+
+```{=include=} chapters
+obtaining.chapter.md
+installing.chapter.md
+changing-config.chapter.md
+upgrading.chapter.md
+building-nixos.chapter.md
+```
diff --git a/nixos/doc/manual/installation/installation.xml b/nixos/doc/manual/installation/installation.xml
deleted file mode 100644
index ba07d71d0ca35..0000000000000
--- a/nixos/doc/manual/installation/installation.xml
+++ /dev/null
@@ -1,18 +0,0 @@
-<part xmlns="http://docbook.org/ns/docbook"
-      xmlns:xlink="http://www.w3.org/1999/xlink"
-      xmlns:xi="http://www.w3.org/2001/XInclude"
-      version="5.0"
-      xml:id="ch-installation">
- <title>Installation</title>
- <partintro xml:id="ch-installation-intro">
-  <para>
-   This section describes how to obtain, install, and configure NixOS for
-   first-time use.
-  </para>
- </partintro>
- <xi:include href="../from_md/installation/obtaining.chapter.xml" />
- <xi:include href="../from_md/installation/installing.chapter.xml" />
- <xi:include href="../from_md/installation/changing-config.chapter.xml" />
- <xi:include href="../from_md/installation/upgrading.chapter.xml" />
- <xi:include href="../from_md/installation/building-nixos.chapter.xml" />
-</part>
diff --git a/nixos/doc/manual/installation/installing.chapter.md b/nixos/doc/manual/installation/installing.chapter.md
index e1908017a7e44..cf783c2d22b6f 100644
--- a/nixos/doc/manual/installation/installing.chapter.md
+++ b/nixos/doc/manual/installation/installing.chapter.md
@@ -602,11 +602,11 @@ With a partitioned disk.
 
 ## Additional installation notes {#sec-installation-additional-notes}
 
-```{=docbook}
-<xi:include href="installing-usb.section.xml" />
-<xi:include href="installing-pxe.section.xml" />
-<xi:include href="installing-kexec.section.xml" />
-<xi:include href="installing-virtualbox-guest.section.xml" />
-<xi:include href="installing-from-other-distro.section.xml" />
-<xi:include href="installing-behind-a-proxy.section.xml" />
+```{=include=} sections
+installing-usb.section.md
+installing-pxe.section.md
+installing-kexec.section.md
+installing-virtualbox-guest.section.md
+installing-from-other-distro.section.md
+installing-behind-a-proxy.section.md
 ```
diff --git a/nixos/doc/manual/manual.md b/nixos/doc/manual/manual.md
new file mode 100644
index 0000000000000..1972eaeda8728
--- /dev/null
+++ b/nixos/doc/manual/manual.md
@@ -0,0 +1,53 @@
+# NixOS Manual {#book-nixos-manual}
+## Version @NIXOS_VERSION@
+
+<!--
+  this is the top-level structure file for the nixos manual.
+
+  the manual structure extends the nixpkgs commonmark further with include
+  blocks to allow better organization of input text. there are six types of
+  include blocks: preface, parts, chapters, sections, appendix, and options.
+  each type except `options`` corresponds to the docbook elements of (roughly)
+  the same name, and can itself can further include blocks to denote its
+  substructure.
+
+  non-`options`` include blocks are fenced code blocks that list a number of
+  files to include, in the form
+
+     ```{=include=} <type>
+     <file-name-1>
+     <file-name-2>
+     <...>
+     ```
+
+  `options` include blocks do not list file names but contain a list of key-value
+  pairs that describe the options to be included and how to convert them into
+  elements of the manual output type:
+
+      ```{=include=} options
+      id-prefix: <options id prefix>
+      list-id: <variable list element id>
+      source: <path to options.json>
+      ```
+
+-->
+
+```{=include=} preface
+preface.md
+```
+
+```{=include=} parts
+installation/installation.md
+configuration/configuration.md
+administration/running.md
+development/development.md
+```
+
+```{=include=} chapters
+contributing-to-this-manual.chapter.md
+```
+
+```{=include=} appendix
+nixos-options.md
+release-notes/release-notes.md
+```
diff --git a/nixos/doc/manual/manual.xml b/nixos/doc/manual/manual.xml
deleted file mode 100644
index 4440f8e04baaa..0000000000000
--- a/nixos/doc/manual/manual.xml
+++ /dev/null
@@ -1,23 +0,0 @@
-<book xmlns="http://docbook.org/ns/docbook"
-      xmlns:xlink="http://www.w3.org/1999/xlink"
-      xmlns:xi="http://www.w3.org/2001/XInclude"
-      version="5.0"
-      xml:id="book-nixos-manual">
- <info>
-  <title>NixOS Manual</title>
-  <subtitle>Version <xi:include href="./generated/version" parse="text" />
-  </subtitle>
- </info>
- <xi:include href="preface.xml" />
- <xi:include href="installation/installation.xml" />
- <xi:include href="configuration/configuration.xml" />
- <xi:include href="administration/running.xml" />
- <xi:include href="development/development.xml" />
- <xi:include href="./from_md/contributing-to-this-manual.chapter.xml" />
- <appendix xml:id="ch-options">
-  <title>Configuration Options</title>
-  <xi:include href="./generated/options-db.xml"
-                xpointer="configuration-variable-list" />
- </appendix>
- <xi:include href="release-notes/release-notes.xml" />
-</book>
diff --git a/nixos/doc/manual/nixos-options.md b/nixos/doc/manual/nixos-options.md
new file mode 100644
index 0000000000000..33b487c95a2e1
--- /dev/null
+++ b/nixos/doc/manual/nixos-options.md
@@ -0,0 +1,7 @@
+# Configuration Options {#ch-options}
+
+```{=include=} options
+id-prefix: opt-
+list-id: configuration-variable-list
+source: @NIXOS_OPTIONS_JSON@
+```
diff --git a/nixos/doc/manual/preface.md b/nixos/doc/manual/preface.md
new file mode 100644
index 0000000000000..d5e6364780a7d
--- /dev/null
+++ b/nixos/doc/manual/preface.md
@@ -0,0 +1,11 @@
+# Preface {#preface}
+
+This manual describes how to install, use and extend NixOS, a Linux distribution based on the purely functional package management system [Nix](https://nixos.org/nix), that is composed using modules and packages defined in the [Nixpkgs](https://nixos.org/nixpkgs) project.
+
+Additional information regarding the Nix package manager and the Nixpkgs project can be found in respectively the [Nix manual](https://nixos.org/nix/manual) and the [Nixpkgs manual](https://nixos.org/nixpkgs/manual).
+
+If you encounter problems, please report them on the [`Discourse`](https://discourse.nixos.org), the [Matrix room](https://matrix.to/#nix:nixos.org), or on the [`#nixos` channel on Libera.Chat](irc://irc.libera.chat/#nixos). Alternatively, consider [contributing to this manual](#chap-contributing). Bugs should be reported in [NixOS’ GitHub issue tracker](https://github.com/NixOS/nixpkgs/issues).
+
+::: {.note}
+Commands prefixed with `#` have to be run as root, either requiring to login as root user or temporarily switching to it using `sudo` for example.
+:::
diff --git a/nixos/doc/manual/preface.xml b/nixos/doc/manual/preface.xml
deleted file mode 100644
index c0d530c3d1b5b..0000000000000
--- a/nixos/doc/manual/preface.xml
+++ /dev/null
@@ -1,42 +0,0 @@
-<preface xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="preface">
- <title>Preface</title>
- <para>
-  This manual describes how to install, use and extend NixOS, a Linux
-  distribution based on the purely functional package management system
-  <link xlink:href="https://nixos.org/nix">Nix</link>, that is composed
-  using modules and packages defined in the
-  <link xlink:href="https://nixos.org/nixpkgs">Nixpkgs</link> project.
- </para>
- <para>
-  Additional information regarding the Nix package manager and the Nixpkgs
-  project can be found in respectively the
-  <link xlink:href="https://nixos.org/nix/manual">Nix manual</link> and the
-  <link xlink:href="https://nixos.org/nixpkgs/manual">Nixpkgs manual</link>.
- </para>
- <para>
-  If you encounter problems, please report them on the
-  <literal
-   xlink:href="https://discourse.nixos.org">Discourse</literal>,
-  the <link
-   xlink:href="https://matrix.to/#nix:nixos.org">Matrix room</link>,
-  or on the <link
-   xlink:href="irc://irc.libera.chat/#nixos">
-  <literal>#nixos</literal> channel on Libera.Chat</link>.
-  Alternatively, consider <link
-   xlink:href="#chap-contributing">
-   contributing to this manual</link>. Bugs should be
-  reported in
-  <link
-   xlink:href="https://github.com/NixOS/nixpkgs/issues">NixOS’
-  GitHub issue tracker</link>.
- </para>
- <note>
-  <para>
-   Commands prefixed with <literal>#</literal> have to be run as root, either
-   requiring to login as root user or temporarily switching to it using
-   <literal>sudo</literal> for example.
-  </para>
- </note>
-</preface>
diff --git a/nixos/doc/manual/release-notes/release-notes.md b/nixos/doc/manual/release-notes/release-notes.md
new file mode 100644
index 0000000000000..ac61de3793e85
--- /dev/null
+++ b/nixos/doc/manual/release-notes/release-notes.md
@@ -0,0 +1,25 @@
+# Release Notes {#ch-release-notes}
+
+This section lists the release notes for each stable version of NixOS and current unstable revision.
+
+```{=include=} sections
+rl-2305.section.md
+rl-2211.section.md
+rl-2205.section.md
+rl-2111.section.md
+rl-2105.section.md
+rl-2009.section.md
+rl-2003.section.md
+rl-1909.section.md
+rl-1903.section.md
+rl-1809.section.md
+rl-1803.section.md
+rl-1709.section.md
+rl-1703.section.md
+rl-1609.section.md
+rl-1603.section.md
+rl-1509.section.md
+rl-1412.section.md
+rl-1404.section.md
+rl-1310.section.md
+```
diff --git a/nixos/doc/manual/release-notes/release-notes.xml b/nixos/doc/manual/release-notes/release-notes.xml
deleted file mode 100644
index bb5cc677afb80..0000000000000
--- a/nixos/doc/manual/release-notes/release-notes.xml
+++ /dev/null
@@ -1,30 +0,0 @@
-<appendix xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude"
-          version="5.0"
-          xml:id="ch-release-notes">
- <title>Release Notes</title>
- <para>
-  This section lists the release notes for each stable version of NixOS and
-  current unstable revision.
- </para>
- <xi:include href="../from_md/release-notes/rl-2305.section.xml" />
- <xi:include href="../from_md/release-notes/rl-2211.section.xml" />
- <xi:include href="../from_md/release-notes/rl-2205.section.xml" />
- <xi:include href="../from_md/release-notes/rl-2111.section.xml" />
- <xi:include href="../from_md/release-notes/rl-2105.section.xml" />
- <xi:include href="../from_md/release-notes/rl-2009.section.xml" />
- <xi:include href="../from_md/release-notes/rl-2003.section.xml" />
- <xi:include href="../from_md/release-notes/rl-1909.section.xml" />
- <xi:include href="../from_md/release-notes/rl-1903.section.xml" />
- <xi:include href="../from_md/release-notes/rl-1809.section.xml" />
- <xi:include href="../from_md/release-notes/rl-1803.section.xml" />
- <xi:include href="../from_md/release-notes/rl-1709.section.xml" />
- <xi:include href="../from_md/release-notes/rl-1703.section.xml" />
- <xi:include href="../from_md/release-notes/rl-1609.section.xml" />
- <xi:include href="../from_md/release-notes/rl-1603.section.xml" />
- <xi:include href="../from_md/release-notes/rl-1509.section.xml" />
- <xi:include href="../from_md/release-notes/rl-1412.section.xml" />
- <xi:include href="../from_md/release-notes/rl-1404.section.xml" />
- <xi:include href="../from_md/release-notes/rl-1310.section.xml" />
-</appendix>