Comprehensive UTM tags documentation (backport of #712 to 5.2)

[promptless-for-oss]

Open in Promptless

Backports the comprehensive UTM tags documentation from user-documentation PR #712 onto the 5.2 branch, at the maintainer's request. It replaces the single thin docs/channels/utm_tags.rst page with a dedicated eight-page UTM Tags section under docs/utm_tags/ — an overview plus per-feature guides for Landing Pages, Asset downloads, Forms, Emails, Dynamic Web Content, Campaign conditions, and Segment filters. The two inbound :doc: links (from Focus Items and Dynamic Web Content) are repointed to the new overview, the old page is removed, the UTM Tags toctree caption is added to the docs index, and CPC/DWC are added to the Vale vocabulary.

Adapted for 5.2: the overview page's screenshot directive points to add_ga_code.png, the Google Analytics ID image that exists on this branch (the 7.x branches use a differently named file).

A few objective RST defects present in the source PR (a nested .. note::, a malformed inline literal, and inconsistent casing inside example-URL code blocks) are corrected in this backport; a placeholder screenshot TODO in the Forms page is carried over as-is.

Trigger Events

• GitHub PR comment on mautic/user-documentation#712 requesting 7.1/7.2/6.0/5.2 backports

Synced from #712 code review (2026-08-14)
Applied maintainer @RCheesley's "Apply suggestions from code review" edits from #712 to keep this backport in step: swapped the placeholder example-URL host to example.com in docs/utm_tags/utm_tags_forms.rst and docs/utm_tags/utm_tags_landing_pages.rst (three sample URLs total). All three edits were applied verbatim. The third file changed on #712 (utm_tags_segment_filters.rst, an inline-literal typo fix on utm_content) needed no change here — that defect was already corrected in this backport, so it was a no-op.

---

Synced with #712 current head + outstanding review nits (2026-09-07)
At @adiati98's request (cherry-pick #712's newest reviewed commit into the backports, plus apply the outstanding fixes), this backport is brought in step with #712's current head:

• Screenshot added — the .. TODO: add screenshot marker on the Forms UTM page is replaced with the 'UTM tags recorded' Contact timeline screenshot (docs/channels/images/utm_tags/utm_tags_recorded_timeline.png). (Supersedes the earlier "TODO carried over as-is" note.)
• Record UTM Tags action-label casing — matches the on-screen label (verified against mautic/mautic LeadBundle messages.ini): utm_tags_forms.rst, utm_tags_campaign_conditions.rst, utm_tags_overview.rst table.
• Host swap yoursite.com/your-mautic.com → example.com (utm_tags_emails.rst, utm_tags_asset_downloads.rst).
• API payload keys referrer→referer, User_agent→user_agent (utm_tags_overview.rst REST bullet).
• Copy/grammar — UTM tags - Urchin Tracking Module - are intro; DWC line narrowed to "tracked links in Dynamic Web Content"; emails "links in the Email"; terminal period on the DWC page.

Branch-specific: the Google-Analytics-ID screenshot on this 5.2 branch stays add_ga_code.png (the 7.x branches use add_google_analytics_id.png); only the new timeline screenshot is added.

Both items previously flagged for your call are now resolved per your reply on #712:

1. Condition paths → green/red wording — switched the Yes/No output-path references (intro, numbered step, and warning) in utm_tags_campaign_conditions.rst to the green/red path terminology the Campaign Builder UI actually uses (green = match, red = no match). Verified against mautic/mautic app/bundles/CampaignBundle/Assets/js/campaign.js: a Contact field value condition node draws a green connector for the match path (--support-success-inverse) and a red connector for the no-match path (--support-error-inverse), with no literal Yes/No text — confirmed identical across 5.2, 6.0, 7.0, 7.1, and 7.2. Matches this repo's own campaign_builder.rst ("Green paths"/"Red paths").
2. Grammar — step lines read Open the … and edit its details: (dropped the stray "the"; kept the "its" wording).

Vale is clean on all changed lines.

[promptless-for-oss]

All 8 UTM Tags pages on this branch are a verbatim backport of already-reviewed content from user-documentation PR #712 (base 7.0). Product-behavior claims are inherited from that PR's review; the Mautic app source is not in this docs repo. Backport adaptations for 5.2: the overview page's screenshot directive points to add_ga_code.png (the image present on 5.2). Objective RST-defect fixes applied: flattened a nested .. note:: in utm_tags_landing_pages.rst, corrected a malformed utm_content literal in utm_tags_segment_filters.rst, and lowercased utm_medium=email inside example-URL code blocks.

Source: #712

[promptless-for-oss]

I noticed that some CI checks failed for this PR. I'm investigating whether the failures are caused by this suggestion. If they're unrelated or pre-existing, I'll leave this suggestion unchanged and create a separate suggestion if a standalone docs fix is needed.