Adding a Readme to NuGet Package Landing Pages

An essential part of working on open-source libraries is conveying the value and useability of said library—a well-written “readme” file, while not a substitute for complete documentation, can help onboard new users and increase the joy of using your code.

Regarding NuGet packages, you can now add a Readme.md asset to your NuGet packages, which NuGet.org will display on your package’s landing page, thus giving you another medium to attract new users and inform the curious developer. For example, check out my library HTMX.NET landing page, which now has the read me prominently displayed.

Let’s see what steps you must take to accomplish the same in your libraries.

The Readme File

Typically, at the root of every open-source repository should be a readme.md file. The inclusion of the file has become a convention across GitHub, GitLab, and most distributed source control offerings. Your source control’s user interface will display the readme to repository visitors, allowing them to read your perspective and introductory notes.

As an aside, a good readme should answer three essential questions:

What is this project? A statement of intent and what the ultimate goal of the repository is trying to accomplish goes a long way.
How do I get started? This includes where to get the library, possibly building the source, or acessing the library through a package manager.
What are some common use cases? While you can’t account for all scenarios, there are likely common use cases your users will encounter. Spell them out. If there are known edge cases, spell those out too.

When adding the Readme.md to your .NET repository, you’ll want to link it to each project that is packagable. Checkout out my NuGet guide here if you’re unfamiliar with setting up .NET projects for NuGet.

Updating The Package Project

The way I accomplish this is by using the Link functionality in a csproj file. Let’s take a look at what that might look like.

<ItemGroup>
    <None Remove="antiforgerySnippet.js" />
    <None Include="..\..\icon.png" Pack="true" PackagePath="">
        <Link>Properties\icon.png</Link>
    </None>
    <!-- IMPORTANT: adding the Readme as a link -->
    <None Include="..\..\README.md" Pack="true" PackagePath="">
        <Link>Properties\README.md</Link>
    </None>
</ItemGroup>

The link can point to anywhere in your project, but I place most of my linked resources inside of the Properties folder to keep the visual clutter to a minnimum. You’ll also need to have the Pack attribute set to true and the PackagePath is set to the NuGet package root. I also have a package icon in this item group, which I also recommend adding.

Next, you’ll need to add some additional elements to your project’s PropertyGroup element, with the important tags for this tutorial being PackageReadmeFile. I’ve included a complete PropertyGroup section to see how it fits in with all the other Package* elements.

The PackageReadmeFile requires the path to the Readme.md file within the NuGet package. Do not confuse this with where you place the file in your project.

<PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <OutputType>Library</OutputType>
    <Nullable>enable</Nullable>
    <LangVersion>Latest</LangVersion>
    <IsPackable>true</IsPackable>
    <PackageId>Htmx.TagHelpers</PackageId>
    <Authors>Khalid Abuhakmeh</Authors>
    <PackageIcon>icon.png</PackageIcon>
    <RepositoryUrl>https://github.com/khalidabuhakmeh/Htmx.Net</RepositoryUrl>
    <PackageLicenseExpression>MIT</PackageLicenseExpression>
    <PackageTags>web,javascript</PackageTags>
    <!-- IMPORTANT Do not forget this -->
    <PackageReadmeFile>README.md</PackageReadmeFile>
    <Description>
        Adds ASP.NET Core tag helpers to make generating urls for Htmx (https://htmx.org) easier. Mimics the ASP.NET Core url tag helpers.
    </Description>
</PropertyGroup>

If you’ve followed these steps correctly, then you should have a visible Readme on your NuGet packages home page. Congratulations! 🎉

Side Note: NuGet.org will not respective relatively-linked resources such as images. If your file uses image references, be sure to have absolute paths to the images or else you’ll have an incomplete readme on NuGet.org.

Conclusion

There you have it! With the use of a Readme file, a Link element, and PackageReadmeFile element you too can have a better looking NuGet package page. It can give you and your package a greater chance of being picked and it can help grow your little corner of the .NET community.

As always, thanks for reading and sharing my posts with friends and colleagues.