Compare Revisions
A guide to linking to support articles
Revision 281260:
Revision 281260 by lsiebert on
Revision 281958:
Revision 281958 by lsiebert on
Keywords:
Search results summary:
This article is a developer reference for linking to support articles.
This article is a developer reference for linking to support articles.
Content:
Linking to Mozilla Support articles is crucial for providing our users with direct access to the help they need. There are two primary ways to establish these links, and the method you choose depends on where you are linking from. This guide will walk you through both methods to ensure you can link effectively, helping users find the appropriate support content seamlessly.
__TOC__
=In-product links to SUMO=
For links placed within the browser interface of Firefox or Firefox for Android, you must use a specific URL structure. This structure enables the CX Content Team to adjust the link destination without disrupting functionality within Firefox. We've established specific targets for various topics, allowing us to direct users to the most relevant articles based on factors like their operating system or Firefox version. This flexibility means that updates or changes can be made directly in [https://wiki.mozilla.org/Support/Kitsune Kitsune], without the need for any modifications to Firefox's code.
Here's the format for creating in-product links to SUMO articles:
<code>
https://support.mozilla.<!-- -->org/1/firefox/%VERSION%/%OS%/%LOCALE%/TOPIC
</code>
{note} '''Note''': The <code>%VERSION%/%OS%/%LOCALE%/</code> sections are placeholders. Engineers are responsible for dynamically populating them in the source code.{/note}
Example:
<code>
https://support.mozilla.<!-- -->org/1/firefox/13.0a2/Darwin/en-US/prefs-privacy
</code>
In this structure:
*<code>%VERSION%</code> Refers to the Firefox version.
*<code>%OS%</code> Represents the operating system of the user.
*<code>%LOCALE%</code> Specifies the language and region settings of the user.
*<code>TOPIC</code> Denotes the subject of the support article, and it can be any text string.
For links specific to Firefox for Android, the URL should include <code>/1/mobile</code> in the URL to distinguish it from links intended for the desktop version.
{note}'''Note:''' When creating a SUMO placeholder to test an in-product link, the placeholder needs to be published and kept under ''administration'' in order for it to function properly. Once the content is finalized and ready to be published, the article should be moved out of administration to make it visible to end users.{/note}
{warning}The creation of in-product links must be coordinated through a [https://bugzilla.mozilla.org/enter_bug.cgi?product=support.mozilla.org&component=Knowledge+Base+Content Content Request Bugzilla] ticket, which will be managed by the CX Content Team. Please do not attempt to manually create these links on your own as they need to be set up in [https://wiki.mozilla.org/Support/Kitsune Kitsune] before they can function properly.{/warning}
=Web property links to SUMO=
When creating links from web properties external to Firefox, omit the locale part of the URL. This practice allows the SUMO system to automatically detect and direct the user to the appropriate language version of the article based on their browser settings.
So, for example, in order to link to the [[Update Firefox to the latest release]] article:
* '''Use''' <code>https://support.mozilla<!-- -->.org/kb/update-firefox-latest-release</code>
* '''Don't use''' <code>https://support.mozilla<!-- -->.org/en-US/kb/update-firefox-latest-release</code>
=Linking from somewhere else=
If you're not linking from Firefox or a website (maybe an app, product, email, etc.), you probably want to use the URL (without the locale string) and identify the source.
Example:
<code>https://support.mozilla<!-- -->.org/kb/update-firefox-latest-release?utm_source=nameofsource</code>
=Create an mzl<!-- -->.la shortened link=
Please, refer to [[How to generate mzl.la link]] to see how you can create an mzl.la shortened link.
=Questions?=
If you need to set up an in-product link, please fill a [https://bugzilla.mozilla.org/enter_bug.cgi?product=support.mozilla.org&component=Knowledge+Base+Content Content Request Bugzilla] ticket. For any inquiries, drop a line in this [https://support.mozilla.org/en-US/forums/contributors/716943?last=87470 support thread].
==Learn more==
*[[About the Knowledge Base]]
*[[Anatomy of a Knowledge Base article]]
Linking to Mozilla Support articles is crucial for providing our users with direct access to the help they need. There are two primary ways to establish these links, and the method you choose depends on where you are linking from. This guide will walk you through both methods to ensure you can link effectively, helping users find the appropriate support content seamlessly.
__TOC__
=In-product links to SUMO=
For links placed within the browser interface of Firefox or Firefox for Android, you must use a specific URL structure. This structure enables the CX Content Team to adjust the link destination without disrupting functionality within Firefox. We've established specific targets for various topics, allowing us to direct users to the most relevant articles based on factors like their operating system or Firefox version. This flexibility means that updates or changes can be made directly in [https://wiki.mozilla.org/Support/Kitsune Kitsune], without the need for any modifications to Firefox's code.
Here's the format for creating in-product links to SUMO articles:
<code>
https://support.mozilla.<!-- -->org/1/firefox/%VERSION%/%OS%/%LOCALE%/TOPIC
</code>
{note} '''Note''': The <code>%VERSION%/%OS%/%LOCALE%/</code> sections are placeholders. Engineers are responsible for dynamically populating them in the source code.{/note}
Example:
<code>
https://support.mozilla.<!-- -->org/1/firefox/13.0a2/Darwin/en-US/prefs-privacy
</code>
In this structure:
*<code>%VERSION%</code> Refers to the Firefox version.
*<code>%OS%</code> Represents the operating system of the user.
*<code>%LOCALE%</code> Specifies the language and region settings of the user.
*<code>TOPIC</code> Denotes the subject of the support article, and it can be any text string.
For links specific to Firefox for Android, the URL should include <code>/1/mobile</code> in the URL to distinguish it from links intended for the desktop version.
{note}'''Note:''' When creating a SUMO placeholder to test an in-product link, the placeholder needs to be published and kept under ''administration'' in order for it to function properly. Once the content is finalized and ready to be published, the article should be moved out of administration to make it visible to end users.{/note}
{warning}The creation of in-product links must be coordinated through a [https://bugzilla.mozilla.org/enter_bug.cgi?product=support.mozilla.org&component=Knowledge+Base+Content Content Request Bugzilla] ticket, which will be managed by the CX Content Team. Please do not attempt to manually create these links on your own as they need to be set up in [https://wiki.mozilla.org/Support/Kitsune Kitsune] before they can function properly.{/warning}
==Avoid redirects to anchors==
Redirects to specific anchors within articles are fragile and can break easily if the page structure changes. To prevent broken links, always link to the main article page instead. This ensures your links remain valid and users can access the necessary information regardless of updates to the article’s internal sections.
=Web property links to SUMO=
When creating links from web properties external to Firefox, omit the locale part of the URL. This practice allows the SUMO system to automatically detect and direct the user to the appropriate language version of the article based on their browser settings.
So, for example, in order to link to the [[Update Firefox to the latest release]] article:
* '''Use''' <code>https://support.mozilla<!-- -->.org/kb/update-firefox-latest-release</code>
* '''Don't use''' <code>https://support.mozilla<!-- -->.org/en-US/kb/update-firefox-latest-release</code>
=Linking from somewhere else=
If you're not linking from Firefox or a website (maybe an app, product, email, etc.), you probably want to use the URL (without the locale string) and identify the source.
Example:
<code>https://support.mozilla<!-- -->.org/kb/update-firefox-latest-release?utm_source=nameofsource</code>
=Create an mzl<!-- -->.la shortened link=
Please, refer to [[How to generate mzl.la link]] to see how you can create an mzl.la shortened link.
=Questions?=
If you need to set up an in-product link, please fill a [https://bugzilla.mozilla.org/enter_bug.cgi?product=support.mozilla.org&component=Knowledge+Base+Content Content Request Bugzilla] ticket. For any inquiries, drop a line in this [https://support.mozilla.org/en-US/forums/contributors/716943?last=87470 support thread].
==Learn more==
*[[About the Knowledge Base]]
*[[Anatomy of a Knowledge Base article]]