Siteimprove.Umbraco17.Plugin 1.0.0

Siteimprove Content Assistant for Umbraco 17

Version 1.0.0 integrates Siteimprove Content Assistant with Umbraco CMS 17.7.1 or later in the 17.x series on .NET 10. It provides published-page insights, full-page draft checks and highlighting inside the editing workflow. A valid Siteimprove account is required.

The same package can be deployed through Umbraco Cloud or a self-hosted build. Validation covers a self-hosted Linux site and Chromium, Firefox and WebKit; see validation and known limits for the tested scope. Read the 1.0.0 release notes.

Documentation

See package information for bundle contents and verification.

• Installation and upgrade: install the release package, install through NuGet, deploy on Cloud or self-hosted sites, and upgrade from v13.
• Usage, configuration, and troubleshooting: editor workflows, Settings → Siteimprove, domain overrides, and common problems.
• Browser test results and release acceptance: verified behavior and remaining checks.
• Marketplace listing: shared listing for Umbraco 13 and 17, package mapping and release checks.
• Release preparation: verify the customer bundle, prepare a stable release, and publish the verified artifacts.

Install

Install the public release from NuGet.org:

dotnet add YourSite.csproj package Siteimprove.Umbraco17.Plugin --version 1.0.0

Before public publication, or when using an internal feed, obtain the verified release bundle and follow the installation guide. Merging this repository does not publish the package automatically.

Remove Siteimprove.Umbraco13.Plugin and stale App_Plugins/Siteimprove files before installing the new package. Rebuild and restart the site, then reload the backoffice. NuGet build targets copy the new files into App_Plugins/Siteimprove for development and include them in published output. No frontend compilation or npm dependencies are required; the modules use Umbraco's backoffice import map.

This upgrades the plugin, not the site's CMS or database. Follow Umbraco's supported upgrade process separately. The old implementation is retained on umbraco-13.

Use and configuration

A valid Siteimprove account is required. The Content Assistant loads after backoffice authentication. Selecting a published document sends its public URL to the assistant. New/unpublished documents clear the previous live-page context. Saving or publishing refreshes that URL; leaving the document clears it. The launcher and panel are visible only in document editing and rendered preview, including drafts. Settings, dashboards and other sections hide them. Preview uses the published route for live insights; never-published content has no live URL and still supports full-page prepublish checks.

For multilingual content, the selected culture is passed to Umbraco's URL provider. In split view the single assistant uses the first (left-hand) culture.

Administrators with access to Settings can open its Siteimprove tab and set a public domain there. Use an HTTP or HTTPS origin such as https://www.example.com; leave it blank to retain Umbraco's published URLs. The scheme, hostname, and port are replaced while the page path is preserved. The original SiteimprovePublicUrl database key is retained.

Environment configuration takes precedence over the database value:

{
  "Siteimprove": {
    "PublicUrl": "https://www.example.com",
    "EnablePreviewChecks": true
  }
}

Omit PublicUrl to use the database value. Set it to "" to force unmodified Umbraco URLs for that environment. When configured, the dashboard displays a read-only value. Settings endpoints require administrator access; document URL endpoints require backoffice authentication, access to the document tree, and browse permission for the requested document.

Umbraco Cloud

Install the package in the Cloud site's project and deploy through its normal Git/build process. Set domain overrides per environment using configuration (for example Siteimprove__PublicUrl where environment-variable configuration is available). Confirm whether each environment should map to the live domain; a development preview's prepublish check still examines the preview's rendered HTML.

Self-hosted / on-premises

Install and publish the same package with the application. Ensure editors' browsers can access Siteimprove's CDN and account services. Siteimprove's live crawling also needs access to the published site; private-site crawling needs a separately supported Siteimprove setup.

Restrictive Content Security Policies must allow the plugin's same-origin script, Siteimprove's overlay script at https://cdn.siteimprove.net, and the services required by your Siteimprove account. The plugin does not relax CSP headers.

Preview checks

Use Umbraco's Save and preview action. The assistant is injected into rendered HTML only when Umbraco verifies the preview session and the routed request is in preview mode. It supports Umbraco 17's separate preview window, without assuming an iframe, a referrer, or an integer document ID.

The prepublish callback returns the rendered document and supports highlighting. An unpublished page can be checked even when it has no public URL. Ordinary public responses are untouched. Non-HTML, compressed, non-UTF-8, and non-success responses are passed through.

Headless/external preview providers render outside this Umbraco application and need their own Siteimprove integration. This middleware covers server-rendered Umbraco website previews.

Development and validation

npm test
python3 -m unittest discover -s tests/python -v
dotnet test tests/Siteimprove.Umbraco17.Plugin.Tests.csproj -c Release
dotnet pack Siteimprove.Umbraco17.Plugin.csproj -c Release -o artifacts
bash scripts/verify-package.sh

The GitHub validation workflow builds, tests, packs, and checks installation and published assets. After the browser matrix passes it creates and verifies a customer ZIP with checksums, provenance and the matching guides/release notes. It uploads the package and customer ZIP as artifacts. Follow release preparation to publish the artifacts from a successful validation run on the merged commit.

Chromium, Firefox and WebKit functionality tests also run against a real Umbraco installation in CI. See docs/BROWSER-TESTS.md for verified behavior, the Playwright report/trace, and local execution instructions.