Skip to content

fix: point the docs links to the current Optimole docs pages with UTMs - #1246

Merged
poonam279 merged 2 commits into
developmentfrom
fix/docs-links-utm
Nov 20, 2026
Merged

poonam279 merged 2 commits into
developmentfrom
fix/docs-links-utm

Conversation

@poonam279

@poonam279 poonam279 commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Every docs link in the plugin uses an old HelpScout URL on docs.optimole.com (/article/…). They redirect to the current pages, but the redirect drops the query string, so no UTMs reach the docs. One of them, the AVIF link, now ends on a 404. This is part of Codeinwp/docs-site#1596 (reviewing docs links in all products).

This PR adds Optml_Admin::docs_url( $path, $campaign, $medium ). It builds the final URL (https://docs.optimole.com/<path>) and adds the UTMs with tsdk_utmify(): utm_source=wpadmin, utm_medium=<screen>, utm_campaign=<feature>. The dashboard's JavaScript can't call it, so Optml_Admin::get_dashboard_docs_links() passes the Help tab and Watermark URLs to the app as optimoleDashboardApp.docs_links.

Where utm_medium Links
Settings, feature descriptions ("Learn more") settings 25
Settings, Watermark "Learn more" button settings 1
Connect screen (visitors count, getting started) and the "can't reach your site" error connect 3
Dashboard, "View all optimization tips" dashboard 1
Help tab, Documentation section (9 articles and the docs home link) help 10

Example: https://docs.optimole.com/wordpress-plugin/best-format?utm_source=wpadmin&utm_medium=settings&utm_campaign=best-format&utm_content=docsoptimolecomwordpress-pluginbest-format

Links whose target changed:

Link Old article Now
AVIF Image Support /article/1943-avif-conversion (404) /wordpress-plugin/best-format, which covers AVIF
GIF to video /article/1171-gif-to-video-conversion, which redirects to the embedded videos page /wordpress-plugin/settings-reference (no GIF page exists)
Loading Method /article/1958-lazy-loading-behaviour /wordpress-plugin/bypass-lazy-load-for-first-images ("Lazy loading behavior")

The AVIF and GIF strings aren't shown by the dashboard today, nor are the noscript, first-images, loading method and offload info descriptions. They're updated anyway so no /article/ URL is left.

The record of current vs new parameters for every product is in the docs-links report: https://claude.ai/artifact/TFrbebxm6kHNpJfb7GfzR2

Testing

  • New PHPUnit test tests/test-docs-links.php (4 tests): docs_url(), a settings description, that no dashboard string uses an /article/ URL and every docs link has the UTMs, and the docs_links passed to the app. All 4 fail on the old code and pass with the fix.
  • Full PHPUnit suite (wp-env): 590 tests, 37 failures and 2 errors, all in the lazyload, media, replacer, REST optimizations, attachment replace and video tag tests. The same tests fail on development in the same environment (plus Test_Lazyload::test_dam_lazyloading there), so none come from this change.
  • Jest: 239 tests pass. ESLint passes on the changed files. npm run build:dashboard compiles.
  • phpcs passes. phpstan reports the same 6 errors as before: include() of assets/build/*.asset.php files that don't exist until the assets are built.
  • All 30 docs URLs return 200 with the UTMs (no redirect).

🤖 Generated with Claude Code

The docs links used the old docs.optimole.com/article/ URLs. They redirect
to the current pages, but the redirect drops the query string, so no UTMs
reached the docs. One of them (AVIF) now ends on a 404.

Adds Optml_Admin::docs_url() to build the final docs URL with tsdk_utmify(),
and passes the Help tab and Watermark docs URLs to the dashboard app as
docs_links.

Part of Codeinwp/docs-site#1596.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@pirate-bot

pirate-bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Plugin build for 004df16 is ready 🛎️!

@poonam279
poonam279 requested a review from pirate-bot November 19, 2026 18:34

@pirate-bot pirate-bot left a comment •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes requested

The dashboard links are fixed, but the readme and changelog still use old /article/ docs URLs that redirect.

  • readme.txt:37 — correctness readme.txt still links to old /article/ docs URLs at lines 37, 63, 300, 304, 326 and 330. README.md repeats them on the same lines. CHANGELOG.md has more at lines 214-220, 334 and 805-806. These links go through the same redirect that drops the query string, so they cannot carry attribution. They also depend on redirects that can disappear, as /article/1943-avif-conversion already did. Replace each one with its final docs path. For example, replace /article/1020-can-i-remove-the-blurry-placeholder-from-the-lazyload-effct with /wordpress-plugin/lazy-load-generic-placeholder.
Validation details
  • Files reviewed: 6/6 changed files. Feature-to-page mapping of the repointed links (a history question) stayed unchecked.
  • PHPUnit Test_Docs_Links at HEAD (PHP 8.3, sandbox): cd /repo; set -o pipefail; timeout 280 vendor/bin/phpunit --do-not-cache-result --filter 'Test_Docs_Links::' 2>&1 | tee … printed OK (4 tests, 67 assertions) (run R3)
  • Against pr-base, the two string tests fail on the old /article/ URLs. The two helper tests error because the helpers are new.
  • All 39 new docs URLs return HTTP 200 without a redirect: cd /workspace/checks/R1; curl -s -o /dev/null -m 15 -w 'probe %{http_code}\n' https://docs.optimole.com/ ; python3 -c " … (run R5, exit 0)
  • Every consumer renders the strings as HTML, so the &#038; from esc_url() decodes in the link.
Untested areas
  • Feature-to-page mapping of the repointed links: compared by curl, but the run was not recorded. Old and new slugs match except the three repoints the PR describes.
  • No Jest test reaches the Help tab or the Watermark button. The PHP test covers the docs_links payload.
  • No browser check of the rendered links.
  • The variant pass did not settle these places, where the fixed cause may still reach:
    • inc/admin.php:802-823 — unverified: Replacement producers pass section paths through tsdk_utmify; its installed implementation is absent, and final-destination redirect behavior was not checked. No remaining legacy l…

🤖 Automated review · run code-review-agent_6aff4140e6b743.26440645.


🤖 Review agent — review posted ✅ on 0a4d5063 · changes requested · 1 finding · 21 min

Run code-review-agent_6aff4140e6b743.26440645 · trail

25 links in the dashboard strings used target=”_blank” with curly quotes.
The browser reads that as a window named ”_blank”, so every link opened
in the same reused tab. 24 of them are the docs links changed here; the
other is the plan quota notice.

Part of Codeinwp/docs-site#1596.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@poonam279
poonam279 dismissed pirate-bot’s stale review November 20, 2026 07:49

This is out of scope for this PR. This work covers the docs links shown inside the plugin's admin screens, where the utm_source=wpadmin UTMs fit. The readme links show on wordpress.org, not in wp-admin, and the changelog is history, so both are left out on purpose. The same applies to the other product PRs in Codeinwp/docs-site#1596.

@poonam279
poonam279 merged commit e6ea072 into development Nov 20, 2026
13 checks passed
@poonam279
poonam279 deleted the fix/docs-links-utm branch November 20, 2026 07:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants