diff --git a/doc/builders/packages/index.xml b/doc/builders/packages/index.xml
index c7a4aa9f47d..e1ddfd276e2 100644
--- a/doc/builders/packages/index.xml
+++ b/doc/builders/packages/index.xml
@@ -14,7 +14,7 @@
  <xi:include href="ibus.xml" />
  <xi:include href="kakoune.section.xml" />
  <xi:include href="linux.section.xml" />
- <xi:include href="locales.xml" />
+ <xi:include href="locales.section.xml" />
  <xi:include href="nginx.section.xml" />
  <xi:include href="opengl.section.xml" />
  <xi:include href="shell-helpers.section.xml" />
diff --git a/doc/builders/packages/locales.section.md b/doc/builders/packages/locales.section.md
new file mode 100644
index 00000000000..e5a03700481
--- /dev/null
+++ b/doc/builders/packages/locales.section.md
@@ -0,0 +1,5 @@
+# Locales {#locales}
+
+To allow simultaneous use of packages linked against different versions of `glibc` with different locale archive formats Nixpkgs patches `glibc` to rely on `LOCALE_ARCHIVE` environment variable.
+
+On non-NixOS distributions this variable is obviously not set. This can cause regressions in language support or even crashes in some Nixpkgs-provided programs. The simplest way to mitigate this problem is exporting the `LOCALE_ARCHIVE` variable pointing to `${glibcLocales}/lib/locale/locale-archive`. The drawback (and the reason this is not the default) is the relatively large (a hundred MiB) size of the full set of locales. It is possible to build a custom set of locales by overriding parameters `allLocales` and `locales` of the package.
diff --git a/doc/builders/packages/locales.xml b/doc/builders/packages/locales.xml
deleted file mode 100644
index 44fdef034e7..00000000000
--- a/doc/builders/packages/locales.xml
+++ /dev/null
@@ -1,13 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="locales">
- <title>Locales</title>
-
- <para>
-  To allow simultaneous use of packages linked against different versions of <literal>glibc</literal> with different locale archive formats Nixpkgs patches <literal>glibc</literal> to rely on <literal>LOCALE_ARCHIVE</literal> environment variable.
- </para>
-
- <para>
-  On non-NixOS distributions this variable is obviously not set. This can cause regressions in language support or even crashes in some Nixpkgs-provided programs. The simplest way to mitigate this problem is exporting the <literal>LOCALE_ARCHIVE</literal> variable pointing to <literal>${glibcLocales}/lib/locale/locale-archive</literal>. The drawback (and the reason this is not the default) is the relatively large (a hundred MiB) size of the full set of locales. It is possible to build a custom set of locales by overriding parameters <literal>allLocales</literal> and <literal>locales</literal> of the package.
- </para>
-</section>