Area	Badges
Health
Release
nuget

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

name	type	description	required/default
uri	Uri	The Uri that is either a file containing your markdown, or the web address where said content can be downloaded	Yes
options	DisplayOptions	Properties and styles to apply to the Markdown elements	no / null
allowFollowingLinks	bool	A flag, when set to true, the list of links will be provided, when false the list is omitted	no / true

It has a second overload

name	type	description	required/default
text	string	the text to display	Yes
uriBase	Uri	The Uri base for all links	no / the current working directory
options	DisplayOptions	Properties and styles to apply to the Markdown elements	no / null
allowFollowingLinks	bool	A flag, when set to true, the list of links will be provided, when false the list is omitted	no / true

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

name	type	description	default
Headers	List<Style>	Used as overrides of Header, an order lists of styles to use for different level of headers	fall back to Header / empty
WrapHeader	bool	When true, will wrap Headers with #'s to denote the level	yes / true
IncludeDebug	bool	When true will display all content within in boxes to help visualize how the content is being interpreted by the tool	off / false
ShowFencedCodeBlockInfo	bool	When true, displays the info field (e.g., language identifier) from fenced code blocks	off / false

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