docs: Split up extension publishing documentation (#62312) (cherry-pick to preview) (#62600)

Cherry-pick of #62312 to preview

----
While our extension ecosystem grows more and more, we simultaneously are
also enforcing more and more policies to have a better experience for
our users and ensure extensions meet a minimum standard. However, at the
same time, it has become increasingly difficult for extension authors to
keep track of what we enforce onto extensions and what specific rules
apply to their extension.

Thus, this PR splits out the publishing guidelines out of the
`Developing Extensions` page in an effort to make it easier to go
through our requirements and make it harder to miss those. This also
paves the way for more detailed publishing prerequisites, so that both
authors can more quickly see what applies to their extension as well as
reviewers having easier ways to point authors to what they are missing.

Release Notes:

- N/A

---------

Co-authored-by: Kirill Bulatov <mail4score@gmail.com>

Co-authored-by: Finn Evers <finn@zed.dev>
Co-authored-by: Kirill Bulatov <mail4score@gmail.com>

docs/book.toml

@@ -25,7 +25,7 @@ default-title = "Zed Code Editor Documentation"
 no-section-label = true
 preferred-dark-theme = "dark"
 additional-css = ["theme/page-toc.css", "theme/plugins.css", "theme/highlight.css", "theme/consent-banner.css"]
-additional-js  = ["theme/page-toc.js", "theme/plugins.js", "theme/c15t@2.0.0-rc.3.js", "theme/analytics.js"]
+additional-js  = ["redirects/legacy-fragment-redirects.js", "theme/page-toc.js", "theme/plugins.js", "theme/c15t@2.0.0-rc.3.js", "theme/analytics.js"]
 
 [output.zed-html.print]
 enable = false

docs/redirects/legacy-fragment-redirects.js

@@ -0,0 +1,37 @@
+(() => {
+  const legacyAnchors = {
+    "#extension-publishing-prerequisites": {
+      page: "publishing/prerequisites",
+    },
+    "#extension-license-requirements": {
+      page: "publishing/license-requirements",
+    },
+    "#forking-and-cloning-the-repo": {
+      page: "publishing/publishing-guide",
+      hash: "#forking-and-cloning-the-repo",
+    },
+    "#publishing-your-extension": {
+      page: "publishing/publishing-guide",
+    },
+    "#updating-an-extension": {
+      page: "publishing/publishing-guide",
+      hash: "#updating-an-extension",
+    },
+  };
+
+  const redirectLegacyAnchor = () => {
+    const destination = legacyAnchors[window.location.hash];
+    const pathMatch = window.location.pathname.match(
+      /^(.*\/extensions\/)developing-extensions(?:\.html)?\/?$/,
+    );
+    if (!destination || !pathMatch) return;
+
+    const destinationUrl = new URL(window.location.href);
+    destinationUrl.pathname = `${pathMatch[1]}${destination.page}.html`;
+    destinationUrl.hash = destination.hash ?? "";
+    window.location.replace(destinationUrl);
+  };
+
+  redirectLegacyAnchor();
+  window.addEventListener("hashchange", redirectLegacyAnchor);
+})();

docs/src/SUMMARY.md

@@ -191,6 +191,10 @@
 - [Overview](./extensions.md)
 - [Installing Extensions](./extensions/installing-extensions.md)
 - [Developing Extensions](./extensions/developing-extensions.md)
+- [Publishing Your Extension](./extensions/publishing/overview.md)
+  - [Publishing Prerequisites](./extensions/publishing/prerequisites.md)
+  - [License Requirements](./extensions/publishing/license-requirements.md)
+  - [Publishing Guide](./extensions/publishing/publishing-guide.md)
 - [Extension Capabilities](./extensions/capabilities.md)
 - [Language Extensions](./extensions/languages.md)
 - [Debugger Extensions](./extensions/debugger-extensions.md)

docs/src/extensions.md

@@ -16,3 +16,12 @@ Zed lets you add new functionality using user-defined extensions.
   - [Developing MCP Servers](./extensions/mcp-extensions.md)
   - [Developing Snippets](./extensions/snippets.md)
   - [Developing Themes](./extensions/themes.md)
+
+# Publishing your extension
+
+If you are considering to publish your extension, please have a look through our documentation to help you with that.
+
+- [Publishing Your Extension](./extensions/publishing/overview.md)
+  - [Publishing Prerequisites](./extensions/publishing/prerequisites.md)
+  - [License Requirements](./extensions/publishing/license-requirements.md)
+  - [Publishing Guide](./extensions/publishing/publishing-guide.md)

docs/src/extensions/developing-extensions.md

@@ -110,126 +110,3 @@ zed::register_extension!(MyExtension);
 ### Debugging your Rust extension
 
 `stdout`/`stderr` is forwarded directly to the Zed process. In order to see `println!`/`dbg!` output from your extension, you can start Zed in your terminal with a `--foreground` flag.
-
-## Forking and cloning the repo
-
-1. Fork the repo
-
-> **Note:** It is very helpful if you fork the `zed-industries/extensions` repo to a personal GitHub account instead of a GitHub organization, as this allows Zed staff to push any needed changes to your PR to expedite the publishing process.
-
-2. Clone the repo to your local machine
-
-```sh
-# Substitute the url of your fork here:
-# git clone https://github.com/zed-industries/extensions
-cd extensions
-git submodule init
-git submodule update
-```
-
-## Extension License Requirements
-
-As of October 1st, 2025, extension repositories must include a license.
-The following licenses are accepted:
-
-- [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0)
-- [BSD 2-Clause](https://opensource.org/license/bsd-2-clause)
-- [BSD 3-Clause](https://opensource.org/license/bsd-3-clause)
-- [CC BY 4.0](https://creativecommons.org/licenses/by/4.0)
-- [GNU GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html)
-- [GNU LGPLv3](https://www.gnu.org/licenses/lgpl-3.0.en.html)
-- [MIT](https://opensource.org/license/mit)
-- [Unlicense](https://unlicense.org)
-- [zlib](https://opensource.org/license/zlib)
-
-This allows us to distribute the resulting binary produced from your extension code to our users.
-Without a valid license, the pull request to add or update your extension in the following steps will fail CI.
-
-Your license file should be at the root of your extension repository. Any filename that has `LICENCE` or `LICENSE` as a prefix (case insensitive) will be inspected to ensure it matches one of the accepted licenses. See the [license validation source code](https://github.com/zed-industries/extensions/blob/main/src/lib/license.js).
-
-> This license requirement applies only to your extension code itself (the code that gets compiled into the extension binary).
-> It does not apply to any tools your extension may download or interact with, such as language servers or other external dependencies.
-> If your repository contains both extension code and other projects (like a language server), you are not required to relicense those other projects — only the extension code needs to be one of the aforementioned accepted licenses.
-
-## Extension Publishing Prerequisites
-
-Before publishing your extension, make sure that you have chosen a unique extension ID for your extension in the [extension manifest](#directory-structure-of-a-zed-extension).
-This will be the primary identifier for your extension and cannot be changed after your extension has been published.
-Also, ensure that you have filled out all the required fields in the manifest.
-
-Furthermore, please make sure that your extension fulfills the following preconditions before you move on to publishing your extension:
-
-- Extension IDs and names must not contain the words `zed`, `Zed` or `extension`, since they are all Zed extensions.
-- Your extension ID should provide some information on what your extension tries to accomplish. E.g. for themes, it should be suffixed with `-theme`, snippet extensions should be suffixed with `-snippets` and so on. An exception to that rule is an extension that provides support for languages or popular tooling that people would expect to find under that ID. You can take a look at the list of [existing extensions](https://github.com/zed-industries/extensions/blob/main/extensions.toml) to get a grasp on how this usually is enforced.
-- Your extension must only include the resources it requires to function and nothing else.
-  - See the [directory structure of a Zed extension](#directory-structure-of-a-zed-extension) and the [Rust and WebAssembly](#rust-and-webassembly) sections for more information.
-- Extensions must in no way attempt to read nor modify the environment outside of the environment designated to them by Zed. Should they need to read the environment, they should use methods as provided by the [Zed Rust Extension API](https://docs.rs/zed_extension_api/latest/zed_extension_api/) and may fall back to appropriate methods from the Rust standard library. Should they need changes to the environment, they must instead ask the user to perform these for them using an appropriate method within the context (e.g. provide information for doing so using the `ContextServerConfiguration` for context servers).
-  - Please make sure to have read the [Rust and WebAssembly section above](#rust-and-webassembly) for more information and help regarding this topic.
-- Extensions should provide something that is not yet available in the marketplace as opposed to fixing something that could be resolved within an existing extension. For example, if you find that an existing extension's support for a language server is not functioning properly, first try contributing a fix to the existing extension as opposed to submitting a new extension immediately.
-  - If you receive no response or reaction within the upstream repository within a reasonable amount of time, feel free to submit a pull request that aims to fix said issue. Please ensure that you provide your previous efforts within the pull request to the extensions repository for adding your extension. Zed maintainers will then decide on how to proceed on a case by case basis.
-- Extensions that intend to provide a language, debugger or MCP server must not ship the language server as part of the extension. Instead, the extension should either download the language server or check for the availability of the language server in the user's environment using the APIs as provided by the [Zed Rust Extension API](https://docs.rs/zed_extension_api/latest/zed_extension_api/).
-- Themes and icon themes should not be published as part of extensions that provide other features, e.g. language support. Instead, they should be published as a distinct extension. This also applies to themes and icon themes living in the same repository.
-
-Non-compliance with these rules will be raised during the publishing process by reviewers. If you fail to comply with the laid out guidelines, the publishing of your extension will either be delayed or rejected.
-
-## Publishing your extension
-
-> Prior to publishing your extension, you should have installed as well as tested it locally thoroughly. Furthermore, you should have read the [prerequisites above](#extension-publishing-prerequisites). Note that untested extension submissions where the extension is not functioning at all will be closed eagerly without further feedback.
-
-To publish an extension, open a PR to [the `zed-industries/extensions` repo](https://github.com/zed-industries/extensions).
-
-In your PR, do the following:
-
-1. Add your extension as a Git submodule within the `extensions/` directory under the `extensions/{extension-id}` path
-
-```sh
-git submodule add https://github.com/your-username/foobar-zed.git extensions/my-extension
-git add extensions/my-extension
-```
-
-> All extension submodules must use HTTPS URLs and not SSH URLS (`git@github.com`). Furthermore, your extension repository must be publicly available and the checked out submodule commit must be on a branch and thus not be a detached commit.
-
-2. Add a new entry to the top-level `extensions.toml` file containing your extension:
-
-```toml
-[my-extension]
-submodule = "extensions/my-extension"
-version = "0.0.1"
-```
-
-If your extension is in a subdirectory within the submodule, you can use the `path` field to point to where the extension resides:
-
-```toml
-[my-extension]
-submodule = "extensions-my-extension"
-path = "packages/zed"
-version = "0.0.1"
-```
-
-> Note that the [required extension license](#extension-license-requirements) must reside at the specified path, a license at the root of the repository will not work. However, you are free to symlink an existing license within the repository or choose an alternative license from the list of accepted licenses for the extension code.
-
-3. Run `pnpm sort-extensions` to ensure `extensions.toml` and `.gitmodules` are sorted
-
-Once your PR is merged, the extension will be packaged and published to the Zed extension registry.
-
-## Updating an extension
-
-To update an extension, open a PR to [the `zed-industries/extensions` repo](https://github.com/zed-industries/extensions).
-
-In your PR do the following:
-
-1. Update the extension's submodule to the commit of the new version. For this, you can run
-
-```sh
-# From the root of the repository:
-git submodule update --remote extensions/your-extension-name
-```
-
-to update your extension to the latest commit available in your remote repository.
-
-2. Update the `version` field for the extension in `extensions.toml`
-   - Make sure the `version` matches the one set in `extension.toml` at the particular commit.
-
-If you'd like to automate this process, there is a [community GitHub Action](https://github.com/huacnlee/zed-extension-action) you can use.
-
-> **Note:** If your extension repository has a different license, you'll need to update it to be one of the [accepted extension licenses](#extension-license-requirements) before publishing your update.

docs/src/extensions/publishing/license-requirements.md

@@ -0,0 +1,30 @@
+---
+title: Extension License Requirements
+description: "Understand the license requirements for publishing a Zed extension."
+---
+
+# Extension License Requirements {#extension-license-requirements}
+
+As of October 1st, 2025, extension repositories must include a license.
+The following licenses are accepted:
+
+- [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0)
+- [BSD 2-Clause](https://opensource.org/license/bsd-2-clause)
+- [BSD 3-Clause](https://opensource.org/license/bsd-3-clause)
+- [CC BY 4.0](https://creativecommons.org/licenses/by/4.0)
+- [GNU GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html)
+- [GNU LGPLv3](https://www.gnu.org/licenses/lgpl-3.0.en.html)
+- [MIT](https://opensource.org/license/mit)
+- [Unlicense](https://unlicense.org)
+- [zlib](https://opensource.org/license/zlib)
+
+This allows us to distribute the resulting binary produced from your extension code to our users.
+Without a valid license, the pull request to add or update your extension in the following steps will fail CI.
+
+Your license file should be at the root of your extension. If your extension is in a subdirectory within its repository, the license must reside within that subdirectory as well; a license at the repository root will not work. You may symlink an existing license into the extension directory or choose another accepted license for the extension code.
+
+Any filename that has `LICENCE` or `LICENSE` as a prefix (case insensitive) will be inspected to ensure it matches one of the accepted licenses. See the [license validation source code](https://github.com/zed-industries/extensions/blob/main/src/lib/license.js).
+
+> This license requirement applies only to your extension code itself (the code that gets compiled into the extension binary).
+> It does not apply to any tools your extension may download or interact with, such as language servers or other external dependencies.
+> If your repository contains both extension code and other projects (like a language server), you are not required to relicense those other projects — only the extension code needs to be one of the aforementioned accepted licenses.

docs/src/extensions/publishing/overview.md

@@ -0,0 +1,12 @@
+---
+title: Publishing Extensions
+description: "Publish extensions in the Zed Extension Gallery."
+---
+
+# Publishing Extensions {#publishing-extensions}
+
+To publish an extension:
+
+1. Review the [publishing prerequisites](./prerequisites.md) and ensure your extension is ready.
+2. Add an [accepted license](./license-requirements.md) to your extension.
+3. Follow the [publishing guide](./publishing-guide.md) to submit it to the Zed extensions repository.

docs/src/extensions/publishing/prerequisites.md

@@ -0,0 +1,27 @@
+---
+title: Extension Publishing Prerequisites
+description: "Review the requirements for publishing an extension to the Zed Extension Registry."
+---
+
+# Extension Publishing Prerequisites {#extension-publishing-prerequisites}
+
+Before publishing your extension, make sure that you have chosen a unique extension ID for your extension in the [extension manifest](../developing-extensions.md#directory-structure-of-a-zed-extension).
+This will be the primary identifier for your extension and cannot be changed after your extension has been published.
+Also, ensure that you have filled out all the required fields in the manifest.
+
+Furthermore, please make sure that your extension fulfills the following preconditions before you move on to publishing your extension:
+
+- Extension IDs and names must not contain the words `zed`, `Zed` or `extension`, since they are all Zed extensions.
+- Your extension ID should provide some information on what your extension tries to accomplish. E.g. for themes, it should be suffixed with `-theme`, snippet extensions should be suffixed with `-snippets` and so on. An exception to that rule is an extension that provides support for languages or popular tooling that people would expect to find under that ID. You can take a look at the list of [existing extensions](https://github.com/zed-industries/extensions/blob/main/extensions.toml) to get a grasp on how this usually is enforced.
+- Your extension must only include the resources it requires to function and nothing else.
+  - See the [directory structure of a Zed extension](../developing-extensions.md#directory-structure-of-a-zed-extension) and the [Rust and WebAssembly](../developing-extensions.md#rust-and-webassembly) sections for more information.
+- Extensions must in no way attempt to read nor modify the environment outside of the environment designated to them by Zed. Should they need to read the environment, they should use methods as provided by the [Zed Rust Extension API](https://docs.rs/zed_extension_api/latest/zed_extension_api/) and may fall back to appropriate methods from the Rust standard library. Should they need changes to the environment, they must instead ask the user to perform these for them using an appropriate method within the context (e.g. provide information for doing so using the `ContextServerConfiguration` for context servers).
+  - Please make sure to have read the [Rust and WebAssembly section](../developing-extensions.md#rust-and-webassembly) for more information and help regarding this topic.
+- Extensions should provide something that is not yet available in the marketplace as opposed to fixing something that could be resolved within an existing extension. For example, if you find that an existing extension's support for a language server is not functioning properly, first try contributing a fix to the existing extension as opposed to submitting a new extension immediately.
+  - If you receive no response or reaction within the upstream repository within a reasonable amount of time, feel free to submit a pull request that aims to fix said issue. Please ensure that you provide your previous efforts within the pull request to the extensions repository for adding your extension. Zed maintainers will then decide on how to proceed on a case by case basis.
+- Extensions that intend to provide a language, debugger or MCP server must not ship the language server as part of the extension. Instead, the extension should either download the language server or check for the availability of the language server in the user's environment using the APIs as provided by the [Zed Rust Extension API](https://docs.rs/zed_extension_api/latest/zed_extension_api/).
+- Themes and icon themes should not be published as part of extensions that provide other features, e.g. language support. Instead, they should be published as a distinct extension. This also applies to themes and icon themes living in the same repository.
+
+Furthermore, before publishing your extension, [install it locally as a dev extension](../developing-extensions.md#developing-an-extension-locally) and test it thoroughly. Submissions for extensions that have not been tested and do not function at all may be closed without further feedback.
+
+Non-compliance with these rules will be raised during the publishing process by reviewers. If you fail to comply with the laid out guidelines, the publishing of your extension will either be delayed or rejected.

docs/src/extensions/publishing/publishing-guide.md

@@ -0,0 +1,80 @@
+---
+title: Publishing Guide
+description: "Submit and update extensions in the Zed Extension Registry."
+---
+
+# Publishing Guide {#publishing-your-extension}
+
+> Before initiating the publishing process, read and ensure that your extension meets all [publishing prerequisites](./prerequisites.md) and [license requirements](./license-requirements.md). Only proceed with the steps below after satisfying these requirements. The publishing may be delayed or outright rejected otherwise.
+
+Follow each step carefully to help the publishing process go smoothly.
+
+## Forking and cloning the repo
+
+1. Fork the `zed-industries/extensions` repository.
+
+> **Note:** It is very helpful if you fork the `zed-industries/extensions` repo to a personal GitHub account instead of a GitHub organization, as this allows Zed staff to push any needed changes to your PR to expedite the publishing process.
+
+2. Clone the repo to your local machine
+
+```sh
+# Substitute the url of your fork here:
+# git clone https://github.com/zed-industries/extensions
+cd extensions
+git submodule init
+git submodule update
+```
+
+To publish an extension, open a PR to [the `zed-industries/extensions` repo](https://github.com/zed-industries/extensions).
+
+In your PR, do the following:
+
+1. Add your extension as a Git submodule within the `extensions/` directory under the `extensions/{extension-id}` path
+
+```sh
+git submodule add https://github.com/your-username/foobar-zed.git extensions/my-extension
+git add extensions/my-extension
+```
+
+> All extension submodules must use HTTPS URLs and not SSH URLS (`git@github.com`). Furthermore, your extension repository must be publicly available and the checked out submodule commit must be on a branch and thus not be a detached commit.
+
+2. Add a new entry to the top-level `extensions.toml` file containing your extension:
+
+```toml
+[my-extension]
+submodule = "extensions/my-extension"
+version = "0.0.1"
+```
+
+If your extension is in a subdirectory within the submodule, you can use the `path` field to point to where the extension resides:
+
+```toml
+[my-extension]
+submodule = "extensions/my-extension"
+path = "packages/zed"
+version = "0.0.1"
+```
+
+3. Run `pnpm sort-extensions` to ensure `extensions.toml` and `.gitmodules` are sorted
+
+Once your PR is merged, the extension will be packaged and published to the Zed extension registry.
+
+## Updating an extension {#updating-an-extension}
+
+To update an extension, open a PR to [the `zed-industries/extensions` repo](https://github.com/zed-industries/extensions).
+
+In your PR do the following:
+
+1. Update the extension's submodule to the commit of the new version. For this, you can run
+
+```sh
+# From the root of the repository:
+git submodule update --remote extensions/your-extension-name
+```
+
+to update your extension to the latest commit available in your remote repository.
+
+2. Update the `version` field for the extension in `extensions.toml`
+   - Make sure the `version` matches the one set in `extension.toml` at the particular commit.
+
+If you'd like to automate this process, there is a [community GitHub Action](https://github.com/huacnlee/zed-extension-action) you can use.