api.md

Library Usage

NuGet package

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

Reading snippets from files

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

var snippets = FileSnippetExtractor.Read(files);

^{snippet source | anchor}

Reading snippets from a directory structure

// extract snippets from files
var snippetExtractor = new DirectorySnippetExtractor(
    // all directories except bin and obj
    directoryFilter: dirPath => !dirPath.EndsWith("bin") &&
                                !dirPath.EndsWith("obj"));
var snippets = snippetExtractor.ReadSnippets(@"C:\path");

^{snippet source | anchor}

Full Usage

var directory = @"C:\path";

// extract snippets from files
var snippetExtractor = new DirectorySnippetExtractor();
var snippets = snippetExtractor.ReadSnippets(directory);

// extract includes from files
var includeFinder = new IncludeFinder();
var includes = includeFinder.ReadIncludes(directory);

// Merge with some markdown text
var markdownProcessor = new MarkdownProcessor(
    convention: DocumentConvention.SourceTransform,
    snippets: snippets.Lookup,
    includes: includes,
    appendSnippets: SimpleSnippetMarkdownHandling.Append,
    snippetSourceFiles: new List<string>(),
    tocLevel: 2,
    writeHeader: true,
    rootDirectory: directory,
    validateContent: true);

var path = @"C:\path\inputMarkdownFile.md";
using var reader = File.OpenText(path);
using var writer = File.CreateText(@"C:\path\outputMarkdownFile.md");
var result = markdownProcessor.Apply(reader, writer, path);
// snippets that the markdown file expected but did not exist in the input snippets
var missingSnippets = result.MissingSnippets;

// snippets that the markdown file used
var usedSnippets = result.UsedSnippets;

^{snippet source | anchor}

Ignored paths

To change conventions manipulate lists MarkdownSnippets.Exclusions.ExcludedDirectorySuffixes and MarkdownSnippets.Exclusions.ExcludedFileExtensions.