Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

docs: publish extension publishing guide on the docs site (#5163)

Manfred Riem7f45114c5d45
diff --git a/.github/ISSUE_TEMPLATE/extension_submission.yml b/.github/ISSUE_TEMPLATE/extension_submission.yml
index da7bf12a8..4b9f812fd 100644
--- a/.github/ISSUE_TEMPLATE/extension_submission.yml
+++ b/.github/ISSUE_TEMPLATE/extension_submission.yml
@@ -9,7 +9,7 @@ body:
Thanks for contributing an extension! This template helps you submit your extension to the community catalog.
**Before submitting:**
- - Review the [Extension Publishing Guide](https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-PUBLISHING-GUIDE.md)
+ - Review the [Extension Publishing Guide](https://github.github.com/spec-kit/extensions/publishing.html)
- Ensure your extension has a valid `extension.yml` manifest
- Create a GitHub release with a version tag (e.g., v1.0.0)
- Test installation: `specify extension add <extension-name> --from <your-release-url>`
diff --git a/.github/skills/add-community-extension/SKILL.md b/.github/skills/add-community-extension/SKILL.md
index 179c11b3e..69fcce8e5 100644
--- a/.github/skills/add-community-extension/SKILL.md
+++ b/.github/skills/add-community-extension/SKILL.md
@@ -27,7 +27,7 @@ Read the GitHub issue to extract all metadata:
### 2. Validate against publishing rules
-Check **all** of the following (per `extensions/EXTENSION-PUBLISHING-GUIDE.md`):
+Check **all** of the following (per `docs/extensions/publishing.md`):
| Check | How |
|-------|-----|
diff --git a/docs/README.md b/docs/README.md
index 2a6f10989..4bd3657d1 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -33,6 +33,7 @@ To build the documentation locally:
- `guides/assessment.md` - Idea assessment walkthrough
- `guides/customization.md` - Choosing and combining customization building blocks
- `reference/catalogs.md` - Catalog discovery, trust, private sources, and precedence
+- `extensions/publishing.md` - Extension publishing and catalog submission guide
- `integrations/index.md` - Integration directory and shared setup guidance
- `integrations/cli.md` - Shared integration management CLI reference
- `integrations/<key>.md` - Agent-specific setup, invocation, options, and limitations
diff --git a/docs/community/extensions.md b/docs/community/extensions.md
index 8fd04eb7b..24ef61ab9 100644
--- a/docs/community/extensions.md
+++ b/docs/community/extensions.md
@@ -211,4 +211,4 @@ The following community-contributed extensions are available in [`catalog.commun
| Worktree Isolation | Spawn isolated git worktrees for parallel feature development without checkout switching | `process` | Read+Write | [spec-kit-worktree](https://github.com/Quratulain-bilal/spec-kit-worktree) |
| Worktrees | Default-on worktree isolation for parallel agents β€” sibling or nested layout | `process` | Read+Write | [spec-kit-worktree-parallel](https://github.com/dango85/spec-kit-worktree-parallel) |
-To submit your own extension, see the [Extension Publishing Guide](https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-PUBLISHING-GUIDE.md).
+To submit your own extension, see the [Extension Publishing Guide](../extensions/publishing.md).
diff --git a/docs/community/overview.md b/docs/community/overview.md
index 6ba99a266..e098c6f97 100644
--- a/docs/community/overview.md
+++ b/docs/community/overview.md
@@ -50,7 +50,7 @@ Community projects that extend, visualize, or build on Spec Kit β€” including VS
## Contribute a component
To publish your own work, follow the
-[Extension Publishing Guide](https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-PUBLISHING-GUIDE.md),
+[Extension Publishing Guide](../extensions/publishing.md),
the [Presets Publishing Guide](https://github.com/github/spec-kit/blob/main/presets/PUBLISHING.md),
the [Community Bundles guide](bundles.md), or the
[Community Workflow Step Types guide](workflow-steps.md). For help choosing a
diff --git a/docs/docfx.json b/docs/docfx.json
index 69e0078e6..4adc745b3 100644
--- a/docs/docfx.json
+++ b/docs/docfx.json
@@ -7,6 +7,7 @@
"toc.yml",
"community/*.md",
"concepts/*.md",
+ "extensions/*.md",
"guides/*.md",
"integrations/*.md",
"reference/*.md",
diff --git a/extensions/EXTENSION-PUBLISHING-GUIDE.md b/docs/extensions/publishing.md
similarity index 96%
rename from extensions/EXTENSION-PUBLISHING-GUIDE.md
rename to docs/extensions/publishing.md
index 72562f3ad..8a453812b 100644
--- a/extensions/EXTENSION-PUBLISHING-GUIDE.md
+++ b/docs/extensions/publishing.md
@@ -130,7 +130,7 @@ specify extension add <extension-name> --from https://github.com/your-org/spec-k
### Understanding the Catalogs
-Spec Kit uses a dual-catalog system. For details about how catalogs work, see the main [Extensions README](README.md#extension-catalogs).
+Spec Kit uses a dual-catalog system. For details about how catalogs work, see the main [Extensions README](https://github.com/github/spec-kit/blob/main/extensions/README.md#extension-catalogs).
**For extension publishing**: All community extensions are listed in `extensions/catalog.community.json`. Users browse this catalog and copy extensions they trust into their own `catalog.json`.
@@ -147,7 +147,7 @@ To submit your extension to the community catalog, file a new issue using the **
- Testing confirmation
> [!IMPORTANT]
-> Do **not** open a pull request directly to edit `extensions/catalog.community.json`. All community extension submissions must go through the issue template so a maintainer can review the entry and update the catalog.
+> Do **not** open a pull request directly to edit `extensions/catalog.community.json`. All community extension submissions must go through the issue template. Submissions that do not use the issue template will be closed, and you will be asked to resubmit using it.
### What Happens After You Submit
@@ -303,7 +303,7 @@ A: Extensions should be free and open-source. Commercial support/services are al
- **Catalog Issues**: <https://github.com/statsperform/spec-kit/issues>
- **Extension Template**: <https://github.com/statsperform/spec-kit-extension-template> (coming soon)
-- **Development Guide**: See EXTENSION-DEVELOPMENT-GUIDE.md
+- **Development Guide**: See the [Extension Development Guide](https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-DEVELOPMENT-GUIDE.md)
- **Community**: Discussions and Q&A
---
diff --git a/docs/reference/catalogs.md b/docs/reference/catalogs.md
index fc48aeb3c..7299e6851 100644
--- a/docs/reference/catalogs.md
+++ b/docs/reference/catalogs.md
@@ -139,7 +139,7 @@ Use the component-specific publishing guidance when authoring catalog entries:
| Component type | Publishing guidance |
| --- | --- |
| Integrations | [Integration catalog contributions](../integrations/contributing.md) |
-| Extensions | [Extension Publishing Guide](https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-PUBLISHING-GUIDE.md) |
+| Extensions | [Extension Publishing Guide](../extensions/publishing.md) |
| Presets | [Preset Publishing Guide](https://github.com/github/spec-kit/blob/main/presets/PUBLISHING.md) |
| Workflows | [Workflow Publishing Guide](https://github.com/github/spec-kit/blob/main/workflows/PUBLISHING.md) |
| Workflow steps | [Community workflow step types](../community/workflow-steps.md) |
diff --git a/docs/toc.yml b/docs/toc.yml
index 31c89f033..31a64b61d 100644
--- a/docs/toc.yml
+++ b/docs/toc.yml
@@ -199,6 +199,8 @@
href: community/overview.md
- name: Extensions
href: community/extensions.md
+ - name: Publishing Extensions
+ href: extensions/publishing.md
- name: Presets
href: community/presets.md
- name: Bundles
diff --git a/extensions/EXTENSION-DEVELOPMENT-GUIDE.md b/extensions/EXTENSION-DEVELOPMENT-GUIDE.md
index a263a7bbf..fb06f7230 100644
--- a/extensions/EXTENSION-DEVELOPMENT-GUIDE.md
+++ b/extensions/EXTENSION-DEVELOPMENT-GUIDE.md
@@ -603,7 +603,7 @@ Submit to the community catalog for public discovery:
- Users copy the entry to their own `catalog.json`
- Users install with: `specify extension add my-ext` (from their catalog)
-See the [Extension Publishing Guide](EXTENSION-PUBLISHING-GUIDE.md) for detailed submission instructions.
+See the [Extension Publishing Guide](https://github.github.com/spec-kit/extensions/publishing.html) for detailed submission instructions.
---
diff --git a/extensions/EXTENSION-USER-GUIDE.md b/extensions/EXTENSION-USER-GUIDE.md
index 04b5e1edc..1561b3c9f 100644
--- a/extensions/EXTENSION-USER-GUIDE.md
+++ b/extensions/EXTENSION-USER-GUIDE.md
@@ -1022,7 +1022,7 @@ After creating tasks, sync to Jira:
- **Extension Issues**: Report to extension repository (see `specify extension info`)
- **Spec Kit Issues**: <https://github.com/statsperform/spec-kit/issues>
- **Extension Catalog**: <https://github.com/statsperform/spec-kit/tree/main/extensions>
-- **Documentation**: See EXTENSION-DEVELOPMENT-GUIDE.md and EXTENSION-PUBLISHING-GUIDE.md
+- **Documentation**: See EXTENSION-DEVELOPMENT-GUIDE.md and the [Extension Publishing Guide](https://github.github.com/spec-kit/extensions/publishing.html)
---
diff --git a/extensions/README.md b/extensions/README.md
index ca39feedc..70156a8fc 100644
--- a/extensions/README.md
+++ b/extensions/README.md
@@ -92,7 +92,7 @@ To add your extension to the community catalog:
3. **File an issue** using the [Extension Submission](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml) template with all required metadata
4. **Wait for review** β€” a maintainer will review the submission, update the catalog, and close the issue
-See the [Extension Publishing Guide](EXTENSION-PUBLISHING-GUIDE.md) for detailed step-by-step instructions.
+See the [Extension Publishing Guide](https://github.github.com/spec-kit/extensions/publishing.html) for detailed step-by-step instructions.
### Submission Checklist
diff --git a/extensions/template/README.md b/extensions/template/README.md
index 1f88d9ce4..8b4274aa4 100644
--- a/extensions/template/README.md
+++ b/extensions/template/README.md
@@ -38,7 +38,7 @@ Starter template for creating a Spec Kit extension.
7. **Publish** (optional):
- Create GitHub repository
- Create release
- - Submit to catalog (see EXTENSION-PUBLISHING-GUIDE.md)
+ - Submit to catalog (see the [Extension Publishing Guide](https://github.github.com/spec-kit/extensions/publishing.html))
## Files in This Template
@@ -69,7 +69,7 @@ Starter template for creating a Spec Kit extension.
- **Development Guide**: See EXTENSION-DEVELOPMENT-GUIDE.md
- **API Reference**: See EXTENSION-API-REFERENCE.md
-- **Publishing Guide**: See EXTENSION-PUBLISHING-GUIDE.md
+- **Publishing Guide**: See the [Extension Publishing Guide](https://github.github.com/spec-kit/extensions/publishing.html)
- **User Guide**: See EXTENSION-USER-GUIDE.md
## Template Version