Support extensions pulling README content from an alternate file

[InsertCreativityHere]

I've run into a similar issue to as #210 and #722, where I'm using a single README file for 2 different purposes:

• what gets displayed in the VSCode Marketplace
• as a guide for developers/contributors to read

For example, it's weird to read build instructions in the marketplace, but useful to mention for developers on GitHub.

---

I understand that this must be limited in scope to avoid sweeping changes being necessary, so I propose the following:
A new option named "readmePath" is added to command line, and/or the package.json manifest.
When set, it copies the specified file into the package and renames it to "README", overriding any file already having that name.

This way no updates would be required to the marketplace, it still pulls from README just like it always has.
But it gives extension developers to flexibility to pull what gets displayed in the marketplace from another file.

---

I'm totally fine opening a PR to add this functionality! I just wanted to gauge if this proposal was okay before I potentially wasted any time implementing it.

[lars-reimann]

I'd like this for the CHANGELOG as well. I'm using MkDocs to build a documentation site and want to include the CHANGELOG there. This requires that the CHANGELOG is inside some folder like docs. vsce on the other hand, requires the file to be next to package.json. For now, I have to duplicate the CHANGELOG so both tools are happy.

[hyangah]

Thanks @joaomoreno.
Is there any restriction in what file path can be passed to --readme-path?

We recently reorganized our repo structure and README.md file is in the parent directory of package.json.
I hoped this feature helped us, but it doesn't seem to work as I expected.

$ npx vsce --version
2.22.1-2
$ ls -al ../README.md
-rw-r--r--  1 user group  11043 Jan 18 11:26 ../README.md
$ npx vsce package --readme-path=../README.md
Executing prepublish script 'npm run vscode:prepublish'...
...
 DONE  Packaged: /Users/hakim/projects/vscode-go/extension/go-nightly-2024.1.1811.vsix (34 files, 616.57KB)
$ unzip -l go-nightly-2024.1.1811.vsix  | grep README
$

[joaomoreno]

It needs to be inside the extension folder. Just add a cp ../README.md . to your prepublish script.

[TylerLeonhardt]

@joaomoreno am I doing something wrong?

My extension structure:

• README.md
• package.json
• CHANGELOG.md
• folder/README.md
• folder/CHANGELOG.md

I run:

vsce package --readme-path ./folder/README.md --changelog-path ./folder/CHANGELOG.md

that runs ok but when I crack open the VSIX:

1. the README.md & CHANGELOG.md in the root of the extracted extension are not the new versions
2. the extension.vsixmanifest does not mention the new paths
3. the package.json doesn't mention it either

I'm not sure where I should expect a change, but I can't seem to find one if it has been done.

[joaomoreno]

This only affects the files for displaying in the Marketplace. This means:

1. There is no copying around of files. The feature is not supposed to copy over the files to the root.
2. Here are relevant assertions: 916fd91#diff-d9bfb150d1cad6a99ad25f02ef84a4250a30fe1fe71757a63f4a47f4c0d0d386R690-R695.
3. package.json should not be affected at all.

[joaomoreno]

Also, I hadn't published vsce with the changes. :D That explains it. 😆

🚀 Just published @vscode/[email protected].

To verify, confirm the Microsoft.VisualStudio.Services.Content.Details points to the path provided by --readme-path.

➜  git git:(main) ✗ unzip -p git-1.0.0.vsix extension.vsixmanifest | grep Microsoft.VisualStudio.Services.Content.Details
			<Asset Type="Microsoft.VisualStudio.Services.Content.Details" Path="extension/resources/README.md" Addressable="true" />

[seanpoulter]

If I understand this correctly:

This only affects the files for displaying in the Marketplace.

If you install a local extension using Install from VSIX...* then we should not expect the README to be displayed. Right? 🤦