Start for Free

MarkdownSnippets - Open Source Sponsorship

Khalid Abuhakmeh
Two blue circles

Every developer has hit the same wall: a code sample in the docs that no longer compiles. A method was renamed, a parameter changed, an API was deprecated, and the snippet in the README quietly rotted while nobody was looking. Copy-pasted code samples are documentation debt waiting to happen, and the bigger your docs, the worse it gets. The fix is to stop copying code into docs by hand, and that is exactly what this quarter's Duende Open Source Sponsorship recipient does: MarkdownSnippets.

In our seventh sponsorship, the team at Duende has chosen MarkdownSnippets as the next recipient of our support for the open-source projects developers rely on every day. It also marks our second sponsorship of Simon Cropp, whose snapshot testing library Verify we sponsored earlier this year.

Let's see what MarkdownSnippets is all about.

What is MarkdownSnippets?

MarkdownSnippets is a dotnet tool (and MSBuild task) that extracts snippets from your real code files and merges them into your Markdown documents. Instead of pasting code into a README and hoping it stays correct, you mark a region in an actual source file and reference it by key from your docs. When the code changes, you re-run the tool and the docs update to match.

The benefits compound quickly:

  • Snippets are verified by a compiler or parser, because they live in real code files.
  • Snippets can be pulled straight from your existing tests, so the documented behavior is the tested behavior.
  • Changes in code are reflected in documentation when you re-run the tool.
  • Snippets stop drifting out of sync with the main codebase.

Maintained by Simon Cropp, MarkdownSnippets has kept .NET documentation honest for years. Simon uses it to keep the docs for his own projects, including Verify, accurate and in sync. It is the kind of quiet infrastructure tool that runs on every docs build and never asks for attention, which is exactly the work we like to support.

Getting Started

MarkdownSnippets ships as a global dotnet tool. Install it with the .NET CLI:

Sh

dotnet tool install -g MarkdownSnippets.Tool

Next, mark a snippet in a real source file. Any code wrapped in a begin-snippet / end-snippet comment pair is picked up, with the key coming right after begin-snippet:.

Csharp

// begin-snippet: client-credentials-token-request
var client = new HttpClient();
var response = await client.RequestClientCredentialsTokenAsync(
    new ClientCredentialsTokenRequest
    {
        Address = "https://demo.duendesoftware.com/connect/token",
        ClientId = "m2m",
        ClientSecret = "secret",
        Scope = "api"
    });
// end-snippet

Then reference that snippet by key from any Markdown file using a snippet: directive:

Markdown

Request an access token using the client credentials flow:

snippet: client-credentials-token-request

Run the tool against your repository:

Sh

mdsnippets

MarkdownSnippets scans the directory, finds the snippet, and injects the current code into the generated markdown, along with a source link back to the exact lines it came from:

Markdown

<!-- snippet: client-credentials-token-request -->
<a id='snippet-client-credentials-token-request'></a>
```cs
var client = new HttpClient();
var response = await client.RequestClientCredentialsTokenAsync(
    new ClientCredentialsTokenRequest
    {
        Address = "https://demo.duendesoftware.com/connect/token",
        ClientId = "m2m",
        ClientSecret = "secret",
        Scope = "api"
    });
```
<sup><a href='/src/Samples/TokenRequest.cs#L12-L23' title='Snippet source file'>snippet source</a> | <a href='#snippet-client-credentials-token-request' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->

Because the snippet points back to real source lines, readers can jump straight to the full context, and you get a compiler checking your documentation for you. If you prefer to keep the tool out of your global environment, the MSBuild task runs the same process as part of your build.

MarkdownSnippets at Duende

Documentation accuracy matters more when the subject is security. A code sample that configures a client or validates a token needs to be correct, because developers copy it directly into applications that protect real users. We are evaluating MarkdownSnippets for our own documentation so that the samples across our IdentityServer, BFF Security Framework, and open-source library docs can be pulled from compiled, tested code rather than maintained by hand.

The pattern that appeals to us most is sourcing snippets from tests. We already run an extensive test suite on xUnit.net with assertions from Shouldly and snapshots from Verify. Wrapping a begin-snippet region around a test's arrange-and-act steps lets that same verified code appear in the docs, so the documented sample is code that a passing build actually exercises.

Csharp

[Fact]
public async Task Discovery_endpoint_returns_issuer()
{
    // begin-snippet: discovery-request
    var client = new HttpClient();
    var disco = await client.GetDiscoveryDocumentAsync(
        "https://demo.duendesoftware.com");
    // end-snippet

    disco.Issuer.ShouldBe("https://demo.duendesoftware.com");
}

The snippet between the markers is exactly what a reader sees in the docs, and it is exactly what the test executes on every build. When an API changes, the test breaks first and the docs update next, so the samples stay in step with the code.

Sponsorship Details

To support the project and Simon Cropp's continued work, Duende Software is sponsoring MarkdownSnippets for the next 12 months at $250 per month (totaling $3,000 for the year). This sponsorship helps the maintainer cover expenses and invest in the project's growth.

If you benefit from MarkdownSnippets, consider supporting the project too. You can contribute through financial sponsorship, code, documentation, or bug reports.

Try It Out

If your README has ever shipped a broken code sample, MarkdownSnippets is worth an afternoon. Install the dotnet tool, mark a snippet in real code, and reference it from your docs. Check out the documentation to get started.

We'd like to thank Simon Cropp for his tireless work on MarkdownSnippets and the broader .NET open-source ecosystem. Supporting open source is at the heart of what we do at Duende Software, and we're proud to help MarkdownSnippets keep documentation honest.

Related Articles