Skip to content

docs: use code group for provider secrets #43

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
thebuilder merged 2 commits into from
Jul 31, 2026
Merged

docs: use code group for provider secrets #43

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
266d129
docs: use code group for provider secrets
thebuilder Jul 31, 2026
23d49e5
docs: simplify provider setup intro
thebuilder Jul 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 18 additions & 23 deletions apps/docs/docs/getting-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,29 +19,24 @@ The package registers its services and backoffice extensions automatically. Buil

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>
Choose the provider that already collects your site analytics. Use the [Vercel](/providers/vercel) or [Plausible](/providers/plausible) guide for its credential, connection identifier, and any provider-specific setup.

For local development, use either a shell environment variable or .NET user secrets:

<CodeGroup>

```sh Vercel
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
```

```sh Plausible
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
```

</CodeGroup>

Use the equivalent secret or app-setting facility in your hosting platform.

Expand Down