From 2836081e34535ac6a88347ff094dca84a643a95a Mon Sep 17 00:00:00 2001 From: Simon Cropp Date: Sun, 11 Aug 2019 11:25:07 +1000 Subject: [PATCH] Add snippet anchor (#76) --- docs/api.md | 9 +++-- docs/config-file.md | 3 +- readme.md | 20 +++++++--- readme.source.md | 5 +++ .../ConfigReader.Tests.csproj | 4 +- src/ConfigReader.Tests/ConfigReaderTests.cs | 1 - src/ConfigReader/ConfigReader.csproj | 2 +- src/Directory.Build.props | 2 +- .../MarkdownSnippets.MsBuild.csproj | 2 +- .../MarkdownSnippets.Tool.csproj | 2 +- src/MarkdownSnippets/MarkdownSnippets.csproj | 2 +- .../Processing/SnippetMarkdownHandling.cs | 40 ++++++++++++++----- src/Tests/Console/CommandRunnerTests.cs | 1 - ...downProcessorTests.Convention.approved.txt | 4 ++ .../DirectorySnippetExtractorTests.cs | 1 - ...actorTests.AppendUrlAsSnippet.approved.txt | 2 +- .../SnippetExtractor/SnippetExtractorTests.cs | 1 - ...downHandlingTests.AppendGroup.approved.txt | 5 ++- src/Tests/SnippetVerifier.cs | 1 - src/Tests/TestBase.cs | 4 +- src/Tests/Tests.csproj | 4 +- 21 files changed, 78 insertions(+), 37 deletions(-) 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