Add Web Analytics documentation site

.github/workflows/docs.yml

@@ -0,0 +1,57 @@
+name: Documentation
+
+on:
+  pull_request:
+    paths:
+      - apps/docs/**
+      - .github/workflows/docs.yml
+      - pnpm-lock.yaml
+      - pnpm-workspace.yaml
+      - package.json
+  push:
+    branches:
+      - main
+    paths:
+      - apps/docs/**
+      - .github/workflows/docs.yml
+      - pnpm-lock.yaml
+      - pnpm-workspace.yaml
+      - package.json
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_TOKEN: ${{ github.token }}
+      ASTRO_TELEMETRY_DISABLED: "1"
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Install documentation dependencies
+        run: corepack pnpm install --frozen-lockfile
+
+      - name: Check documentation
+        run: corepack pnpm docs:check
+
+      - name: Validate documentation links
+        run: corepack pnpm docs:validate
+
+      - name: Build documentation
+        run: corepack pnpm docs:build

.github/workflows/publish-nuget.yml

@@ -55,7 +55,6 @@ jobs:
           node-version: 24
 
       - name: Install backoffice dependencies
-        working-directory: src/TheBuilder.WebAnalytics/Client
         run: |
           corepack enable
           pnpm install --frozen-lockfile

.github/workflows/refresh-docs-on-release.yml

@@ -0,0 +1,19 @@
+name: Refresh documentation on release
+
+on:
+  release:
+    types:
+      - published
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  deploy:
+    name: Refresh Vercel documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger Vercel deployment
+        env:
+          VERCEL_DEPLOY_HOOK: ${{ secrets.VERCEL_DEPLOY_HOOK }}
+        run: curl --fail-with-body --request POST --retry 3 --retry-all-errors "$VERCEL_DEPLOY_HOOK"

.github/workflows/validate.yml

@@ -13,9 +13,6 @@ jobs:
   client:
     name: Client
     runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: src/TheBuilder.WebAnalytics/Client
     steps:
       - name: Check out repository
         uses: actions/checkout@v7
@@ -35,13 +32,13 @@ jobs:
 
       - name: Audit changed client code
         if: github.event_name == 'pull_request'
-        run: pnpm run audit --base '${{ github.event.pull_request.base.sha }}' --format github-annotations
+        run: pnpm --filter thebuilder-web-analytics run audit --base '${{ github.event.pull_request.base.sha }}' --format github-annotations
 
       - name: Test client
-        run: pnpm test
+        run: pnpm --filter thebuilder-web-analytics test
 
       - name: Build client
-        run: pnpm build
+        run: pnpm --filter thebuilder-web-analytics build
 
   dotnet:
     name: .NET (Umbraco ${{ matrix.umbraco-version }})
@@ -89,7 +86,6 @@ jobs:
         run: corepack enable
 
       - name: Install backoffice dependencies
-        working-directory: src/TheBuilder.WebAnalytics/Client
         run: pnpm install --frozen-lockfile
 
       - name: Pack NuGet package

.gitignore

@@ -4,6 +4,9 @@
 .pnpm-store/
 **/coverage/
 **/.vite/
+apps/docs/.blume/
+apps/docs/.blume-verify/
+apps/docs/dist/
 artifacts/
 src/TheBuilder.WebAnalytics/wwwroot/App_Plugins/
 **/umbraco/Data/
@@ -21,3 +24,4 @@ samples/TheBuilder.WebAnalytics.Example/appsettings-schema.json
 *.key
 .idea/
 .vs/
+.blume-verify/

apps/docs/.gitignore

@@ -0,0 +1 @@
+.blume-verify/

apps/docs/blume.config.ts

@@ -0,0 +1,42 @@
+import { defineConfig } from "blume";
+
+import { githubReleaseChangelogSource } from "./sources/github-releases";
+
+export default defineConfig({
+  title: "Web Analytics",
+  description:
+    "Bring Vercel Web Analytics and Plausible reports into the Umbraco backoffice.",
+  github: {
+    owner: "thebuilder",
+    repo: "web-analytics",
+    dir: "apps/docs",
+  },
+  content: {
+    sources: [
+      { type: "filesystem", root: "docs" },
+      {
+        type: "custom",
+        source: githubReleaseChangelogSource({
+          owner: "thebuilder",
+          repo: "web-analytics",
+        }),
+      },
+    ],
+  },
+  navigation: {
+    tabs: [
+      { label: "Docs", path: "/" },
+      { label: "Changelog", path: "/changelog", href: "/changelog" },
+    ],
+  },
+  deployment: {
+    output: "static",
+    site: "https://umbraco-web-analytics.vercel.app",
+  },
+  analytics: {
+    vercel: true,
+  },
+  ai: {
+    llmsTxt: true,
+  },
+});

apps/docs/docs/getting-started.mdx

@@ -0,0 +1,68 @@
+---
+title: Getting started
+description: Create a read-only credential with account or site access, store it in application or hosting-platform secret settings, restart every instance, and verify the connection.
+---
+
+This guide covers the shared path for both providers. Provider-specific identifiers and capabilities are covered in the [Vercel](/providers/vercel) and [Plausible](/providers/plausible) guides.
+
+## 1. Install the package
+
+Add Web Analytics to the Umbraco web project:
+
+```sh
+dotnet add package TheBuilder.WebAnalytics
+```
+
+The package registers its services and backoffice extensions automatically. Build and deploy the Umbraco application as usual; NuGet static web assets include the package's `App_Plugins` files.
+
+## 2. Choose a provider, configure its secret, and restart
+
+Create a read-only credential with access to the provider account or site being connected. Add it to the application's secret configuration—not `appsettings.json` and never source control. Restart every Umbraco application instance after adding or rotating the credential.
+
+<Tabs param="provider">
+  <Tab title="Vercel">
+    Create a Vercel access token with read access to the project. Configure it as `WebAnalytics__Providers__Vercel__AccessToken`, then use the project's ID as the connection identifier in Umbraco. Add the team ID only when the project belongs to a Vercel team.
+
+    For local development, use either a shell environment variable or .NET user secrets:
+
+    ```sh
+    dotnet user-secrets init --project path/to/Your.Umbraco.Web.csproj
+    dotnet user-secrets set "WebAnalytics:Providers:Vercel:AccessToken" "your_token" --project path/to/Your.Umbraco.Web.csproj
+    ```
+  </Tab>
+  <Tab title="Plausible">
+    Create a Plausible Stats API key with access to the site. Configure it as `WebAnalytics__Providers__Plausible__AccessToken`, then use the site's exact domain as the connection identifier in Umbraco. For a self-hosted instance, also configure `WebAnalytics__Providers__Plausible__BaseUrl` with its public base URL. The instance must expose `/api/v2/query`.
+
+    For local development, use either a shell environment variable or .NET user secrets:
+
+    ```sh
+    dotnet user-secrets init --project path/to/Your.Umbraco.Web.csproj
+    dotnet user-secrets set "WebAnalytics:Providers:Plausible:AccessToken" "your_stats_api_key" --project path/to/Your.Umbraco.Web.csproj
+    dotnet user-secrets set "WebAnalytics:Providers:Plausible:BaseUrl" "https://analytics.example.com/" --project path/to/Your.Umbraco.Web.csproj
+    ```
+  </Tab>
+</Tabs>
+
+Use the equivalent secret or app-setting facility in your hosting platform.
+
+## 3. Add and test the connection
+
+As an administrator, open **Settings → Web Analytics**.
+
+1. Select **Add connection**.
+2. Choose Vercel or Plausible. The provider cannot be changed after creation.
+3. Enter the provider identifier.
+4. Select **Save settings**, then **Test connection**.
+5. Review the credential status. The settings screen reports whether it detected a shared credential or a connection override. It does not display or store a token.
+
+![A Plausible connection in the Web Analytics settings screen](./screenshots/settings.png)
+
+## 4. Verify the dashboard
+
+Open the global **Analytics** section. Check that totals and history load, then use a known date range with recorded production traffic.
+
+If reports do not load, start with [troubleshooting](/reference/troubleshooting). A provider may hide an unsupported panel; that is different from a failed connection.
+
+## Next step
+
+Configure [document analytics](/guides/document-analytics) when editors should see a report while editing a mapped document.

apps/docs/docs/guides/document-analytics.mdx

@@ -0,0 +1,54 @@
+---
+title: Document analytics
+description: Map the nearest document root and types to show reports automatically filtered to the selected published route. Document reports do not require global Analytics-section access.
+---
+
+Document mappings are optional. A connection without a mapping remains available in the global Analytics section but does not add a document workspace report. Document reports do not require global Analytics-section access.
+
+## Map an Umbraco site root
+
+For each site that needs page-level reports, choose the root document in the connection's **Page analytics** settings. A document uses the connection from its nearest mapped ancestor; it does not use a connection from merely any ancestor root. A mapped document report is automatically filtered to its selected published route.
+
+Then either enable all document types below that root or choose the specific document types that should show the Analytics workspace view.
+
+## When the workspace appears
+
+A document shows its Analytics workspace view only when all of these conditions are met:
+
+- It is published and has a published route.
+- Its nearest configured document root must specifically resolve to a connection, not merely any ancestor root.
+- Its document type is enabled for that connection.
+- The current user can access the Content section and browse that document.
+
+This lets an editor inspect the page they are working on without first finding it in a global report.
+
+![The Analytics workspace on a mapped Home document](../screenshots/document-analytics-workspace.png)
+
+## Multi-site example
+
+Imagine one Umbraco installation with two site roots:
+
+| Root document | Connection | Result |
+| --- | --- | --- |
+| `Brand A` | Vercel project A | Documents below Brand A report against project A. |
+| `Brand B` | Plausible site B | Documents below Brand B report against site B. |
+
+If a nested root is mapped too, it wins for documents below it because it is the nearest mapped ancestor.
+
+## Permissions
+
+Global and document analytics are intentionally separate:
+
+| User | Global Analytics | Document Analytics | Settings |
+| --- | --- | --- | --- |
+| Administrator | Yes | Yes, where mapped | Yes |
+| Analytics-section user | Yes | Only with Content access and document browse permission | No |
+| Editor with Content access and document browse permission | No | Yes, where mapped and published | No |
+
+This means an editor can see analytics for a document they can browse without gaining access to global site reporting.
+
+Document reports do not require global Analytics-section access.
+
+## Troubleshoot a missing workspace
+
+Check publication and route state first, then the nearest root mapping and document-type setting. If the workspace still does not appear, verify Content-section access and document browse permission. See [troubleshooting](/reference/troubleshooting) for the full symptom checklist.

apps/docs/docs/guides/meta.ts

@@ -0,0 +1,8 @@
+import { defineMeta } from "blume";
+
+export default defineMeta({
+  title: "Guides",
+  icon: "book-open",
+  order: 2,
+  pages: ["document-analytics"],
+});

apps/docs/docs/index.mdx

@@ -0,0 +1,53 @@
+---
+title: Web Analytics for Umbraco
+description: Web Analytics provides a dedicated Analytics section with reports for visitors, page views, trends, acquisition, audience, pages, routes, and campaigns, plus mapped published document workspaces.
+---
+
+Web Analytics connects [Vercel Web Analytics](https://vercel.com/docs/analytics) and [Plausible](https://plausible.io/docs/stats-api) to Umbraco's dedicated Analytics section, so editors can understand traffic where they manage content.
+
+It provides a dedicated Analytics section with reports covering visitors, page views, trends, acquisition, audience, pages, routes, and campaigns. Document-workspace analytics are scoped to the mapped published document's route.
+
+It reads analytics your provider already collects. It does **not** install, replace, or configure tracking on your public website.
+
+![The global Analytics dashboard in the Umbraco backoffice](./screenshots/analytics-overview.png)
+
+## Start here
+
+<Steps>
+  <Step title="Install the package">
+    [Add Web Analytics to your Umbraco project](/getting-started), then build and deploy it as usual.
+  </Step>
+  <Step title="Configure and test a connection">
+    Create a provider credential, add it to server-side configuration, then add and test the connection in **Settings → Web Analytics**. Follow the provider-specific guide for [Vercel](/providers/vercel) or [Plausible](/providers/plausible) when you need its identifiers and capabilities.
+  </Step>
+  <Step title="Open Analytics">
+    Verify the global **Analytics** section, then set up [document analytics](/guides/document-analytics) when editors need page-level reports.
+  </Step>
+</Steps>
+
+## What you get
+
+- Analytics is displayed in mapped published document workspaces and scoped to the document route.
+- Provider-supported activity reports appear when available.
+- Date comparisons, filters, and drill-downs that help editors move from a headline number to useful context.
+- More than one connection for multi-site Umbraco installations.
+- Server-side provider access: credentials remain in the application configuration, never in the browser or Umbraco content.
+
+## Supported versions and providers
+
+Web Analytics supports Umbraco CMS 17.1 through 18.x.
+
+| Provider | Identifier | Credential | Provider-specific capabilities |
+| --- | --- | --- | --- |
+| Vercel Web Analytics | Project ID (`prj_...`) and optional team | Scoped access token | Feature flags |
+| Plausible | Site ID, usually the registered domain | Stats API key | Global event filtering and configurable event-property names |
+
+Both providers support core reports, event lists and details, and event-property drill-downs. The interface hides unsupported reports instead of presenting them as errors.
+
+:::note
+Plausible Cloud's Stats API requires a Business plan. Self-hosted Plausible is supported when its instance exposes the v2 Stats API query endpoint.
+:::
+
+## Need the details?
+
+The [configuration reference](/reference/configuration) explains configuration precedence, credentials, cache behaviour, and every supported option. Use [troubleshooting](/reference/troubleshooting) for missing access, connection errors, empty reports, and multi-instance deployment issues.

apps/docs/docs/providers/meta.ts

@@ -0,0 +1,8 @@
+import { defineMeta } from "blume";
+
+export default defineMeta({
+  title: "Providers",
+  icon: "plug",
+  order: 1,
+  pages: ["vercel", "plausible"],
+});