Merge pull request #137082 from bobby285271/markdown

nixos/doc: Convert more articles to CommonMark

37 files changed, 1988 insertions, 1114 deletions

diff --git a/nixos/doc/manual/administration/containers.chapter.md b/nixos/doc/manual/administration/containers.chapter.md
new file mode 100644
index 000000000000..ea51f91f698f
--- /dev/null
+++ b/nixos/doc/manual/administration/containers.chapter.md
@@ -0,0 +1,28 @@
+# Container Management {#ch-containers}
+
+NixOS allows you to easily run other NixOS instances as *containers*.
+Containers are a light-weight approach to virtualisation that runs
+software in the container at the same speed as in the host system. NixOS
+containers share the Nix store of the host, making container creation
+very efficient.
+
+::: {.warning}
+Currently, NixOS containers are not perfectly isolated from the host
+system. This means that a user with root access to the container can do
+things that affect the host. So you should not give container root
+access to untrusted users.
+:::
+
+NixOS containers can be created in two ways: imperatively, using the
+command `nixos-container`, and declaratively, by specifying them in your
+`configuration.nix`. The declarative approach implies that containers
+get upgraded along with your host system when you run `nixos-rebuild`,
+which is often not what you want. By contrast, in the imperative
+approach, containers are configured and updated independently from the
+host system.
+
+```{=docbook}
+<xi:include href="imperative-containers.section.xml" />
+<xi:include href="declarative-containers.section.xml" />
+<xi:include href="container-networking.section.xml" />
+```
diff --git a/nixos/doc/manual/administration/containers.xml b/nixos/doc/manual/administration/containers.xml
deleted file mode 100644
index 8e0e300f367b..000000000000
--- a/nixos/doc/manual/administration/containers.xml
+++ /dev/null
@@ -1,34 +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="ch-containers">
- <title>Container Management</title>
- <para>
-  NixOS allows you to easily run other NixOS instances as
-  <emphasis>containers</emphasis>. Containers are a light-weight approach to
-  virtualisation that runs software in the container at the same speed as in
-  the host system. NixOS containers share the Nix store of the host, making
-  container creation very efficient.
- </para>
- <warning>
-  <para>
-   Currently, NixOS containers are not perfectly isolated from the host system.
-   This means that a user with root access to the container can do things that
-   affect the host. So you should not give container root access to untrusted
-   users.
-  </para>
- </warning>
- <para>
-  NixOS containers can be created in two ways: imperatively, using the command
-  <command>nixos-container</command>, and declaratively, by specifying them in
-  your <filename>configuration.nix</filename>. The declarative approach implies
-  that containers get upgraded along with your host system when you run
-  <command>nixos-rebuild</command>, which is often not what you want. By
-  contrast, in the imperative approach, containers are configured and updated
-  independently from the host system.
- </para>
- <xi:include href="../from_md/administration/imperative-containers.section.xml" />
- <xi:include href="../from_md/administration/declarative-containers.section.xml" />
- <xi:include href="../from_md/administration/container-networking.section.xml" />
-</chapter>
diff --git a/nixos/doc/manual/administration/running.xml b/nixos/doc/manual/administration/running.xml
index 24fd864956ff..d9fcc1aee263 100644
--- a/nixos/doc/manual/administration/running.xml
+++ b/nixos/doc/manual/administration/running.xml
@@ -16,6 +16,6 @@
  <xi:include href="../from_md/administration/control-groups.chapter.xml" />
  <xi:include href="../from_md/administration/logging.chapter.xml" />
  <xi:include href="../from_md/administration/cleaning-store.chapter.xml" />
- <xi:include href="containers.xml" />
- <xi:include href="troubleshooting.xml" />
+ <xi:include href="../from_md/administration/containers.chapter.xml" />
+ <xi:include href="../from_md/administration/troubleshooting.chapter.xml" />
 </part>
diff --git a/nixos/doc/manual/administration/troubleshooting.chapter.md b/nixos/doc/manual/administration/troubleshooting.chapter.md
new file mode 100644
index 000000000000..548456eaf6d6
--- /dev/null
+++ b/nixos/doc/manual/administration/troubleshooting.chapter.md
@@ -0,0 +1,12 @@
+# Troubleshooting {#ch-troubleshooting}
+
+This chapter describes solutions to common problems you might encounter
+when you manage your NixOS system.
+
+```{=docbook}
+<xi:include href="boot-problems.section.xml" />
+<xi:include href="maintenance-mode.section.xml" />
+<xi:include href="rollback.section.xml" />
+<xi:include href="store-corruption.section.xml" />
+<xi:include href="network-problems.section.xml" />
+```
diff --git a/nixos/doc/manual/administration/troubleshooting.xml b/nixos/doc/manual/administration/troubleshooting.xml
deleted file mode 100644
index d447b537335b..000000000000
--- a/nixos/doc/manual/administration/troubleshooting.xml
+++ /dev/null
@@ -1,16 +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="ch-troubleshooting">
- <title>Troubleshooting</title>
- <para>
-  This chapter describes solutions to common problems you might encounter when
-  you manage your NixOS system.
- </para>
- <xi:include href="../from_md/administration/boot-problems.section.xml" />
- <xi:include href="../from_md/administration/maintenance-mode.section.xml" />
- <xi:include href="../from_md/administration/rollback.section.xml" />
- <xi:include href="../from_md/administration/store-corruption.section.xml" />
- <xi:include href="../from_md/administration/network-problems.section.xml" />
-</chapter>
diff --git a/nixos/doc/manual/configuration/config-syntax.chapter.md b/nixos/doc/manual/configuration/config-syntax.chapter.md
new file mode 100644
index 000000000000..56d093c0f6e8
--- /dev/null
+++ b/nixos/doc/manual/configuration/config-syntax.chapter.md
@@ -0,0 +1,19 @@
+# Configuration Syntax {#sec-configuration-syntax}
+
+The NixOS configuration file `/etc/nixos/configuration.nix` is actually
+a *Nix expression*, which is the Nix package manager's purely functional
+language for describing how to build packages and configurations. This
+means you have all the expressive power of that language at your
+disposal, including the ability to abstract over common patterns, which
+is very useful when managing complex systems. The syntax and semantics
+of the Nix language are fully described in the [Nix
+manual](https://nixos.org/nix/manual/#chap-writing-nix-expressions), but
+here we give a short overview of the most important constructs useful in
+NixOS configuration files.
+
+```{=docbook}
+<xi:include href="config-file.section.xml" />
+<xi:include href="abstractions.section.xml" />
+<xi:include href="modularity.section.xml" />
+<xi:include href="summary.section.xml" />
+```
diff --git a/nixos/doc/manual/configuration/config-syntax.xml b/nixos/doc/manual/configuration/config-syntax.xml
deleted file mode 100644
index d1351ff934e5..000000000000
--- a/nixos/doc/manual/configuration/config-syntax.xml
+++ /dev/null
@@ -1,25 +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-configuration-syntax">
- <title>Configuration Syntax</title>
- <para>
-  The NixOS configuration file
-  <filename>/etc/nixos/configuration.nix</filename> is actually a <emphasis>Nix
-  expression</emphasis>, which is the Nix package manager’s purely functional
-  language for describing how to build packages and configurations. This means
-  you have all the expressive power of that language at your disposal,
-  including the ability to abstract over common patterns, which is very useful
-  when managing complex systems. The syntax and semantics of the Nix language
-  are fully described in the
-  <link
-xlink:href="https://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix
-  manual</link>, but here we give a short overview of the most important
-  constructs useful in NixOS configuration files.
- </para>
- <xi:include href="../from_md/configuration/config-file.section.xml" />
- <xi:include href="../from_md/configuration/abstractions.section.xml" />
- <xi:include href="../from_md/configuration/modularity.section.xml" />
- <xi:include href="../from_md/configuration/summary.section.xml" />
-</chapter>
diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml
index 2461a5de73ad..b04316cfa48e 100644
--- a/nixos/doc/manual/configuration/configuration.xml
+++ b/nixos/doc/manual/configuration/configuration.xml
@@ -13,19 +13,19 @@
    effect after you run <command>nixos-rebuild</command>.
   </para>
  </partintro>
- <xi:include href="config-syntax.xml" />
- <xi:include href="package-mgmt.xml" />
+ <xi:include href="../from_md/configuration/config-syntax.chapter.xml" />
+ <xi:include href="../from_md/configuration/package-mgmt.chapter.xml" />
  <xi:include href="../from_md/configuration/user-mgmt.chapter.xml" />
- <xi:include href="file-systems.xml" />
+ <xi:include href="../from_md/configuration/file-systems.chapter.xml" />
  <xi:include href="../from_md/configuration/x-windows.chapter.xml" />
  <xi:include href="../from_md/configuration/wayland.chapter.xml" />
  <xi:include href="../from_md/configuration/gpu-accel.chapter.xml" />
  <xi:include href="../from_md/configuration/xfce.chapter.xml" />
- <xi:include href="networking.xml" />
+ <xi:include href="../from_md/configuration/networking.chapter.xml" />
  <xi:include href="../from_md/configuration/linux-kernel.chapter.xml" />
  <xi:include href="../from_md/configuration/subversion.chapter.xml" />
  <xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
- <xi:include href="profiles.xml" />
+ <xi:include href="../from_md/configuration/profiles.chapter.xml" />
  <xi:include href="../from_md/configuration/kubernetes.chapter.xml" />
 <!-- Apache; libvirtd virtualisation -->
 </part>
diff --git a/nixos/doc/manual/configuration/declarative-packages.section.md b/nixos/doc/manual/configuration/declarative-packages.section.md
new file mode 100644
index 000000000000..337cdf8472e4
--- /dev/null
+++ b/nixos/doc/manual/configuration/declarative-packages.section.md
@@ -0,0 +1,46 @@
+# Declarative Package Management {#sec-declarative-package-mgmt}
+
+With declarative package management, you specify which packages you want
+on your system by setting the option
+[](#opt-environment.systemPackages). For instance, adding the
+following line to `configuration.nix` enables the Mozilla Thunderbird
+email application:
+
+```nix
+environment.systemPackages = [ pkgs.thunderbird ];
+```
+
+The effect of this specification is that the Thunderbird package from
+Nixpkgs will be built or downloaded as part of the system when you run
+`nixos-rebuild switch`.
+
+::: {.note}
+Some packages require additional global configuration such as D-Bus or
+systemd service registration so adding them to
+[](#opt-environment.systemPackages) might not be sufficient. You are
+advised to check the [list of options](#ch-options) whether a NixOS
+module for the package does not exist.
+:::
+
+You can get a list of the available packages as follows:
+
+```ShellSession
+$ nix-env -qaP '*' --description
+nixos.firefox   firefox-23.0   Mozilla Firefox - the browser, reloaded
+...
+```
+
+The first column in the output is the *attribute name*, such as
+`nixos.thunderbird`.
+
+Note: the `nixos` prefix tells us that we want to get the package from
+the `nixos` channel and works only in CLI tools. In declarative
+configuration use `pkgs` prefix (variable).
+
+To "uninstall" a package, simply remove it from
+[](#opt-environment.systemPackages) and run `nixos-rebuild switch`.
+
+```{=docbook}
+<xi:include href="customizing-packages.section.xml" />
+<xi:include href="adding-custom-packages.section.xml" />
+```
diff --git a/nixos/doc/manual/configuration/declarative-packages.xml b/nixos/doc/manual/configuration/declarative-packages.xml
deleted file mode 100644
index 8d321929f3f0..000000000000
--- a/nixos/doc/manual/configuration/declarative-packages.xml
+++ /dev/null
@@ -1,54 +0,0 @@
-<section 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-declarative-package-mgmt">
- <title>Declarative Package Management</title>
-
- <para>
-  With declarative package management, you specify which packages you want on
-  your system by setting the option
-  <xref linkend="opt-environment.systemPackages"/>. For instance, adding the
-  following line to <filename>configuration.nix</filename> enables the Mozilla
-  Thunderbird email application:
-<programlisting>
-<xref linkend="opt-environment.systemPackages"/> = [ pkgs.thunderbird ];
-</programlisting>
-  The effect of this specification is that the Thunderbird package from Nixpkgs
-  will be built or downloaded as part of the system when you run
-  <command>nixos-rebuild switch</command>.
- </para>
-
- <note>
-  <para>
-   Some packages require additional global configuration such as D-Bus or systemd service registration so adding them to <xref linkend="opt-environment.systemPackages"/> might not be sufficient. You are advised to check the <link xlink:href="#ch-options">list of options</link> whether a NixOS module for the package does not exist.
-  </para>
- </note>
-
- <para>
-  You can get a list of the available packages as follows:
-<screen>
-<prompt>$ </prompt>nix-env -qaP '*' --description
-nixos.firefox   firefox-23.0   Mozilla Firefox - the browser, reloaded
-<replaceable>...</replaceable>
-</screen>
-  The first column in the output is the <emphasis>attribute name</emphasis>,
-  such as <literal>nixos.thunderbird</literal>.
- </para>
- <para>
-  Note: the <literal>nixos</literal> prefix tells us that we want to get the
-  package from the <literal>nixos</literal> channel and works only in CLI tools.
-
-  In declarative configuration use <literal>pkgs</literal> prefix (variable).
- </para>
-
- <para>
-  To “uninstall” a package, simply remove it from
-  <xref linkend="opt-environment.systemPackages"/> and run
-  <command>nixos-rebuild switch</command>.
- </para>
-
- <xi:include href="../from_md/configuration/customizing-packages.section.xml" />
-
- <xi:include href="../from_md/configuration/adding-custom-packages.section.xml" />
-</section>
diff --git a/nixos/doc/manual/configuration/file-systems.chapter.md b/nixos/doc/manual/configuration/file-systems.chapter.md
new file mode 100644
index 000000000000..901e2e4f181b
--- /dev/null
+++ b/nixos/doc/manual/configuration/file-systems.chapter.md
@@ -0,0 +1,42 @@
+# File Systems {#ch-file-systems}
+
+You can define file systems using the `fileSystems` configuration
+option. For instance, the following definition causes NixOS to mount the
+Ext4 file system on device `/dev/disk/by-label/data` onto the mount
+point `/data`:
+
+```nix
+fileSystems."/data" =
+  { device = "/dev/disk/by-label/data";
+    fsType = "ext4";
+  };
+```
+
+This will create an entry in `/etc/fstab`, which will generate a
+corresponding [systemd.mount](https://www.freedesktop.org/software/systemd/man/systemd.mount.html)
+unit via [systemd-fstab-generator](https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html).
+The filesystem will be mounted automatically unless `"noauto"` is
+present in [options](#opt-fileSystems._name_.options). `"noauto"`
+filesystems can be mounted explicitly using `systemctl` e.g.
+`systemctl start data.mount`. Mount points are created automatically if they don't
+already exist. For `device`, it's best to use the topology-independent
+device aliases in `/dev/disk/by-label` and `/dev/disk/by-uuid`, as these
+don't change if the topology changes (e.g. if a disk is moved to another
+IDE controller).
+
+You can usually omit the file system type (`fsType`), since `mount` can
+usually detect the type and load the necessary kernel module
+automatically. However, if the file system is needed at early boot (in
+the initial ramdisk) and is not `ext2`, `ext3` or `ext4`, then it's best
+to specify `fsType` to ensure that the kernel module is available.
+
+::: {.note}
+System startup will fail if any of the filesystems fails to mount,
+dropping you to the emergency shell. You can make a mount asynchronous
+and non-critical by adding `options = [ "nofail" ];`.
+:::
+
+```{=docbook}
+<xi:include href="luks-file-systems.section.xml" />
+<xi:include href="sshfs-file-systems.section.xml" />
+```
diff --git a/nixos/doc/manual/configuration/file-systems.xml b/nixos/doc/manual/configuration/file-systems.xml
deleted file mode 100644
index 908b5d6c4681..000000000000
--- a/nixos/doc/manual/configuration/file-systems.xml
+++ /dev/null
@@ -1,58 +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="ch-file-systems">
- <title>File Systems</title>
- <para>
-  You can define file systems using the <option>fileSystems</option>
-  configuration option. For instance, the following definition causes NixOS to
-  mount the Ext4 file system on device
-  <filename>/dev/disk/by-label/data</filename> onto the mount point
-  <filename>/data</filename>:
-<programlisting>
-<xref linkend="opt-fileSystems"/>."/data" =
-  { device = "/dev/disk/by-label/data";
-    fsType = "ext4";
-  };
-</programlisting>
-  This will create an entry in <filename>/etc/fstab</filename>, which will
-  generate a corresponding
-  <link xlink:href="https://www.freedesktop.org/software/systemd/man/systemd.mount.html">systemd.mount</link>
-  unit via
-  <link xlink:href="https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html">systemd-fstab-generator</link>.
-  The filesystem will be mounted automatically unless
-  <literal>"noauto"</literal> is present in <link
-  linkend="opt-fileSystems._name_.options">options</link>.
-  <literal>"noauto"</literal> filesystems can be mounted explicitly using
-  <command>systemctl</command> e.g. <command>systemctl start
-  data.mount</command>.
-  Mount points are created automatically if they don’t already exist. For
-  <option><link linkend="opt-fileSystems._name_.device">device</link></option>,
-  it’s best to use the topology-independent device aliases in
-  <filename>/dev/disk/by-label</filename> and
-  <filename>/dev/disk/by-uuid</filename>, as these don’t change if the
-  topology changes (e.g. if a disk is moved to another IDE controller).
- </para>
- <para>
-  You can usually omit the file system type
-  (<option><link linkend="opt-fileSystems._name_.fsType">fsType</link></option>),
-  since <command>mount</command> can usually detect the type and load the
-  necessary kernel module automatically. However, if the file system is needed
-  at early boot (in the initial ramdisk) and is not <literal>ext2</literal>,
-  <literal>ext3</literal> or <literal>ext4</literal>, then it’s best to
-  specify <option>fsType</option> to ensure that the kernel module is
-  available.
- </para>
- <note>
-  <para>
-   System startup will fail if any of the filesystems fails to mount, dropping
-   you to the emergency shell. You can make a mount asynchronous and
-   non-critical by adding
-   <literal><link linkend="opt-fileSystems._name_.options">options</link> = [
-   "nofail" ];</literal>.
-  </para>
- </note>
- <xi:include href="../from_md/configuration/luks-file-systems.section.xml" />
- <xi:include href="../from_md/configuration/sshfs-file-systems.section.xml" />
-</chapter>
diff --git a/nixos/doc/manual/configuration/networking.chapter.md b/nixos/doc/manual/configuration/networking.chapter.md
new file mode 100644
index 000000000000..529dc0610bda
--- /dev/null
+++ b/nixos/doc/manual/configuration/networking.chapter.md
@@ -0,0 +1,16 @@
+# Networking {#sec-networking}
+
+This section describes how to configure networking components
+on your NixOS machine.
+
+```{=docbook}
+<xi:include href="network-manager.section.xml" />
+<xi:include href="ssh.section.xml" />
+<xi:include href="ipv4-config.section.xml" />
+<xi:include href="ipv6-config.section.xml" />
+<xi:include href="firewall.section.xml" />
+<xi:include href="wireless.section.xml" />
+<xi:include href="ad-hoc-network-config.section.xml" />
+<xi:include href="renaming-interfaces.section.xml" />
+```
+<!-- TODO: OpenVPN, NAT -->
diff --git a/nixos/doc/manual/configuration/networking.xml b/nixos/doc/manual/configuration/networking.xml
deleted file mode 100644
index 5dd0278569b9..000000000000
--- a/nixos/doc/manual/configuration/networking.xml
+++ /dev/null
@@ -1,20 +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-networking">
- <title>Networking</title>
- <para>
-  This section describes how to configure networking components on your NixOS
-  machine.
- </para>
- <xi:include href="../from_md/configuration/network-manager.section.xml" />
- <xi:include href="../from_md/configuration/ssh.section.xml" />
- <xi:include href="../from_md/configuration/ipv4-config.section.xml" />
- <xi:include href="../from_md/configuration/ipv6-config.section.xml" />
- <xi:include href="../from_md/configuration/firewall.section.xml" />
- <xi:include href="../from_md/configuration/wireless.section.xml" />
- <xi:include href="../from_md/configuration/ad-hoc-network-config.section.xml" />
- <xi:include href="../from_md/configuration/renaming-interfaces.section.xml" />
-<!-- TODO: OpenVPN, NAT -->
-</chapter>
diff --git a/nixos/doc/manual/configuration/package-mgmt.chapter.md b/nixos/doc/manual/configuration/package-mgmt.chapter.md
new file mode 100644
index 000000000000..a6c414be59a9
--- /dev/null
+++ b/nixos/doc/manual/configuration/package-mgmt.chapter.md
@@ -0,0 +1,18 @@
+# Package Management {#sec-package-management}
+
+This section describes how to add additional packages to your system.
+NixOS has two distinct styles of package management:
+
+-   *Declarative*, where you declare what packages you want in your
+    `configuration.nix`. Every time you run `nixos-rebuild`, NixOS will
+    ensure that you get a consistent set of binaries corresponding to
+    your specification.
+
+-   *Ad hoc*, where you install, upgrade and uninstall packages via the
+    `nix-env` command. This style allows mixing packages from different
+    Nixpkgs versions. It's the only choice for non-root users.
+
+```{=docbook}
+<xi:include href="declarative-packages.section.xml" />
+<xi:include href="ad-hoc-packages.section.xml" />
+```
diff --git a/nixos/doc/manual/configuration/package-mgmt.xml b/nixos/doc/manual/configuration/package-mgmt.xml
deleted file mode 100644
index 2f9395d26fa8..000000000000
--- a/nixos/doc/manual/configuration/package-mgmt.xml
+++ /dev/null
@@ -1,31 +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-package-management">
- <title>Package Management</title>
- <para>
-  This section describes how to add additional packages to your system. NixOS
-  has two distinct styles of package management:
-  <itemizedlist>
-   <listitem>
-    <para>
-     <emphasis>Declarative</emphasis>, where you declare what packages you want
-     in your <filename>configuration.nix</filename>. Every time you run
-     <command>nixos-rebuild</command>, NixOS will ensure that you get a
-     consistent set of binaries corresponding to your specification.
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     <emphasis>Ad hoc</emphasis>, where you install, upgrade and uninstall
-     packages via the <command>nix-env</command> command. This style allows
-     mixing packages from different Nixpkgs versions. It’s the only choice
-     for non-root users.
-    </para>
-   </listitem>
-  </itemizedlist>
- </para>
- <xi:include href="declarative-packages.xml" />
- <xi:include href="../from_md/configuration/ad-hoc-packages.section.xml" />
-</chapter>