Embedded markdown readme for NuGet packages

[MSDN-WhiteKnight]

NuGet introduced embedded markdown Readme support in May 2021. Now the updated gallery design displays this readme file on the package page if it's included. Looks like most runtime packages don't have readme embedded (neither markdown nor plaintext), and for them it fallbacks to description from nuspec. This leads to experience like this:

A lot of space is unused here. It could be filled with some more introductory information or simple usage example. And also listed "Commonly used types" could be links to their API docs. That's how package with markdown readme looks like:

Could we add markdown readme files for runtime packages?

---

Progress:

• microsoft.extensions.configuration
• microsoft.extensions.configuration.json
• system.configuration.configurationmanager
• system.text.json
• microsoft.extensions.configuration.binder
• microsoft.extensions.configuration.abstractions
• System.Runtime.Caching

For up-to-date checklist, see PR #91210

See also:

• Write a high-quality README for NuGet packages
• Package Readme guidelines
• Example PR with new Readme template

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

Tagging subscribers to this area: @Anipik, @safern, @ViktorHofer
See info in area-owners.md if you want to be subscribed.

Issue Details

---

NuGet introduced embedded markdown Readme support in May 2021. Now the updated gallery design displays this readme file on the package page if it's included. Looks like most runtime packages don't have readme embedded (neither markdown nor plaintext), and for them it fallbacks to description from nuspec. This leads to experience like this:

A lot of space is unused here. It could be filled with some more introductory information or simple usage example. And also listed "Commonly used types" could be links to their API docs. That's how package with markdown readme looks like:

Could we add markdown readme files for runtime packages?

Author:	MSDN-WhiteKnight
Assignees:	-
Labels:	enhancement, area-Infrastructure-libraries, packaging, untriaged
Milestone:	-

[joperezr]

That is a good suggestion. Moving issue to infrastructure as the change to add markdown for package descriptions would likely go there. We can consider using third-party libraries that convert a (markdown) string into html. We could use one of those and then let individual packages onboard markdown description as they see fit.

[ViktorHofer]

Would this actually require any infrastructure support? I assume a library author just needs to set a property to point to the manually written markdown file.

[joperezr]

I'm not sure how this works, I assumed that in order for this to work then you should need to write the description in Html so that the Nuspec is able to parse it and show it in nuget.org. In any case, even if that is not the case and all we need to do is to change the description to markdown, I believe infrastructure has usually been the owners of package ddescription so I'd imagine that we should do an overall pass through all packages to make the conversion.

[svick]

@joperezr The relevant documentation is here. In short, the readme file has to be in Markdown, so no extra work for converting it is needed.

[ViktorHofer]

I'm wondering if it makes more sense to convert every library's existing PackageDescription property content into README.md markdown files or just keep it as is and let library authors decide if they would like to leverage the README.md support.

Pros for converting now:

• Easier to add content to what's already there

Cons:

• Adding a README.md file per project and shipping it via our packages even though most packages won't have any additional information that would warrant a README.md file.

[MSDN-WhiteKnight]

Better to convert individual libraries as needed, i think. This is mainly needed for out-of-band libraries that are explicitly installed via package manager. For libraries like System.Collections.Immutable that are inbox on all .NET Core versions and only installed via package manager for .NET Framework, it's less important.

We also need to define convention where readme.md is placed in projects. Should it be docs\README.md as in NuGet default example, or just README.md near .csproj file?

[ViktorHofer]

We also need to define convention where readme.md is placed in projects. Should it be docs\README.md as in NuGet default example, or just README.md near .csproj file?

No need for another folder. I would just put it next to the csproj file.