P0021 url-tracking-params¶
Rule: A link in docs or a comment carries no tracking query parameter.
| Code | P0021 (stable, never reused) |
| Id | url-tracking-params |
| Category | prose |
| Source | spirit_level |
| Fix | by hand |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | off | |
| small-workspace | off | |
| medium | off | |
| big | off | |
| ai | warn |
a link pasted from a browser or a chat app carries an id that tells the reader nothing and goes stale |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
params |
list of strings | ["utm_", "?si=", "&si=", "fbclid=", "gclid=", "msclkid=", "igshid=", "mc_cid=", "mc_eid=", "yclid=", "ref_src=", "spm=", "_hsenc=", "_hsmi="] |
the tracking parameters, matched as substrings, case-insensitive |
files |
list of strings | ["**/*.md"] |
globs of the Markdown files checked, relative to the root |
skip |
list of strings | [] |
globs of Markdown files left out |
comments |
boolean | true |
also check Rust comments |
Why¶
A link pasted from a browser, a chat app or a social post carries a tracking query parameter: utm_source=, ?si=, fbclid=, and similar. It tells an outside service where the link was shared from; it tells the reader nothing, and the id goes stale.
Parameters match as substrings, case-insensitive, in the Markdown files of files and in Rust comments, including a link target ([text](url)): that is where a pasted link lives. A code span, a fenced block, a double quote or a curly quote still hides a mention: writing the parameter to explain it, as this page does, is not a use.
// see [the guide](https://example.com/docs?utm_source=newsletter) <- finding
// see [the guide](https://example.com/docs) <- passes
How to fix¶
Strip the tracking parameters from the URL before pasting it; keep the path and any parameter the page actually needs.
Configure¶
[lints.url-tracking-params]
level = "deny"
params = ["utm_", "?si=", "&si=", "fbclid=", "gclid=", "msclkid=", "igshid=", "mc_cid=", "mc_eid=", "yclid=", "ref_src=", "spm=", "_hsenc=", "_hsmi="]
files = ["**/*.md"]
skip = []
comments = true
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(url-tracking-params) <reason> (waivers); the code works there too, as in [lints.P0021].