4 files changed, 24 insertions, 24 deletions
diff --git a/doc/builders/packages/firefox.section.md b/doc/builders/packages/firefox.section.md
index 2f89da2d4595..28fa3f0dbd7c 100644
--- a/doc/builders/packages/firefox.section.md
+++ b/doc/builders/packages/firefox.section.md
@@ -1,4 +1,4 @@
-# Firefox
+# Firefox {#sec-firefox}
 
 ## Build wrapped Firefox with extensions and policies
 
@@ -7,7 +7,7 @@ The `wrapFirefox` function allows to pass policies, preferences and extension th
 ```nix
 {
   myFirefox = wrapFirefox firefox-unwrapped {
-    extraExtensions = [
+    nixExtensions = [
       (fetchFirefoxAddon {
         name = "ublock";
         url = "https://addons.mozilla.org/firefox/downloads/file/3679754/ublock_origin-1.31.0-an+fx.xpi";
@@ -38,3 +38,12 @@ The `wrapFirefox` function allows to pass policies, preferences and extension th
   };
 }
 ```
+
+If `nixExtensions != null` then all manually installed addons will be uninstalled from your browser profile.
+To view available enterprise policies visit [enterprise policies](https://github.com/mozilla/policy-templates#enterprisepoliciesenabled)
+or type into the Firefox url bar: `about:policies#documentation`.
+Nix installed addons do not have a valid signature, which is why signature verification is disabled. This does not compromise security because downloaded addons are checksumed and manual addons can't be installed.
+
+## Troubleshooting {#sec-firefox-troubleshooting}
+If addons do not appear installed although they have been defined in your nix configuration file reset the local addon state of your Firefox profile by clicking `help -> restart with addons disabled -> restart -> refresh firefox`. This can happen if you switch from manual addon mode to nix addon mode and then back to manual mode and then again to nix addon mode.
+
diff --git a/doc/builders/packages/index.xml b/doc/builders/packages/index.xml
index 38d72a4748f6..c7a4aa9f47dc 100644
--- a/doc/builders/packages/index.xml
+++ b/doc/builders/packages/index.xml
@@ -17,7 +17,7 @@
  <xi:include href="locales.xml" />
  <xi:include href="nginx.section.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.section.xml" />
diff --git a/doc/builders/packages/shell-helpers.section.md b/doc/builders/packages/shell-helpers.section.md
new file mode 100644
index 000000000000..57b8619c5007
--- /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 a4ac9022c4ce..000000000000
--- 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>