BoxOfYellow.ConsoleMarkdownRenderer 0.9.2

I have markdown files, you have markdown files we all have markdown files...

We create them to document various parts of projects. Sometimes that documentation would be helpful while folks are using those projects. And that's where this library comes in. This library provides support for displaying markdown within the console and provides a simple navigation list of links and images within the document. When items from the list are selected their content will be shown inline when possible (aka it's another markdown file, or it's an image and the console appears to be using iTerm2)

I will totally admit README.md files and response that is displayed with --help are not 100% interchangeable, but there is a lot of overlap 🙂

Using it is simple

Option 1: Static API

Just call the one public method from the static Displayer.cs class called DisplayMarkdownAsync it accepts the following parameters

It has a second overload

Option 2: Injectable API (IMarkdownDisplayer)

For dependency injection and testability, the library provides an IMarkdownDisplayer interface with the same display methods. MarkdownDisplayer implements IDisposable; use a using declaration or let your DI container manage the lifetime:

// Short-lived / direct use
using IMarkdownDisplayer displayer = new MarkdownDisplayer();

// Display from a URI
await displayer.DisplayMarkdownAsync(uri, options, allowFollowingLinks: true);

// Display from text
await displayer.DisplayMarkdownAsync(markdownText, baseUri, options);

For DI registration without an IHttpClientFactory (the displayer manages its own HttpClient):

// Register as scoped so the container disposes it automatically
services.AddScoped<IMarkdownDisplayer, MarkdownDisplayer>();

To pipe the container's IHttpClientFactory through to MarkdownDisplayer, use a factory delegate:

// services.AddHttpClient() registers IHttpClientFactory
services.AddHttpClient();
services.AddScoped<IMarkdownDisplayer>(sp =>
    new MarkdownDisplayer(sp.GetRequiredService<IHttpClientFactory>()));

// Or with a named client:
services.AddHttpClient("myClient", client => { /* configure */ });
services.AddScoped<IMarkdownDisplayer>(sp =>
    new MarkdownDisplayer(sp.GetRequiredService<IHttpClientFactory>(), httpClientName: "myClient"));

Supplying a custom IHttpClientFactory

If your application already registers an IHttpClientFactory (e.g. in an ASP.NET Core or IHostBuilder setup), you can pass it to MarkdownDisplayer so that all HTTP requests go through your configured factory. The factory — and the clients it produces — is owned and managed by the caller.

// Using the default (unnamed) client from the factory:
using IMarkdownDisplayer displayer = new MarkdownDisplayer(httpClientFactory);

// Using a named client registered in your DI container:
using IMarkdownDisplayer displayer = new MarkdownDisplayer(httpClientFactory, httpClientName: "myClient");

When no factory is supplied, MarkdownDisplayer creates and reuses its own internal HttpClient with a SocketsHttpHandler configured with a 15-minute pooled connection lifetime.

Testing with Fakes

The ConsoleMarkdownRenderer.Fakes package provides an out-of-the-box test double:

// Install: BoxOfYellow.ConsoleMarkdownRenderer.Fakes

var fakeDisplayer = new FakeMarkdownDisplayer();
await fakeDisplayer.DisplayMarkdownAsync(new Uri("https://example.com/readme.md"));

// Assert on recorded calls
Assert.AreEqual(1, fakeDisplayer.Calls.Count);
Assert.AreEqual("https://example.com/readme.md", fakeDisplayer.Calls[0].Uri?.ToString());

See ConsoleMarkdownRenderer.ExampleTests for more examples.

Checkout ConsoleMarkdownRenderer.Example to see it in use

Default Styling

The defaults for the styling for the Markdown elements can be seen in the examples listed above. The details for that style can be changed by creating an instance of DisplayOptions and overwriting any that you see fit.

This object is more or less a bag of styles to use for the various parts of your markdown document. There are a few exceptions

Supporting packages

It's also important to give credit where credit is due, this library is really just glue for the following packages

• Markdig for parsing the markdown
• Spectre.Console for display rich formatting within the console
• RomanNumeral for minimal roman numeral processing

Contributing

Contributions are welcome, please see CONTRIBUTING.md and CODE_OF_CONDUCT.md