chore(docs): upgrade to Blume 2 and load related packages from the hub

apps/docs/blume.config.ts

@@ -1,8 +1,12 @@
 import { defineConfig } from "blume";
+import { vercel } from "blume/analytics";
+import { custom, filesystem } from "blume/sources";
 
 import { githubReleaseChangelogSource } from "./sources/github-releases";
 import { webAnalyticsPackage } from "./umbraco-package";
 
+const site = "https://web-analytics.thebuilder.dk";
+
 export default defineConfig({
   title: webAnalyticsPackage.name,
   description: webAnalyticsPackage.summary,
@@ -17,14 +21,14 @@ export default defineConfig({
   },
   content: {
     sources: [
-      { type: "filesystem", root: "docs" },
-      {
-        type: "custom",
-        source: githubReleaseChangelogSource({
+      filesystem({ root: "docs" }),
+      custom(
+        githubReleaseChangelogSource({
           owner: "thebuilder",
           repo: "web-analytics",
+          site,
         }),
-      },
+      ),
     ],
   },
   navigation: {
@@ -36,19 +40,14 @@ export default defineConfig({
     ],
   },
   redirects: [{ from: "/getting-started", to: "/quickstart", status: 301 }],
-  deployment: {
-    output: "static",
-    site: "https://web-analytics.thebuilder.dk",
-  },
+  deployment: { site },
   seo: {
     // Package-owned cards are generated into public/og before Blume builds.
     // Disable Blume's generated /og routes so it cannot overwrite them.
     og: { enabled: false },
   },
-  analytics: {
-    vercel: true,
-  },
-  ai: {
+  analytics: [vercel()],
+  agents: {
     llmsTxt: true,
   },
 });

apps/docs/package.json

@@ -14,9 +14,9 @@
     "check:og": "umbraco-docs-og --check"
   },
   "devDependencies": {
-    "@thebuilder/umbraco-docs": "^1.0.4",
+    "@thebuilder/umbraco-docs": "^1.2.0",
     "@types/node": "24.10.1",
-    "blume": "1.6.4",
+    "blume": "2.2.3",
     "sharp": "0.35.4"
   }
 }

apps/docs/pages/index.astro

@@ -5,6 +5,7 @@
 // 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 { loadUmbracoPackages } from "@thebuilder/umbraco-docs";
 import {
   EcosystemSection,
   LandingRoot,
@@ -15,10 +16,10 @@ 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";
+import { webAnalyticsPackage } from "../umbraco-package";
+
+// The other packages come from the hub at umbraco.thebuilder.dk, so this list never needs editing here.
+const ecosystemPackages = await loadUmbracoPackages();
 
 const { config } = data;
 

apps/docs/sources/github-releases.ts

@@ -1,11 +1,17 @@
 import { resolve } from "node:path";
 
-import type { ContentSource, SourceEntry } from "blume/core/sources/types.ts";
+import type {
+  ContentSource,
+  SourceContext,
+  SourceEntry,
+} from "blume/core/sources/types.ts";
 import { githubReleasesSource } from "blume/sources/github-releases.ts";
 
 type ReleaseSourceOptions = {
   owner: string;
   repo: string;
+  /** The site's own URL, so links back to it become root-relative. */
+  site?: string;
 };
 
 const excludeSearchFromRaw = (raw: string): string =>
@@ -20,26 +26,12 @@ const excludeFromSearch = (entry: SourceEntry): SourceEntry => ({
   raw: entry.raw ? excludeSearchFromRaw(entry.raw) : undefined,
 });
 
-export const githubReleaseChangelogSource = ({
-  owner,
-  repo,
-}: ReleaseSourceOptions): ContentSource => {
-  const isDev = process.argv.includes("dev");
-  const source = githubReleasesSource(
-    {
-      name: "changelog",
-      owner,
-      prefix: "changelog",
-      repo,
-    },
-    {
-      cacheDir: resolve(".blume/cache/changelog"),
-      mode: isDev ? "dev" : "build",
-      projectRoot: process.cwd(),
-      refresh: !isDev,
-    },
-  );
-  const read = source.read;
+// Wraps Blume's GitHub Releases engine so every release page stays out of
+// search. Blume rebuilds a custom() source on each scan's context through
+// withContext, so the wrapper re-applies itself there, otherwise the rebuilt
+// engine would drop the search exclusion.
+const withSearchExcluded = (source: ContentSource): ContentSource => {
+  const { read, withContext } = source;
 
   return {
     ...source,
@@ -54,5 +46,31 @@ export const githubReleaseChangelogSource = ({
     read: read
       ? async (ref: string) => excludeSearchFromRaw(await read(ref))
       : undefined,
+    withContext: withContext
+      ? (ctx: SourceContext) => withSearchExcluded(withContext(ctx))
+      : undefined,
   };
 };
+
+export const githubReleaseChangelogSource = ({
+  owner,
+  repo,
+  site,
+}: ReleaseSourceOptions): ContentSource =>
+  withSearchExcluded(
+    githubReleasesSource(
+      {
+        name: "changelog",
+        owner,
+        prefix: "changelog",
+        repo,
+        site,
+      },
+      // Placeholder until Blume calls withContext with the scan's context.
+      {
+        cacheDir: resolve(".blume/cache/changelog"),
+        mode: "build",
+        projectRoot: process.cwd(),
+      },
+    ),
+  );

apps/docs/umbraco-package.ts

@@ -15,21 +15,3 @@ export const webAnalyticsPackage = defineUmbracoPackage({
   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.thebuilder.dk/",
-    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];