diff --git a/doc/functions.xml b/doc/functions.xml
index 5a9240ec800e..e8ab8d97b913 100644
--- a/doc/functions.xml
+++ b/doc/functions.xml
@@ -10,5 +10,5 @@
-
+
diff --git a/doc/functions/nix-gitignore.section.md b/doc/functions/nix-gitignore.section.md
new file mode 100644
index 000000000000..2fb833b23000
--- /dev/null
+++ b/doc/functions/nix-gitignore.section.md
@@ -0,0 +1,49 @@
+# pkgs.nix-gitignore {#sec-pkgs-nix-gitignore}
+
+`pkgs.nix-gitignore` is a function that acts similarly to `builtins.filterSource` but also allows filtering with the help of the gitignore format.
+
+## Usage {#sec-pkgs-nix-gitignore-usage}
+
+`pkgs.nix-gitignore` exports a number of functions, but you\'ll most likely need either `gitignoreSource` or `gitignoreSourcePure`. As their first argument, they both accept either 1. a file with gitignore lines or 2. a string with gitignore lines, or 3. a list of either of the two. They will be concatenated into a single big string.
+
+```nix
+{ pkgs ? import {} }:
+
+ nix-gitignore.gitignoreSource [] ./source
+ # Simplest version
+
+ nix-gitignore.gitignoreSource "supplemental-ignores\n" ./source
+ # This one reads the ./source/.gitignore and concats the auxiliary ignores
+
+ nix-gitignore.gitignoreSourcePure "ignore-this\nignore-that\n" ./source
+ # Use this string as gitignore, don't read ./source/.gitignore.
+
+ nix-gitignore.gitignoreSourcePure ["ignore-this\nignore-that\n", ~/.gitignore] ./source
+ # It also accepts a list (of strings and paths) that will be concatenated
+ # once the paths are turned to strings via readFile.
+```
+
+These functions are derived from the `Filter` functions by setting the first filter argument to `(_: _: true)`:
+
+```nix
+gitignoreSourcePure = gitignoreFilterSourcePure (_: _: true);
+gitignoreSource = gitignoreFilterSource (_: _: true);
+```
+
+Those filter functions accept the same arguments the `builtins.filterSource` function would pass to its filters, thus `fn: gitignoreFilterSourcePure fn ""` should be extensionally equivalent to `filterSource`. The file is blacklisted if it\'s blacklisted by either your filter or the gitignoreFilter.
+
+If you want to make your own filter from scratch, you may use
+
+```nix
+gitignoreFilter = ign: root: filterPattern (gitignoreToPatterns ign) root;
+```
+
+## gitignore files in subdirectories {#sec-pkgs-nix-gitignore-usage-recursive}
+
+If you wish to use a filter that would search for .gitignore files in subdirectories, just like git does by default, use this function:
+
+```nix
+gitignoreFilterRecursiveSource = filter: patterns: root:
+# OR
+gitignoreRecursiveSource = gitignoreFilterSourcePure (_: _: true);
+```
diff --git a/doc/functions/nix-gitignore.xml b/doc/functions/nix-gitignore.xml
deleted file mode 100644
index 37a82b196ccf..000000000000
--- a/doc/functions/nix-gitignore.xml
+++ /dev/null
@@ -1,70 +0,0 @@
-
- pkgs.nix-gitignore
-
-
- pkgs.nix-gitignore is a function that acts similarly to builtins.filterSource but also allows filtering with the help of the gitignore format.
-
-
-
- Usage
-
-
- pkgs.nix-gitignore exports a number of functions, but you'll most likely need either gitignoreSource or gitignoreSourcePure. As their first argument, they both accept either 1. a file with gitignore lines or 2. a string with gitignore lines, or 3. a list of either of the two. They will be concatenated into a single big string.
-
-
- {} }:
-
- nix-gitignore.gitignoreSource [] ./source
- # Simplest version
-
- nix-gitignore.gitignoreSource "supplemental-ignores\n" ./source
- # This one reads the ./source/.gitignore and concats the auxiliary ignores
-
- nix-gitignore.gitignoreSourcePure "ignore-this\nignore-that\n" ./source
- # Use this string as gitignore, don't read ./source/.gitignore.
-
- nix-gitignore.gitignoreSourcePure ["ignore-this\nignore-that\n", ~/.gitignore] ./source
- # It also accepts a list (of strings and paths) that will be concatenated
- # once the paths are turned to strings via readFile.
- ]]>
-
-
- These functions are derived from the Filter functions by setting the first filter argument to (_: _: true):
-
-
-
-
-
- Those filter functions accept the same arguments the builtins.filterSource function would pass to its filters, thus fn: gitignoreFilterSourcePure fn "" should be extensionally equivalent to filterSource. The file is blacklisted iff it's blacklisted by either your filter or the gitignoreFilter.
-
-
-
- If you want to make your own filter from scratch, you may use
-
-
-
-
-
-
- gitignore files in subdirectories
-
-
- If you wish to use a filter that would search for .gitignore files in subdirectories, just like git does by default, use this function:
-
-
-
-
-