diff --git a/data/nav.yml b/data/nav.yml
index 39169df12a..e2902b65f1 100644
--- a/data/nav.yml
+++ b/data/nav.yml
@@ -487,6 +487,8 @@
- name: "Package ecosystems"
start_expanded: true
children:
+ - name: "Overview"
+ path: "packages/ecosystems"
- name: "Alpine"
path: "packages/alpine"
- name: "Container"
diff --git a/pages/apis/rest_api/packages/packages.md b/pages/apis/rest_api/packages/packages.md
index 517cc20de6..95d0666c2b 100644
--- a/pages/apis/rest_api/packages/packages.md
+++ b/pages/apis/rest_api/packages/packages.md
@@ -4,13 +4,34 @@ The packages API endpoint lets you create and manage packages in a registry.
## Publish a package
+The following type of `curl` syntax for publishing to registries will work across [all package ecosystems supported by Buildkite Packages](/docs/packages/ecosystems), with the `file` form-field modified accordingly.
+
```bash
curl -H "Authorization: Bearer $TOKEN" \
-X POST "https://api.buildkite.com/v2/packages/organizations/{org.slug}/registries/{registry.slug}/packages" \
- -H "Content-Type: application/json" \
- -F 'file=@path/to/ruby/gem/banana-1.0.0.gem'
+ -F 'file=@path/to/debian/package/banana_1.1-2_amd64.deb
```
+However, this type of REST API call is just recommended for:
+
+- [Alpine (apk)](/docs/packages/alpine#publish-a-package) packages
+- [Debian/Ubuntu (deb)](/docs/packages/debian#publish-a-package) packages
+- [Files (generic)](/docs/packages/files#publish-a-file)
+- [Helm (Standard)](/docs/packages/helm#publish-a-chart) charts
+- [Python (PyPI)](/docs/packages/python#publish-a-package) packages
+- [Red Hat (RPM)](/docs/packages/red-hat#publish-a-package) packages
+- [Terraform](/docs/packages/terraform#publish-a-module) modules
+
+For other supported package ecosystems, it is recommended that you use their native tools to publish to registries in your Buildkite Packages organization. These ecosystems' native tools are for:
+
+- [Container (Docker)](/docs/packages/container#publish-an-image) images
+- [Helm (OCI)](/docs/packages/helm-oci#publish-a-chart) charts
+- Java ([Maven](/docs/packages/maven#publish-a-package) or [Gradle leveraging the Maven Publish Plugin](/docs/packages/gradle#publish-a-package)) packages
+- [JavaScript (npm)](/docs/packages/javascript#publish-a-package) packages
+- [Ruby (RubyGems)](/docs/packages/ruby#publish-a-package) packages
+
+The following type of response is returned by Buildkite upon a successful `curl` publishing event.
+
```json
{
"id": "0191e23a-4bc8-7683-bfa4-5f73bc9b7c44",
@@ -37,7 +58,7 @@ Required request form-field content:
- file | Path to the package. Example: "file=@path/to/ruby/gem/banana-1.0.0.gem" . |
+ file | Path to the package. Example: "file=@path/to/debian/package/banana_1.1-2_amd64.deb" . |
diff --git a/pages/packages/_supported_package_ecosystems.md b/pages/packages/_supported_package_ecosystems.md
new file mode 100644
index 0000000000..fac0a90ae1
--- /dev/null
+++ b/pages/packages/_supported_package_ecosystems.md
@@ -0,0 +1,11 @@
+- [Alpine (apk)](/docs/packages/alpine)
+- [Container (Docker)](/docs/packages/container) images
+- [Debian/Ubuntu (deb)](/docs/packages/debian)
+- [Files (generic)](/docs/packages/files)
+- Helm ([OCI](/docs/packages/helm-oci) or [Standard](/docs/packages/helm))
+- Java ([Maven](/docs/packages/maven) or [Gradle leveraging the Maven Publish Plugin](/docs/packages/gradle))
+- [JavaScript (npm)](/docs/packages/javascript)
+- [Python (PyPI)](/docs/packages/python)
+- [Red Hat (RPM)](/docs/packages/red-hat)
+- [Ruby (RubyGems)](/docs/packages/ruby)
+- [Terraform](/docs/packages/terraform) modules
diff --git a/pages/packages/ecosystems.md b/pages/packages/ecosystems.md
new file mode 100644
index 0000000000..a2197c1ffd
--- /dev/null
+++ b/pages/packages/ecosystems.md
@@ -0,0 +1,5 @@
+# Package ecosystems overview
+
+Buildkite Packages supports the following language and package ecosystems:
+
+<%= render_markdown partial: 'packages/supported_package_ecosystems' %>
diff --git a/pages/packages/helm.md b/pages/packages/helm.md
index 75f59fa901..1a574e2cff 100644
--- a/pages/packages/helm.md
+++ b/pages/packages/helm.md
@@ -18,7 +18,7 @@ This command provides:
- The API access token required to publish packages to your Helm registry.
- The Helm package (`.tgz`) to be published.
-## Publishing a chart
+## Publish a chart
The following `curl` command (which you'll need to modify as required before submitting) describes the process above to publish a Helm chart to your Helm registry:
diff --git a/pages/packages/helm_oci.md b/pages/packages/helm_oci.md
index a35541d855..383ad253cc 100644
--- a/pages/packages/helm_oci.md
+++ b/pages/packages/helm_oci.md
@@ -15,7 +15,7 @@ These Helm commands are used to:
- Log in to your Buildkite Helm OCI registry with an API access token.
- Publish a Helm chart to your registry.
-## Publishing a chart
+## Publish a chart
The following steps describe the process above:
diff --git a/pages/packages/manage_registries.md b/pages/packages/manage_registries.md
index 29c682dde2..02f9ad8e78 100644
--- a/pages/packages/manage_registries.md
+++ b/pages/packages/manage_registries.md
@@ -25,17 +25,7 @@ To create a new registry:
Once a [registry is created](#create-a-registry), packages can then be uploaded to it. Learn more about how to manage packages for your registry's relevant language and package ecosystem:
-- [Alpine (apk)](/docs/packages/alpine)
-- [Container (Docker)](/docs/packages/container) images
-- [Debian/Ubuntu (deb)](/docs/packages/debian)
-- [Files (generic)](/docs/packages/files)
-- Helm ([OCI](/docs/packages/helm-oci) or [Standard](/docs/packages/helm))
-- Java ([Maven](/docs/packages/maven) or [Gradle leveraging the Maven Publish Plugin](/docs/packages/gradle))
-- [JavaScript (npm)](/docs/packages/javascript)
-- [Python (PyPI)](/docs/packages/python)
-- [Red Hat (RPM)](/docs/packages/red-hat)
-- [Ruby (RubyGems)](/docs/packages/ruby)
-- [Terraform](/docs/packages/terraform) modules
+<%= render_markdown partial: 'packages/supported_package_ecosystems' %>
## Update a registry