Add snippet anchor (#76)

docs/api.md

@@ -16,18 +16,20 @@ https://nuget.org/packages/MarkdownSnippets/ [![NuGet Status](http://img.shields
 ## Reading snippets from files
 
 <!-- snippet: ReadingFilesSimple -->
+<a id='snippet-readingfilessimple'/></a>
 ```cs
 var files = Directory.EnumerateFiles(@"C:\path", "*.cs", SearchOption.AllDirectories);
 
 var snippets = FileSnippetExtractor.Read(files);
 ```
-<sup>[snippet source](/src/Tests/Snippets/Usage.cs#L9-L15)</sup>
+<sup>[snippet source](/src/Tests/Snippets/Usage.cs#L9-L15) / [anchor](#snippet-readingfilessimple)</sup>
 <!-- endsnippet -->
 
 
 ## Reading snippets from a directory structure
 
 <!-- snippet: ReadingDirectorySimple -->
+<a id='snippet-readingdirectorysimple'/></a>
 ```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");
 ```
-<sup>[snippet source](/src/Tests/Snippets/Usage.cs#L30-L39)</sup>
+<sup>[snippet source](/src/Tests/Snippets/Usage.cs#L30-L39) / [anchor](#snippet-readingdirectorysimple)</sup>
 <!-- endsnippet -->
 
 
 ## Full Usage
 
 <!-- snippet: markdownProcessingSimple -->
+<a id='snippet-markdownprocessingsimple'/></a>
 ```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;
 }
 ```
-<sup>[snippet source](/src/Tests/Snippets/Usage.cs#L44-L70)</sup>
+<sup>[snippet source](/src/Tests/Snippets/Usage.cs#L44-L70) / [anchor](#snippet-markdownprocessingsimple)</sup>
 <!-- endsnippet -->
 
 

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:
 
 <!-- snippet: sampleConfig.json -->
+<a id='snippet-sampleConfig.json'/></a>
 ```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}"
 }
 ```
-<sup>[snippet source](/src/ConfigReader.Tests/sampleConfig.json#L1-L10)</sup>
+<sup>[snippet source](/src/ConfigReader.Tests/sampleConfig.json#L1-L10) / [anchor](#snippet-sampleConfig.json)</sup>
 <!-- endsnippet -->

readme.md

@@ -98,10 +98,15 @@ snippet: MySnippetName
 
 The resulting markdown will be:
 
+    <!-- snippet: MySnippetName -->
     Some blurb about the below snippet
+    <a id='snippet-MySnippetName'/></a>
     ```
     My Snippet Code
     ```
+    <sup>[snippet source](/relativeUrlToFile#L1-L11) / [anchor](#snippet-MySnippetName)</sup>
+    <!-- endsnippet -->
+
 
 
 ### 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:
 
 <!-- snippet: tocBefore.txt -->
+<a id='snippet-tocBefore.txt'/></a>
 ```txt
 # Title
 
@@ -169,12 +175,13 @@ Text1
 
 Text2
 ```
-<sup>[snippet source](/docs/mdsource/toc/tocBefore.txt#L1-L11)</sup>
+<sup>[snippet source](/docs/mdsource/toc/tocBefore.txt#L1-L11) / [anchor](#snippet-tocBefore.txt)</sup>
 <!-- endsnippet -->
 
 The result will be rendered:
 
 <!-- snippet: tocAfter.txt -->
+<a id='snippet-tocAfter.txt'/></a>
 ```txt
 # Title
 
@@ -193,7 +200,7 @@ Text1
 
 Text2
 ```
-<sup>[snippet source](/docs/mdsource/toc/tocAfter.txt#L1-L16)</sup>
+<sup>[snippet source](/docs/mdsource/toc/tocAfter.txt#L1-L16) / [anchor](#snippet-tocAfter.txt)</sup>
 <!-- endsnippet -->
 
 
@@ -221,13 +228,14 @@ mdsnippets --toc-excludes heading1:heading2
 When a .md file is written, a header is include. The default header is:
 
 <!-- snippet: HeaderWriterTests.DefaultHeader.approved.txt -->
+<a id='snippet-HeaderWriterTests.DefaultHeader.approved.txt'/></a>
 ```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.
 ```
-<sup>[snippet source](/src/Tests/HeaderWriterTests.DefaultHeader.approved.txt#L1-L4)</sup>
+<sup>[snippet source](/src/Tests/HeaderWriterTests.DefaultHeader.approved.txt#L1-L4) / [anchor](#snippet-HeaderWriterTests.DefaultHeader.approved.txt)</sup>
 <!-- endsnippet -->
 
 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.
 
 <!-- snippet: LinkFormat.cs -->
+<a id='snippet-LinkFormat.cs'/></a>
 ```cs
 namespace MarkdownSnippets
 {
@@ -264,10 +273,11 @@ namespace MarkdownSnippets
     }
 }
 ```
-<sup>[snippet source](/src/MarkdownSnippets/Processing/LinkFormat.cs#L1-L8)</sup>
+<sup>[snippet source](/src/MarkdownSnippets/Processing/LinkFormat.cs#L1-L8) / [anchor](#snippet-LinkFormat.cs)</sup>
 <!-- endsnippet -->
 
 <!-- snippet: BuildLink -->
+<a id='snippet-buildlink'/></a>
 ```cs
 if (linkFormat == LinkFormat.GitHub)
 {
@@ -278,7 +288,7 @@ if (linkFormat == LinkFormat.Tfs)
     return $"{path}&line={snippet.StartLine}&lineEnd={snippet.EndLine}";
 }
 ```
-<sup>[snippet source](/src/MarkdownSnippets/Processing/SnippetMarkdownHandling.cs#L50-L59)</sup>
+<sup>[snippet source](/src/MarkdownSnippets/Processing/SnippetMarkdownHandling.cs#L72-L81) / [anchor](#snippet-buildlink)</sup>
 <!-- endsnippet -->
 
 

readme.source.md

@@ -78,10 +78,15 @@ snippet: MySnippetName
 
 The resulting markdown will be:
 
+    <!-- snippet: MySnippetName -->
     Some blurb about the below snippet
+    <a id='snippet-MySnippetName'/></a>
     ```
     My Snippet Code
     ```
+    <sup>[snippet source](/relativeUrlToFile#L1-L11) / [anchor](#snippet-MySnippetName)</sup>
+    <!-- endsnippet -->
+
 
 
 ### Including full files

src/ConfigReader.Tests/ConfigReader.Tests.csproj

@@ -11,12 +11,12 @@
   <ItemGroup>
     <ProjectReference Include="..\ConfigReader\ConfigReader.csproj" />
     <PackageReference Include="ApprovalTests" Version="4.0.0" />
-    <PackageReference Include="ObjectApproval" Version="10.0.0" />
+    <PackageReference Include="ObjectApproval" Version="11.0.0" />
     <PackageReference Include="xunit.runner.visualstudio" Version="2.4.1" />
     <PackageReference Include="Xunit" Version="2.4.1" />
     <PackageReference Include="XunitLogger" Version="2.4.0" />
     <PackageReference Include="Microsoft.NET.Test.Sdk" Version="16.2.0" />
-    <PackageReference Include="ProjectDefaults" Version="1.0.9" PrivateAssets="All" />
+    <PackageReference Include="ProjectDefaults" Version="1.0.10" PrivateAssets="All" />
   </ItemGroup>
 
   <ItemGroup>

src/ConfigReader.Tests/ConfigReaderTests.cs

@@ -1,5 +1,4 @@
 using System.IO;
-using ObjectApproval;
 using Xunit;
 using Xunit.Abstractions;
 

src/ConfigReader/ConfigReader.csproj

@@ -6,7 +6,7 @@
 
   <ItemGroup>
     <ProjectReference Include="..\MarkdownSnippets\MarkdownSnippets.csproj" />
-    <PackageReference Include="ProjectDefaults" Version="1.0.9" PrivateAssets="All" />
+    <PackageReference Include="ProjectDefaults" Version="1.0.10" PrivateAssets="All" />
   </ItemGroup>
 
 </Project>

src/Directory.Build.props

@@ -2,7 +2,7 @@
 <Project>
   <PropertyGroup>
     <NoWarn>CS1591</NoWarn>
-    <Version>16.1.1</Version>
+    <Version>16.2.0</Version>
     <PackageTags>Markdown, Snippets, mdsnippets, documentation, MarkdownSnippets</PackageTags>
     <Description>Extracts snippets from code files and merges them into markdown documents.</Description>
   </PropertyGroup>

src/MarkdownSnippets.MsBuild/MarkdownSnippets.MsBuild.csproj

@@ -17,6 +17,6 @@
   <ItemGroup>
     <PackageReference Include="Microsoft.Build.Tasks.Core" Version="16.0.461" PrivateAssets="All" />
     <ProjectReference Include="..\MarkdownSnippets\MarkdownSnippets.csproj" />
-    <PackageReference Include="ProjectDefaults" Version="1.0.9" PrivateAssets="All" />
+    <PackageReference Include="ProjectDefaults" Version="1.0.10" PrivateAssets="All" />
   </ItemGroup>
 </Project>

src/MarkdownSnippets.Tool/MarkdownSnippets.Tool.csproj

@@ -15,6 +15,6 @@
   <ItemGroup>
     <ProjectReference Include="..\MarkdownSnippets\MarkdownSnippets.csproj" />
     <PackageReference Include="CommandLineParser" Version="2.6.0" />
-    <PackageReference Include="ProjectDefaults" Version="1.0.9" PrivateAssets="All" />
+    <PackageReference Include="ProjectDefaults" Version="1.0.10" PrivateAssets="All" />
   </ItemGroup>
 </Project>

src/MarkdownSnippets/MarkdownSnippets.csproj

@@ -6,6 +6,6 @@
   <ItemGroup>
     <PackageReference Include="ConfigureAwait.Fody" Version="3.1.0" PrivateAssets="All" />
     <PackageReference Include="Fody" Version="5.1.1" PrivateAssets="All" />
-    <PackageReference Include="ProjectDefaults" Version="1.0.9" PrivateAssets="All" />
+    <PackageReference Include="ProjectDefaults" Version="1.0.10" PrivateAssets="All" />
   </ItemGroup>
 </Project>

src/MarkdownSnippets/Processing/SnippetMarkdownHandling.cs

@@ -22,29 +22,51 @@ public SnippetMarkdownHandling(string rootDirectory, LinkFormat linkFormat)
 
         public void AppendGroup(string key, IEnumerable<Snippet> snippets, Action<string> 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<string> appendLine, Snippet snippet)
+        void WriteSnippet(Action<string> 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($"<a id='{anchor}'/></a>");
+            if (snippet.Path == null)
+            {
+                WriteSnippetValueAndLanguage(appendLine, snippet);
+                appendLine($"<sup>[anchor](#{anchor})</sup>");
+            }
+            else
             {
                 var path = snippet.Path.Replace(@"\", "/").Substring(rootDirectory.Length);
-                var link = BuildLink(snippet, path);
-                appendLine($"<sup>[snippet source]({link})</sup>");
+                var sourceLink = BuildLink(snippet, path);
+                WriteSnippetValueAndLanguage(appendLine, snippet);
+                appendLine($"<sup>[snippet source]({sourceLink}) / [anchor](#{anchor})</sup>");
             }
         }
 
+        private static void WriteSnippetValueAndLanguage(Action<string> appendLine, Snippet snippet)
+        {
+            appendLine($"```{snippet.Language}");
+            appendLine(snippet.Value);
+            appendLine("```");
+        }
+
         string BuildLink(Snippet snippet, string path)
         {
             #region BuildLink

src/Tests/Console/CommandRunnerTests.cs

@@ -1,6 +1,5 @@
 using System;
 using System.IO;
-using ObjectApproval;
 using Xunit;
 using Xunit.Abstractions;
 

src/Tests/DirectoryMarkdownProcessor/DirectoryMarkdownProcessorTests.Convention.approved.txt

@@ -1,8 +1,10 @@
 \one.md
 <!-- snippet: snippet1 -->
+<a id='snippet-snippet1'/></a>
 ```.cs
 the code from snippet1
 ```
+<sup>[anchor](#snippet-snippet1)</sup>
 <!-- endsnippet -->
 
 
@@ -11,9 +13,11 @@ snippet: snippet1
 
 \two.md
 <!-- snippet: snippet2 -->
+<a id='snippet-snippet2'/></a>
 ```.cs
 the code from snippet2
 ```
+<sup>[anchor](#snippet-snippet2)</sup>
 <!-- endsnippet -->
 
 

src/Tests/DirectorySnippetExtractor/DirectorySnippetExtractorTests.cs

@@ -3,7 +3,6 @@
 using System.IO;
 using System.Linq;
 using MarkdownSnippets;
-using ObjectApproval;
 using Xunit;
 using Xunit.Abstractions;
 

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

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;
 

src/Tests/SnippetMarkdownHandlingTests.AppendGroup.approved.txt

@@ -1,4 +1,5 @@
-```thelanguage
+<a id='snippet-thekey'/></a>
+```thelanguage
 theValue
 ```
-<sup>[snippet source](thePath#L1-L2)</sup>
+<sup>[snippet source](thePath#L1-L2) / [anchor](#snippet-thekey)</sup>

src/Tests/SnippetVerifier.cs

@@ -2,7 +2,6 @@
 using System.IO;
 using System.Text;
 using MarkdownSnippets;
-using ObjectApproval;
 
 static class SnippetVerifier
 {

src/Tests/TestBase.cs

@@ -1,5 +1,5 @@
-using ObjectApproval;
-using Xunit.Abstractions;
+using Xunit.Abstractions;
+using ObjectApproval;
 
 public class TestBase:
     XunitLoggingBase

src/Tests/Tests.csproj

@@ -7,14 +7,14 @@
     <Folder Include="DirectorySnippetExtractor\VerifyLambdasAreCalled\subpath\" />
     <Folder Include="GitDirs\" />
     <PackageReference Include="ApprovalTests" Version="4.0.0" />
-    <PackageReference Include="ObjectApproval" Version="10.0.0" />
+    <PackageReference Include="ObjectApproval" Version="11.0.0" />
     <PackageReference Include="xunit.runner.visualstudio" Version="2.4.1" />
     <PackageReference Include="Xunit" Version="2.4.1" />
     <PackageReference Include="XunitLogger" Version="2.4.0" />
     <PackageReference Include="Microsoft.NET.Test.Sdk" Version="16.2.0" />
     <ProjectReference Include="..\MarkdownSnippets.Tool\MarkdownSnippets.Tool.csproj" />
     <ProjectReference Include="..\MarkdownSnippets\MarkdownSnippets.csproj" />
-    <PackageReference Include="ProjectDefaults" Version="1.0.9" PrivateAssets="All" />
+    <PackageReference Include="ProjectDefaults" Version="1.0.10" PrivateAssets="All" />
     <Reference Include="Microsoft.CSharp" />
     <None Include="badsnippets\code.txt">
       <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>