diff --git a/doc/functions.xml b/doc/functions.xml
index ee73c46ad4d3..88011061ae6e 100644
--- a/doc/functions.xml
+++ b/doc/functions.xml
@@ -12,6 +12,6 @@
  <xi:include href="functions/generators.xml" />
  <xi:include href="functions/debug.xml" />
  <xi:include href="functions/fhs-environments.xml" />
- <xi:include href="functions/shell.section.xml" />
+ <xi:include href="functions/shell.xml" />
  <xi:include href="functions/dockertools.xml" />
 </chapter>
diff --git a/doc/functions/shell.section.md b/doc/functions/shell.section.md
deleted file mode 100644
index cb8832a814fc..000000000000
--- a/doc/functions/shell.section.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: pkgs.mkShell
-author: zimbatm
-date: 2017-10-30
----
-
-# mkShell
-
-pkgs.mkShell is a special kind of derivation that is only useful when using
-it combined with nix-shell. It will in fact fail to instantiate when invoked
-with nix-build.
-
-## Usage
-
-```nix
-{ pkgs ? import <nixpkgs> {} }:
-pkgs.mkShell {
-  # this will make all the build inputs from hello and gnutar available to the shell environment
-  inputsFrom = with pkgs; [ hello gnutar ];
-  buildInputs = [ pkgs.gnumake ];
-}
-```
diff --git a/doc/functions/shell.xml b/doc/functions/shell.xml
new file mode 100644
index 000000000000..a8d2a30cb508
--- /dev/null
+++ b/doc/functions/shell.xml
@@ -0,0 +1,27 @@
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         xml:id="sec-pkgs-mkShell">
+  <title>pkgs.mkShell</title>
+
+  <para>
+    <function>pkgs.mkShell</function> is a special kind of derivation
+    that is only useful when using it combined with
+    <command>nix-shell</command>. It will in fact fail to instantiate
+    when invoked with <command>nix-build</command>.
+  </para>
+
+  <section xml:id="sec-pkgs-mkShell-usage">
+    <title>Usage</title>
+
+    <programlisting><![CDATA[
+{ pkgs ? import <nixpkgs> {} }:
+pkgs.mkShell {
+  # this will make all the build inputs from hello and gnutar
+  # available to the shell environment
+  inputsFrom = with pkgs; [ hello gnutar ];
+  buildInputs = [ pkgs.gnumake ];
+}
+]]></programlisting>
+  </section>
+</section>