{"id":2005,"date":"2021-05-06T12:00:22","date_gmt":"2021-05-06T19:00:22","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/dotnet\/?p=2005"},"modified":"2021-05-06T12:00:22","modified_gmt":"2021-05-06T19:00:22","slug":"add-a-readme-to-your-nuget-package","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/add-a-readme-to-your-nuget-package\/","title":{"rendered":"Add a README to Your NuGet Package"},"content":{"rendered":"

In March, we published a blog on the State of the NuGet Ecosystem<\/a>, where we discussed insights gained from the hundreds of customers we’ve heard from over the last six months. One of the top problems customers identified in our surveys is that “most packages have insufficient docs” easily accessible from NuGet.org. In fact, 45% of NuGet.org survey respondents reported “critical packages I need do exist but they are not well documented” as a reason for dissatisfaction with the NuGet ecosystem.<\/p>\n

We’re excited to announce that you can finally pack a README.md<\/code> file in your NuGet package and have it fully rendered on NuGet.org!<\/strong><\/p>\n

\"Image<\/p>\n

– Image from MySqlConnector<\/a> package<\/em><\/p>\n

This new capability is still 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<\/a> or the latest Visual Studio preview<\/a>.<\/p>\n

Previously, we offered limited support for markdown documentation on NuGet.org. However, this experience required authors to paste a link to their README or paste their README contents on NuGet.org for each new package version. We heard from authors that this additional step took too much time and felt removed from the rest of the package creation and publishing process.<\/p>\n

In the new experience, you add the README.md<\/code> file the same way you would for any other embedded package file like an icon or license. This means:<\/p>\n

    \n
  1. You don’t have to go to NuGet.org just to add documentation to your package, you can do it with whichever tools you prefer to use to author NuGet packages.<\/li>\n
  2. Once you set up your project file with a path to your README.md<\/code>, the latest version of your README will be packed every time. Just set it and forget it!<\/li>\n
  3. The README file is immutable and version-specific, so consumers can view the relevant README for older versions of the package too!<\/li>\n<\/ol>\n

    Add a README to your package<\/h2>\n

    If you already have a README.md<\/code> file, including it in your package is as easy as adding a couple lines to your project file for SDK-style projects<\/a> or nuspec for non-SDK-style projects. If you are new to creating NuGet packages<\/a>, we recommend going with an SDK-style project.<\/p>\n

    For the following examples, I am keeping my README.md<\/code> file in a “docs” folder so its relative path to my project file is docs\\README.md<\/code>. You can also use a README file at the repository root or any other folder as long as you use adjust the relative path. Additionally, you can name the target file anything you would like, such as NuGet.md<\/code> instead of README.md<\/code>.<\/p>\n

    Add a README in your project file (recommended)<\/h3>\n

    You can reference the README in the project file<\/a> as follows:<\/p>\n

    <Project Sdk=\"Microsoft.NET.Sdk\">\n    <PropertyGroup>\n        ...\n        <PackageReadmeFile>README.md<\/PackageReadmeFile>\n        ...\n    <\/PropertyGroup>\n\n    <ItemGroup>\n        ...\n        <None Include=\"docs\\README.md\" Pack=\"true\" PackagePath=\"\\\"\/>\n        ...\n    <\/ItemGroup>\n<\/Project><\/code><\/pre>\n
    Add a README in your nuspec<\/h3>\n
    You can reference the same README in the nuspec<\/a> as follows:<\/p>\n
    <package>\n    <metadata>\n    ...\n    <readme>docs\\README.md<\/readme>\n    ...\n    <\/metadata>\n    <files>\n    ...\n    <file src=\"..\\README.md\" target=\"docs\\\" \/>\n    ...\n    <\/files>\n<\/package><\/code><\/pre>\n
    Writing a README for NuGet.org<\/h2>\n
    Consider including the following items in your README:<\/p>\n