/** * Add the Themeisle UTM parameters to a docs link. * * Mirrors the SDK's tsdk_utmify() in PHP, so links built in the dashboard app * report the same utm_source, utm_medium, utm_campaign and utm_content values. * * @param url - The docs page URL. * @param utmCampaign - The feature or placement the link belongs to. * @param utmMedium - The screen the link is shown on. * @returns The URL with UTM parameters, or the URL unchanged if it is not a full URL. * * @example * docsURL('https://docs.themeisle.com/super-page-cache/defer-js', 'defer-js', 'settings') * // https://docs.themeisle.com/super-page-cache/defer-js?utm_source=wpadmin&utm_medium=settings&utm_campaign=defer-js&utm_content=docssuper-page-cachedefer-js */ export function docsURL(url: string, utmCampaign: string, utmMedium: string) { // The Help page passes links from the remote docs feed. A relative or empty one // must not throw, or the whole page goes blank: return it unchanged instead. let link: URL; try { link = new URL(url); } catch { return url ?? ''; } const content = ['https://', 'themeisle.com', '/themes/', '/plugins/', '/upgrade'] .reduce((value, part) => value.split(part).join(''), url) .replace(/^\/+|\/+$/g, '') .toLowerCase() .replace(/[^a-z0-9_-]/g, ''); link.searchParams.set('utm_source', 'wpadmin'); link.searchParams.set('utm_medium', utmMedium); link.searchParams.set('utm_campaign', utmCampaign); link.searchParams.set('utm_content', content); return link.toString(); }