How to create an in-product, stable link

Revision Information
  • Revision id: 316608
  • Created:
  • Creator: Abby
  • Comment: New article to clarify in product link creation process
  • Reviewed: No
  • Ready for localization: No
Revision Source
Revision Content

When engineers or product managers link to a SUMO support article from inside a product (like Firefox), they should always use a stable URL, not the direct article link. Direct links change when the article title or slug is updated, which can break in-product links. Stable links protect against this and ensure users always reach the right page.

This article explains why stable links matter, how to format them for different platforms, and how to set one up using the Kitsune dashboard.

Why stable links matter

Using direct links to support articles (like https://support.mozilla.org/en-US/kb/example-article) can lead to problems:

  • They break easily: Article URLs change if the title changes unless the editor manually preserves the slug.
  • They’re not localizable: Direct links hardcode a language, which isn’t ideal for international users.
  • They’re harder to manage: We can't update them globally if used directly in the product.

By contrast, stable links:

  • Stay consistent, even if the article URL changes
  • Automatically detect the correct locale
  • Can be redirected or updated centrally if needed

Link format for in-product support articles

Use a standardized format to construct stable support links for desktop and mobile products: 

https://support.mozilla.org/1/<product>/<version>/<os>/<locale>/<slug>

Notes:

  • %VERSION%, %OS%, and %LOCALE% are automatically populated by the product.
  • Replace <slug> with the unique slug you create.

This format ensures users are directed to the correct localized article.

Example:
https://support.mozilla.org/1/firefox/%VERSION%/%OS%/%LOCALE%/recommendations-firefox-new-tab

How to setup a stable, in-product link in Kitsune

To create a stable redirect, follow these steps in the Kitsune admin dashboard.

You must be a Kitsune admin with the right permissions to create stable links.
  1. Sign in to the Kitsune admin dashboard.
  2. Under INPRODUCT, click Redirects.
  3. Click Add Redirect in the top-right corner.
  4. Complete the required fields Product, Topic, and Target, as described in the Redirect fields section below.
  5. Click SAVE.
  6. Share the completed stable link with the engineer or product manager, using the in-product format: 
https://support.mozilla.org/1/firefox/%VERSION%/%OS%/%LOCALE%/<slug>

Redirect fields

Field Description
Product Use firefox for desktop or mobile for Firefox mobile products.
Topic (slug)

Enter a short, unique identifier for the article. This becomes part of the stable link.

  • New article? Create a new slug.
  • Existing article? Use the article’s current slug if appropriate.
  • Use only lowercase letters (a–z) and dashes (-)
  • Do not include special characters like #, underscores, or spaces
  • The slug should be simple and descriptive, like: firefox-manage-account
Note:The slug does not have to match the target article’s actual URL. Choose something meaningful and consistent for product usage.
Target

The path to the support article you want to redirect to. Only include the part from kb/ onward.

Example: kb/firefox-lockwise-managing-account-data

Note: You can include an anchor (e.g., kb/customize-items-on-firefox-new-tab-page#w_weather) to link to a specific section. Anchors only work in the English version and may not resolve in other locales.

Tips

  • Stable links ensure localization: users will be automatically redirected to their preferred language when available.
  • You can update or delete stable redirects later via the Kitsune admin interface.
  • Use this method any time you're linking from:
    • “Learn more” in-product messages
    • Onboarding flows
    • Error or warning messages
    • Contextual help modals