diff --git a/nixos/doc/manual/administration/network-problems.section.md b/nixos/doc/manual/administration/network-problems.section.md
new file mode 100644
index 000000000000..d360120d72d0
--- /dev/null
+++ b/nixos/doc/manual/administration/network-problems.section.md
@@ -0,0 +1,21 @@
+# Network Problems {#sec-nix-network-issues}
+
+Nix uses a so-called *binary cache* to optimise building a package from
+source into downloading it as a pre-built binary. That is, whenever a
+command like `nixos-rebuild` needs a path in the Nix store, Nix will try
+to download that path from the Internet rather than build it from
+source. The default binary cache is `https://cache.nixos.org/`. If this
+cache is unreachable, Nix operations may take a long time due to HTTP
+connection timeouts. You can disable the use of the binary cache by
+adding `--option use-binary-caches false`, e.g.
+
+```ShellSession
+# nixos-rebuild switch --option use-binary-caches false
+```
+
+If you have an alternative binary cache at your disposal, you can use it
+instead:
+
+```ShellSession
+# nixos-rebuild switch --option binary-caches http://my-cache.example.org/
+```
diff --git a/nixos/doc/manual/administration/network-problems.xml b/nixos/doc/manual/administration/network-problems.xml
deleted file mode 100644
index 1035e4e056a9..000000000000
--- a/nixos/doc/manual/administration/network-problems.xml
+++ /dev/null
@@ -1,27 +0,0 @@
-
- Network Problems
-
-
- Nix uses a so-called binary cache to optimise building a
- package from source into downloading it as a pre-built binary. That is,
- whenever a command like nixos-rebuild needs a path in the
- Nix store, Nix will try to download that path from the Internet rather than
- build it from source. The default binary cache is
- https://cache.nixos.org/. If this cache is unreachable, Nix
- operations may take a long time due to HTTP connection timeouts. You can
- disable the use of the binary cache by adding , e.g.
-
-# nixos-rebuild switch --option use-binary-caches false
-
- If you have an alternative binary cache at your disposal, you can use it
- instead:
-
-# nixos-rebuild switch --option binary-caches http://my-cache.example.org/
-
-
-
diff --git a/nixos/doc/manual/administration/troubleshooting.xml b/nixos/doc/manual/administration/troubleshooting.xml
index 218324b299ac..d447b537335b 100644
--- a/nixos/doc/manual/administration/troubleshooting.xml
+++ b/nixos/doc/manual/administration/troubleshooting.xml
@@ -12,5 +12,5 @@
-
+
diff --git a/nixos/doc/manual/from_md/administration/network-problems.section.xml b/nixos/doc/manual/from_md/administration/network-problems.section.xml
new file mode 100644
index 000000000000..4c0598ca94e8
--- /dev/null
+++ b/nixos/doc/manual/from_md/administration/network-problems.section.xml
@@ -0,0 +1,25 @@
+
+ Network Problems
+
+ Nix uses a so-called binary cache to optimise
+ building a package from source into downloading it as a pre-built
+ binary. That is, whenever a command like
+ nixos-rebuild needs a path in the Nix store, Nix
+ will try to download that path from the Internet rather than build
+ it from source. The default binary cache is
+ https://cache.nixos.org/. If this cache is
+ unreachable, Nix operations may take a long time due to HTTP
+ connection timeouts. You can disable the use of the binary cache by
+ adding --option use-binary-caches false, e.g.
+
+
+# nixos-rebuild switch --option use-binary-caches false
+
+
+ If you have an alternative binary cache at your disposal, you can
+ use it instead:
+
+
+# nixos-rebuild switch --option binary-caches http://my-cache.example.org/
+
+