Add a README to Your NuGet Package

Christopher Gill

In March, we published a blog on the State of the NuGet Ecosystem, 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.

We’re excited to announce that you can finally pack a README.md file in your NuGet package and have it fully rendered on NuGet.org!

– Image from MySqlConnector package

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 or the latest Visual Studio preview.

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.

In the new experience, you add the README.md file the same way you would for any other embedded package file like an icon or license. This means:

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.
2. Once you set up your project file with a path to your README.md, the latest version of your README will be packed every time. Just set it and forget it!
3. The README file is immutable and version-specific, so consumers can view the relevant README for older versions of the package too!

Add a README to your package

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

For the following examples, I am keeping my README.md file in a “docs” folder so its relative path to my project file is docs\README.md. 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 instead of README.md.

Add a README in your project file (recommended)

You can reference the README in the project file as follows:

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        ...
        <PackageReadmeFile>README.md</PackageReadmeFile>
        ...
    </PropertyGroup>

    <ItemGroup>
        ...
        <None Include="docs\README.md" Pack="true" PackagePath="\"/>
        ...
    </ItemGroup>
</Project>

Add a README in your nuspec

You can reference the same README in the nuspec as follows:

<package>
    <metadata>
    ...
    <readme>docs\README.md</readme>
    ...
    </metadata>
    <files>
    ...
    <file src="..\README.md" target="docs\" />
    ...
    </files>
</package>

Writing a README for NuGet.org

Consider including the following items in your README:

• An introduction to what your package is and does – what problems does it solve?
• How to get started with your package – are there any specific requirements?
• Links to more comprehensive documentation if not included in the README itself.
• At least a few code snippets/samples or example images.
• Where and how to leave feedback such as link to the project issues, Twitter, bug tracker, or other platform.
• How to contribute, if applicable.

Keep in mind, high quality READMEs can come in a wide variety of formats, shapes, and sizes! If you already have a package available on NuGet.org, chances are that you already have a README.md file in your repository that would be a great addition to your NuGet.org details page.

Preview your README

To preview your README file before it’s live on NuGet.org, upload your package using the Upload Package web portal on NuGet.org and scroll down to the “Readme File” section of the metadata preview. It should look something like this:

Consider taking time to review and preview your readme file for image compliance and supported formatting to make sure it gives a great first impression to potential users! To correct mistakes on your package README once it’s published to NuGet.org, you will need to push an updated package version with the fix. Making sure everything looks good in advance may save you headache down the road.

Markdown and image support

NuGet.org READMEs support CommonMark compliant Markdown through the Markdig parsing engine. See our NuGet.org README documentation for a full list of supported Markdown features.

Due to security and privacy concerns, NuGet.org will only support badges and images from a trusted allow-list of sources. Unfortunately, links to local images won’t be supported at this time either. Consider hosting local images in one our trusted sources to produce a link to include in your NuGet.org README.

Examples

We want to thank every NuGet.org package author that volunteered to try out the new README experience in advance to give us feedback and serve as models for the broader NuGet ecosystem.

Check out the following NuGet.org packages and how they used READMEs to enhance the richness of their package details page and improve the onboarding experience for new and prospective users:

• NLog.Web.AspNetCore by Julian Verdurmen
• GraphQLing.Client by Giorgi Dalakishvili
• Ben.Demystifier and Ben.Http by Ben Adams
• MySqlConnector by Bradley Grainger and Caleb Lloyed
• CommonHelpers by Lance McCarthy

Where can I see package READMEs?

When a package with an embedded README is uploaded to NuGet.org, the README can be found on its NuGet.org package details page. A link to the README will also be available in the Visual Studio package details pane.

– Image from Ben.Demystifier package

We want to hear your feedback!

Your feedback is very important to us. If you experience any problem trying the new README feature, check out our documentation on submitting bugs and suggestions to find the right place to look for solutions or file new issues.

To see what is coming to NuGet next, view our public proposals or create your own proposal. Be sure to leave your feedback on existing issues & pull requests!

If you add a README to your NuGet.org package, tweet about it and mention @nuget to get a like or retweet from us to signal boost your package!

Christopher Gill Program Manager, NuGet

Follow