diff --git a/doc/builders/packages/index.xml b/doc/builders/packages/index.xml
index ba59ceb016b..58417a0fc77 100644
--- a/doc/builders/packages/index.xml
+++ b/doc/builders/packages/index.xml
@@ -16,7 +16,7 @@
  <xi:include href="locales.xml" />
  <xi:include href="nginx.xml" />
  <xi:include href="opengl.section.xml" />
- <xi:include href="shell-helpers.xml" />
+ <xi:include href="shell-helpers.section.xml" />
  <xi:include href="steam.xml" />
  <xi:include href="cataclysm-dda.section.xml" />
  <xi:include href="urxvt.xml" />
diff --git a/doc/builders/packages/shell-helpers.section.md b/doc/builders/packages/shell-helpers.section.md
new file mode 100644
index 00000000000..57b8619c500
--- /dev/null
+++ b/doc/builders/packages/shell-helpers.section.md
@@ -0,0 +1,12 @@
+# Interactive shell helpers {#sec-shell-helpers}
+
+Some packages provide the shell integration to be more useful. But unlike other systems, nix doesn't have a standard `share` directory location. This is why a bunch `PACKAGE-share` scripts are shipped that print the location of the corresponding shared folder. Current list of such packages is as following:
+
+- `fzf` : `fzf-share`
+
+E.g. `fzf` can then used in the `.bashrc` like this:
+
+```bash
+source "$(fzf-share)/completion.bash"
+source "$(fzf-share)/key-bindings.bash"
+```
diff --git a/doc/builders/packages/shell-helpers.xml b/doc/builders/packages/shell-helpers.xml
deleted file mode 100644
index a4ac9022c4c..00000000000
--- a/doc/builders/packages/shell-helpers.xml
+++ /dev/null
@@ -1,21 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="sec-shell-helpers">
- <title>Interactive shell helpers</title>
-
- <para>
-  Some packages provide the shell integration to be more useful. But unlike other systems, nix doesn't have a standard share directory location. This is why a bunch <command>PACKAGE-share</command> scripts are shipped that print the location of the corresponding shared folder. Current list of such packages is as following:
-  <itemizedlist>
-   <listitem>
-    <para>
-     <literal>fzf</literal>: <command>fzf-share</command>
-    </para>
-   </listitem>
-  </itemizedlist>
-  E.g. <literal>fzf</literal> can then used in the .bashrc like this:
-<screen>
-  source "$(fzf-share)/completion.bash"
-  source "$(fzf-share)/key-bindings.bash"
-</screen>
- </para>
-</section>