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

Support is available via a Tidelift Subscription.

• Value Proposition
• Installation
• Usage
• Defining Snippets
• Using Snippets
• Snippet Exclusions
• Mark resulting files as read only
• Table of contents
• Header
• Markdown includes
• LinkFormat
• UrlPrefix
• UrlsAsSnippets
• Security contact information
• .net API
• MsBuild Task
• Github Action
• Config file convention
• Indentation
• Max Width

Automatically extract snippets from code and injecting them into markdown documents has several benefits:

• Snippets can be verified by a compiler or parser.
• Tests can be run on snippets, or snippets can be pulled from existing tests.
• Changes in code are automatically reflected in documentation.
• Snippets are less likely to get out of sync with the main code-base.
• Snippets in markdown is easier to create and maintain since any preferred editor can be used to edit them.

Ensure dotnet CLI is installed.

Install MarkdownSnippets.Tool

dotnet tool install -g MarkdownSnippets.Tool

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.

• Recursively scan the target directory for all non ignored files for snippets.
• Recursively scan the target directory for all *.source.md files.
• Merge the snippets with the .source.md to produce .md files. So for example readme.source.md would be merged with snippets to produce readme.md. Note that this process will overwrite any existing .md files that have matching .source.md files.

There is a secondary convention that leverages the use of a directory named mdsource. Where .source.md files are placed in a mdsource sub-directory, the mdsource part of the file path will be removed when calculating the target path. This allows the .source.md to be grouped in a sub directory and avoid cluttering up the main documentation directory.

When using the mdsource convention, all references to other files, such as links and images, should specify the full path from the root of the repository. This will allow those links to work correctly in both the source and generated markdown files. Relative paths cannot work for both the source and the target file.

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.

To stop regions collapsing in Visual Studio disable 'enter outlining mode when files open'. See Visual Studio outlining.

The keyed snippets can be used in any documentation .md file by adding the text snippet: KEY.

Then snippets with that key.

For example

Some blurb about the below snippet
snippet: MySnippetName

The resulting markdown will be:

<!-- snippet: MySnippetName -->
Some blurb about the below snippet
<a id='snippet-MySnippetName'/></a>
```
My Snippet Code
```
<sup><a href='/relativeUrlToFile#L1-L11' title='File snippet `MySnippetName` was extracted from'>snippet source</a> | <a href='#snippet-MySnippetName' title='Navigate to start of snippet `MySnippetName`'>anchor</a></sup>
<!-- endsnippet -->

Notes:

• The vertical bar ( | ) is used to separate adjacent links as per web accessibility recommendations: https://webaim.org/techniques/hypertext/hypertext_links#groups
• H33: Supplementing link text with the title attribute

When snippets are read all source files are stored in a list. When searching for a snippet with a specified key, and that key is not found, the list of files are used as a secondary lookup. The lookup is done by finding all files that have a suffix matching the key. This results in the ability to include full files as snippets using the following syntax:

snippet: directory/FileToInclude.txt

The path syntax uses forward slashes /.

snippet: http://myurl

To exclude directories use -e or --exclude.

For example the following will exclude any directory containing 'foo' or 'bar'

mdsnippets -e foo:bar

When scanning for snippets the following are ignored:

• All directories and files starting with a period .
• All binary files as defined by https://github.com/sindresorhus/binary-extensions/
• Any of the following directory names: bin, obj

To mark the resulting .md files as read only use -r or --readonly.

This can be helpful in preventing incorrectly editing the .md file instead of the .source.md file.

mdsnippets -r true

If a line is toc it will be replaced with a table of contents

So if a markdown document contains the following:

# Title

toc

## Heading 1

Text1

## Heading 1

Text2

^{snippet source | anchor}

The result will be rendered:

# Title

<!-- toc -->
## Contents

 * [Heading 1](#heading-1)
 * [Heading 2](#heading-2)
<!-- endtoc -->

## Heading 1

Text1

## Heading 2

Text2

^{snippet source | anchor}

Headings with level 2 (##) or greater can be rendered. By default all level 2 and level 3 headings are included.

To include more levels use the --toc-level argument. So for example to include headings levels 2 though level 6 use:

mdsnippets --toc-level 5

To exclude headings use the --toc-excludes argument. So for example to exclude heading1 and heading2 use:

mdsnippets --toc-excludes heading1:heading2

When a .md file is written, a header is include. The default header is:

GENERATED FILE - DO NOT EDIT
This file was generated by [MarkdownSnippets](https://github.com/SimonCropp/MarkdownSnippets).
Source File: {relativePath}
To change this file edit the source file and then run MarkdownSnippets.

^{snippet source | anchor}

To disable the header use --write-header

mdsnippets --write-header false

To apply a custom header use --header. {relativePath} will be replaced with the relative path of the .source.md file.

mdsnippets --header "GENERATED FILE - Source File: {relativePath}"

To insert a newline use \n

mdsnippets --header "GENERATED FILE\nSource File: {relativePath}"

Markdown includes are pulled into the document before passing the content through the snippet insertion.

Add a file anywhere in the target directory that is suffixed with .include.md. For example, the file might be named theKey.include.md.

Add the following to the markdown:

include: theKey

include: http://myurl

Defines the format of snippet source links that appear under each snippet.

namespace MarkdownSnippets
{
    public enum LinkFormat
    {
        GitHub,
        Tfs,
        Bitbucket,
        GitLab
    }
}

^{snippet source | anchor}

if (linkFormat == LinkFormat.GitHub)
{
    return $"{path}#L{snippet.StartLine}-L{snippet.EndLine}";
}

if (linkFormat == LinkFormat.Tfs)
{
    return $"{path}&line={snippet.StartLine}&lineEnd={snippet.EndLine}";
}

if (linkFormat == LinkFormat.Bitbucket)
{
    return $"{path}#lines={snippet.StartLine}:{snippet.EndLine}";
}

if (linkFormat == LinkFormat.GitLab)
{
    return $"{path}#L{snippet.StartLine}-{snippet.EndLine}";
}

^{snippet source | anchor}

UrlPrefix allows a string to be defined that will prefix all snippet links. This is helpful when the markdown file are being hosted on a site that is no co-located with the source code files. It can be defined in the config file, the MsBuild task, and the dotnet tool.

Urls to files to be included as snippets. Space separated for multiple values.

mdsnippets --urls-as-snippets "https://github.com/SimonCropp/MarkdownSnippets/snippet.cs"

To report a security vulnerability, use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.

Loosely based on some code from https://github.com/shiftkey/scribble.

Down by Alfredo Creates from The Noun Project.