Bug 1943050 user scripts API - move legacy content

[rebloor]

Description

Initial PR for addressing the documentation needs of Bug 1943050 Enable userScripts API by default. This PR moves the documentation for the userScript API available in Manifest V2 to a new _legacy folder and updates cross-references. Also, include appropriate updates to the user_script manifest key documentation.

Related issues and pull requests

Addition of related browser compatibility data in mdn/browser-compat-data#25857

[github-actions]

Preview URLs (10 pages)

• /en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts_legacy/RegisteredUserScript/unregister
• /en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts_legacy/RegisteredUserScript
• /en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts_legacy/UserScriptOptions
• /en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts_legacy/Working_with_userScripts
• /en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts_legacy/onBeforeScript
• /en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts_legacy/register
• /en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts_legacy
• /en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts
• /en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_contextual_identities
• /en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/user_scripts

Flaws (1)

Note! 9 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts
Title: userScripts
Flaw count: 1

• macros:
  • Macro produces link /en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts/onBeforeScript which is a redirect

External URLs (1)

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts_legacy/register
Title: userScripts.register() (Legacy)

• https://support.mozilla.org/en-US/kb/extensions-private-browsing (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2025-02-08 17:37:08)

[Rob--W]

The top-level userScripts page still exists. Did you intentionally keep it?

[rebloor]

The top-level userScripts page still exists. Did you intentionally keep it?

@Rob--W Yes. I saw this as a move of all the existing content so that if someone wanted it, they had the convenience of being able to find it from the sidebar menu. Also, there wouldn't be a convenient redirect for register, for example. If you would prefer to have this content hidden, then we can remove the top-level page, and the content wouldn't show in the sidebar. However, we should then add an index on each page we retain so readers can navigate between the legacy methods, types, and events, if they want to. Let me know your preference.

[Rob--W]

The top-level userScripts page still exists. Did you intentionally keep it?

@Rob--W Yes. I saw this as a move of all the existing content so that if someone wanted it, they had the convenience of being able to find it from the sidebar menu.

I think that we are talking about different things.

By top-level userScripts page still existing, I am referring to the fact that this PR kept the original content at https://pr37975.content.dev.mdn.mozit.cloud/en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts while the PR moved most of the other pages without keeping the original.

I don't mind keeping the original if it helps with the transition, especially if we are going to land the PRs shortly after each other.

I asked whether it was intentional to make sure that it was in fact intentional, and that you are not going to be surprised about the existing file when you write the new docs.

[rebloor]

@Rob--W I guess I'm still thinking of this as one atomic change, moving legacy content to a new folder and adding the new API content. So I don't expect to have any issues. Also, I wasn't sure if you would want to put a redirect in place temporarily if this PR was merged ahead of one for the new API content.

[dotproto]

Looks pretty good. Most of this review is just polish.

[dotproto]

Suggested change

	/en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts/RegisteredUserScript/RegisteredUserScript.unregister() /en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts_legacy/RegisteredUserScript/unregister
	/en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts/RegisteredUserScript/unregister /en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts_legacy/RegisteredUserScript/unregister

[rebloor]

@dotproto redirects are set automatically and we're specifically told not to edit them manually, see https://github.com/mdn/content/blob/main/CONTRIBUTING.md#moving-documents

[dotproto]

Is it possible (and a good idea) to move this block into a reusable fragment that we can include in each page? (I may have asked something like this before on a previous issue. If so, apologies for the repetition.)

[rebloor]

As far as I'm aware, banners have to be coded as a macro (https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Banners_and_notices). If there is another option, it's not obviously documented.

Even if the process was simple, as the banners here are static and will not be used ad hoc, the benefit of including a reusable fragment seemed limited.

[dotproto]

NOTE: This file was renamed to files/en-us/mozilla/add-ons/webextensions/api/userscripts_legacy/registereduserscript/unregister/index.md (included below).

[rebloor]

?

[dotproto]

Line 42 should be updated to add a space before the user_scripts link.

- - : An event available to the API script, registered in[`"user_scripts"`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/user_scripts), that execute before a user script executes. Use it to trigger the export of the additional APIs provided by the API script, so they are available to the user script.
+ - : An event available to the API script, registered in [`"user_scripts"`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/user_scripts), that execute before a user script executes. Use it to trigger the export of the additional APIs provided by the API script, so they are available to the user script.

[rebloor]

This line will go when the page is updated to add the new API docs.