README.md (markdown description) support for NuGet packages

[dazinator]

Details about Problem

When uploading a package to nuget.org manually via the website, I can set a documentation URL that points to a readme file on github, as shown here: https://www.nuget.org/packages/DotNet.Glob/2.0.2

How do I this via a nuspec file, as I use CI / CD to publish my packages and so I don't want this to be a manual step. Is there some attribute in the nuspec for this?

I couldn't see anything obvious here: https://docs.microsoft.com/en-us/nuget/reference/nuspec

[PatoBeltran]

@rohit21agrawal is there any way to specify this when pushing on command line?

[rohit21agrawal]

No this is a NuGet.org only feature

[karann-msft]

@dazinator working on a feature that will improve this experience. Will announce it through the announcements repo when the sepc draft is ready.

[karann-msft]

Here is the spec - https://github.com/NuGet/Home/wiki/Packaging-Documentation-within-the-nupkg

[markusschaber]

The current spec talks about "path to the icon file in the package" - I guess that's a typo and it should refer to the documentation file... :-)

[vbfox]

Having the markdown option support a very different subset of markdown from what other tools are doing (github, npmjs.com, crates.io, ... all more or less supporting GFM) is a little weird.

[karann-msft]

@markusshaber that's right :) fixed it in the spec.

[infin8x]

@karann-msft this is exciting!

Would you consider using 'readme.md' as the default file name instead of 'documentation.md'? The readme name is commonly used across Git repos and other package types like npm - would be great to encourage that same convention in NuGet.

[karann-msft]

@alexmullans you can name it anything you like since the file name must be specified in the nuspec.
NuGet.org will look for a file with the name, and at the path specified in the target attribute of the documentation element.
<documentation target="filename.md"/> here it would look for a file named filename.md at the package root.

[infin8x]

Yep, that totally makes sense, thanks. My point remains though, it'd be great if the help text were:
<!-- e.g. <documentation src="readme.md"/>. Learn more at https://aka.ms/nugetPackageDocumentation--> <documentation src=""/>

Many people will have README.md files in the root of their repo already, and this small change would make it clear that it's easy to make that README part of the NuGet package just by updating the tag.

[mungojam]

@alexmullans I guess for most packages, they will want different things in their main Readme.md at the repo root than they want in their documentation. The repo root one usually has a focus on how to build and contribute to the package rather than how to use it (though I wish that both were easily accessible)

[infin8x]

That's totally fair. I'm coming from an npm background, where the README.md is just included by convention in the package (so a lot of popular projects seem to cover both the "use" and the "build and contribute" content in the README). Some examples: express, lodash. I'd also aruge that the CONTRIBUTING.md is the right convention place for the "build and test" guidance.

[karann-msft]

Thanks for the feedback @alexmullans. We'll clarify that in the docs. Note that this text will get generated only when you run nuget spec.

[ffMathy]

I agree with @alexmullans in regards to that it should default to README.md, since that is what NPM does and what people would expect. It is also what GitHub looks for per default - even TFS!

The point @mungojam is making could also be applied to the opposite scenario. Why can't they just opt out of the "README.md" and explicitly specify "Documentation.md"?

[ffMathy]

Also, are there any updates on this? How long does the review phase typically take? Is this still being prioritized?

[tonyhallett]

Update please

[karann-msft]

@ffMathy @tonyhallett - we are currently finishing up Self-Contained NuGet Packages - License #4628, and then we will pick up Package Icon should be able to come from inside the package #352. The License, Icon, and documentation are all part of the uber self-contained package spec and is being implemented in phases.

I currently do not have a hard ETA for this feature but this is something we'll pick up after we have implemented self-contained icons. I'll be sure to post here once we have a technical design, and you'll see tasks being added to this issue, as we start executing.

[kconners]

I am pretty excited that this hasn't been ruled out as an enhancement.

[MarkPieszak]

This would definitely be a nice feature, as it should just use the README inside Content folder (or whatever URL we'd like to specify).

It's a bit tough to remember to go to the nuget website and manually enter in the readme for every minor update 😞

[robertmclaws]

Just wanted to check in and see where we stand on this. I could really use this feature in my apps... at the very least, just to be able to open a readme.md instead of a readme.txt file.

[rrelyea]

This continues to be on our backlog...but will likely not be started until post calendar Q4 (if i had to guess).
We are doing this work as part of "self contained work" -- first we did license. Now we are working on package icons. Next part of this series is readme.

Thanks for continuing to 👍 and giving your feedback on items that are important to you.

[lissyx]

This continues to be on our backlog...but will likely not be started until post calendar Q4 (if i had to guess).
We are doing this work as part of "self contained work" -- first we did license. Now we are working on package icons. Next part of this series is readme.

Thanks for continuing to +1 and giving your feedback on items that are important to you.

So, Q4 ended, I guess it means this is not yet being worked on ? Is there any workaround in the mean time ?

I'm looking at something limited to NuGet.org, so we could upload the README as part of the package upload. As much as I can tell, only package upload / unlisting / relisting are documented on https://docs.microsoft.com/nuget/api/package-publish-resource, am I missing any other documentation that contains that information ?

[rrelyea]

@lissyx - correct, we have not started this work yet. our backlog order changes per updated planning, so something isn't done until it is done. Please make sure you vote for issues that are important to you, to help us prioritize.
If you'd like to engage with nuget.org to understand if the existing documentation feature can do something for you today, https://github.com/nuget/nugetgallery is the best place to engage with that team.

[robertmclaws]

I would argue that the NuGet team should not be adding new features at this point until the old ones are fully documented... especially when the currently-shipping features are throwing compiler warnings or errors. Documentation should be a part of every development cycle, not something we should have to wait for. This is a cross-org problem for Microsoft.

[chrisraygill]

As part of this work, we should also consider allowing embedding files for release notes and description. Release notes being the big one. Currently, very few authors take advantage of the release notes section because it has be manually typed in, even though they likely have release notes or a changelog in their repo somewhere already. Very similar reasoning for why embedded readme would be helpful.

Currently only 1 of the top 10 packages uses the release notes field, and it just links to their changelog file in their repo.

[chrisraygill]

Hi everyone! We are actively working on delivering embedded READMEs for NuGet packages 🎉

Check out the latest spec!

Please leave any feedback by commenting on this issue or scheduling a time to talk to me on https://aka.ms/talktonuget.

Edit: corrected talk to NuGet link

[MingweiSamuel]

or scheduling a time to talk to me on

fixed link: https://aka.ms/talktonuget

[chrisraygill]

or scheduling a time to talk to me on

fixed link: https://aka.ms/talktonuget

Fixed it, thanks for the catch!

[Perry004]

Hi, is the idea added into nuget now?

[ffMathy]

@chgill-MSFT looks good to me, except I'd prefer if inclusion of README.md was default, like on NPM. People will quickly adopt. It is highly unlikely that it'll be a surprise, and it is so much easier.

Want a vibrant ecosystem that's well-documented? Because most NuGet packages are not including README.md today, and that is an absolute must if you want to have an NPM-ish experience.

[chrisraygill]

Hi @Perry004, it is not implemented yet. I will update this thread when it's ready 😊 Thank you for your patience!

@ffMathy thank you for your feedback! I think this will eventually the default behavior of the feature, but the thinking was that we would introduce the feature first without auto-inclusion and essentially give authors time to update/write their Readmes with the expectation of it being used as public documentation on NuGet.org.

[ffMathy]

@chgill-MSFT that makes perfect sense, and I get the idea. However, I just don't think people will actually notice and do something about it until they discover the descriptions to their packages being weird.

That's how I figured out how it worked on NPM - by observing that the package description turned into the repo description.

It's nice to give people some time to adapt, but don't expect a huge change in the amount of documented packages unless you force it.

Besides, most NuGet packages that I see around have all their documentation in their README, but not on NuGet.org. In other words, they don't know how to get their documentation on to nuget.org, or don't want to invest the effort.

To be honest, I think it's best to "force" it, and then let people opt out. At worst, it'll make people wonder a little bit, but most likely it'll just be better than what is already there, and people will love that you took their README.md which already contained documentation.

[chrisraygill]

Hi everyone! I'm happy to announce that you can now add a README.md to your NuGet package by adding a property to your project file or nuspec 🙌

The feature is currently in preview with support starting in .NET SDK 5.0.300 preview, NuGet 5.10 preview 2, and Visual Studio 16.10 preview 2. The easiest way to try this feature today is to install the latest .NET 6 preview or the latest Visual Studio preview.

Read the the blogpost we just published for further details: Add a README to Your NuGet Package

If you run into any problems or have suggestions for enhancements, please file new issues to allow us to better keep track on incoming requests and feedback 😊

Thank you everyone for helping us prioritize this feature and giving us plentiful feedback!

[ffMathy]

@chgill-MSFT this is fantastic news! But I doubt it'll truly be used a lot before you start enabling it per default, if there is a README.md file present.

Time will tell!

[wangkanai]

@chgill-MSFT Cool! a very a long await features for me.