Comparar edições

Use stable URLs instead of direct SUMO links in product UI to prevent broken links when articles change.

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. __TOC__ = 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: {note}<pre> https://support.mozilla.org/1/&lt;product&gt;/&lt;%VERSION%&gt;/&lt;%OS%&gt;/&lt;%LOCALE%&gt;/&lt;slug&gt; </pre>{/note} Notes: * <code>%VERSION%</code>, <code>%OS%</code>, and <code>%LOCALE%</code> are automatically populated by the product. * The SUMO team creates the <code>&lt;slug&gt;</code> and <code>&lt;product&gt;</code> fields. * Replace <code>&lt;slug&gt;</code> with the unique slug you create. This format ensures users are directed to the correct localized article. '''Example:'''<pre> https://support.mozilla.org/1/firefox/%VERSION%/%OS%/%LOCALE%/recommendations-firefox-new-tab </pre> = How to setup a stable, in-product link in Kitsune = To create a stable redirect, follow these steps in the Kitsune admin dashboard. {warning} You must be a Kitsune admin with the right permissions to create stable links.{/warning} # Sign in to the Kitsune admin dashboard. # Under '''INPRODUCT''', click '''Redirects'''. # Click {button Add Redirect} in the top-right corner. # Complete the required fields '''Product''', '''Topic''', and '''Target''', as described in the [[#redirect-fields|Redirect fields]] section below. # Click {button SAVE}. # Share the completed stable link with the engineer or product manager, using the in-product format: <pre> https://support.mozilla.org/1/firefox/%VERSION%/%OS%/%LOCALE%/&lt;slug&gt; </pre> = Redirect fields = {| ! Field !! Description |- | '''Product''' || Use <code>firefox</code> for desktop or <code>mobile</code> 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 (<code>-</code>) * Do <strong>not</strong> include special characters like <code>#</code>, underscores, or spaces * The slug should be simple and descriptive, like: <code>firefox-manage-account</code> {note}'''Note:''' The slug does <em>not</em> have to match the target article’s actual URL. Choose something meaningful and consistent for product usage.{/note} |- | '''Target''' || The path to the support article you want to redirect to. Only include the part from <code>kb/</code> onward. '''Example:''' <code>kb/firefox-lockwise-managing-account-data</code> {note}'''Note:''' You can include an anchor (e.g., <code>kb/customize-items-on-firefox-new-tab-page#w_weather</code>) to link to a specific section. Anchors only work in the English version and may not resolve in other locales.{/note} |} = 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