Merge pull request #129003 from bobby285271/pr10

nixos/doc: convert "2.5. Additional installation notes" to CommonMark

11 files changed, 435 insertions, 610 deletions

diff --git a/nixos/doc/manual/installation/installing-behind-a-proxy.section.md b/nixos/doc/manual/installation/installing-behind-a-proxy.section.md
new file mode 100644
index 0000000000000..aca151531d0f4
--- /dev/null
+++ b/nixos/doc/manual/installation/installing-behind-a-proxy.section.md
@@ -0,0 +1,29 @@
+# Installing behind a proxy {#sec-installing-behind-proxy}
+
+To install NixOS behind a proxy, do the following before running
+`nixos-install`.
+
+1.  Update proxy configuration in `/mnt/etc/nixos/configuration.nix` to
+    keep the internet accessible after reboot.
+
+    ```nix
+    networking.proxy.default = "http://user:password@proxy:port/";
+    networking.proxy.noProxy = "127.0.0.1,localhost,internal.domain";
+    ```
+
+1.  Setup the proxy environment variables in the shell where you are
+    running `nixos-install`.
+
+    ```ShellSession
+    # proxy_url="http://user:password@proxy:port/"
+    # export http_proxy="$proxy_url"
+    # export HTTP_PROXY="$proxy_url"
+    # export https_proxy="$proxy_url"
+    # export HTTPS_PROXY="$proxy_url"
+    ```
+
+::: {.note}
+If you are switching networks with different proxy configurations, use
+the `specialisation` option in `configuration.nix` to switch proxies at
+runtime. Refer to [](#ch-options) for more information.
+:::
diff --git a/nixos/doc/manual/installation/installing-behind-a-proxy.xml b/nixos/doc/manual/installation/installing-behind-a-proxy.xml
deleted file mode 100644
index 6788882aa8c0f..0000000000000
--- a/nixos/doc/manual/installation/installing-behind-a-proxy.xml
+++ /dev/null
@@ -1,48 +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-installing-behind-proxy">
- <title>Installing behind a proxy</title>
-
- <para>
-  To install NixOS behind a proxy, do the following before running
-  <literal>nixos-install</literal>.
- </para>
-
- <orderedlist numeration="arabic">
-  <listitem>
-   <para>
-    Update proxy configuration in
-    <literal>/mnt/etc/nixos/configuration.nix</literal> to keep the internet
-    accessible after reboot.
-   </para>
-<programlisting>
-networking.proxy.default = &quot;http://user:password@proxy:port/&quot;;
-networking.proxy.noProxy = &quot;127.0.0.1,localhost,internal.domain&quot;;
-</programlisting>
-  </listitem>
-  <listitem>
-   <para>
-    Setup the proxy environment variables in the shell where you are running
-    <literal>nixos-install</literal>.
-   </para>
-<screen>
-<prompt># </prompt>proxy_url=&quot;http://user:password@proxy:port/&quot;
-<prompt># </prompt>export http_proxy=&quot;$proxy_url&quot;
-<prompt># </prompt>export HTTP_PROXY=&quot;$proxy_url&quot;
-<prompt># </prompt>export https_proxy=&quot;$proxy_url&quot;
-<prompt># </prompt>export HTTPS_PROXY=&quot;$proxy_url&quot;
-</screen>
-  </listitem>
- </orderedlist>
-
- <note>
-  <para>
-   If you are switching networks with different proxy configurations, use the
-   <literal>specialisation</literal> option in
-   <literal>configuration.nix</literal> to switch proxies at runtime. Refer to
-   <xref linkend="ch-options" /> for more information.
-  </para>
- </note>
-</section>
diff --git a/nixos/doc/manual/installation/installing-from-other-distro.section.md b/nixos/doc/manual/installation/installing-from-other-distro.section.md
new file mode 100644
index 0000000000000..d9060eb89c372
--- /dev/null
+++ b/nixos/doc/manual/installation/installing-from-other-distro.section.md
@@ -0,0 +1,279 @@
+# Installing from another Linux distribution {#sec-installing-from-other-distro}
+
+Because Nix (the package manager) & Nixpkgs (the Nix packages
+collection) can both be installed on any (most?) Linux distributions,
+they can be used to install NixOS in various creative ways. You can, for
+instance:
+
+1.  Install NixOS on another partition, from your existing Linux
+    distribution (without the use of a USB or optical device!)
+
+1.  Install NixOS on the same partition (in place!), from your existing
+    non-NixOS Linux distribution using `NIXOS_LUSTRATE`.
+
+1.  Install NixOS on your hard drive from the Live CD of any Linux
+    distribution.
+
+The first steps to all these are the same:
+
+1.  Install the Nix package manager:
+
+    Short version:
+
+    ```ShellSession
+    $ curl -L https://nixos.org/nix/install | sh
+    $ . $HOME/.nix-profile/etc/profile.d/nix.sh # …or open a fresh shell
+    ```
+
+    More details in the [ Nix
+    manual](https://nixos.org/nix/manual/#chap-quick-start)
+
+1.  Switch to the NixOS channel:
+
+    If you\'ve just installed Nix on a non-NixOS distribution, you will
+    be on the `nixpkgs` channel by default.
+
+    ```ShellSession
+    $ nix-channel --list
+    nixpkgs https://nixos.org/channels/nixpkgs-unstable
+    ```
+
+    As that channel gets released without running the NixOS tests, it
+    will be safer to use the `nixos-*` channels instead:
+
+    ```ShellSession
+    $ nix-channel --add https://nixos.org/channels/nixos-version nixpkgs
+    ```
+
+    You may want to throw in a `nix-channel --update` for good measure.
+
+1.  Install the NixOS installation tools:
+
+    You\'ll need `nixos-generate-config` and `nixos-install`, but this
+    also makes some man pages and `nixos-enter` available, just in case
+    you want to chroot into your NixOS partition. NixOS installs these
+    by default, but you don\'t have NixOS yet..
+
+    ```ShellSession
+    $ nix-env -f '<nixpkgs>' -iA nixos-install-tools
+    ```
+
+1.  ::: {.note}
+    The following 5 steps are only for installing NixOS to another
+    partition. For installing NixOS in place using `NIXOS_LUSTRATE`,
+    skip ahead.
+    :::
+
+    Prepare your target partition:
+
+    At this point it is time to prepare your target partition. Please
+    refer to the partitioning, file-system creation, and mounting steps
+    of [](#sec-installation)
+
+    If you\'re about to install NixOS in place using `NIXOS_LUSTRATE`
+    there is nothing to do for this step.
+
+1.  Generate your NixOS configuration:
+
+    ```ShellSession
+    $ sudo `which nixos-generate-config` --root /mnt
+    ```
+
+    You\'ll probably want to edit the configuration files. Refer to the
+    `nixos-generate-config` step in [](#sec-installation) for more
+    information.
+
+    Consider setting up the NixOS bootloader to give you the ability to
+    boot on your existing Linux partition. For instance, if you\'re
+    using GRUB and your existing distribution is running Ubuntu, you may
+    want to add something like this to your `configuration.nix`:
+
+    ```nix
+    boot.loader.grub.extraEntries = ''
+      menuentry "Ubuntu" {
+        search --set=ubuntu --fs-uuid 3cc3e652-0c1f-4800-8451-033754f68e6e
+        configfile "($ubuntu)/boot/grub/grub.cfg"
+      }
+    '';
+    ```
+
+    (You can find the appropriate UUID for your partition in
+    `/dev/disk/by-uuid`)
+
+1.  Create the `nixbld` group and user on your original distribution:
+
+    ```ShellSession
+    $ sudo groupadd -g 30000 nixbld
+    $ sudo useradd -u 30000 -g nixbld -G nixbld nixbld
+    ```
+
+1.  Download/build/install NixOS:
+
+    ::: {.warning}
+    Once you complete this step, you might no longer be able to boot on
+    existing systems without the help of a rescue USB drive or similar.
+    :::
+
+    ::: {.note}
+    On some distributions there are separate PATHS for programs intended
+    only for root. In order for the installation to succeed, you might
+    have to use `PATH="$PATH:/usr/sbin:/sbin"` in the following command.
+    :::
+
+    ```ShellSession
+    $ sudo PATH="$PATH" NIX_PATH="$NIX_PATH" `which nixos-install` --root /mnt
+    ```
+
+    Again, please refer to the `nixos-install` step in
+    [](#sec-installation) for more information.
+
+    That should be it for installation to another partition!
+
+1.  Optionally, you may want to clean up your non-NixOS distribution:
+
+    ```ShellSession
+    $ sudo userdel nixbld
+    $ sudo groupdel nixbld
+    ```
+
+    If you do not wish to keep the Nix package manager installed either,
+    run something like `sudo rm -rv ~/.nix-* /nix` and remove the line
+    that the Nix installer added to your `~/.profile`.
+
+1.  ::: {.note}
+    The following steps are only for installing NixOS in place using
+    `NIXOS_LUSTRATE`:
+    :::
+
+    Generate your NixOS configuration:
+
+    ```ShellSession
+    $ sudo `which nixos-generate-config` --root /
+    ```
+
+    Note that this will place the generated configuration files in
+    `/etc/nixos`. You\'ll probably want to edit the configuration files.
+    Refer to the `nixos-generate-config` step in
+    [](#sec-installation) for more information.
+
+    You\'ll likely want to set a root password for your first boot using
+    the configuration files because you won\'t have a chance to enter a
+    password until after you reboot. You can initalize the root password
+    to an empty one with this line: (and of course don\'t forget to set
+    one once you\'ve rebooted or to lock the account with
+    `sudo passwd -l root` if you use `sudo`)
+
+    ```nix
+    users.users.root.initialHashedPassword = "";
+    ```
+
+1.  Build the NixOS closure and install it in the `system` profile:
+
+    ```ShellSession
+    $ nix-env -p /nix/var/nix/profiles/system -f '<nixpkgs/nixos>' -I nixos-config=/etc/nixos/configuration.nix -iA system
+    ```
+
+1.  Change ownership of the `/nix` tree to root (since your Nix install
+    was probably single user):
+
+    ```ShellSession
+    $ sudo chown -R 0.0 /nix
+    ```
+
+1.  Set up the `/etc/NIXOS` and `/etc/NIXOS_LUSTRATE` files:
+
+    `/etc/NIXOS` officializes that this is now a NixOS partition (the
+    bootup scripts require its presence).
+
+    `/etc/NIXOS_LUSTRATE` tells the NixOS bootup scripts to move
+    *everything* that\'s in the root partition to `/old-root`. This will
+    move your existing distribution out of the way in the very early
+    stages of the NixOS bootup. There are exceptions (we do need to keep
+    NixOS there after all), so the NixOS lustrate process will not
+    touch:
+
+    -   The `/nix` directory
+
+    -   The `/boot` directory
+
+    -   Any file or directory listed in `/etc/NIXOS_LUSTRATE` (one per
+        line)
+
+    ::: {.note}
+    Support for `NIXOS_LUSTRATE` was added in NixOS 16.09. The act of
+    \"lustrating\" refers to the wiping of the existing distribution.
+    Creating `/etc/NIXOS_LUSTRATE` can also be used on NixOS to remove
+    all mutable files from your root partition (anything that\'s not in
+    `/nix` or `/boot` gets \"lustrated\" on the next boot.
+
+    lustrate /ˈlʌstreɪt/ verb.
+
+    purify by expiatory sacrifice, ceremonial washing, or some other
+    ritual action.
+    :::
+
+    Let\'s create the files:
+
+    ```ShellSession
+    $ sudo touch /etc/NIXOS
+    $ sudo touch /etc/NIXOS_LUSTRATE
+    ```
+
+    Let\'s also make sure the NixOS configuration files are kept once we
+    reboot on NixOS:
+
+    ```ShellSession
+    $ echo etc/nixos | sudo tee -a /etc/NIXOS_LUSTRATE
+    ```
+
+1.  Finally, move the `/boot` directory of your current distribution out
+    of the way (the lustrate process will take care of the rest once you
+    reboot, but this one must be moved out now because NixOS needs to
+    install its own boot files:
+
+    ::: {.warning}
+    Once you complete this step, your current distribution will no
+    longer be bootable! If you didn\'t get all the NixOS configuration
+    right, especially those settings pertaining to boot loading and root
+    partition, NixOS may not be bootable either. Have a USB rescue
+    device ready in case this happens.
+    :::
+
+    ```ShellSession
+    $ sudo mv -v /boot /boot.bak &&
+    sudo /nix/var/nix/profiles/system/bin/switch-to-configuration boot
+    ```
+
+    Cross your fingers, reboot, hopefully you should get a NixOS prompt!
+
+1.  If for some reason you want to revert to the old distribution,
+    you\'ll need to boot on a USB rescue disk and do something along
+    these lines:
+
+    ```ShellSession
+    # mkdir root
+    # mount /dev/sdaX root
+    # mkdir root/nixos-root
+    # mv -v root/* root/nixos-root/
+    # mv -v root/nixos-root/old-root/* root/
+    # mv -v root/boot.bak root/boot  # We had renamed this by hand earlier
+    # umount root
+    # reboot
+    ```
+
+    This may work as is or you might also need to reinstall the boot
+    loader.
+
+    And of course, if you\'re happy with NixOS and no longer need the
+    old distribution:
+
+    ```ShellSession
+    sudo rm -rf /old-root
+    ```
+
+1.  It\'s also worth noting that this whole process can be automated.
+    This is especially useful for Cloud VMs, where provider do not
+    provide NixOS. For instance,
+    [nixos-infect](https://github.com/elitak/nixos-infect) uses the
+    lustrate process to convert Digital Ocean droplets to NixOS from
+    other distributions automatically.
diff --git a/nixos/doc/manual/installation/installing-from-other-distro.xml b/nixos/doc/manual/installation/installing-from-other-distro.xml
deleted file mode 100644
index 63d1d52b01b2f..0000000000000
--- a/nixos/doc/manual/installation/installing-from-other-distro.xml
+++ /dev/null
@@ -1,364 +0,0 @@
-<!-- vim: set expandtab ts=2 softtabstop=2 shiftwidth=2 smarttab textwidth=80 wrapmargin=2 -->
-<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-installing-from-other-distro">
- <title>Installing from another Linux distribution</title>
-
- <para>
-  Because Nix (the package manager) &amp; Nixpkgs (the Nix packages collection)
-  can both be installed on any (most?) Linux distributions, they can be used to
-  install NixOS in various creative ways. You can, for instance:
- </para>
-
- <orderedlist>
-  <listitem>
-   <para>
-    Install NixOS on another partition, from your existing Linux distribution
-    (without the use of a USB or optical device!)
-   </para>
-  </listitem>
-  <listitem>
-   <para>
-    Install NixOS on the same partition (in place!), from your existing
-    non-NixOS Linux distribution using <literal>NIXOS_LUSTRATE</literal>.
-   </para>
-  </listitem>
-  <listitem>
-   <para>
-    Install NixOS on your hard drive from the Live CD of any Linux
-    distribution.
-   </para>
-  </listitem>
- </orderedlist>
-
- <para>
-  The first steps to all these are the same:
- </para>
-
- <orderedlist>
-  <listitem>
-   <para>
-    Install the Nix package manager:
-   </para>
-   <para>
-    Short version:
-   </para>
-<screen>
-<prompt>$ </prompt>curl -L https://nixos.org/nix/install | sh
-<prompt>$ </prompt>. $HOME/.nix-profile/etc/profile.d/nix.sh # …or open a fresh shell</screen>
-   <para>
-    More details in the
-    <link
-                    xlink:href="https://nixos.org/nix/manual/#chap-quick-start">
-    Nix manual</link>
-   </para>
-  </listitem>
-  <listitem>
-   <para>
-    Switch to the NixOS channel:
-   </para>
-   <para>
-    If you've just installed Nix on a non-NixOS distribution, you will be on
-    the <literal>nixpkgs</literal> channel by default.
-   </para>
-<screen>
-<prompt>$ </prompt>nix-channel --list
-nixpkgs https://nixos.org/channels/nixpkgs-unstable</screen>
-   <para>
-    As that channel gets released without running the NixOS tests, it will be
-    safer to use the <literal>nixos-*</literal> channels instead:
-   </para>
-<screen>
-<prompt>$ </prompt>nix-channel --add https://nixos.org/channels/nixos-<replaceable>version</replaceable> nixpkgs</screen>
-   <para>
-    You may want to throw in a <literal>nix-channel --update</literal> for good
-    measure.
-   </para>
-  </listitem>
-  <listitem>
-   <para>
-    Install the NixOS installation tools:
-   </para>
-   <para>
-    You'll need <literal>nixos-generate-config</literal> and
-    <literal>nixos-install</literal>, but this also makes some man pages
-    and <literal>nixos-enter</literal> available, just in case you want to chroot into your
-    NixOS partition. NixOS installs these by default, but you don't have
-    NixOS yet..
-   </para>
-   <screen><prompt>$ </prompt>nix-env -f '&lt;nixpkgs>' -iA nixos-install-tools</screen>
-  </listitem>
-  <listitem>
-   <note>
-    <para>
-     The following 5 steps are only for installing NixOS to another partition.
-     For installing NixOS in place using <literal>NIXOS_LUSTRATE</literal>,
-     skip ahead.
-    </para>
-   </note>
-   <para>
-    Prepare your target partition:
-   </para>
-   <para>
-    At this point it is time to prepare your target partition. Please refer to
-    the partitioning, file-system creation, and mounting steps of
-    <xref linkend="sec-installation" />
-   </para>
-   <para>
-    If you're about to install NixOS in place using
-    <literal>NIXOS_LUSTRATE</literal> there is nothing to do for this step.
-   </para>
-  </listitem>
-  <listitem>
-   <para>
-    Generate your NixOS configuration:
-   </para>
-<screen><prompt>$ </prompt>sudo `which nixos-generate-config` --root /mnt</screen>
-   <para>
-    You'll probably want to edit the configuration files. Refer to the
-    <literal>nixos-generate-config</literal> step in
-    <xref
-                    linkend="sec-installation" /> for more
-    information.
-   </para>
-   <para>
-    Consider setting up the NixOS bootloader to give you the ability to boot on
-    your existing Linux partition. For instance, if you're using GRUB and your
-    existing distribution is running Ubuntu, you may want to add something like
-    this to your <literal>configuration.nix</literal>:
-   </para>
-<programlisting>
-<xref linkend="opt-boot.loader.grub.extraEntries"/> = ''
-  menuentry "Ubuntu" {
-    search --set=ubuntu --fs-uuid 3cc3e652-0c1f-4800-8451-033754f68e6e
-    configfile "($ubuntu)/boot/grub/grub.cfg"
-  }
-'';</programlisting>
-   <para>
-    (You can find the appropriate UUID for your partition in
-    <literal>/dev/disk/by-uuid</literal>)
-   </para>
-  </listitem>
-  <listitem>
-   <para>
-    Create the <literal>nixbld</literal> group and user on your original
-    distribution:
-   </para>
-<screen>
-<prompt>$ </prompt>sudo groupadd -g 30000 nixbld
-<prompt>$ </prompt>sudo useradd -u 30000 -g nixbld -G nixbld nixbld</screen>
-  </listitem>
-  <listitem>
-   <para>
-    Download/build/install NixOS:
-   </para>
-   <warning>
-    <para>
-     Once you complete this step, you might no longer be able to boot on
-     existing systems without the help of a rescue USB drive or similar.
-    </para>
-   </warning>
-   <note>
-    <para>
-     On some distributions there are separate PATHS for programs intended only for root.
-     In order for the installation to succeed, you might have to use <literal>PATH="$PATH:/usr/sbin:/sbin"</literal>
-     in the following command.
-    </para>
-   </note>
-<screen><prompt>$ </prompt>sudo PATH="$PATH" NIX_PATH="$NIX_PATH" `which nixos-install` --root /mnt</screen>
-   <para>
-    Again, please refer to the <literal>nixos-install</literal> step in
-    <xref linkend="sec-installation" /> for more information.
-   </para>
-   <para>
-    That should be it for installation to another partition!
-   </para>
-  </listitem>
-  <listitem>
-   <para>
-    Optionally, you may want to clean up your non-NixOS distribution:
-   </para>
-<screen>
-<prompt>$ </prompt>sudo userdel nixbld
-<prompt>$ </prompt>sudo groupdel nixbld</screen>
-   <para>
-    If you do not wish to keep the Nix package manager installed either, run
-    something like <literal>sudo rm -rv ~/.nix-* /nix</literal> and remove the
-    line that the Nix installer added to your <literal>~/.profile</literal>.
-   </para>
-  </listitem>
-  <listitem>
-   <note>
-    <para>
-     The following steps are only for installing NixOS in place using
-     <literal>NIXOS_LUSTRATE</literal>:
-    </para>
-   </note>
-   <para>
-    Generate your NixOS configuration:
-   </para>
-<screen><prompt>$ </prompt>sudo `which nixos-generate-config` --root /</screen>
-   <para>
-    Note that this will place the generated configuration files in
-    <literal>/etc/nixos</literal>. You'll probably want to edit the
-    configuration files. Refer to the <literal>nixos-generate-config</literal>
-    step in <xref
-                    linkend="sec-installation" /> for more
-    information.
-   </para>
-   <para>
-    You'll likely want to set a root password for your first boot using the
-    configuration files because you won't have a chance to enter a password
-    until after you reboot. You can initalize the root password to an empty one
-    with this line: (and of course don't forget to set one once you've rebooted
-    or to lock the account with <literal>sudo passwd -l root</literal> if you
-    use <literal>sudo</literal>)
-   </para>
-<programlisting>
-<link linkend="opt-users.users._name_.initialHashedPassword">users.users.root.initialHashedPassword</link> = "";
-</programlisting>
-  </listitem>
-  <listitem>
-   <para>
-    Build the NixOS closure and install it in the <literal>system</literal>
-    profile:
-   </para>
-<screen><prompt>$ </prompt>nix-env -p /nix/var/nix/profiles/system -f '&lt;nixpkgs/nixos&gt;' -I nixos-config=/etc/nixos/configuration.nix -iA system</screen>
-  </listitem>
-  <listitem>
-   <para>
-    Change ownership of the <literal>/nix</literal> tree to root (since your
-    Nix install was probably single user):
-   </para>
-<screen><prompt>$ </prompt>sudo chown -R 0.0 /nix</screen>
-  </listitem>
-  <listitem>
-   <para>
-    Set up the <literal>/etc/NIXOS</literal> and
-    <literal>/etc/NIXOS_LUSTRATE</literal> files:
-   </para>
-   <para>
-    <literal>/etc/NIXOS</literal> officializes that this is now a NixOS
-    partition (the bootup scripts require its presence).
-   </para>
-   <para>
-    <literal>/etc/NIXOS_LUSTRATE</literal> tells the NixOS bootup scripts to
-    move <emphasis>everything</emphasis> that's in the root partition to
-    <literal>/old-root</literal>. This will move your existing distribution out
-    of the way in the very early stages of the NixOS bootup. There are
-    exceptions (we do need to keep NixOS there after all), so the NixOS
-    lustrate process will not touch:
-   </para>
-   <itemizedlist>
-    <listitem>
-     <para>
-      The <literal>/nix</literal> directory
-     </para>
-    </listitem>
-    <listitem>
-     <para>
-      The <literal>/boot</literal> directory
-     </para>
-    </listitem>
-    <listitem>
-     <para>
-      Any file or directory listed in <literal>/etc/NIXOS_LUSTRATE</literal>
-      (one per line)
-     </para>
-    </listitem>
-   </itemizedlist>
-   <note>
-    <para>
-     Support for <literal>NIXOS_LUSTRATE</literal> was added in NixOS 16.09.
-     The act of "lustrating" refers to the wiping of the existing distribution.
-     Creating <literal>/etc/NIXOS_LUSTRATE</literal> can also be used on NixOS
-     to remove all mutable files from your root partition (anything that's not
-     in <literal>/nix</literal> or <literal>/boot</literal> gets "lustrated" on
-     the next boot.
-    </para>
-    <para>
-     lustrate /ˈlʌstreɪt/ verb.
-    </para>
-    <para>
-     purify by expiatory sacrifice, ceremonial washing, or some other ritual
-     action.
-    </para>
-   </note>
-   <para>
-    Let's create the files:
-   </para>
-<screen>
-<prompt>$ </prompt>sudo touch /etc/NIXOS
-<prompt>$ </prompt>sudo touch /etc/NIXOS_LUSTRATE
-</screen>
-   <para>
-    Let's also make sure the NixOS configuration files are kept once we reboot
-    on NixOS:
-   </para>
-<screen>
-<prompt>$ </prompt>echo etc/nixos | sudo tee -a /etc/NIXOS_LUSTRATE
-</screen>
-  </listitem>
-  <listitem>
-   <para>
-    Finally, move the <literal>/boot</literal> directory of your current
-    distribution out of the way (the lustrate process will take care of the
-    rest once you reboot, but this one must be moved out now because NixOS
-    needs to install its own boot files:
-   </para>
-   <warning>
-    <para>
-     Once you complete this step, your current distribution will no longer be
-     bootable! If you didn't get all the NixOS configuration right, especially
-     those settings pertaining to boot loading and root partition, NixOS may
-     not be bootable either. Have a USB rescue device ready in case this
-     happens.
-    </para>
-   </warning>
-<screen>
-<prompt>$ </prompt>sudo mv -v /boot /boot.bak &amp;&amp;
-sudo /nix/var/nix/profiles/system/bin/switch-to-configuration boot
-</screen>
-   <para>
-    Cross your fingers, reboot, hopefully you should get a NixOS prompt!
-   </para>
-  </listitem>
-  <listitem>
-   <para>
-    If for some reason you want to revert to the old distribution, you'll need
-    to boot on a USB rescue disk and do something along these lines:
-   </para>
-<screen>
-<prompt># </prompt>mkdir root
-<prompt># </prompt>mount /dev/sdaX root
-<prompt># </prompt>mkdir root/nixos-root
-<prompt># </prompt>mv -v root/* root/nixos-root/
-<prompt># </prompt>mv -v root/nixos-root/old-root/* root/
-<prompt># </prompt>mv -v root/boot.bak root/boot  # We had renamed this by hand earlier
-<prompt># </prompt>umount root
-<prompt># </prompt>reboot</screen>
-   <para>
-    This may work as is or you might also need to reinstall the boot loader
-   </para>
-   <para>
-    And of course, if you're happy with NixOS and no longer need the old
-    distribution:
-   </para>
-<screen>sudo rm -rf /old-root</screen>
-  </listitem>
-  <listitem>
-   <para>
-    It's also worth noting that this whole process can be automated. This is
-    especially useful for Cloud VMs, where provider do not provide NixOS. For
-    instance,
-    <link
-                    xlink:href="https://github.com/elitak/nixos-infect">nixos-infect</link>
-    uses the lustrate process to convert Digital Ocean droplets to NixOS from
-    other distributions automatically.
-   </para>
-  </listitem>
- </orderedlist>
-</section>
diff --git a/nixos/doc/manual/installation/installing-pxe.section.md b/nixos/doc/manual/installation/installing-pxe.section.md
new file mode 100644
index 0000000000000..2016a258251f8
--- /dev/null
+++ b/nixos/doc/manual/installation/installing-pxe.section.md
@@ -0,0 +1,32 @@
+# Booting from the "netboot" media (PXE) {#sec-booting-from-pxe}
+
+Advanced users may wish to install NixOS using an existing PXE or iPXE
+setup.
+
+These instructions assume that you have an existing PXE or iPXE
+infrastructure and simply want to add the NixOS installer as another
+option. To build the necessary files from a recent version of nixpkgs,
+you can run:
+
+```ShellSession
+nix-build -A netboot.x86_64-linux nixos/release.nix
+```
+
+This will create a `result` directory containing: \* `bzImage` -- the
+Linux kernel \* `initrd` -- the initrd file \* `netboot.ipxe` -- an
+example ipxe script demonstrating the appropriate kernel command line
+arguments for this image
+
+If you're using plain PXE, configure your boot loader to use the
+`bzImage` and `initrd` files and have it provide the same kernel command
+line arguments found in `netboot.ipxe`.
+
+If you're using iPXE, depending on how your HTTP/FTP/etc. server is
+configured you may be able to use `netboot.ipxe` unmodified, or you may
+need to update the paths to the files to match your server's directory
+layout.
+
+In the future we may begin making these files available as build
+products from hydra at which point we will update this documentation
+with instructions on how to obtain them either for placing on a
+dedicated TFTP server or to boot them directly over the internet.
diff --git a/nixos/doc/manual/installation/installing-pxe.xml b/nixos/doc/manual/installation/installing-pxe.xml
deleted file mode 100644
index ea88fbdad7e29..0000000000000
--- a/nixos/doc/manual/installation/installing-pxe.xml
+++ /dev/null
@@ -1,50 +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-booting-from-pxe">
- <title>Booting from the <quote>netboot</quote> media (PXE)</title>
-
- <para>
-  Advanced users may wish to install NixOS using an existing PXE or iPXE setup.
- </para>
-
- <para>
-  These instructions assume that you have an existing PXE or iPXE
-  infrastructure and simply want to add the NixOS installer as another option.
-  To build the necessary files from a recent version of nixpkgs, you can run:
- </para>
-
-<programlisting>
-nix-build -A netboot.x86_64-linux nixos/release.nix
-</programlisting>
-
- <para>
-  This will create a <literal>result</literal> directory containing: *
-  <literal>bzImage</literal> – the Linux kernel * <literal>initrd</literal>
-  – the initrd file * <literal>netboot.ipxe</literal> – an example ipxe
-  script demonstrating the appropriate kernel command line arguments for this
-  image
- </para>
-
- <para>
-  If you’re using plain PXE, configure your boot loader to use the
-  <literal>bzImage</literal> and <literal>initrd</literal> files and have it
-  provide the same kernel command line arguments found in
-  <literal>netboot.ipxe</literal>.
- </para>
-
- <para>
-  If you’re using iPXE, depending on how your HTTP/FTP/etc. server is
-  configured you may be able to use <literal>netboot.ipxe</literal> unmodified,
-  or you may need to update the paths to the files to match your server’s
-  directory layout
- </para>
-
- <para>
-  In the future we may begin making these files available as build products
-  from hydra at which point we will update this documentation with instructions
-  on how to obtain them either for placing on a dedicated TFTP server or to
-  boot them directly over the internet.
- </para>
-</section>
diff --git a/nixos/doc/manual/installation/installing-usb.section.md b/nixos/doc/manual/installation/installing-usb.section.md
new file mode 100644
index 0000000000000..ae58c08e5237e
--- /dev/null
+++ b/nixos/doc/manual/installation/installing-usb.section.md
@@ -0,0 +1,31 @@
+# Booting from a USB Drive {#sec-booting-from-usb}
+
+For systems without CD drive, the NixOS live CD can be booted from a USB
+stick. You can use the `dd` utility to write the image:
+`dd if=path-to-image of=/dev/sdX`. Be careful about specifying the correct
+drive; you can use the `lsblk` command to get a list of block devices.
+
+::: {.note}
+::: {.title}
+On macOS
+:::
+
+```ShellSession
+$ diskutil list
+[..]
+/dev/diskN (external, physical):
+   #:                       TYPE NAME                    SIZE       IDENTIFIER
+[..]
+$ diskutil unmountDisk diskN
+Unmount of all volumes on diskN was successful
+$ sudo dd if=nix.iso of=/dev/rdiskN
+```
+
+Using the \'raw\' `rdiskN` device instead of `diskN` completes in
+minutes instead of hours. After `dd` completes, a GUI dialog \"The disk
+you inserted was not readable by this computer\" will pop up, which can
+be ignored.
+:::
+
+The `dd` utility will write the image verbatim to the drive, making it
+the recommended option for both UEFI and non-UEFI installations.
diff --git a/nixos/doc/manual/installation/installing-usb.xml b/nixos/doc/manual/installation/installing-usb.xml
deleted file mode 100644
index 83598635accab..0000000000000
--- a/nixos/doc/manual/installation/installing-usb.xml
+++ /dev/null
@@ -1,40 +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-booting-from-usb">
- <title>Booting from a USB Drive</title>
-
- <para>
-  For systems without CD drive, the NixOS live CD can be booted from a USB
-  stick. You can use the <command>dd</command> utility to write the image:
-  <command>dd if=<replaceable>path-to-image</replaceable>
-  of=<replaceable>/dev/sdX</replaceable></command>. Be careful about specifying
-  the correct drive; you can use the <command>lsblk</command> command to get a
-  list of block devices.
-  <note>
-   <title>On macOS</title>
-   <para>
-<screen>
-<prompt>$ </prompt>diskutil list
-[..]
-/dev/diskN (external, physical):
-   #:                       TYPE NAME                    SIZE       IDENTIFIER
-[..]
-<prompt>$ </prompt>diskutil unmountDisk diskN
-Unmount of all volumes on diskN was successful
-<prompt>$ </prompt>sudo dd if=nix.iso of=/dev/rdiskN
-</screen>
-    Using the 'raw' <command>rdiskN</command> device instead of
-    <command>diskN</command> completes in minutes instead of hours. After
-    <command>dd</command> completes, a GUI dialog "The disk you inserted was
-    not readable by this computer" will pop up, which can be ignored.
-   </para>
-  </note>
- </para>
-
- <para>
-  The <command>dd</command> utility will write the image verbatim to the drive,
-  making it the recommended option for both UEFI and non-UEFI installations.
- </para>
-</section>
diff --git a/nixos/doc/manual/installation/installing-virtualbox-guest.section.md b/nixos/doc/manual/installation/installing-virtualbox-guest.section.md
new file mode 100644
index 0000000000000..e9c2a621c1bba
--- /dev/null
+++ b/nixos/doc/manual/installation/installing-virtualbox-guest.section.md
@@ -0,0 +1,59 @@
+# Installing in a VirtualBox guest {#sec-instaling-virtualbox-guest}
+
+Installing NixOS into a VirtualBox guest is convenient for users who
+want to try NixOS without installing it on bare metal. If you want to
+use a pre-made VirtualBox appliance, it is available at [the downloads
+page](https://nixos.org/nixos/download.html). If you want to set up a
+VirtualBox guest manually, follow these instructions:
+
+1.  Add a New Machine in VirtualBox with OS Type \"Linux / Other Linux\"
+
+1.  Base Memory Size: 768 MB or higher.
+
+1.  New Hard Disk of 8 GB or higher.
+
+1.  Mount the CD-ROM with the NixOS ISO (by clicking on CD/DVD-ROM)
+
+1.  Click on Settings / System / Processor and enable PAE/NX
+
+1.  Click on Settings / System / Acceleration and enable \"VT-x/AMD-V\"
+    acceleration
+
+1.  Click on Settings / Display / Screen and select VMSVGA as Graphics
+    Controller
+
+1.  Save the settings, start the virtual machine, and continue
+    installation like normal
+
+There are a few modifications you should make in configuration.nix.
+Enable booting:
+
+```nix
+boot.loader.grub.device = "/dev/sda";
+```
+
+Also remove the fsck that runs at startup. It will always fail to run,
+stopping your boot until you press `*`.
+
+```nix
+boot.initrd.checkJournalingFS = false;
+```
+
+Shared folders can be given a name and a path in the host system in the
+VirtualBox settings (Machine / Settings / Shared Folders, then click on
+the \"Add\" icon). Add the following to the
+`/etc/nixos/configuration.nix` to auto-mount them. If you do not add
+`"nofail"`, the system will not boot properly.
+
+```nix
+{ config, pkgs, ...} :
+{
+  fileSystems."/virtualboxshare" = {
+    fsType = "vboxsf";
+    device = "nameofthesharedfolder";
+    options = [ "rw" "nofail" ];
+  };
+}
+```
+
+The folder will be available directly under the root directory.
diff --git a/nixos/doc/manual/installation/installing-virtualbox-guest.xml b/nixos/doc/manual/installation/installing-virtualbox-guest.xml
deleted file mode 100644
index 019e5098a8e27..0000000000000
--- a/nixos/doc/manual/installation/installing-virtualbox-guest.xml
+++ /dev/null
@@ -1,103 +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-instaling-virtualbox-guest">
- <title>Installing in a VirtualBox guest</title>
-
- <para>
-  Installing NixOS into a VirtualBox guest is convenient for users who want to
-  try NixOS without installing it on bare metal. If you want to use a pre-made
-  VirtualBox appliance, it is available at
-  <link
-  xlink:href="https://nixos.org/nixos/download.html">the downloads
-  page</link>. If you want to set up a VirtualBox guest manually, follow these
-  instructions:
- </para>
-
- <orderedlist>
-  <listitem>
-   <para>
-    Add a New Machine in VirtualBox with OS Type "Linux / Other Linux"
-   </para>
-  </listitem>
-  <listitem>
-   <para>
-    Base Memory Size: 768 MB or higher.
-   </para>
-  </listitem>
-  <listitem>
-   <para>
-    New Hard Disk of 8 GB or higher.
-   </para>
-  </listitem>
-  <listitem>
-   <para>
-    Mount the CD-ROM with the NixOS ISO (by clicking on CD/DVD-ROM)
-   </para>
-  </listitem>
-  <listitem>
-   <para>
-    Click on Settings / System / Processor and enable PAE/NX
-   </para>
-  </listitem>
-  <listitem>
-   <para>
-    Click on Settings / System / Acceleration and enable "VT-x/AMD-V"
-    acceleration
-   </para>
-  </listitem>
-  <listitem>
-   <para>
-    Click on Settings / Display / Screen and select VMSVGA as Graphics Controller
-   </para>
-  </listitem>
-  <listitem>
-   <para>
-    Save the settings, start the virtual machine, and continue installation
-    like normal
-   </para>
-  </listitem>
- </orderedlist>
-
- <para>
-  There are a few modifications you should make in configuration.nix. Enable
-  booting:
- </para>
-
-<programlisting>
-<xref linkend="opt-boot.loader.grub.device"/> = "/dev/sda";
-</programlisting>
-
- <para>
-  Also remove the fsck that runs at startup. It will always fail to run,
-  stopping your boot until you press <literal>*</literal>.
- </para>
-
-<programlisting>
-<xref linkend="opt-boot.initrd.checkJournalingFS"/> = false;
-</programlisting>
-
- <para>
-  Shared folders can be given a name and a path in the host system in the
-  VirtualBox settings (Machine / Settings / Shared Folders, then click on the
-  "Add" icon). Add the following to the
-  <literal>/etc/nixos/configuration.nix</literal> to auto-mount them. If you do
-  not add <literal>"nofail"</literal>, the system will not boot properly.
- </para>
-
-<programlisting>
-{ config, pkgs, ...} :
-{
-  fileSystems."/virtualboxshare" = {
-    fsType = "vboxsf";
-    device = "nameofthesharedfolder";
-    options = [ "rw" "nofail" ];
-  };
-}
-</programlisting>
-
- <para>
-  The folder will be available directly under the root directory.
- </para>
-</section>
diff --git a/nixos/doc/manual/installation/installing.xml b/nixos/doc/manual/installation/installing.xml
index ff2425e725e8c..6eb097f243ab8 100644
--- a/nixos/doc/manual/installation/installing.xml
+++ b/nixos/doc/manual/installation/installing.xml
@@ -603,14 +603,14 @@ Retype new password: ***</screen>
  <section xml:id="sec-installation-additional-notes">
   <title>Additional installation notes</title>
 
-  <xi:include href="installing-usb.xml" />
+  <xi:include href="../from_md/installation/installing-usb.section.xml" />
 
-  <xi:include href="installing-pxe.xml" />
+  <xi:include href="../from_md/installation/installing-pxe.section.xml" />
 
-  <xi:include href="installing-virtualbox-guest.xml" />
+  <xi:include href="../from_md/installation/installing-virtualbox-guest.section.xml" />
 
-  <xi:include href="installing-from-other-distro.xml" />
+  <xi:include href="../from_md/installation/installing-from-other-distro.section.xml" />
 
-  <xi:include href="installing-behind-a-proxy.xml" />
+  <xi:include href="../from_md/installation/installing-behind-a-proxy.section.xml" />
  </section>
 </chapter>