Add dedicated package README

- Add a dedicated package README to improve rendering in the NuGet gallery.
- Fix markdownlint warnings.

Author: martincostello

Directory.Build.props

@@ -31,7 +31,7 @@
     <PackageIcon></PackageIcon>
     <PackageLicenseExpression>Apache-2.0</PackageLicenseExpression>
     <PackageProjectUrl>https://github.com/martincostello/xunit-logging</PackageProjectUrl>
-    <PackageReadmeFile>README.md</PackageReadmeFile>
+    <PackageReadmeFile>package-readme.md</PackageReadmeFile>
     <PackageReleaseNotes>See $(PackageProjectUrl)/releases for details.</PackageReleaseNotes>
     <PackageRequireLicenseAcceptance>false</PackageRequireLicenseAcceptance>
     <PackageTags>xunit;logging</PackageTags>

README.md

@@ -16,7 +16,7 @@
 
 To install the library from [NuGet](https://www.nuget.org/packages/MartinCostello.Logging.XUnit/ "MartinCostello.Logging.XUnit on NuGet.org") using the .NET SDK run:
 
-```
+```console
 dotnet add package MartinCostello.Logging.XUnit
 ```
 
@@ -65,16 +65,17 @@ public sealed class Calculator(ILogger<Calculator> logger)
 ```
 
 See below for links to more examples:
-  1. [Unit tests](https://github.com/martincostello/xunit-logging/blob/main/tests/Logging.XUnit.Tests/Examples.cs "Unit test examples")
-  1. [Integration tests for an ASP.NET Core HTTP application](https://github.com/martincostello/xunit-logging/blob/main/tests/Logging.XUnit.Tests/Integration/HttpApplicationTests.cs "Integration test examples")
+
+- [Unit tests](https://github.com/martincostello/xunit-logging/blob/main/tests/Logging.XUnit.Tests/Examples.cs "Unit test examples")
+- [Integration tests for an ASP.NET Core HTTP application](https://github.com/martincostello/xunit-logging/blob/main/tests/Logging.XUnit.Tests/Integration/HttpApplicationTests.cs "Integration test examples")
 
 ## Feedback
 
 Any feedback or issues can be added to the issues for this project in [GitHub](https://github.com/martincostello/xunit-logging/issues "Issues for this project on GitHub.com").
 
 ## Repository
 
-The repository is hosted in [GitHub](https://github.com/martincostello/xunit-logging "This project on GitHub.com"): https://github.com/martincostello/xunit-logging.git
+The repository is hosted in [GitHub](https://github.com/martincostello/xunit-logging "This project on GitHub.com"): <https://github.com/martincostello/xunit-logging.git>
 
 ## License
 

package-readme.md

@@ -0,0 +1,57 @@
+# xunit Logging
+
+## Introduction
+
+`MartinCostello.Logging.XUnit` provides extensions to hook into the `ILogger` infrastructure to output logs from your xunit tests to the test output.
+
+### Usage
+
+```csharp
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging;
+using Xunit;
+using Xunit.Abstractions;
+
+namespace MyApp.Calculator;
+
+public class CalculatorTests(ITestOutputHelper outputHelper)
+{
+    [Fact]
+    public void Calculator_Sums_Two_Integers()
+    {
+        // Arrange
+        using var serviceProvider = new ServiceCollection()
+            .AddLogging((builder) => builder.AddXUnit(outputHelper))
+            .AddSingleton<Calculator>()
+            .BuildServiceProvider();
+
+        var calculator = services.GetRequiredService<Calculator>();
+
+        // Act
+        int actual = calculator.Sum(1, 2);
+
+        // Assert
+        Assert.AreEqual(3, actual);
+    }
+}
+
+public sealed class Calculator(ILogger<Calculator> logger)
+{
+    public int Sum(int x, int y)
+    {
+        int sum = x + y;
+
+        logger.LogInformation("The sum of {x} and {y} is {sum}.", x, y, sum);
+
+        return sum;
+    }
+}
+```
+
+## Feedback
+
+Any feedback or issues can be added to the issues for this project in [GitHub](https://github.com/martincostello/xunit-logging/issues "Issues for this project on GitHub.com").
+
+## License
+
+This project is licensed under the [Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0.txt "The Apache 2.0 license") license.