You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 24f948f
Browse filesBrowse the repository at this point in the historyBrowse files
docs: rewrite docs site and README copy in plainer language (#59)
* docs: rewrite docs site and README copy in plainer language
Pass over every user-facing text surface to replace vague marketing
phrasing with statements of what the package actually does.
The marketplace readme was the worst offender: a bold-label-colon
feature list, a puffery line about "where content decisions happen",
and a "Ready to bring your analytics into the backoffice?" call to
action. It is now six bullets that each name a concrete behaviour.
On the landing page, "The traffic signals that matter for the current
editorial task, within immediate reach, with nothing more to configure"
said nothing specific to this package. Replaced with the actual
contents of the dashboard. The phrase "follow a headline number down to
the context behind it" appeared in four files and is gone from all of
them. The Plausible card claimed you could explore "privacy-friendly
traffic", which is not a property traffic can have; it now names what
Plausible adds over Vercel.
Both provider pages opened with "The quickstart owns the first-time
setup flow". Vague capability statements now name the mechanism:
"The backoffice adapts to those capabilities" became "The backoffice
hides both controls on a Vercel connection".
Also thinned out repetition introduced while rewriting: "already" ran
six times on the landing page alone, the marketplace bullets all opened
with the same verb form, and the "a hidden panel is not an error" fact
was stated six times across the doc set. It now stays where it is the
point and comes out of the overview's Compatibility section.
Two accuracy fixes found along the way:
- A marketplace screenshot caption said "provider-supported events and
features" where it meant feature flags.
- A document-analytics condition read "Its nearest configured document
root must specifically resolve to one or more connections, not merely
any ancestor root", mixing "must" into a list of plain conditions and
repeating a clause from earlier on the page.
No behaviour or structural changes. Docs build, type-check, and
validate clean; the 9 asset warnings from `blume validate` predate
this change.
* docs: add install and setup steps to the marketplace readme
The marketplace listing is a standalone landing surface, reached
without going through the docs site, but it only described what the
package does. Someone reading it had no way to get started without
first finding the documentation link on the last line.
Adds a short Install section (package reference, version and provider
prerequisites, the Plausible Cloud Business plan requirement) and a
four-step connection setup covering the credential, the restart, the
Settings screen, and Test connection. Gives the documentation link its
own section rather than a bare trailing sentence.
Steps verified against apps/docs/docs/quickstart.mdx and the document
analytics guide.
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+14-14Lines changed: 14 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,10 @@
1
1
# Contributing to Web Analytics
2
2
3
-
Thanks for your interest in improving Web Analytics for Umbraco. This guide covers the repository layout, how to set up a local development environment, and how to get a change merged. For how released package versions reach NuGet, see [docs/releasing.md](docs/releasing.md).
3
+
Thanks for helping improve Web Analytics for Umbraco. This guide covers the repository layout, how to set up a local development environment, and how to get a change merged. [docs/releasing.md](docs/releasing.md) covers how a released version reaches NuGet.
4
4
5
5
## Repository layout
6
6
7
-
This repository is a pnpm and .NET workspace. The most relevant folders:
7
+
The repository is a pnpm and .NET workspace. The folders you are most likely to touch:
8
8
9
9
| Path | What it is |
10
10
| --- | --- |
@@ -17,9 +17,9 @@ This repository is a pnpm and .NET workspace. The most relevant folders:
17
17
18
18
## Prerequisites
19
19
20
-
-[.NET SDK 10.0](https://dotnet.microsoft.com/download): builds the package, sample, and tests.
21
-
-[Node.js 24](https://nodejs.org/): builds the backoffice client and the docs site.
22
-
-[pnpm](https://pnpm.io/) via [Corepack](https://nodejs.org/api/corepack.html). Run `corepack enable` once; the pinned pnpm version is resolved automatically from `package.json`.
20
+
-[.NET SDK 10.0](https://dotnet.microsoft.com/download) builds the package, sample, and tests.
21
+
-[Node.js 24](https://nodejs.org/) builds the backoffice client and the docs site.
22
+
-[pnpm](https://pnpm.io/) via [Corepack](https://nodejs.org/api/corepack.html). Run `corepack enable` once. The pinned pnpm version comes from `package.json`.
23
23
24
24
Install the JavaScript dependencies from the repository root:
25
25
@@ -29,7 +29,7 @@ pnpm install
29
29
30
30
## Build the backoffice client
31
31
32
-
The backoffice UI is a separate frontend build. A plain `dotnet build` of the sample does **not** rebuild it; the client is only built automatically when the NuGet package is packed. During development, build (or watch) the client yourself so its assets land in `wwwroot/App_Plugins/`:
32
+
The backoffice UI is a separate frontend build. A plain `dotnet build` of the sample does **not** rebuild it. Only packing the NuGet package triggers the client build, so during development you run it yourself. The assets land in `wwwroot/App_Plugins/`:
33
33
34
34
```sh
35
35
pnpm client:build # one-off build
@@ -44,9 +44,9 @@ The example project references the package directly, so it always uses your loca
44
44
dotnet run --project samples/TheBuilder.WebAnalytics.Example
45
45
```
46
46
47
-
On first launch Umbraco installs unattended and creates a local SQLite database. In `Development` the sample enables mock connections (`WebAnalytics:EnableMockConnections`), so the Analytics section shows deterministic sample data without any Vercel or Plausible credential. For live data, configure a real provider credential and connection exactly as a consumer would (see the [Quickstart](https://web-analytics.thebuilder.dk/quickstart)).
47
+
On first launch Umbraco installs unattended and creates a local SQLite database. In `Development` the sample turns on mock connections (`WebAnalytics:EnableMockConnections`), so the Analytics section shows deterministic sample data without any Vercel or Plausible credential. For live data, set up a real provider credential and connection the way a consumer would. See the [Quickstart](https://web-analytics.thebuilder.dk/quickstart).
48
48
49
-
For an efficient loop, run `pnpm client:watch` in one terminal and `dotnet run` in another.
49
+
Run `pnpm client:watch` in one terminal and `dotnet run` in another for the fastest loop.
dotnet test tests/TheBuilder.WebAnalytics.Tests/TheBuilder.WebAnalytics.Tests.csproj # .NET tests
57
57
```
58
58
59
-
The .NET suite runs against Umbraco 17.1, the latest 17.x, and the latest 18.x in CI. Target a specific line locally by passing the version, for example `-p:UmbracoVersion=18.*`.
59
+
CI runs the .NET suite against Umbraco 17.1, the latest 17.x, and the latest 18.x. Target one line locally by passing the version, for example `-p:UmbracoVersion=18.*`.
60
60
61
61
## Work on the documentation site
62
62
@@ -66,15 +66,15 @@ pnpm docs:build # production build
66
66
pnpm docs:check # validate content and links
67
67
```
68
68
69
-
The `apps/docs/`content is Markdown/MDX; see the files under `apps/docs/docs/`for structure.
69
+
The content in `apps/docs/` is Markdown and MDX. The files under `apps/docs/docs/`show the structure.
70
70
71
71
## Submitting a change
72
72
73
73
1. Create a branch for your change.
74
-
2. Keep pull requests focused, and update the relevant docs under `apps/docs/` when behaviour changes.
75
-
3. Run the frontend and .NET tests above so CI passes on the first try. The `Validate` workflow builds the client, runs both test suites across the supported Umbraco versions, and validates the NuGet package.
76
-
4. Open a pull request against `main`with a clear description of the change and its motivation.
74
+
2. Keep pull requests focused, and update the docs under `apps/docs/` when behaviour changes.
75
+
3. Run the frontend and .NET tests above so CI passes first time. The `Validate` workflow builds the client, runs both test suites across the supported Umbraco versions, and validates the NuGet package.
76
+
4. Open a pull request against `main`explaining what changed and why.
77
77
78
78
## Releasing
79
79
80
-
Publishing packages to NuGet is release-driven and documented separately in [docs/releasing.md](docs/releasing.md). GitHub Releases are the authoritative changelog and are surfaced in the [documentation changelog](https://web-analytics.thebuilder.dk/changelog/).
80
+
Publishing to NuGet is release-driven and documented separately in [docs/releasing.md](docs/releasing.md). GitHub Releases are the authoritative changelog and are mirrored in the [documentation changelog](https://web-analytics.thebuilder.dk/changelog/).
Bring Vercel Web Analytics and Plausible reports into the Umbraco backoffice. Editors can understand site-wide traffic and the performance of the page they are working on without leaving Umbraco.
7
+
Read the traffic your site already sends to Vercel Web Analytics or Plausible, and report it inside the Umbraco backoffice. Editors get the site-wide numbers and the numbers for the page they are editing, without leaving Umbraco.
8
8
9
9
10
10
11
-
Web Analytics reads analytics already collected by the configured provider. It does **not** install, replace, or configure tracking on your public website.
11
+
Web Analytics is read-only. It does **not** install, replace, or configure tracking on your public website.
12
12
13
13
## Install
14
14
@@ -18,7 +18,7 @@ Web Analytics supports Umbraco CMS 17.1 through 18.x. Add it to the Umbraco web
18
18
dotnet add package TheBuilder.WebAnalytics
19
19
```
20
20
21
-
Your public site must already collect analytics with Vercel or Plausible; this package reads that data and does not add tracking of its own.
21
+
Your public site must already collect analytics with Vercel or Plausible. This package reads that data and adds no tracking of its own.
22
22
23
23
The package registers its services and backoffice extensions automatically. Then:
24
24
@@ -40,15 +40,15 @@ Plausible Cloud's Stats API requires a Business plan. Self-hosted Plausible is s
40
40
41
41
## Configure a credential
42
42
43
-
Provider credentials are always read from **server-side configuration** and are never stored in Umbraco or exposed to the browser. Keep them out of `appsettings.json` and source control. Use environment variables, [.NET user secrets](https://learn.microsoft.com/aspnet/core/security/app-secrets), or your hosting platform's secret store. Restart every application instance after adding or rotating a credential.
43
+
Provider credentials are always read from **server-side configuration**. They are never stored in Umbraco and never sent to the browser. Keep them out of `appsettings.json` and source control: use environment variables, [.NET user secrets](https://learn.microsoft.com/aspnet/core/security/app-secrets), or your hosting platform's secret store. Restart every application instance after adding or rotating a credential.
44
44
45
-
The configuration keys use the standard .NET double-underscore (`__`) delimiter for environment variables, or `:`for user secrets and JSON.
45
+
Configuration keys use the standard .NET double-underscore (`__`) delimiter in environment variables, or `:`in user secrets and JSON.
46
46
47
47
### Vercel
48
48
49
49
1. Create 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.
50
-
2.Provide it as `WebAnalytics__Providers__Vercel__AccessToken`.
51
-
3. Note the project ID (`prj_...`), and the team ID (`team_...`) or slug for a team-owned project, to enter in Settings.
50
+
2.Set it as `WebAnalytics__Providers__Vercel__AccessToken`.
51
+
3. Note the project ID (`prj_...`), plus the team ID (`team_...`) or slug for a team-owned project. You enter those in Settings.
@@ -57,9 +57,9 @@ dotnet user-secrets set "WebAnalytics:Providers:Vercel:AccessToken" "your_token"
57
57
### Plausible
58
58
59
59
1. Create a [Plausible Stats API key](https://plausible.io/docs/stats-api) for the site you want to connect.
60
-
2.Provide it as `WebAnalytics__Providers__Plausible__AccessToken`.
61
-
3. Note the Site ID (normally the registered domain) to enter in Settings.
62
-
4.For a self-hosted instance, set `WebAnalytics__Providers__Plausible__BaseUrl` to its public base URL (it must expose `/api/v2/query`). Cloud users keep the default `https://plausible.io/`.
60
+
2.Set it as `WebAnalytics__Providers__Plausible__AccessToken`.
61
+
3. Note the Site ID, normally the registered domain. You enter it in Settings.
62
+
4.On a self-hosted instance, set `WebAnalytics__Providers__Plausible__BaseUrl` to its public base URL, which must expose `/api/v2/query`. Cloud users keep the default `https://plausible.io/`.
@@ -68,15 +68,15 @@ dotnet user-secrets set "WebAnalytics:Providers:Plausible:BaseUrl" "https://anal
68
68
69
69
### Per-connection credential override (optional)
70
70
71
-
When one connection needs a different credential from the shared provider token, set a connection-specific override keyed by the connection GUID. The Settings screen shows the exact key. An override takes precedence over the shared provider credential.
71
+
When one connection needs a different credential from the shared provider token, set an override keyed by that connection's GUID. The Settings screen shows the exact key. An override wins over the shared provider credential.
The Settings screen (**Settings → Web Analytics**) is the normal way to manage connections. Configuration precedence works as follows:
79
+
The Settings screen (**Settings → Web Analytics**) is the normal way to manage connections. Precedence works like this:
80
80
81
81
- At startup the package reads the `WebAnalytics` section from server configuration.
82
82
- Until an administrator first saves Settings, those non-secret values are the active configuration.
@@ -85,21 +85,21 @@ The Settings screen (**Settings → Web Analytics**) is the normal way to manage
85
85
86
86
Each application instance keeps its own in-memory report cache, so restart every instance after changing saved settings or credentials.
87
87
88
-
Besides the provider credentials above, these tunables live under the `WebAnalytics` section:
88
+
Besides the provider credentials above, the `WebAnalytics` section takes these options:
89
89
90
90
| Key | Default | Description |
91
91
| --- | --- | --- |
92
92
|`Enabled`|`true`| Enables the Analytics section and configured document workspace views. |
93
93
|`DefaultRangeDays`|`30`| Initial reporting range, in days. Valid values are 1 to 730. |
94
94
|`CacheDuration`|`00:05:00`| Per-instance in-memory cache duration. Valid from zero to one hour. |
95
95
|`Connections`|`[]`| Provider connection definitions. The first becomes the initial default. |
96
-
|`EnableMockConnections`|`false`|Development-only deterministic connection presets. Never enable in production. |
96
+
|`EnableMockConnections`|`false`|Deterministic development-only connection presets. Never enable in production. |
97
97
98
-
Connections are normally created through the Settings screen, but they can also be bootstrapped from configuration for deployment automation. The [configuration reference](https://web-analytics.thebuilder.dk/reference/configuration) documents every connection key and the full precedence rules.
98
+
Connections are normally created through the Settings screen, but deployment automation can bootstrap them from configuration instead. The [configuration reference](https://web-analytics.thebuilder.dk/reference/configuration) documents every connection key and the full precedence rules.
99
99
100
100
## Documentation
101
101
102
-
The full documentation site covers everything above in more depth, plus the reporting UI and per-provider capabilities:
102
+
The documentation site covers everything above in more depth, plus the reporting UI and per-provider capabilities:
103
103
104
104
-[Quickstart](https://web-analytics.thebuilder.dk/quickstart): install, connect a provider, and verify the dashboard.
105
105
-[Understanding your reports](https://web-analytics.thebuilder.dk/guides/reports): what each metric, breakdown, and control means.
@@ -108,4 +108,4 @@ The full documentation site covers everything above in more depth, plus the repo
108
108
109
109
## Contributing
110
110
111
-
Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md)for the repository layout, local development setup (building the backoffice client, running the sample site, and running the tests), and how to submit a pull request. NuGet publishing guidance is in [docs/releasing.md](docs/releasing.md). GitHub Releases are the authoritative changelog and are surfaced in the [documentation changelog](https://web-analytics.thebuilder.dk/changelog/).
111
+
Contributions are welcome. [CONTRIBUTING.md](CONTRIBUTING.md)covers the repository layout, local development setup, and how to open a pull request. [docs/releasing.md](docs/releasing.md) covers NuGet publishing. GitHub Releases are the authoritative changelog and are mirrored in the [documentation changelog](https://web-analytics.thebuilder.dk/changelog/).
0 commit comments