MarkdownSnippets.MsBuild

MarkdownSnippets

A dotnet tool or MsBuild Task that extract snippets from code files and merges them into markdown documents.

See https://github.com/SimonCropp/MarkdownSnippets for full documentation.

Behavior

• Recursively scan the target directory for code files containing snippets.
• Recursively scan the target directory for markdown (.md or mdx) files.
• Merge the snippets into those markdown files.

Installation

Ensure dotnet CLI is installed.

Install MarkdownSnippets.Tool

dotnet tool install -g MarkdownSnippets.Tool

Usage

mdsnippets C:\Code\TargetDirectory

If no directory is passed the current directory will be used, but only if it exists with a git repository directory tree. If not an error is returned.

Defining Snippets

Any code wrapped in a convention based comment will be picked up. The comment needs to start with begin-snippet: which is followed by the key. The snippet is then terminated by end-snippet.

// begin-snippet: MySnippetName
My Snippet Code
// end-snippet

Named C# regions will also be picked up, with the name of the region used as the key.

#region MySnippetName
My Snippet Code
#endregion

Using Snippets in Markdown

The raw snippet key can be used in any markdown document by subsequent surrounding it with snippet::

<!-- snippet: MySnippetName -->