MarkdownSnippets

MarkdownSnippets performs 'smart trimming' of indentation within snippets. It identifies the common leading whitespace (either spaces or tabs) used across all lines within the snippet boundaries and removes that amount from every line. This allows you to indent snippet definitions within your source files without affecting the actual content of the snippet when it is rendered.

```markdown
··// begin-snippet MySnippetName
··Line one of the snippet
····Line two of the snippet
··// end-snippet

// Resulting output: Line one of the snippet ··Line two of the snippet

MarkdownSnippets extracts code blocks based on specific comment conventions or C# regions. The name used in the code becomes the snippet key.

Using convention-based comments

Wrap your code with begin-snippet: <KeyName> and end-snippet.

Using C# regions

Named C# regions are also supported. The region name is used as the snippet key.

Behavior: The tool recursively scans the target directory for code files containing these markers and markdown (.md or .mdx) files to merge them into.

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

#region MySnippetName
My Snippet Code
#endregion

Setting ValidateContent: true runs technical-writing style checks on the processed markdown. It flags:

• Exclamation marks (! ).
• Discouraged words (e.g., you, your, we, our, please, just, simply, easy, aforementioned, henceforth).
• Wordy phrases (e.g., in order to should be to).

Note: Block quotes (>), fenced code blocks, and inline code spans are skipped. An unclosed fenced code block will be reported as an error.

MarkdownSnippets performs 'smart trimming' of snippet indentation. It identifies the common leading whitespace (either spaces or tabs) used across all lines within a snippet block and removes that specific amount from every line. This allows you to indent your snippet definitions within your source file without affecting the actual content of the snippet when it is rendered.

// Source snippet with 2 leading spaces:
  // begin-snippet MySnippetName
  Line one of the snippet
    Line two of the snippet
  // end-snippet

// Resulting output:
Line one of the snippet
  Line two of the snippet

MarkdownSnippets automatically ignores several types of directories by default to avoid processing unnecessary or temporary files. These include:

• Source Control: .git
• IDE Temp Files: .vs, .vscode, .idea
• Package Caches: packages, node_modules
• Build Output: dist, .angular, bin, obj
• Hidden Directories: Any directory with the Hidden attribute.

MarkdownSnippets automatically excludes certain file types from processing:

1. Binary Files: A wide range of binary extensions (e.g., .exe, .zip, .png, .pdf, .mp3, etc.) are excluded to prevent errors during text processing.
2. Files that cannot contain comments: Files that do not support the comment syntax required for snippet markers are excluded. These include:
   • DotSettings
   • csv
   • json
   • geojson
   • sln

To enable editor help, code completion, and validation in IDEs like JetBrains Rider, include the $schema field in your mdsnippets.json file pointing to the official schema.

{
  "$schema": "https://raw.githubusercontent.com/SimonCropp/MarkdownSnippets/master/schema.json"
}

To include the entire content of a remote URL as a snippet, use the snippet: prefix followed by the URL.

snippet: http://myurl

You can consume the MarkdownSnippets library by installing the NuGet package. This provides the core logic for extracting snippets from files.

https://nuget.org/packages/MarkdownSnippets/