Skip to main content

Documentation URL conventions

A documentation URL is a promise. From the first rule on, every finding SQLens reports can carry a link to the page that explains it, and a link that a shipped finding already carries can never be changed without breaking that finding in the field. So the shape of these URLs is fixed here, before the first page is written, as a rule rather than a list of examples.

The rule​

Every documentation page has exactly one canonical URL, built this way:

  • Lowercase. a–z, 0–9, and hyphens only.
  • Hyphen-separated. Words in a path segment are joined with -, never underscores, spaces, or camelCase.
  • No file extension. /deploy-gate, never /deploy-gate.html or /deploy-gate.md.
  • No trailing slash on a leaf page; the canonical form is the one without it.
  • No language segment in a technical path. The documentation is English; a path is /rules/..., never /en/rules/.... Localized content, if it ever exists, is negotiated by content, not baked into the canonical path.
  • One canonical URL per page. Where more than one address could reach a page (a moved page, an alternate spelling), every non-canonical address redirects to the canonical one. Duplicates that both return 200 are not allowed — they split search ranking and make "the" URL ambiguous.

What this does not define​

The rule documentation URL scheme — the exact address a given rule id maps to — is defined once, together with the rule catalog, so a rule and its page cannot drift. This page is the frame that scheme fits into; it does not restate it. Whatever that scheme is, it obeys the rule above: lowercase, hyphenated, extensionless, one canonical address per rule.