### Install MarkdownSnippets CLI Tool

Source: https://context7.com/simoncropp/markdownsnippets/llms.txt

Install the dotnet tool globally to use MarkdownSnippets from the command line.

```bash
dotnet tool install -g MarkdownSnippets.Tool
```

--------------------------------

### Code Snippet Example

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/DirectoryMarkdownProcessor/ValidationErrors/one.md

This snippet contains a simple code example. It is presented in a TXT format.

```txt
Some code
```

```txt
Some code
```

```txt
Some code
```

```txt
Some code
```

```txt
Some code
```

```txt
Some code
```

--------------------------------

### Include Full File Example

Source: https://github.com/simoncropp/markdownsnippets/blob/main/readme.md

Demonstrates how to include a full file when no specific snippet is found. The target directory is searched for a file matching the name.

```markdown
<!-- snippet: license.txt -->
<a id='snippet-license.txt'></a>
```txt
The MIT License (MIT)

Copyright (c) 2013 Simon Cropp

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
```
<sup><a href='/license.txt#L1-L20' title='Snippet source file'>snippet source</a> | <a href='#snippet-license.txt' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->
```

--------------------------------

### Configure GitHub Action for MarkdownSnippets

Source: https://github.com/simoncropp/markdownsnippets/blob/main/docs/github-action.md

Workflow configuration to install the tool and push documentation updates back to the repository.

```yml
name: on-push-do-docs
on:
  push:
jobs:
  docs:
    runs-on: windows-latest
    steps:
    - uses: actions/checkout@v4
    - name: Run MarkdownSnippets
      run: |
        dotnet tool install --global MarkdownSnippets.Tool
        mdsnippets ${GITHUB_WORKSPACE}
      shell: bash
    - name: Push changes
      run: |
        git config --local user.email "action@github.com"
        git config --local user.name "GitHub Action"
        git commit -m "Docs changes" -a || echo "nothing to commit"
        remote="https://${GITHUB_ACTOR}:${{secrets.GITHUB_TOKEN}}@github.com/${GITHUB_REPOSITORY}.git"
        branch="${GITHUB_REF:11}"
        git push "${remote}" ${branch} || echo "nothing to push"
      shell: bash
```

--------------------------------

### Appveyor CI Configuration for .NET

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/SnippetExtractor/SnippetExtractorTests.AppendUrlAsSnippet.verified.txt

This configuration sets up the build environment, installs .NET SDKs for Windows and Linux, builds the project, and runs tests. It also includes logic for uploading artifacts on failure.

```yml
image:
- Visual Studio 2022
#- macOS
environment:
  DOTNET_NOLOGO: true
  DOTNET_CLI_TELEMETRY_OPTOUT: true
  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true
build_script:
- pwsh: |
    if ($isWindows) {
      Invoke-WebRequest "https://dot.net/v1/dotnet-install.ps1" -OutFile "./dotnet-install.ps1"
      ./dotnet-install.ps1 -JSonFile src/global.json -Architecture x64 -InstallDir 'C:/Program Files/dotnet'
    }
    else {
      Invoke-WebRequest "https://dot.net/v1/dotnet-install.sh" -OutFile "./dotnet-install.sh"
      sudo chmod u+x dotnet-install.sh
      sudo ./dotnet-install.sh --jsonfile src/global.json --architecture x64 --install-dir '/usr/local/share/dotnet'
      sudo ./dotnet-install.sh --version 9.0.306 --architecture x64 --install-dir '/usr/local/share/dotnet'
    }
- dotnet build src --configuration Release
- dotnet test src --configuration Release --no-build --no-restore
test: off
on_failure:
  - ps: Get-ChildItem *.received.* -recurse | % { Push-AppveyorArtifact $_.FullName -FileName $_.Name }
artifacts:
- path: nugets/*.nupkg
```

--------------------------------

### Full MarkdownSnippets Configuration Example

Source: https://github.com/simoncropp/markdownsnippets/blob/main/docs/config-file.md

This JSON demonstrates all available configuration settings for MarkdownSnippets, including read-only status, link format, exclusion rules, and header customization.

```json
{
  "$schema": "https://raw.githubusercontent.com/SimonCropp/MarkdownSnippets/master/schema.json",
  "ReadOnly": false,
  "LinkFormat": "Tfs",
  "TocLevel": 3,
  "ExcludeDirectories": [ "Dir1", "Dir2" ],
  "ExcludeMarkdownDirectories": [ "Dir2", "Dir3" ],
  "ExcludeSnippetDirectories": [ "Dir4", "Dir5" ],
  "UrlsAsSnippets": [ "Url1", "Url2" ],
  "TocExcludes": [ "Exclude Heading1", "Exclude Heading2" ],
  "Convention": "InPlaceOverwrite",
  "WriteHeader": true,
  "MaxWidth": 80,
  "Header": "GENERATED FILE - Source File: {relativePath}",
  "UrlPrefix": "TheUrlPrefix",
  "TreatMissingAsWarning": true,
  "ValidateContent": true,
  "OmitSnippetLinks": true
}
```

--------------------------------

### Markdown Snippet Output Example

Source: https://context7.com/simoncropp/markdownsnippets/llms.txt

Example of how a markdown file is processed to include a code snippet, including source link and anchor.

```markdown
Here's how to use the Example class:

<!-- snippet: MySnippetName -->
<a id='snippet-MySnippetName'></a>
```csharp
public class Example
{
    public void DoSomething()
    {
        Console.WriteLine("Hello, World!");
    }
}
```
<sup><a href='/src/Example.cs#L2-L10' title='Snippet source file'>snippet source</a> | <a href='#snippet-MySnippetName' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->
```

--------------------------------

### C# Code Snippet Example

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/SnippetExtractor/SnippetExtractorTests.CanExtractWithNoTrailingCharacters.verified.txt

This snippet demonstrates a basic C# code structure. Ensure the code is correctly placed within a C# file.

```cs
the code
```

--------------------------------

### Snippet Indentation Trimming Example

Source: https://github.com/simoncropp/markdownsnippets/blob/main/docs/mdsource/indentation.source.md

Shows how leading spaces are removed from a snippet block.

```text
••// begin-snippet MySnippetName
••Line one of the snippet
••••Line two of the snippet
••// end-snippet
```

```text
Line one of the snippet
••Line two of the snippet
```

--------------------------------

### Basic C# Snippet

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/MarkdownProcessor/MarkdownProcessorTests.SnippetInIncludeLast.verified.txt

A simple C# code snippet. No specific setup or constraints are mentioned.

```cs
Snippet
```

--------------------------------

### Rooted Local Snippet Reference

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/DirectoryMarkdownProcessorTests.FileSnippetWithWhiteSpace.verified.txt

Reference a local snippet using a rooted path starting from the project root. This provides an absolute path within the project.

```markdown
<!-- snippet: /sourceFile.txt -->
<a id='snippet-/sourceFile.txt'></a>
```txt
From Source File
```
<sup><a href='/sourceFile.txt#L1-L7' title='Snippet source file'>snippet source</a> | <a href='#snippet-/sourceFile.txt' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->
```

--------------------------------

### Generated Table of Contents Output

Source: https://context7.com/simoncropp/markdownsnippets/llms.txt

Example of the generated markdown output after processing a document with the `toc` directive. Includes a table of contents with links to document sections.

```markdown
# My Document

<!-- toc -->
## Contents

 * [Introduction](#introduction)
 * [Installation](#installation)
 * [Usage](#usage)
<!-- endToc -->

## Introduction

Some intro text.

```

--------------------------------

### Project Configuration Object

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/MarkdownSnippets.Tool.Tests/CommandRunnerTests.ExcludeMarkdownDirectoriesLong.verified.txt

Defines the target directory and excludes specific markdown directories. Ensure 'CurrentDirectory' and 'dir' are replaced with actual values.

```json
{
  targetDirectory: {CurrentDirectory},
  configInput: {
    ExcludeMarkdownDirectories: [
      dir
    ]
  }
}
```

--------------------------------

### Embed code snippet in markdown

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/MarkdownProcessor/MarkdownProcessorTests.WithMultiLineSnippet.verified.txt

Uses comment tags to define the start and end of a snippet block for the MarkdownSnippets processor.

```markdown
<!-- snippet: theKey -->
```cs
the
long
Snippet
```
<!-- endSnippet -->
```

--------------------------------

### Include Single Line File

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/DirectoryMarkdownProcessor/InPlaceOverwriteNotExists/file.md

Demonstrates how to include the content of a single-line file. Ensure the file exists in the same directory or provide a relative path.

```markdown
include: fileToInclude.txt
```

--------------------------------

### Include Code Snippet

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/DirectoryMarkdownProcessor/InPlaceOverwriteExists/file.md

This snippet demonstrates including code from an external file. Ensure the file exists at the specified path.

```text
Bad Code
```

--------------------------------

### Reference local, relative, and rooted files

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/DirectoryMarkdownProcessorTests.FileSnippetWithHash.verified.txt

Use these patterns to include content from local files into your markdown documentation.

```txt
From Source File
```

```txt
From Source File
```

```txt
From Source File
```

--------------------------------

### Configure Link Formats via CLI

Source: https://context7.com/simoncropp/markdownsnippets/llms.txt

Set the Git hosting platform for snippet source links using the --link-format option.

```bash
# GitHub (default)
mdsnippets --link-format GitHub
# Output: /path/file.cs#L1-L10

# GitLab
mdsnippets --link-format GitLab
# Output: /path/file.cs#L1-10

# Bitbucket
mdsnippets --link-format Bitbucket
# Output: /path/file.cs#lines=1:10

# Azure DevOps
mdsnippets --link-format DevOps
# Output: ?path=/path/file.cs&line=1&lineEnd=10&lineStartColumn=1&lineEndColumn=999

# TFS
mdsnippets --link-format Tfs
# Output: /path/file.cs&line=1&lineEnd=10

# No source links
mdsnippets --link-format None
```

--------------------------------

### Run MarkdownSnippets

Source: https://github.com/simoncropp/markdownsnippets/blob/main/readme.source.md

Execute the tool against a target directory to process markdown files.

```ps
mdsnippets C:\Code\TargetDirectory
```

--------------------------------

### Configure URL Prefix via Configuration

Source: https://context7.com/simoncropp/markdownsnippets/llms.txt

Add a prefix to all snippet links for documentation hosted separately from source code using a JSON configuration file.

```json
{
  "UrlPrefix": "https://github.com/myorg/myrepo/blob/main"
}
```

--------------------------------

### Reference a rooted local file

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/DirectoryMarkdownProcessor/FileSnippet/one.source.md

Include a file using an absolute path from the root directory.

```text
snippet: /sourceFile.txt
```

--------------------------------

### Build and Test Commands for MarkdownSnippets

Source: https://github.com/simoncropp/markdownsnippets/blob/main/claude.md

Common bash commands for building the project, running all tests, targeting specific test projects, and filtering tests by name. Also includes packing the tool.

```bash
# Build everything
dotnet build src

```

```bash
# Run all tests
dotnet test src

```

```bash
# Run a single test project
dotnet test src/Tests/Tests.csproj
dotnet test src/ConfigReader.Tests/ConfigReader.Tests.csproj
dotnet test src/MarkdownSnippets.Tool.Tests/MarkdownSnippets.Tool.Tests.csproj

```

```bash
# Run a specific test by name
dotnet test src/Tests/Tests.csproj --filter "FullyQualifiedName~TestClassName.TestMethodName"

```

```bash
# Pack the tool
dotnet pack src/MarkdownSnippets.Tool/MarkdownSnippets.Tool.csproj

```

--------------------------------

### Integrate with MSBuild

Source: https://context7.com/simoncropp/markdownsnippets/llms.txt

Add the NuGet package to your project file to trigger MarkdownSnippets during the build process.

```xml
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="MarkdownSnippets.MsBuild" Version="*" PrivateAssets="all" />
  </ItemGroup>
</Project>
```

--------------------------------

### Retrieve MIT License text

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/DirectoryMarkdownProcessorTests.UrlSnippet.verified.txt

Displays the full MIT license terms for the project.

```txt
The MIT License (MIT)

Copyright (c) 2013 Simon Cropp

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
```

--------------------------------

### Reference a local file

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/DirectoryMarkdownProcessor/FileSnippet/one.source.md

Include a file located in the current directory.

```text
snippet: sourceFile.txt
```

--------------------------------

### Set URL Prefix via Command Line

Source: https://github.com/simoncropp/markdownsnippets/blob/main/readme.source.md

Use the --url-prefix argument to prepend a string to all snippet links. This is useful for hosting markdown files on a separate site.

```powershell
mdsnippets --url-prefix "TheUrlPrefix"
```

--------------------------------

### Define Snippet File Paths

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/SnippetFileFinderTests.Simple.verified.txt

Use this JSON array to specify the directory paths for snippet files. Ensure the {ProjectDirectory} placeholder is correctly resolved in your environment.

```json
[
  {ProjectDirectory}SnippetFileFinder/Simple/code1.txt,
  {ProjectDirectory}SnippetFileFinder/Simple/code2.txt,
  {ProjectDirectory}SnippetFileFinder/Simple/code3.txt,
  {ProjectDirectory}SnippetFileFinder/Simple/code4.txt
]
```

--------------------------------

### Run DirectoryMarkdownProcessor

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/SnippetExtractor/SnippetExtractorTests.AppendUrlAsSnippetInline.verified.txt

Executes the markdown processor on a target directory with default inclusion settings.

```cs
var processor = new DirectoryMarkdownProcessor(
    "targetDirectory",
    directoryIncludes: _ => true,
    markdownDirectoryIncludes: _ => true,
    snippetDirectoryIncludes: _ => true);
processor.Run();
```

--------------------------------

### Configure MarkdownSnippets settings

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/MarkdownSnippets.Tool.Tests/CommandRunnerTests.UrlsAsSnippetsLong.verified.txt

Defines the target directory and URL-based snippet inputs for the configuration object.

```json
{
  targetDirectory: {CurrentDirectory},
  configInput: {
    UrlsAsSnippets: [
      url
    ]
  }
}
```

--------------------------------

### Configure URL Prefix via CLI

Source: https://context7.com/simoncropp/markdownsnippets/llms.txt

Add a prefix to all snippet links for documentation hosted separately from source code using the command line interface.

```bash
# Command line
mdsnippets --url-prefix "https://github.com/myorg/myrepo/blob/main"
```

--------------------------------

### Configure Multi-Line Header via CLI

Source: https://context7.com/simoncropp/markdownsnippets/llms.txt

Configure a custom multi-line header with newlines for generated markdown files with support for placeholders, using the command line interface.

```bash
# Custom multi-line header with newlines
mdsnippets --header "AUTO-GENERATED\nDo not edit directly\nSource: {relativePath}"
```

--------------------------------

### Import text snippet

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/DirectoryMarkdownProcessor/MissingInclude/one.md

Displays text content imported from source files.

```txt
this is some text to import
```

```txt
this is some text to import
```

```txt
Some code
```

```txt
Some code
```

```txt
Some code
```

```txt
Some code
```

```txt
Some code
```

```txt
Some code
```

--------------------------------

### Include Full File by Name

Source: https://github.com/simoncropp/markdownsnippets/blob/main/readme.source.md

If a snippet with the specified name is not found, the tool will search the target directory for a file matching the name and include its entire content.

```markdown
snippet: license.txt
```

--------------------------------

### Configure MarkdownSnippets with JSON

Source: https://context7.com/simoncropp/markdownsnippets/llms.txt

Define persistent settings for the tool by creating an mdsnippets.json file in the target directory.

```json
{
  "$schema": "https://raw.githubusercontent.com/SimonCropp/MarkdownSnippets/master/schema.json",
  "Convention": "InPlaceOverwrite",
  "ReadOnly": false,
  "LinkFormat": "GitHub",
  "TocLevel": 3,
  "MaxWidth": 80,
  "WriteHeader": true,
  "Header": "GENERATED FILE - Source File: {relativePath}",
  "UrlPrefix": "https://github.com/myorg/myrepo/blob/main",
  "ExcludeDirectories": ["node_modules", "bin", "obj"],
  "ExcludeMarkdownDirectories": ["drafts"],
  "ExcludeSnippetDirectories": ["tests/fixtures"],
  "UrlsAsSnippets": ["https://example.com/shared-snippet.cs"],
  "TocExcludes": ["Contents", "Table of Contents"],
  "TreatMissingAsWarning": false,
  "ValidateContent": true,
  "OmitSnippetLinks": false
}
```

--------------------------------

### C# Snippet 2

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/DirectoryMarkdownProcessorTests.Convention.verified.txt

This is the code from snippet2.

```cs
the code from snippet2
```

--------------------------------

### Include C# snippet from external file

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/SnippetMarkdownHandlingTests.AppendWebSnippet.verified.txt

Displays a specific snippet referenced by a URL and anchor.

```cs
theValue
```

--------------------------------

### Configure Single-Line Header via CLI

Source: https://context7.com/simoncropp/markdownsnippets/llms.txt

Configure a custom single-line header for generated markdown files with support for placeholders, using the command line interface.

```bash
# Custom single-line header
mdsnippets --header "GENERATED FILE - Source: {relativePath}"
```

--------------------------------

### Set Read-Only Attribute

Source: https://github.com/simoncropp/markdownsnippets/blob/main/readme.source.md

Mark generated documentation files as read-only to prevent accidental edits.

```ps
mdsnippets -r true
```

```ps
mdsnippets --read-only true
```

--------------------------------

### Reference a relative local file

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/DirectoryMarkdownProcessor/FileSnippet/one.source.md

Include a file using a relative path from the current directory.

```text
snippet: ./sourceFile.txt
```

--------------------------------

### Max Width Code API

Source: https://github.com/simoncropp/markdownsnippets/blob/main/docs/max-width.md

Instantiate and run the DirectoryMarkdownProcessor with a specified maximum line width.

```csharp
var processor = new DirectoryMarkdownProcessor(
    "targetDirectory",
    maxWidth: 80,
    directoryIncludes: _ => true,
    markdownDirectoryIncludes: _ => true,
    snippetDirectoryIncludes: _ => true);
processor.Run();
```

--------------------------------

### Include Multi-Line File

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/DirectoryMarkdownProcessor/InPlaceOverwriteNotExists/file.md

Shows how to include content from a file that spans multiple lines. This is useful for larger code blocks or text.

```markdown
include: multiLineFileToInclude.txt
```

--------------------------------

### XML Configuration Section

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/SnippetExtractor/SnippetExtractorTests.CanExtractFromXml.verified.txt

Represents a basic XML configuration section. This is often used as a placeholder or a minimal structure in configuration files.

```xml
<configSections/>
```

--------------------------------

### Default directory exclusion logic

Source: https://github.com/simoncropp/markdownsnippets/blob/main/docs/exclusion.md

C# implementation for determining if a directory should be ignored based on common build, cache, or source control patterns.

```cs
namespace MarkdownSnippets;

public static class DefaultDirectoryExclusions
{
    public static bool ShouldExcludeDirectory(string path)
    {
        var suffix = Path
            .GetFileName(path)
            .ToLowerInvariant();
        if (suffix is
            // source control
            ".git" or

            // ide temp files
            ".vs" or
            ".vscode" or
            ".idea" or

            // package cache
            "packages" or
            "node_modules" or

            // build output
            "dist" or
            ".angular" or
            "bin" or
            "obj")
        {
            return true;
        }

        var directory = new DirectoryInfo(path);
        return directory.Attributes.HasFlag(FileAttributes.Hidden);
    }
}
```

--------------------------------

### Max Width Config File

Source: https://github.com/simoncropp/markdownsnippets/blob/main/docs/max-width.md

Configure the maximum characters per line for snippets using a JSON configuration file.

```json
{
  "MaxWidth": 80
}
```

--------------------------------

### Rooted File Path Snippet

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/DirectoryMarkdownProcessor/FileSnippetWithHash/one.source.md

Specifies a file path rooted at the project's root directory. Use '/' to indicate the root.

```markdown
snippet: /source#File.txt
```

--------------------------------

### Set Link Format via Command Line

Source: https://github.com/simoncropp/markdownsnippets/blob/main/readme.source.md

Use the --link-format argument to specify the desired link format for snippet sources. This can be a shorthand like -l.

```powershell
mdsnippets --link-format Bitbucket
```

```powershell
mdsnippets -l Bitbucket
```

--------------------------------

### Include Remote Snippet by URL

Source: https://github.com/simoncropp/markdownsnippets/blob/main/readme.source.md

Snippets can be directly included from a URL by prefixing the URL with `snippet:`. The content at the URL will be downloaded and rendered.

```markdown
snippet: https://raw.githubusercontent.com/SimonCropp/MarkdownSnippets/master/license.txt
```

--------------------------------

### Extract Text Snippet

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/MarkdownProcessor/MarkdownProcessorTests.WithInlineWebSnippetWithViewUrl.verified.txt

This snippet demonstrates basic text extraction. Ensure the file path and snippet key are correctly specified.

```txt
Some code
```

--------------------------------

### BuildLink Logic for Snippet Links

Source: https://github.com/simoncropp/markdownsnippets/blob/main/readme.md

This switch statement determines how snippet source links are constructed based on the specified LinkFormat. The 'None' format throws an exception.

```csharp
switch (linkFormat)
{
    case LinkFormat.GitHub:
        Polyfill.Append(builder, $"{path}#L{snippet.StartLine}-L{snippet.EndLine}");
        return;
    case LinkFormat.Tfs:
        Polyfill.Append(builder, $"{path}&line={snippet.StartLine}&lineEnd={snippet.EndLine}");
        return;
    case LinkFormat.Bitbucket:
        Polyfill.Append(builder, $"{path}#lines={snippet.StartLine}:{snippet.EndLine}");
        return;
    case LinkFormat.GitLab:
        Polyfill.Append(builder, $"{path}#L{snippet.StartLine}-{snippet.EndLine}");
        return;
    case LinkFormat.DevOps:
        Polyfill.Append(builder, $"?path={path}&line={snippet.StartLine}&lineEnd={snippet.EndLine}&lineStartColumn=1&lineEndColumn=999");
        return;
    case LinkFormat.None:
        throw new($"Unknown LinkFormat: {linkFormat}");
}
```

--------------------------------

### Include Text Snippet

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/MarkdownProcessor/MarkdownProcessorTests.WithCommentWebSnippetUpdate.verified.txt

Include a text snippet from a file. Ensure the file exists and the snippet key is correct.

```markdown
<!-- web-snippet: https://raw.githubusercontent.com/SimonCropp/MarkdownSnippets/main/src/Tests/DirectorySnippetExtractor/Case/code1.txt#snipPet -->
```txt
Some code
```
<!-- endSnippet -->
```

--------------------------------

### Use .NET API for Custom Integration

Source: https://context7.com/simoncropp/markdownsnippets/llms.txt

Programmatically extract and process snippets using the MarkdownSnippets library.

```csharp
using MarkdownSnippets;

// Extract snippets from files
var files = Directory.EnumerateFiles(@"C:\Code\MyProject", "*.cs", SearchOption.AllDirectories);
var snippets = FileSnippetExtractor.Read(files);

// Process a directory with full configuration
var processor = new DirectoryMarkdownProcessor(
    targetDirectory: @"C:\Code\MyProject",
    directoryIncludes: path => !path.Contains("node_modules"),
    markdownDirectoryIncludes: path => true,
    snippetDirectoryIncludes: path => !path.Contains("bin"),
    convention: DocumentConvention.InPlaceOverwrite,
    linkFormat: LinkFormat.GitHub,
    writeHeader: true,
    readOnly: false,
    tocLevel: 3,
    maxWidth: 80,
    validateContent: true,
    treatMissingAsWarning: false
);

processor.Run();

// Access extracted snippets
foreach (var snippet in processor.Snippets)
{
    Console.WriteLine($"Snippet: {snippet.Key} from {snippet.Path}");
}
```

--------------------------------

### Configure URLs as snippets via CLI

Source: https://github.com/simoncropp/markdownsnippets/blob/main/readme.md

Use the mdsnippets CLI to include remote files as snippets. The long and short flag variants are functionally equivalent.

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

```ps
mdsnippets -u "https://github.com/SimonCropp/MarkdownSnippets/snippet.cs"
```

--------------------------------

### Display text content with MarkdownSnippets

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/MarkdownProcessor/MarkdownProcessorTests.MixedNewlinesInFile.verified.txt

Use the snippet tag to include content from a specified file in markdown documentation.

```txt
a
b
c
d
```

--------------------------------

### Smart Indentation Trimming

Source: https://github.com/simoncropp/markdownsnippets/blob/main/docs/indentation.md

This demonstrates how MarkdownSnippets trims leading spaces from code snippets. Ensure consistent spacing for proper trimming.

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

--------------------------------

### Import Text Snippet

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/DirectoryMarkdownProcessor/ValidationErrors/one.md

This snippet contains text intended for import. It is presented in a TXT format.

```txt
this is some text to import
```

```txt
this is some text to import
```

--------------------------------

### Configure MarkdownSnippets settings

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/MarkdownSnippets.Tool.Tests/CommandRunnerTests.ExcludeLong.verified.txt

Defines the target directory and directories to exclude during snippet processing.

```json
{
  targetDirectory: {CurrentDirectory},
  configInput: {
    ExcludeDirectories: [
      dir
    ]
  }
}
```

--------------------------------

### Local File Snippet

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/DirectoryMarkdownProcessorTests.Mdx.verified.txt

Includes a snippet from a local file. Ensure the file exists in the same directory.

```markdown
<!-- snippet: sourceFile.txt -->
<a id='snippet-sourceFile.txt'></a>
```txt
From Source File
```
<sup><a href='/sourceFile.txt#L1-L1' title='Snippet source file'>snippet source</a> | <a href='#snippet-sourceFile.txt' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->
```

--------------------------------

### Set URL Prefix via Config File

Source: https://github.com/simoncropp/markdownsnippets/blob/main/readme.source.md

Define a URL prefix for all snippet links by setting the UrlPrefix property in the configuration file. This helps when markdown files are hosted separately from source code.

```json
{
  "UrlPrefix": "TheUrlPrefix"
}
```

--------------------------------

### Include content with singleLineInclude

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/MarkdownProcessor/MarkdownProcessorTests.WithSingleInclude.verified.txt

Use this syntax to inject content from a specified key and path into a markdown file.

```markdown
<!-- singleLineInclude: theKey. path: {CurrentDirectory}thePath -->
```

--------------------------------

### Include Web Content as Snippet

Source: https://context7.com/simoncropp/markdownsnippets/llms.txt

Fetch and include content directly from URLs using the `snippet:` or `web-snippet:` directives. Supports including entire files, specific snippets from remote files, and custom source links.

```markdown
Include entire file from URL:

snippet: https://raw.githubusercontent.com/SimonCropp/MarkdownSnippets/master/license.txt

Include specific snippet from remote file:

web-snippet: https://raw.githubusercontent.com/owner/repo/main/src/Example.cs#MySnippetKey

Include with custom source link:

web-snippet: https://raw.githubusercontent.com/owner/repo/main/src/Example.cs#MySnippet https://github.com/owner/repo/blob/main/src/Example.cs#MySnippet
```

--------------------------------

### Include snippet1 in C#

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/DirectoryMarkdownProcessor/ExplicitFileIncludeWithMergedSnippet/fileToInclude.txt

Displays the content of snippet1 using the .cs language identifier.

```cs
the code from snippet1
```

--------------------------------

### Max Width Command Line

Source: https://github.com/simoncropp/markdownsnippets/blob/main/docs/max-width.md

Set the maximum characters per line for snippets using a command-line argument.

```bash
--max-width 80
```

--------------------------------

### Specify URLs as Snippets via CLI

Source: https://github.com/simoncropp/markdownsnippets/blob/main/readme.source.md

Use the `mdsnippets --urls-as-snippets` command to specify URLs from which snippets should be extracted. Multiple URLs can be space-separated.

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

--------------------------------

### Enable InPlaceOverwrite Convention via Command Line

Source: https://github.com/simoncropp/markdownsnippets/blob/main/readme.md

Configures MarkdownSnippets to use the 'InPlaceOverwrite' convention directly from the command line. This convention merges snippets directly into existing markdown files.

```powershell
mdsnippets -c InPlaceOverwrite
```

```powershell
mdsnippets --convention InPlaceOverwrite
```

--------------------------------

### Configure JSON Schema for mdsnippets.json

Source: https://github.com/simoncropp/markdownsnippets/blob/main/docs/mdsource/config-file.source.md

Add the $schema field to enable IDE code completion and validation for the configuration file.

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

--------------------------------

### Include Snippet by Key

Source: https://github.com/simoncropp/markdownsnippets/blob/main/readme.source.md

Insert a defined snippet into a Markdown file by using the `snippet: KEY` syntax. The KEY corresponds to the name defined in the snippet.

```markdown
snippet: MySnippetName
```

--------------------------------

### Binary file extension list

Source: https://github.com/simoncropp/markdownsnippets/blob/main/docs/exclusion.md

A collection of file extensions treated as binary and excluded from snippet processing.

```cs
"user",
// extra binary
"mdb",
"binlog",
"shp",
"dbf",
"shx",
"pbf",
"map",
"sbn",

//from https://github.com/sindresorhus/binary-extensions/blob/master/binary-extensions.json
"3dm",
"3ds",
"3g2",
"3gp",
"7z",
"a",
"aac",
"adp",
"ai",
"aif",
"aiff",
"alz",
"ape",
"apk",
"appimage",
"ar",
"arj",
"asf",
"au",
"avi",
"bak",
"baml",
"bh",
"bin",
"bk",
"bmp",
"btif",
"bz2",
"bzip2",
"cab",
"caf",
"cgm",
"class",
"cmx",
"cpio",
"cr2",
"cur",
"dat",
"dcm",
"deb",
"dex",
"djvu",
"dll",
"dmg",
"dng",
"doc",
"docm",
"docx",
"dot",
"dotm",
"dra",
"DS_Store",
"dsk",
"dts",
"dtshd",
"dvb",
"dwg",
"dxf",
"ecelp4800",
"ecelp7470",
"ecelp9600",
"egg",
"eol",
"eot",
"epub",
"exe",
"f4v",
"fbs",
"fh",
"fla",
"flac",
"flatpak",
"fli",
"flv",
"fpx",
"fst",
"fvt",
"g3",
"gh",
"gif",
"graffle",
"gz",
"gzip",
"h261",
"h263",
"h264",
"icns",
"ico",
"ief",
"img",
"ipa",
"iso",
"jar",
"jpeg",
"jpg",
"jpgv",
"jpm",
"jxr",
"key",
"ktx",
"lha",
"lib",
"lvp",
"lz",
"lzh",
"lzma",
"lzo",
"m3u",
"m4a",
"m4v",
"mar",
"mdi",
"mht",
"mid",
"midi",
"mj2",
"mka",
"mkv",
"mmr",
"mng",
"mobi",
"mov",
"movie",
"mp3",
"mp4",
"mp4a",
"mpeg",
"mpg",
"mpga",
"mxu",
"nef",
"npx",
"numbers",
"nupkg",
"o",
"oga",
"ogg",
"ogv",
"otf",
"pages",
"pbm",
"pcx",
"pdb",
"pdf",
"pea",
"pgm",
"pic",
"png",
"pnm",
"pot",
"potm",
"potx",
"ppa",
"ppam",
"ppm",
"pps",
"ppsm",
"ppsx",
"ppt",
"pptm",
"pptx",
"psd",
"pya",
"pyc",
"pyo",
"pyv",
"qt",
"rar",
"ras",
"raw",
"resources",
"rgb",
"rip",
"rlc",
"rmf",
"rmvb",
"rpm",
"rtf",
"rz",
"s3m",
"s7z",
"scpt",
"sgi",
"shar",
"snap",
"sil",
"sketch",
"slk",
"smv",
"snk",
"so",
"stl",
"suo",
"sub",
"swf",
"tar",
"tbz",
"tbz2",
"tga",
"tgz",
"thmx",
"tif",
"tiff",
"tlz",
"ttc",
"ttf",
"txz",
"udf",
"uvh",
"uvi",
"uvm",
"uvp",
"uvs",
"uvu",
"viv",
"vob",
"war",
"wav",
"wax",
"wbmp",
"wdp",
"weba",
"webm",
"webp",
"whl",
"wim",
"wm",
"wma",
"wmv",
"wmx",
"woff",
"woff2",
"wrm",
"wvx",
"xbm",
"xif",
"xla",
"xlam",
"xls",
"xlsb",
"xlsm",
"xlsx",
"xlt",
"xltm",
"xltx",
"xm",
"xmind",
"xpi",
"xpm",
"xwd",
"xz",
"z",
"zip",
"zipx"
```

--------------------------------

### Local File Path Snippet

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/DirectoryMarkdownProcessor/FileSnippetWithHash/one.source.md

Specifies a local file path. Ensure the file exists in the same directory as the markdown file.

```markdown
snippet: source#File.txt
```

--------------------------------

### Rooted File Snippet

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/DirectoryMarkdownProcessorTests.Mdx.verified.txt

Includes a snippet from a file using a path rooted at the project's root. This allows referencing files from anywhere in the project.

```markdown
<!-- snippet: /sourceFile.txt -->
<a id='snippet-/sourceFile.txt'></a>
```txt
From Source File
```
<sup><a href='/sourceFile.txt#L1-L1' title='Snippet source file'>snippet source</a> | <a href='#snippet-/sourceFile.txt' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->
```

--------------------------------

### Include file directive

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/DirectoryMarkdownProcessorTests.ExplicitFileIncludeWithMergedSnippet.verified.txt

Use this syntax to include the contents of an external file into the current Markdown document.

```markdown
<!-- include: fileToInclude.txt -->
```

--------------------------------

### Include Full File as Snippet

Source: https://context7.com/simoncropp/markdownsnippets/llms.txt

Reference entire files as snippets in markdown by using the filename as the snippet key. This can include files from subdirectories.

```markdown
Include the license file:

snippet: license.txt

Include a specific file from a subdirectory:

snippet: src/config/settings.json
```

--------------------------------

### Text File Snippet 1

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/MarkdownProcessor/MarkdownProcessorTests.Simple_Overwrite.verified.txt

Content from a text file.

```txt
The
Content
From
File
```

--------------------------------

### Include File with Embedded Code

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/DirectoryMarkdownProcessor/InPlaceOverwriteNotExists/file.md

Illustrates including a file that contains its own code snippets. The content is rendered as is.

```markdown
include: includeWithCode.txt
```

--------------------------------

### Add MarkdownSnippets to Windows Explorer

Source: https://github.com/simoncropp/markdownsnippets/blob/main/readme.source.md

A registry file is provided to add MarkdownSnippets to the Windows Explorer context menu for easier access.

```plaintext
snippet: context-menu.reg
```

--------------------------------

### Local Snippet Reference

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/DirectoryMarkdownProcessorTests.FileSnippetWithWhiteSpace.verified.txt

Reference a local snippet using its filename. Ensure the file is in the same directory.

```markdown
<!-- snippet: sourceFile.txt -->
<a id='snippet-sourceFile.txt'></a>
```txt
From Source File
```
<sup><a href='/sourceFile.txt#L1-L7' title='Snippet source file'>snippet source</a> | <a href='#snippet-sourceFile.txt' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->
```

--------------------------------

### Embed code from file

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/DirectoryMarkdownProcessorTests.InPlaceOverwriteExists.verified.md

Use the include directive to embed the contents of an external file into the markdown output.

```text
The Code
```

--------------------------------

### View Default Header

Source: https://github.com/simoncropp/markdownsnippets/blob/main/docs/header.md

The default header template used by MarkdownSnippets, including the relative path placeholder.

```txt
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.
```

--------------------------------

### Handle SnippetException during configuration deserialization

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/ConfigReader.Tests/ConfigReaderTests.BadJson.verified.txt

This exception occurs when the configuration file contains malformed JSON, such as a missing comma between properties.

```json
{
  "ValidateContent": true
  "Convention": "InPlaceOverwrite"
}
```

--------------------------------

### Configure InPlaceOverwrite Convention

Source: https://github.com/simoncropp/markdownsnippets/blob/main/readme.source.md

Set the processing convention to InPlaceOverwrite using command line arguments or a configuration file.

```ps
mdsnippets -c InPlaceOverwrite
```

```ps
mdsnippets --convention InPlaceOverwrite
```

```json
{
  "Convention": "InPlaceOverwrite"
}
```

--------------------------------

### Specify URLs as Snippets via CLI (Shorthand)

Source: https://github.com/simoncropp/markdownsnippets/blob/main/readme.source.md

The shorthand `-u` flag can be used with `mdsnippets` to specify URLs for extracting snippets. This is an alternative to the `--urls-as-snippets` flag.

```powershell
mdsnippets -u "https://github.com/SimonCropp/MarkdownSnippets/snippet.cs"
```

--------------------------------

### Configure TOC levels via CLI

Source: https://github.com/simoncropp/markdownsnippets/blob/main/docs/mdsource/toc.source.md

Sets the maximum heading level to include in the generated table of contents.

```ps
mdsnippets --toc-level 5
```

--------------------------------

### Use Include File in Markdown

Source: https://context7.com/simoncropp/markdownsnippets/llms.txt

Use the `include:` directive in markdown files to insert content from a defined include file. This is useful for creating reusable markdown sections.

```markdown
# Documentation

include: doc-index

See the links above for more information.
```

--------------------------------

### Relative Local File Path Snippet

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/DirectoryMarkdownProcessor/FileSnippetWithHash/one.source.md

Specifies a file path relative to the current directory. Use './' for the current directory.

```markdown
snippet: ./source#File.txt
```

--------------------------------

### Run MarkdownSnippets CLI

Source: https://context7.com/simoncropp/markdownsnippets/llms.txt

Run MarkdownSnippets against a target directory to process all markdown files and inject code snippets. Supports processing the current directory, a specific directory, using the InPlaceOverwrite convention, and marking output files as read-only.

```bash
# Process current directory
mdsnippets

# Process specific directory
mdsnippets C:\Code\MyProject

# Use InPlaceOverwrite convention
mdsnippets -c InPlaceOverwrite

# Mark output files as read-only
mdsnippets --read-only true
```

--------------------------------

### Mixed Tab and Space Indentation Behavior

Source: https://github.com/simoncropp/markdownsnippets/blob/main/docs/mdsource/indentation.source.md

Demonstrates that indentation trimming fails when tabs and spaces are mixed in the same snippet.

```text
••// begin-snippet MySnippetNamea
••Line one of the snippet
⇥⇥Line one of the snippet
••// end-snippet
```

```text
Line one of the snippet
⇥⇥Line one of the snippet
```

--------------------------------

### Render snippet in markdown

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/MarkdownProcessor/MarkdownProcessorTests.WithSingleSnippet.verified.txt

Displays the standard markdown syntax used to inject a snippet into a document.

```markdown
<!-- snippet: theKey -->
```cs
Snippet
```
<!-- endSnippet -->
```

--------------------------------

### Set Max Width via CLI

Source: https://context7.com/simoncropp/markdownsnippets/llms.txt

Configure the maximum width for code snippets using the command line interface. This setting affects how code blocks are rendered.

```bash
mdsnippets --max-width 80
```

--------------------------------

### Define Include File for Markdown

Source: https://context7.com/simoncropp/markdownsnippets/llms.txt

Define reusable markdown content blocks using include files with the `.include.md` extension. These files can contain lists, links, or other markdown elements.

```markdown
* [Getting Started](/docs/getting-started.md)
* [API Reference](/docs/api.md)
* [Configuration](/docs/config.md)
```

--------------------------------

### Include Specific Remote Snippet by URL and Snippet Name

Source: https://github.com/simoncropp/markdownsnippets/blob/main/readme.source.md

Use `web-snippet:` to reference remote content and specify a particular snippet within that content using a `#snippetName` anchor. This allows for more granular inclusion of remote code.

```markdown
web-snippet: https://raw.githubusercontent.com/SimonCropp/MarkdownSnippets/main/src/Tests/DirectorySnippetExtractor/Case/code1.txt#snipPet
```

--------------------------------

### Exclude directories via CLI

Source: https://github.com/simoncropp/markdownsnippets/blob/main/docs/exclusion.md

Use command-line flags to ignore directories containing specific patterns during discovery.

```ps
mdsnippets -e foo:bar
```

```ps
mdsnippets --exclude-snippet-directories foo:bar
```

```ps
mdsnippets --exclude-markdown-directories foo:bar
```

--------------------------------

### Define Snippets using begin-snippet/end-snippet

Source: https://context7.com/simoncropp/markdownsnippets/llms.txt

Define named code snippets using convention-based comments in C# files. These snippets can be referenced from markdown documents.

```csharp
// Using begin-snippet/end-snippet comments
// begin-snippet: MySnippetName
public class Example
{
    public void DoSomething()
    {
        Console.WriteLine("Hello, World!");
    }
}
// end-snippet
```

--------------------------------

### Display Long Snippet in C#

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/MarkdownProcessor/MarkdownProcessorTests.WithIndentedMultiLineSnippet.verified.txt

This snippet demonstrates how to display a long code snippet in C#.

```cs
the
long
Snippet
```

--------------------------------

### Apply Custom Header in mdsnippets

Source: https://github.com/simoncropp/markdownsnippets/blob/main/docs/mdsource/header.source.md

Use the --header flag to define a custom string. The {relativePath} placeholder is automatically replaced with the path of the source file.

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

--------------------------------

### Relative Local Snippet Reference

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/DirectoryMarkdownProcessorTests.FileSnippetWithWhiteSpace.verified.txt

Reference a local snippet using a relative path. This is useful for snippets in subdirectories.

```markdown
<!-- snippet: ./sourceFile.txt -->
<a id='snippet-./sourceFile.txt'></a>
```txt
From Source File
```
<sup><a href='#snippet-./sourceFile.txt' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->
```

--------------------------------

### Add Metadata to Snippet for Animations

Source: https://github.com/simoncropp/markdownsnippets/blob/main/readme.source.md

Metadata within parentheses can be used for various rendering purposes, such as applying animations in presentation tools like Sli.dev.

```csharp
// begin-snippet: EncapsulateVariable({*|2})
Console.WriteLine("Hello, World");
// end-snippet
```

--------------------------------

### Reference snippet in Markdown

Source: https://github.com/simoncropp/markdownsnippets/blob/main/readme.md

Include a defined snippet in a Markdown file using the snippet key.

```markdown
Some blurb about the below snippet
snippet: MySnippetName
```

--------------------------------

### Enable InPlaceOverwrite Convention via Config File

Source: https://github.com/simoncropp/markdownsnippets/blob/main/readme.md

Sets the 'Convention' to 'InPlaceOverwrite' within the mdsnippets.json configuration file. This enables the direct merging of snippets into markdown files.

```json
{
  "Convention": "InPlaceOverwrite"
}
```

--------------------------------

### Configure InPlaceOverwrite Convention

Source: https://github.com/simoncropp/markdownsnippets/blob/main/docs/config-file.md

Use this JSON to set the 'InPlaceOverwrite' convention for MarkdownSnippets. This convention overwrites the source markdown file with the snippet content.

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

--------------------------------

### Read C# Snippets from Files

Source: https://github.com/simoncropp/markdownsnippets/blob/main/docs/api.md

Use `FileSnippetExtractor.Read` to extract code snippets from a collection of C# files. Ensure the files are correctly enumerated.

```cs
var files = Directory.EnumerateFiles(@"C:\path", "*.cs", SearchOption.AllDirectories);

var snippets = FileSnippetExtractor.Read(files);
```

--------------------------------

### Exclude Directories via CLI

Source: https://context7.com/simoncropp/markdownsnippets/llms.txt

Use command-line flags to filter directories during snippet or markdown discovery.

```bash
# Exclude directories from both snippet and markdown discovery
mdsnippets --exclude-directories foo:bar

# Exclude directories from snippet discovery only
mdsnippets --exclude-snippet-directories tests:samples

# Exclude directories from markdown discovery only
mdsnippets --exclude-markdown-directories drafts:archive
```

--------------------------------

### Windows Explorer Context Menu Registry Script

Source: https://github.com/simoncropp/markdownsnippets/blob/main/readme.md

This registry script adds MarkdownSnippets to the Windows Explorer context menu for directories. It allows running mdsnippets on a selected directory.

```reg
Windows Registry Editor Version 5.00
[HKEY_CLASSES_ROOT\Directory\Shell]
@="none"
[HKEY_CLASSES_ROOT\Directory\shell\mdsnippets]
"MUIVerb"="run mdsnippets"
"Position"="bottom"
[HKEY_CLASSES_ROOT\Directory\Background\shell\mdsnippets]
"MUIVerb"="run mdsnippets"
"Position"="bottom"
[HKEY_CLASSES_ROOT\Directory\shell\mdsnippets\command]
@="cmd.exe /c mdsnippets \"%V\""
[HKEY_CLASSES_ROOT\Directory\Background\shell\mdsnippets\command]
@="cmd.exe /c mdsnippets \"%V\""
```

--------------------------------

### Define Snippet with Convention Comment

Source: https://github.com/simoncropp/markdownsnippets/blob/main/readme.source.md

Use `begin-snippet:` and `end-snippet:` comments to define a named code snippet. The text between these comments is captured as the snippet content.

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

--------------------------------

### Read snippets from files

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/SnippetExtractor/SnippetExtractorTests.AppendUrlAsSnippetInline.verified.txt

Extracts snippets from a collection of files using FileSnippetExtractor.

```cs
// ReSharper disable UnusedVariable

class Usage
{
    static void ReadingFiles()
    {

        var files = Directory.EnumerateFiles(@"C:/path", "*.cs", SearchOption.AllDirectories);

        var snippets = FileSnippetExtractor.Read(files);

    }

    static void DirectoryMarkdownProcessorRun()
    {

        var processor = new DirectoryMarkdownProcessor(
            "targetDirectory",
            directoryIncludes: _ => true,
            markdownDirectoryIncludes: _ => true,
            snippetDirectoryIncludes: _ => true);
        processor.Run();

    }

    static void DirectoryMarkdownProcessorRunMaxWidth()
    {

        var processor = new DirectoryMarkdownProcessor(
            "targetDirectory",
            maxWidth: 80,
            directoryIncludes: _ => true,
            markdownDirectoryIncludes: _ => true,
            snippetDirectoryIncludes: _ => true);
        processor.Run();

    }
}
```

```cs
var files = Directory.EnumerateFiles(@"C:/path", "*.cs", SearchOption.AllDirectories);

var snippets = FileSnippetExtractor.Read(files);
```

--------------------------------

### Default Directory Exclusions

Source: https://github.com/simoncropp/markdownsnippets/blob/main/docs/mdsource/exclusion.source.md

This snippet refers to the default directory exclusion rules used by mdsnippets.

```csharp
snippet: DefaultDirectoryExclusions.cs
```

--------------------------------

### Add Expressive Code Metadata

Source: https://context7.com/simoncropp/markdownsnippets/llms.txt

Include metadata within snippet tags to control rendering features like titles, highlighting, and animations.

```csharp
// Add title and line highlighting metadata
// begin-snippet: HelloWorld(title=Program.cs {1})
Console.WriteLine("Hello, World");
// end-snippet

// Add animation metadata for presentation tools
// begin-snippet: CodeAnimation({*|2})
var x = 1;
var y = 2;
// end-snippet
```

```markdown
```csharp title=Program.cs {1}
Console.WriteLine("Hello, World");
```
```

--------------------------------

### Markdown with TOC placeholder

Source: https://github.com/simoncropp/markdownsnippets/blob/main/docs/toc.md

This markdown includes the 'toc' placeholder which will be replaced by a generated table of contents.

```markdown
# Title

toc

## Heading 1

Text1

## Heading 1

Text2
```

--------------------------------

### Add Metadata to Snippet with Title

Source: https://github.com/simoncropp/markdownsnippets/blob/main/readme.source.md

Use Expressive Code syntax to add metadata, such as a title, to a snippet. The metadata is processed and can influence rendering in compatible documentation systems.

```csharp
// begin-snippet: HelloWorld(title=Program.cs {1})
Console.WriteLine("Hello, World");
// end-snippet
```

--------------------------------

### Configure SourceTransform Convention

Source: https://github.com/simoncropp/markdownsnippets/blob/main/docs/config-file.md

Use this JSON to set the 'SourceTransform' convention for MarkdownSnippets. This convention transforms the source markdown file based on snippet content.

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

--------------------------------

### Result object structure

Source: https://github.com/simoncropp/markdownsnippets/blob/main/src/Tests/MarkdownProcessor/MarkdownProcessorTests.WithIndentedSnippetMultipleSpaces.verified.txt

Represents the metadata for processed snippets including key, language, and file location.

```json
{
  UsedSnippets: [
    {
      Key: theKey,
      Language: cs,
      Value: Snippet,
      Error: ,
      FileLocation: thePath(1-2),
      IsInError: false
    }
  ],
  result:
before

        <!-- snippet: theKey -->
        ```cs
        Snippet
        ```
        <!-- endSnippet -->

after
}
```

--------------------------------

### Set Max Width Programmatically

Source: https://context7.com/simoncropp/markdownsnippets/llms.txt

Configure the maximum width for code snippets using the programmatic API in C#. This setting affects how code blocks are rendered.

```csharp
// Programmatic API
var processor = new DirectoryMarkdownProcessor(
    "targetDirectory",
    maxWidth: 80,
    directoryIncludes: _ => true,
    markdownDirectoryIncludes: _ => true,
    snippetDirectoryIncludes: _ => true
);
processor.Run();
```

--------------------------------

### Binary File Extensions Exclusion

Source: https://github.com/simoncropp/markdownsnippets/blob/main/docs/mdsource/exclusion.source.md

This snippet lists file extensions that are considered binary and thus excluded from processing.

```plaintext
snippet: BinaryFileExtensions
```

--------------------------------

### Define Snippet with C# Region

Source: https://github.com/simoncropp/markdownsnippets/blob/main/readme.source.md

Named C# regions can also be used to define code snippets, with the region name serving as the snippet key. Ensure 'enter outlining mode when files open' is disabled in Visual Studio to prevent regions from collapsing.

```csharp
#region MySnippetName
My Snippet Code
#endregion
```