diff --git a/nixos/doc/manual/configuration/networking.xml b/nixos/doc/manual/configuration/networking.xml
index 6b078bb3b6c..c326785dbe3 100644
--- a/nixos/doc/manual/configuration/networking.xml
+++ b/nixos/doc/manual/configuration/networking.xml
@@ -9,7 +9,7 @@
   machine.
  </para>
  <xi:include href="../from_md/configuration/network-manager.section.xml" />
- <xi:include href="ssh.xml" />
+ <xi:include href="../from_md/configuration/ssh.section.xml" />
  <xi:include href="ipv4-config.xml" />
  <xi:include href="ipv6-config.xml" />
  <xi:include href="firewall.xml" />
diff --git a/nixos/doc/manual/configuration/ssh.section.md b/nixos/doc/manual/configuration/ssh.section.md
new file mode 100644
index 00000000000..9390108ad8b
--- /dev/null
+++ b/nixos/doc/manual/configuration/ssh.section.md
@@ -0,0 +1,19 @@
+# Secure Shell Access {#sec-ssh}
+
+Secure shell (SSH) access to your machine can be enabled by setting:
+
+```nix
+services.openssh.enable = true;
+```
+
+By default, root logins using a password are disallowed. They can be
+disabled entirely by setting
+[`services.openssh.permitRootLogin`](options.html#opt-services.openssh.permitRootLogin) to `"no"`.
+
+You can declaratively specify authorised RSA/DSA public keys for a user
+as follows:
+
+```nix
+users.users.alice.openssh.authorizedKeys.keys =
+  [ "ssh-dss AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ];
+```
diff --git a/nixos/doc/manual/configuration/ssh.xml b/nixos/doc/manual/configuration/ssh.xml
deleted file mode 100644
index 95ad3edff93..00000000000
--- a/nixos/doc/manual/configuration/ssh.xml
+++ /dev/null
@@ -1,27 +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-ssh">
- <title>Secure Shell Access</title>
-
- <para>
-  Secure shell (SSH) access to your machine can be enabled by setting:
-<programlisting>
-<xref linkend="opt-services.openssh.enable"/> = true;
-</programlisting>
-  By default, root logins using a password are disallowed. They can be disabled
-  entirely by setting <xref linkend="opt-services.openssh.permitRootLogin"/> to
-  <literal>"no"</literal>.
- </para>
-
- <para>
-  You can declaratively specify authorised RSA/DSA public keys for a user as
-  follows:
-<!-- FIXME: this might not work if the user is unmanaged. -->
-<programlisting>
-<link linkend="opt-users.users._name_.openssh.authorizedKeys.keys">users.users.alice.openssh.authorizedKeys.keys</link> =
-  [ "ssh-dss AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ];
-</programlisting>
- </para>
-</section>
diff --git a/nixos/doc/manual/from_md/configuration/ssh.section.xml b/nixos/doc/manual/from_md/configuration/ssh.section.xml
new file mode 100644
index 00000000000..46046064535
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/ssh.section.xml
@@ -0,0 +1,23 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-ssh">
+  <title>Secure Shell Access</title>
+  <para>
+    Secure shell (SSH) access to your machine can be enabled by setting:
+  </para>
+  <programlisting language="bash">
+services.openssh.enable = true;
+</programlisting>
+  <para>
+    By default, root logins using a password are disallowed. They can be
+    disabled entirely by setting
+    <link xlink:href="options.html#opt-services.openssh.permitRootLogin"><literal>services.openssh.permitRootLogin</literal></link>
+    to <literal>&quot;no&quot;</literal>.
+  </para>
+  <para>
+    You can declaratively specify authorised RSA/DSA public keys for a
+    user as follows:
+  </para>
+  <programlisting language="bash">
+users.users.alice.openssh.authorizedKeys.keys =
+  [ &quot;ssh-dss AAAAB3NzaC1kc3MAAACBAPIkGWVEt4...&quot; ];
+</programlisting>
+</section>