thebuilder · thebuilder · Jul 31, 2026 · Jul 31, 2026 · Jul 31, 2026
diff --git a/apps/docs/blume.config.ts b/apps/docs/blume.config.ts
@@ -29,6 +29,7 @@ export default defineConfig({
       { label: "Changelog", path: "/changelog", href: "/changelog" },
     ],
   },
+  redirects: [{ from: "/getting-started", to: "/quickstart", status: 301 }],
   deployment: {
     output: "static",
     site: "https://umbraco-web-analytics.vercel.app",

diff --git a/apps/docs/docs/getting-started.mdx b/apps/docs/docs/getting-started.mdx
diff --git a/apps/docs/docs/index.mdx b/apps/docs/docs/index.mdx
@@ -1,52 +1,39 @@
 ---
-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.
+title: Overview
+description: Bring the analytics your site already collects into Umbraco, giving editors useful traffic reports in the backoffice and on mapped documents.
 ---
 
-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.
+## Supported providers
 
-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.
+Choose the reference for the analytics provider your site already has.
 
-It reads analytics your provider already collects. It does **not** install, replace, or configure tracking on your public website.
+<CardGroup cols={2}>
+  <Card title="Vercel Web Analytics" href="/providers/vercel">
+    Reference connection fields, team projects, feature flags, and Vercel-specific errors.
+  </Card>
+  <Card title="Plausible" href="/providers/plausible">
+    Reference Cloud and self-hosted connections, event properties, and Plausible-specific errors.
+  </Card>
+</CardGroup>
 
-![The global Analytics dashboard in the Umbraco backoffice](./screenshots/analytics-overview.png)
-
-## Start here
+:::tip[Ready to connect your analytics?]
+[Follow the Quickstart](/quickstart) to install the package, connect the provider your site already uses, and verify the dashboard.
+:::
 
-<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>
+![The global Analytics dashboard in the Umbraco backoffice](./screenshots/analytics-overview.png)
 
 ## 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.
+- **Traffic reports.** Explore visitors, page views, trends, acquisition, audience, pages, routes, and campaigns.
+- **Document context.** Show analytics in mapped published document workspaces, scoped to the document's route.
+- **Useful detail.** Use date comparisons, filters, and drill-downs to move from a headline number to useful context.
+- **Multi-site support.** Add more than one connection to an Umbraco installation.
+- **Private credentials.** Keep provider access in server-side application configuration, never in the browser or Umbraco content.
+- **No tracking changes.** Read provider-collected data without installing, replacing, or configuring public-site tracking.
 
-## Supported versions and providers
+## Compatibility
 
-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.
-:::
+Web Analytics supports Umbraco CMS 17.1 through 18.x. [Vercel Web Analytics](/providers/vercel) and [Plausible](/providers/plausible) both provide core reports, event lists and details, and event-property drill-downs. The interface hides provider capabilities that are not available instead of presenting them as errors.
 
 ## Need the details?
 

diff --git a/apps/docs/docs/providers/plausible.mdx b/apps/docs/docs/providers/plausible.mdx
@@ -1,46 +1,38 @@
 ---
 title: Plausible
-description: Connect Plausible Cloud or a self-hosted Plausible site and configure event properties.
+description: Reference for Plausible Cloud and self-hosted connections, including fields, endpoint requirements, event properties, reports, and common errors.
 ---
 
-Use this guide after following the shared [getting-started flow](/getting-started).
+The [quickstart](/quickstart) owns the first-time setup flow. Use this page to look up Plausible-specific requirements, connection fields, and capabilities.
 
 ## About Plausible
 
 [Plausible](https://plausible.io/) is a privacy-friendly, open-source web analytics platform available as a hosted service or self-hosted instance. This package reads the reports Plausible already collects and makes them available in Umbraco; it does not add tracking to the public site.
 
-## Create the credential
+## Cloud and self-hosted requirements
 
-Create a Stats API key in Plausible and store it in the application's secret configuration:
+The connection needs a [Plausible Stats API key](https://plausible.io/docs/stats-api) in server-side configuration. Plausible Cloud's Stats API requires a Business plan.
 
-```text
-WebAnalytics__Providers__Plausible__AccessToken
-```
+Self-hosted Plausible is supported when the instance exposes the v2 Stats API query endpoint. Its public base URL must use HTTP or HTTPS and cannot include user information, a query, or a fragment. The Umbraco application must be able to reach its `/api/v2/query` endpoint.
 
-Plausible Cloud's Stats API requires a Business plan. Self-hosted Plausible is supported when the instance exposes the v2 Stats API query endpoint.
+## Connection fields
 
-## Configure a self-hosted instance
+| Field | Value |
+| --- | --- |
+| Credential setting | `WebAnalytics__Providers__Plausible__AccessToken` |
+| Site ID | The registered site ID, normally the domain, matching Plausible exactly |
+| Self-hosted base URL | `WebAnalytics__Providers__Plausible__BaseUrl=https://analytics.example.com/`; Cloud users keep the default `https://plausible.io/` |
 
-Set the public base URL of a self-hosted instance in server-side configuration. The URL must use HTTP or HTTPS and cannot include user information, a query, or a fragment. Its `/api/v2/query` endpoint must be reachable from the Umbraco application.
-
-```text
-WebAnalytics__Providers__Plausible__BaseUrl=https://analytics.example.com/
-```
-
-The default is `https://plausible.io/`, so Cloud users do not need to set this value.
-
-## Add the connection
-
-In **Settings → Web Analytics**, choose **Plausible** and enter the **Site ID**. This normally is the domain registered in Plausible and must match it exactly.
-
-Save, then select **Test connection**. A `401` or `403` usually means the Stats API key cannot read that site; a rejected query commonly means the Site ID does not match the registered domain.
+Add these values in **Settings → Web Analytics**. A `401` or `403` usually means the Stats API key cannot read that site; a rejected query commonly means the Site ID does not match the registered domain.
 
 ## Event properties
 
 Add custom event-property names when the site records properties beyond Plausible's built-in fields. You can configure up to 20 names, each with at most 100 characters.
 
-- `url` is built in for outbound-link and file-download goals.
-- `path` is built in for 404 goals.
+| Property | Built in for |
+| --- | --- |
+| `url` | Outbound-link and file-download goals |
+| `path` | 404 goals |
 
 ## Capabilities
 

diff --git a/apps/docs/docs/providers/vercel.mdx b/apps/docs/docs/providers/vercel.mdx
@@ -1,32 +1,27 @@
 ---
 title: Vercel Web Analytics
-description: Connect a Vercel project and understand its available analytics reports.
+description: Reference for Vercel Web Analytics connection fields, reports, team projects, credential overrides, and common connection errors.
 ---
 
-Use this guide after following the shared [getting-started flow](/getting-started).
+The [quickstart](/quickstart) owns the first-time setup flow. Use this page to look up Vercel-specific requirements, connection fields, and capabilities.
 
 ## About Vercel Web Analytics
 
 [Vercel Web Analytics](https://vercel.com/docs/analytics) is Vercel's analytics product for understanding traffic to a Vercel project. This package reads the reports Vercel already collects and makes them available in Umbraco; it does not add tracking to the public site.
 
-## Create the credential
+## Requirements
 
-Create a Vercel token in account settings and scope it to the account or team that owns the project. The access token must be configured server-side.
+The connection needs a [Vercel access token](https://vercel.com/kb/guide/how-do-i-use-a-vercel-api-access-token) scoped to the account or team that owns the project. Configure the token server-side; it is never stored in Umbraco.
 
-```text
-WebAnalytics__Providers__Vercel__AccessToken
-```
-
-For a team-owned project, copy either the team ID (`team_...`) or team slug as well.
-
-## Add the connection
-
-In **Settings → Web Analytics**, choose **Vercel** and enter:
+## Connection fields
 
-- **Project ID** — the Vercel project identifier beginning with `prj_...`.
-- **Team** — optional. Leave it blank for a personal project.
+| Field | Value |
+| --- | --- |
+| Credential setting | `WebAnalytics__Providers__Vercel__AccessToken` |
+| Project ID | Vercel project identifier beginning with `prj_...` |
+| Team | Optional for a personal project; for a team-owned project, use its `team_...` ID or slug |
 
-Save, then select **Test connection**. A `401` or `403` generally means the token cannot access the project; a `400` usually means the project ID or optional team value is invalid.
+Add these values in **Settings → Web Analytics**. A `401` or `403` generally means the token cannot access the project; a `400` usually means the project ID or optional team value is invalid.
 
 ## Capabilities
 

diff --git a/apps/docs/docs/quickstart.mdx b/apps/docs/docs/quickstart.mdx
@@ -0,0 +1,79 @@
+---
+title: Quickstart
+description: Install Web Analytics, configure a Vercel or Plausible credential, create and test a connection, then verify the Umbraco Analytics dashboard.
+---
+
+This is the complete first-time setup path for Web Analytics. Stay on this page from package installation to a working dashboard.
+
+## 1. Check the prerequisites
+
+Web Analytics supports Umbraco CMS 17.1 through 18.x. Your public site must already collect analytics with Vercel Web Analytics or Plausible; this package reads that data and does **not** add tracking to the public website.
+
+You also need a read-only provider credential that can access the Vercel project or Plausible site you want to connect.
+
+## 2. 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.
+
+## 3. Choose a provider and configure its credential
+
+Choose the provider that already collects analytics for your site. Store its credential in application secret configuration—not `appsettings.json` and never source control. Restart every Umbraco application instance after adding or rotating a credential.
+
+### Vercel Web Analytics
+
+1. Create a Vercel token scoped to the account or team that owns the project.
+2. Configure it as `WebAnalytics__Providers__Vercel__AccessToken` in your hosting platform's secret or app-setting facility.
+3. Copy the project ID, beginning with `prj_...`. For a team-owned project, also copy the team ID (`team_...`) or team slug.
+
+For local development, set the token with .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
+```
+
+### Plausible
+
+1. Create a Plausible Stats API key for the site you want to connect. Plausible Cloud requires a Business plan for Stats API access.
+2. Configure it as `WebAnalytics__Providers__Plausible__AccessToken` in your hosting platform's secret or app-setting facility.
+3. Copy the Site ID, normally the registered domain, exactly as it appears in Plausible.
+4. If you use a self-hosted instance, configure its public base URL as `WebAnalytics__Providers__Plausible__BaseUrl`. It must expose `/api/v2/query` to the Umbraco application.
+
+For local development, set the values with .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
+```
+
+## 4. Add 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: a Vercel project ID and optional team, or a Plausible Site ID.
+4. Select **Save settings**.
+
+![A Plausible connection in the Web Analytics settings screen](./screenshots/settings.png)
+
+## 5. Test the connection
+
+Select **Test connection** and 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.
+
+If the test fails, use [troubleshooting](/reference/troubleshooting). A provider may hide an unsupported panel; that is different from a failed connection.
+
+## 6. Verify the Analytics dashboard
+
+Open the global **Analytics** section. Check that totals and history load, then use a known date range with recorded production traffic.
+
+## Next step: document analytics
+
+Optionally configure [document analytics](/guides/document-analytics) when editors should see a report while editing a mapped document.
diff --git a/apps/docs/evals.yaml b/apps/docs/evals.yaml
@@ -6,7 +6,7 @@ questions:
       - The package registers its services and backoffice extensions automatically.
       - Build and deploy the Umbraco application as usual; NuGet static web assets include the App_Plugins files.
     routes:
-      - /getting-started
+      - /quickstart
 
   - id: configure-provider-secret
     question: How should I securely create, configure, deploy, and rotate an analytics provider credential?
@@ -16,7 +16,7 @@ questions:
       - Use the hosting platform's equivalent secret or app-setting facility in deployed environments.
       - Restart every Umbraco application instance after adding or rotating a credential.
     routes:
-      - /getting-started
+      - /quickstart
 
   - id: add-first-connection
     question: How do I add and test my first analytics connection, and how can I confirm whether it uses a shared credential or a connection override?
@@ -26,7 +26,7 @@ questions:
       - Enter the provider identifier, save settings, and select Test connection.
       - The settings screen reports whether it detected a shared credential or connection override without displaying or storing a token.
     routes:
-      - /getting-started
+      - /quickstart
 
   - id: settings-precedence
     question: How does Web Analytics configuration precedence work before and after the first Settings → Web Analytics save?