From 28ee53c87e919559999ddd67b92c5e14c8bb732d Mon Sep 17 00:00:00 2001
From: Brian Smith <brian@smith.berlin>
Date: Fri, 6 Nov 2026 10:41:45 +0100
Subject: [PATCH] feat: add homepage, firefoxhome examples

---
 .../docs/reference/policies/FirefoxHome.mdx   | 41 +++++++++++++++++--
 .../docs/reference/policies/Homepage.mdx      | 37 ++++++++++++++++-
 2 files changed, 74 insertions(+), 4 deletions(-)

diff --git a/src/content/docs/reference/policies/FirefoxHome.mdx b/src/content/docs/reference/policies/FirefoxHome.mdx
index d5a2598..f768d57 100644
--- a/src/content/docs/reference/policies/FirefoxHome.mdx
+++ b/src/content/docs/reference/policies/FirefoxHome.mdx
@@ -14,15 +14,50 @@ Each key named after a Firefox Home section is a Boolean that shows or hides tha
 
 - `Enabled`: A Boolean that shows or hides widgets as a whole.
   It follows `Locked` like the other keys.
-- `Blocked`: A list of widget ids to turn off individually.
+- `Blocked`: A list of widget IDs to turn off individually.
   Blocked widgets are always locked, whether or not `Locked` is set.
-  The ids are `clocks`, `crossword`, `focusTimer`, `lists`, `pictureOfTheDay`, `privacy`, `recentSearches`, `sportsWidget`, `stocks`, and `weather`.
-  An invalid widget id is ignored.
+  The IDs are `clocks`, `crossword`, `focusTimer`, `lists`, `pictureOfTheDay`, `privacy`, `recentSearches`, `sportsWidget`, `stocks`, and `weather`.
+  An invalid widget ID is ignored.
 
 ## Examples
 
 <PolicyExample policy="FirefoxHome" />
 
+### Removing sponsored content
+
+This example turns off sponsored shortcuts and sponsored stories, and sets `Locked` to `true` so users can't turn them back on.
+Setting and locking both keys also locks the "Support Firefox" toggle so that users don't see a control that has no effect.
+Sponsored content is disabled in Firefox Enterprise, so this is only relevant for Firefox and Firefox ESR:
+
+```json
+{
+  "policies": {
+    "FirefoxHome": {
+      "SponsoredTopSites": false,
+      "SponsoredStories": false,
+      "Locked": true
+    }
+  }
+}
+```
+
+### Turning off specific widgets
+
+This example turns off the sports, stocks and crossword widgets and leaves the other widgets for users to configure.
+Widgets listed in `Blocked` are always disabled and locked, so you don't need `Locked` here:
+
+```json
+{
+  "policies": {
+    "FirefoxHome": {
+      "Widgets": {
+        "Blocked": ["sportsWidget", "stocks", "crossword"]
+      }
+    }
+  }
+}
+```
+
 ## Windows (GPO)
 
 ```
diff --git a/src/content/docs/reference/policies/Homepage.mdx b/src/content/docs/reference/policies/Homepage.mdx
index c608f2c..53c920a 100644
--- a/src/content/docs/reference/policies/Homepage.mdx
+++ b/src/content/docs/reference/policies/Homepage.mdx
@@ -25,12 +25,47 @@ The following members are configurable:
 - `NewTabOnRestore` controls the "Also open new tab" option under Settings, in the Startup section. When it is enabled, Firefox opens an extra tab whenever it restores your previous windows and tabs at startup. Firefox may turn this option on for your users on its own, so set `NewTabOnRestore` to `false` to keep it off, or `true` to always enable it.
 
 > [!NOTE]
-> Firefox may turn on "Also open new tab" for your users on its own. If you don't want your users to suddenly get an extra tab when their previous windows and tabs are restored, set `NewTabOnRestore` to `false`.
+> Firefox may turn on "Also open new tab" for your users.
+> If you don't want your users to get an extra tab when their previous windows and tabs are restored, set `NewTabOnRestore` to `false`.
 
 ## Examples
 
 <PolicyExample policy="Homepage" />
 
+### Setting a company SSO portal as the default homepage
+
+This example sets your company's single sign-on (SSO) portal as the default homepage and startup page, so that users can sign in and open your company's apps.
+Users can still change both settings, and existing user choices take precedence over these defaults.
+Setting `URL` also adds the Home button to the default toolbar:
+
+```json
+{
+  "policies": {
+    "Homepage": {
+      "URL": "https://sso.example.com/",
+      "StartPage": "homepage"
+    }
+  }
+}
+```
+
+### Enforcing a homepage on every start
+
+This example opens your company's SSO portal whenever Firefox starts and stops users from changing the homepage address.
+`Locked` locks only the homepage address, and `StartPage: "homepage-locked"` locks how Firefox starts, so both are necessary:
+
+```json
+{
+  "policies": {
+    "Homepage": {
+      "URL": "https://sso.example.com/",
+      "Locked": true,
+      "StartPage": "homepage-locked"
+    }
+  }
+}
+```
+
 ## Windows (GPO)
 
 ```