docs: adopt shared Umbraco docs tooling

Author: thebuilder

.gitignore

@@ -27,3 +27,4 @@ samples/TheBuilder.WebAnalytics.Example/appsettings-schema.json
 .idea/
 .vs/
 .blume-verify/
+apps/docs/public/social/

apps/docs/blume.config.ts

@@ -1,11 +1,11 @@
 import { defineConfig } from "blume";
 
 import { githubReleaseChangelogSource } from "./sources/github-releases";
+import { webAnalyticsPackage } from "./umbraco-package";
 
 export default defineConfig({
-  title: "Web Analytics",
-  description:
-    "Bring Vercel Web Analytics and Plausible reports into the Umbraco backoffice.",
+  title: webAnalyticsPackage.name,
+  description: webAnalyticsPackage.summary,
   logo: {
     image: "/logo.png",
     text: "Web Analytics",

apps/docs/package.json

@@ -9,13 +9,14 @@
     "build": "pnpm run generate:og && blume build",
     "check": "blume check",
     "generate:brand": "node scripts/generate-brand.mjs",
-    "generate:og": "node scripts/generate-og-image.mjs",
-    "validate": "blume validate"
+    "validate": "blume validate",
+    "generate:og": "umbraco-docs-og",
+    "check:og": "umbraco-docs-og --check"
   },
   "devDependencies": {
+    "@thebuilder/umbraco-docs": "^1.0.0",
     "@types/node": "24.10.1",
-    "blume": "1.2.1",
-    "gray-matter": "4.0.3",
+    "blume": "1.4.3",
     "sharp": "0.34.5"
   }
 }

apps/docs/pages/_home/home.css

@@ -13,7 +13,6 @@
 .home {
   /* Echoes the logo's blue -> purple -> pink for subtle gradient accents. */
   --brand-gradient: linear-gradient(105deg, #60a5fa, #a78bfa 52%, #f472b6);
-  padding-bottom: 5rem;
   overflow: clip;
 }
 
@@ -249,6 +248,10 @@
 .home-block__head a { color: var(--blume-accent); text-decoration: none; }
 .home-block__head a:hover { text-decoration: underline; }
 
+/* Avoid stacking the shared section's bottom margin with this custom page's
+   footer spacing. The component's card and heading styles remain package-owned. */
+.home .udocs-ecosystem { margin-block: clamp(4rem, 9vw, 7rem) 0; }
+
 .trust {
   margin-top: clamp(3rem, 7vw, 5rem);
   text-align: center;

apps/docs/pages/index.astro

@@ -5,12 +5,20 @@
 // and renders correctly; skip type-checking to avoid the false positives.
 import PageLayout from "blume/components/layout/PageLayout.astro";
 import data from "blume:data";
+import {
+  EcosystemSection,
+  LandingRoot,
+} from "@thebuilder/umbraco-docs/astro";
 
 import "./_home/home.css";
 
 import overviewShot from "../docs/screenshots/analytics-overview.png";
 import documentShot from "../docs/screenshots/document-analytics-workspace.png";
 import settingsShot from "../docs/screenshots/settings.png";
+import {
+  ecosystemPackages,
+  webAnalyticsPackage,
+} from "../umbraco-package";
 
 const { config } = data;
 
@@ -96,15 +104,15 @@ const steps = [
   searchEnabled={config.search.enabled}
   siteUrl={config.site}
   ogEnabled={config.og.enabled}
-  ogImage="/opengraph-image.png"
+  ogImage="/social/index.png"
   page={{
     title: "Web Analytics for Umbraco",
     description:
       "Bring Vercel Web Analytics and Plausible reports into the Umbraco backoffice: site-wide and page-level traffic where editors already work.",
     route: "/",
   }}
 >
-  <div class="home" data-home>
+  <LandingRoot class="home">
     {/* Hero */}
     <section class="hero">
       <div class="hero__glow" aria-hidden="true"></div>
@@ -317,7 +325,12 @@ const steps = [
         </div>
       </div>
     </section>
-  </div>
+
+    <EcosystemSection
+      packages={ecosystemPackages}
+      currentPackageId={webAnalyticsPackage.id}
+    />
+  </LandingRoot>
 
   {/* Footer */}
   <footer class="home-footer" slot="footer">
@@ -340,7 +353,7 @@ const steps = [
 </PageLayout>
 
 <script>
-  const root = document.querySelector<HTMLElement>("[data-home]");
+  const root = document.querySelector<HTMLElement>("[data-udocs-root]");
   const prefersReduced = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
 
   if (root && !prefersReduced && "IntersectionObserver" in window) {

apps/docs/public/ecosystem/blur-placeholder.svg

@@ -0,0 +1,14 @@
+import { defineOgConfig } from "@thebuilder/umbraco-docs/og";
+import { fileURLToPath } from "node:url";
+
+export default defineOgConfig({
+  contentDir: fileURLToPath(new URL("./docs", import.meta.url)),
+  publicDir: fileURLToPath(new URL("./public", import.meta.url)),
+  prefix: "/social",
+  brand: "TheBuilder · Web Analytics",
+  accent: "#3544b1",
+  root: {
+    title: "Web Analytics",
+    description: "Bring Vercel Web Analytics and Plausible reports into the Umbraco backoffice.",
+  },
+});

apps/docs/scripts/generate-og-image.mjs

@@ -0,0 +1,35 @@
+import { defineUmbracoPackage } from "@thebuilder/umbraco-docs";
+
+export const webAnalyticsPackage = defineUmbracoPackage({
+  id: "thebuilder.webanalytics",
+  name: "Web Analytics",
+  summary: "Connect analytics providers and bring site-wide and page-level insights into the Umbraco backoffice.",
+  links: {
+    docs: "https://umbraco-web-analytics.vercel.app/",
+    nuget: "https://www.nuget.org/packages/TheBuilder.WebAnalytics",
+    marketplace: "https://marketplace.umbraco.com/package/thebuilder.webanalytics",
+    github: "https://github.com/thebuilder/web-analytics",
+  },
+  logo: "/logo.png",
+  compatibility: { umbraco: ">=17.1 <19", dotnet: ">=10" },
+  status: "stable",
+  categories: ["Analytics", "Editor Tools"],
+});
+
+export const blurPlaceholderPackage = defineUmbracoPackage({
+  id: "thebuilder.blurplaceholder",
+  name: "Blur Placeholder",
+  summary: "Generate WebP, BlurHash, or ThumbHash placeholders for Umbraco Image media and deliver one frontend-ready string.",
+  links: {
+    docs: "https://blur-placeholder.vercel.app/",
+    nuget: "https://www.nuget.org/packages/TheBuilder.BlurPlaceholder",
+    marketplace: "https://marketplace.umbraco.com/package/thebuilder.blurplaceholder",
+    github: "https://github.com/thebuilder/blur-placeholder",
+  },
+  logo: "/ecosystem/blur-placeholder.svg",
+  compatibility: { umbraco: ">=17.1 <19", dotnet: ">=10" },
+  status: "stable",
+  categories: ["Developer Tools", "Media"],
+});
+
+export const ecosystemPackages = [webAnalyticsPackage, blurPlaceholderPackage];