From 7c8994e40e411d5b0a151b3891a57a73006d0e8d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= <joerg@thalheim.io>
Date: Wed, 2 Dec 2020 09:49:43 +0100
Subject: [PATCH] doc/firefox: initial documentation

---
 doc/builders/packages/firefox.section.md | 40 ++++++++++++++++++++++++
 doc/builders/packages/index.xml          |  1 +
 2 files changed, 41 insertions(+)
 create mode 100644 doc/builders/packages/firefox.section.md

diff --git a/doc/builders/packages/firefox.section.md b/doc/builders/packages/firefox.section.md
new file mode 100644
index 000000000000..2f89da2d4595
--- /dev/null
+++ b/doc/builders/packages/firefox.section.md
@@ -0,0 +1,40 @@
+# Firefox
+
+## Build wrapped Firefox with extensions and policies
+
+The `wrapFirefox` function allows to pass policies, preferences and extension that are available to firefox. With the help of `fetchFirefoxAddon` this allows build a firefox version that already comes with addons pre-installed:
+
+```nix
+{
+  myFirefox = wrapFirefox firefox-unwrapped {
+    extraExtensions = [
+      (fetchFirefoxAddon {
+        name = "ublock";
+        url = "https://addons.mozilla.org/firefox/downloads/file/3679754/ublock_origin-1.31.0-an+fx.xpi";
+        sha256 = "1h768ljlh3pi23l27qp961v1hd0nbj2vasgy11bmcrlqp40zgvnr";
+      })
+    ];
+
+    extraPolicies = {
+      CaptivePortal = false;
+      DisableFirefoxStudies = true;
+      DisablePocket = true;
+      DisableTelemetry = true;
+      DisableFirefoxAccounts = true;
+      FirefoxHome = {
+        Pocket = false;
+        Snippets = false;
+      };
+       UserMessaging = {
+         ExtensionRecommendations = false;
+         SkipOnboarding = true;
+       };
+    };
+
+    extraPrefs = ''
+      // Show more ssl cert infos
+      lockPref("security.identityblock.show_extended_validation", true);
+    '';
+  };
+}
+```
diff --git a/doc/builders/packages/index.xml b/doc/builders/packages/index.xml
index 3c9a56a81b7f..6d7537bb36de 100644
--- a/doc/builders/packages/index.xml
+++ b/doc/builders/packages/index.xml
@@ -10,6 +10,7 @@
  <xi:include href="eclipse.xml" />
  <xi:include href="elm.xml" />
  <xi:include href="emacs.xml" />
+ <xi:include href="firefox.section.xml" />
  <xi:include href="ibus.xml" />
  <xi:include href="kakoune.section.xml" />
  <xi:include href="linux.xml" />