Akade.SnippetLink 0.2.1

Akade.SnippetLink

A streamlined, extensible and opinionated dotnet tool for importing snippets into Markdown files.

Shamelessly inspired by Simon Crop's excellent MarkdownSnippets but designed for easier extensibility and per snippet parametrization. The main motivations for this incarnation are support for directly referencing C# symbols like methods and importing BenchmarkDotNet results. In contrast to MarkdownSnippets, SnippetLink ironically does not render any user-clickable links.

Features

• Import code snippets from C# source files into Markdown files
• Import markdown snippets from other Markdown files with special support for BenchmarkDotNet results
• Extensible architecture for different source files and output formats

Getting started

ℹ️ Prerequisite: .NET 10 SDK

If you have the following method in YourFile.cs:

public void MyMethod()
{
    // Implementation
}

You can reference it in your markdown-file:

Run dnx Akade.SnippetLink and all markdown files in the current and subdirectories will now include any linked snippet:

```cs
public void MyMethod()
{
    // Implementation
}
```

As you can see, the links will still be there: You can repeatedly run the tool to update snippets as needed.

Alternatively, install it as a local or global tool:

• dotnet tool install Akade.SnippetLink
• Run it using dotnet snippet-link

C-Sharp snippets

You can directly reference most symbols (see below) by name. If you want to reference a different part of your file, use either // begin-snippet: MarkdownProcessorTest or #region MarkdownProcessorTest in the specified source file. Closed by either // end-snippet or #endregion. Indentation matches the start of the content. ``

public string Test()
{
    return string.Empty;
}

``

BenchmarkDotNet result snippets based on benchmark class name

``

``

Snippet-Link Format defintion

<> means reqruired, [] means optional

The options within brackets are semicolon separated key-value pairs where the value is an optional query-string. Available options:

• importer: Specifies which importer to use for this snippet. If not specified, the default importer for the source file type will be used.
• formatter: Specifies the formatter that determines the rendering of the snippet. If not specified, the default formatter for the selected importer will be used.

Importers

CSharpImporter

Imports C# code snippets from .cs files, based on a symbol, region name, or a reference to a snippet-comment.

ℹ️ For Symbols, the name does not need to be fully qualified if it is unique within the file. It matches from the innermost to outermost scope: i.e. If only one method A exists within the file, A is sufficient. If multiple methods A exist within different classes, the class name must be included as well: ClassName.A.

❗ Currently, generic type parameters and method overloads are not supported for symbol resolution. This will likely be added in a future release. Use regions or snippet-comments in the meantime.

• Supported Symbols
  • Constructors
  • Methods
  • Properties
  • Types
    • Enums
    • Classes
    • Extension blocks
    • Extensions
    • Interfaces
    • Records
    • Structs
  • Delegates
• Regions, referenced by name
• Snippet-Comments: // begin-snippet: snippet-name and // end-snippet

• Parameters:
  • body-only (optional, bool): If true, only the body of the symbol is included (if applicable), excluding the signature or declaration. Defaults to false and ignored for regions and snippet-comments.

Examples:

BenchmarkDotNetImporter

Imports BenchmarkDotNet markdown reports as snippets. The source-file should be the project directory containing the benchmark project , and snippet-name is the benchmark class name. If the env parameter is set to true, environment information is included.

• Parameters:
  • env (optional, bool): If true, includes environment info from the report. Defaults to false

Examples:

Formatters

• code-block:
  Renders the snippet as a fenced code block in markdown, using the snippet's language (e.g., ```cs for C#).

• raw:
  Outputs the snippet content as raw markdown, without wrapping it in a code block. This is useful for markdown-formatted content such as BenchmarkDotNet reports.