docs: document extension.manifest.json schema for CI/CD publishing

[CalvinAllen]

Summary

Add documentation covering the extension.manifest.json file, which is used by VsixPublisher for automated CI/CD publishing to the Visual Studio Marketplace.

Full Schema Reference

Schema URL: http://json.schemastore.org/vsix-publish

Required Fields

Field	Type	Description
categories	array	1-3 unique category values
identity	object	Extension identity (requires internalName subfield)
overview	string	Path to markdown file for marketplace page
publisher	string	Publisher identifier (not display name)

All Properties

assetFiles (array)

Additional assets to include in the marketplace package.

Subfield	Type	Required	Description
pathOnDisk	string	Yes	File path relative to JSON directory
targetPath	string	Yes	Embedded package path (defaults to empty)

categories (array)

Constraints: 1-3 items, unique values

Valid values:

• ajax, build, coding, connected services, data, database, documentation
• extension sdk, framework and libraries, lightswitch, modelling, office, other
• performance, programming languages, reporting, security, services
• setup and deployment, sharepoint, source control, testing, theme
• visual studio extensions, web, workflow

identity (object)

Subfield	Type	Constraints	Notes
internalName	string	1-63 chars, pattern ^[^\s-]+$	Required. Format: publisherName.internalName
displayName	string	1-80 chars	Required for non-VSIX extensions
description	string	1-280 chars	Required for non-VSIX extensions
icon	string	-	Required for non-VSIX; supports relative paths
version	string	Pattern ^([0-9]+\.){1,3}([0-9]+)$	Required for non-VSIX
vsixId	string	-	Extension identifier
language	string/number	-	CLR locale or LCID code
tags	array	Each tag 1-50 chars	Marketplace tags
installTargets	array	Min 1 item	Required for non-VSIX extensions

installTargets subfields:

• sku (enum): Target Visual Studio SKU
  • Microsoft.VisualStudio.Community
  • Microsoft.VisualStudio.Enterprise
  • Microsoft.VisualStudio.Pro
  • Microsoft.VisualStudio.Express variants
  • Microsoft.VisualStudio.VSLS
• version (string): Version range, pattern ^[0-9\[\(,. \)\]]+$

overview (string)

Path to markdown file displayed on the extension's marketplace page. Min 1 character.

priceCategory (string)

• Default: free
• Valid values: free, trial, paid

private (boolean)

• Default: false
• Controls whether extension is uploaded as private

publisher (string)

Publisher identifier. Must not be a display name. Min 1 character.

qna (boolean)

• Default: true
• Enables Q&A section on marketplace page

repo (string)

GitHub repository URL. Must be valid URI format.

---

Documentation Tasks

• Create new doc page for extension.manifest.json
• Document purpose and use case (CI/CD publishing with VsixPublisher)
• Include complete field reference (above)
• Add example files for common scenarios
• Document VsixPublisher CLI integration
• Add CI/CD workflow examples (GitHub Actions, Azure Pipelines)
• Note which fields come from VSIX vs need manual specification

Example (Minimal)

{
  "$schema": "http://json.schemastore.org/vsix-publish",
  "categories": ["coding"],
  "identity": {
    "internalName": "MyExtension"
  },
  "overview": "../README.md",
  "publisher": "MyPublisher"
}

Example (Full)

{
  "$schema": "http://json.schemastore.org/vsix-publish",
  "categories": ["coding", "programming languages"],
  "identity": {
    "internalName": "MyExtension",
    "tags": ["productivity", "tools"]
  },
  "overview": "../README.md",
  "publisher": "MyPublisher",
  "priceCategory": "free",
  "private": false,
  "qna": true,
  "repo": "https://github.com/MyPublisher/MyExtension"
}

[CalvinAllen]

Resolution Found

After testing, the marketplace repository link now appears. The fix required:

1. Adding <MoreInfo> element to source.extension.vsixmanifest
2. Changing www.github.com to github.com in extension.manifest.json

Important: Either the www. prefix breaks it, OR both files must have matching URLs. Document both requirements to be safe.

[CalvinAllen]

Confirmed: www. Prefix Breaks Marketplace Links

Testing on VS-SuperClean with matching URLs (both using www.github.com) confirmed the links still don't appear.

Conclusion: The www. prefix in the URL breaks the marketplace repository link, regardless of whether the URLs match between files.

Fix required: Use https://github.com/... (without www.) in both:

• extension.manifest.json repo field
• source.extension.vsixmanifest <MoreInfo> element

[CalvinAllen]

Final Results

Extension	extension.manifest.json repo	vsixmanifest <MoreInfo>	Link Shows?
ProjectRenamifier	github.com	github.com	✅ Yes
SuperClean	github.com	github.com	✅ Yes
SuperClean (earlier)	www.github.com	www.github.com	❌ No
OpenBinFolder	github.com	MISSING	✅ Yes
BreakpointNotifier	MISSING	github.com	❌ No

Conclusion

1. The repo field in extension.manifest.json controls the marketplace repository link
2. The <MoreInfo> element in vsixmanifest has NO effect on the marketplace link
3. The www. prefix breaks the link - must use github.com not www.github.com
4. <MoreInfo> is optional - not needed for the marketplace link to appear

Recommendation

For marketplace repository links to work:

• ✅ Use "repo": "https://github.com/..." in extension.manifest.json
• ✅ Do NOT use www.github.com
• ℹ️ <MoreInfo> in vsixmanifest is optional (doesn't affect marketplace)

[CalvinAllen]

Additional: in the vsixmanifest might only matter if you manually upload your extensions to the marketplace

[CalvinAllen]

vsixmanifest - manual uploading

publish manifest - automated uploading