diff --git a/docs/api.md b/docs/api.md
index 93a30494..5b54bca9 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -16,18 +16,20 @@ https://nuget.org/packages/MarkdownSnippets/ [![NuGet Status](http://img.shields
## Reading snippets from files
+
```cs
var files = Directory.EnumerateFiles(@"C:\path", "*.cs", SearchOption.AllDirectories);
var snippets = FileSnippetExtractor.Read(files);
```
-[snippet source](/src/Tests/Snippets/Usage.cs#L9-L15)
+[snippet source](/src/Tests/Snippets/Usage.cs#L9-L15) / [anchor](#snippet-readingfilessimple)
## Reading snippets from a directory structure
+
```cs
// extract snippets from files
var snippetExtractor = new DirectorySnippetExtractor(
@@ -36,13 +38,14 @@ var snippetExtractor = new DirectorySnippetExtractor(
!dirPath.EndsWith("obj"));
var snippets = snippetExtractor.ReadSnippets(@"C:\path");
```
-[snippet source](/src/Tests/Snippets/Usage.cs#L30-L39)
+[snippet source](/src/Tests/Snippets/Usage.cs#L30-L39) / [anchor](#snippet-readingdirectorysimple)
## Full Usage
+
```cs
// setup version convention and extract snippets from files
var snippetExtractor = new DirectorySnippetExtractor();
@@ -68,7 +71,7 @@ using (var writer = File.CreateText(@"C:\path\outputMarkdownFile.md"))
var usedSnippets = result.UsedSnippets;
}
```
-[snippet source](/src/Tests/Snippets/Usage.cs#L44-L70)
+[snippet source](/src/Tests/Snippets/Usage.cs#L44-L70) / [anchor](#snippet-markdownprocessingsimple)
diff --git a/docs/config-file.md b/docs/config-file.md
index c94695e8..44922376 100644
--- a/docs/config-file.md
+++ b/docs/config-file.md
@@ -12,6 +12,7 @@ The [dotnet tool](/MarkdownSnippets#installation) and the [MSBuild Task](msbuild
Add a file named `mdsnippets.json` at the target directory with the following content:
+
```json
{
"ReadOnly": false,
@@ -24,5 +25,5 @@ Add a file named `mdsnippets.json` at the target directory with the following co
"Header": "GENERATED FILE - Source File: {relativePath}"
}
```
-[snippet source](/src/ConfigReader.Tests/sampleConfig.json#L1-L10)
+[snippet source](/src/ConfigReader.Tests/sampleConfig.json#L1-L10) / [anchor](#snippet-sampleConfig.json)
diff --git a/readme.md b/readme.md
index e26dd16d..837ad21e 100644
--- a/readme.md
+++ b/readme.md
@@ -98,10 +98,15 @@ snippet: MySnippetName
The resulting markdown will be:
+
Some blurb about the below snippet
+
```
My Snippet Code
```
+ [snippet source](/relativeUrlToFile#L1-L11) / [anchor](#snippet-MySnippetName)
+
+
### Including full files
@@ -156,6 +161,7 @@ If a line is `toc` it will be replaced with a table of contents
So if a markdown document contains the following:
+
```txt
# Title
@@ -169,12 +175,13 @@ Text1
Text2
```
-[snippet source](/docs/mdsource/toc/tocBefore.txt#L1-L11)
+[snippet source](/docs/mdsource/toc/tocBefore.txt#L1-L11) / [anchor](#snippet-tocBefore.txt)
The result will be rendered:
+
```txt
# Title
@@ -193,7 +200,7 @@ Text1
Text2
```
-[snippet source](/docs/mdsource/toc/tocAfter.txt#L1-L16)
+[snippet source](/docs/mdsource/toc/tocAfter.txt#L1-L16) / [anchor](#snippet-tocAfter.txt)
@@ -221,13 +228,14 @@ mdsnippets --toc-excludes heading1:heading2
When a .md file is written, a header is include. The default header is:
+
```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.
```
-[snippet source](/src/Tests/HeaderWriterTests.DefaultHeader.approved.txt#L1-L4)
+[snippet source](/src/Tests/HeaderWriterTests.DefaultHeader.approved.txt#L1-L4) / [anchor](#snippet-HeaderWriterTests.DefaultHeader.approved.txt)
To disable the header use `--write-header`
@@ -254,6 +262,7 @@ mdsnippets --header "GENERATED FILE\nSource File: {relativePath}"
Defines the format of `snippet source` links that appear under each snippet.
+
```cs
namespace MarkdownSnippets
{
@@ -264,10 +273,11 @@ namespace MarkdownSnippets
}
}
```
-[snippet source](/src/MarkdownSnippets/Processing/LinkFormat.cs#L1-L8)
+[snippet source](/src/MarkdownSnippets/Processing/LinkFormat.cs#L1-L8) / [anchor](#snippet-LinkFormat.cs)
+
```cs
if (linkFormat == LinkFormat.GitHub)
{
@@ -278,7 +288,7 @@ if (linkFormat == LinkFormat.Tfs)
return $"{path}&line={snippet.StartLine}&lineEnd={snippet.EndLine}";
}
```
-[snippet source](/src/MarkdownSnippets/Processing/SnippetMarkdownHandling.cs#L50-L59)
+[snippet source](/src/MarkdownSnippets/Processing/SnippetMarkdownHandling.cs#L72-L81) / [anchor](#snippet-buildlink)
diff --git a/readme.source.md b/readme.source.md
index dfcace2e..4a799dff 100644
--- a/readme.source.md
+++ b/readme.source.md
@@ -78,10 +78,15 @@ snippet: MySnippetName
The resulting markdown will be:
+
Some blurb about the below snippet
+
```
My Snippet Code
```
+ [snippet source](/relativeUrlToFile#L1-L11) / [anchor](#snippet-MySnippetName)
+
+
### Including full files
diff --git a/src/ConfigReader.Tests/ConfigReader.Tests.csproj b/src/ConfigReader.Tests/ConfigReader.Tests.csproj
index a7ab5df8..a8e5226d 100644
--- a/src/ConfigReader.Tests/ConfigReader.Tests.csproj
+++ b/src/ConfigReader.Tests/ConfigReader.Tests.csproj
@@ -11,12 +11,12 @@
-
+
-
+
diff --git a/src/ConfigReader.Tests/ConfigReaderTests.cs b/src/ConfigReader.Tests/ConfigReaderTests.cs
index 579f1bad..13a00b21 100644
--- a/src/ConfigReader.Tests/ConfigReaderTests.cs
+++ b/src/ConfigReader.Tests/ConfigReaderTests.cs
@@ -1,5 +1,4 @@
using System.IO;
-using ObjectApproval;
using Xunit;
using Xunit.Abstractions;
diff --git a/src/ConfigReader/ConfigReader.csproj b/src/ConfigReader/ConfigReader.csproj
index 686ab49c..77508215 100644
--- a/src/ConfigReader/ConfigReader.csproj
+++ b/src/ConfigReader/ConfigReader.csproj
@@ -6,7 +6,7 @@
-
+
\ No newline at end of file
diff --git a/src/Directory.Build.props b/src/Directory.Build.props
index ef7f38bc..617f2d55 100644
--- a/src/Directory.Build.props
+++ b/src/Directory.Build.props
@@ -2,7 +2,7 @@
CS1591
- 16.1.1
+ 16.2.0
Markdown, Snippets, mdsnippets, documentation, MarkdownSnippets
Extracts snippets from code files and merges them into markdown documents.
diff --git a/src/MarkdownSnippets.MsBuild/MarkdownSnippets.MsBuild.csproj b/src/MarkdownSnippets.MsBuild/MarkdownSnippets.MsBuild.csproj
index 86c896a4..82e50cd4 100644
--- a/src/MarkdownSnippets.MsBuild/MarkdownSnippets.MsBuild.csproj
+++ b/src/MarkdownSnippets.MsBuild/MarkdownSnippets.MsBuild.csproj
@@ -17,6 +17,6 @@
-
+
\ No newline at end of file
diff --git a/src/MarkdownSnippets.Tool/MarkdownSnippets.Tool.csproj b/src/MarkdownSnippets.Tool/MarkdownSnippets.Tool.csproj
index d1ebb197..727c766b 100644
--- a/src/MarkdownSnippets.Tool/MarkdownSnippets.Tool.csproj
+++ b/src/MarkdownSnippets.Tool/MarkdownSnippets.Tool.csproj
@@ -15,6 +15,6 @@
-
+
\ No newline at end of file
diff --git a/src/MarkdownSnippets/MarkdownSnippets.csproj b/src/MarkdownSnippets/MarkdownSnippets.csproj
index dace9273..6fa3f8f8 100644
--- a/src/MarkdownSnippets/MarkdownSnippets.csproj
+++ b/src/MarkdownSnippets/MarkdownSnippets.csproj
@@ -6,6 +6,6 @@
-
+
\ No newline at end of file
diff --git a/src/MarkdownSnippets/Processing/SnippetMarkdownHandling.cs b/src/MarkdownSnippets/Processing/SnippetMarkdownHandling.cs
index 73c32260..dec2f6bb 100644
--- a/src/MarkdownSnippets/Processing/SnippetMarkdownHandling.cs
+++ b/src/MarkdownSnippets/Processing/SnippetMarkdownHandling.cs
@@ -22,29 +22,51 @@ public SnippetMarkdownHandling(string rootDirectory, LinkFormat linkFormat)
public void AppendGroup(string key, IEnumerable snippets, Action appendLine)
{
+ Guard.AgainstNullAndEmpty(key, nameof(key));
Guard.AgainstNull(snippets, nameof(snippets));
Guard.AgainstNull(appendLine, nameof(appendLine));
-
+ uint index = 0;
foreach (var snippet in snippets)
{
- WriteSnippet(appendLine, snippet);
+ WriteSnippet(appendLine, snippet, index);
+ index++;
}
}
- void WriteSnippet(Action appendLine, Snippet snippet)
+ void WriteSnippet(Action appendLine, Snippet snippet, uint index)
{
- appendLine($"```{snippet.Language}");
- appendLine(snippet.Value);
- appendLine("```");
+ string anchor;
+ if (index == 0)
+ {
+ anchor = $"snippet-{snippet.Key}";
+ }
+ else
+ {
+ anchor = $"snippet-{snippet.Key}-{index}";
+ }
- if (snippet.Path != null)
+ appendLine($"");
+ if (snippet.Path == null)
+ {
+ WriteSnippetValueAndLanguage(appendLine, snippet);
+ appendLine($"[anchor](#{anchor})");
+ }
+ else
{
var path = snippet.Path.Replace(@"\", "/").Substring(rootDirectory.Length);
- var link = BuildLink(snippet, path);
- appendLine($"[snippet source]({link})");
+ var sourceLink = BuildLink(snippet, path);
+ WriteSnippetValueAndLanguage(appendLine, snippet);
+ appendLine($"[snippet source]({sourceLink}) / [anchor](#{anchor})");
}
}
+ private static void WriteSnippetValueAndLanguage(Action appendLine, Snippet snippet)
+ {
+ appendLine($"```{snippet.Language}");
+ appendLine(snippet.Value);
+ appendLine("```");
+ }
+
string BuildLink(Snippet snippet, string path)
{
#region BuildLink
diff --git a/src/Tests/Console/CommandRunnerTests.cs b/src/Tests/Console/CommandRunnerTests.cs
index 85715db9..d66d733b 100644
--- a/src/Tests/Console/CommandRunnerTests.cs
+++ b/src/Tests/Console/CommandRunnerTests.cs
@@ -1,6 +1,5 @@
using System;
using System.IO;
-using ObjectApproval;
using Xunit;
using Xunit.Abstractions;
diff --git a/src/Tests/DirectoryMarkdownProcessor/DirectoryMarkdownProcessorTests.Convention.approved.txt b/src/Tests/DirectoryMarkdownProcessor/DirectoryMarkdownProcessorTests.Convention.approved.txt
index b25a56ca..3dc9799c 100644
--- a/src/Tests/DirectoryMarkdownProcessor/DirectoryMarkdownProcessorTests.Convention.approved.txt
+++ b/src/Tests/DirectoryMarkdownProcessor/DirectoryMarkdownProcessorTests.Convention.approved.txt
@@ -1,8 +1,10 @@
\one.md
+
```.cs
the code from snippet1
```
+[anchor](#snippet-snippet1)
@@ -11,9 +13,11 @@ snippet: snippet1
\two.md
+
```.cs
the code from snippet2
```
+[anchor](#snippet-snippet2)
diff --git a/src/Tests/DirectorySnippetExtractor/DirectorySnippetExtractorTests.cs b/src/Tests/DirectorySnippetExtractor/DirectorySnippetExtractorTests.cs
index 13f718b8..4942199d 100644
--- a/src/Tests/DirectorySnippetExtractor/DirectorySnippetExtractorTests.cs
+++ b/src/Tests/DirectorySnippetExtractor/DirectorySnippetExtractorTests.cs
@@ -3,7 +3,6 @@
using System.IO;
using System.Linq;
using MarkdownSnippets;
-using ObjectApproval;
using Xunit;
using Xunit.Abstractions;
diff --git a/src/Tests/SnippetExtractor/SnippetExtractorTests.AppendUrlAsSnippet.approved.txt b/src/Tests/SnippetExtractor/SnippetExtractorTests.AppendUrlAsSnippet.approved.txt
index 93b6d96b..de453ca5 100644
--- a/src/Tests/SnippetExtractor/SnippetExtractorTests.AppendUrlAsSnippet.approved.txt
+++ b/src/Tests/SnippetExtractor/SnippetExtractorTests.AppendUrlAsSnippet.approved.txt
@@ -2,7 +2,7 @@
{
Key: 'appveyor.yml',
Language: 'yml',
- Value: 'image: Visual Studio 2019\nskip_commits:\n message: /Merge pull request.*/\nbuild_script:\n- ps: >-\n dotnet build src --configuration Release\n\n dotnet test src --configuration Release --no-build --no-restore\ntest: off\nartifacts:\n- path: nugets\*.nupkg',
+ Value: 'image: Visual Studio 2019\nskip_commits:\n message: /doco|Merge pull request.*/\nbuild_script:\n- ps: >-\n dotnet build src --configuration Release\n\n dotnet test src --configuration Release --no-build --no-restore\ntest: off\nartifacts:\n- path: nugets\*.nupkg',
Error: null,
FileLocation: null,
IsInError: false
diff --git a/src/Tests/SnippetExtractor/SnippetExtractorTests.cs b/src/Tests/SnippetExtractor/SnippetExtractorTests.cs
index 3a1bf077..f74fec85 100644
--- a/src/Tests/SnippetExtractor/SnippetExtractorTests.cs
+++ b/src/Tests/SnippetExtractor/SnippetExtractorTests.cs
@@ -4,7 +4,6 @@
using System.Linq;
using System.Threading.Tasks;
using MarkdownSnippets;
-using ObjectApproval;
using Xunit;
using Xunit.Abstractions;
diff --git a/src/Tests/SnippetMarkdownHandlingTests.AppendGroup.approved.txt b/src/Tests/SnippetMarkdownHandlingTests.AppendGroup.approved.txt
index 1a9a4d06..9ebebbc6 100644
--- a/src/Tests/SnippetMarkdownHandlingTests.AppendGroup.approved.txt
+++ b/src/Tests/SnippetMarkdownHandlingTests.AppendGroup.approved.txt
@@ -1,4 +1,5 @@
-```thelanguage
+
+```thelanguage
theValue
```
-[snippet source](thePath#L1-L2)
+[snippet source](thePath#L1-L2) / [anchor](#snippet-thekey)
diff --git a/src/Tests/SnippetVerifier.cs b/src/Tests/SnippetVerifier.cs
index 6631a9d9..d4dfd214 100644
--- a/src/Tests/SnippetVerifier.cs
+++ b/src/Tests/SnippetVerifier.cs
@@ -2,7 +2,6 @@
using System.IO;
using System.Text;
using MarkdownSnippets;
-using ObjectApproval;
static class SnippetVerifier
{
diff --git a/src/Tests/TestBase.cs b/src/Tests/TestBase.cs
index 2f389c8f..a11870cf 100644
--- a/src/Tests/TestBase.cs
+++ b/src/Tests/TestBase.cs
@@ -1,5 +1,5 @@
-using ObjectApproval;
-using Xunit.Abstractions;
+using Xunit.Abstractions;
+using ObjectApproval;
public class TestBase:
XunitLoggingBase
diff --git a/src/Tests/Tests.csproj b/src/Tests/Tests.csproj
index bc7e2e5b..cab8dac0 100644
--- a/src/Tests/Tests.csproj
+++ b/src/Tests/Tests.csproj
@@ -7,14 +7,14 @@
-
+
-
+
PreserveNewest