Adds automatic package readme packing and include-directive resolution at pack time. Works with SDK Pack and NuGetizer (no NuGetizer required).

<PackageReference Include="Readme" Version="*" PrivateAssets="all" />

When the project is packable and a readme.md (or $(PackageReadmeFile)) is present:

1. The readme is included in the package automatically (PackReadme=false to opt out).
2. Include directives are resolved before pack (local files, nested includes, #fragment sections, HTTP(S) URLs).
3. The processed file is written under $(BaseIntermediateOutputPath) and that intermediate file is what is packed.

Include syntax

Use an HTML comment starting with include and a path (relative file, #fragment, or http(s) URL). Nested includes are supported.

Fragments resolve in this order:

1. Explicit comment anchors — matching <!-- #section --> … <!-- #section --> pairs (when present). The markers and everything between them is included, so you control whether a section title is in the range (for example put ## Usage inside the pair to keep the title, or place the pair after the heading to omit it).
2. GitHub heading auto-anchors — otherwise the Markdown ATX heading whose GitHub auto-anchor matches the fragment (for example ## Usage for #usage). The heading line itself is included, through the line before the next heading of the same or higher level.

Use explicit <!-- #fragment --> markup when you need maximum control over whether the section name is included; auto-anchors always include the matching heading.

Unresolved includes log a warning and leave the marker in place (pack does not fail).

Remote includes

Absolute http(s) includes from a local file are always allowed (subject to scheme). Includes nested inside remote content resolve relative paths against that URL’s base. Absolute URLs from remote content are allowed only when the host is the same as (or a subdomain of) the including remote host, or is listed in @(ReadmeIncludeDomain) (subdomains of listed domains count too). Other schemes/hosts warn and stay unresolved.

Properties

<PropertyGroup>
  <!-- Optional: allow cleartext remote includes -->
  <ReadmeIncludeScheme>https;http</ReadmeIncludeScheme>
</PropertyGroup>
<ItemGroup>
  <ReadmeIncludeDomain Include="cdn.example.com" />
</ItemGroup>

Open Source Maintenance Fee

To ensure the long-term sustainability of this project, users of this package who generate revenue must pay an Open Source Maintenance Fee. While the source code is freely available under the terms of the License, this package and other aspects of the project require adherence to the Maintenance Fee.

To pay the Maintenance Fee, become a Sponsor at the proper OSMF tier. A single fee covers all of Devlooped packages.

Sponsors

Learn more about GitHub Sponsors