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.
Document Convention
There are two approaches scanning and modifying markdown files.
SourceTransform
This is the default.
source.md file
The file convention recursively scans the target directory for all *.source.md files. Once snippets are merged 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.
mdsource directory
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.
InPlaceOverwrite
Recursively scans the target directory for all *.md files and merges snippets into those files.
Ensure "WriteHeader": false is used in mdsnippets.json.
Ensure "ReadOnly": false is used in mdsnippets.json.
Ensure using the current stable version and a docs generation has run.
Delete all .source.md files.
Modify mdsnippets.json to add "Convention": "InPlaceOverwrite".
Run the docs generation.
Mark resulting files as read only
To mark the resulting documents files as read only use -r or --read-only.
This can be helpful in preventing incorrectly editing the documents file instead of the .source. file conventions.
mdsnippets-rtrue
mdsnippets--read-onlytrue
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.
Link format None will omit the source link but still keep the snippet anchor.
OmitSnippetLinks
The links below a snippet can be omitted.
Command line
mdsnippets--omit-snippet-linkstrue
Config file
{
"OmitSnippetLinks": true
}
How links are constructed
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}";
}
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.
Command line
mdsnippets--url-prefix"TheUrlPrefix"
Config file
{
"UrlPrefix": "TheUrlPrefix"
}
Add to Windows Explorer
Use src/context-menu.reg to add MarkdownSnippets to the Windows Explorer context menu.
客服电话
APP下载
官方微信
请发表评论