Highlight.js Deployment: Condition To Confirm if Page URL Matches the Canonical

This support article describes a feature of our highlight.js scripts that confirms whether a Page URL matches the canonical URL element in the HTML, and sends markup to the canonical URL.

Note: This feature applies Editor deployment, as well as Highlighter deployment via a URL pattern or list of URLs defined in Step 3. Deployment via XPath does not require the canonical URL to match the Page URL.

What are canonical link elements?

Search engines use canonical canonical link elements within the HTML of a page, to determine the most representative URL for a piece of content.

The canonical link element looks something like this:

<link rel="canonical" href="https://example.com/path/a-page-name/" />

How does this feature work?

When the highlight.js script runs on a particular page (e.g. https://www.website.com/example-url), the script will check that the Page URL matches the canonical URL listed in the HTML. If there is a mis-match, the Highlight.js script will prefer to generate markup for the canonical URL listed in the HTML. Therefore, markup will only deploy to Canonical URLs that are also targeted by the deployment pattern for a given template.

Variant: Canonical is different from Page URL

The Page URL is 'https://www.website.com/example-url'.

The on-page Canonical URL Element references 'https://www.website.com/example-url/nested-folder'.

Because the Page URL and the Canonical URL do not match, highlight.js will not not deploy to this page, as https://www.website.com/example-url/nested-folder would be preferred.

Variant: Canonical URL Includes Parameters

The Page URL is 'https://example.com/my-page'

The on-page Canonical URL Element references 'https://example.com/my-page?section=1234'

Because the Page URL highlight.js will generate and record markup for the canonical URL, the will not deploy to https://example.com/my-page, as https://example.com/my-page?section=1234 will be preferred.

Variant: Canonical URL is Relative not Absolute

The Page URL is 'https://example.com/my-page' 

The on-page Canonical URL Element is '/my-page'

Google does not recommend this format, however it is still valid. In the case that the canonical URL is relative, the Schema App Highlighter will construct a URL using the protocol and host from the website (e.g. https://example.com).

Variant: Canonical URL uses different case

The URL listed in Step 3 is 'https://example.com/my-page'

The on-page Canonical URL is 'https://example.com/My-Page' 

The Highlighter tool will not deploy to 'https://example.com/My-Page' without matching capitalization.

Variant: No Canonical URL is Present

The Page URL is 'https://example.com/my-page'

There is no canonical URL.

Because there is no canonical to check against, the markup will deploy 'https://example.com/my-page'

Possible Workarounds for Non-matching Canonical URLs

Sometimes, we will want to test markup for URLs that do not match their canonical URLs. This section will review possible scenarios and workarounds for those scenarios.

Scenario: Testing in PrePROD Environments

Description: Testing Deployment in a prePROD environment where canonical URL references PROD version

Solution: Include the PROD URLs in the list of URLs in Step 3.