Merge pull request #129121 from bobby285271/pr13

nixos/doc: convert Chapter 7, 9, 10, 11, 12, 14, 15, 48 to CommonMark

27 files changed, 2279 insertions, 1198 deletions

diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml
index 6949189b888..2461a5de73a 100644
--- a/nixos/doc/manual/configuration/configuration.xml
+++ b/nixos/doc/manual/configuration/configuration.xml
@@ -15,17 +15,17 @@
  </partintro>
  <xi:include href="config-syntax.xml" />
  <xi:include href="package-mgmt.xml" />
- <xi:include href="user-mgmt.xml" />
+ <xi:include href="../from_md/configuration/user-mgmt.chapter.xml" />
  <xi:include href="file-systems.xml" />
- <xi:include href="x-windows.xml" />
- <xi:include href="wayland.xml" />
- <xi:include href="gpu-accel.xml" />
- <xi:include href="xfce.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="networking.xml" />
- <xi:include href="linux-kernel.xml" />
- <xi:include href="subversion.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="profiles.xml" />
- <xi:include href="kubernetes.xml" />
+ <xi:include href="../from_md/configuration/kubernetes.chapter.xml" />
 <!-- Apache; libvirtd virtualisation -->
 </part>
diff --git a/nixos/doc/manual/configuration/gpu-accel.chapter.md b/nixos/doc/manual/configuration/gpu-accel.chapter.md
new file mode 100644
index 00000000000..08b6af5d98a
--- /dev/null
+++ b/nixos/doc/manual/configuration/gpu-accel.chapter.md
@@ -0,0 +1,204 @@
+# GPU acceleration {#sec-gpu-accel}
+
+NixOS provides various APIs that benefit from GPU hardware acceleration,
+such as VA-API and VDPAU for video playback; OpenGL and Vulkan for 3D
+graphics; and OpenCL for general-purpose computing. This chapter
+describes how to set up GPU hardware acceleration (as far as this is not
+done automatically) and how to verify that hardware acceleration is
+indeed used.
+
+Most of the aforementioned APIs are agnostic with regards to which
+display server is used. Consequently, these instructions should apply
+both to the X Window System and Wayland compositors.
+
+## OpenCL {#sec-gpu-accel-opencl}
+
+[OpenCL](https://en.wikipedia.org/wiki/OpenCL) is a general compute API.
+It is used by various applications such as Blender and Darktable to
+accelerate certain operations.
+
+OpenCL applications load drivers through the *Installable Client Driver*
+(ICD) mechanism. In this mechanism, an ICD file specifies the path to
+the OpenCL driver for a particular GPU family. In NixOS, there are two
+ways to make ICD files visible to the ICD loader. The first is through
+the `OCL_ICD_VENDORS` environment variable. This variable can contain a
+directory which is scanned by the ICL loader for ICD files. For example:
+
+```ShellSession
+$ export \
+  OCL_ICD_VENDORS=`nix-build '<nixpkgs>' --no-out-link -A rocm-opencl-icd`/etc/OpenCL/vendors/
+```
+
+The second mechanism is to add the OpenCL driver package to
+[](#opt-hardware.opengl.extraPackages).
+This links the ICD file under `/run/opengl-driver`, where it will be visible
+to the ICD loader.
+
+The proper installation of OpenCL drivers can be verified through the
+`clinfo` command of the clinfo package. This command will report the
+number of hardware devices that is found and give detailed information
+for each device:
+
+```ShellSession
+$ clinfo | head -n3
+Number of platforms  1
+Platform Name        AMD Accelerated Parallel Processing
+Platform Vendor      Advanced Micro Devices, Inc.
+```
+
+### AMD {#sec-gpu-accel-opencl-amd}
+
+Modern AMD [Graphics Core
+Next](https://en.wikipedia.org/wiki/Graphics_Core_Next) (GCN) GPUs are
+supported through the rocm-opencl-icd package. Adding this package to
+[](#opt-hardware.opengl.extraPackages)
+enables OpenCL support:
+
+```nix
+hardware.opengl.extraPackages = [
+  rocm-opencl-icd
+];
+```
+
+### Intel {#sec-gpu-accel-opencl-intel}
+
+[Intel Gen8 and later
+GPUs](https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units#Gen8)
+are supported by the Intel NEO OpenCL runtime that is provided by the
+intel-compute-runtime package. For Gen7 GPUs, the deprecated Beignet
+runtime can be used, which is provided by the beignet package. The
+proprietary Intel OpenCL runtime, in the intel-ocl package, is an
+alternative for Gen7 GPUs.
+
+The intel-compute-runtime, beignet, or intel-ocl package can be added to
+[](#opt-hardware.opengl.extraPackages)
+to enable OpenCL support. For example, for Gen8 and later GPUs, the following
+configuration can be used:
+
+```nix
+hardware.opengl.extraPackages = [
+  intel-compute-runtime
+];
+```
+
+## Vulkan {#sec-gpu-accel-vulkan}
+
+[Vulkan](https://en.wikipedia.org/wiki/Vulkan_(API)) is a graphics and
+compute API for GPUs. It is used directly by games or indirectly though
+compatibility layers like
+[DXVK](https://github.com/doitsujin/dxvk/wiki).
+
+By default, if [](#opt-hardware.opengl.driSupport)
+is enabled, mesa is installed and provides Vulkan for supported hardware.
+
+Similar to OpenCL, Vulkan drivers are loaded through the *Installable
+Client Driver* (ICD) mechanism. ICD files for Vulkan are JSON files that
+specify the path to the driver library and the supported Vulkan version.
+All successfully loaded drivers are exposed to the application as
+different GPUs. In NixOS, there are two ways to make ICD files visible
+to Vulkan applications: an environment variable and a module option.
+
+The first option is through the `VK_ICD_FILENAMES` environment variable.
+This variable can contain multiple JSON files, separated by `:`. For
+example:
+
+```ShellSession
+$ export \
+  VK_ICD_FILENAMES=`nix-build '<nixpkgs>' --no-out-link -A amdvlk`/share/vulkan/icd.d/amd_icd64.json
+```
+
+The second mechanism is to add the Vulkan driver package to
+[](#opt-hardware.opengl.extraPackages).
+This links the ICD file under `/run/opengl-driver`, where it will be
+visible to the ICD loader.
+
+The proper installation of Vulkan drivers can be verified through the
+`vulkaninfo` command of the vulkan-tools package. This command will
+report the hardware devices and drivers found, in this example output
+amdvlk and radv:
+
+```ShellSession
+$ vulkaninfo | grep GPU
+                GPU id  : 0 (Unknown AMD GPU)
+                GPU id  : 1 (AMD RADV NAVI10 (LLVM 9.0.1))
+     ...
+GPU0:
+        deviceType     = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU
+        deviceName     = Unknown AMD GPU
+GPU1:
+        deviceType     = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU
+```
+
+A simple graphical application that uses Vulkan is `vkcube` from the
+vulkan-tools package.
+
+### AMD {#sec-gpu-accel-vulkan-amd}
+
+Modern AMD [Graphics Core
+Next](https://en.wikipedia.org/wiki/Graphics_Core_Next) (GCN) GPUs are
+supported through either radv, which is part of mesa, or the amdvlk
+package. Adding the amdvlk package to
+[](#opt-hardware.opengl.extraPackages)
+makes amdvlk the default driver and hides radv and lavapipe from the device list.
+A specific driver can be forced as follows:
+
+```nix
+hardware.opengl.extraPackages = [
+  pkgs.amdvlk
+];
+
+# To enable Vulkan support for 32-bit applications, also add:
+hardware.opengl.extraPackages32 = [
+  pkgs.driversi686Linux.amdvlk
+];
+
+# Force radv
+environment.variables.AMD_VULKAN_ICD = "RADV";
+# Or
+environment.variables.VK_ICD_FILENAMES =
+  "/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json";
+```
+
+## Common issues {#sec-gpu-accel-common-issues}
+
+### User permissions {#sec-gpu-accel-common-issues-permissions}
+
+Except where noted explicitly, it should not be necessary to adjust user
+permissions to use these acceleration APIs. In the default
+configuration, GPU devices have world-read/write permissions
+(`/dev/dri/renderD*`) or are tagged as `uaccess` (`/dev/dri/card*`). The
+access control lists of devices with the `uaccess` tag will be updated
+automatically when a user logs in through `systemd-logind`. For example,
+if the user *jane* is logged in, the access control list should look as
+follows:
+
+```ShellSession
+$ getfacl /dev/dri/card0
+# file: dev/dri/card0
+# owner: root
+# group: video
+user::rw-
+user:jane:rw-
+group::rw-
+mask::rw-
+other::---
+```
+
+If you disabled (this functionality of) `systemd-logind`, you may need
+to add the user to the `video` group and log in again.
+
+### Mixing different versions of nixpkgs {#sec-gpu-accel-common-issues-mixing-nixpkgs}
+
+The *Installable Client Driver* (ICD) mechanism used by OpenCL and
+Vulkan loads runtimes into its address space using `dlopen`. Mixing an
+ICD loader mechanism and runtimes from different version of nixpkgs may
+not work. For example, if the ICD loader uses an older version of glibc
+than the runtime, the runtime may not be loadable due to missing
+symbols. Unfortunately, the loader will generally be quiet about such
+issues.
+
+If you suspect that you are running into library version mismatches
+between an ICL loader and a runtime, you could run an application with
+the `LD_DEBUG` variable set to get more diagnostic information. For
+example, OpenCL can be tested with `LD_DEBUG=files clinfo`, which should
+report missing symbols.
diff --git a/nixos/doc/manual/configuration/gpu-accel.xml b/nixos/doc/manual/configuration/gpu-accel.xml
deleted file mode 100644
index 9aa9be86a06..00000000000
--- a/nixos/doc/manual/configuration/gpu-accel.xml
+++ /dev/null
@@ -1,262 +0,0 @@
-<chapter 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="sec-gpu-accel">
-  <title>GPU acceleration</title>
-
-  <para>
-    NixOS provides various APIs that benefit from GPU hardware
-    acceleration, such as VA-API and VDPAU for video playback; OpenGL and
-    Vulkan for 3D graphics; and OpenCL for general-purpose computing.
-    This chapter describes how to set up GPU hardware acceleration (as far
-    as this is not done automatically) and how to verify that hardware
-    acceleration is indeed used.
-  </para>
-
-  <para>
-    Most of the aforementioned APIs are agnostic with regards to which
-    display server is used. Consequently, these instructions should apply
-    both to the X Window System and Wayland compositors.
-  </para>
-
-  <section xml:id="sec-gpu-accel-opencl">
-    <title>OpenCL</title>
-
-    <para>
-      <link xlink:href="https://en.wikipedia.org/wiki/OpenCL">OpenCL</link> is a
-      general compute API. It is used by various applications such as
-      Blender and Darktable to accelerate certain operations.
-    </para>
-
-    <para>
-      OpenCL applications load drivers through the <emphasis>Installable Client
-      Driver</emphasis> (ICD) mechanism. In this mechanism, an ICD file
-      specifies the path to the OpenCL driver for a particular GPU family.
-      In NixOS, there are two ways to make ICD files visible to the ICD
-      loader. The first is through the <varname>OCL_ICD_VENDORS</varname>
-      environment variable. This variable can contain a directory which
-      is scanned by the ICL loader for ICD files. For example:
-
-      <screen><prompt>$</prompt> export \
-  OCL_ICD_VENDORS=`nix-build '&lt;nixpkgs&gt;' --no-out-link -A rocm-opencl-icd`/etc/OpenCL/vendors/</screen>
-    </para>
-
-    <para>
-      The second mechanism is to add the OpenCL driver package to
-      <xref linkend="opt-hardware.opengl.extraPackages"/>. This links the
-      ICD file under <filename>/run/opengl-driver</filename>, where it will
-      be visible to the ICD loader.
-    </para>
-
-    <para>
-      The proper installation of OpenCL drivers can be verified through
-      the <command>clinfo</command> command of the <package>clinfo</package>
-      package. This command will report the number of hardware devices
-      that is found and give detailed information for each device:
-    </para>
-
-    <screen><prompt>$</prompt> clinfo | head -n3
-Number of platforms  1
-Platform Name        AMD Accelerated Parallel Processing
-Platform Vendor      Advanced Micro Devices, Inc.</screen>
-
-    <section xml:id="sec-gpu-accel-opencl-amd">
-      <title>AMD</title>
-
-      <para>
-       Modern AMD <link
-       xlink:href="https://en.wikipedia.org/wiki/Graphics_Core_Next">Graphics
-       Core Next</link> (GCN) GPUs are supported through the
-       <package>rocm-opencl-icd</package> package. Adding this package to
-       <xref linkend="opt-hardware.opengl.extraPackages"/> enables OpenCL
-       support:
-
-       <programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [
-         rocm-opencl-icd
-       ];</programlisting>
-      </para>
-    </section>
-
-    <section xml:id="sec-gpu-accel-opencl-intel">
-      <title>Intel</title>
-
-      <para>
-       <link
-         xlink:href="https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units#Gen8">Intel
-       Gen8 and later GPUs</link> are supported by the Intel NEO OpenCL
-       runtime that is provided by the
-       <package>intel-compute-runtime</package> package. For Gen7 GPUs,
-       the deprecated Beignet runtime can be used, which is provided
-       by the <package>beignet</package> package. The proprietary Intel
-       OpenCL runtime, in the <package>intel-ocl</package> package, is
-       an alternative for Gen7 GPUs.
-      </para>
-
-      <para>
-       The <package>intel-compute-runtime</package>, <package>beignet</package>,
-       or <package>intel-ocl</package> package can be added to
-       <xref linkend="opt-hardware.opengl.extraPackages"/> to enable OpenCL
-       support. For example, for Gen8 and later GPUs, the following
-       configuration can be used:
-
-      <programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [
-        intel-compute-runtime
-      ];</programlisting>
-
-      </para>
-    </section>
-  </section>
-
-  <section xml:id="sec-gpu-accel-vulkan">
-    <title>Vulkan</title>
-
-    <para>
-      <link xlink:href="https://en.wikipedia.org/wiki/Vulkan_(API)">Vulkan</link> is a
-      graphics and compute API for GPUs. It is used directly by games or indirectly though
-      compatibility layers like <link xlink:href="https://github.com/doitsujin/dxvk/wiki">DXVK</link>.
-    </para>
-
-    <para>
-     By default, if <xref linkend="opt-hardware.opengl.driSupport"/> is enabled,
-     <package>mesa</package> is installed and provides Vulkan for supported hardware.
-    </para>
-
-    <para>
-      Similar to OpenCL, Vulkan drivers are loaded through the <emphasis>Installable Client
-      Driver</emphasis> (ICD) mechanism. ICD files for Vulkan are JSON files that specify
-      the path to the driver library and the supported Vulkan version. All successfully
-      loaded drivers are exposed to the application as different GPUs.
-      In NixOS, there are two ways to make ICD files visible to Vulkan applications: an
-      environment variable and a module option.
-    </para>
-
-    <para>
-      The first option is through the <varname>VK_ICD_FILENAMES</varname>
-      environment variable. This variable can contain multiple JSON files, separated by
-      <literal>:</literal>. For example:
-
-      <screen><prompt>$</prompt> export \
-  VK_ICD_FILENAMES=`nix-build '&lt;nixpkgs&gt;' --no-out-link -A amdvlk`/share/vulkan/icd.d/amd_icd64.json</screen>
-    </para>
-
-    <para>
-      The second mechanism is to add the Vulkan driver package to
-      <xref linkend="opt-hardware.opengl.extraPackages"/>. This links the
-      ICD file under <filename>/run/opengl-driver</filename>, where it will
-      be visible to the ICD loader.
-    </para>
-
-    <para>
-      The proper installation of Vulkan drivers can be verified through
-      the <command>vulkaninfo</command> command of the <package>vulkan-tools</package>
-      package. This command will report the hardware devices and drivers found,
-      in this example output amdvlk and radv:
-    </para>
-
-    <screen><prompt>$</prompt> vulkaninfo | grep GPU
-                GPU id  : 0 (Unknown AMD GPU)
-                GPU id  : 1 (AMD RADV NAVI10 (LLVM 9.0.1))
-     ...
-GPU0:
-        deviceType     = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU
-        deviceName     = Unknown AMD GPU
-GPU1:
-        deviceType     = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU</screen>
-
-    <para>
-      A simple graphical application that uses Vulkan is <command>vkcube</command>
-      from the <package>vulkan-tools</package> package.
-    </para>
-
-    <section xml:id="sec-gpu-accel-vulkan-amd">
-      <title>AMD</title>
-
-      <para>
-       Modern AMD <link
-       xlink:href="https://en.wikipedia.org/wiki/Graphics_Core_Next">Graphics
-       Core Next</link> (GCN) GPUs are supported through either radv, which is
-       part of <package>mesa</package>, or the <package>amdvlk</package> package.
-       Adding the <package>amdvlk</package> package to
-       <xref linkend="opt-hardware.opengl.extraPackages"/> makes amdvlk the
-       default driver and hides radv and lavapipe from the device list. A
-       specific driver can be forced as follows:
-
-       <programlisting><xref linkend="opt-hardware.opengl.extraPackages"/> = [
-         pkgs.<package>amdvlk</package>
-       ];
-
-       # To enable Vulkan support for 32-bit applications, also add:
-       <xref linkend="opt-hardware.opengl.extraPackages32"/> = [
-         pkgs.driversi686Linux.<package>amdvlk</package>
-       ];
-
-       # Force radv
-       <xref linkend="opt-environment.variables"/>.AMD_VULKAN_ICD = "RADV";
-       # Or
-       <xref linkend="opt-environment.variables"/>.VK_ICD_FILENAMES =
-         "/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json";
-       </programlisting>
-      </para>
-    </section>
-  </section>
-
-  <section xml:id="sec-gpu-accel-common-issues">
-   <title>Common issues</title>
-
-   <section xml:id="sec-gpu-accel-common-issues-permissions">
-    <title>User permissions</title>
-
-    <para>
-     Except where noted explicitly, it should not be necessary to
-     adjust user permissions to use these acceleration APIs. In the default
-     configuration, GPU devices have world-read/write permissions
-     (<filename>/dev/dri/renderD*</filename>) or are tagged as
-     <code>uaccess</code> (<filename>/dev/dri/card*</filename>).  The
-     access control lists of devices with the <varname>uaccess</varname>
-     tag will be updated automatically when a user logs in through
-     <command>systemd-logind</command>. For example, if the user
-     <emphasis>jane</emphasis> is logged in, the access control list
-     should look as follows:
-
-     <screen><prompt>$</prompt> getfacl /dev/dri/card0
-# file: dev/dri/card0
-# owner: root
-# group: video
-user::rw-
-user:jane:rw-
-group::rw-
-mask::rw-
-other::---</screen>
-
-     If you disabled (this functionality of) <command>systemd-logind</command>,
-     you may need to add the user to the <code>video</code> group and
-     log in again.
-    </para>
-   </section>
-
-   <section xml:id="sec-gpu-accel-common-issues-mixing-nixpkgs">
-    <title>Mixing different versions of nixpkgs</title>
-
-    <para>
-     The <emphasis>Installable Client Driver</emphasis> (ICD)
-     mechanism used by OpenCL and Vulkan loads runtimes into its address
-     space using <code>dlopen</code>. Mixing an ICD loader mechanism and
-     runtimes from different version of nixpkgs may not work. For example,
-     if the ICD loader uses an older version of <package>glibc</package>
-     than the runtime, the runtime may not be loadable due to
-     missing symbols. Unfortunately, the loader will generally be quiet
-     about such issues.
-    </para>
-
-    <para>
-     If you suspect that you are running into library version mismatches
-     between an ICL loader and a runtime, you could run an application with
-     the <code>LD_DEBUG</code> variable set to get more diagnostic
-     information. For example, OpenCL can be tested with
-     <code>LD_DEBUG=files clinfo</code>, which should report missing
-     symbols.
-    </para>
-   </section>
-  </section>
-</chapter>
diff --git a/nixos/doc/manual/configuration/kubernetes.chapter.md b/nixos/doc/manual/configuration/kubernetes.chapter.md
new file mode 100644
index 00000000000..93787577be9
--- /dev/null
+++ b/nixos/doc/manual/configuration/kubernetes.chapter.md
@@ -0,0 +1,104 @@
+# Kubernetes {#sec-kubernetes}
+
+The NixOS Kubernetes module is a collective term for a handful of
+individual submodules implementing the Kubernetes cluster components.
+
+There are generally two ways of enabling Kubernetes on NixOS. One way is
+to enable and configure cluster components appropriately by hand:
+
+```nix
+services.kubernetes = {
+  apiserver.enable = true;
+  controllerManager.enable = true;
+  scheduler.enable = true;
+  addonManager.enable = true;
+  proxy.enable = true;
+  flannel.enable = true;
+};
+```
+
+Another way is to assign cluster roles (\"master\" and/or \"node\") to
+the host. This enables apiserver, controllerManager, scheduler,
+addonManager, kube-proxy and etcd:
+
+```nix
+services.kubernetes.roles = [ "master" ];
+```
+
+While this will enable the kubelet and kube-proxy only:
+
+```nix
+services.kubernetes.roles = [ "node" ];
+```
+
+Assigning both the master and node roles is usable if you want a single
+node Kubernetes cluster for dev or testing purposes:
+
+```nix
+services.kubernetes.roles = [ "master" "node" ];
+```
+
+Note: Assigning either role will also default both
+[](#opt-services.kubernetes.flannel.enable)
+and [](#opt-services.kubernetes.easyCerts)
+to true. This sets up flannel as CNI and activates automatic PKI bootstrapping.
+
+As of kubernetes 1.10.X it has been deprecated to open non-tls-enabled
+ports on kubernetes components. Thus, from NixOS 19.03 all plain HTTP
+ports have been disabled by default. While opening insecure ports is
+still possible, it is recommended not to bind these to other interfaces
+than loopback. To re-enable the insecure port on the apiserver, see options:
+[](#opt-services.kubernetes.apiserver.insecurePort) and
+[](#opt-services.kubernetes.apiserver.insecureBindAddress)
+
+::: {.note}
+As of NixOS 19.03, it is mandatory to configure:
+[](#opt-services.kubernetes.masterAddress).
+The masterAddress must be resolveable and routeable by all cluster nodes.
+In single node clusters, this can be set to `localhost`.
+:::
+
+Role-based access control (RBAC) authorization mode is enabled by
+default. This means that anonymous requests to the apiserver secure port
+will expectedly cause a permission denied error. All cluster components
+must therefore be configured with x509 certificates for two-way tls
+communication. The x509 certificate subject section determines the roles
+and permissions granted by the apiserver to perform clusterwide or
+namespaced operations. See also: [ Using RBAC
+Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/).
+
+The NixOS kubernetes module provides an option for automatic certificate
+bootstrapping and configuration,
+[](#opt-services.kubernetes.easyCerts).
+The PKI bootstrapping process involves setting up a certificate authority (CA)
+daemon (cfssl) on the kubernetes master node. cfssl generates a CA-cert
+for the cluster, and uses the CA-cert for signing subordinate certs issued
+to each of the cluster components. Subsequently, the certmgr daemon monitors
+active certificates and renews them when needed. For single node Kubernetes
+clusters, setting [](#opt-services.kubernetes.easyCerts)
+= true is sufficient and no further action is required. For joining extra node
+machines to an existing cluster on the other hand, establishing initial
+trust is mandatory.
+
+To add new nodes to the cluster: On any (non-master) cluster node where
+[](#opt-services.kubernetes.easyCerts)
+is enabled, the helper script `nixos-kubernetes-node-join` is available on PATH.
+Given a token on stdin, it will copy the token to the kubernetes secrets directory
+and restart the certmgr service. As requested certificates are issued, the
+script will restart kubernetes cluster components as needed for them to
+pick up new keypairs.
+
+::: {.note}
+Multi-master (HA) clusters are not supported by the easyCerts module.
+:::
+
+In order to interact with an RBAC-enabled cluster as an administrator,
+one needs to have cluster-admin privileges. By default, when easyCerts
+is enabled, a cluster-admin kubeconfig file is generated and linked into
+`/etc/kubernetes/cluster-admin.kubeconfig` as determined by
+[](#opt-services.kubernetes.pki.etcClusterAdminKubeconfig).
+`export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig` will make
+kubectl use this kubeconfig to access and authenticate the cluster. The
+cluster-admin kubeconfig references an auto-generated keypair owned by
+root. Thus, only root on the kubernetes master may obtain cluster-admin
+rights by means of this file.
diff --git a/nixos/doc/manual/configuration/kubernetes.xml b/nixos/doc/manual/configuration/kubernetes.xml
deleted file mode 100644
index 54a100e4479..00000000000
--- a/nixos/doc/manual/configuration/kubernetes.xml
+++ /dev/null
@@ -1,112 +0,0 @@
-<chapter 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="sec-kubernetes">
- <title>Kubernetes</title>
- <para>
-  The NixOS Kubernetes module is a collective term for a handful of individual
-  submodules implementing the Kubernetes cluster components.
- </para>
- <para>
-  There are generally two ways of enabling Kubernetes on NixOS. One way is to
-  enable and configure cluster components appropriately by hand:
-<programlisting>
-services.kubernetes = {
-  apiserver.enable = true;
-  controllerManager.enable = true;
-  scheduler.enable = true;
-  addonManager.enable = true;
-  proxy.enable = true;
-  flannel.enable = true;
-};
-</programlisting>
-  Another way is to assign cluster roles ("master" and/or "node") to the host.
-  This enables apiserver, controllerManager, scheduler, addonManager,
-  kube-proxy and etcd:
-<programlisting>
-<xref linkend="opt-services.kubernetes.roles"/> = [ "master" ];
-</programlisting>
-  While this will enable the kubelet and kube-proxy only:
-<programlisting>
-<xref linkend="opt-services.kubernetes.roles"/> = [ "node" ];
-</programlisting>
-  Assigning both the master and node roles is usable if you want a single node
-  Kubernetes cluster for dev or testing purposes:
-<programlisting>
-<xref linkend="opt-services.kubernetes.roles"/> = [ "master" "node" ];
-</programlisting>
-  Note: Assigning either role will also default both
-  <xref linkend="opt-services.kubernetes.flannel.enable"/> and
-  <xref linkend="opt-services.kubernetes.easyCerts"/> to true. This sets up
-  flannel as CNI and activates automatic PKI bootstrapping.
- </para>
- <para>
-  As of kubernetes 1.10.X it has been deprecated to open non-tls-enabled ports
-  on kubernetes components. Thus, from NixOS 19.03 all plain HTTP ports have
-  been disabled by default. While opening insecure ports is still possible, it
-  is recommended not to bind these to other interfaces than loopback. To
-  re-enable the insecure port on the apiserver, see options:
-  <xref linkend="opt-services.kubernetes.apiserver.insecurePort"/> and
-  <xref linkend="opt-services.kubernetes.apiserver.insecureBindAddress"/>
- </para>
- <note>
-  <para>
-   As of NixOS 19.03, it is mandatory to configure:
-   <xref linkend="opt-services.kubernetes.masterAddress"/>. The masterAddress
-   must be resolveable and routeable by all cluster nodes. In single node
-   clusters, this can be set to <literal>localhost</literal>.
-  </para>
- </note>
- <para>
-  Role-based access control (RBAC) authorization mode is enabled by default.
-  This means that anonymous requests to the apiserver secure port will
-  expectedly cause a permission denied error. All cluster components must
-  therefore be configured with x509 certificates for two-way tls communication.
-  The x509 certificate subject section determines the roles and permissions
-  granted by the apiserver to perform clusterwide or namespaced operations. See
-  also:
-  <link
-     xlink:href="https://kubernetes.io/docs/reference/access-authn-authz/rbac/">
-  Using RBAC Authorization</link>.
- </para>
- <para>
-  The NixOS kubernetes module provides an option for automatic certificate
-  bootstrapping and configuration,
-  <xref linkend="opt-services.kubernetes.easyCerts"/>. The PKI bootstrapping
-  process involves setting up a certificate authority (CA) daemon (cfssl) on
-  the kubernetes master node. cfssl generates a CA-cert for the cluster, and
-  uses the CA-cert for signing subordinate certs issued to each of the cluster
-  components. Subsequently, the certmgr daemon monitors active certificates and
-  renews them when needed. For single node Kubernetes clusters, setting
-  <xref linkend="opt-services.kubernetes.easyCerts"/> = true is sufficient and
-  no further action is required. For joining extra node machines to an existing
-  cluster on the other hand, establishing initial trust is mandatory.
- </para>
- <para>
-  To add new nodes to the cluster: On any (non-master) cluster node where
-  <xref linkend="opt-services.kubernetes.easyCerts"/> is enabled, the helper
-  script <literal>nixos-kubernetes-node-join</literal> is available on PATH.
-  Given a token on stdin, it will copy the token to the kubernetes secrets
-  directory and restart the certmgr service. As requested certificates are
-  issued, the script will restart kubernetes cluster components as needed for
-  them to pick up new keypairs.
- </para>
- <note>
-  <para>
-   Multi-master (HA) clusters are not supported by the easyCerts module.
-  </para>
- </note>
- <para>
-  In order to interact with an RBAC-enabled cluster as an administrator, one
-  needs to have cluster-admin privileges. By default, when easyCerts is
-  enabled, a cluster-admin kubeconfig file is generated and linked into
-  <literal>/etc/kubernetes/cluster-admin.kubeconfig</literal> as determined by
-  <xref linkend="opt-services.kubernetes.pki.etcClusterAdminKubeconfig"/>.
-  <literal>export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig</literal>
-  will make kubectl use this kubeconfig to access and authenticate the cluster.
-  The cluster-admin kubeconfig references an auto-generated keypair owned by
-  root. Thus, only root on the kubernetes master may obtain cluster-admin
-  rights by means of this file.
- </para>
-</chapter>
diff --git a/nixos/doc/manual/configuration/linux-kernel.chapter.md b/nixos/doc/manual/configuration/linux-kernel.chapter.md
new file mode 100644
index 00000000000..aad6d49c72c
--- /dev/null
+++ b/nixos/doc/manual/configuration/linux-kernel.chapter.md
@@ -0,0 +1,135 @@
+# Linux Kernel {#sec-kernel-config}
+
+You can override the Linux kernel and associated packages using the
+option `boot.kernelPackages`. For instance, this selects the Linux 3.10
+kernel:
+
+```nix
+boot.kernelPackages = pkgs.linuxPackages_3_10;
+```
+
+Note that this not only replaces the kernel, but also packages that are
+specific to the kernel version, such as the NVIDIA video drivers. This
+ensures that driver packages are consistent with the kernel.
+
+The default Linux kernel configuration should be fine for most users.
+You can see the configuration of your current kernel with the following
+command:
+
+```ShellSession
+zcat /proc/config.gz
+```
+
+If you want to change the kernel configuration, you can use the
+`packageOverrides` feature (see [](#sec-customising-packages)). For
+instance, to enable support for the kernel debugger KGDB:
+
+```nix
+nixpkgs.config.packageOverrides = pkgs:
+  { linux_3_4 = pkgs.linux_3_4.override {
+      extraConfig =
+        ''
+          KGDB y
+        '';
+    };
+  };
+```
+
+`extraConfig` takes a list of Linux kernel configuration options, one
+per line. The name of the option should not include the prefix
+`CONFIG_`. The option value is typically `y`, `n` or `m` (to build
+something as a kernel module).
+
+Kernel modules for hardware devices are generally loaded automatically
+by `udev`. You can force a module to be loaded via
+[](#opt-boot.kernelModules), e.g.
+
+```nix
+boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];
+```
+
+If the module is required early during the boot (e.g. to mount the root
+file system), you can use [](#opt-boot.initrd.kernelModules):
+
+```nix
+boot.initrd.kernelModules = [ "cifs" ];
+```
+
+This causes the specified modules and their dependencies to be added to
+the initial ramdisk.
+
+Kernel runtime parameters can be set through
+[](#opt-boot.kernel.sysctl), e.g.
+
+```nix
+boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120;
+```
+
+sets the kernel's TCP keepalive time to 120 seconds. To see the
+available parameters, run `sysctl -a`.
+
+## Customize your kernel {#sec-linux-config-customizing}
+
+The first step before compiling the kernel is to generate an appropriate
+`.config` configuration. Either you pass your own config via the
+`configfile` setting of `linuxManualConfig`:
+
+```nix
+custom-kernel = super.linuxManualConfig {
+  inherit (super) stdenv hostPlatform;
+  inherit (linux_4_9) src;
+  version = "${linux_4_9.version}-custom";
+
+  configfile = /home/me/my_kernel_config;
+  allowImportFromDerivation = true;
+};
+```
+
+You can edit the config with this snippet (by default `make
+   menuconfig` won\'t work out of the box on nixos):
+
+```ShellSession
+nix-shell -E 'with import <nixpkgs> {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkg-config ncurses ];})'
+```
+
+or you can let nixpkgs generate the configuration. Nixpkgs generates it
+via answering the interactive kernel utility `make config`. The answers
+depend on parameters passed to
+`pkgs/os-specific/linux/kernel/generic.nix` (which you can influence by
+overriding `extraConfig, autoModules,
+   modDirVersion, preferBuiltin, extraConfig`).
+
+```nix
+mptcp93.override ({
+  name="mptcp-local";
+
+  ignoreConfigErrors = true;
+  autoModules = false;
+  kernelPreferBuiltin = true;
+
+  enableParallelBuilding = true;
+
+  extraConfig = ''
+    DEBUG_KERNEL y
+    FRAME_POINTER y
+    KGDB y
+    KGDB_SERIAL_CONSOLE y
+    DEBUG_INFO y
+  '';
+});
+```
+
+## Developing kernel modules {#sec-linux-config-developing-modules}
+
+When developing kernel modules it\'s often convenient to run
+edit-compile-run loop as quickly as possible. See below snippet as an
+example of developing `mellanox` drivers.
+
+```ShellSession
+$ nix-build '<nixpkgs>' -A linuxPackages.kernel.dev
+$ nix-shell '<nixpkgs>' -A linuxPackages.kernel
+$ unpackPhase
+$ cd linux-*
+$ make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules
+# insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko
+```
diff --git a/nixos/doc/manual/configuration/linux-kernel.xml b/nixos/doc/manual/configuration/linux-kernel.xml
deleted file mode 100644
index 529ac1b1cd4..00000000000
--- a/nixos/doc/manual/configuration/linux-kernel.xml
+++ /dev/null
@@ -1,138 +0,0 @@
-<chapter 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="sec-kernel-config">
- <title>Linux Kernel</title>
- <para>
-  You can override the Linux kernel and associated packages using the option
-  <option>boot.kernelPackages</option>. For instance, this selects the Linux
-  3.10 kernel:
-<programlisting>
-<xref linkend="opt-boot.kernelPackages"/> = pkgs.linuxPackages_3_10;
-</programlisting>
-  Note that this not only replaces the kernel, but also packages that are
-  specific to the kernel version, such as the NVIDIA video drivers. This
-  ensures that driver packages are consistent with the kernel.
- </para>
- <para>
-  The default Linux kernel configuration should be fine for most users. You can
-  see the configuration of your current kernel with the following command:
-<programlisting>
-zcat /proc/config.gz
-</programlisting>
-  If you want to change the kernel configuration, you can use the
-  <option>packageOverrides</option> feature (see
-  <xref
-linkend="sec-customising-packages" />). For instance, to enable support
-  for the kernel debugger KGDB:
-<programlisting>
-nixpkgs.config.packageOverrides = pkgs:
-  { linux_3_4 = pkgs.linux_3_4.override {
-      extraConfig =
-        ''
-          KGDB y
-        '';
-    };
-  };
-</programlisting>
-  <varname>extraConfig</varname> takes a list of Linux kernel configuration
-  options, one per line. The name of the option should not include the prefix
-  <literal>CONFIG_</literal>. The option value is typically
-  <literal>y</literal>, <literal>n</literal> or <literal>m</literal> (to build
-  something as a kernel module).
- </para>
- <para>
-  Kernel modules for hardware devices are generally loaded automatically by
-  <command>udev</command>. You can force a module to be loaded via
-  <xref linkend="opt-boot.kernelModules"/>, e.g.
-<programlisting>
-<xref linkend="opt-boot.kernelModules"/> = [ "fuse" "kvm-intel" "coretemp" ];
-</programlisting>
-  If the module is required early during the boot (e.g. to mount the root file
-  system), you can use <xref linkend="opt-boot.initrd.kernelModules"/>:
-<programlisting>
-<xref linkend="opt-boot.initrd.kernelModules"/> = [ "cifs" ];
-</programlisting>
-  This causes the specified modules and their dependencies to be added to the
-  initial ramdisk.
- </para>
- <para>
-  Kernel runtime parameters can be set through
-  <xref linkend="opt-boot.kernel.sysctl"/>, e.g.
-<programlisting>
-<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv4.tcp_keepalive_time" = 120;
-</programlisting>
-  sets the kernel’s TCP keepalive time to 120 seconds. To see the available
-  parameters, run <command>sysctl -a</command>.
- </para>
- <section xml:id="sec-linux-config-customizing">
-  <title>Customize your kernel</title>
-
-  <para>
-   The first step before compiling the kernel is to generate an appropriate
-   <literal>.config</literal> configuration. Either you pass your own config
-   via the <literal>configfile</literal> setting of
-   <literal>linuxManualConfig</literal>:
-<screen><![CDATA[
-  custom-kernel = super.linuxManualConfig {
-    inherit (super) stdenv hostPlatform;
-    inherit (linux_4_9) src;
-    version = "${linux_4_9.version}-custom";
-
-    configfile = /home/me/my_kernel_config;
-    allowImportFromDerivation = true;
-  };
-  ]]></screen>
-   You can edit the config with this snippet (by default <command>make
-   menuconfig</command> won't work out of the box on nixos):
-<screen><![CDATA[
-      nix-shell -E 'with import <nixpkgs> {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkg-config ncurses ];})'
-  ]]></screen>
-   or you can let nixpkgs generate the configuration. Nixpkgs generates it via
-   answering the interactive kernel utility <command>make config</command>. The
-   answers depend on parameters passed to
-   <filename>pkgs/os-specific/linux/kernel/generic.nix</filename> (which you
-   can influence by overriding <literal>extraConfig, autoModules,
-   modDirVersion, preferBuiltin, extraConfig</literal>).
-<screen><![CDATA[
-
-  mptcp93.override ({
-      name="mptcp-local";
-
-      ignoreConfigErrors = true;
-      autoModules = false;
-      kernelPreferBuiltin = true;
-
-      enableParallelBuilding = true;
-
-      extraConfig = ''
-        DEBUG_KERNEL y
-        FRAME_POINTER y
-        KGDB y
-        KGDB_SERIAL_CONSOLE y
-        DEBUG_INFO y
-      '';
-    });
-  ]]></screen>
-  </para>
- </section>
- <section xml:id="sec-linux-config-developing-modules">
-  <title>Developing kernel modules</title>
-
-  <para>
-   When developing kernel modules it's often convenient to run edit-compile-run
-   loop as quickly as possible. See below snippet as an example of developing
-   <literal>mellanox</literal> drivers.
-  </para>
-
-<screen>
-<prompt>$ </prompt>nix-build '&lt;nixpkgs>' -A linuxPackages.kernel.dev
-<prompt>$ </prompt>nix-shell '&lt;nixpkgs>' -A linuxPackages.kernel
-<prompt>$ </prompt>unpackPhase
-<prompt>$ </prompt>cd linux-*
-<prompt>$ </prompt>make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules
-<prompt># </prompt>insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko
-</screen>
- </section>
-</chapter>
diff --git a/nixos/doc/manual/configuration/sshfs-file-systems.section.md b/nixos/doc/manual/configuration/sshfs-file-systems.section.md
index 4625fce03d5..4dd1b203a24 100644
--- a/nixos/doc/manual/configuration/sshfs-file-systems.section.md
+++ b/nixos/doc/manual/configuration/sshfs-file-systems.section.md
@@ -34,7 +34,7 @@ SHA256:yjxl3UbTn31fLWeyLYTAKYJPRmzknjQZoyG8gSNEoIE my-user@workstation
 To keep the key safe, change the ownership to `root:root` and make sure the permissions are `600`:
 OpenSSH normally refuses to use the key if it's not well-protected.
 
-The file system can be configured in NixOS via the usual [fileSystems](options.html#opt-fileSystems) option.
+The file system can be configured in NixOS via the usual [fileSystems](#opt-fileSystems) option.
 Here's a typical setup:
 ```nix
 {
diff --git a/nixos/doc/manual/configuration/subversion.chapter.md b/nixos/doc/manual/configuration/subversion.chapter.md
new file mode 100644
index 00000000000..84f9c270337
--- /dev/null
+++ b/nixos/doc/manual/configuration/subversion.chapter.md
@@ -0,0 +1,102 @@
+# Subversion {#module-services-subversion}
+
+[Subversion](https://subversion.apache.org/) is a centralized
+version-control system. It can use a [variety of
+protocols](http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.choosing)
+for communication between client and server.
+
+## Subversion inside Apache HTTP {#module-services-subversion-apache-httpd}
+
+This section focuses on configuring a web-based server on top of the
+Apache HTTP server, which uses
+[WebDAV](http://www.webdav.org/)/[DeltaV](http://www.webdav.org/deltav/WWW10/deltav-intro.htm)
+for communication.
+
+For more information on the general setup, please refer to the [the
+appropriate section of the Subversion
+book](http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.httpd).
+
+To configure, include in `/etc/nixos/configuration.nix` code to activate
+Apache HTTP, setting [](#opt-services.httpd.adminAddr)
+appropriately:
+
+```nix
+services.httpd.enable = true;
+services.httpd.adminAddr = ...;
+networking.firewall.allowedTCPPorts = [ 80 443 ];
+```
+
+For a simple Subversion server with basic authentication, configure the
+Subversion module for Apache as follows, setting `hostName` and
+`documentRoot` appropriately, and `SVNParentPath` to the parent
+directory of the repositories, `AuthzSVNAccessFile` to the location of
+the `.authz` file describing access permission, and `AuthUserFile` to
+the password file.
+
+```nix
+services.httpd.extraModules = [
+    # note that order is *super* important here
+    { name = "dav_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_dav_svn.so"; }
+    { name = "authz_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_authz_svn.so"; }
+  ];
+  services.httpd.virtualHosts = {
+    "svn" = {
+       hostName = HOSTNAME;
+       documentRoot = DOCUMENTROOT;
+       locations."/svn".extraConfig = ''
+           DAV svn
+           SVNParentPath REPO_PARENT
+           AuthzSVNAccessFile ACCESS_FILE
+           AuthName "SVN Repositories"
+           AuthType Basic
+           AuthUserFile PASSWORD_FILE
+           Require valid-user
+      '';
+    }
+```
+
+The key `"svn"` is just a symbolic name identifying the virtual host.
+The `"/svn"` in `locations."/svn".extraConfig` is the path underneath
+which the repositories will be served.
+
+[This page](https://wiki.archlinux.org/index.php/Subversion) explains
+how to set up the Subversion configuration itself. This boils down to
+the following:
+
+Underneath `REPO_PARENT` repositories can be set up as follows:
+
+```ShellSession
+$ svn create REPO_NAME
+```
+
+Repository files need to be accessible by `wwwrun`:
+
+```ShellSession
+$ chown -R wwwrun:wwwrun REPO_PARENT
+```
+
+The password file `PASSWORD_FILE` can be created as follows:
+
+```ShellSession
+$ htpasswd -cs PASSWORD_FILE USER_NAME
+```
+
+Additional users can be set up similarly, omitting the `c` flag:
+
+```ShellSession
+$ htpasswd -s PASSWORD_FILE USER_NAME
+```
+
+The file describing access permissions `ACCESS_FILE` will look something
+like the following:
+
+```nix
+[/]
+* = r
+
+[REPO_NAME:/]
+USER_NAME = rw
+```
+
+The Subversion repositories will be accessible as
+`http://HOSTNAME/svn/REPO_NAME`.
diff --git a/nixos/doc/manual/configuration/subversion.xml b/nixos/doc/manual/configuration/subversion.xml
deleted file mode 100644
index 940d63cc4e6..00000000000
--- a/nixos/doc/manual/configuration/subversion.xml
+++ /dev/null
@@ -1,140 +0,0 @@
-<chapter 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="module-services-subversion">
-  <title>Subversion</title>
-
- <para>
-  <link xlink:href="https://subversion.apache.org/">Subversion</link>
-  is a centralized version-control system.  It can use a <link
-  xlink:href="http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.choosing">variety
-  of protocols</link> for communication between client and server.
- </para>
- <section xml:id="module-services-subversion-apache-httpd">
-  <title>Subversion inside Apache HTTP</title>
-
-   <para>
-   This section focuses on configuring a web-based server on top of
-   the Apache HTTP server, which uses
-   <link xlink:href="http://www.webdav.org/">WebDAV</link>/<link
-   xlink:href="http://www.webdav.org/deltav/WWW10/deltav-intro.htm">DeltaV</link>
-   for communication.
-   </para>
-
-   <para>For more information on the general setup, please refer to
-   the <link
-   xlink:href="http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.httpd">the
-   appropriate section of the Subversion book</link>.
-   </para>
-
-   <para>To configure, include in
-   <literal>/etc/nixos/configuration.nix</literal> code to activate
-   Apache HTTP, setting <xref linkend="opt-services.httpd.adminAddr" />
-   appropriately:
-   </para>
-
-    <para>
-<programlisting>
-  services.httpd.enable = true;
-  services.httpd.adminAddr = ...;
-  networking.firewall.allowedTCPPorts = [ 80 443 ];
-</programlisting>
-    </para>
-
-    <para>For a simple Subversion server with basic authentication,
-    configure the Subversion module for Apache as follows, setting
-    <literal>hostName</literal> and <literal>documentRoot</literal>
-    appropriately, and <literal>SVNParentPath</literal> to the parent
-    directory of the repositories,
-    <literal>AuthzSVNAccessFile</literal> to the location of the
-    <code>.authz</code> file describing access permission, and
-    <literal>AuthUserFile</literal> to the password file.
-    </para>
-    <para>
-<programlisting>
-services.httpd.extraModules = [
-    # note that order is *super* important here
-    { name = "dav_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_dav_svn.so"; }
-    { name = "authz_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_authz_svn.so"; }
-  ];
-  services.httpd.virtualHosts = {
-    "svn" = {
-       hostName = HOSTNAME;
-       documentRoot = DOCUMENTROOT;
-       locations."/svn".extraConfig = ''
-           DAV svn
-           SVNParentPath REPO_PARENT
-           AuthzSVNAccessFile ACCESS_FILE
-           AuthName "SVN Repositories"
-           AuthType Basic
-           AuthUserFile PASSWORD_FILE
-           Require valid-user
-      '';
-    }
-</programlisting>
-    </para>
-
-    <para>
-    The key <code>"svn"</code> is just a symbolic name identifying the
-    virtual host.  The <code>"/svn"</code> in
-    <code>locations."/svn".extraConfig</code> is the path underneath
-    which the repositories will be served.
-    </para>
-
-    <para><link
-              xlink:href="https://wiki.archlinux.org/index.php/Subversion">This
-    page</link> explains how to set up the Subversion configuration
-    itself.  This boils down to the following:
-    </para>
-    <para>
-      Underneath <literal>REPO_PARENT</literal> repositories can be set up
-      as follows:
-    </para>
-    <para>
-<screen>
-<prompt>$ </prompt> svn create REPO_NAME
-</screen>
-    </para>
-    <para>Repository files need to be accessible by
-    <literal>wwwrun</literal>:
-    </para>
-    <para>
-<screen>
-<prompt>$ </prompt> chown -R wwwrun:wwwrun REPO_PARENT
-</screen>
-    </para>
-    <para>
-      The password file <literal>PASSWORD_FILE</literal> can be created as follows:
-    </para>
-    <para>
-<screen>
-<prompt>$ </prompt> htpasswd -cs PASSWORD_FILE USER_NAME
-</screen>
-    </para>
-    <para>
-    Additional users can be set up similarly, omitting the
-    <code>c</code> flag:
-    </para>
-    <para>
-<screen>
-<prompt>$ </prompt> htpasswd -s PASSWORD_FILE USER_NAME
-</screen>
-    </para>
-    <para>
-      The file describing access permissions
-      <literal>ACCESS_FILE</literal> will look something like
-      the following:
-    </para>
-    <para>
-<programlisting>
-[/]
-* = r
-
-[REPO_NAME:/]
-USER_NAME = rw
-</programlisting>
-    </para>
-    <para>The Subversion repositories will be accessible as <code>http://HOSTNAME/svn/REPO_NAME</code>.</para>
- </section>
-</chapter>
diff --git a/nixos/doc/manual/configuration/user-mgmt.chapter.md b/nixos/doc/manual/configuration/user-mgmt.chapter.md
new file mode 100644
index 00000000000..37990664a8f
--- /dev/null
+++ b/nixos/doc/manual/configuration/user-mgmt.chapter.md
@@ -0,0 +1,92 @@
+# User Management {#sec-user-management}
+
+NixOS supports both declarative and imperative styles of user
+management. In the declarative style, users are specified in
+`configuration.nix`. For instance, the following states that a user
+account named `alice` shall exist:
+
+```nix
+users.users.alice = {
+  isNormalUser = true;
+  home = "/home/alice";
+  description = "Alice Foobar";
+  extraGroups = [ "wheel" "networkmanager" ];
+  openssh.authorizedKeys.keys = [ "ssh-dss AAAAB3Nza... alice@foobar" ];
+};
+```
+
+Note that `alice` is a member of the `wheel` and `networkmanager`
+groups, which allows her to use `sudo` to execute commands as `root` and
+to configure the network, respectively. Also note the SSH public key
+that allows remote logins with the corresponding private key. Users
+created in this way do not have a password by default, so they cannot
+log in via mechanisms that require a password. However, you can use the
+`passwd` program to set a password, which is retained across invocations
+of `nixos-rebuild`.
+
+If you set [](#opt-users.mutableUsers) to
+false, then the contents of `/etc/passwd` and `/etc/group` will be congruent
+to your NixOS configuration. For instance, if you remove a user from
+[](#opt-users.users) and run nixos-rebuild, the user
+account will cease to exist. Also, imperative commands for managing users and
+groups, such as useradd, are no longer available. Passwords may still be
+assigned by setting the user\'s
+[hashedPassword](#opt-users.users._name_.hashedPassword) option. A
+hashed password can be generated using `mkpasswd -m
+  sha-512`.
+
+A user ID (uid) is assigned automatically. You can also specify a uid
+manually by adding
+
+```nix
+uid = 1000;
+```
+
+to the user specification.
+
+Groups can be specified similarly. The following states that a group
+named `students` shall exist:
+
+```nix
+users.groups.students.gid = 1000;
+```
+
+As with users, the group ID (gid) is optional and will be assigned
+automatically if it's missing.
+
+In the imperative style, users and groups are managed by commands such
+as `useradd`, `groupmod` and so on. For instance, to create a user
+account named `alice`:
+
+```ShellSession
+# useradd -m alice
+```
+
+To make all nix tools available to this new user use \`su - USER\` which
+opens a login shell (==shell that loads the profile) for given user.
+This will create the \~/.nix-defexpr symlink. So run:
+
+```ShellSession
+# su - alice -c "true"
+```
+
+The flag `-m` causes the creation of a home directory for the new user,
+which is generally what you want. The user does not have an initial
+password and therefore cannot log in. A password can be set using the
+`passwd` utility:
+
+```ShellSession
+# passwd alice
+Enter new UNIX password: ***
+Retype new UNIX password: ***
+```
+
+A user can be deleted using `userdel`:
+
+```ShellSession
+# userdel -r alice
+```
+
+The flag `-r` deletes the user's home directory. Accounts can be
+modified using `usermod`. Unix groups can be managed using `groupadd`,
+`groupmod` and `groupdel`.
diff --git a/nixos/doc/manual/configuration/user-mgmt.xml b/nixos/doc/manual/configuration/user-mgmt.xml
deleted file mode 100644
index e83e7b75ef5..00000000000
--- a/nixos/doc/manual/configuration/user-mgmt.xml
+++ /dev/null
@@ -1,88 +0,0 @@
-<chapter 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="sec-user-management">
- <title>User Management</title>
- <para>
-  NixOS supports both declarative and imperative styles of user management. In
-  the declarative style, users are specified in
-  <filename>configuration.nix</filename>. For instance, the following states
-  that a user account named <literal>alice</literal> shall exist:
-<programlisting>
-<xref linkend="opt-users.users"/>.alice = {
-  <link linkend="opt-users.users._name_.isNormalUser">isNormalUser</link> = true;
-  <link linkend="opt-users.users._name_.home">home</link> = "/home/alice";
-  <link linkend="opt-users.users._name_.description">description</link> = "Alice Foobar";
-  <link linkend="opt-users.users._name_.extraGroups">extraGroups</link> = [ "wheel" "networkmanager" ];
-  <link linkend="opt-users.users._name_.openssh.authorizedKeys.keys">openssh.authorizedKeys.keys</link> = [ "ssh-dss AAAAB3Nza... alice@foobar" ];
-};
-</programlisting>
-  Note that <literal>alice</literal> is a member of the
-  <literal>wheel</literal> and <literal>networkmanager</literal> groups, which
-  allows her to use <command>sudo</command> to execute commands as
-  <literal>root</literal> and to configure the network, respectively. Also note
-  the SSH public key that allows remote logins with the corresponding private
-  key. Users created in this way do not have a password by default, so they
-  cannot log in via mechanisms that require a password. However, you can use
-  the <command>passwd</command> program to set a password, which is retained
-  across invocations of <command>nixos-rebuild</command>.
- </para>
- <para>
-  If you set <xref linkend="opt-users.mutableUsers"/> to false, then the
-  contents of <literal>/etc/passwd</literal> and <literal>/etc/group</literal>
-  will be congruent to your NixOS configuration. For instance, if you remove a
-  user from <xref linkend="opt-users.users"/> and run nixos-rebuild, the user
-  account will cease to exist. Also, imperative commands for managing users and
-  groups, such as useradd, are no longer available. Passwords may still be
-  assigned by setting the user's
-  <link linkend="opt-users.users._name_.hashedPassword">hashedPassword</link>
-  option. A hashed password can be generated using <command>mkpasswd -m
-  sha-512</command>.
- </para>
- <para>
-  A user ID (uid) is assigned automatically. You can also specify a uid
-  manually by adding
-<programlisting>
-uid = 1000;
-</programlisting>
-  to the user specification.
- </para>
- <para>
-  Groups can be specified similarly. The following states that a group named
-  <literal>students</literal> shall exist:
-<programlisting>
-<xref linkend="opt-users.groups"/>.students.gid = 1000;
-</programlisting>
-  As with users, the group ID (gid) is optional and will be assigned
-  automatically if it’s missing.
- </para>
- <para>
-  In the imperative style, users and groups are managed by commands such as
-  <command>useradd</command>, <command>groupmod</command> and so on. For
-  instance, to create a user account named <literal>alice</literal>:
-<screen>
-<prompt># </prompt>useradd -m <replaceable>alice</replaceable></screen>
-  To make all nix tools available to this new user use `su - USER` which opens
-  a login shell (==shell that loads the profile) for given user. This will
-  create the ~/.nix-defexpr symlink. So run:
-<screen>
-<prompt># </prompt>su - <replaceable>alice</replaceable> -c "true"</screen>
-  The flag <option>-m</option> causes the creation of a home directory for the
-  new user, which is generally what you want. The user does not have an initial
-  password and therefore cannot log in. A password can be set using the
-  <command>passwd</command> utility:
-<screen>
-<prompt># </prompt>passwd <replaceable>alice</replaceable>
-Enter new UNIX password: ***
-Retype new UNIX password: ***
-</screen>
-  A user can be deleted using <command>userdel</command>:
-<screen>
-<prompt># </prompt>userdel -r <replaceable>alice</replaceable></screen>
-  The flag <option>-r</option> deletes the user’s home directory. Accounts
-  can be modified using <command>usermod</command>. Unix groups can be managed
-  using <command>groupadd</command>, <command>groupmod</command> and
-  <command>groupdel</command>.
- </para>
-</chapter>
diff --git a/nixos/doc/manual/configuration/wayland.chapter.md b/nixos/doc/manual/configuration/wayland.chapter.md
new file mode 100644
index 00000000000..a3a46aa3da6
--- /dev/null
+++ b/nixos/doc/manual/configuration/wayland.chapter.md
@@ -0,0 +1,27 @@
+# Wayland {#sec-wayland}
+
+While X11 (see [](#sec-x11)) is still the primary display technology
+on NixOS, Wayland support is steadily improving. Where X11 separates the
+X Server and the window manager, on Wayland those are combined: a
+Wayland Compositor is like an X11 window manager, but also embeds the
+Wayland \'Server\' functionality. This means it is sufficient to install
+a Wayland Compositor such as sway without separately enabling a Wayland
+server:
+
+```nix
+programs.sway.enable = true;
+```
+
+This installs the sway compositor along with some essential utilities.
+Now you can start sway from the TTY console.
+
+If you are using a wlroots-based compositor, like sway, and want to be
+able to share your screen, you might want to activate this option:
+
+```nix
+xdg.portal.wlr.enable = true;
+```
+
+and configure Pipewire using
+[](#opt-services.pipewire.enable)
+and related options.
diff --git a/nixos/doc/manual/configuration/wayland.xml b/nixos/doc/manual/configuration/wayland.xml
deleted file mode 100644
index 2aefda3e22c..00000000000
--- a/nixos/doc/manual/configuration/wayland.xml
+++ /dev/null
@@ -1,33 +0,0 @@
-<chapter 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="sec-wayland">
- <title>Wayland</title>
-
- <para>
-  While X11 (see <xref linkend="sec-x11"/>) is still the primary display
-  technology on NixOS, Wayland support is steadily improving.
-  Where X11 separates the X Server and the window manager, on Wayland those
-  are combined: a Wayland Compositor is like an X11 window manager, but also
-  embeds the Wayland 'Server' functionality. This means it is sufficient to
-  install a Wayland Compositor such as <package>sway</package> without
-  separately enabling a Wayland server:
-<programlisting>
-<xref linkend="opt-programs.sway.enable"/> = true;
-</programlisting>
-  This installs the <package>sway</package> compositor along with some
-  essential utilities. Now you can start <package>sway</package> from the TTY
-  console.
- </para>
-
- <para>
-  If you are using a wlroots-based compositor, like sway, and want to be able to
-  share your screen, you might want to activate this option:
-<programlisting>
-<xref linkend="opt-xdg.portal.wlr.enable"/> = true;
-</programlisting>
-  and configure Pipewire using <xref linkend="opt-services.pipewire.enable"/>
-  and related options.
- </para>
-</chapter>
diff --git a/nixos/doc/manual/configuration/x-windows.chapter.md b/nixos/doc/manual/configuration/x-windows.chapter.md
new file mode 100644
index 00000000000..2c80b786b26
--- /dev/null
+++ b/nixos/doc/manual/configuration/x-windows.chapter.md
@@ -0,0 +1,337 @@
+# X Window System {#sec-x11}
+
+The X Window System (X11) provides the basis of NixOS' graphical user
+interface. It can be enabled as follows:
+
+```nix
+services.xserver.enable = true;
+```
+
+The X server will automatically detect and use the appropriate video
+driver from a set of X.org drivers (such as `vesa` and `intel`). You can
+also specify a driver manually, e.g.
+
+```nix
+services.xserver.videoDrivers = [ "r128" ];
+```
+
+to enable X.org's `xf86-video-r128` driver.
+
+You also need to enable at least one desktop or window manager.
+Otherwise, you can only log into a plain undecorated `xterm` window.
+Thus you should pick one or more of the following lines:
+
+```nix
+services.xserver.desktopManager.plasma5.enable = true;
+services.xserver.desktopManager.xfce.enable = true;
+services.xserver.desktopManager.gnome.enable = true;
+services.xserver.desktopManager.mate.enable = true;
+services.xserver.windowManager.xmonad.enable = true;
+services.xserver.windowManager.twm.enable = true;
+services.xserver.windowManager.icewm.enable = true;
+services.xserver.windowManager.i3.enable = true;
+services.xserver.windowManager.herbstluftwm.enable = true;
+```
+
+NixOS's default *display manager* (the program that provides a graphical
+login prompt and manages the X server) is LightDM. You can select an
+alternative one by picking one of the following lines:
+
+```nix
+services.xserver.displayManager.sddm.enable = true;
+services.xserver.displayManager.gdm.enable = true;
+```
+
+You can set the keyboard layout (and optionally the layout variant):
+
+```nix
+services.xserver.layout = "de";
+services.xserver.xkbVariant = "neo";
+```
+
+The X server is started automatically at boot time. If you don't want
+this to happen, you can set:
+
+```nix
+services.xserver.autorun = false;
+```
+
+The X server can then be started manually:
+
+```ShellSession
+# systemctl start display-manager.service
+```
+
+On 64-bit systems, if you want OpenGL for 32-bit programs such as in
+Wine, you should also set the following:
+
+```nix
+hardware.opengl.driSupport32Bit = true;
+```
+
+## Auto-login {#sec-x11-auto-login .unnumbered}
+
+The x11 login screen can be skipped entirely, automatically logging you
+into your window manager and desktop environment when you boot your
+computer.
+
+This is especially helpful if you have disk encryption enabled. Since
+you already have to provide a password to decrypt your disk, entering a
+second password to login can be redundant.
+
+To enable auto-login, you need to define your default window manager and
+desktop environment. If you wanted no desktop environment and i3 as your
+your window manager, you\'d define:
+
+```nix
+services.xserver.displayManager.defaultSession = "none+i3";
+```
+
+Every display manager in NixOS supports auto-login, here is an example
+using lightdm for a user `alice`:
+
+```nix
+services.xserver.displayManager.lightdm.enable = true;
+services.xserver.displayManager.autoLogin.enable = true;
+services.xserver.displayManager.autoLogin.user = "alice";
+```
+
+## Intel Graphics drivers {#sec-x11--graphics-cards-intel .unnumbered}
+
+There are two choices for Intel Graphics drivers in X.org: `modesetting`
+(included in the xorg-server itself) and `intel` (provided by the
+package xf86-video-intel).
+
+The default and recommended is `modesetting`. It is a generic driver
+which uses the kernel [mode
+setting](https://en.wikipedia.org/wiki/Mode_setting) (KMS) mechanism. It
+supports Glamor (2D graphics acceleration via OpenGL) and is actively
+maintained but may perform worse in some cases (like in old chipsets).
+
+The second driver, `intel`, is specific to Intel GPUs, but not
+recommended by most distributions: it lacks several modern features (for
+example, it doesn\'t support Glamor) and the package hasn\'t been
+officially updated since 2015.
+
+The results vary depending on the hardware, so you may have to try both
+drivers. Use the option
+[](#opt-services.xserver.videoDrivers)
+to set one. The recommended configuration for modern systems is:
+
+```nix
+services.xserver.videoDrivers = [ "modesetting" ];
+services.xserver.useGlamor = true;
+```
+
+If you experience screen tearing no matter what, this configuration was
+reported to resolve the issue:
+
+```nix
+services.xserver.videoDrivers = [ "intel" ];
+services.xserver.deviceSection = ''
+  Option "DRI" "2"
+  Option "TearFree" "true"
+'';
+```
+
+Note that this will likely downgrade the performance compared to
+`modesetting` or `intel` with DRI 3 (default).
+
+## Proprietary NVIDIA drivers {#sec-x11-graphics-cards-nvidia .unnumbered}
+
+NVIDIA provides a proprietary driver for its graphics cards that has
+better 3D performance than the X.org drivers. It is not enabled by
+default because it's not free software. You can enable it as follows:
+
+```nix
+services.xserver.videoDrivers = [ "nvidia" ];
+```
+
+Or if you have an older card, you may have to use one of the legacy
+drivers:
+
+```nix
+services.xserver.videoDrivers = [ "nvidiaLegacy390" ];
+services.xserver.videoDrivers = [ "nvidiaLegacy340" ];
+services.xserver.videoDrivers = [ "nvidiaLegacy304" ];
+```
+
+You may need to reboot after enabling this driver to prevent a clash
+with other kernel modules.
+
+## Proprietary AMD drivers {#sec-x11--graphics-cards-amd .unnumbered}
+
+AMD provides a proprietary driver for its graphics cards that is not
+enabled by default because it's not Free Software, is often broken in
+nixpkgs and as of this writing doesn\'t offer more features or
+performance. If you still want to use it anyway, you need to explicitly
+set:
+
+```nix
+services.xserver.videoDrivers = [ "amdgpu-pro" ];
+```
+
+You will need to reboot after enabling this driver to prevent a clash
+with other kernel modules.
+
+## Touchpads {#sec-x11-touchpads .unnumbered}
+
+Support for Synaptics touchpads (found in many laptops such as the Dell
+Latitude series) can be enabled as follows:
+
+```nix
+services.xserver.libinput.enable = true;
+```
+
+The driver has many options (see [](#ch-options)).
+For instance, the following disables tap-to-click behavior:
+
+```nix
+services.xserver.libinput.touchpad.tapping = false;
+```
+
+Note: the use of `services.xserver.synaptics` is deprecated since NixOS
+17.09.
+
+## GTK/Qt themes {#sec-x11-gtk-and-qt-themes .unnumbered}
+
+GTK themes can be installed either to user profile or system-wide (via
+`environment.systemPackages`). To make Qt 5 applications look similar to
+GTK ones, you can use the following configuration:
+
+```nix
+qt5.enable = true;
+qt5.platformTheme = "gtk2";
+qt5.style = "gtk2";
+```
+
+## Custom XKB layouts {#custom-xkb-layouts .unnumbered}
+
+It is possible to install custom [ XKB
+](https://en.wikipedia.org/wiki/X_keyboard_extension) keyboard layouts
+using the option `services.xserver.extraLayouts`.
+
+As a first example, we are going to create a layout based on the basic
+US layout, with an additional layer to type some greek symbols by
+pressing the right-alt key.
+
+Create a file called `us-greek` with the following content (under a
+directory called `symbols`; it\'s an XKB peculiarity that will help with
+testing):
+
+```nix
+xkb_symbols "us-greek"
+{
+  include "us(basic)"            // includes the base US keys
+  include "level3(ralt_switch)"  // configures right alt as a third level switch
+
+  key <LatA> { [ a, A, Greek_alpha ] };
+  key <LatB> { [ b, B, Greek_beta  ] };
+  key <LatG> { [ g, G, Greek_gamma ] };
+  key <LatD> { [ d, D, Greek_delta ] };
+  key <LatZ> { [ z, Z, Greek_zeta  ] };
+};
+```
+
+A minimal layout specification must include the following:
+
+```nix
+services.xserver.extraLayouts.us-greek = {
+  description = "US layout with alt-gr greek";
+  languages   = [ "eng" ];
+  symbolsFile = /yourpath/symbols/us-greek;
+};
+```
+
+::: {.note}
+The name (after `extraLayouts.`) should match the one given to the
+`xkb_symbols` block.
+:::
+
+Applying this customization requires rebuilding several packages, and a
+broken XKB file can lead to the X session crashing at login. Therefore,
+you\'re strongly advised to **test your layout before applying it**:
+
+```ShellSession
+$ nix-shell -p xorg.xkbcomp
+$ setxkbmap -I/yourpath us-greek -print | xkbcomp -I/yourpath - $DISPLAY
+```
+
+You can inspect the predefined XKB files for examples:
+
+```ShellSession
+$ echo "$(nix-build --no-out-link '<nixpkgs>' -A xorg.xkeyboardconfig)/etc/X11/xkb/"
+```
+
+Once the configuration is applied, and you did a logout/login cycle, the
+layout should be ready to use. You can try it by e.g. running
+`setxkbmap us-greek` and then type `<alt>+a` (it may not get applied in
+your terminal straight away). To change the default, the usual
+`services.xserver.layout` option can still be used.
+
+A layout can have several other components besides `xkb_symbols`, for
+example we will define new keycodes for some multimedia key and bind
+these to some symbol.
+
+Use the *xev* utility from `pkgs.xorg.xev` to find the codes of the keys
+of interest, then create a `media-key` file to hold the keycodes
+definitions
+
+```nix
+xkb_keycodes "media"
+{
+ <volUp>   = 123;
+ <volDown> = 456;
+}
+```
+
+Now use the newly define keycodes in `media-sym`:
+
+```nix
+xkb_symbols "media"
+{
+ key.type = "ONE_LEVEL";
+ key <volUp>   { [ XF86AudioLowerVolume ] };
+ key <volDown> { [ XF86AudioRaiseVolume ] };
+}
+```
+
+As before, to install the layout do
+
+```nix
+services.xserver.extraLayouts.media = {
+  description  = "Multimedia keys remapping";
+  languages    = [ "eng" ];
+  symbolsFile  = /path/to/media-key;
+  keycodesFile = /path/to/media-sym;
+};
+```
+
+::: {.note}
+The function `pkgs.writeText <filename> <content>` can be useful if you
+prefer to keep the layout definitions inside the NixOS configuration.
+:::
+
+Unfortunately, the Xorg server does not (currently) support setting a
+keymap directly but relies instead on XKB rules to select the matching
+components (keycodes, types, \...) of a layout. This means that
+components other than symbols won\'t be loaded by default. As a
+workaround, you can set the keymap using `setxkbmap` at the start of the
+session with:
+
+```nix
+services.xserver.displayManager.sessionCommands = "setxkbmap -keycodes media";
+```
+
+If you are manually starting the X server, you should set the argument
+`-xkbdir /etc/X11/xkb`, otherwise X won\'t find your layout files. For
+example with `xinit` run
+
+```ShellSession
+$ xinit -- -xkbdir /etc/X11/xkb
+```
+
+To learn how to write layouts take a look at the XKB [documentation
+](https://www.x.org/releases/current/doc/xorg-docs/input/XKB-Enhancing.html#Defining_New_Layouts).
+More example layouts can also be found [here
+](https://wiki.archlinux.org/index.php/X_KeyBoard_extension#Basic_examples).
diff --git a/nixos/doc/manual/configuration/x-windows.xml b/nixos/doc/manual/configuration/x-windows.xml
deleted file mode 100644
index f9121508d7d..00000000000
--- a/nixos/doc/manual/configuration/x-windows.xml
+++ /dev/null
@@ -1,355 +0,0 @@
-<chapter 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="sec-x11">
- <title>X Window System</title>
- <para>
-  The X Window System (X11) provides the basis of NixOS’ graphical user
-  interface. It can be enabled as follows:
-<programlisting>
-<xref linkend="opt-services.xserver.enable"/> = true;
-</programlisting>
-  The X server will automatically detect and use the appropriate video driver
-  from a set of X.org drivers (such as <literal>vesa</literal> and
-  <literal>intel</literal>). You can also specify a driver manually, e.g.
-<programlisting>
-<xref linkend="opt-services.xserver.videoDrivers"/> = [ "r128" ];
-</programlisting>
-  to enable X.org’s <literal>xf86-video-r128</literal> driver.
- </para>
- <para>
-  You also need to enable at least one desktop or window manager. Otherwise,
-  you can only log into a plain undecorated <command>xterm</command> window.
-  Thus you should pick one or more of the following lines:
-<programlisting>
-<xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/> = true;
-<xref linkend="opt-services.xserver.desktopManager.xfce.enable"/> = true;
-<xref linkend="opt-services.xserver.desktopManager.gnome.enable"/> = true;
-<xref linkend="opt-services.xserver.desktopManager.mate.enable"/> = true;
-<xref linkend="opt-services.xserver.windowManager.xmonad.enable"/> = true;
-<xref linkend="opt-services.xserver.windowManager.twm.enable"/> = true;
-<xref linkend="opt-services.xserver.windowManager.icewm.enable"/> = true;
-<xref linkend="opt-services.xserver.windowManager.i3.enable"/> = true;
-<xref linkend="opt-services.xserver.windowManager.herbstluftwm.enable"/> = true;
-</programlisting>
- </para>
- <para>
-  NixOS’s default <emphasis>display manager</emphasis> (the program that
-  provides a graphical login prompt and manages the X server) is LightDM. You
-  can select an alternative one by picking one of the following lines:
-<programlisting>
-<xref linkend="opt-services.xserver.displayManager.sddm.enable"/> = true;
-<xref linkend="opt-services.xserver.displayManager.gdm.enable"/> = true;
-</programlisting>
- </para>
- <para>
-  You can set the keyboard layout (and optionally the layout variant):
-<programlisting>
-<xref linkend="opt-services.xserver.layout"/> = "de";
-<xref linkend="opt-services.xserver.xkbVariant"/> = "neo";
-</programlisting>
- </para>
- <para>
-  The X server is started automatically at boot time. If you don’t want this
-  to happen, you can set:
-<programlisting>
-<xref linkend="opt-services.xserver.autorun"/> = false;
-</programlisting>
-  The X server can then be started manually:
-<screen>
-<prompt># </prompt>systemctl start display-manager.service
-</screen>
- </para>
- <para>
-  On 64-bit systems, if you want OpenGL for 32-bit programs such as in Wine,
-  you should also set the following:
-<programlisting>
-<xref linkend="opt-hardware.opengl.driSupport32Bit"/> = true;
-</programlisting>
- </para>
- <simplesect xml:id="sec-x11-auto-login">
-  <title>Auto-login</title>
-  <para>
-  The x11 login screen can be skipped entirely, automatically logging you into
-  your window manager and desktop environment when you boot your computer.
-  </para>
-  <para>
-  This is especially helpful if you have disk encryption enabled. Since you
-  already have to provide a password to decrypt your disk, entering a second
-  password to login can be redundant.
-  </para>
-  <para>
-  To enable auto-login, you need to define your default window manager and
-  desktop environment. If you wanted no desktop environment and i3 as your your
-  window manager, you'd define:
-<programlisting>
-<xref linkend="opt-services.xserver.displayManager.defaultSession"/> = "none+i3";
-</programlisting>
-  Every display manager in NixOS supports auto-login, here is an example
-  using lightdm for a user <literal>alice</literal>:
-<programlisting>
-<xref linkend="opt-services.xserver.displayManager.lightdm.enable"/> = true;
-<xref linkend="opt-services.xserver.displayManager.autoLogin.enable"/> = true;
-<xref linkend="opt-services.xserver.displayManager.autoLogin.user"/> = "alice";
-</programlisting>
-  </para>
- </simplesect>
- <simplesect xml:id="sec-x11--graphics-cards-intel">
-  <title>Intel Graphics drivers</title>
-  <para>
-   There are two choices for Intel Graphics drivers in X.org:
-   <literal>modesetting</literal> (included in the <package>xorg-server</package> itself)
-   and <literal>intel</literal> (provided by the package <package>xf86-video-intel</package>).
-  </para>
-  <para>
-   The default and recommended is <literal>modesetting</literal>.
-   It is a generic driver which uses the kernel
-   <link xlink:href="https://en.wikipedia.org/wiki/Mode_setting">mode setting</link>
-   (KMS) mechanism. It supports Glamor (2D graphics acceleration via OpenGL)
-   and is actively maintained but may perform worse in some cases (like in old chipsets).
-  </para>
-  <para>
-   The second driver, <literal>intel</literal>, is specific to Intel GPUs,
-   but not recommended by most distributions: it lacks several modern features
-   (for example, it doesn't support Glamor) and the package hasn't been officially
-   updated since 2015.
-  </para>
-  <para>
-   The results vary depending on the hardware, so you may have to try both drivers.
-   Use the option <xref linkend="opt-services.xserver.videoDrivers"/> to set one.
-   The recommended configuration for modern systems is:
-<programlisting>
-  <xref linkend="opt-services.xserver.videoDrivers"/> = [ "modesetting" ];
-  <xref linkend="opt-services.xserver.useGlamor"/> = true;
-</programlisting>
-   If you experience screen tearing no matter what, this configuration was
-   reported to resolve the issue:
-<programlisting>
-  <xref linkend="opt-services.xserver.videoDrivers"/> = [ "intel" ];
-  <xref linkend="opt-services.xserver.deviceSection"/> = ''
-    Option "DRI" "2"
-    Option "TearFree" "true"
-  '';
-</programlisting>
-   Note that this will likely downgrade the performance compared to
-  <literal>modesetting</literal> or <literal>intel</literal> with DRI 3 (default).
-  </para>
- </simplesect>
- <simplesect xml:id="sec-x11-graphics-cards-nvidia">
-  <title>Proprietary NVIDIA drivers</title>
-  <para>
-   NVIDIA provides a proprietary driver for its graphics cards that has better
-   3D performance than the X.org drivers. It is not enabled by default because
-   it’s not free software. You can enable it as follows:
-<programlisting>
-<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidia" ];
-</programlisting>
-   Or if you have an older card, you may have to use one of the legacy drivers:
-<programlisting>
-<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy390" ];
-<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy340" ];
-<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy304" ];
-</programlisting>
-   You may need to reboot after enabling this driver to prevent a clash with
-   other kernel modules.
-  </para>
- </simplesect>
- <simplesect xml:id="sec-x11--graphics-cards-amd">
-  <title>Proprietary AMD drivers</title>
-  <para>
-   AMD provides a proprietary driver for its graphics cards that is not
-   enabled by default because it’s not Free Software, is often broken
-   in nixpkgs and as of this writing doesn't offer more features or
-   performance. If you still want to use it anyway, you need to explicitly set:
-<programlisting>
-<xref linkend="opt-services.xserver.videoDrivers"/> = [ "amdgpu-pro" ];
-</programlisting>
-   You will need to reboot after enabling this driver to prevent a clash with
-   other kernel modules.
-  </para>
- </simplesect>
- <simplesect xml:id="sec-x11-touchpads">
-  <title>Touchpads</title>
-  <para>
-   Support for Synaptics touchpads (found in many laptops such as the Dell
-   Latitude series) can be enabled as follows:
-<programlisting>
-<xref linkend="opt-services.xserver.libinput.enable"/> = true;
-</programlisting>
-   The driver has many options (see <xref linkend="ch-options"/>). For
-   instance, the following disables tap-to-click behavior:
-<programlisting>
-<xref linkend="opt-services.xserver.libinput.touchpad.tapping"/> = false;
-</programlisting>
-   Note: the use of <literal>services.xserver.synaptics</literal> is deprecated
-   since NixOS 17.09.
-  </para>
- </simplesect>
- <simplesect xml:id="sec-x11-gtk-and-qt-themes">
-  <title>GTK/Qt themes</title>
-  <para>
-   GTK themes can be installed either to user profile or system-wide (via
-   <literal>environment.systemPackages</literal>). To make Qt 5 applications
-   look similar to GTK ones, you can use the following configuration:
-<programlisting>
-<xref linkend="opt-qt5.enable"/> = true;
-<xref linkend="opt-qt5.platformTheme"/> = "gtk2";
-<xref linkend="opt-qt5.style"/> = "gtk2";
-</programlisting>
-  </para>
- </simplesect>
- <simplesect xml:id="custom-xkb-layouts">
-  <title>Custom XKB layouts</title>
-  <para>
-   It is possible to install custom
-   <link xlink:href="https://en.wikipedia.org/wiki/X_keyboard_extension">
-    XKB
-   </link>
-   keyboard layouts using the option
-   <option><link linkend="opt-services.xserver.extraLayouts">
-     services.xserver.extraLayouts</link></option>.
-  </para>
-  <para>
-   As a first example, we are going to create a layout based on the basic US
-   layout, with an additional layer to type some greek symbols by pressing the
-   right-alt key.
-  </para>
-  <para>
-   Create a file called <literal>us-greek</literal> with the following
-   content (under a directory called <literal>symbols</literal>; it's
-   an XKB peculiarity that will help with testing):
-  </para>
-<programlisting>
-xkb_symbols &quot;us-greek&quot;
-{
-  include &quot;us(basic)&quot;            // includes the base US keys
-  include &quot;level3(ralt_switch)&quot;  // configures right alt as a third level switch
-
-  key &lt;LatA&gt; { [ a, A, Greek_alpha ] };
-  key &lt;LatB&gt; { [ b, B, Greek_beta  ] };
-  key &lt;LatG&gt; { [ g, G, Greek_gamma ] };
-  key &lt;LatD&gt; { [ d, D, Greek_delta ] };
-  key &lt;LatZ&gt; { [ z, Z, Greek_zeta  ] };
-};
-</programlisting>
-  <para>
-   A minimal layout specification must include the following:
-  </para>
-<programlisting>
-<xref linkend="opt-services.xserver.extraLayouts"/>.us-greek = {
-  description = "US layout with alt-gr greek";
-  languages   = [ "eng" ];
-  symbolsFile = /yourpath/symbols/us-greek;
-};
-</programlisting>
-  <note>
-  <para>
-   The name (after <literal>extraLayouts.</literal>) should match the one given to the
-   <literal>xkb_symbols</literal> block.
-  </para>
-  </note>
-  <para>
-   Applying this customization requires rebuilding several packages,
-   and a broken XKB file can lead to the X session crashing at login.
-   Therefore, you're strongly advised to <emphasis role="strong">test
-   your layout before applying it</emphasis>:
-<screen>
-<prompt>$ </prompt>nix-shell -p xorg.xkbcomp
-<prompt>$ </prompt>setxkbmap -I/yourpath us-greek -print | xkbcomp -I/yourpath - $DISPLAY
-</screen>
-  </para>
-  <para>
-   You can inspect the predefined XKB files for examples:
-<screen>
-<prompt>$ </prompt>echo "$(nix-build --no-out-link '&lt;nixpkgs&gt;' -A xorg.xkeyboardconfig)/etc/X11/xkb/"
-</screen>
-  </para>
-  <para>
-   Once the configuration is applied, and you did a logout/login
-   cycle, the layout should be ready to use. You can try it by e.g.
-   running <literal>setxkbmap us-greek</literal> and then type
-   <literal>&lt;alt&gt;+a</literal> (it may not get applied in your
-   terminal straight away). To change the default, the usual
-   <option>
-    <link linkend="opt-services.xserver.layout">
-     services.xserver.layout
-    </link>
-   </option>
-   option can still be used.
-  </para>
-  <para>
-   A layout can have several other components besides
-   <literal>xkb_symbols</literal>, for example we will define new
-   keycodes for some multimedia key and bind these to some symbol.
-  </para>
-  <para>
-   Use the <emphasis>xev</emphasis> utility from
-   <literal>pkgs.xorg.xev</literal> to find the codes of the keys of
-   interest, then create a <literal>media-key</literal> file to hold
-   the keycodes definitions
-  </para>
-<programlisting>
-xkb_keycodes &quot;media&quot;
-{
- &lt;volUp&gt;   = 123;
- &lt;volDown&gt; = 456;
-}
-</programlisting>
-  <para>
-    Now use the newly define keycodes in <literal>media-sym</literal>:
-  </para>
-<programlisting>
-xkb_symbols &quot;media&quot;
-{
- key.type = &quot;ONE_LEVEL&quot;;
- key &lt;volUp&gt;   { [ XF86AudioLowerVolume ] };
- key &lt;volDown&gt; { [ XF86AudioRaiseVolume ] };
-}
-</programlisting>
-  <para>
-    As before, to install the layout do
-  </para>
-<programlisting>
-<xref linkend="opt-services.xserver.extraLayouts"/>.media = {
-  description  = "Multimedia keys remapping";
-  languages    = [ "eng" ];
-  symbolsFile  = /path/to/media-key;
-  keycodesFile = /path/to/media-sym;
-};
-</programlisting>
-  <note>
-  <para>
-   The function <literal>pkgs.writeText &lt;filename&gt; &lt;content&gt;
-   </literal> can be useful if you prefer to keep the layout definitions
-   inside the NixOS configuration.
-  </para>
-  </note>
-  <para>
-    Unfortunately, the Xorg server does not (currently) support setting a
-    keymap directly but relies instead on XKB rules to select the matching
-    components (keycodes, types, ...) of a layout. This means that components
-    other than symbols won't be loaded by default. As a workaround, you
-    can set the keymap using <literal>setxkbmap</literal> at the start of the
-    session with:
-  </para>
-<programlisting>
-<xref linkend="opt-services.xserver.displayManager.sessionCommands"/> = "setxkbmap -keycodes media";
-</programlisting>
-  <para>
-    If you are manually starting the X server, you should set the argument
-    <literal>-xkbdir /etc/X11/xkb</literal>, otherwise X won't find your layout files.
-    For example with <command>xinit</command> run
-    <screen><prompt>$ </prompt>xinit -- -xkbdir /etc/X11/xkb</screen>
-  </para>
-  <para>
-   To learn how to write layouts take a look at the XKB
-  <link xlink:href="https://www.x.org/releases/current/doc/xorg-docs/input/XKB-Enhancing.html#Defining_New_Layouts">
-   documentation
-  </link>. More example layouts can also be found
-  <link xlink:href="https://wiki.archlinux.org/index.php/X_KeyBoard_extension#Basic_examples">
-   here
-  </link>.
-  </para>
-</simplesect>
-</chapter>
diff --git a/nixos/doc/manual/configuration/xfce.chapter.md b/nixos/doc/manual/configuration/xfce.chapter.md
new file mode 100644
index 00000000000..b0ef6682aae
--- /dev/null
+++ b/nixos/doc/manual/configuration/xfce.chapter.md
@@ -0,0 +1,52 @@
+# Xfce Desktop Environment {#sec-xfce}
+
+To enable the Xfce Desktop Environment, set
+
+```nix
+services.xserver.desktopManager.xfce.enable = true;
+services.xserver.displayManager.defaultSession = "xfce";
+```
+
+Optionally, *picom* can be enabled for nice graphical effects, some
+example settings:
+
+```nix
+services.picom = {
+  enable = true;
+  fade = true;
+  inactiveOpacity = 0.9;
+  shadow = true;
+  fadeDelta = 4;
+};
+```
+
+Some Xfce programs are not installed automatically. To install them
+manually (system wide), put them into your
+[](#opt-environment.systemPackages) from `pkgs.xfce`.
+
+## Thunar Plugins {#sec-xfce-thunar-plugins .unnumbered}
+
+If you\'d like to add extra plugins to Thunar, add them to
+[](#opt-services.xserver.desktopManager.xfce.thunarPlugins).
+You shouldn\'t just add them to [](#opt-environment.systemPackages).
+
+## Troubleshooting {#sec-xfce-troubleshooting .unnumbered}
+
+Even after enabling udisks2, volume management might not work. Thunar
+and/or the desktop takes time to show up. Thunar will spit out this kind
+of message on start (look at `journalctl --user -b`).
+
+```plain
+Thunar:2410): GVFS-RemoteVolumeMonitor-WARNING **: remote volume monitor with dbus name org.gtk.Private.UDisks2VolumeMonitor is not supported
+```
+
+This is caused by some needed GNOME services not running. This is all
+fixed by enabling \"Launch GNOME services on startup\" in the Advanced
+tab of the Session and Startup settings panel. Alternatively, you can
+run this command to do the same thing.
+
+```ShellSession
+$ xfconf-query -c xfce4-session -p /compat/LaunchGNOME -s true
+```
+
+A log-out and re-log will be needed for this to take effect.
diff --git a/nixos/doc/manual/configuration/xfce.xml b/nixos/doc/manual/configuration/xfce.xml
deleted file mode 100644
index abcf5f648a4..00000000000
--- a/nixos/doc/manual/configuration/xfce.xml
+++ /dev/null
@@ -1,59 +0,0 @@
-<chapter 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="sec-xfce">
- <title>Xfce Desktop Environment</title>
- <para>
-  To enable the Xfce Desktop Environment, set
-<programlisting>
-<xref linkend="opt-services.xserver.desktopManager.xfce.enable" /> = true;
-<xref linkend="opt-services.xserver.displayManager.defaultSession" /> = "xfce";
-</programlisting>
- </para>
- <para>
-  Optionally, <emphasis>picom</emphasis> can be enabled for nice graphical
-  effects, some example settings:
-<programlisting>
-<link linkend="opt-services.picom.enable">services.picom</link> = {
-  <link linkend="opt-services.picom.enable">enable</link> = true;
-  <link linkend="opt-services.picom.fade">fade</link> = true;
-  <link linkend="opt-services.picom.inactiveOpacity">inactiveOpacity</link> = 0.9;
-  <link linkend="opt-services.picom.shadow">shadow</link> = true;
-  <link linkend="opt-services.picom.fadeDelta">fadeDelta</link> = 4;
-};
-</programlisting>
- </para>
- <para>
-  Some Xfce programs are not installed automatically. To install them manually
-  (system wide), put them into your
-  <xref linkend="opt-environment.systemPackages"/> from <literal>pkgs.xfce</literal>.
- </para>
- <simplesect xml:id="sec-xfce-thunar-plugins">
-  <title>Thunar Plugins</title>
-  <para>
-    If you'd like to add extra plugins to Thunar, add them to
-    <xref linkend="opt-services.xserver.desktopManager.xfce.thunarPlugins"/>.
-    You shouldn't just add them to <xref linkend="opt-environment.systemPackages"/>.
-  </para>
- </simplesect>
- <simplesect xml:id="sec-xfce-troubleshooting">
-  <title>Troubleshooting</title>
-  <para>
-   Even after enabling udisks2, volume management might not work. Thunar and/or
-   the desktop takes time to show up. Thunar will spit out this kind of message
-   on start (look at <command>journalctl --user -b</command>).
-<programlisting>
-Thunar:2410): GVFS-RemoteVolumeMonitor-WARNING **: remote volume monitor with dbus name org.gtk.Private.UDisks2VolumeMonitor is not supported
-</programlisting>
-   This is caused by some needed GNOME services not running. This is all fixed
-   by enabling "Launch GNOME services on startup" in the Advanced tab of the
-   Session and Startup settings panel. Alternatively, you can run this command
-   to do the same thing.
-<programlisting>
-<prompt>$ </prompt>xfconf-query -c xfce4-session -p /compat/LaunchGNOME -s true
-</programlisting>
-   A log-out and re-log will be needed for this to take effect.
-  </para>
- </simplesect>
-</chapter>
diff --git a/nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml b/nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml
new file mode 100644
index 00000000000..8e780c5dee9
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/gpu-accel.chapter.xml
@@ -0,0 +1,239 @@
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-gpu-accel">
+  <title>GPU acceleration</title>
+  <para>
+    NixOS provides various APIs that benefit from GPU hardware
+    acceleration, such as VA-API and VDPAU for video playback; OpenGL
+    and Vulkan for 3D graphics; and OpenCL for general-purpose
+    computing. This chapter describes how to set up GPU hardware
+    acceleration (as far as this is not done automatically) and how to
+    verify that hardware acceleration is indeed used.
+  </para>
+  <para>
+    Most of the aforementioned APIs are agnostic with regards to which
+    display server is used. Consequently, these instructions should
+    apply both to the X Window System and Wayland compositors.
+  </para>
+  <section xml:id="sec-gpu-accel-opencl">
+    <title>OpenCL</title>
+    <para>
+      <link xlink:href="https://en.wikipedia.org/wiki/OpenCL">OpenCL</link>
+      is a general compute API. It is used by various applications such
+      as Blender and Darktable to accelerate certain operations.
+    </para>
+    <para>
+      OpenCL applications load drivers through the <emphasis>Installable
+      Client Driver</emphasis> (ICD) mechanism. In this mechanism, an
+      ICD file specifies the path to the OpenCL driver for a particular
+      GPU family. In NixOS, there are two ways to make ICD files visible
+      to the ICD loader. The first is through the
+      <literal>OCL_ICD_VENDORS</literal> environment variable. This
+      variable can contain a directory which is scanned by the ICL
+      loader for ICD files. For example:
+    </para>
+    <programlisting>
+$ export \
+  OCL_ICD_VENDORS=`nix-build '&lt;nixpkgs&gt;' --no-out-link -A rocm-opencl-icd`/etc/OpenCL/vendors/
+</programlisting>
+    <para>
+      The second mechanism is to add the OpenCL driver package to
+      <xref linkend="opt-hardware.opengl.extraPackages" />. This links
+      the ICD file under <literal>/run/opengl-driver</literal>, where it
+      will be visible to the ICD loader.
+    </para>
+    <para>
+      The proper installation of OpenCL drivers can be verified through
+      the <literal>clinfo</literal> command of the clinfo package. This
+      command will report the number of hardware devices that is found
+      and give detailed information for each device:
+    </para>
+    <programlisting>
+$ clinfo | head -n3
+Number of platforms  1
+Platform Name        AMD Accelerated Parallel Processing
+Platform Vendor      Advanced Micro Devices, Inc.
+</programlisting>
+    <section xml:id="sec-gpu-accel-opencl-amd">
+      <title>AMD</title>
+      <para>
+        Modern AMD
+        <link xlink:href="https://en.wikipedia.org/wiki/Graphics_Core_Next">Graphics
+        Core Next</link> (GCN) GPUs are supported through the
+        rocm-opencl-icd package. Adding this package to
+        <xref linkend="opt-hardware.opengl.extraPackages" /> enables
+        OpenCL support:
+      </para>
+      <programlisting language="bash">
+hardware.opengl.extraPackages = [
+  rocm-opencl-icd
+];
+</programlisting>
+    </section>
+    <section xml:id="sec-gpu-accel-opencl-intel">
+      <title>Intel</title>
+      <para>
+        <link xlink:href="https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units#Gen8">Intel
+        Gen8 and later GPUs</link> are supported by the Intel NEO OpenCL
+        runtime that is provided by the intel-compute-runtime package.
+        For Gen7 GPUs, the deprecated Beignet runtime can be used, which
+        is provided by the beignet package. The proprietary Intel OpenCL
+        runtime, in the intel-ocl package, is an alternative for Gen7
+        GPUs.
+      </para>
+      <para>
+        The intel-compute-runtime, beignet, or intel-ocl package can be
+        added to <xref linkend="opt-hardware.opengl.extraPackages" /> to
+        enable OpenCL support. For example, for Gen8 and later GPUs, the
+        following configuration can be used:
+      </para>
+      <programlisting language="bash">
+hardware.opengl.extraPackages = [
+  intel-compute-runtime
+];
+</programlisting>
+    </section>
+  </section>
+  <section xml:id="sec-gpu-accel-vulkan">
+    <title>Vulkan</title>
+    <para>
+      <link xlink:href="https://en.wikipedia.org/wiki/Vulkan_(API)">Vulkan</link>
+      is a graphics and compute API for GPUs. It is used directly by
+      games or indirectly though compatibility layers like
+      <link xlink:href="https://github.com/doitsujin/dxvk/wiki">DXVK</link>.
+    </para>
+    <para>
+      By default, if <xref linkend="opt-hardware.opengl.driSupport" />
+      is enabled, mesa is installed and provides Vulkan for supported
+      hardware.
+    </para>
+    <para>
+      Similar to OpenCL, Vulkan drivers are loaded through the
+      <emphasis>Installable Client Driver</emphasis> (ICD) mechanism.
+      ICD files for Vulkan are JSON files that specify the path to the
+      driver library and the supported Vulkan version. All successfully
+      loaded drivers are exposed to the application as different GPUs.
+      In NixOS, there are two ways to make ICD files visible to Vulkan
+      applications: an environment variable and a module option.
+    </para>
+    <para>
+      The first option is through the
+      <literal>VK_ICD_FILENAMES</literal> environment variable. This
+      variable can contain multiple JSON files, separated by
+      <literal>:</literal>. For example:
+    </para>
+    <programlisting>
+$ export \
+  VK_ICD_FILENAMES=`nix-build '&lt;nixpkgs&gt;' --no-out-link -A amdvlk`/share/vulkan/icd.d/amd_icd64.json
+</programlisting>
+    <para>
+      The second mechanism is to add the Vulkan driver package to
+      <xref linkend="opt-hardware.opengl.extraPackages" />. This links
+      the ICD file under <literal>/run/opengl-driver</literal>, where it
+      will be visible to the ICD loader.
+    </para>
+    <para>
+      The proper installation of Vulkan drivers can be verified through
+      the <literal>vulkaninfo</literal> command of the vulkan-tools
+      package. This command will report the hardware devices and drivers
+      found, in this example output amdvlk and radv:
+    </para>
+    <programlisting>
+$ vulkaninfo | grep GPU
+                GPU id  : 0 (Unknown AMD GPU)
+                GPU id  : 1 (AMD RADV NAVI10 (LLVM 9.0.1))
+     ...
+GPU0:
+        deviceType     = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU
+        deviceName     = Unknown AMD GPU
+GPU1:
+        deviceType     = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU
+</programlisting>
+    <para>
+      A simple graphical application that uses Vulkan is
+      <literal>vkcube</literal> from the vulkan-tools package.
+    </para>
+    <section xml:id="sec-gpu-accel-vulkan-amd">
+      <title>AMD</title>
+      <para>
+        Modern AMD
+        <link xlink:href="https://en.wikipedia.org/wiki/Graphics_Core_Next">Graphics
+        Core Next</link> (GCN) GPUs are supported through either radv,
+        which is part of mesa, or the amdvlk package. Adding the amdvlk
+        package to <xref linkend="opt-hardware.opengl.extraPackages" />
+        makes amdvlk the default driver and hides radv and lavapipe from
+        the device list. A specific driver can be forced as follows:
+      </para>
+      <programlisting language="bash">
+hardware.opengl.extraPackages = [
+  pkgs.amdvlk
+];
+
+# To enable Vulkan support for 32-bit applications, also add:
+hardware.opengl.extraPackages32 = [
+  pkgs.driversi686Linux.amdvlk
+];
+
+# Force radv
+environment.variables.AMD_VULKAN_ICD = &quot;RADV&quot;;
+# Or
+environment.variables.VK_ICD_FILENAMES =
+  &quot;/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json&quot;;
+</programlisting>
+    </section>
+  </section>
+  <section xml:id="sec-gpu-accel-common-issues">
+    <title>Common issues</title>
+    <section xml:id="sec-gpu-accel-common-issues-permissions">
+      <title>User permissions</title>
+      <para>
+        Except where noted explicitly, it should not be necessary to
+        adjust user permissions to use these acceleration APIs. In the
+        default configuration, GPU devices have world-read/write
+        permissions (<literal>/dev/dri/renderD*</literal>) or are tagged
+        as <literal>uaccess</literal>
+        (<literal>/dev/dri/card*</literal>). The access control lists of
+        devices with the <literal>uaccess</literal> tag will be updated
+        automatically when a user logs in through
+        <literal>systemd-logind</literal>. For example, if the user
+        <emphasis>jane</emphasis> is logged in, the access control list
+        should look as follows:
+      </para>
+      <programlisting>
+$ getfacl /dev/dri/card0
+# file: dev/dri/card0
+# owner: root
+# group: video
+user::rw-
+user:jane:rw-
+group::rw-
+mask::rw-
+other::---
+</programlisting>
+      <para>
+        If you disabled (this functionality of)
+        <literal>systemd-logind</literal>, you may need to add the user
+        to the <literal>video</literal> group and log in again.
+      </para>
+    </section>
+    <section xml:id="sec-gpu-accel-common-issues-mixing-nixpkgs">
+      <title>Mixing different versions of nixpkgs</title>
+      <para>
+        The <emphasis>Installable Client Driver</emphasis> (ICD)
+        mechanism used by OpenCL and Vulkan loads runtimes into its
+        address space using <literal>dlopen</literal>. Mixing an ICD
+        loader mechanism and runtimes from different version of nixpkgs
+        may not work. For example, if the ICD loader uses an older
+        version of glibc than the runtime, the runtime may not be
+        loadable due to missing symbols. Unfortunately, the loader will
+        generally be quiet about such issues.
+      </para>
+      <para>
+        If you suspect that you are running into library version
+        mismatches between an ICL loader and a runtime, you could run an
+        application with the <literal>LD_DEBUG</literal> variable set to
+        get more diagnostic information. For example, OpenCL can be
+        tested with <literal>LD_DEBUG=files clinfo</literal>, which
+        should report missing symbols.
+      </para>
+    </section>
+  </section>
+</chapter>
diff --git a/nixos/doc/manual/from_md/configuration/kubernetes.chapter.xml b/nixos/doc/manual/from_md/configuration/kubernetes.chapter.xml
new file mode 100644
index 00000000000..83a50d7c49d
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/kubernetes.chapter.xml
@@ -0,0 +1,126 @@
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-kubernetes">
+  <title>Kubernetes</title>
+  <para>
+    The NixOS Kubernetes module is a collective term for a handful of
+    individual submodules implementing the Kubernetes cluster
+    components.
+  </para>
+  <para>
+    There are generally two ways of enabling Kubernetes on NixOS. One
+    way is to enable and configure cluster components appropriately by
+    hand:
+  </para>
+  <programlisting language="bash">
+services.kubernetes = {
+  apiserver.enable = true;
+  controllerManager.enable = true;
+  scheduler.enable = true;
+  addonManager.enable = true;
+  proxy.enable = true;
+  flannel.enable = true;
+};
+</programlisting>
+  <para>
+    Another way is to assign cluster roles (&quot;master&quot; and/or
+    &quot;node&quot;) to the host. This enables apiserver,
+    controllerManager, scheduler, addonManager, kube-proxy and etcd:
+  </para>
+  <programlisting language="bash">
+services.kubernetes.roles = [ &quot;master&quot; ];
+</programlisting>
+  <para>
+    While this will enable the kubelet and kube-proxy only:
+  </para>
+  <programlisting language="bash">
+services.kubernetes.roles = [ &quot;node&quot; ];
+</programlisting>
+  <para>
+    Assigning both the master and node roles is usable if you want a
+    single node Kubernetes cluster for dev or testing purposes:
+  </para>
+  <programlisting language="bash">
+services.kubernetes.roles = [ &quot;master&quot; &quot;node&quot; ];
+</programlisting>
+  <para>
+    Note: Assigning either role will also default both
+    <xref linkend="opt-services.kubernetes.flannel.enable" /> and
+    <xref linkend="opt-services.kubernetes.easyCerts" /> to true. This
+    sets up flannel as CNI and activates automatic PKI bootstrapping.
+  </para>
+  <para>
+    As of kubernetes 1.10.X it has been deprecated to open
+    non-tls-enabled ports on kubernetes components. Thus, from NixOS
+    19.03 all plain HTTP ports have been disabled by default. While
+    opening insecure ports is still possible, it is recommended not to
+    bind these to other interfaces than loopback. To re-enable the
+    insecure port on the apiserver, see options:
+    <xref linkend="opt-services.kubernetes.apiserver.insecurePort" />
+    and
+    <xref linkend="opt-services.kubernetes.apiserver.insecureBindAddress" />
+  </para>
+  <note>
+    <para>
+      As of NixOS 19.03, it is mandatory to configure:
+      <xref linkend="opt-services.kubernetes.masterAddress" />. The
+      masterAddress must be resolveable and routeable by all cluster
+      nodes. In single node clusters, this can be set to
+      <literal>localhost</literal>.
+    </para>
+  </note>
+  <para>
+    Role-based access control (RBAC) authorization mode is enabled by
+    default. This means that anonymous requests to the apiserver secure
+    port will expectedly cause a permission denied error. All cluster
+    components must therefore be configured with x509 certificates for
+    two-way tls communication. The x509 certificate subject section
+    determines the roles and permissions granted by the apiserver to
+    perform clusterwide or namespaced operations. See also:
+    <link xlink:href="https://kubernetes.io/docs/reference/access-authn-authz/rbac/">
+    Using RBAC Authorization</link>.
+  </para>
+  <para>
+    The NixOS kubernetes module provides an option for automatic
+    certificate bootstrapping and configuration,
+    <xref linkend="opt-services.kubernetes.easyCerts" />. The PKI
+    bootstrapping process involves setting up a certificate authority
+    (CA) daemon (cfssl) on the kubernetes master node. cfssl generates a
+    CA-cert for the cluster, and uses the CA-cert for signing
+    subordinate certs issued to each of the cluster components.
+    Subsequently, the certmgr daemon monitors active certificates and
+    renews them when needed. For single node Kubernetes clusters,
+    setting <xref linkend="opt-services.kubernetes.easyCerts" /> = true
+    is sufficient and no further action is required. For joining extra
+    node machines to an existing cluster on the other hand, establishing
+    initial trust is mandatory.
+  </para>
+  <para>
+    To add new nodes to the cluster: On any (non-master) cluster node
+    where <xref linkend="opt-services.kubernetes.easyCerts" /> is
+    enabled, the helper script
+    <literal>nixos-kubernetes-node-join</literal> is available on PATH.
+    Given a token on stdin, it will copy the token to the kubernetes
+    secrets directory and restart the certmgr service. As requested
+    certificates are issued, the script will restart kubernetes cluster
+    components as needed for them to pick up new keypairs.
+  </para>
+  <note>
+    <para>
+      Multi-master (HA) clusters are not supported by the easyCerts
+      module.
+    </para>
+  </note>
+  <para>
+    In order to interact with an RBAC-enabled cluster as an
+    administrator, one needs to have cluster-admin privileges. By
+    default, when easyCerts is enabled, a cluster-admin kubeconfig file
+    is generated and linked into
+    <literal>/etc/kubernetes/cluster-admin.kubeconfig</literal> as
+    determined by
+    <xref linkend="opt-services.kubernetes.pki.etcClusterAdminKubeconfig" />.
+    <literal>export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig</literal>
+    will make kubectl use this kubeconfig to access and authenticate the
+    cluster. The cluster-admin kubeconfig references an auto-generated
+    keypair owned by root. Thus, only root on the kubernetes master may
+    obtain cluster-admin rights by means of this file.
+  </para>
+</chapter>
diff --git a/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml b/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml
new file mode 100644
index 00000000000..f804d0a3b8c
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml
@@ -0,0 +1,150 @@
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-kernel-config">
+  <title>Linux Kernel</title>
+  <para>
+    You can override the Linux kernel and associated packages using the
+    option <literal>boot.kernelPackages</literal>. For instance, this
+    selects the Linux 3.10 kernel:
+  </para>
+  <programlisting language="bash">
+boot.kernelPackages = pkgs.linuxPackages_3_10;
+</programlisting>
+  <para>
+    Note that this not only replaces the kernel, but also packages that
+    are specific to the kernel version, such as the NVIDIA video
+    drivers. This ensures that driver packages are consistent with the
+    kernel.
+  </para>
+  <para>
+    The default Linux kernel configuration should be fine for most
+    users. You can see the configuration of your current kernel with the
+    following command:
+  </para>
+  <programlisting>
+zcat /proc/config.gz
+</programlisting>
+  <para>
+    If you want to change the kernel configuration, you can use the
+    <literal>packageOverrides</literal> feature (see
+    <xref linkend="sec-customising-packages" />). For instance, to
+    enable support for the kernel debugger KGDB:
+  </para>
+  <programlisting language="bash">
+nixpkgs.config.packageOverrides = pkgs:
+  { linux_3_4 = pkgs.linux_3_4.override {
+      extraConfig =
+        ''
+          KGDB y
+        '';
+    };
+  };
+</programlisting>
+  <para>
+    <literal>extraConfig</literal> takes a list of Linux kernel
+    configuration options, one per line. The name of the option should
+    not include the prefix <literal>CONFIG_</literal>. The option value
+    is typically <literal>y</literal>, <literal>n</literal> or
+    <literal>m</literal> (to build something as a kernel module).
+  </para>
+  <para>
+    Kernel modules for hardware devices are generally loaded
+    automatically by <literal>udev</literal>. You can force a module to
+    be loaded via <xref linkend="opt-boot.kernelModules" />, e.g.
+  </para>
+  <programlisting language="bash">
+boot.kernelModules = [ &quot;fuse&quot; &quot;kvm-intel&quot; &quot;coretemp&quot; ];
+</programlisting>
+  <para>
+    If the module is required early during the boot (e.g. to mount the
+    root file system), you can use
+    <xref linkend="opt-boot.initrd.kernelModules" />:
+  </para>
+  <programlisting language="bash">
+boot.initrd.kernelModules = [ &quot;cifs&quot; ];
+</programlisting>
+  <para>
+    This causes the specified modules and their dependencies to be added
+    to the initial ramdisk.
+  </para>
+  <para>
+    Kernel runtime parameters can be set through
+    <xref linkend="opt-boot.kernel.sysctl" />, e.g.
+  </para>
+  <programlisting language="bash">
+boot.kernel.sysctl.&quot;net.ipv4.tcp_keepalive_time&quot; = 120;
+</programlisting>
+  <para>
+    sets the kernel’s TCP keepalive time to 120 seconds. To see the
+    available parameters, run <literal>sysctl -a</literal>.
+  </para>
+  <section xml:id="sec-linux-config-customizing">
+    <title>Customize your kernel</title>
+    <para>
+      The first step before compiling the kernel is to generate an
+      appropriate <literal>.config</literal> configuration. Either you
+      pass your own config via the <literal>configfile</literal> setting
+      of <literal>linuxManualConfig</literal>:
+    </para>
+    <programlisting language="bash">
+custom-kernel = super.linuxManualConfig {
+  inherit (super) stdenv hostPlatform;
+  inherit (linux_4_9) src;
+  version = &quot;${linux_4_9.version}-custom&quot;;
+
+  configfile = /home/me/my_kernel_config;
+  allowImportFromDerivation = true;
+};
+</programlisting>
+    <para>
+      You can edit the config with this snippet (by default
+      <literal>make menuconfig</literal> won't work out of the box on
+      nixos):
+    </para>
+    <programlisting>
+nix-shell -E 'with import &lt;nixpkgs&gt; {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkg-config ncurses ];})'
+</programlisting>
+    <para>
+      or you can let nixpkgs generate the configuration. Nixpkgs
+      generates it via answering the interactive kernel utility
+      <literal>make config</literal>. The answers depend on parameters
+      passed to
+      <literal>pkgs/os-specific/linux/kernel/generic.nix</literal>
+      (which you can influence by overriding
+      <literal>extraConfig, autoModules, modDirVersion, preferBuiltin, extraConfig</literal>).
+    </para>
+    <programlisting language="bash">
+mptcp93.override ({
+  name=&quot;mptcp-local&quot;;
+
+  ignoreConfigErrors = true;
+  autoModules = false;
+  kernelPreferBuiltin = true;
+
+  enableParallelBuilding = true;
+
+  extraConfig = ''
+    DEBUG_KERNEL y
+    FRAME_POINTER y
+    KGDB y
+    KGDB_SERIAL_CONSOLE y
+    DEBUG_INFO y
+  '';
+});
+</programlisting>
+  </section>
+  <section xml:id="sec-linux-config-developing-modules">
+    <title>Developing kernel modules</title>
+    <para>
+      When developing kernel modules it's often convenient to run
+      edit-compile-run loop as quickly as possible. See below snippet as
+      an example of developing <literal>mellanox</literal> drivers.
+    </para>
+    <programlisting>
+$ nix-build '&lt;nixpkgs&gt;' -A linuxPackages.kernel.dev
+$ nix-shell '&lt;nixpkgs&gt;' -A linuxPackages.kernel
+$ unpackPhase
+$ cd linux-*
+$ make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules
+# insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko
+</programlisting>
+  </section>
+</chapter>
diff --git a/nixos/doc/manual/from_md/configuration/sshfs-file-systems.section.xml b/nixos/doc/manual/from_md/configuration/sshfs-file-systems.section.xml
index 6b317aa63e9..5d74712f35d 100644
--- a/nixos/doc/manual/from_md/configuration/sshfs-file-systems.section.xml
+++ b/nixos/doc/manual/from_md/configuration/sshfs-file-systems.section.xml
@@ -51,8 +51,8 @@ SHA256:yjxl3UbTn31fLWeyLYTAKYJPRmzknjQZoyG8gSNEoIE my-user@workstation
     </para>
     <para>
       The file system can be configured in NixOS via the usual
-      <link xlink:href="options.html#opt-fileSystems">fileSystems</link>
-      option. Here’s a typical setup:
+      <link linkend="opt-fileSystems">fileSystems</link> option. Here’s
+      a typical setup:
     </para>
     <programlisting language="bash">
 {
diff --git a/nixos/doc/manual/from_md/configuration/subversion.chapter.xml b/nixos/doc/manual/from_md/configuration/subversion.chapter.xml
new file mode 100644
index 00000000000..794c2c34e39
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/subversion.chapter.xml
@@ -0,0 +1,121 @@
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-subversion">
+  <title>Subversion</title>
+  <para>
+    <link xlink:href="https://subversion.apache.org/">Subversion</link>
+    is a centralized version-control system. It can use a
+    <link xlink:href="http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.choosing">variety
+    of protocols</link> for communication between client and server.
+  </para>
+  <section xml:id="module-services-subversion-apache-httpd">
+    <title>Subversion inside Apache HTTP</title>
+    <para>
+      This section focuses on configuring a web-based server on top of
+      the Apache HTTP server, which uses
+      <link xlink:href="http://www.webdav.org/">WebDAV</link>/<link xlink:href="http://www.webdav.org/deltav/WWW10/deltav-intro.htm">DeltaV</link>
+      for communication.
+    </para>
+    <para>
+      For more information on the general setup, please refer to the
+      <link xlink:href="http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.httpd">the
+      appropriate section of the Subversion book</link>.
+    </para>
+    <para>
+      To configure, include in
+      <literal>/etc/nixos/configuration.nix</literal> code to activate
+      Apache HTTP, setting
+      <xref linkend="opt-services.httpd.adminAddr" /> appropriately:
+    </para>
+    <programlisting language="bash">
+services.httpd.enable = true;
+services.httpd.adminAddr = ...;
+networking.firewall.allowedTCPPorts = [ 80 443 ];
+</programlisting>
+    <para>
+      For a simple Subversion server with basic authentication,
+      configure the Subversion module for Apache as follows, setting
+      <literal>hostName</literal> and <literal>documentRoot</literal>
+      appropriately, and <literal>SVNParentPath</literal> to the parent
+      directory of the repositories,
+      <literal>AuthzSVNAccessFile</literal> to the location of the
+      <literal>.authz</literal> file describing access permission, and
+      <literal>AuthUserFile</literal> to the password file.
+    </para>
+    <programlisting language="bash">
+services.httpd.extraModules = [
+    # note that order is *super* important here
+    { name = &quot;dav_svn&quot;; path = &quot;${pkgs.apacheHttpdPackages.subversion}/modules/mod_dav_svn.so&quot;; }
+    { name = &quot;authz_svn&quot;; path = &quot;${pkgs.apacheHttpdPackages.subversion}/modules/mod_authz_svn.so&quot;; }
+  ];
+  services.httpd.virtualHosts = {
+    &quot;svn&quot; = {
+       hostName = HOSTNAME;
+       documentRoot = DOCUMENTROOT;
+       locations.&quot;/svn&quot;.extraConfig = ''
+           DAV svn
+           SVNParentPath REPO_PARENT
+           AuthzSVNAccessFile ACCESS_FILE
+           AuthName &quot;SVN Repositories&quot;
+           AuthType Basic
+           AuthUserFile PASSWORD_FILE
+           Require valid-user
+      '';
+    }
+</programlisting>
+    <para>
+      The key <literal>&quot;svn&quot;</literal> is just a symbolic name
+      identifying the virtual host. The
+      <literal>&quot;/svn&quot;</literal> in
+      <literal>locations.&quot;/svn&quot;.extraConfig</literal> is the
+      path underneath which the repositories will be served.
+    </para>
+    <para>
+      <link xlink:href="https://wiki.archlinux.org/index.php/Subversion">This
+      page</link> explains how to set up the Subversion configuration
+      itself. This boils down to the following:
+    </para>
+    <para>
+      Underneath <literal>REPO_PARENT</literal> repositories can be set
+      up as follows:
+    </para>
+    <programlisting>
+$ svn create REPO_NAME
+</programlisting>
+    <para>
+      Repository files need to be accessible by
+      <literal>wwwrun</literal>:
+    </para>
+    <programlisting>
+$ chown -R wwwrun:wwwrun REPO_PARENT
+</programlisting>
+    <para>
+      The password file <literal>PASSWORD_FILE</literal> can be created
+      as follows:
+    </para>
+    <programlisting>
+$ htpasswd -cs PASSWORD_FILE USER_NAME
+</programlisting>
+    <para>
+      Additional users can be set up similarly, omitting the
+      <literal>c</literal> flag:
+    </para>
+    <programlisting>
+$ htpasswd -s PASSWORD_FILE USER_NAME
+</programlisting>
+    <para>
+      The file describing access permissions
+      <literal>ACCESS_FILE</literal> will look something like the
+      following:
+    </para>
+    <programlisting language="bash">
+[/]
+* = r
+
+[REPO_NAME:/]
+USER_NAME = rw
+</programlisting>
+    <para>
+      The Subversion repositories will be accessible as
+      <literal>http://HOSTNAME/svn/REPO_NAME</literal>.
+    </para>
+  </section>
+</chapter>
diff --git a/nixos/doc/manual/from_md/configuration/user-mgmt.chapter.xml b/nixos/doc/manual/from_md/configuration/user-mgmt.chapter.xml
new file mode 100644
index 00000000000..06492d5c251
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/user-mgmt.chapter.xml
@@ -0,0 +1,105 @@
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-user-management">
+  <title>User Management</title>
+  <para>
+    NixOS supports both declarative and imperative styles of user
+    management. In the declarative style, users are specified in
+    <literal>configuration.nix</literal>. For instance, the following
+    states that a user account named <literal>alice</literal> shall
+    exist:
+  </para>
+  <programlisting language="bash">
+users.users.alice = {
+  isNormalUser = true;
+  home = &quot;/home/alice&quot;;
+  description = &quot;Alice Foobar&quot;;
+  extraGroups = [ &quot;wheel&quot; &quot;networkmanager&quot; ];
+  openssh.authorizedKeys.keys = [ &quot;ssh-dss AAAAB3Nza... alice@foobar&quot; ];
+};
+</programlisting>
+  <para>
+    Note that <literal>alice</literal> is a member of the
+    <literal>wheel</literal> and <literal>networkmanager</literal>
+    groups, which allows her to use <literal>sudo</literal> to execute
+    commands as <literal>root</literal> and to configure the network,
+    respectively. Also note the SSH public key that allows remote logins
+    with the corresponding private key. Users created in this way do not
+    have a password by default, so they cannot log in via mechanisms
+    that require a password. However, you can use the
+    <literal>passwd</literal> program to set a password, which is
+    retained across invocations of <literal>nixos-rebuild</literal>.
+  </para>
+  <para>
+    If you set <xref linkend="opt-users.mutableUsers" /> to false, then
+    the contents of <literal>/etc/passwd</literal> and
+    <literal>/etc/group</literal> will be congruent to your NixOS
+    configuration. For instance, if you remove a user from
+    <xref linkend="opt-users.users" /> and run nixos-rebuild, the user
+    account will cease to exist. Also, imperative commands for managing
+    users and groups, such as useradd, are no longer available.
+    Passwords may still be assigned by setting the user's
+    <link linkend="opt-users.users._name_.hashedPassword">hashedPassword</link>
+    option. A hashed password can be generated using
+    <literal>mkpasswd -m sha-512</literal>.
+  </para>
+  <para>
+    A user ID (uid) is assigned automatically. You can also specify a
+    uid manually by adding
+  </para>
+  <programlisting language="bash">
+uid = 1000;
+</programlisting>
+  <para>
+    to the user specification.
+  </para>
+  <para>
+    Groups can be specified similarly. The following states that a group
+    named <literal>students</literal> shall exist:
+  </para>
+  <programlisting language="bash">
+users.groups.students.gid = 1000;
+</programlisting>
+  <para>
+    As with users, the group ID (gid) is optional and will be assigned
+    automatically if it’s missing.
+  </para>
+  <para>
+    In the imperative style, users and groups are managed by commands
+    such as <literal>useradd</literal>, <literal>groupmod</literal> and
+    so on. For instance, to create a user account named
+    <literal>alice</literal>:
+  </para>
+  <programlisting>
+# useradd -m alice
+</programlisting>
+  <para>
+    To make all nix tools available to this new user use `su - USER`
+    which opens a login shell (==shell that loads the profile) for given
+    user. This will create the ~/.nix-defexpr symlink. So run:
+  </para>
+  <programlisting>
+# su - alice -c &quot;true&quot;
+</programlisting>
+  <para>
+    The flag <literal>-m</literal> causes the creation of a home
+    directory for the new user, which is generally what you want. The
+    user does not have an initial password and therefore cannot log in.
+    A password can be set using the <literal>passwd</literal> utility:
+  </para>
+  <programlisting>
+# passwd alice
+Enter new UNIX password: ***
+Retype new UNIX password: ***
+</programlisting>
+  <para>
+    A user can be deleted using <literal>userdel</literal>:
+  </para>
+  <programlisting>
+# userdel -r alice
+</programlisting>
+  <para>
+    The flag <literal>-r</literal> deletes the user’s home directory.
+    Accounts can be modified using <literal>usermod</literal>. Unix
+    groups can be managed using <literal>groupadd</literal>,
+    <literal>groupmod</literal> and <literal>groupdel</literal>.
+  </para>
+</chapter>
diff --git a/nixos/doc/manual/from_md/configuration/wayland.chapter.xml b/nixos/doc/manual/from_md/configuration/wayland.chapter.xml
new file mode 100644
index 00000000000..1e90d4f3117
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/wayland.chapter.xml
@@ -0,0 +1,31 @@
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-wayland">
+  <title>Wayland</title>
+  <para>
+    While X11 (see <xref linkend="sec-x11" />) is still the primary
+    display technology on NixOS, Wayland support is steadily improving.
+    Where X11 separates the X Server and the window manager, on Wayland
+    those are combined: a Wayland Compositor is like an X11 window
+    manager, but also embeds the Wayland 'Server' functionality. This
+    means it is sufficient to install a Wayland Compositor such as sway
+    without separately enabling a Wayland server:
+  </para>
+  <programlisting language="bash">
+programs.sway.enable = true;
+</programlisting>
+  <para>
+    This installs the sway compositor along with some essential
+    utilities. Now you can start sway from the TTY console.
+  </para>
+  <para>
+    If you are using a wlroots-based compositor, like sway, and want to
+    be able to share your screen, you might want to activate this
+    option:
+  </para>
+  <programlisting language="bash">
+xdg.portal.wlr.enable = true;
+</programlisting>
+  <para>
+    and configure Pipewire using
+    <xref linkend="opt-services.pipewire.enable" /> and related options.
+  </para>
+</chapter>
diff --git a/nixos/doc/manual/from_md/configuration/x-windows.chapter.xml b/nixos/doc/manual/from_md/configuration/x-windows.chapter.xml
new file mode 100644
index 00000000000..274d0d817bc
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/x-windows.chapter.xml
@@ -0,0 +1,381 @@
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-x11">
+  <title>X Window System</title>
+  <para>
+    The X Window System (X11) provides the basis of NixOS’ graphical
+    user interface. It can be enabled as follows:
+  </para>
+  <programlisting language="bash">
+services.xserver.enable = true;
+</programlisting>
+  <para>
+    The X server will automatically detect and use the appropriate video
+    driver from a set of X.org drivers (such as <literal>vesa</literal>
+    and <literal>intel</literal>). You can also specify a driver
+    manually, e.g.
+  </para>
+  <programlisting language="bash">
+services.xserver.videoDrivers = [ &quot;r128&quot; ];
+</programlisting>
+  <para>
+    to enable X.org’s <literal>xf86-video-r128</literal> driver.
+  </para>
+  <para>
+    You also need to enable at least one desktop or window manager.
+    Otherwise, you can only log into a plain undecorated
+    <literal>xterm</literal> window. Thus you should pick one or more of
+    the following lines:
+  </para>
+  <programlisting language="bash">
+services.xserver.desktopManager.plasma5.enable = true;
+services.xserver.desktopManager.xfce.enable = true;
+services.xserver.desktopManager.gnome.enable = true;
+services.xserver.desktopManager.mate.enable = true;
+services.xserver.windowManager.xmonad.enable = true;
+services.xserver.windowManager.twm.enable = true;
+services.xserver.windowManager.icewm.enable = true;
+services.xserver.windowManager.i3.enable = true;
+services.xserver.windowManager.herbstluftwm.enable = true;
+</programlisting>
+  <para>
+    NixOS’s default <emphasis>display manager</emphasis> (the program
+    that provides a graphical login prompt and manages the X server) is
+    LightDM. You can select an alternative one by picking one of the
+    following lines:
+  </para>
+  <programlisting language="bash">
+services.xserver.displayManager.sddm.enable = true;
+services.xserver.displayManager.gdm.enable = true;
+</programlisting>
+  <para>
+    You can set the keyboard layout (and optionally the layout variant):
+  </para>
+  <programlisting language="bash">
+services.xserver.layout = &quot;de&quot;;
+services.xserver.xkbVariant = &quot;neo&quot;;
+</programlisting>
+  <para>
+    The X server is started automatically at boot time. If you don’t
+    want this to happen, you can set:
+  </para>
+  <programlisting language="bash">
+services.xserver.autorun = false;
+</programlisting>
+  <para>
+    The X server can then be started manually:
+  </para>
+  <programlisting>
+# systemctl start display-manager.service
+</programlisting>
+  <para>
+    On 64-bit systems, if you want OpenGL for 32-bit programs such as in
+    Wine, you should also set the following:
+  </para>
+  <programlisting language="bash">
+hardware.opengl.driSupport32Bit = true;
+</programlisting>
+  <section xml:id="sec-x11-auto-login">
+    <title>Auto-login</title>
+    <para>
+      The x11 login screen can be skipped entirely, automatically
+      logging you into your window manager and desktop environment when
+      you boot your computer.
+    </para>
+    <para>
+      This is especially helpful if you have disk encryption enabled.
+      Since you already have to provide a password to decrypt your disk,
+      entering a second password to login can be redundant.
+    </para>
+    <para>
+      To enable auto-login, you need to define your default window
+      manager and desktop environment. If you wanted no desktop
+      environment and i3 as your your window manager, you'd define:
+    </para>
+    <programlisting language="bash">
+services.xserver.displayManager.defaultSession = &quot;none+i3&quot;;
+</programlisting>
+    <para>
+      Every display manager in NixOS supports auto-login, here is an
+      example using lightdm for a user <literal>alice</literal>:
+    </para>
+    <programlisting language="bash">
+services.xserver.displayManager.lightdm.enable = true;
+services.xserver.displayManager.autoLogin.enable = true;
+services.xserver.displayManager.autoLogin.user = &quot;alice&quot;;
+</programlisting>
+  </section>
+  <section xml:id="sec-x11--graphics-cards-intel">
+    <title>Intel Graphics drivers</title>
+    <para>
+      There are two choices for Intel Graphics drivers in X.org:
+      <literal>modesetting</literal> (included in the xorg-server
+      itself) and <literal>intel</literal> (provided by the package
+      xf86-video-intel).
+    </para>
+    <para>
+      The default and recommended is <literal>modesetting</literal>. It
+      is a generic driver which uses the kernel
+      <link xlink:href="https://en.wikipedia.org/wiki/Mode_setting">mode
+      setting</link> (KMS) mechanism. It supports Glamor (2D graphics
+      acceleration via OpenGL) and is actively maintained but may
+      perform worse in some cases (like in old chipsets).
+    </para>
+    <para>
+      The second driver, <literal>intel</literal>, is specific to Intel
+      GPUs, but not recommended by most distributions: it lacks several
+      modern features (for example, it doesn't support Glamor) and the
+      package hasn't been officially updated since 2015.
+    </para>
+    <para>
+      The results vary depending on the hardware, so you may have to try
+      both drivers. Use the option
+      <xref linkend="opt-services.xserver.videoDrivers" /> to set one.
+      The recommended configuration for modern systems is:
+    </para>
+    <programlisting language="bash">
+services.xserver.videoDrivers = [ &quot;modesetting&quot; ];
+services.xserver.useGlamor = true;
+</programlisting>
+    <para>
+      If you experience screen tearing no matter what, this
+      configuration was reported to resolve the issue:
+    </para>
+    <programlisting language="bash">
+services.xserver.videoDrivers = [ &quot;intel&quot; ];
+services.xserver.deviceSection = ''
+  Option &quot;DRI&quot; &quot;2&quot;
+  Option &quot;TearFree&quot; &quot;true&quot;
+'';
+</programlisting>
+    <para>
+      Note that this will likely downgrade the performance compared to
+      <literal>modesetting</literal> or <literal>intel</literal> with
+      DRI 3 (default).
+    </para>
+  </section>
+  <section xml:id="sec-x11-graphics-cards-nvidia">
+    <title>Proprietary NVIDIA drivers</title>
+    <para>
+      NVIDIA provides a proprietary driver for its graphics cards that
+      has better 3D performance than the X.org drivers. It is not
+      enabled by default because it’s not free software. You can enable
+      it as follows:
+    </para>
+    <programlisting language="bash">
+services.xserver.videoDrivers = [ &quot;nvidia&quot; ];
+</programlisting>
+    <para>
+      Or if you have an older card, you may have to use one of the
+      legacy drivers:
+    </para>
+    <programlisting language="bash">
+services.xserver.videoDrivers = [ &quot;nvidiaLegacy390&quot; ];
+services.xserver.videoDrivers = [ &quot;nvidiaLegacy340&quot; ];
+services.xserver.videoDrivers = [ &quot;nvidiaLegacy304&quot; ];
+</programlisting>
+    <para>
+      You may need to reboot after enabling this driver to prevent a
+      clash with other kernel modules.
+    </para>
+  </section>
+  <section xml:id="sec-x11--graphics-cards-amd">
+    <title>Proprietary AMD drivers</title>
+    <para>
+      AMD provides a proprietary driver for its graphics cards that is
+      not enabled by default because it’s not Free Software, is often
+      broken in nixpkgs and as of this writing doesn't offer more
+      features or performance. If you still want to use it anyway, you
+      need to explicitly set:
+    </para>
+    <programlisting language="bash">
+services.xserver.videoDrivers = [ &quot;amdgpu-pro&quot; ];
+</programlisting>
+    <para>
+      You will need to reboot after enabling this driver to prevent a
+      clash with other kernel modules.
+    </para>
+  </section>
+  <section xml:id="sec-x11-touchpads">
+    <title>Touchpads</title>
+    <para>
+      Support for Synaptics touchpads (found in many laptops such as the
+      Dell Latitude series) can be enabled as follows:
+    </para>
+    <programlisting language="bash">
+services.xserver.libinput.enable = true;
+</programlisting>
+    <para>
+      The driver has many options (see <xref linkend="ch-options" />).
+      For instance, the following disables tap-to-click behavior:
+    </para>
+    <programlisting language="bash">
+services.xserver.libinput.touchpad.tapping = false;
+</programlisting>
+    <para>
+      Note: the use of <literal>services.xserver.synaptics</literal> is
+      deprecated since NixOS 17.09.
+    </para>
+  </section>
+  <section xml:id="sec-x11-gtk-and-qt-themes">
+    <title>GTK/Qt themes</title>
+    <para>
+      GTK themes can be installed either to user profile or system-wide
+      (via <literal>environment.systemPackages</literal>). To make Qt 5
+      applications look similar to GTK ones, you can use the following
+      configuration:
+    </para>
+    <programlisting language="bash">
+qt5.enable = true;
+qt5.platformTheme = &quot;gtk2&quot;;
+qt5.style = &quot;gtk2&quot;;
+</programlisting>
+  </section>
+  <section xml:id="custom-xkb-layouts">
+    <title>Custom XKB layouts</title>
+    <para>
+      It is possible to install custom
+      <link xlink:href="https://en.wikipedia.org/wiki/X_keyboard_extension">
+      XKB </link> keyboard layouts using the option
+      <literal>services.xserver.extraLayouts</literal>.
+    </para>
+    <para>
+      As a first example, we are going to create a layout based on the
+      basic US layout, with an additional layer to type some greek
+      symbols by pressing the right-alt key.
+    </para>
+    <para>
+      Create a file called <literal>us-greek</literal> with the
+      following content (under a directory called
+      <literal>symbols</literal>; it's an XKB peculiarity that will help
+      with testing):
+    </para>
+    <programlisting language="bash">
+xkb_symbols &quot;us-greek&quot;
+{
+  include &quot;us(basic)&quot;            // includes the base US keys
+  include &quot;level3(ralt_switch)&quot;  // configures right alt as a third level switch
+
+  key &lt;LatA&gt; { [ a, A, Greek_alpha ] };
+  key &lt;LatB&gt; { [ b, B, Greek_beta  ] };
+  key &lt;LatG&gt; { [ g, G, Greek_gamma ] };
+  key &lt;LatD&gt; { [ d, D, Greek_delta ] };
+  key &lt;LatZ&gt; { [ z, Z, Greek_zeta  ] };
+};
+</programlisting>
+    <para>
+      A minimal layout specification must include the following:
+    </para>
+    <programlisting language="bash">
+services.xserver.extraLayouts.us-greek = {
+  description = &quot;US layout with alt-gr greek&quot;;
+  languages   = [ &quot;eng&quot; ];
+  symbolsFile = /yourpath/symbols/us-greek;
+};
+</programlisting>
+    <note>
+      <para>
+        The name (after <literal>extraLayouts.</literal>) should match
+        the one given to the <literal>xkb_symbols</literal> block.
+      </para>
+    </note>
+    <para>
+      Applying this customization requires rebuilding several packages,
+      and a broken XKB file can lead to the X session crashing at login.
+      Therefore, you're strongly advised to <emphasis role="strong">test
+      your layout before applying it</emphasis>:
+    </para>
+    <programlisting>
+$ nix-shell -p xorg.xkbcomp
+$ setxkbmap -I/yourpath us-greek -print | xkbcomp -I/yourpath - $DISPLAY
+</programlisting>
+    <para>
+      You can inspect the predefined XKB files for examples:
+    </para>
+    <programlisting>
+$ echo &quot;$(nix-build --no-out-link '&lt;nixpkgs&gt;' -A xorg.xkeyboardconfig)/etc/X11/xkb/&quot;
+</programlisting>
+    <para>
+      Once the configuration is applied, and you did a logout/login
+      cycle, the layout should be ready to use. You can try it by e.g.
+      running <literal>setxkbmap us-greek</literal> and then type
+      <literal>&lt;alt&gt;+a</literal> (it may not get applied in your
+      terminal straight away). To change the default, the usual
+      <literal>services.xserver.layout</literal> option can still be
+      used.
+    </para>
+    <para>
+      A layout can have several other components besides
+      <literal>xkb_symbols</literal>, for example we will define new
+      keycodes for some multimedia key and bind these to some symbol.
+    </para>
+    <para>
+      Use the <emphasis>xev</emphasis> utility from
+      <literal>pkgs.xorg.xev</literal> to find the codes of the keys of
+      interest, then create a <literal>media-key</literal> file to hold
+      the keycodes definitions
+    </para>
+    <programlisting language="bash">
+xkb_keycodes &quot;media&quot;
+{
+ &lt;volUp&gt;   = 123;
+ &lt;volDown&gt; = 456;
+}
+</programlisting>
+    <para>
+      Now use the newly define keycodes in <literal>media-sym</literal>:
+    </para>
+    <programlisting language="bash">
+xkb_symbols &quot;media&quot;
+{
+ key.type = &quot;ONE_LEVEL&quot;;
+ key &lt;volUp&gt;   { [ XF86AudioLowerVolume ] };
+ key &lt;volDown&gt; { [ XF86AudioRaiseVolume ] };
+}
+</programlisting>
+    <para>
+      As before, to install the layout do
+    </para>
+    <programlisting language="bash">
+services.xserver.extraLayouts.media = {
+  description  = &quot;Multimedia keys remapping&quot;;
+  languages    = [ &quot;eng&quot; ];
+  symbolsFile  = /path/to/media-key;
+  keycodesFile = /path/to/media-sym;
+};
+</programlisting>
+    <note>
+      <para>
+        The function
+        <literal>pkgs.writeText &lt;filename&gt; &lt;content&gt;</literal>
+        can be useful if you prefer to keep the layout definitions
+        inside the NixOS configuration.
+      </para>
+    </note>
+    <para>
+      Unfortunately, the Xorg server does not (currently) support
+      setting a keymap directly but relies instead on XKB rules to
+      select the matching components (keycodes, types, ...) of a layout.
+      This means that components other than symbols won't be loaded by
+      default. As a workaround, you can set the keymap using
+      <literal>setxkbmap</literal> at the start of the session with:
+    </para>
+    <programlisting language="bash">
+services.xserver.displayManager.sessionCommands = &quot;setxkbmap -keycodes media&quot;;
+</programlisting>
+    <para>
+      If you are manually starting the X server, you should set the
+      argument <literal>-xkbdir /etc/X11/xkb</literal>, otherwise X
+      won't find your layout files. For example with
+      <literal>xinit</literal> run
+    </para>
+    <programlisting>
+$ xinit -- -xkbdir /etc/X11/xkb
+</programlisting>
+    <para>
+      To learn how to write layouts take a look at the XKB
+      <link xlink:href="https://www.x.org/releases/current/doc/xorg-docs/input/XKB-Enhancing.html#Defining_New_Layouts">documentation
+      </link>. More example layouts can also be found
+      <link xlink:href="https://wiki.archlinux.org/index.php/X_KeyBoard_extension#Basic_examples">here
+      </link>.
+    </para>
+  </section>
+</chapter>
diff --git a/nixos/doc/manual/from_md/configuration/xfce.chapter.xml b/nixos/doc/manual/from_md/configuration/xfce.chapter.xml
new file mode 100644
index 00000000000..f96ef2e8c48
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/xfce.chapter.xml
@@ -0,0 +1,62 @@
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-xfce">
+  <title>Xfce Desktop Environment</title>
+  <para>
+    To enable the Xfce Desktop Environment, set
+  </para>
+  <programlisting language="bash">
+services.xserver.desktopManager.xfce.enable = true;
+services.xserver.displayManager.defaultSession = &quot;xfce&quot;;
+</programlisting>
+  <para>
+    Optionally, <emphasis>picom</emphasis> can be enabled for nice
+    graphical effects, some example settings:
+  </para>
+  <programlisting language="bash">
+services.picom = {
+  enable = true;
+  fade = true;
+  inactiveOpacity = 0.9;
+  shadow = true;
+  fadeDelta = 4;
+};
+</programlisting>
+  <para>
+    Some Xfce programs are not installed automatically. To install them
+    manually (system wide), put them into your
+    <xref linkend="opt-environment.systemPackages" /> from
+    <literal>pkgs.xfce</literal>.
+  </para>
+  <section xml:id="sec-xfce-thunar-plugins">
+    <title>Thunar Plugins</title>
+    <para>
+      If you'd like to add extra plugins to Thunar, add them to
+      <xref linkend="opt-services.xserver.desktopManager.xfce.thunarPlugins" />.
+      You shouldn't just add them to
+      <xref linkend="opt-environment.systemPackages" />.
+    </para>
+  </section>
+  <section xml:id="sec-xfce-troubleshooting">
+    <title>Troubleshooting</title>
+    <para>
+      Even after enabling udisks2, volume management might not work.
+      Thunar and/or the desktop takes time to show up. Thunar will spit
+      out this kind of message on start (look at
+      <literal>journalctl --user -b</literal>).
+    </para>
+    <programlisting>
+Thunar:2410): GVFS-RemoteVolumeMonitor-WARNING **: remote volume monitor with dbus name org.gtk.Private.UDisks2VolumeMonitor is not supported
+</programlisting>
+    <para>
+      This is caused by some needed GNOME services not running. This is
+      all fixed by enabling &quot;Launch GNOME services on startup&quot;
+      in the Advanced tab of the Session and Startup settings panel.
+      Alternatively, you can run this command to do the same thing.
+    </para>
+    <programlisting>
+$ xfconf-query -c xfce4-session -p /compat/LaunchGNOME -s true
+</programlisting>
+    <para>
+      A log-out and re-log will be needed for this to take effect.
+    </para>
+  </section>
+</chapter>