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..7d0d56726226 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="../from_md/administration/containers.chapter.xml" />
  <xi:include href="troubleshooting.xml" />
 </part>
diff --git a/nixos/doc/manual/from_md/administration/containers.chapter.xml b/nixos/doc/manual/from_md/administration/containers.chapter.xml
new file mode 100644
index 000000000000..afbd5b35aaa5
--- /dev/null
+++ b/nixos/doc/manual/from_md/administration/containers.chapter.xml
@@ -0,0 +1,31 @@
+<chapter xmlns="http://docbook.org/ns/docbook"  xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" 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 <literal>nixos-container</literal>, and declaratively, by
+    specifying them in your <literal>configuration.nix</literal>. The
+    declarative approach implies that containers get upgraded along with
+    your host system when you run <literal>nixos-rebuild</literal>,
+    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="imperative-containers.section.xml" />
+  <xi:include href="declarative-containers.section.xml" />
+  <xi:include href="container-networking.section.xml" />
+</chapter>