diff --git a/nixos/doc/manual/configuration/ad-hoc-packages.section.md b/nixos/doc/manual/configuration/ad-hoc-packages.section.md
new file mode 100644
index 000000000000..e9d574903a10
--- /dev/null
+++ b/nixos/doc/manual/configuration/ad-hoc-packages.section.md
@@ -0,0 +1,51 @@
+# Ad-Hoc Package Management {#sec-ad-hoc-packages}
+
+With the command `nix-env`, you can install and uninstall packages from
+the command line. For instance, to install Mozilla Thunderbird:
+
+```ShellSession
+$ nix-env -iA nixos.thunderbird
+```
+
+If you invoke this as root, the package is installed in the Nix profile
+`/nix/var/nix/profiles/default` and visible to all users of the system;
+otherwise, the package ends up in
+`/nix/var/nix/profiles/per-user/username/profile` and is not visible to
+other users. The `-A` flag specifies the package by its attribute name;
+without it, the package is installed by matching against its package
+name (e.g. `thunderbird`). The latter is slower because it requires
+matching against all available Nix packages, and is ambiguous if there
+are multiple matching packages.
+
+Packages come from the NixOS channel. You typically upgrade a package by
+updating to the latest version of the NixOS channel:
+
+```ShellSession
+$ nix-channel --update nixos
+```
+
+and then running `nix-env -i` again. Other packages in the profile are
+*not* affected; this is the crucial difference with the declarative
+style of package management, where running `nixos-rebuild switch` causes
+all packages to be updated to their current versions in the NixOS
+channel. You can however upgrade all packages for which there is a newer
+version by doing:
+
+```ShellSession
+$ nix-env -u '*'
+```
+
+A package can be uninstalled using the `-e` flag:
+
+```ShellSession
+$ nix-env -e thunderbird
+```
+
+Finally, you can roll back an undesirable `nix-env` action:
+
+```ShellSession
+$ nix-env --rollback
+```
+
+`nix-env` has many more flags. For details, see the nix-env(1) manpage or
+the Nix manual.
diff --git a/nixos/doc/manual/configuration/ad-hoc-packages.xml b/nixos/doc/manual/configuration/ad-hoc-packages.xml
deleted file mode 100644
index c7e882d846fa..000000000000
--- a/nixos/doc/manual/configuration/ad-hoc-packages.xml
+++ /dev/null
@@ -1,61 +0,0 @@
-
- Ad-Hoc Package Management
-
-
- With the command nix-env, you can install and uninstall
- packages from the command line. For instance, to install Mozilla Thunderbird:
-
-$ nix-env -iA nixos.thunderbird
- If you invoke this as root, the package is installed in the Nix profile
- /nix/var/nix/profiles/default and visible to all users
- of the system; otherwise, the package ends up in
- /nix/var/nix/profiles/per-user/username/profile
- and is not visible to other users. The flag specifies the
- package by its attribute name; without it, the package is installed by
- matching against its package name (e.g. thunderbird). The
- latter is slower because it requires matching against all available Nix
- packages, and is ambiguous if there are multiple matching packages.
-
-
-
- Packages come from the NixOS channel. You typically upgrade a package by
- updating to the latest version of the NixOS channel:
-
-$ nix-channel --update nixos
-
- and then running nix-env -i again. Other packages in the
- profile are not affected; this is the crucial difference
- with the declarative style of package management, where running
- nixos-rebuild switch causes all packages to be updated to
- their current versions in the NixOS channel. You can however upgrade all
- packages for which there is a newer version by doing:
-
-$ nix-env -u '*'
-
-
-
-
- A package can be uninstalled using the flag:
-
-$ nix-env -e thunderbird
-
-
-
-
- Finally, you can roll back an undesirable nix-env action:
-
-$ nix-env --rollback
-
-
-
-
- nix-env has many more flags. For details, see the
-
- nix-env
- 1 manpage or the Nix manual.
-
-
diff --git a/nixos/doc/manual/configuration/package-mgmt.xml b/nixos/doc/manual/configuration/package-mgmt.xml
index e8ac5d0681a9..2f9395d26fa8 100644
--- a/nixos/doc/manual/configuration/package-mgmt.xml
+++ b/nixos/doc/manual/configuration/package-mgmt.xml
@@ -27,5 +27,5 @@
-
+
diff --git a/nixos/doc/manual/from_md/configuration/ad-hoc-packages.section.xml b/nixos/doc/manual/from_md/configuration/ad-hoc-packages.section.xml
new file mode 100644
index 000000000000..c9a8d4f3f106
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/ad-hoc-packages.section.xml
@@ -0,0 +1,59 @@
+
+ Ad-Hoc Package Management
+
+ With the command nix-env, you can install and
+ uninstall packages from the command line. For instance, to install
+ Mozilla Thunderbird:
+
+
+$ nix-env -iA nixos.thunderbird
+
+
+ If you invoke this as root, the package is installed in the Nix
+ profile /nix/var/nix/profiles/default and visible
+ to all users of the system; otherwise, the package ends up in
+ /nix/var/nix/profiles/per-user/username/profile
+ and is not visible to other users. The -A flag
+ specifies the package by its attribute name; without it, the package
+ is installed by matching against its package name (e.g.
+ thunderbird). The latter is slower because it
+ requires matching against all available Nix packages, and is
+ ambiguous if there are multiple matching packages.
+
+
+ Packages come from the NixOS channel. You typically upgrade a
+ package by updating to the latest version of the NixOS channel:
+
+
+$ nix-channel --update nixos
+
+
+ and then running nix-env -i again. Other packages
+ in the profile are not affected; this is the
+ crucial difference with the declarative style of package management,
+ where running nixos-rebuild switch causes all
+ packages to be updated to their current versions in the NixOS
+ channel. You can however upgrade all packages for which there is a
+ newer version by doing:
+
+
+$ nix-env -u '*'
+
+
+ A package can be uninstalled using the -e flag:
+
+
+$ nix-env -e thunderbird
+
+
+ Finally, you can roll back an undesirable nix-env
+ action:
+
+
+$ nix-env --rollback
+
+
+ nix-env has many more flags. For details, see the
+ nix-env(1) manpage or the Nix manual.
+
+