OctopusDeploy · KMajkrzakOctopus · May 26, 2026 · May 25, 2026 · May 26, 2026
diff --git a/.env.production b/.env.production
@@ -0,0 +1,5 @@
+# DO NOT add secrets here - this file is checked into git.
+# Production defaults for the shared navbar/footer integration.
+FOOTER_FRAGMENT_URL=https://octopus.com/fragments/footer
+SHARED_ASSETS_BASE_URL=https://octopus.com/octopus-public/assets
+SHARED_ASSETS_ORIGIN=https://octopus.com
diff --git a/.env.staging b/.env.staging
@@ -0,0 +1,8 @@
+# DO NOT add secrets here - this file is checked into git.
+#
+# Defaults match production. Edit temporarily to point at staging URLs
+# (e.g. https://a.dev.octopus.com/...) when you want to preview upcoming
+# shared navbar/footer changes locally before they ship to prod.
+FOOTER_FRAGMENT_URL=https://octopus.com/fragments/footer
+SHARED_ASSETS_BASE_URL=https://octopus.com/octopus-public/assets
+SHARED_ASSETS_ORIGIN=https://octopus.com
diff --git a/.gitignore b/.gitignore
@@ -18,7 +18,6 @@ pnpm-debug.log*
 
 # environment variables
 .env
-.env.production
 
 # macOS-specific files
 .DS_Store

diff --git a/README.md b/README.md
@@ -227,6 +227,48 @@ Within an MDX file, this looks like a code block and will error. Escape the stat
 
 MDX files don't allow short-form links, instead of using `<https://example.com>` use `[https://example.com](https://example.com)`, or even better - put in useful link text, like `[example website](https://example.com)`.
 
+## Shared footer
+
+The footer is not maintained in this repo. It is fetched at build time from the
+main site:
+
+- `https://octopus.com/fragments/footer`
+
+CSS, JS, and fonts load at page-view time from
+`https://octopus.com/octopus-public/assets/...` via `<link>` and
+`<script defer>` tags in every page. The fetch URL lives in `.env.staging`
+(used by `pnpm dev`) and `.env.production` (used by `pnpm build`).
+
+`SharedFooter.astro` wraps the injected HTML in a `<div>` with
+`data-shared-source`, `data-shared-fragment`, and `data-shared-note`
+attributes. Inspect those in DevTools to confirm whether a given build's footer
+came from the live fetch (`"live"`) or the local fallback (`"fallback"`).
+
+**About the committed `.env.*` files:** `.env.staging` and `.env.production`
+are checked into git on purpose. They contain **only** the three public asset
+URLs the integration needs - the same URLs that appear in every rendered page's
+`<head>`. They are not secrets and there is nothing in them you couldn't read
+from a visitor's browser DevTools. Do not add API keys, tokens, or anything
+sensitive to these files. Use `.env` (gitignored) for any local-only overrides.
+
+### Snapshot fallback
+
+If the live fetch fails during a build (origin unreachable, timeout, non-200
+response), the build silently uses the on-disk snapshot at
+`src/fallback/footer.html` instead of failing. This file is committed and
+refreshed manually with:
+
+```bash
+pnpm snapshot
+git diff src/fallback/
+git add src/fallback/
+git commit -m "Refresh shared footer snapshot"
+```
+
+The build never writes to `src/fallback/` automatically. Refresh when the live
+footer has changed meaningfully and you want the safety net to stay roughly
+current, or when `data-shared-source="fallback"` shows up on a deployed page.
+
 ## Docs page layout guidelines
 
 ### Title icons

diff --git a/cspell.json b/cspell.json
@@ -62,6 +62,7 @@
     ".vscode/**",
     ".github/**",
     "src/pages/report/**",
+    "src/fallback/**",
     "public/docs/js/**",
     "node_modules/**",
     "public/docs/css/fa/**"

@@ -281,6 +281,7 @@ mattc
 maxage
 mdast
 Metabase
+microsite
 milli
 minidump
 minifier
@@ -328,6 +329,7 @@ nodir
 nologo
 nologs
 noninteractive
+nonroot-v2
 noopener
 NOPASSWD
 noreferrer
@@ -624,4 +626,3 @@ xxlarge
 youtu
 Zstandard
 Zuora
-nonroot-v2
diff --git a/package.json b/package.json
@@ -12,9 +12,10 @@
         "dev": "npm-run-all --parallel dev:img dev:dictionary dev:astro dev:watch",
         "dev:dictionary": "node ./dictionary-sorter.mjs",
         "dev:img": "node ./src/themes/octopus/utilities/img.mjs",
-        "dev:astro": "astro dev",
+        "dev:astro": "astro dev --mode staging",
         "dev:watch": "onchange 'src/**/*.{js,mjs,ts,astro,css}' 'public/docs/js/**/*.js' 'public/docs/css/**/*.css' -- prettier --write --plugin=prettier-plugin-astro {{changed}}",
         "astro": "astro",
+        "snapshot": "node --env-file=.env.production ./scripts/snapshot-shared.mjs",
         "build": "astro build",
         "crawl": "linkinator ./dist --skip \"^(?!http://localhost)\" --recurse  --verbosity error",
         "format": "prettier --write --plugin=prettier-plugin-astro 'src/**/*.{js,mjs,ts,astro,css}' 'public/docs/js/**/*.js' 'public/docs/css/**/*.css'",

diff --git a/public/docs/css/footer-bundle.css b/public/docs/css/footer-bundle.css
diff --git a/public/docs/css/footer/container.css b/public/docs/css/footer/container.css